• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Liutauras Vilda
  • Jeanne Boyarsky
  • Devaka Cooray
  • Paul Clapham
Sheriffs:
  • Tim Cooke
  • Knute Snortum
  • Bear Bibeault
Saloon Keepers:
  • Ron McLeod
  • Tim Moores
  • Stephan van Hulst
  • Piet Souris
  • Ganesh Patekar
Bartenders:
  • Frits Walraven
  • Carey Brown
  • Tim Holloway

Reading Java docs help

 
Ranch Hand
Posts: 208
1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
My knowledge of using Java docs is weak and i feel i must really improve this now.

I got help from you guys regarding a keyboard utility class and am going through it line by line to understand it.

the first line is:



Which I understand imports a class? Optional?

I have never used java.util.Optional and dont know what it does, so I googled it and it came up in the docs

but my reading of the docs is poor, or rather my understanding is.

in the docs:

compact1, compact2, compact3 What is this?

java.util - this means it belongs to the java.util class?

Class Optional<T> - again....?

java.lang.Object

java.util.Optional<T>

public final class Optional<T>
what is <T>?

extends Object
A container object which may or may not contain a non-null value. If a value is present, isPresent() will return true and get() will return the value.
Additional methods that depend on the presence or absence of a contained value are provided, such as orElse() (return a default value if value not present) and ifPresent() (execute a block of code if the value is present).

This is a value-based class; use of identity-sensitive operations (including reference equality (==), identity hash code, or synchronization) on instances of Optional may have unpredictable results and should be avoided.


I dont know what any of this information means or how to find what it does or how things fit together, i feel like a mouse in a very big java maze

I just completed a 6 month java course and we didnt touch on anything to do with documentation.

and people like Campbell and Carey and Snort always tell me check documentation etc, but its really difficult when it seems so cryptic.

whats the best plan of action to tackle this?

as always, thanks.
 
Bartender
Posts: 1027
18
Mac OS X IntelliJ IDE Oracle Spring VI Editor Tomcat Server Redhat Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Maybe you should start with the Java Tutorial Docs rather than the actual API documentation.  

what is <T>?

- part of Java's support for generics, which is covered within the collections documentation;
Java Collections

Optional seems to be used to try and deal with the null type that causes so many problems in Java (and also other languages).  

i feel like a mouse in a very big java maze

, yes we all do and the maze seems to be forever growing!  Trick is not to worry as nobody can know everything, but after a while you will notice that technology changes the fundamental concepts don't.  
 
Bartender
Posts: 5906
57
Eclipse IDE Firefox Browser MySQL Database VI Editor Java Windows
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

wayne brandon wrote:My knowledge of using Java docs is weak and i feel i must really improve this now.
I got help from you guys regarding a keyboard utility class and am going through it line by line to understand it.
the first line is:

Which I understand imports a class? Optional?


"java.util" is the package.
"Optional" is the class defined in that package.
In order to make use of the Optional class it is necessary to import it.

compact1, compact2, compact3 What is this?


Don't know (?).

Class Optional<T>


"Optional" is a class that can utilize a specified type. The letter 'T' is the conventional name for a generic type specification. For instance, you can't just have Optional by itself, you need to also specify the type that it will use. So, you could have Optional<Integer>, or Optional<String>, etc. The Optional class was designed as a replacement for methods returning null in some situation. The person designing a method has no control over whether or not the caller actually checks for null. This can lead to bugs. Optional wraps the specified type with methods to determine if a value is present or not, and to get access to the value. The caller is forced to deal with Optional being returned from a method.

java.lang.Object


Object is the base class in Java. ALL classes inherit (extend) Object whether explicitly declared or not.
 
Carey Brown
Bartender
Posts: 5906
57
Eclipse IDE Firefox Browser MySQL Database VI Editor Java Windows
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
As Peter mentioned, tutorials are a good place to start. In your example, I would have googled "java optional tutorial" and start with those search hits which may also include some non-Oracle tutorials.
 
Ranch Hand
Posts: 84
2
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
In my opinion you don't have a problem with reading javadocs, you have a problem with understanding basics of Java and OOP, it's not your fault, I guess this 6 months course was rubbish. I suggest starting from scratch using different course or a book.
 
wayne brandon
Ranch Hand
Posts: 208
1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Adrian Grabowski that was a bit harsh, i do have a fundamental understanding of OOP and java in general and have written many small applications and things. i didnt find the course "rubbish" i learnt a lot. Hey! even one of the members above who has vast knowledge didnt understand something in the docs.  
 
Adrian Grabowski
Ranch Hand
Posts: 84
2
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I didn't mean to sound harsh, maybe "rubbish" isn't the best word here but I would assume that basic Java course would explain difference between package and class and some basics of generics. I assume it was one of the courses that get you from zero to hero in a shortest amount of time possible and they cover a lot of topics so you can write something useful but they don't go deep enough. It's good as it keeps things interesting but the downside is that you might end up with some gaps in your knowledge. Apologies if I have offended you.
 
wayne brandon
Ranch Hand
Posts: 208
1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Not at all Adrian, it was not a personal attack. But I do agree that we could have looked at some documentation. We did look at Classes like Scanner and Random but didnt cover how to search and do things on your own.
I do know what a package is, but couldnt determine what Object does. like I do know that Scanner is a class in the java.util package right? where would you suggest i start?
 
Saloon Keeper
Posts: 10308
217
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

wayne brandon wrote:compact1, compact2, compact3 What is this?


These were API profiles. The standard API is huge, and it's not a good idea to support it completely on every device. Some devices support only compact1, while others support only compact1 and compact2. This line will tell you whether the class is available if your device is running a certain Java API profile. I believe it's only applicable to Java 8 though, because Java 9 introduced modules, which are a different way of splitting up the Java API. In Java 9 documentation and newer, you will see a line saying something like Module java.base instead.

java.util - this means it belongs to the java.util class?


No, it means the Optional class belongs to the java.util package.

Class Optional<T> - again....?


Just the main heading of the web page.

Below the main heading you will find the inheritance tree. It will tell you what classes java.util.Optional derives from. It only has one ancestor: java.lang.Object.

what is <T>?


T is a type parameter. It's like a variable, except it doesn't hold a value, but a type. When you encounter this next to the name of the class, it means the class is generic. Go through the Java tutorials on generics to understand more about it.


A container object which may or may not contain a non-null value. If a value is present, isPresent() will return true and get() will return the value.
Additional methods that depend on the presence or absence of a contained value are provided, such as orElse() (return a default value if value not present) and ifPresent() (execute a block of code if the value is present).


Optional is a wrapper around an object reference. It allows you to call operations on an object reference without fear that the reference is null, because it forces you to write code that handles the case where the reference is null. Starting with Java 8, it's often used as a return type for methods. If a method returns an Optional<String>, that means quite literally that it optionally returns a reference to a string. It may also return nothing, which is represented by the value Optional.empty(). In the olden days, people would do this with null instead, but this lead to lots of bugs because programmers tend to forget to check for null references. The Javadoc tells you that Optional has methods like isPresent() to check whether the value currently refers to an object or not.

This is a value-based class; use of identity-sensitive operations (including reference equality (==), identity hash code, or synchronization) on instances of Optional may have unpredictable results and should be avoided.


"Value-based class" means that the class was written in such a way that an instance of Optional is considered equal to another instance, if their internal state is equal. For instance, Optional.of("Hello World!") is equal to Optional.of("Hello " + "World!"). However, they still are two different object references, so using operators like == where you are supposed to use equals() will lead to bugs.

and people like Campbell and Carey and Snort


I think you mean Knute, and his last name is Snortum.

whats the best plan of action to tackle this?


Practice practice practice. Refer to the documentation a lot, until you get familiar with it. Ask questions if you don't understand.
 
wayne brandon
Ranch Hand
Posts: 208
1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks Stephen for that info, sorry yes I meant to say package not class regarding java.util. thats why Adrian pointed me out earlier.
 
Adrian Grabowski
Ranch Hand
Posts: 84
2
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

wayne brandon wrote: where would you suggest i start?



I'm not sure as everyone's path is different, in my case I'm always wondering if I'm learning useful things of I'm progressing fast enough but I as a rule of thumb: if I look at my code from few months ago and think "what an idiot wrote it this way" then I assume I'm making a progress
 
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!