User’s Guide
Take a look at class String in the package java.lang. The navigational anchors are at the top. This is followed by the fully qualified class name and a representation of its position in the class hierarchy.
The next entries are links to the superclass and the interfaces, if any. This is followed by a description of the class, taken from the class comment. Notice how the programmer has embedded some code samples using html tags.
The author also chose to include a See Also entry to another class. Following the class-level entries for See Also, Version, and Author, the index begins.
The Index
Each class/interface begins with an index of its variables, constructors and methods, sorted alphabetically. The entry consists of the declaration and short description. The description is the first sentence of the doc comment for that item. The index entries are linked to their corresponding entries in the application programming inteface which immediately follows.
The Detailed API
The index is followed by the complete API for each entry. Within the three categories: Variables, Constructors, and Methods, the entries are presented in the order they appear in the source. This is done to preserve the logical groupings established by the programmer.
Where Are All the Links in the API?
- At the top of each class/interface there are navigational anchors to the other levels and to Previous and Next (class or interface).
- There are links in the class type of every method and variable definition.
- At the top of each class/interface there is a drawing of the tree structure down to the current class/interface, in which each superclass is a link.
- Every method contains a list of exceptions that it may throw. These are linked to the appropriate class.
- The superclass and interface references at the beginning of the class are links.
- Every See Also is a link.
- When a method overrides a method in the superclass, the API has the entry «Overrides: foo in class bar.» Both foo (the method name) and bar (the class name) are links.
Oracle is reviewing the Sun product roadmap and will provide guidance to customers in accordance with Oracle’s standard product communication policies. Any resulting features and timing of release of such features as determined by Oracle’s review of roadmaps, are at the sole discretion of Oracle. All product roadmap information, whether communicated by Sun Microsystems or by Oracle, does not represent a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. It is intended for information purposes only, and may not be incorporated into any contract.
—> © 2010, Oracle Corporation and/or its affiliates
Unless otherwise licensed, code in all technical manuals herein (including articles, FAQs, samples) is provided under this License.
Sun Developer RSS Feeds
Interfaces
There are a number of situations in software engineering when it is important for disparate groups of programmers to agree to a «contract» that spells out how their software interacts. Each group should be able to write their code without any knowledge of how the other group’s code is written. Generally speaking, interfaces are such contracts.
For example, imagine a futuristic society where computer-controlled robotic cars transport passengers through city streets without a human operator. Automobile manufacturers write software (Java, of course) that operates the automobilestop, start, accelerate, turn left, and so forth. Another industrial group, electronic guidance instrument manufacturers, make computer systems that receive GPS (Global Positioning System) position data and wireless transmission of traffic conditions and use that information to drive the car.
The auto manufacturers must publish an industry-standard interface that spells out in detail what methods can be invoked to make the car move (any car, from any manufacturer). The guidance manufacturers can then write software that invokes the methods described in the interface to command the car. Neither industrial group needs to know how the other group’s software is implemented. In fact, each group considers its software highly proprietary and reserves the right to modify it at any time, as long as it continues to adhere to the published interface.
Interfaces in Java
In the Java programming language, an interface is a reference type, similar to a class, that can contain only constants, method signatures, default methods, static methods, and nested types. Method bodies exist only for default methods and static methods. Interfaces cannot be instantiatedthey can only be implemented by classes or extended by other interfaces. Extension is discussed later in this lesson.
Defining an interface is similar to creating a new class:
public interface OperateCar < // constant declarations, if any // method signatures // An enum with values RIGHT, LEFT int turn(Direction direction, double radius, double startSpeed, double endSpeed); int changeLanes(Direction direction, double startSpeed, double endSpeed); int signalTurn(Direction direction, boolean signalOn); int getRadarFront(double distanceToCar, double speedOfCar); int getRadarRear(double distanceToCar, double speedOfCar); . // more method signatures >
Note that the method signatures have no braces and are terminated with a semicolon.
To use an interface, you write a class that implements the interface. When an instantiable class implements an interface, it provides a method body for each of the methods declared in the interface. For example,
public class OperateBMW760i implements OperateCar < // the OperateCar method signatures, with implementation -- // for example: public int signalTurn(Direction direction, boolean signalOn) < // code to turn BMW's LEFT turn indicator lights on // code to turn BMW's LEFT turn indicator lights off // code to turn BMW's RIGHT turn indicator lights on // code to turn BMW's RIGHT turn indicator lights off >// other members, as needed -- for example, helper classes not // visible to clients of the interface >
In the robotic car example above, it is the automobile manufacturers who will implement the interface. Chevrolet’s implementation will be substantially different from that of Toyota, of course, but both manufacturers will adhere to the same interface. The guidance manufacturers, who are the clients of the interface, will build systems that use GPS data on a car’s location, digital street maps, and traffic data to drive the car. In so doing, the guidance systems will invoke the interface methods: turn, change lanes, brake, accelerate, and so forth.
Interfaces as APIs
The robotic car example shows an interface being used as an industry standard Application Programming Interface (API). APIs are also common in commercial software products. Typically, a company sells a software package that contains complex methods that another company wants to use in its own software product. An example would be a package of digital image processing methods that are sold to companies making end-user graphics programs. The image processing company writes its classes to implement an interface, which it makes public to its customers. The graphics company then invokes the image processing methods using the signatures and return types defined in the interface. While the image processing company’s API is made public (to its customers), its implementation of the API is kept as a closely guarded secretin fact, it may revise the implementation at a later date as long as it continues to implement the original interface that its customers have relied on.