Start of Tutorial > Start of Trail > Start of Lesson |
Search
Feedback Form |
In this short but important lesson, you'll learn a few simple guidelines that will allow your API to interoperate seamlessly with all other fine APIs that follow these guidelines. In essence, these rules define what it takes to be a good citizen in the brave new world of collections.
If your API contains a method that requires a collection on input, it is of paramount importance that you declare the relevant parameter type to be one of the collection interface types. Never use an implementation type, as this defeats the purpose of an interface-based collection framework, which is to allow collections to be manipulated without regard to implementation details.Further, you should always use the least specific type that makes sense. For example, don't require a
List
or aSet
if aCollection
would do. It's not that you should never require aList
or aSet
on input; it is correct to do so if a method depends on some property of one of these interfaces. For example, many of the algorithms provided by the Java platform require aList
on input because they depend on the fact that lists are ordered. As a general rule, however, the best types to use on input are the most general:Collection
andMap
.
Caution: Never, never, define your own ad hoc collection class and require objects of this class on input. By doing this, you'd lose all the benefits provided by the collection framework.
You can afford to be much more flexible with return values than input parameters. It's fine to return an object of any type that implements or extends one of the collection interfaces. This can be one of the interfaces themselves, or some special-purpose type that extends (or implements) one of these interfaces.For example, one could imagine some image-processing package that returned objects of a new class that implements
List
, calledImageList
. In addition to theList
operations,ImageList
could support any application-specific operations that seemed desirable. For example, it might provide anindexImage
operation that returned an image containing thumbnail images of each graphic in theImageList
. It's critical to note that even if the API furnishesImageList
objects on output, it should accept arbitraryCollection
(or perhapsList
) objects on input.In one sense, return values should have the opposite behavior of input parameters: it's best to return the most specific applicable collection interface, rather than the most general. For example, if you're quite sure that a
Map
returned by some method will always be aSortedMap
, you should give the method the return type ofSortedMap
rather thanMap
.SortedMap
objects are both more time-consuming to build than ordinaryMap
objects and more powerful. Given that your module has already invested the time to build aSortedMap
, it makes good sense to give the user access to its increased power. Furthermore, the user will be able to pass the returned object to methods that demand aSortedMap
, as well as those that accept anyMap
.Again, never, never, define your own ad hoc collection class and furnish an object of this class as a return value. By doing this, you'd lose all of the benefits provided by the collection framework. (Sound familiar?)
There are currently plenty of APIs out there that define their own ad hoc collection types. While this is unfortunate, it's a fact of life, given that there was no collection framework in the first two major releases of the Java platform. Suppose that you own one of these APIs. Here's what you can do about it.If possible, retrofit your legacy collection type to implement one of the standard collection interfaces. Then all of the collections that you return will interoperate smoothly with other collection-based APIs. If this is impossible (for example, because one or more of the preexisting type signatures conflict with the standard collection interfaces), define an adapter class that wraps one of your legacy collections objects, allowing it to function as a standard collection. (The adapter class is an example of a custom implementation.)
Retrofit your API with new calls that follow the input guidelines to accept objects of a standard collection interface, if possible. Such calls can coexist with the calls that take the legacy collection type. If this is impossible, provide a constructor or static factory for your legacy type that takes an object of one of the standard interfaces and returns a legacy collection containing the same elements (or mappings). Either of these approaches will allow users to pass arbitrary collections into your API.
Start of Tutorial > Start of Trail > Start of Lesson |
Search
Feedback Form |