Documentation Help

 

Contents:

 

Terminology

Terminology used in this Help document:

 

 

 

 

Overview of Documentation Organization

Image This documentation is organized into three frames in the browser window:

 

 

 

 

Documentation pages contain the following elements:

 

 

 

 

 

 

Main Navigation Bar

Image Main Navigation Bar is located at the top of every documentation page and provides links to global documentation pages and to package documentation pages.

 

When current documentation page is a global page not related to a particular package, only global links are present in the Main Navigation Bar. Examples of global documentation pages are the system overview page, hierarchy of all documented classes and interfaces, alphabetical index of names, and other.

 

When current documentation page is a package or a package member document (Class document, Interface document, etc.), the package links are present and allow access to the documentation of current package.

 

Global links may contain the items described below. Some items may not be present in your particular documentation. The exact set of links included into the Main Navigation Bar is determined by the documentation creator. If any of the all possible global links listed below are not present, it means that your documentation does not provide the corresponding documentation pages.

 

 

 

 

 

 

Package Links are present in the Main Navigation Bar when the current documentation page shown in the right frame is a package document or a document for a package member, i.e. Class, Interface, Enum or Annotation Type. Package links may include the items desribed below. An item may not be present if this documentation does not provide the corresponding pages. The exact set of items present in the package links section is determined by the documentation creator.

 

 

 

 

 

Switching between Frames and No-Frames

Image Frames Mode Switch, if present, is located in the Main Navigation Bar between the links and the documentation name. Its appearance depends on the current mode and if your browser supports and enables JavaScript. It is recommended to enable JavaScript in order to view this documentation.

 

Frames Mode Switch allows you to change the browser window layout between the 3-frames layout (default layout) and the single frame layout when the documentation pages shown in the right frame occupy the entire browser window. In No-Frames layout the left-side frames are not present and you do not have immediate access to the list of packages and classes. You can access the System Overview page containing a list of all packages using the Overview link in the Main Navigation Bar, as well as you can access the list of members in the current package using the Package link.

 

When JavaScript is enabled, the Frames Mode Switch is shown as a small icon in the Main Navigation Bar. The icon changes depending on the current mode, as shown in the picture on the right. Click on the icon to toggle between the Frames Mode and No-Frames Mode.

 

When JavaScript is not supported by the browser or is disabled, the Frames Mode Switch is shown as two small links "F" and "NF" regardless of current mode. Click on "F" to switch to Frames Mode, click on "NF" to switch to No-Frames Mode.

 

The documentation creator may disable the Frames Mode Switch in which case it is not present in the Main Navigation Bar.

 

 

Types of Documentation Pages

The presence of a particular type of the documentation page in this documentation, except the pages noted to be always present, is determined by the documentation creator. Some of the pages described below may not be present in this documentation.

 

The documentation includes the following page types:

 

 

 

 

 

 

 

 

 

 

 

 

Class Document Page

Image This section describes the structure and sections of a page documenting a Class, Interface, Enum or an Annotation Type. Note that Exceptions and Errors are ordinary Classes.

 

The Class Document Page contains the following sections as shown in the picture on the right:

 

 

 

 

All sections in the Class Document Page are optional, based on both their applicability and their existence for a particular class. Some sections may be missing if they are not applicable or are not present for a particular class. For example, the SuperClass path is not applicable to interfaces and is not present in the documentation of interfaces. The Constructors Summary table shown in the picture may be absent if a Class has no documented constructors, etc.

 

 

Class Navigation Bar

Class Navigation Bar is located at the top of the Class Document Page and provides links to sections inside the page and to other pages. All links described below are present only if the corresponding section inside the Class Document Page or another linked page exist. In rare cases the Class Navigation Bar may be absent.

 

Class Navigation Bar contains three sections of links:

 

Image "Summary" section of the Class Navigation Bar contains links to sections inside the same page, it may contain the following links:

 

 

Notice that Summary section never contains all links listed above. It contains only links applicable to the documented package member and if the corresponding section of the page exists. For example, "Values" link is present only if the documented package member is an Enum. "Fields" link may be present only if the documented member is an ordinary class or an interface, and if it contains documented fields. The same description applies to the links described below.

 

"Details" section may contain the following links:

 

 

"Class" section may contain the following links:

 

 

The "Prev" and "Next" links are the only links that link to documentation pages of other package members. Both of these links are present, as described above, only when corresponding previous or next package member exists. The "Prev" link is absent only if this class is the first member in its package (in the order of members shown in the left-bottom frame). The "Next" link is absent only if this class is the last member in its package. Both "Prev" and "Next" links may be absent only when the documented class is the only member of its package.

 

 

Class Information Table

Image Class Information Table is located below the class name and optional superclass path (shown for ordinary Classes and Enums) and presents important information about the documented Class, Interface, Enum or Annotation Type.

 

Class Information Table may contain one or more information rows. With the exception of the first row "Declaration:", all other rows are present only if they are applicable to the type of the documented package member and if the row has the content to be shown. For example, the row "Implemented by:" is applicable only to Interfaces and is not applicable to any other package members. It may, however, be absent for a particular Interface if it is not implemented by any documented Class.

 

The table below describes all rows which may be present in the Class Information Table. Row title is shown on the left, the comments on the right describe the information present by the row. The names of other documented Classes and Interfaces shown in this table are present by links (if available) to their documentation page.

 

 

Declaration: Complete formal declaration of a Class, Interfaces, Enum or Annotation Type. This includes annotations and, when applicable, extended class and the list of directly implemented or extended interfaces.
This row is the only always present row in the information table.
Enclosing Class: Name of the enclosing class or interface if this is a nested member.
This row is absent if this class, interface or enum is not nested.
Type Parameters: Description of type parameters.
This row is present only for generic classes and interfaces that have one or more type parameters and if their type parameters are documented. If type parameters are present but not documented this row is absent. The type parameters are always shown in the "Declaration:" row.
All Superinterfaces: List of all interfaces extended by this interface, including interfaces extended directly and interfaces inherited from superinterfaces. Interfaces extended directly are shown in bold font. Inherited interfaces are shown using regular font.
This row may be present only for interfaces and is absent if the interface does not extend and does not inherit any other interfaces.
All Subinterfaces: List of all interfaces extending this interface. Names of interfaces extending this interface directly are shown in bold font. Names of interfaces inheriting this interface from their superinterfaces are shown using regular font.
This row may be present only for interfaces and is absent if this interface has no subinterfaces, i.e. no other interface extends this interface.
Implemented by: Lists all ordinary classes and enums implementing this interface. Names of classes directly implementing this interface are shown in bold font. Names of classes that inherit this interface from their superclasses are shown using regular font.
This row may be present only for interfaces and is absent if this interface is not implemented by any class in this documentation.
All Interfaces: List of all interfaces implemented by this ordinary class or enum, including interfaces this class implements directly and interfaces inherited from superclasses. Interfaces implemented directly by this class are shown in bold font. Inherited interfaces are shown using regular font.
This row may be present only for ordinary classes and enums and is absent if this class does not implement and does not inherit any interfaces.
Direct Subclasses: Lists all direct subclasses of this ordinary class.
This row may be present only for ordinary classes and is absent if this class has no direct subclasses in this documentation. If this row is present, all names are shown using regular font because it is clear from the row title that all listed classes extend this class directly.

 

System Overview Page

System Overview Page is present in every documentation. It is the page shown in the right frame of the browser window when the documentation is initially opened.

 

This page contains the list of all packages present in the documentation. If the documentation contains any top-level classes not placed into any named package, they are present as members of a package named "root package".

 

The list of all packages may be shown in alphabetical order in a single table or grouped into several tables. This is determined by the documentation creator. The name of each package is a link to the Package Overview Page.

 

Optionally the System Overview page may contain text describing the documented system.

 

Package Overview Page

Package Overview Page is present for every documented package and provides the list of all interfaces, classes, enums, exceptions, errors and annotation types in that package.

 

Package members are shown grouped by type in several tables in the following order:

 

 

The name of each Interface, Class, etc. is a link to the Class Document Page of that member.

 

Optionally the Package Overview page may contain text describing the package.

 

Hierarchy Pages

Image Hierarchy Pages present the hierarchy (also called inheritance tree) of classes, interfaces, enums and annotation types in one package or a single overall hierarchy of all classes, interfaces, enums and annotation types present in this documentation.

 

Hierarchy Pages are optional and may be absent. Their presence in the documentation is determined by the documentation creator.

 

When present, Hierarchy Pages are accessed by opening the "Tree" links in the Main Navigation Bar as shown in the picture. The global Hierarchy Page containing the hierarchy of all documented classes is accessed via the global "Tree" link located in the left part of the Main Navigation Bar. The Hierarchy Page for current package is accessed via the "Tree" link located in the Package Links section of the Main Navigation Bar.

 

The Hierarchy Page may contain one or more of othe following hierarchies:

 

 

The hierarchies are shown using the commonly used visual presentation of trees. Notice that hierarchies of ordinary Classes, Enums and Annotation Types are mathematical trees because each node has one and only one parent with the exception of root nodes that have no parent (such as java.lang.Object). Hierarchies of Interfaces, while visually present as a tree, are not mathematical trees because one node (i.e. interface) may have more than one parent (i.e. more than one superinterfaces). Consequently, in the hierarchy of interfaces the same interface may appear more than once in the tree if it has more than one documented superinterfaces.

 

In visual presentation of hierarchy trees the documented members are marked with the "+" sign in front of them. In global hierarchy of all classes, the nodes representing external classes and interfaces are shown without the "+" sign and using slightly brighter font color. In hierarchies for a selected package the same visual presentation applied to both external classes and interfaces as well as classes and interfaces from other documented packages.

 

 

Alphabetical Index Pages

Image Alphabetical Index Pages present the alphabetically sorted list of all documented names, including the names of packages, package members (classes, interfaces, etc.), enum values, annotation type elements, fields, constructors and methods.

 

Alphabetical Index Pages are optional and may be absent. Their presence in the documentation is determined by the documentation creator.

 

When present, Alphabetical Index Pages are accessed by opening the "Index" link in the Main Navigation Bar.

 

Depending on the style chosen by the documentation creator, all names may be present in a single Alphabetical Index Page or in the collection of pages where each page presents all names beginning with the same letter.

 

The letter links at the top of the Alphabetical Index Page may link to sections inside the single Alphabetical Index Page or link to other pages if the index is present by one page for each index letter. The set of letter links includes only letters that have at least one indexed name beginning with that letter. As shown in the picture some letters may be absent if none of the indexed names begins with that letter.

 

The list of index names is present as a name on the left followed by brief description of the name type and the owner of the name. The name is present via a link to the detailed documentation of that name in the corresponding documentation page. The owner of the name is present via a link to the documentation of the owner.

 

 

History Pages

Image History Pages present the summary and detailed information about deprecated API and the new API present in the documentation.

 

 

 

History Pages are optional and may be absent. Their presence in the documentation is determined by the documentation creator.

 

When present, History Pages are accessed by opening the "History" link in the Main Navigation Bar.

 

The main History Page, shown in the picture, contains the list of links to the Deprecated API Page and to the New API Pages by version name. Deprecated API, if present, always shown first and links to the single Deprecated API Page. New API, if any present, shown as a set of rows with links to the corresponding New API Page for that version (the version name is the value used in @since tags).

 

The Deprecated API Page and each present New API Page contain detailed list of packages, classes and class members that are, respectively, deprecated or were introduced in the corresponding version.

 

The statistics for each row in the table present in the main History Page provides the total number of packages, package members and class members (i.e. fields, constructors and methods) listed in the detailed documentation page for that version. This is provided for informational purposes. The counts of affected elements include only elements directly marked as deprecated or with the @since tag. For example, if some class is marked with the @since tag, it is included into the count of affected classes, however, its fields, constructors and methods are not included into the count of affected class members.

 

 

Package and Class Use Pages

Use Pages present the documented use of a package by other packages and of a class by other classes. Documented use is the use of classes and interfaces by documented API as desribed below in this section, it does not account for or reflect the use of classes and interfaces by the implementation of other classes.

 

Use Pages are optional and may be absent. Their presence in the documentation is determined by the documentation creator.

 

When present, Package Use Page is accessed by opening the "Use" link in the Package Links section of the Main Navigation Bar. Class Use Page is accessed by opening the "Use" link present in the "Class" section of the Class Navigation Bar.

 

Package Use Page provides detailed information about what other packages use members of the current package and what other packages are used by members of the current package. This is useful to investigate the mutual use of package members by members of other packages. The use of package by other packages is based on the class-level use as described below and provides the overall view of what members of different packages use each other. Such information is difficult to obtain by investigating each particular class of the package.

 

Class Use Page provides detailed information about what other classes, including classes in the same package, use that class. The information is present as a collection of tables where each table describes one type of use. The possible types of use are listed below.

 

Consider A and B are members of same or different packages.

 

Informally, B uses A if A is present anywhere in the formal documentation of B, i.e. in the Superclass Path, Class Information Table, or in the declaration of any fields, constructors or methods of B (use of A in plain-text description of B or in "See Also" lists does not constitute the use).

 

Formally, the use types and, respectively, the types of tables that may be present in the Class Use Page for class, interface or enum A are:

 

 

If A is an Annotation Type then use pages also include the list of classes, fields, constructors and methods that use A. Notice that only documented use of Annotation Types is present in the Use Pages. Annotation Types not exposed in the documentation pages are not shown by the Use Pages.

 

Notice that the types of use described above collect uses of A by all other documented classes and interfaces including classes and interfaces in the same package and in other packages. The Package Use Page provides the summary and details of cross-use of packages based on the same information excluding the use of classes and interfaces by members of the same package.

 

Constant Fields Values Pages

Constant Fields Values Page documents the actual values of the constant fields declared by classes and interfaces. Constant field is a field of primitive type or of type java.lang.String declared as static and final. Static and final fields of types other than a primitive type or java.lang.String are not constant fields.

 

Constant Fields Values Pages document classes and interfaces that define one or more constant fields. These pages can be accessed using the "Constants" link in the Class Navigation Bar or the "Constants" link present in the "See also:" list in the documentation of the constant fields.

 

If a class or an interface does not define constant fields, the "Constants" link is not present in the Class Navigation Bar.

 

Class Serialization Pages

Class Serialization Pages document serializable fields and explicitly coded serialization methods of serializable classes.

 

One Serialization Page documents all serializable classes in one package. If none of the package classes are serializable, the Serialization Page for that package is not present.

 

When present, Serialization Page may be accessed using the "Serialization" link found in the Package Overview Page, or using the "Serial" link in the Class Navigation Bar of any serializable class in that package. If you need to investigate which classes in a particular package are serializable, use the Package Overview Page. The link in the Class Navigation Bar is convenient when you need to learn about serialization of a particular class. Note that if the "Serial" link is not present in Class Navigation Bar in the documentation of a particular class, it means that that class is not serializable.

 

Note that the serialization information present for each class includes all serializable fields. Serialization methods are documented if they are explicitly coded by the class. If serialization methods are not documented it designates that the class uses default serialization.

 

 

© 2005 - 2010 ArtfulBits. All rights reserved.