Advertisement

Revision History

• 0.6 - Mon, Jan 29, 2001, Made so many changes I can't list them here. I did a major rework of the API after the design review I held with Berco Beute and Jakob Eg Larsen in Groningen, Holland in early December. I then made changes to the API as I wrote the Montage browser. Version 0.6 of this specification describes the API at the point where I completed the browser (well, complete as far as serving as a nice demo) and released the browser, the Place API, and the BasicPlace service under SCSL. In addition, in this version I've included details about the Place API that I generated with "speclet," a doclet I wrote to transform JavaDoc documentation into a form suitable for HTML specifications.
• 0.5 - Fri, Oct 13, 2000, Friday the 13th! Removed the String and Throwable from the activationFailed(). Changed ServicePresenter from one static presentService() method that presents the service, to a static factory method that produces a singleton that contains the presentService() method.
• 0.4 - Wed, Oct 11, 2000, Changed name of URLLink to URLFactoryLink, and dropped all constructors from it except the constructor that takes a String URL. Added ServiceURLLink. Added DynamicLinkMap, LinkMapListener, and LinkMapEvent to support the idea of a place whose contents can change while the client is using it. Added more text to description of ServicePresenter.
• 0.3 - Mon, Oct 9, 2000, Did a rather extensive overhaul of the introduction. Link has only one method now, activate(). Progress events are defined to indicate major, not minor, percentages. Described changes to URLFactoryLink, including a description of URLFactory. Changed the proposal for a fourth component of the jini: URL to be the service ID rather than a URL name. Dropped the service context in favor of the ServicePresenter. Main change in this iteration is that Link represents a link to a Jini service item, not a "resource." All resources will be wrapped in Jini service objects, yielding a more Jini-like view of the network: Everything on the network is a service. Every service is represented by an object.
• 0.2 - Tue, Oct 3, 2000, Added text to end of section 4.2., "The ResourceInfo Interface." Mentioned possibility of application/x-service and .service in section 9.1, "HTTP: URLs." Also, fixed a typo.
• 0.1 - Fri, Sept 29, 2000, First version.

1. Introduction

A new computer is on the horizon, a meta-computer made of up every computer connected to every other computer. As embedded devices with high bandwidth network connections become increasingly common, this new meta-computer may gradually supplant the desktop PC as the primary computer people use. The coming change in the hardware status quo provides an opportunity to rethink the basic user-interface metaphors by which people use software. The Jini Place API proposes a simple "space metaphor" by which users could relate to and use the services offered by the emerging meta-computer.

Two fundamental metaphors currently dominate most people's experience of software: the desktop metaphor and the web metaphor. The abstraction that plays the starring role in both of these metaphors is the file.

The personality of a desktop computer is its hard disk, and the desktop metaphor primarily helps users manage files on disks. Users are told that some of those files are applications, the rest are documents. All files are represented by icons. If you double click on an application's icon, the application launches. If you double click on a document icon, an application launches and immediately opens the clicked-upon document.

Each document on the desktop is associated with an application. The application, which is the behavior that knows how to use the document's data, can be thought of as the document's type. The type of a document is usually indicated in some manner external to the document file contents. On Windows, for example, the document type is indicated by the three-character extension of the filename. The filename (and its extension) is known to the file system, but is not generally an intrinsic part of the file itself.

The World Wide Web popularized hypertext, a user-interface metaphor distinctly different from the desktop. Yet on the web, the fundamental unit is still the file. Rather than helping users manage files on nearby disks, however, the web helps people use files delivered by servers on in internet. Most files, but not all, show up as HTML web pages. As on the desktop, each file on the web has a type, which is external to the contents of the file itself. When an HTTP server sends a file, it includes a MIME type header that indicates the type of the file. The browser uses the file type to decide how to present the file to the user.

The browser understands certain MIME types, such as text/html. For such types, the browser itself is the behavior that knows how to use the file's data. If the browser receives a file with a MIME type it doesn't understand, it looks around for a plug-in that understands the type. If it finds a suitable plug-in, it passes the file to the plug-in, and the plug-in decides what to do. In this case, the plug-in is the behavior that understands how to use the file. In either case, the software that represents the behavior for a particular file type must already reside on the client side, either in the browser itself or as a plug-in.

1.1. Jini Service Objects and Service UIs

In contrast to the desktop and web metaphors, where the fundamental abstraction is the file, the fundamental abstraction in the proposed space metaphor is the object. In Jini, network-delivered services are represented by network-mobile objects. Each object has a class, which represents its type. In contrast to files, whose types are generally extrinsic (not part of the file contents), the types of objects are intrinsic. Although most objects are bundles of both data (the values of their instance variables) and behavior (the code of their instance methods), the fundamental character of an object is its behavior. The type of an object determines its interface, which is usually composed of a set of method signatures and their semantic meanings. Objects usually keep their instance variables private (not exposed in the interface) and use those instance variables to help them decide how to behave when their instance methods are invoked.

To present the behavior of a Jini service object to a human user, a user interface (UI) object can be inserted between the user and the service object. If the client has prior knowledge of the object's type, the UI object can be provided by the client. Alternatively, the UI object can be delivered across the network with the service. Such network-delivered UIs are called service UIs, because they are provided by the service. Here's a diagram from the Jini Service UI specification, which defines a standard way to associate UIs with Jini services. This diagram shows a user using a Jini service via a service UI:

Figure 1. A user interacts with a service via a UI object.

1.2. Objects in Places

Although the service UI standard shows how users can interact with any individual service, it doesn't address how users will interact with the set all the services offered by the emerging meta-computer. The purpose of the Jini Place API is to address this second question: to provide users with a metaphor by which they interact with the meta-computer as a whole, to give struture to a new service-oriented user medium.

In the metaphor established by the Place API, all services are represented by objects. Objects are organized into places. To do something on the meta-computer, users go to a place and use an object. This "objects in places" metaphor encourages users to think of the meta-computer as a space.

Most users of the World Wide Web already tend to think in spatial terms. You might hear someone say, "Jini.org is the main Jini web site." Or, "Jini.org is now easier to navigate." Or, "If you want to start a Jini project, go to Jini.org." The italicized words -- site, navigate, go to -- demonstrate the tendency for users to form their own ad hoc space metaphor when thinking about the World Wide Web. The Place API formalizes this space metaphor.

1.3. A Graph of Objects

Place is a Jini service interface that will enable service objects, in addition to whatever other services they provide via their interface, to offer a "collection of links" service. Objects and places, the two basic concepts of user interaction in the service-oriented medium, are therefore both implemented as network-mobile Jini service objects. To be a conceptual place, a Jini service need only implement the Place interface.

In the sense that they offer a "collection of links" service, Place services are similar to web pages. Two main characteristics distinguish a web page from a traditional page, such as a page from a book or magazine. First, a web page is delivered across a network. Second, a web page contains links to other resources on the network, primarily other web pages. Both web pages and traditional pages offer information services, but a web page also offers a "collection of links" service in addition to its information service.

The following diagram depicts the organization of the current World Wide Web. Each rectangle is a web page, which offers both an information service and a collection of links service. The links are depicted as arrows drawn from one web page to another.

Figure 2. The web is a graph of files.

Like web pages, Jini service objects offer network-delivered services. Whereas an individual web page offers primarily an information service, a collection of links service, and perhaps a form service, a Jini service object is more generic. A Jini service object offers the types of service inherent in the object's class. The services themselves are available via the object's interface. Any type of service for which an interface can be defined, therefore, could be delivered across the network as a Jini service object.

The Place interface enables service objects, in addition to whatever other services they provide via their interface, to offer a "collection of links" service. The aim of Place is to enable the set of all services to be organized into a graph, as depicted in the following diagram. In this diagram, the circles are Jini service objects, arrows show links from one object to another.

Figure 3. The space is a graph of objects.

The space metaphor says that everything is a conceptual "object." Conceptual objects are implemented as network-mobile service objects, accessed by users via network-mobile service UIs. Every object has an intrinsic class, which defines the types of services offered by the object. Users and service providers organize objects by placing links to those objects in places. The existence of places on the network continues the "everything is an object" metaphor, because a place is just another type of object -- an object used to organize user relationships to other objects. As objects link to other objects, the graph organization shown in Figure 3 emerges.

1.4. A Seamless User Experience

One of the motivations of the Place API is to give users a more seamless experience than is possible with the web. Because the web is file-based, users must already have installed behavior that understands the type of a network-mobile file. Because objects are behavior, network-mobile objects can provide users with a more seamless experience of interacting network-delivered services. Users needn't worry about installing plug-ins. They can just use the objects.

Given that the World Wide Web is rather popular, however, the Place API includes a way to wrap files in objects. Instead of plug-ins, files can be viewed with network-mobile service UIs. The space metaphor, therefore, subsumes the web metaphor. As shown in Figure 4, in the space metaphor web pages become a special kind of document object.

Figure 4. The space subsumes the web.

1.5. Overview of the Place API

The Place API contains two packages:

• com.artima.place - the main package
• com.artima.place.info - a subpackage concerned with distributed localization

Perhaps the most fundamental interface in the Place API is com.artima.place.Link, which represents a link to some Jini service on the network. Interface Link contains one method, activate. Invoking activate on a Link is called activating the Link. When you activate a Link, you request that the Link retrieve a service for you.

A com.artima.place.Place is a collection of Links. In the API, Place is an interface that contains one method declaration, getLinkMap, which returns a com.artima.place.LinkMap. A LinkMap maps Object keys to com.artima.place.LinkItem values. A LinkItem simply holds two values, a Link and an com.artima.place.info.InfoBundle. An InfoBundle is a bundle of localizable information about the linked-to service, such as name, description, and icons, etc..

(Note: If we can convince the Jini community, we'd like to ultimately place Place in the net.jini.place package.)

2. The Service Presenter

Because the Place API is aimed at enabling users to access network-delivered services, Place API will in general be used in the context of a user agent at the client device. In this specification, the user agent will simply be called, "the browser." This specification describes a way for users to relate to the entire space of network delivered services without saying anything about how any particular browser should look or behave. In the Place API, the browser is represented by the ServicePresenter interface. You can think of the ServicePresenter as a proxy for the browser.

Class ServicePresenter contains a presentService method that allows Place or other services, or service UIs, to request that the browser present a service to the user.

public abstract void presentService(Link link);

The main functionality of the service presenter is activating links on behalf of network-delivered services. By delegating link activation to the service presenter, network-delivered services can let the browser worry about providing users with a seamless experience of the space of services. In addition, the browser can wrap activations of trusted Link classes in doPrivileged invocations to enable those trusted Links to open socket connections to any network location. Code (including untrusted code) that invokes presentService on the service presenter won't get a reference to the resulting service item, but the user will be able to interact with the service via a service UI. If untrusted code invokes activate directly on a Link, the untrusted code may get a security exception.

Because the passed Link is activated by the browser, the browser can give the user feedback about the activation progress in a uniform way. The browser can, for example, show an animation, status messages, progress bar, etc., during the activation of the Link. The browser can provide this feedback in the same manner for every link activation, yielding a more uniform experience for the user.

Here are the public portions of ServicePresenter:

package com.artima.place;

public abstract class ServicePresenter {

    public static final int DEFAULT_ACTIVATION_TIMEOUT = 30000;
    public static final int DEFAULT_SINGLE_REQUEST_TIMEOUT = 20000;

    public ServicePresenter() {...}

    public static void setLatencyTimeouts(int singleRequestTimeout,
        int activationTimeout) {...}
    public static int getActivationTimeout() {...}
    public static int getSingleRequestTimeout() {...}
    public abstract void presentService(Link link);
    public static ServicePresenter getDefault() {...}
}

The presentService method is not static, because browsers may want to treat activations differently depending on who requested the activation. For example, a browser may allow multiple windows, each of which can host one or more services. When a service requests the browser to activate a link, the browser may want to know which window hosts the service making the activation request. By making presentService an instance, rather than static, method, the browser can pass a different ServicePresenter instance to each service when it arrives. Each service can then delegate its activation requests to that particular ServicePresenter object.

To make it possible for browsers to pass a ServicePresenter to a service, and then enable service UIs to retrieve that ServicePresenter, the Place API includes a Jini service interface called Presentable. The Presentable. interface includes a setServicePresenter method, that enables the browser to pass a ServicePresenter to the service, and a getServicePresenter, that enables service UIs to request the ServicePresenter from the service. Here are the public portions of ServicePresenter:

package com.artima.place;

public interface Presentable {

    void setServicePresenter(ServicePresenter presenter);
    ServicePresenter getServicePresenter();
}

3. The Place Interface

The com.artima.place.Place interface contains only one method, getLinkMap(), which takes no parameters and returns a LinkMap object, an object that implements the com.artima.place.LinkMap interface. A LinkMap object is a collection of links to resources on the network. Jini services of any type can, in addition to other services they offer through their interface, offer a "collection of links" service through their interface by implementing com.artima.place.Place.

Here's the Place interface:

package com.artima.place;

import java.rmi.RemoteException;

public interface Place extends Presentable {

    LinkMap getLinkMap() throws RemoteException;
}

4. The LinkMap Interface

A LinkMap holds a collection of links to resources on the network. The methods declared in interface com.artima.place.LinkMap allow clients to access, but not change those links. Interface ModifiableLinkMap, a subinterface of LinkMap described later in this specification, allows clients to modify the links contained in a LinkMap. The links contained in a DynamicLinkMap, yet another subinterface of LinkMap described later in this specification, may asynchronously change while the client is using the DynamicLinkMap.

LinkMap is called a map because each link contained in a LinkMap is associated with an Object key. To obtain the link value for a particular key, clients can invoke the get() method, which takes an Object key as its only parameter and returns a LinkItem. LinkItem is described in the next section of this specification.

Here's the LinkMap interface:

package com.artima.place;

import java.io.Serializable;
import java.rmi.RemoteException;
import java.util.Set;
import java.util.Collection;

public interface LinkMap extends Serializable {

    boolean containsAllKeys(Collection keys) throws RemoteException;
    boolean containsAllLinkItems(Collection values) throws RemoteException;
    boolean containsKey(int key) throws RemoteException;
    boolean containsKey(Object key) throws RemoteException;
    boolean containsLinkItem(LinkItem value) throws RemoteException;

    LinkItem get(int key) throws RemoteException;
    LinkItem get(Object key) throws RemoteException;

    boolean isEmpty() throws RemoteException;

    KeyIterator keyIterator() throws RemoteException;
    int keySetSize() throws RemoteException;

    LinkItemIterator linkItemIterator() throws RemoteException;
    int size() throws RemoteException;
}

The motivation for having Place return a LinkMap, rather than simply declaring the LinkMap methods in Place, is to make it easy for any Jini service class to implement Place. The method signatures in LinkMap seem more likely clash with method signatures appearing in other interfaces or classes compared to the method signatures in Place.

5. LinkItem and Link

The object returned by LinkMap's get() method is an instance of com.artima.place.LinkItem. LinkItem is a simple container for two other objects, a com.artima.place.Link and a com.artima.place.info.InfoBundle. The Link object represents the actual link to a service on the network. The InfoBundle object provides localizable information, suitable for presentation to users, about the service referenced by the Link.

The motivation for having a LinkItem that associates an InfoBundle with a Link, rather than allowing Links themselves to contain an InfoBundle, is that the information stored in the InfoBundle belongs to the Place, not to the Link or the service it references. Just as current users of the World Wide Web bookmark pages they want to return to, users of a space of objects may want to copy object Links to their own modifiable home places. They may then wish to change the name, description, and/or icons associated with that copied and saved Link. By keeping Link and InfoBundle separate, each client can change the InfoBundle associated with their own copies of Links.

Here are the public portions of LinkItem:

package com.artima.place;

import java.io.Serializable;
import com.artima.place.info.InfoBundle;

public class LinkItem implements Serializable {

    public LinkItem(Link link, InfoBundle infoBundle) {...}

    public Link getLink() {...}

    public InfoBundle getInfoBundle() {...}

    public boolean equals(Object o) {...}

    public int hashCode() {...}
}

5.1. The Link Interface

An object that implements interface com.artima.place.Link represents a link to a resource on the network. In the current World Wide Web, links to resources are expressed in terms of URLs, a string that represents an address or unique name of a resource. Links are intended to serve the same purpose as URLs, but Links a distinctly different from URLs.

Although like URLs, Links represent links to resources on the network, Links are not just wrappers for URLs. Link is an attempt to raise the level of abstraction of URLs. A URL is data. You can send a URL across the network to a client, but for the client to use the URL, the client needs code already existing on the client side that knows how to interpret the URL data. In particular, the client needs to know the protocol indicated in the first portion of the URL. What's more, the person doing the sending of the URL needs to know the host and port number where the resource is available, in addition to the name of the resource.

In contrast to URLs, a Link is not a chunk of data, a Link is an object. You can send a Link across the network to the client, just as you can send a URL across the network. But in the case of a Link, you are not sending data across the network, you are sending behavior. To follow a Link, you ask the Link to get the resource for you. The behavior determining how the resource is retrieved does not reside in client side code, but is contained in the code that defines the Link's class, code that is sent across the network as part of the Link object. To retrieve a resource, the Link can do anything it wants (so long as it is allowed by the local security policy) to retrieve the resource.

Here's the Link interface:

package com.artima.place;

import java.rmi.RemoteException;

public interface Link {

    LinkActivation activate(ActivationClient ac);
}

One of the motivations of raising the level of abstraction of a URL is that a Link will be able to do fancy things with Jini lookup services that would be very difficult to express in a URL. For example, a Link could do multicast discovery to get references to nearby Jini lookup services. It could then perform lookups by type and attributes in those lookup services, and sort through multiple responses using some algorithm that is also part of the network-delivered code of the Link. One of the goals for Link is to provide an abstraction that everyday users can understand that enables those users to access the functionality of the ServiceRegistrar interface.

More discussion of link activation is given later in this specification.

6. InfoBundle and Distributed Localization

Accompanying each Link in a LinkItem is an instance of com.artima.place.info.InfoBundle. InfoBundle allows clients to retrieve localizable information, suitable for presentation to users, about the resource referenced by the Link. An InfoBundle contains a set of info objects, objects that provide localizable information that describe the linked-to service. For example, this specification recommends that service providers include at least these three info objects in any InfoBundle in a LinkItem:

• A com.artima.place.info.Name instance, which provides a localizable name.
• A com.artima.place.info.Description instance, which provides a localizable description.
• A com.artima.place.info.Icons instance, which provides localizable icons.

In addition to Icons, the Place API includes two other classes for info objects:

• A com.artima.place.info.Keywords instance, which provides a localizable keywords (which search engines could use to index the service).
• A com.artima.place.info.ModificationDate instance, which provides a last modified date.

One other info object we have considered is a Thumbnail, which would allow clients to get compressed views of the service.

6.1 Localization

Class InfoBundle and its accompanying attribute classes are designed to both deal with the challenges of localizing network-delivered software and allowing users to make copies of links to store in their own modifiable places. The getBundle methods of class java.util.ResourceBundle are designed with the assumption that all localized flavors of a resource bundle will be installed nearby. To determine the best fit resource bundle for a desired locale, these methods create file names for class and property files, and go look for them in a defined order. (For details, see the Javadoc documentation for class java.util.ResourceBundle.) If network mobile code uses this mechanism as is, then all the JAR files that contain class and property files for resource bundles would need to be downloaded across the network to the client, so the getBundle method can figure out the best-fit bundle.

The main class that supports distributed localization in the Place API is com.artima.place.info.ResourceBundleLoader. An instance of this class may be contained in InfoBundle and the other info classes. A ResourceBundleLoader is in effect a client-side cache of the information embedded in the class and property file names of resource bundles that may still be on the other side of the network. A ResourceBundleLoader contains a mapping from Locales to codebase URLs. This mapping allows a ResourceBundleLoader to determine the best fit resource bundle before any JAR files containing resource bundles are downloaded. Thus, ResourceBundleLoader enables service providers to distribute resource bundles among several JAR files. Clients will only download the JAR file that contains the resource bundle they are actually going to use.

6.2 Copying Links

In addition to a ResourceBundleLoader, each info object may contain a cache of the most recently requested locale of the information it encapsulates. Service providers may fill the cache with an initial guess at what most clients will desire, or leave the cache empty. As soon as the information is requested of the object, however, the cache will be filled.

If an info object already contains in its cache the best-fit locale for a piece of information (either name or description) requested of it, the info object need not download a JAR file containing the localized information. The info object just returns the cached information. If a user copies a link to his or her modifiable home place (such as with drag and drop), that copied link will most likely already have the appropriate locale in its cache. This means that the place service receiving the link, the user's home place, won't have to go get the JAR file containing the localized resources. Since the copied link will reappear every time the user revisits his or her home place, the caching approach will prevent many network connections to grab JAR files resource bundles for InfoBundles and the info objects they contain.

Lastly, info object may implement Purgable, an interface that declares two purge methods. Invoking purge requests that an info object purge itself of undersired localization information. Once an info object has landed in front of a user, it is most likely already localized for that user. When a user copies the link to his or her home place, the home place can purge the InfoBundle of any locales other than the user's locale, because those locales are not desired by that user.

6.3 The LinkEntry Class

Service providers can provide a master copy of an InfoBundle and Link for their service by placing a LinkEntry entry in their ServiceItem. LinkEntry is an entry class that contains an InfoBundle and a Link. This entry can be used by spiders (or any other kind of searchers, such as a Gnutella-like distributed search) to gather information about a service, or test a query for a match.

LinkEntry can also be used by a modifiable place service to enable a user to "reset" an InfoBundle and/or a Link from the master copy. This enables a user to get back ResourceBundleLoader that were purged when the link was copied. Plus, since modifiable home places will likely often allow users to change at least the name associated with a link, resetting an InfoBundle will enable the user to get back the original name if they've forgotten what their own name meant. To reset an InfoBundle, a place service need only activate the link and grab the master InfoBundle out of the LinkEntry entry contained in the ServiceItem that results from the link activation.

7. Activating Links

When the activate method is invoked on a Link, the Link will attempt to retrieve the referenced Jini service. Here's the signature of the activate method:

    LinkActivation activate(ActivationClient al);

7.1. The ActivationClient Interface

The activate method accepts a single parameter, an object that implements com.artima.place.ActivationClient. The ActivationClient passed to activate is notified when a link activation completes, either with success, failure, or as a result of being aborted. Only one of the methods in this interface will be invoked (only once) for each link activation. This enables clients to indicate to users that an activation is in progress. For example, a client could show an animation while the activation is in progress, then stop the animation after the activation completes.

Here's the ActivationClient interface:

package com.artima.place;

public interface ActivationClient {

    void activationSucceeded(ServiceItem serviceItem);

    void activationFailed();

    void activationAborted();
}

The result of every successful link activation is a Jini ServiceItem, which is passed to the activationSucceeded method.

7.2. The LinkActivation Interface

The activate method returns an object that implements the com.artima.place.LinkActivation interface. The activate method should never block until the activation completes. Rather, activate should return promptly. The LinkActivation object returned by activate represents the ongoing activation to the client. The LinkActivation object allows the client to abort the activation via the abort method. The object may optionally implement other interfaces, such as ProgressEventGenerator, or include other methods in its class, which allow other kinds of client interaction. ProgressEventGenerator is described later in this specification.

Here's the LinkActivation interface:

package com.artima.place;

public interface LinkActivation {

    void abort();
}

7.3. The ProgressEventGenerator Interface

The LinkActivation object returned from activate may optionally implement the com.artima.place.ProgressEventGenerator interface, which enables clients to register interest in receiving progress updates, expressed in terms of percent complete, during the course of the activation. Here's the ProgressEventGenerator interface:

package com.artima.place;

public interface ProgressEventGenerator {

    void addProgressListener(ProgressListener pl);

    void removeProgressListener(ProgressListener pl);
}

The methods of ProgressEventGenerator accept an object that implements the com.artima.place.ProgressListener interface. ProgressListener contains one method, progressUpdated, which is invoked when the progress of an activation has changed. Progress is reported as percent complete. Although users would expect that the percent complete reported would in general increase over time, the actual progress events need not report consecutive percentages, or even increasing percentages.

Here's the ProgressListener interface:

package com.artima.place;

public interface ProgressListener {

    void progressUpdated(ProgressEvent pe);
}

To notify a ProgressListener of a change in percentage complete, the event generator passes a com.artima.place.ProgressEvent to the ProgressListener's progressUpdated method. The ProgressEvent contains an int percent complete, which may be communicated to users via a explicit percentage number, a progress bar, or other means.

Here are the public portions of the ProgressEvent class:

package com.artima.place;
import java.util.EventObject;

public class ProgressEvent extends EventObject {

    public ProgressEvent(ProgressEventGenerator source,
        int percentComplete) {...}

    public int getPercentComplete() {...}
}

ProgressEvents indicate the overall activation progress (major progress), not the the progress of each individual activity (minor progress). Thus, the progress should not snap from zero to 100 percent quickly and repetitively during the lifetime of the activation. Progress should in general move from zero to 100 percent once for each activation, and in general have at least four or five discreet reported percentages.

8. The ModifiableLinkMap Interface

Service providers can use Place services to present multiple services to users. In such Places, links will be controlled by the service provider. Users will be allowed to activate links at those Places, but not add, delete, or change the links. But some Place services will be provided to users, so that the users can organize their own links to resources on the network. At this kind of Place, links will be controlled by the user.

The com.artima.place.ModifiableLinkMap interface enables users to maintain links to their favorite resources. Regardless of whether the links at a Place are intended to be controlled by the service provider or user, the service object implements the same interface, com.artima.place.Place. In either case, clients obtain a LinkMap by invoking getLinkMap on the Place service object. The returned object definitely implements LinkMap, but may also implement ModifiableLinkMap, which is a subinterface of LinkMap. If the object is a ModifiableLinkMap, the client will be able to add, delete, and change links contained in the LinkMap via the methods declared in ModifiableLinkMap interface. The changes requested via the ModifiableLinkMap interface are persistent with respect to the Place. The next time a user visits the same Place, the user will see all the changes made the previous visit.

With a ModifiableLinkMap, a client can add a new LinkItem to a Place via the put method, can remove a LinkItem via the remove method, and can associate a new InfoBundle with an existing Link via the update method. Here's the ModifiableLinkMap interface:

package com.artima.place;

import java.rmi.RemoteException;
import com.artima.place.info.InfoBundle;

public interface ModifiableLinkMap extends LinkMap {

    void clear() throws RemoteException;

    LinkItem put(Object key, LinkItem value) throws RemoteException;

    LinkItem put(int key, LinkItem value) throws RemoteException;

    LinkItem put(LinkItem value) throws RemoteException;

    LinkItem update(Object key, InfoBundle infoBundle) throws RemoteException;

    void putAll(LinkMap map) throws RemoteException;

    LinkItem remove(Object key) throws RemoteException;
}

9. The DynamicLinkMap Interface

A DynamicLinkMap represents a dynamic map of links to resources on the network. The map is "dynamic" because it may asynchronously change while the client using it. For example, a Place service may provide a client with links to the Jini services registered in a particular lookup service that match a particular template. As matching services arrive and depart the lookup service, links to those services will be dynamically added and removed from the Place's LinkMap.

The DynamicLinkMap interface contains methods that enable the client to register and unregister itself as an interested listener for events that describe changes to the map. A LinkMap implementation class can optionally implement ModifiableLinkMap and/or DynamicLinkMap. A class that implements both ModifiableLinkMap and DynamicLinkMap will notify LinkMapListeners of all changes to the LinkMap, including changes resulting from the client invoking methods declared in ModifiableLinkMap.

Here's the DynamicLinkMap interface:

package com.artima.place;

import java.io.Serializable;
import java.rmi.RemoteException;
import java.util.Set;
import java.util.Collection;

public interface DynamicLinkMap extends LinkMap {

    void addLinkMapListener(LinkMapListener lml);

    void removeLinkMapListener(LinkMapListener lml);
}

The linkMapChanged method of all registered LinkMapListeners are invoked when one or more links in a DynamicLinkMap are altered, added, and/or removed. Here's the LinkMapListener interface:

package com.artima.place;

public interface LinkMapListener {

    void linkMapChanged(LinkMapEvent lme);
}

A LinkMapEvent indicates a change in the contents of a DynamicLinkMap. This event will only be fired if at least one link was altered, added, or removed. On the other hand, a single LinkMapEvent may be used to report multiple alterations, additions, and/or removals. Each alteration, addition, or removal of a particular DynamicLinkMap is reported in one and only one LinkMapEvent.

Each get method in LinkMapEvent returns an array of Object keys for those links that have been either altered, added, or removed. Here's the public portions of LinkMapEvent:

package com.artima.place;
import java.util.EventObject;

public class LinkMapEvent extends EventObject {

    public LinkMapEvent(DynamicLinkMap source, Object[] keysAltered,
        Object[] keysAdded, Object[] keysRemoved) {...}

    public Object[] getKeysAltered() {...}

    public Object[] getKeysAdded() {...}

    public Object[] getKeysRemoved() {...}
}

10. Link Implementations

The com.artima.place package contains three implementations of the com.artima.place.Link interface.

10.1. Class URLLink

URLLink is an implementation of the Link interface that produces a Jini ServiceItem that contains a URLFactory service and null references in the service id and attribute sets fields. Here are the public portions of URLLink:

package com.artima.place;

public final class URLLink implements Link {

    public URLLink(URLString url) {...}
    public URLLink(URLString[] urls) {...}

    public LinkActivation activate(ActivationClient al) {...}
}

The URLFactory Jini service interface has methods that allow clients to get at the single or multiple URLs stored in the URLFactory. Here's the URLFactory interface:

package com.artima.place;

import java.io.Serializable;
import java.util.List;

public final class URLFactory implements Serializable {

    public URLFactory(URLString url) {...}
    public URLFactory(URLString[] urls) {...}

    public int getLength() {...}
    public URLString getURL() {...}
    public URLString[] getURLs() {...}
    public List getURLsAsList() {...}
}

URLFactory is used to wrap existing file-based resources, such as web pages. Instead of plug-ins that must be installed at the client by the user, a network-mobile service UI can automatically provide a user access to the file-based resource. If a URLFactory doesn't contain a suitable UI for a file with a MIME type, the browser could go look up a batch of UIDescriptors given the MIME type. The browser can have its own repertiore of client UIs and can also possibly consult a "UI descriptor service" over the network. This UI descriptor service is kind of like Netscape Navigator giving you information about potential plug-ins that will let you view some content, but in this case the information about each service UI "plug-in" is encapsulated in a UIDescriptor, a form that will allow the browser code to decide on a UI and seamlessly "install" it. Thus, besides granting users access to the space of Jini services on the network, Place API attempts to give users a more seamless experience when using web resources than is possible with existing web browsers.

10.2. Class UnicastDiscoveryLink

UnicastDiscoveryLink is an implementation of the Link interface that produces a Jini service by performing unicast discovery on one or more Jini lookup services and performing lookups with a ServiceTemplate.

10.3. Class MulticastDiscoveryLink

MulticastDiscoveryLink is an implementation of the Link interface that produces a Jini service by performing multicast discovery on one or more Jini lookup services and performing lookups with a ServiceTemplate.

11. Jini Service URLs

Although Places are collections of Links, not URLs, for resources on the existing web to link into the web of objects, objects will need to be accessible via URLs.

11.1 HTTP URLs

To enable Jini services and service UIs to be referenced via HTTP URLs, the following MIME type is proposed: application/x-serviceitem. A file delivered with this MIME type should be a serialized java.rmi.MarshalledObject, that contains a marshalled net.jini.core.lookup.ServiceItem.

An HTTP server could produce an application/x-serviceitem file in any way. A servlet could, for example, do a lookup in a Jini lookup service, marshal the resulting ServiceItem, serialize the marshalled object, and return it to the client. Alternatively, an HTTP service could just grab a file that already contains a serialized marshalled ServiceItem, and return that file. This specification recommends using .si as the standard extension for such files.

Other possibilities for the recommended MIME type are:

• application/x-service
• application/x-jini

Other possibilities for the recommended file extension are:

• .service
• .item
• .svc
• .jini

10.2 JINI URLs

The jini: URL as currently defined identifies a Jini lookup service. The host name or IP address specifies the host on which the lookup service is running, such as:

jini://www.artima.com
or
jini://123.45.678.9

If no port number is given, as shown in the previous examples, the default port number for Jini services, 4160, is implied. As with all URLs, if you need to address a lookup service at a different port besides the default, you can specify the port explicitly, as in:

jini://www.artima.com:2000
or
jini://123.45.678.9:2001

Although URLs often have a fourth component after the protocol, host, and port number, jini: no fourth component is currently defined for jini: URLs. This specification proposes that the Jini Community define that fourth component to mean a Jini service that is registered within the Jini lookup service identified by the host and port number of the URL.

A Jini service can be uniquely identified inside a lookup service is by its service ID. This specification proposes that the jini: protocol indicate a service ID of a Jini service registered at the indicated host and port. For example:

jini://www.artima.com:7777/a1366531-5805-4f2e-8b40-e6b9b36f78fb

To locate a service referenced by a jini: URL with a fourth component, the Jini client that is handed the URL first checks to see if it already has a ServiceRegistrar for the lookup service identified by the host and port number specified in the URL. If not, the client attempts to perform unicast discovery on that lookup service. If successful, the client instantiates a net.jini.core.lookup.ServiceID of the same value represented in the file portion of the URL. The client places this ServiceID in the serviceID field of a ServiceTemplate, and makes a lookup query. If no service matches the query, then the service identified by the URL is not available. Otherwise, the matching service is selected and returned.

Alternatively, could define something like the following, which would also allow lookups by name and potentially other things.

• jini://www.artima.com:876/lookup=name=IlludiumQ36ExplosiveSpaceModulator
• jini://www.artima.com:876/lookup=name=cal9000
• jini://www.artima.com:876/lookup=serviceid=a1366531-5805-4f2e-8b40-e6b9b36f78fb

12. Search

The Jini lookup service is designed to help software, not users, find network-delivered services. Nowadays, when users are looking for a network-delivered service, they go to search engines. Many search engine databases are constructed by autonomous robots, which "spider" the web. A spider visits a page, places information about that page into its search engine database, then follows links from that page to other pages. The Place API includes support for spiders or other search agents, such as those used in Gnutella-like distributed searches. A search agent can follow the links contained in a Place, and thereby "spider" the space of all Jini services. For each service, the search agent can collect localizable information about the service, suitable for presenting to users, from an InfoBundle contained in a LinkEntry contained in the attribute sets of the services's ServiceItem. The InfoBundle's info objects can include Keywords, which a search engine spider can use to index a service.

We feel that search will be extremely important way that users will access services, even within Places. If you have 10,000 Links in a Place, you'll have to search for things. Expect more on search in the coming months.

13. Package com.artima.place

Provides classes and interfaces that enable Jini services to act as collections of links to other services on the network. The full specification of this package is available at:

http://www.artima.com/jini/cyberspace/Spec.html

13.1. Summary of Interfaces In Package com.artima.place

• ActivationClient - Interface implemented by an object that is notified when a link activation completes, either with success, failure, or as a result of being aborted.
• Dismissable - Interface implemented by network-mobile objects that consume finite non-memory resources, such as sockets, database connections, threads, file handles, etc.
• DynamicLinkMap - Represents a dynamic map of links to resources on the network.
• KeyIterator - A iterator over a potentially distributed collection of object keys.
• Link - Represents a link to a service on the network.
• LinkActivation - Interface implemented by the object returned by the activate method of a Link that represents a progressing activation.
• LinkItemIterator - A iterator over a potentially distributed collection of LinkItems.
• LinkMap - Represents a map of links to resources on the network.
• LinkMapListener - The listener interface for receiving LinkMapEvents from a DynamicLinkMap.
• ModifiableLinkMap - Represents a modifiable map of links to services on the network.
• Place - A collection of links to services on the network.
• Presentable - A Jini service interface for services that may activate Links on behalf of users.
• ProgressEventGenerator - Interface optionally implemented by the object returned by the activate method of a Link to allow the client to receive progress updates during the course of the activation.
• ProgressListener - The listener interface for receiving ProgressEvents from the ProgressEventGenerator object, which may be returned by a Link's activate method.

13.2. Summary of Classes In Package com.artima.place

• LinkEntry - Entry containing a link to this service (the service in whose ServiceItem this entry appears) and bundle of localizable information that can be used to represent a link to this service to users.
• LinkItem - Associates a Link to an InfoBundle.
• LinkMapEvent - An event that indicates a change in the contents of a DynamicLinkMap.
• MulticastDiscoveryLink - A Link that performs queries in lookup services located via multicast discovery.
• ProgressEvent - An event that indicates a revised progress of a Link activation expressed in terms of percent complete.
• ServerAddress - Holds a String host name and int port number.
• ServicePresenter - Contains a method that allows clients to request that the service host present a service to the user.
• UnicastDiscoveryLink - Represents a unicast discovery-based link to a Jini service on the network.
• URLFactory - Jini service that produces a URL or array of URLs.
• URLLink - Represents a URL-based link to a service on the network.
• URLString - Holds a valid URL String.

13.3. Summary of Exceptions In Package com.artima.place

No Exceptions are declared in package com.artima.place.

13.4. Summary of Errors In Package com.artima.place

No Errorss are declared in package com.artima.place.

13.5. Interface com.artima.place.ActivationClient

public interface ActivationClient


Interface implemented by an object that is notified when a link activation completes, either with success, failure, or as a result of being aborted. Only one of the methods in this interface will be invoked (only once) for each link activation.

13.5.1. Method activationSucceeded(net.jini.core.lookup.ServiceItem)

public void activationSucceeded(net.jini.core.lookup.ServiceItem item)


Invoked when a Link activation succeeds. The client recieves the ServiceItem that resulted from the link activation as a parameter of this method.

Parameters:

item - the ServiceItem resulting from the successful link activation

Throws:

NullPointerException - if passed item is null

13.5.2. Method activationFailed()

public void activationFailed()


Invoked when a Link activation fails for any reason except being aborted.

13.5.3. Method activationAborted()

public void activationAborted()


Invoked when a Link activation fails because of being aborted. Because a client indicates they wish to abort an activation by invoking abort on the LinkActivation returned by the activate method, a client may request abort just as the activation succeeds or fails. So after a client invokes abort, this method will likely be invoked on the ActivationListener, but either of the other two methods in this interface may alternatively be invoked.

13.6. Interface com.artima.place.Dismissable

public interface Dismissable


Interface implemented by network-mobile objects that consume finite non-memory resources, such as sockets, database connections, threads, file handles, etc. This interface provides a "universal cleanup method" that allows clients, whose finite non-memory resources are being consumed, to ask the Dismissable object to release those resources prior to the client's releasing the Dismissable object to the whims of the garbage collector.

13.6.1. Method dismissObject()

public void dismissObject()


Releases any non-memory finite resources held by the object, such as file handles, sockets, database connections, graphics contexts, running threads, etc. Once this method has been invoked, the object may be defunct. If defunct, the object will no longer be able to fulfill some or all of its contract.

Clients should only call this method right before releasing all remaining references to this object. If the resource have already been released, either through invocation of other cleanup methods or a prior invocation of dismissObject, this method has no effect.

13.7. Interface com.artima.place.DynamicLinkMap

public interface DynamicLinkMap
     extends com.artima.place.LinkMap


Represents a dynamic map of links to resources on the network. The map is dynamic because it may asynchronously change while the client using it. For example, a Place service may provide a client with links to the Jini services registered in a particular lookup service that match a particular template. As matching services arrive and depart the lookup service, links to those services will be dynamically added and removed from the Place's LinkMap.

A LinkMap implementation class can optionally implement ModifiableLinkMap and/or DynamicLinkMap. A class that implements both ModifiableLinkMap and DynamicLinkMap will notify LinkMapListeners of all changes to the LinkMap, including changes resulting from the client invoking methods declared in ModifiableLinkMap.

13.7.1. Method addLinkMapListener(com.artima.place.LinkMapListener)

public void addLinkMapListener(com.artima.place.LinkMapListener listener)


Adds the specified LinkMapListener to receive LinkMapEvents from this object.

Parameters:

listener - the LinkMapListener to add

Throws:

NullPointerException - if passed listener is null

13.7.2. Method removeLinkMapListener(com.artima.place.LinkMapListener)

public void removeLinkMapListener(com.artima.place.LinkMapListener listener)


Removes the specified LinkMapListener so that it no longer receives LinkMapEvents from this object.

Parameters:

listener - the LinkMapListener to remove

Throws:

NullPointerException - if passed listener is null

13.8. Interface com.artima.place.KeyIterator

public interface KeyIterator


A iterator over a potentially distributed collection of object keys. KeyIterator supports distributed collections by including RemoteException in the throws clauses of all its methods. In addition, KeyIterator provides cache support via its cachNext method, which enables clients to manage network traffic.

13.8.1. Method hasNext()

public boolean hasNext()
     throws java.rmi.RemoteException


Returns true if the iteration has more elements.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.8.2. Method next()

public java.lang.Object next()
     throws java.rmi.RemoteException


Returns the next element in the iteration.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.8.3. Method cacheNext(int)

public void cacheNext(int cacheSize)
     throws java.rmi.RemoteException


Requests that the next cacheSize elements be cached locally. Any elements remaining in the iteration, up to the passed cacheSize, that have not yet been downloaded across the network will be downloaded when this method is invoked.

Parameters:

cacheSize - the number of elements to cache locally.

Throws:

IllegalArgumentException - if passed cacheSize is less than or equal to zero.

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.9. Interface com.artima.place.Link

public interface Link
     extends java.io.Serializable


Represents a link to a service on the network. The result of any successful link activation is a Jini service item, passed to the ActivationClient via the activationSucceeded method.

13.9.1. Method activate(com.artima.place.ActivationClient)

public com.artima.place.LinkActivation activate(com.artima.place.ActivationClient activationClient)


Retrieve this service. The activate method will return promptly, returning a LinkActivation object that enables clients to abort an activation. Invoking activate again while an activation is currently in progress just starts a new activation independent of the already running one.

Parameters:

activationClient - the ActivationClient that will notified when this link activation completes

Throws:

NullPointerException - if passed activationClient is null

13.10. Interface com.artima.place.LinkActivation

public interface LinkActivation
     extends java.io.Serializable


Interface implemented by the object returned by the activate method of a Link that represents a progressing activation. The LinkActivation object allows the client to abort the activation via the abort() method. The object may optionally implement other interfaces, such as ProgressEventGenerator and StatusEventGenerator, or include other methods in its class, which allow other kinds of client interaction.

13.10.1. Method abort()

public void abort()


Requests an abort of a Link activation. If the activation is still progressing, and has not previously succeeded, failed, or been aborted, then the activation is aborted. Otherwise, invoking abort has no effect. The abort() method does not throw an exception to indicate the activation has already succeeded, failed, or been aborted, but returns normally in these cases.

13.11. Class com.artima.place.LinkEntry

public class LinkEntry


Entry containing a link to this service (the service in whose ServiceItem this entry appears) and bundle of localizable information that can be used to represent a link to this service to users.

13.11.1. Constructor LinkEntry()

public LinkEntry()


Constructs a LinkEntry with all fields set to null.

13.11.2. Constructor LinkEntry(com.artima.place.info.InfoBundle, com.artima.place.Link)

public LinkEntry(com.artima.place.info.InfoBundle infoBundle, com.artima.place.Link link)


Constructs a LinkEntry with its infoBundle and link fields set to the passed values.

Parameters:

infoBundle - the InfoBundle to store in this LinkEntry, or null.

link - the Link to store in this LinkEntry, or null.

13.11.3. Field infoBundle

public infoBundle


InfoBundle object that provides localized information about this service, suitable for presenting to users, which can be used in presenting or describing a link to this service to users.

13.11.4. Field link

public link


Link object that when activated, will yield this service.

13.12. Class com.artima.place.LinkItem

public class LinkItem
     extends java.lang.Object
     implements java.io.Serializable


Associates a Link to an InfoBundle. Keeping the InfoBundle outside of the Link, enables modifiable places to more easily change the InfoBundle data for a particular Link.

13.12.1. Constructor LinkItem(com.artima.place.Link, com.artima.place.info.InfoBundle)

public LinkItem(com.artima.place.Link link, com.artima.place.info.InfoBundle infoBundle)


Constructs a LinkItem with passed Link and InfoBundle.

Parameters:

link - The Link to hold in this LinkItem

infoBundle - The InfoBundle to hold in this LinkItem

Throws:

NullPointerException - if either of the Link or InfoBundle references passed to this constructor are null

13.12.2. Method getLink()

public com.artima.place.Link getLink()


Returns the Link object that's stored in this LinkItem.

13.12.3. Method getInfoBundle()

public com.artima.place.info.InfoBundle getInfoBundle()


Returns the InfoBundle object that's stored in this LinkItem. The InfoBundle provides information, suitable for display to users, about the linked-to service.

13.12.4. Method equals(java.lang.Object)

public boolean equals(java.lang.Object o)


Compares the specified Object with this LinkItem for equality. Two LinkItems are semantically equal if their Links are semantically equal and their InfoBundles are semantically equal. If the passed object reference is null, this method returns false.

13.12.5. Method hashCode()

public int hashCode()


Returns the hash code value for this LinkItem. The hashcode for a LinkItem is the exclusive OR of the hashcodes for the LinkItem's constituent Link and InfoBundle.

13.13. Interface com.artima.place.LinkItemIterator

public interface LinkItemIterator


A iterator over a potentially distributed collection of LinkItems. LinkItemIterator supports distributed collections by including RemoteException in the throws clauses of all its methods. In addition, LinkItemIterator provides cache support via its cachNext method, which enables clients to manage network traffic.

13.13.1. Method hasNext()

public boolean hasNext()
     throws java.rmi.RemoteException


Returns true if the iteration has more elements.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.13.2. Method next()

public com.artima.place.LinkItem next()
     throws java.rmi.RemoteException


Returns the next element in the iteration.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.13.3. Method cacheNext(int)

public void cacheNext(int cacheSize)
     throws java.rmi.RemoteException


Requests that the next cacheSize elements be cached locally. Any elements remaining in the iteration, up to the passed cacheSize, that have not yet been downloaded across the network will be downloaded when this method is invoked.

Parameters:

cacheSize - the number of elements to cache locally.

Throws:

IllegalArgumentException - if passed cacheSize is less than or equal to zero.

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.14. Interface com.artima.place.LinkMap

public interface LinkMap


Represents a map of links to resources on the network. If a LinkMap object also implements ModifiableLinkMap, the client may add, remove, and alter the LinkItems contained in the LinkMap. If a LinkMap object also implements DynamicLinkMap, LinkItems may be added to or removed from the LinkMap, and existing LinkItems may be altered, by parties other than the client.

13.14.1. Method get(java.lang.Object)

public com.artima.place.LinkItem get(java.lang.Object key)
     throws java.rmi.RemoteException


Returns the LinkItem value to which this LinkMap maps the specified Object key. Returns null if the map contains no mapping for this key. A return value of null does definitely indicate that the map contains no mapping for the key, because LinkMaps never map a key to the value null. In other words, all keys contained in the LinkMap are associated with a non-null LinkItem value.

Parameters:

key - key whose associated value is to be returned.

Throws:

NullPointerException - if passed key is null

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.14.2. Method get(int)

public com.artima.place.LinkItem get(int key)
     throws java.rmi.RemoteException


Convenience method that returns the LinkItem value to which this LinkMap maps the Integer key with the int value passed in the key parameter. Returns null if the map contains no mapping for this key. A return value of null does definitely indicate that the map contains no mapping for the key, because LinkMaps never map a key to the value null. In other words, all keys contained in the LinkMap are associated with a non-null LinkItem value.

Parameters:

the - int value of an Integer key whose LinkItem mapping is requested

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.14.3. Method containsKey(java.lang.Object)

public boolean containsKey(java.lang.Object key)
     throws java.rmi.RemoteException


Returns true if this LinkMap contains a mapping for the specified key.

Parameters:

key - key whose presence in this LinkMap is to be tested.

Throws:

NullPointerException - if passed key is null

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.14.4. Method containsKey(int)

public boolean containsKey(int key)
     throws java.rmi.RemoteException


Returns true if this LinkMap contains a mapping for the key created by wrapping the specified int in an Integer object.

Parameters:

key - int key whose presence in in this LinkMap in Integer form is to be tested.

Throws:

NullPointerException - if passed key is null

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.14.5. Method containsAllKeys(java.util.Collection)

public boolean containsAllKeys(java.util.Collection keys)
     throws java.rmi.RemoteException


Returns true if this LinkMap contains a mapping for each key in the passed collection.

Parameters:

keys - collection of keys to check for in this LinkMap's set of keys.

Throws:

NullPointerException - if passed keys is null

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.14.6. Method containsLinkItem(com.artima.place.LinkItem)

public boolean containsLinkItem(com.artima.place.LinkItem value)
     throws java.rmi.RemoteException


Returns true if this LinkMap maps one or more keys to the specified value.

Parameters:

value - LinkItem check for in this LinkMap.

Throws:

NullPointerException - if passed value is null.

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.14.7. Method containsAllLinkItems(java.util.Collection)

public boolean containsAllLinkItems(java.util.Collection values)
     throws java.rmi.RemoteException


Returns true if this LinkMap maps one or more keys to each LinkItem value in the passed collection.

Parameters:

values - collection of LinkItems to check for in this LinkMap collection of values.

Throws:

NullPointerException - if passed values is null

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.14.8. Method isEmpty()

public boolean isEmpty()
     throws java.rmi.RemoteException


Returns true if this map contains no key-value mappings.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.14.9. Method keyIterator()

public com.artima.place.KeyIterator keyIterator()
     throws java.rmi.RemoteException


Returns a KeyIterator over the Object keys contained in this LinkMap.

If changes occur to this LinkMap after this method returns, which is possible if this object is a DynamicLinkMap or a ModifiableLinkMap, those changes will be reflected in the returned KeyIterator. In other words, the returned KeyIterator is backed by this LinkMap.

If an iteration (via a KeyIterator) is in progress when this LinkMap is changed, the iteration will be able to continue to completion, but may give stale results or result in an NoSuchElementException being thrown as a result of the change to the underlying LinkMap. Any keys removed from this LinkMap may or may not be returned by subsequent invocations of next on the KeyIteration. (Of course, the removed keys may have already been returned by prior invocations of the next method). Any keys added to this LinkMap may or may not be returned by subsequent invocations of next on the KeyIteration.

Therefore, the client of a KeyIterator returned by a DynamicLinkMap or a ModifiableLinkMap should be careful to catch NoSuchElementException. For example, imagine a KeyIterator has one more key to return before the iteration completes. When the client invokes hasNext, the result will be true. If the key is then removed, then a subsequent invocation of hasNext could legally return false. I.e., the key removed from the LinkMap is also removed from the iteration. Since the client has already invoked hasNext and gotten a true back, however, the client may go ahead and simply invoke next. Even if the client has registered a LinkMapListener, that listener may not be notified of removal of the key before the client invokes next on the KeyIterator. The result of invoking next would then be a thrown NoSuchElementException.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.14.10. Method keySetSize()

public int keySetSize()
     throws java.rmi.RemoteException


Returns the number of unique keys in this map. Baring any changes to the underlying LinkMap, the value returned by this method will be the number of keys returned by iterating with the KeyIterator returned by the keyIterator method.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.14.11. Method size()

public int size()
     throws java.rmi.RemoteException


Returns the number of key-value mappings in this map.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.14.12. Method linkItemIterator()

public com.artima.place.LinkItemIterator linkItemIterator()
     throws java.rmi.RemoteException


Returns a LinkItemIterator over the LinkItem values contained contained in this LinkMap.

If changes occur to this LinkMap after this method returns, which is possible if this object is a DynamicLinkMap or a ModifiableLinkMap, those changes will be reflected in the returned LinkItemIterator. In other words, the returned LinkItemIterator is backed by this LinkMap.

If an iteration (via a LinkItemIterator) over the returned LinkCollection is in progress when this LinkMap is changed, the iteration will be able to continue to completion, but may give stale results or result in an NoSuchElementException being thrown as a result of the change to the underlying LinkMap. Any values removed from this LinkMap may or may not be returned by subsequent invocations of next on the LinkItemIterator. (Of course, the removed values may have already been returned by prior invocations of the next method). Any values added to this LinkMap may or may not be returned by subsequent invocations of next on the LinkItemIterator.

Therefore, the client of a LinkItemIterator returned by a DynamicLinkMap or a ModifiableLinkMap should be careful to catch NoSuchElementException. For example, imagine a LinkItemIterator has one more value to return before the iteration completes. When the client invokes hasNext, the result will be true. If the value is then removed, then a subsequent invocation of hasNext could legally return false. I.e., the value removed from the LinkMap is also removed from the iteration. Since the client has already invoked hasNext and gotten a true back, however, the client may go ahead and simply invoke next. Even if the client has registered a LinkMapListener, that listener may not be notified of removal of the value before the client invokes next on the LinkItemIterator. The result of invoking next would then be a thrown NoSuchElementException.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.15. Class com.artima.place.LinkMapEvent

public class LinkMapEvent
     extends java.util.EventObject


An event that indicates a change in the contents of a DynamicLinkMap. This event will only be fired if at least one link was altered, added, or removed. A single LinkMapEvent may be used to report multiple alterations, additions, and/or removals. Each alteration, addition, or removal of a particular DynamicLinkMap is reported in one and only one LinkMapEvent.

13.15.1. Constructor LinkMapEvent(com.artima.place.DynamicLinkMap, java.lang.Object[], java.lang.Object[], java.lang.Object[])

public LinkMapEvent(com.artima.place.DynamicLinkMap source, java.lang.Object[] keysAltered, java.lang.Object[] keysAdded, java.lang.Object[] keysRemoved)


Constructs a LinkMapEvent object with the specified keys altered, added, and removed. To indicate that no values have been altered (or added, or removed), either an empty Object array or a null reference must be passed in the keysAltered (or keysAdded or keysRemoved) parameter.

Parameters:

source - the source of this LinkMapEvent

keysAltered - an array of keys whose LinkItem values have been altered

keysAdded - an array of keys associated with LinkItem values that have been added

keysRemoved - an array of keys associated with LinkItem values that have been removed

Throws:

NullPointerException - if passed source is null

13.15.2. Method getKeysAltered()

public java.lang.Object[] getKeysAltered()


Returns an array of Object keys for those links that have been altered. A link is "altered" if a value for that key already existed in the LinkMap, and the value was altered or replaced a new value. If no links have been altered since the previous LinkMapEvent was propagated (or since the DynamicLinkMap was sent to the client if this is the first LinkMapEvent propagated), this method returns an empty Object array. This method never returns null.

13.15.3. Method getKeysAdded()

public java.lang.Object[] getKeysAdded()


Returns an array of Object keys for those links that have been added. A link is "added" if the key for a newly added LinkItem value did not previously exist in the LinkMap. If no links have been added since the previous LinkMapEvent was propagated (or since the DynamicLinkMap was sent to the client if this is the first LinkMapEvent propagated), this method returns an empty Object array. This method never returns null.

13.15.4. Method getKeysRemoved()

public java.lang.Object[] getKeysRemoved()


Returns an array of Object keys for those links that have been removed. A link is "removed" if its key previously existed in the LinkMap, but now does not. If no links have been removed since the previous LinkMapEvent was propagated (or since the DynamicLinkMap was sent to the client if this is the first LinkMapEvent propagated), this method returns an empty Object array. This method never returns null.

13.16. Interface com.artima.place.LinkMapListener

public interface LinkMapListener


The listener interface for receiving LinkMapEvents from a DynamicLinkMap.

13.16.1. Method linkMapChanged(com.artima.place.LinkMapEvent)

public void linkMapChanged(com.artima.place.LinkMapEvent event)


Invoked when one or more links in a DynamicLinkMap are altered, added, and/or removed.

Parameters:

event - the LinkMapEvent to handle

Throws:

NullPointerException - if passed event is null

13.17. Interface com.artima.place.ModifiableLinkMap

public interface ModifiableLinkMap
     extends com.artima.place.LinkMap


Represents a modifiable map of links to services on the network.

13.17.1. Method clear()

public void clear()
     throws java.rmi.RemoteException


Removes all mapping from this LinkMap.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.17.2. Method put(java.lang.Object, com.artima.place.LinkItem)

public com.artima.place.LinkItem put(java.lang.Object key, com.artima.place.LinkItem value)
     throws java.rmi.RemoteException


Associates the specified value with the specified key in this LinkMap.

Parameters:

key - the key with which to associate the specified LinkItem value in this LinkMap.

value - the LinkItem value to associate with the specified key in this LinkMap.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.17.3. Method put(int, com.artima.place.LinkItem)

public com.artima.place.LinkItem put(int keyValue, com.artima.place.LinkItem value)
     throws java.rmi.RemoteException


Convenience method that associates the specified value with the Integer key whose int value equals the int specified keyValue.

Parameters:

key - the key with which (in Integer form) to associate the specified LinkItem value in this LinkMap.

value - the LinkItem value to associate with the specified key in this LinkMap.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.17.4. Method put(com.artima.place.LinkItem)

public java.lang.Object put(com.artima.place.LinkItem value)
     throws java.rmi.RemoteException


Associates the specified value in this LinkMap with a new unique key selected by this method.

Parameters:

value - the LinkItem value to associate with a randomly selected new key in this LinkMap.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.17.5. Method update(java.lang.Object, com.artima.place.info.InfoBundle)

public com.artima.place.LinkItem update(java.lang.Object key, com.artima.place.info.InfoBundle infoBundle)
     throws java.rmi.RemoteException


Associates the specified InfoBundle with the Link that is associated with the specified key in this LinkMap.

Parameters:

key - the key with which to associate the specified LinkItem value in this LinkMap.

value - the LinkItem value to associate with the specified key in this LinkMap.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

NoSuchElementException - if the key is not associated with any LinkItem in this ModifiableLinkMap

13.17.6. Method putAll(com.artima.place.LinkMap)

public void putAll(com.artima.place.LinkMap map)
     throws java.rmi.RemoteException


Copies all of the mappings from the specified LinkMap to this LinkMap.

Parameters:

map - the LinkMap from which to copy mappings to this LinkMap.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations.

13.17.7. Method remove(java.lang.Object)

public com.artima.place.LinkItem remove(java.lang.Object key)
     throws java.rmi.RemoteException


Removes the mapping for this key from this LinkMap if present.

Parameters:

key - the key whose mapping is to be removed from this LinkMap.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.18. Class com.artima.place.MulticastDiscoveryLink

public final class MulticastDiscoveryLink
     extends java.lang.Object
     implements com.artima.place.Link


A Link that performs queries in lookup services located via multicast discovery.

13.18.1. Constructor MulticastDiscoveryLink(net.jini.core.lookup.ServiceTemplate)

public MulticastDiscoveryLink(net.jini.core.lookup.ServiceTemplate template)
     throws java.io.IOException, java.lang.ClassNotFoundException


Construct a MulticastDiscoveryLink with the passed ServiceTemplate.

The activate method will perform multicast discovery of all reachable lookup services, and query each discovered lookup service with the passed ServiceTemplate.

Parameters:

template - the ServiceTemplate with which to peform lookups when this link is activated

Throws:

IOException - if an I/O error occurs when attempting to serialize or deserialize the ServiceTemplate.

ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

13.18.2. Constructor MulticastDiscoveryLink(java.lang.String[], net.jini.core.lookup.ServiceTemplate)

public MulticastDiscoveryLink(java.lang.String[] groups, net.jini.core.lookup.ServiceTemplate template)
     throws java.io.IOException, java.lang.ClassNotFoundException


Construct a MulticastDiscoveryLink with the passed groups String array and ServiceTemplate.

The activate method will perform multicast discovery, and query each discovered lookup service with the passed ServiceTemplate. Does multicast discovery and lookups. When this link is activated it will just keep trying until either a match is found or the user aborts. If multiple matches are found, a random match is returned.

Parameters:

groups - an array of String group names with which perform multicast discovery when this link is activated.

template - the ServiceTemplate with which to peform lookups when this link is activated

13.18.3. Method activate(com.artima.place.ActivationClient)

public com.artima.place.LinkActivation activate(com.artima.place.ActivationClient al)


Retrieve this service. The activate method will return promptly, returning a LinkActivation object that enables clients to abort an activation. Invoking activate again while an activation is currently in progress just starts a new activation independent of the already running one.

Parameters:

al - the ActivationClient that will be notified when this link activation completes

Throws:

NullPointerException - if passed activationClient is null

13.18.4. Method getServiceTemplate()

public net.jini.core.lookup.ServiceTemplate getServiceTemplate()
     throws java.io.IOException, java.lang.ClassNotFoundException


Returns a duplicate of the ServiceTemplace used in lookups when this link is activated. The duplicate is created by serializing and then deserializing the actual ServiceTemplate.

Throws:

IOException - if an I/O error occurs when attempting to duplicate the ServiceTemplate.

ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

13.18.5. Method getGroups()

public java.lang.String[] getGroups()


Returns the groups used by this link in performing multicast discovery when activated. A null return value indicates this link will attempt discovery of all reachable lookup services when activated.

13.19. Interface com.artima.place.Place

public interface Place
     extends com.artima.place.Presentable


A collection of links to services on the network.

13.19.1. Method getLinkMap()

public com.artima.place.LinkMap getLinkMap()
     throws java.rmi.RemoteException


Returns a LinkMap collection of the Links contained in this Place.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

13.20. Interface com.artima.place.Presentable

public interface Presentable


A Jini service interface for services that may activate Links on behalf of users.

13.20.1. Method setServicePresenter(com.artima.place.ServicePresenter)

public void setServicePresenter(com.artima.place.ServicePresenter presenter)


Sets the ServicePresenter. This method would usually be invoked by the client to pass in a the service presenter context object to the Presentable service, before attaching a service UI.

Parameters:

presenter - the ServicePresenter to which this service may wish to delegate link activations

13.20.2. Method getServicePresenter()

public com.artima.place.ServicePresenter getServicePresenter()


Gets the ServicePresenter for this Presentable service. This method will return the object passed to the setServicePresenter method in its most recent invocation. If the setServicePresenter method has not yet been invoked, this method will return the default ServicePresenter returned by the ServicePresenter.getDefault method.

This method could be called by a service UI for a Presentable service, when the service UI detects that the user wishes to activate a link. The service UI can delegate the actual activation of that link to the ServicePresenter returned by this method.

13.21. Class com.artima.place.ProgressEvent

public class ProgressEvent
     extends java.util.EventObject


An event that indicates a revised progress of a Link activation expressed in terms of percent complete.

13.21.1. Constructor ProgressEvent(com.artima.place.ProgressEventGenerator, int)

public ProgressEvent(com.artima.place.ProgressEventGenerator source, int percentComplete)


Constructs a ProgressEvent object with the specified percent completion.

Parameters:

source - the source of this ProgressEvent

percentComplete - the percentage of completion that this ProgressEvent represents

Throws:

NullPointerException - if passed source is null

IllegalArgumentException - if percentComplete is less than zero or greater than 100

13.21.2. Method getPercentComplete()

public int getPercentComplete()


Returns the percent complete for this Link activation.

13.22. Interface com.artima.place.ProgressEventGenerator

public interface ProgressEventGenerator


Interface optionally implemented by the object returned by the activate method of a Link to allow the client to receive progress updates during the course of the activation. The object returned by activate need not implement this interface.

13.22.1. Method addProgressListener(com.artima.place.ProgressListener)

public void addProgressListener(com.artima.place.ProgressListener listener)


Adds the specified ProgressListener to receive progress events from this object. If pl is null, no exception is thrown and no action is performed.

Parameters:

listener - the LinkMapListener to add

Throws:

NullPointerException - if passed listener is null

13.22.2. Method removeProgressListener(com.artima.place.ProgressListener)

public void removeProgressListener(com.artima.place.ProgressListener listener)


Removes the specified ProgressListener so that it no longer receives progress events from this object. This method performs no function, nor does it throw an exception, if the listener specified by the argument was not previously added to this object. If pl is null, no exception is thrown and no action is performed.

Parameters:

listener - the LinkMapListener to remove

Throws:

NullPointerException - if passed listener is null

13.23. Interface com.artima.place.ProgressListener

public interface ProgressListener


The listener interface for receiving ProgressEvents from the ProgressEventGenerator object, which may be returned by a Link's activate method.

13.23.1. Method progressUpdated(com.artima.place.ProgressEvent)

public void progressUpdated(com.artima.place.ProgressEvent event)


Invoked when the progress of an activation has changed. Progress is reported as percent complete. Although users would expect that the percent complete reported would in general increase over time, the actual progress events need not report consecutive percentages, or even increasing percentages.

Parameters:

event - the ProgressEvent to handle

Throws:

NullPointerException - if passed event is null

13.24. Class com.artima.place.ServerAddress

public final class ServerAddress
     extends java.lang.Object
     implements java.io.Serializable


Holds a String host name and int port number. The host name must be in either quad or domain name form.

ServerAddress is not clonable because its immutable.

13.24.1. Constructor ServerAddress(java.lang.String, int)

public ServerAddress(java.lang.String host, int port)


Constructs a ServerAddress with passed String host name and int port number. The server host name should be in quad or domain name form, acceptable to the isValidHost method of this class.

Parameters:

host - a server host name in quad or domain name form

port - a server port number

Throws:

NullPointerException - if the host reference passed to this constructor is null

IllegalArgumentException - if the port passed to this constructor is less than zero or greater than 65,535, or if the host is not a well-formed host name in quad or domain name form

13.24.2. Method getHost()

public java.lang.String getHost()


Returns the String host name that's stored in this ServerAddress.

13.24.3. Method getPort()

public int getPort()


Returns the int port number that's stored in this ServerAddress.

13.24.4. Method equals(java.lang.Object)

public boolean equals(java.lang.Object o)


Compares the specified Object with this ServerAddress for equality. Two ServerAddresss are semantically equal if their host names are semantically equal and their ports are equal.

Parameters:

o - the object to compare to this one.

13.24.5. Method hashCode()

public int hashCode()


Returns the hash code value for this ServerAddress.

13.24.6. Method isValidPort(int)

public static boolean isValidPort(int port)


Returns true if passed int is a valid port number. To be valid, the passed int must be greater than or equal to zero and less than or equal to 65535.

Parameters:

port - a server port number

13.24.7. Method isValidHost(java.lang.String)

public static boolean isValidHost(java.lang.String host)


Returns true if passed String is a valid host name. To be valid, the passed int must be either a valid IP address in quad form or a well-formed domain name. This method does not verify that any particular IP address or domain name exists or is reachable, just that the String is well-formed.

Parameters:

host - a server host name in quad or domain name form

13.25. Class com.artima.place.ServicePresenter

public abstract class ServicePresenter
     extends java.lang.Object


Contains a method that allows clients to request that the service host present a service to the user. The passed Link is activated by the host, so that the host can give the user feedback about the activation progress. The host can, for example, show an animation, status messages, progress bar, etc., during the activation of the Link.

13.25.1. Constructor ServicePresenter()

public ServicePresenter()


Construct a ServicePresenter.

13.25.2. Field DEFAULT_ACTIVATION_TIMEOUT

public static final DEFAULT_ACTIVATION_TIMEOUT


The default maximum activation time is 30 seconds. This value is expressed in milliseconds. This is the value that getMaxActivationTime will return if it is not explicitly set by the client via setMaxActivationTime.

13.25.3. Field DEFAULT_SINGLE_REQUEST_TIMEOUT

public static final DEFAULT_SINGLE_REQUEST_TIMEOUT


The default network request timeout is 20 seconds. This value is expressed in milliseconds. This is the value that getNetworkRequestTimeout will return if it is not explicitly set by the client via setNetworkRequestTimeout.

13.25.4. Method setLatencyTimeouts(int, int)

public static void setLatencyTimeouts(int singleRequestTimeout, int activationTimeout)


Sets the two recommended latency timeouts: the single request timeout and the activation timeout.

Link activations may use the single request timeout in deciding when to stop attempting to contact a particular server on the network. This value may be used, for example, if the link has several alternative servers that would yield the same service. If one is down (hasn't been reached within the single request timeout), the link could give up on that server and try the next in line. Link activations are not in any way required to use this value.

Link activations may use the activation timeout in deciding when to declare that an activation has failed due to no or slow response on the network. Link activations are not in any way required to use this value.

Parameters:

singleRequestTimeout - the recommended single request timeout, expressed in milliseconds

activationTimeout - the recommended activation timeout, expressed in milliseconds

Throws:

IllegalArgumentException - if either of passed activationTimeout or singleRequestTimeout is less than or equal to zero, or if singleRequestTimeout is greater than activationTimeout

13.25.5. Method getActivationTimeout()

public static int getActivationTimeout()


Returns the recommended activation timeout. Link activations may use this value in deciding when to declare that an activation has failed due to no or slow response on the network. Service presenters may dynamically adjust this value via the setLatencyTimeouts method to reflect user preferences and observed network latency. Link activations are not in any way required to use this value.

13.25.6. Method getSingleRequestTimeout()

public static int getSingleRequestTimeout()


Returns the recommended single request timeout. Link activations may use this value in deciding when to stop attempting to contact a particular server on the network. This value may be used, for example, if the link has several alternative servers that would yield the same service. If one is down (hasn't been reached within the single request timeout), the link could give up on that server and try the next in line. Link activations are not in any way required to use this value.

13.25.7. Method presentService(com.artima.place.Link)

public abstract void presentService(com.artima.place.Link link)


Presents a service to a user. This method will return promptly. If the method needs to do something on the network, which it often will, that something will need to be done in a different thread. This means that a GUI event handler thread should be able to safely invoke this method directly without fear that doing so will "hang" their UI.

Parameters:

link - the Link that, when activated, will produce a service to present to the user.

13.25.8. Method getDefault()

public static com.artima.place.ServicePresenter getDefault()


Gets the default ServicePresenter object.

13.26. Class com.artima.place.UnicastDiscoveryLink

public final class UnicastDiscoveryLink
     extends java.lang.Object
     implements com.artima.place.Link


Represents a unicast discovery-based link to a Jini service on the network. Clients may specify one to many host and port locations at which this link will attempt unicast discovery.

If multiple server addresses are specified when constructing the UnicastDiscoveryLink, the UnicastDiscoveryLink may when activated attempt unicast discovery of multiple lookup services. If the specified approach is either ORDERED_SEQUENTIAL or RANDOM_SEQUENTIAL, then multiple attempts will occur sequentially, via LookupLocator objects. If the specified approach is ORDERED_SEQUENTIAL, this object will attempt to contact lookup services in the order they appear in the passed ServerAddress array. If the specified approach is RANDOM_SEQUENTIAL, this object will attempt to contact lookup services in a random order selected each time the link is activated. When an attempt at unicast discovery fails or times out, the activation will attempt to contact the next server address on the list. The first successful discovery that, upon lookup with the specified ServiceTemplate, yields a match causes the link activation to successfully terminate. By randomizing the list of server addresses at which to attempt unicast discovery, this link can help achieve a kind of load balancing.

If multiple server addresses are specified with an approach of CONCURRENTLY, then when this link is activated it will use a LookupLocatorDiscovery object to concurrently attempt to contact via unicast discovery all the specified server addresses. The first successful discovery that, upon lookup with the specified ServiceTemplate, yields a match causes the link activation to successfully terminate.

13.26.1. Constructor UnicastDiscoveryLink(com.artima.place.URLString, net.jini.core.lookup.ServiceTemplate)

public UnicastDiscoveryLink(com.artima.place.URLString url, net.jini.core.lookup.ServiceTemplate template)
     throws java.io.IOException, java.lang.ClassNotFoundException


Construct a UnicastDiscoveryLink with a URLString and ServiceTemplate. The URL must be a jini: URL that identifies a Jini lookup service, with the form jini://host/ or jini://host:port/.

Parameters:

url - the URL at which this link will perform unicast discovery when activated

template - the ServiceTemplate with which to peform lookups when this link is activated

Throws:

NullPointerException - if either of passed url or template references are null

IllegalArgumentException - if the passed url is not a valid jini: URL

IOException - if an I/O error occurs when attempting to serialize or deserialize the ServiceTemplate.

ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

13.26.2. Constructor UnicastDiscoveryLink(com.artima.place.URLString[], net.jini.core.lookup.ServiceTemplate, int)

public UnicastDiscoveryLink(com.artima.place.URLString[] urls, net.jini.core.lookup.ServiceTemplate template, int approach)
     throws java.io.IOException, java.lang.ClassNotFoundException


Construct a UnicastDiscoveryLink with an array of URLStrings and a ServiceTemplate. Each URL must be a jini: URL that identifies a Jini lookup service, with the form jini://host/ or jini://host:port/.

Parameters:

urls - the URLs at which this link will perform unicast discovery when activated

template - the ServiceTemplate with which to peform lookups when this link is activated

approach - the approach (either ORDERED_SEQUENTIAL, RANDOM_SEQUENTIAL, or CONCURRENTLY) to use when contacting lookup services when this link is activated.

Throws:

NullPointerException - if either of passed urls or template references are null

IllegalArgumentException - if the passed urls is a zero length array or contains any URLs that aren't valid jini: URL, or if the int passed as approach isn't one of ORDERED_SEQUENTIAL, RANDOM_SEQUENTIAL, or CONCURRENTLY.

IOException - if an I/O error occurs when attempting to serialize or deserialize the ServiceTemplate.

ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

13.26.3. Constructor UnicastDiscoveryLink(java.lang.String, net.jini.core.lookup.ServiceTemplate)

public UnicastDiscoveryLink(java.lang.String host, net.jini.core.lookup.ServiceTemplate template)
     throws java.io.IOException, java.lang.ClassNotFoundException


Construct a UnicastDiscoveryLink with a host String and ServiceTemplate. This object's activate method will perform unicast discovery at the default port (4160) of the passed host, and perform a query on the resulting lookup service using the passed ServiceTemplate.

Parameters:

host - the host at which to perform unicast discovery at the default port when this link is activated.

template - the ServiceTemplate with which to peform lookups when this link is activated

Throws:

NullPointerException - if either of passed host or template references are null

IllegalArgumentException - if the passed host is not a valid host name, as determined by the isValidHost method of class ServerAddress

IOException - if an I/O error occurs when attempting to serialize or deserialize the ServiceTemplate.

ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

13.26.4. Constructor UnicastDiscoveryLink(com.artima.place.ServerAddress, net.jini.core.lookup.ServiceTemplate)

public UnicastDiscoveryLink(com.artima.place.ServerAddress serverAddress, net.jini.core.lookup.ServiceTemplate template)
     throws java.io.IOException, java.lang.ClassNotFoundException


Construct a UnicastDiscoveryLink with a ServerAddress and ServiceTemplate. This object's activate method will perform unicast discovery at the host and port specified by the passed ServerAddress, and perform a query on the resulting lookup service using the passed ServiceTemplate.

Parameters:

serverAddress - the server address (host and port) at which to perform unicast discovery when this link is activated.

template - the ServiceTemplate with which to peform lookups when this link is activated

Throws:

NullPointerException - if either of passed serverAddress ortemplate references are null

IllegalArgumentException - if the passed host is not a valid host name, as determined by the isValidHost method of class ServerAddress

IOException - if an I/O error occurs when attempting to serialize or deserialize the ServiceTemplate.

ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

13.26.5. Constructor UnicastDiscoveryLink(com.artima.place.ServerAddress[], net.jini.core.lookup.ServiceTemplate, int)

public UnicastDiscoveryLink(com.artima.place.ServerAddress[] serverAddresses, net.jini.core.lookup.ServiceTemplate template, int approach)
     throws java.io.IOException, java.lang.ClassNotFoundException


Construct a UnicastDiscoveryLink with an array of ServerAddress objects and a ServiceTemplate.

This object's activate method will attempt to perform unicast discovery at each host and port specified in the passed ServerAddress array, in order of appearance in the array. The activate method will perform a query on the each resulting lookup service using the passed ServiceTemplate. The first match that is found will be passed to the ActivationClient. If multiple matches are found, a random match will be returned. If a lookup service is not able to be contacted within a timeout determined by this class, the next ServerAddress on the list will be tried. Only after all ServerAddresses have either yielded no match when the query was performed, or were not contactable within the timeout, will the activate method notify the ActivationClient that the activation failed.

Parameters:

serverAddress - the server addresses (hosts and ports) at which to perform unicast discovery when this link is activated.

template - the ServiceTemplate with which to peform lookups when this link is activated

approach - the approach (either ORDERED_SEQUENTIAL, RANDOM_SEQUENTIAL, or CONCURRENTLY) to use when contacting lookup services when this link is activated.

Throws:

NullPointerException - if either of passed serverAddresses or template references are null

IllegalArgumentException - if the passed serverAddresses array is empty, or if the int passed as approach isn't one of ORDERED_SEQUENTIAL, RANDOM_SEQUENTIAL, or CONCURRENTLY.

IOException - if an I/O error occurs when attempting to serialize or deserialize the ServiceTemplate.

ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

13.26.6. Field DEFAULT_JINI_PORT

public static final DEFAULT_JINI_PORT


13.26.7. Field ORDERED_SEQUENTIAL

public static final ORDERED_SEQUENTIAL


Constant that when passed to certain constructors indicates that LookupLocators for a list of ServerAddresses will be tried sequentially in the order they appear in the list.

13.26.8. Field RANDOM_SEQUENTIAL

public static final RANDOM_SEQUENTIAL


Constant that when passed to certain constructors indicates that LookupLocators for a list of ServerAddresses will be tried sequentially in a random order chosen each time the link is activated.

13.26.9. Field CONCURRENTLY

public static final CONCURRENTLY


Constant that when passed to certain constructors indicates that a LookupLocatorDiscovery object will be used to concurrently attempt to contact all ServerAddresses in the passed list.

13.26.10. Method activate(com.artima.place.ActivationClient)

public com.artima.place.LinkActivation activate(com.artima.place.ActivationClient al)


Activate this link by attempting unicast discovery of lookup services identified in the ServerAddresses array using the specified approach, ultimately performing lookups at discovered lookup services with the specified ServiceTemplate. The activate method will return promptly, returning a LinkActivation object that enables the client to abort the activation. Invoking activate again while an activation is currently in progress just starts a new activation independent of the already running one.

Parameters:

al - the ActivationClient that will be notified when this link activation completes.

Throws:

NullPointerException - if passed al is null.

13.26.11. Method getServerAddresses()

public com.artima.place.ServerAddress[] getServerAddresses()


Returns the array of ServerAddress objects which determine the hosts and ports at which unicast discovery will be attempted by this link's activate method.

13.26.12. Method getServiceTemplate()

public net.jini.core.lookup.ServiceTemplate getServiceTemplate()
     throws java.io.IOException, java.lang.ClassNotFoundException


Returns the ServiceTemplate with which lookups will be performed by this UnicastDiscoveryLink.

Throws:

IOException - if an I/O error occurs when attempting to serialize or deserialize the ServiceTemplate.

ClassNotFoundException - if a class can't be found when attempting deserialize the duplicate ServiceTemplate.

13.26.13. Method getApproach()

public int getApproach()


Returns the approach used by this UnicastDiscoveryLink, which will be one of ORDERED_SEQUENTIAL, RANDOM_SEQUENTIAL, or CONCURRENTLY.

13.27. Class com.artima.place.URLFactory

public final class URLFactory
     extends java.lang.Object
     implements java.io.Serializable, com.artima.place.Presentable


Jini service that produces a URL or array of URLs. This service can be used to wrap existing file-based resources in a network mobile service object. An appropriate service UI can then be used to present the file to a user.

If this service produces an array of URLs, each URL must represent a different way to access the same resource. If a network partition, crashed server, or some other problem prevents the first URL from being successfully used, the second URL can be tried. If that one doesn't work, the third can be tried, and so on.

13.27.1. Constructor URLFactory(com.artima.place.URLString)

public URLFactory(com.artima.place.URLString url)


Creates a URLFactory with passed String URL.

Parameters:

url - the URL to be contained in this URLFactory

Throws:

NullPointerException - if passed url reference is null

13.27.2. Constructor URLFactory(com.artima.place.URLString[])

public URLFactory(com.artima.place.URLString[] urls)


Construct a URLFactory with an array of URLStrings.

Parameters:

urls - the URLs to be contained in this URLFactory

Throws:

NullPointerException - if passed urls array is null

IllegalArgumentException - if passed urls array is empty

13.27.3. Method getURL()

public com.artima.place.URLString getURL()


Returns the first URLString in the list of URLStrings contained in this URLFactory.

13.27.4. Method getURLs()

public com.artima.place.URLString[] getURLs()


Returns an array containing in order the URLStrings contained in this URLFactory.

13.27.5. Method getURLsAsList()

public java.util.List getURLsAsList()


Returns a List of the URLStrings. Returns a List containing in order the URLStrings contained in this URLFactory.

13.27.6. Method getLength()

public int getLength()


Returns the number of URLs contained in this URLFactory.

13.27.7. Method getServicePresenter()

public com.artima.place.ServicePresenter getServicePresenter()


Gets the ServicePresenter for this Presentable service. This method will return the object passed to the setServicePresenter method in its most recent invocation. If the setServicePresenter method has not yet been invoked, this method will return the default ServicePresenter returned by the ServicePresenter.getDefault method.

This method could be called by a service or client UI for a Presentable service, when the UI detects that the user wishes to activate a link. The UI can delegate the actual activation activation of that link to the ServicePresenter returned by this method.

13.27.8. Method setServicePresenter(com.artima.place.ServicePresenter)

public void setServicePresenter(com.artima.place.ServicePresenter servicePresenter)


Sets the ServicePresenter. This method would usually be invoked by the client to pass in a the service presenter context object to the Presentable service, before attaching a service or client UI.

Parameters:

presenter - the ServicePresenter to which this service may wish to delegate link activations

13.28. Class com.artima.place.URLLink

public final class URLLink
     extends java.lang.Object
     implements com.artima.place.Link


Represents a URL-based link to a service on the network.

13.28.1. Constructor URLLink(com.artima.place.URLString)

public URLLink(com.artima.place.URLString url)


Construct a URLLink with a URLString.

Parameters:

url - the URL to be contained in the URLFactory produced when this link is activated.

Throws:

NullPointerException - if passed url reference is null

13.28.2. Constructor URLLink(com.artima.place.URLString[])

public URLLink(com.artima.place.URLString[] urls)


Construct a URLLink with an array of URLStrings.

Parameters:

urls - the URLs, in order, to be contained in the URLFactory produced when this link is activated.

Throws:

NullPointerException - if passed urls array is null

IllegalArgumentException - if passed urls array is empty

13.28.3. Method activate(com.artima.place.ActivationClient)

public com.artima.place.LinkActivation activate(com.artima.place.ActivationClient client)


Invokes activationSucceeded() on the passed ActivationClient, passing to activationSucceeded() a ServiceItem that contains a URLFactory service and null references for the ServiceID and attributes set (the Entry array).

Parameters:

client - the ActivationClient that will notified when this link activation completes

Throws:

NullPointerException - if passed client is null

13.29. Class com.artima.place.URLString

public final class URLString
     extends java.lang.Object
     implements java.io.Serializable


Holds a valid URL String.

This is not clonable because its immutable.

13.29.1. Constructor URLString(java.lang.String)

public URLString(java.lang.String url)
     throws java.net.MalformedURLException


Constructs a URLString with passed String URL.

Parameters:

url - The String URL to hold in this URLString

Throws:

NullPointerException - if the URL String reference passed to this constructor is null

MalformedURLException - if the String passed to this constructor is does not have the form of a valid URL.

13.29.2. Method toString()

public java.lang.String toString()


Returns the String URL that's stored in this URLString.

13.29.3. Method getProtocol()

public java.lang.String getProtocol()


Returns the protocol portion of the URL.

13.29.4. Method getHost()

public java.lang.String getHost()


Returns the host portion of the URL.

13.29.5. Method getPort()

public int getPort()


Returns the port portion of the URL.

13.29.6. Method getFile()

public java.lang.String getFile()


Returns the file portion of the URL.

13.29.7. Method getRef()

public java.lang.String getRef()


Returns the reference portion of the URL.

13.29.8. Method equals(java.lang.Object)

public boolean equals(java.lang.Object o)


Compares the specified Object with this URLString for equality. Two URLStrings are semantically equal if their String URLs have the same value.

Parameters:

o - the object to compare to this one.

13.29.9. Method hashCode()

public int hashCode()


Returns the hash code value for this URLString. The hashcode for a URLString is the hashcode for the URLString's constituent String URL.

14. Package com.artima.place.info

Provides classes and interfaces that support localization across a network. The full specification of this package is available at:

http://www.artima.com/jini/cyberspace/Spec.html

14.1. Summary of Interfaces In Package com.artima.place.info

• Informative - A Jini service interface implemented by service proxies that can produce a bundle of localizable information about the service.
• Purgable - Interface implemented by classes that can purge away localizable information for undesired locales, keeping only information about a desired locale, which is the only locale preserved when one of the purge methods is invoked.

14.2. Summary of Classes In Package com.artima.place.info

• Description - A localizable description.
• Icons - A set of localizable icons.
• InfoBundle - A bundle of localizable information objects.
• Keywords - A bundle of localizable keywords.
• LocalizableInfo - A bundle of localizable information suitable for delivery across a network.
• ModificationDate - An info object that represents a last modified date.
• Name - A localizable name.
• ResourceBundleLoader - A class that takes care of loading resources from a codebase that is selected based on best-fit locale.

14.3. Summary of Exceptions In Package com.artima.place.info

No Exceptions are declared in package com.artima.place.info.

14.4. Summary of Errors In Package com.artima.place.info

No Errorss are declared in package com.artima.place.info.

14.5. Class com.artima.place.info.Description

public class Description
     extends com.artima.place.info.LocalizableInfo


A localizable description.

14.5.1. Constructor Description(com.artima.place.info.ResourceBundleLoader, java.lang.String)

public Description(com.artima.place.info.ResourceBundleLoader loader, java.lang.String descriptionKey)


Constructs a new Description with passed resource bundle loader, description key, and no cached description.

Parameters:

loader - the ResourceBundleLoader which can load ResourceBundles for this Description.

descriptionKey - the String key with which the String resource can be retrieved from a ResourceBundle provided by the ResourceBundleLoader

14.5.2. Constructor Description(com.artima.place.info.ResourceBundleLoader, java.lang.String, java.util.Locale, java.lang.String)

public Description(com.artima.place.info.ResourceBundleLoader loader, java.lang.String descriptionKey, java.util.Locale cachedLocale, java.lang.String cachedDescription)


Constructs a new Description with passed resource bundle loader, description key, and cached description (for the passed locale).

Parameters:

loader - the ResourceBundleLoader which can load ResourceBundles for this Description.

descriptionKey - the String key with which the String resource can be retrieved from a ResourceBundle provided by the ResourceBundleLoader

cachedLocale - the Locale of the description passed as cachedDescription.

cachedDescription - the description whose locale is passed as cachedLocale that should be cached by this Description.

14.5.3. Constructor Description(java.util.Locale, java.lang.String)

public Description(java.util.Locale cachedLocale, java.lang.String cachedDescription)


Constructs a new Description with passed cached description for the passed locale, and no name key resource bundle loader. (Because this Description info object contains no resource bundle loader, it also requires no key with which to look up a description resource in a resource bundle.

Parameters:

cachedLocale - the Locale of the description passed as cachedDescription.

cachedDescription - the description, whose locale is passed as cachedLocale that should be cached by this Description.

14.5.4. Method getDescription()

public java.lang.String getDescription()


Returns a String description, suitable for presentation to users, appropriate to the default locale.

Throws:

MissingResourceException - if a codebase URL is found to be unusable. (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase

14.5.5. Method getDescription(java.util.Locale)

public java.lang.String getDescription(java.util.Locale desiredLocale)


Returns a String description, suitable for presentation to users, which represents the best-fit description for the specified locale.

Parameters:

desiredLocale - the locale for which an appropriate description is desired.

Throws:

MissingResourceException - if a codebase URL is found to be unusable. (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase

14.5.6. Method purge()

public void purge()


Purge away information about undesired locales. If no cache exists, this method first fills the cache based on the default locale. If a cache currently exists, that cache will be left intact. Once a cache is in place, this method will clear the resource bundle loader.

14.5.7. Method purge(java.util.Locale)

public void purge(java.util.Locale preserveLocale)


Purge away information about all locales except the passed locale. This method first makes sure the cache is appropriate to the passed desired locale. Once the cache is in place, this method will clear the resource bundle loader.

Parameters:

preserveLocale - a locale to preserve in this Description.

14.5.8. Method equals(java.lang.Object)

public boolean equals(java.lang.Object o)


Compares this Description to the passed object for equality. To be semantically equal, the class of the passed object must be Description, the passed object's cached description must be semantically equal to this object's cached description, the passed object's description key must be semantically to this object's description key, and the equals method of Description's superclass must return true.

Parameters:

An - object to compare to this Description

14.5.9. Method hashCode()

public int hashCode()


Returns a hash code for this object.

14.5.10. Method clone()

public java.lang.Object clone()


Clones this Name.

14.6. Class com.artima.place.info.Icons

public class Icons
     extends com.artima.place.info.LocalizableInfo


A set of localizable icons.

The icon images must be arrays of bytes in a resource bundle, with names composed of the iconKey passed to a constructor of this class plus one of the following four suffixes, which are for convenience defined as constants in this class:

• "Color16", defined as SUFFIX_COLOR_16x16
• "Color32", defined as SUFFIX_COLOR_32x32
• "Mono16", defined as SUFFIX_MONO_16x16
• "Mono32", defined as SUFFIX_MONO_32x32

For example, if an Icons object is constructed with an iconKey of "calcIcon", the color 16 by 16 pixel icon byte array should be named "calcIconColor16" in the resource bundle.

14.6.1. Constructor Icons(com.artima.place.info.ResourceBundleLoader, java.lang.String)

public Icons(com.artima.place.info.ResourceBundleLoader loader, java.lang.String iconKey)


Constructs a new Icons with passed resource bundle loader, icon key, and no cached icon images.

Parameters:

loader - the ResourceBundleLoader which can load ResourceBundles for this Icons.

iconKey - a String that forms the base of the String keys with which the byte[] resource can be retrieved from a ResourceBundle provided by the ResourceBundleLoader

14.6.2. Constructor Icons(com.artima.place.info.ResourceBundleLoader, java.lang.String, java.util.Locale, byte[], byte[], byte[], byte[])

public Icons(com.artima.place.info.ResourceBundleLoader loader, java.lang.String iconKey, java.util.Locale cachedLocale, byte[] cachedColor16Icon, byte[] cachedColor32Icon, byte[] cachedMono16Icon, byte[] cachedMono32Icon)


Constructs a new Icons with passed resource bundle loader, icon key, and cached icon images (for the passed locale).

Parameters:

loader - the ResourceBundleLoader which can load ResourceBundles for this Icons.

iconKey - a String that forms the base of the String keys with which the byte[] resource can be retrieved from a ResourceBundle provided by the ResourceBundleLoader

cachedLocale - the Locale of the icons passed as cachedColor16Icon, cachedColor32Icon, cachedMono16Icon, and cachedMono32Icon.

cachedColor16Icon - the 16x16 color icon, whose locale is passed as cachedLocale, that should be cached by this Icons.

cachedColor32Icon - the 32x32 color icon, whose locale is passed as cachedLocale, that should be cached by this Icons.

cachedMono16Icon - the 16x16 monochrome icon, whose locale is passed as cachedLocale, that should be cached by this Icons.

cachedMono32Icon - the 32x32 monochrome icon, whose locale is passed as cachedLocale, that should be cached by this Icons.

14.6.3. Constructor Icons(java.util.Locale, byte[], byte[], byte[], byte[])

public Icons(java.util.Locale cachedLocale, byte[] cachedColor16Icon, byte[] cachedColor32Icon, byte[] cachedMono16Icon, byte[] cachedMono32Icon)


Constructs a new Icons with passed cached icon images for the passed locale, and no icon key or resource bundle loader. (Because this Icons info object contains no resource bundle loader, it also requires no icon key with which to look up an icon resource in a resource bundle.

Parameters:

cachedLocale - the Locale of the icons passed as cachedColor16Icon, cachedColor32Icon, cachedMono16Icon, and cachedMono32Icon.

cachedColor16Icon - the 16x16 color icon, whose locale is passed as cachedLocale, that should be cached by this Icons.

cachedColor32Icon - the 32x32 color icon, whose locale is passed as cachedLocale, that should be cached by this Icons.

cachedMono16Icon - the 16x16 monochrome icon, whose locale is passed as cachedLocale, that should be cached by this Icons.

cachedMono32Icon - the 32x32 monochrome icon, whose locale is passed as cachedLocale, that should be cached by this Icons.

14.6.4. Field ICON_COLOR_16x16

public static final ICON_COLOR_16x16


Constant to indicate a 16 x 16 color icon. (Same value as java.beans.BeanInfo.ICON_COLOR_16x16.)

14.6.5. Field ICON_COLOR_32x32

public static final ICON_COLOR_32x32


Constant to indicate a 32 x 32 color icon. (Same value as java.beans.BeanInfo.ICON_COLOR_32x32.)

14.6.6. Field ICON_MONO_16x16

public static final ICON_MONO_16x16


Constant to indicate a 16 x 16 monochrome icon. (Same value as java.beans.BeanInfo.ICON_MONO_16x16.)

14.6.7. Field ICON_MONO_32x32

public static final ICON_MONO_32x32


Constant to indicate a 32 x 32 monochrome icon. (Same value as java.beans.BeanInfo.ICON_MONO_32x32.)

14.6.8. Field SUFFIX_COLOR_16x16

public static final SUFFIX_COLOR_16x16


Convenience constant for the suffix applied to the icon key passed to a constructor of this class to form the actual key passed to a resource bundle to retrieve a 16 by 16 color icon.

14.6.9. Field SUFFIX_COLOR_32x32

public static final SUFFIX_COLOR_32x32


Convenience constant for the suffix applied to the icon key passed to a constructor of this class to form the actual key passed to a resource bundle to retrieve a 32 by 32 color icon.

14.6.10. Field SUFFIX_MONO_16x16

public static final SUFFIX_MONO_16x16


Convenience constant for the suffix applied to the icon key passed to a constructor of this class to form the actual key passed to a resource bundle to retrieve a 16 by 16 monochrome icon.

14.6.11. Field SUFFIX_MONO_32x32

public static final SUFFIX_MONO_32x32


Convenience constant for the suffix applied to the icon key passed to a constructor of this class to form the actual key passed to a resource bundle to retrieve a 32 by 32 monochrome icon.

14.6.12. Method getIcon(int)

public byte[] getIcon(int iconKind)


Gets a URL for the image file of an icon for this resource, suitable for presentation to users, under the current locale. (The image file is likely either a GIF or JPG file, but could be any image file format.) The valid parameter values are the same as for the getIcon method of java.beans.BeanInfo, which for convenience are also declared in this interface: ICON_COLOR_16x16, ICON_COLOR_32x32, ICON_MONO_16x16, ICON_MONO_32x32.

Parameters:

iconKind - the kind of icon to be returned (one of ICON_COLOR_16x16, ICON_COLOR_32x32, ICON_MONO_16x16, or ICON_MONO_32x32).

Throws:

MissingResourceException - if the icon image can't be retrieved successfully

14.6.13. Method getIcon(int, java.util.Locale)

public byte[] getIcon(int iconKind, java.util.Locale desiredLocale)


Gets a URL for the image file of an icon for this resource, suitable for presentation to users, under the passed locale. (The image file is likely either a GIF or JPG file, but could be any image file format.) The valid parameter values are the same as for the getIcon method of java.beans.BeanInfo, which for convenience are also declared in this interface: ICON_COLOR_16x16, ICON_COLOR_32x32, ICON_MONO_16x16, ICON_MONO_32x32.

Parameters:

iconKind - the kind of icon to be returned (one of ICON_COLOR_16x16, ICON_COLOR_32x32, ICON_MONO_16x16, or ICON_MONO_32x32).

desiredLocale - the locale for which an appropriate icon is desired.

Throws:

MissingResourceException - if the icon image can't be retrieved successfully

14.6.14. Method purge()

public void purge()


Purge away information about undesired locales. If no cache exists, this method first fills the cache based on the default locale. If a cache currently exists, that cache will be left intact. Once a cache is in place, this method will clear the resource bundle loader.

14.6.15. Method purge(java.util.Locale)

public void purge(java.util.Locale preserveLocale)


Purge away information about all locales except the passed desired locale. This method first makes sure the cache is appropriate to the passed desired locale. Once the cache is in place, this method will clear the resource bundle loader.

Parameters:

preserveLocale - a locale to preserve in this Icons.

14.6.16. Method equals(java.lang.Object)

public boolean equals(java.lang.Object o)


Compares this Icons to the passed object for equality. To be semantically equal, the class of the passed object must be Icons, the passed object's cached icon images must be semantically equal to this object's cached icon images, the passed object's icon key must be semantically to this object's icon key, and the equals method of Icons's superclass must return true.

Parameters:

an - object to compare to this Icons.

14.6.17. Method hashCode()

public int hashCode()


Returns a hash code for this object.

14.6.18. Method clone()

public java.lang.Object clone()


Clones this Icons.

14.7. Class com.artima.place.info.InfoBundle

public class InfoBundle
     extends java.lang.Object
     implements java.lang.Cloneable, java.io.Serializable, com.artima.place.info.Purgable


A bundle of localizable information objects.

14.7.1. Constructor InfoBundle(java.util.Set)

public InfoBundle(java.util.Set infoSet)


Constructs a new InfoBundle with passed info object set.

The passed Set will not be used as part of the state of this newly constructed object. Rather its contents will be used to initialize an unmodifiable Set that will be returned by getInfoSet.

Parameters:

infoSet - a Set (which may be empty) of info objects

14.7.2. Method getInfoSet()

public java.util.Set getInfoSet()


Returns a Set of info objects which provide localizable information suitable for presentation to users.

14.7.3. Method purge()

public void purge()


Purge away information about undesired locales. This method merely invokes purge() on each Purgable object in its info set.

14.7.4. Method purge(java.util.Locale)

public void purge(java.util.Locale preserveLocale)


Purge away information about all locales except the passed desired locale. This method merely invokes purge(Locale) on each Purgable object in its info set, passing to purge(Locale) the desiredLocale passed to this method.

Parameters:

preserveLocale - a locale to preserve in this InfoBundle.

14.7.5. Method equals(java.lang.Object)

public boolean equals(java.lang.Object o)


Compares this InfoBundle to the passed object for equality. To be semantically equal, the class of the passed object must be InfoBundle and the passed object's info set must be semantically to this object's info set.

Parameters:

An - object to compare to this InfoBundle

14.7.6. Method hashCode()

public int hashCode()


Returns a hash code for this object.

14.7.7. Method clone()

public java.lang.Object clone()


Clones this InfoBundle. This method performs a shallow copy of the contained info set.

14.8. Interface com.artima.place.info.Informative

public interface Informative


A Jini service interface implemented by service proxies that can produce a bundle of localizable information about the service.

14.8.1. Method getInfoBundle()

public com.artima.place.info.InfoBundle getInfoBundle()
     throws java.rmi.RemoteException


Returns a bundle of localizable information about this service.

Throws:

RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

14.9. Class com.artima.place.info.Keywords

public class Keywords
     extends com.artima.place.info.LocalizableInfo


A bundle of localizable keywords. This information could, for example, be used by search engines spiders when adding this resource to their database.

14.9.1. Constructor Keywords(com.artima.place.info.ResourceBundleLoader, java.lang.String)

public Keywords(com.artima.place.info.ResourceBundleLoader loader, java.lang.String keywordsKey)


Constructs a new Keywords with passed resource bundle loader, keywords key, and no cached keywords.

Parameters:

loader - the ResourceBundleLoader which can load ResourceBundles for this Keywords.

keywordsKey - the String key with which the String resource can be retrieved from a ResourceBundle provided by the ResourceBundleLoader

14.9.2. Constructor Keywords(com.artima.place.info.ResourceBundleLoader, java.lang.String, java.util.Locale, java.util.Set)

public Keywords(com.artima.place.info.ResourceBundleLoader loader, java.lang.String keywordsKey, java.util.Locale cachedLocale, java.util.Set cachedKeywords)


Constructs a new Keywords with passed resource bundle loader, keywords key, and cached keywords (for the passed locale).

The passed Set will not be used as part of the state of this newly constructed object. Rather its contents will be used to initialize an unmodifiable Set which will be returned by getKeywords when the locale passed in cachedLocale is requested.

Parameters:

loader - the ResourceBundleLoader which can load ResourceBundles for this Keywords.

cachedKeywords - a set of keywords that will be stored as part of the state of this object, representing the root locale.

keywordsKey - the String key with which the String resource can be retrieved from a ResourceBundle provided by the ResourceBundleLoader

cachedLocale - the Locale of the description passed as cachedKeywords.

cachedKeywords - the description, whose locale is passed as cachedLocale that should be cached by this Keywords.

14.9.3. Constructor Keywords(java.util.Locale, java.util.Set)

public Keywords(java.util.Locale cachedLocale, java.util.Set cachedKeywords)


Constructs a new Keywords with passed cached keywords for the passed locale, and no keywords key and resource bundle loader. (Because this Keywords info object contains no resource bundle loader, it also requires no key with which to look up a keywords resource in a resource bundle.

The passed Set will not be used as part of the state of this newly constructed object. Rather its contents will be used to initialize an unmodifiable Set which will be returned by getKeywords when the locale passed in cachedLocale is requested.

Parameters:

cachedLocale - the Locale of the description passed as cachedKeywords.

cachedKeywords - the keywords, whose locale is passed as cachedLocale that should be cached by this Keywords.

14.9.4. Method getKeywords()

public java.util.SortedSet getKeywords()


Returns a SortedSet of keywords, suitable for presentation to users, appropriate to the default locale. These keywords can be used by search engines to index the resource.

Throws:

MissingResourceException - if a codebase URL is found to be unusable. (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase

14.9.5. Method getKeywords(java.util.Locale)

public java.util.SortedSet getKeywords(java.util.Locale desiredLocale)


Returns a SortedSet of keywords, suitable for presentation to users, which represents the best-fit name for the specified locale. These keywords can be used by search engines to index the resource.

Throws:

MissingResourceException - if a codebase URL is found to be unusable. (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase

14.9.6. Method purge()

public void purge()


Purge away information about undesired locales. If no cache exists, this method first fills the cache based on the default locale. If a cache currently exists, that cache will be left intact. Once a cache is in place, this method will clear the resource bundle loader.

14.9.7. Method purge(java.util.Locale)

public void purge(java.util.Locale preserveLocale)


Purge away information about all locales except the passed desired locale. This method first makes sure the cache is appropriate to the passed desired locale. Once the cache is in place, this method will clear the resource bundle loader.

Parameters:

preserveLocale - a locale to preserve in this Keywords.

14.9.8. Method equals(java.lang.Object)

public boolean equals(java.lang.Object o)


Compares this Keywords to the passed object for equality. To be semantically equal, the class of the passed object must be Keywords, the passed object's cached keywords must be semantically equal to this object's cached keywords, the passed object's keywords key must be semantically to this object's keywords key, and the equals method of Keywords' superclass must return true.

Parameters:

An - object to compare to this Keywords

14.9.9. Method hashCode()

public int hashCode()


Returns a hash code for this object.

14.9.10. Method clone()

public java.lang.Object clone()


Clones this Keywords.

14.10. Class com.artima.place.info.LocalizableInfo

public abstract class LocalizableInfo
     extends java.lang.Object
     implements java.lang.Cloneable, java.io.Serializable, com.artima.place.info.Purgable


A bundle of localizable information suitable for delivery across a network.

14.10.1. Constructor LocalizableInfo(com.artima.place.info.ResourceBundleLoader)

public LocalizableInfo(com.artima.place.info.ResourceBundleLoader loader)


Construct a LocalizableInfo with specified ResourceBundleLoader. Because ResourceBundleLoader is immutable, the passed loader may be used as part of the state of this object. The new LocalizableInfo object will start its life with no locales cache.

Parameters:

loader - the ResourceBundleLoader which can load ResourceBundles for this LocalizableInfo.

14.10.2. Constructor LocalizableInfo(java.util.Locale)

public LocalizableInfo(java.util.Locale cachedLocale)


Constructs a new LocalizableInfo with passed cached Locale and no ResourceBundleLoader.

Parameters:

cachedLocale - the Locale for which information will be cached by subclasses.

14.10.3. Constructor LocalizableInfo(com.artima.place.info.ResourceBundleLoader, java.util.Locale)

public LocalizableInfo(com.artima.place.info.ResourceBundleLoader loader, java.util.Locale cachedLocale)


Constructs a new CachableInfo with passed ResourceBundleLoader and cached Locale.

Parameters:

loader - the ResourceBundleLoader which can load ResourceBundles for this LocalizableInfo.

cachedLocale - the Locale for which information will be cached by subclasses.

14.10.4. Method setCachedLocale(java.util.Locale)

protected final void setCachedLocale(java.util.Locale cachedLocale)


Validates and sets the cached Locale to the passed Locale.

Parameters:

cachedLocale - the Locale for which information is cached by subclasses.

14.10.5. Method getResourceBundleLoader()

protected final com.artima.place.info.ResourceBundleLoader getResourceBundleLoader()


Gives subclasses a reference to the ResourceBundleLoader contained in this LocalizableInfo.

14.10.6. Method getCachedLocale()

public final java.util.Locale getCachedLocale()


Gets a reference to the cached Locale contained in this LocalizableInfo, if one exists.

14.10.7. Method getSupportedLocales()

public java.util.Set getSupportedLocales()


Returns an unmodifiable set of Locales which are directly supported by this LocalizableInfo. The returned set will definitely include the empty (or root) Locale.

14.10.8. Method getBestFitLocale()

public java.util.Locale getBestFitLocale()


Returns the best-fit locale for the default locale.

14.10.9. Method getBestFitLocale(java.util.Locale)

public java.util.Locale getBestFitLocale(java.util.Locale desiredLocale)


Returns the best-fit locale for the specified locale.

Parameters:

desiredLocale - the locale for which to determine a best-fit.

14.10.10. Method hasResourceBundleLoader()

public final boolean hasResourceBundleLoader()


Indicates whether or not this LocalizableInfo contains a ResourceBundleLoader. This LocalizableInfo will contain no ResourceBundleLoader if it was constructed with the constructor that takes only a cached Locale, or if its ResourceBundleLoader was cleared by the clearResourceBundleLoader method.

14.10.11. Method clearResourceBundleLoader()

public final void clearResourceBundleLoader()


Nulls out the reference to the ResourceBundleLoader contained in this LocalizableInfo, if any. This can be invoked by the purge methods of subclasses that keep a cache of the desired locale and wish to eliminate all record of the full localizable information contained in the ResourceBundleLoader.

If this LocalizableInfo contains no cached Locale, then this method will fail with an IllegalStateException. If no cached locale exists, then clearing the ResourceBundleLoader would eliminate all possibility of getting localized information from this LocalizableInfo. To avoid this exception, invoke this method only if the hasCachedLocale method returns true. In the absence of a cached Locale, the locales supported by the ResourceBundleLoader can be reduced by calling the stripResourceBundleLoader method.

If this LocalizableInfo already contains no ResourceBundleLoader, this method throws no exception and has no effect.

14.10.12. Method stripResourceBundleLoader(java.util.Set)

public final void stripResourceBundleLoader(java.util.Set preserveLocales)


Replaces the resource bundle with a new one that contains only the locales in the passed set. If the passed set does not contain the empty Locale, the empty locale from the current ResourceBundleLoader will be included in the stripped ResourceBundleLoader anyway. If the length of the passed set is zero, only the empty Locale will be contained in the stripped ResourceBundleLoader. All Locales contained in the passed Set must be directly supported by the ResourceBundleLoader, i.e., must be included in the Set returned by the getSupportedLocales method of the ResourceBundleLoader.

Parameters:

preserveLocales - a set of locales to preserve in the ResourceBundleLoader (all others will be removed).

Throws:

NullPointerException - if the ResourceBundleLoader contained in this LocalizableInfo has already been cleared, or if the passed Set reference is null

IllegalArgumentException - if any of the elements contained in the passed Set are not Locales, or if any of the Locales contained in the passed Set are not directly supported by the ResourceBundleLoader.

14.10.13. Method hasCachedLocale()

public final boolean hasCachedLocale()


Indicates whether or not this LocalizableInfo contains a cached Locale. This LocalizableInfo will contain no cached Locale if it was constructed with the constructor that takes only a ResourceBundleLoader and its cached Locale hasn't been installed via the setCachedLocale method, or if a cached Locale was cleared by the clearCachedLocale method.

14.10.14. Method clearCachedLocale()

public final void clearCachedLocale()


Nulls out the reference to the cached Locale contained in this LocalizableInfo, if any.

If this LocalizableInfo contains no ResourceBundleLoader, then this method will fail with an IllegalStateException. If no ResourceBundleLoader exists, then clearing the cached Locale would eliminate all possibility of getting localized information from this LocalizableInfo. To avoid this exception, invoke this method only if the hasResourceBundleLoader method returns true.

If this LocalizableInfo already contains no cached Locale, this method throws no exception and has no effect.

14.10.15. Method useCache(java.util.Locale)

protected boolean useCache(java.util.Locale desiredLocale)


Indicates whether or not the cached locale, if any exists, should be used given a desired locale. If this method returns false, then the resource or resources should be requested of the resource bundle loader rather than using the currently cached resources, if any.

Parameters:

desiredLocale - the desire locale against which to check for the appropriateness of the cached locale.

14.10.16. Method purge()

public abstract void purge()


Purge away information about undesired locales. Subclasses can decide how best to implement this method. Subclasses that use caches may eliminate the ResourceBundleLoader entirely by invoking clearResourceBundleLoader. Subclasses that do not use a cache may strip away undesired locales from the ResourceBundleLoader via the stripResourceBundleLoader method. Subclasses must assume the desired locale is the default locale.

In short, the contract of this method is: eliminate extraneous information about undesired locales, and keep only the ability to get at the desired locale, which is the current default locale.

14.10.17. Method purge(java.util.Locale)

public abstract void purge(java.util.Locale preserveLocale)


Purge away information about any locales other than the passed Locale. Subclasses can decide how best to implement this method. Subclasses that use caches may eliminate the ResourceBundleLoader entirely by invoking clearResourceBundleLoader. Subclasses that do not use a cache may strip away undesired locales from the ResourceBundleLoader via the stripResourceBundleLoader method.

In short, the contract of this method is: eliminate extraneous information about undesired locales, and keep only the ability to get at the desired locale, which is passed as a parameter to this method.

Parameters:

preserveLocale - a locale to preserve in the ResourceBundleLoader (all others will be removed).

14.10.18. Method equals(java.lang.Object)

public boolean equals(java.lang.Object o)


Compares this LocalizableInfo to the passed object for equality. To be semantically equal, the passed object must be an instanceof LocalizableInfo, both ResourceBundleLoaders must be either null or semantically equal, and both cached Locales must either be null or semantically equal.

Parameters:

An - object to compare to this LocalizableInfo

14.10.19. Method hashCode()

public int hashCode()


Returns a hash code for this object.

14.10.20. Method clone()

public java.lang.Object clone()
     throws java.lang.CloneNotSupportedException


Clones this LocalizableInfo. This method merely returns the reference returned by its superclass's clone method. This class's instance variable hold references to two objects, a ResourceBundleLoader and a cached Locale. Because ResourceBundleLoader and Locale objects are immutable, this method need not clone them in the process of cloning the LocalizableInfo. Although this class is not itself immutable, the only state changes it supports involve replacing the ResourceBundleLoader or the cached Locale. Since this method merely returns the result of Object's implementation of clone, its only real effect is to make clone public.

14.10.21. Method compareObjectsOrNull(java.lang.Object, java.lang.Object)

public static boolean compareObjectsOrNull(java.lang.Object o1, java.lang.Object o2)


Utility method that returns true only if the two passed objects references are both null, or the objects are semantically equal.

Parameters:

o1 - an object to compare to o2

o2 - an object to compare to o1

14.11. Class com.artima.place.info.ModificationDate

public class ModificationDate
     extends java.lang.Object
     implements java.lang.Cloneable, java.io.Serializable


An info object that represents a last modified date.

14.11.1. Constructor ModificationDate(java.util.Date)

public ModificationDate(java.util.Date modDate)


Constructs a ModificationDate with passed last modified Date.

Parameters:

modDate - the last modified date to store in this ModificationDate.

Throws:

NullPointerException - if passed modDate is null.

14.11.2. Method getModificationDate()

public java.util.Date getModificationDate()


Returns the modification date.

14.11.3. Method equals(java.lang.Object)

public boolean equals(java.lang.Object o)


Compares this ModificationDate to the passed object for equality. To be semantically equal, the class of the passed object must be ModificationDate and the passed object's modification date must be semantically equal to this object's modification date.

Parameters:

An - object to compare to this ModificationDate

14.11.4. Method hashCode()

public int hashCode()


Returns a hash code for this object.

14.11.5. Method clone()

public java.lang.Object clone()


Clones this ModificationDate.

14.12. Class com.artima.place.info.Name

public class Name
     extends com.artima.place.info.LocalizableInfo


A localizable name.

14.12.1. Constructor Name(com.artima.place.info.ResourceBundleLoader, java.lang.String)

public Name(com.artima.place.info.ResourceBundleLoader loader, java.lang.String nameKey)


Constructs a new Name with passed resource bundle loader, name key, and no cached name.

Parameters:

loader - the ResourceBundleLoader which can load ResourceBundles for this Name.

nameKey - the String key with which the String resource can be retrieved from a ResourceBundle provided by the ResourceBundleLoader

14.12.2. Constructor Name(com.artima.place.info.ResourceBundleLoader, java.lang.String, java.util.Locale, java.lang.String)

public Name(com.artima.place.info.ResourceBundleLoader loader, java.lang.String nameKey, java.util.Locale cachedLocale, java.lang.String cachedName)


Constructs a new Name with passed resource bundle loader, name key, and cached name (for the passed locale).

Parameters:

loader - the ResourceBundleLoader which can load ResourceBundles for this Name.

nameKey - the String key with which the String resource can be retrieved from a ResourceBundle provided by the ResourceBundleLoader

cachedLocale - the Locale of the name passed as cachedName.

cachedName - the name whose locale is passed as cachedLocale that should be cached by this Name.

14.12.3. Constructor Name(java.util.Locale, java.lang.String)

public Name(java.util.Locale cachedLocale, java.lang.String cachedName)


Constructs a new Name with passed cached name for the passed locale, and no name key and resource bundle loader. (Because this Name info object contains no resource bundle loader, it also requires no key with which to look up a name resource in a resource bundle.

Parameters:

cachedLocale - the Locale of the name passed as cachedName.

cachedName - the name whose locale is passed as cachedLocale that should be cached by this Name.

14.12.4. Method getName()

public java.lang.String getName()


Returns a String name, suitable for presentation to users, appropriate to the default locale.

Throws:

MissingResourceException - if a codebase URL is found to be unusable. (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase

14.12.5. Method getName(java.util.Locale)

public java.lang.String getName(java.util.Locale desiredLocale)


Returns a String name, suitable for presentation to users, which represents the best-fit name for the specified locale.

Throws:

MissingResourceException - if a codebase URL is found to be unusable. (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase

14.12.6. Method purge()

public void purge()


Purge away information about undesired locales. If no cache exists, this method first fills the cache based on the default locale. If a cache currently exists, that cache will be left intact. Once a cache is in place, this method will clear the resource bundle loader.

14.12.7. Method purge(java.util.Locale)

public void purge(java.util.Locale preserveLocale)


Purge away information about all locales except the passed locale. This method first makes sure the cache is appropriate to the passed desired locale. Once the cache is in place, this method will clear the resource bundle loader.

Parameters:

preserveLocale - a locale to preserve in this Name.

14.12.8. Method equals(java.lang.Object)

public boolean equals(java.lang.Object o)


Compares this Name to the passed object for equality. To be semantically equal, the class of the passed object must be Name, the passed object's cached name must be semantically equal to this object's cached name, the passed object's name key must be semantically to this object's name key, and the equals method of Name's superclass must return true.

Parameters:

An - object to compare to this Name

14.12.9. Method hashCode()

public int hashCode()


Returns a hash code for this object.

14.12.10. Method clone()

public java.lang.Object clone()


Clones this Name.

14.13. Interface com.artima.place.info.Purgable

public interface Purgable


Interface implemented by classes that can purge away localizable information for undesired locales, keeping only information about a desired locale, which is the only locale preserved when one of the purge methods is invoked.

14.13.1. Method purge()

public void purge()


Purge away information about undesired locales. If the class that implements this method doesn't already know what the desired locale is, it should assume that the current default locale is the desired locale.

All localizable information about undesired locales should be purged. Only localizable information about the desired locale should be preserved.

14.13.2. Method purge(java.util.Locale)

public void purge(java.util.Locale preserveLocale)


Purge away information about any locales other than the passed Locale, whose localized information should be preserved.

Parameters:

preserveLocale - a locale to preserve

14.14. Class com.artima.place.info.ResourceBundleLoader

public class ResourceBundleLoader
     extends java.lang.Object
     implements java.io.Serializable


A class that takes care of loading resources from a codebase that is selected based on best-fit locale. The best-fit locale is selected using an algorithm similar to that used by ResourceBundle.getBundle().

This class is not cloneable because it is immutable.

14.14.1. Constructor ResourceBundleLoader(java.lang.String, java.util.Map)

public ResourceBundleLoader(java.lang.String baseName, java.util.Map localesMap)


Constructs a ResourceBundleLoader with passed base name and locales map. The locales map contains Locale keys mapped to codebase URLStrings. The Locale keys represent locales for which ResourceBundles exist at the corresponding codebase URL. The set of locales in this map are a cache of the information embedded in the class names (or property file names) of the resources. For example, if class files MyResources_de_CH.class, MyResources_de.class, and MyResources.class are sitting in a JAR file at http://www.artima.com/myderes.jar, then Locale keys for ("de", "CH"), ("de", ""), and ("", "") would exist in this map all of whose coresponding URLString values would be "http://www.artima.com/myderes.jar".

The passed map is not used as part of the state of this object. The locales map may also contain as values arrays of URLString, so long as the length of the array is not zero and no elements of the array is null.

Parameters:

baseName - the base name of the ResourceBundles that can be loaded by this ResourceBundleLoader

localesMap - a mapping of Locales to codebase URL Strings

Throws:

NullPointerException - if either of passed baseName or localesMap is null, or if any value contained in the localesMap is null

IllegalArgumentException - if any keys contained in passed localesMap are not Locales, if any values are not either URLStrings or URLString[]s, if the length of any URLString[] array is zero, or if any URLString[] array contains null elements, if the localesMap does not contain the empty Locale, or if the basename contains any white space.

14.14.2. Method getBestFitLocale(java.util.Locale)

public java.util.Locale getBestFitLocale(java.util.Locale desiredLocale)


Returns the actual locale for which this ResourceBundleLoader can return a resource bundle that best fits the passed locale.

Parameters:

desiredLocale - the locale for which to get a best-fit supported locale.

Throws:

NullPointerException - if the desiredLocale parameter is null

14.14.3. Method getBestFitLocale()

public java.util.Locale getBestFitLocale()


Returns the actual locale for which this ResourceBundleLoader can return a resource bundle that best fits the default locale.

14.14.4. Method getSupportedLocales()

public java.util.Set getSupportedLocales()


Returns an unmodifiable set of locales which are directly supported by this ResourceBundleLoader. Need to define whether or not this means also listing the dudes that don't have all, such as the root, or _en if also have _en_US. Probably want to send back all.

14.14.5. Method getResourceBundle()

public java.util.ResourceBundle getResourceBundle()
     throws java.util.MissingResourceException


Returns a best-fit ResourceBundle for the default Locale.

Throws:

MissingResourceException - if a codebase URL is found to be unusable. (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase

14.14.6. Method getResourceBundle(java.util.Locale)

public java.util.ResourceBundle getResourceBundle(java.util.Locale locale)
     throws java.util.MissingResourceException


Returns a best-fit ResourceBundle for the passed desired Locale.

Parameters:

locale - the desired locale

Throws:

MissingResourceException - if a codebase URL is found to be unusable (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase

NullPointerException - if the passed locale parameter is null

14.14.7. Method getCodebaseClassLoader()

public java.lang.ClassLoader getCodebaseClassLoader()
     throws java.net.MalformedURLException


Returns a ClassLoader for the codebase that best fits the default Locale. The returned ClassLoader represents the codebase from which the ResourceBundle returned by getResourceBundle() is loaded. If a resource loaded from a ResourceBundle indicates the name of a file loadable from its codebase, that file can be loaded via the getResource, getResourceAsStream, or getResources methods of the returned ClassLoader.

Throws:

MalformedURLException - if a codebase URL is found to be unusable. (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase

14.14.8. Method getCodebaseClassLoader(java.util.Locale)

public java.lang.ClassLoader getCodebaseClassLoader(java.util.Locale locale)
     throws java.net.MalformedURLException


Returns a ClassLoader for the codebase that best fits the passed Locale. The returned ClassLoader represents the codebase from which the ResourceBundle returned by getResourceBundle(Locale) is loaded. If a resource loaded from a ResourceBundle indicates the name of a file loadable from its codebase, that file can be loaded via the getResource, getResourceAsStream, or getResources methods of the returned ClassLoader.

Parameters:

locale - the desired locale

Throws:

MalformedURLException - if a codebase URL is found to be unusable (Because URLString enforces well-formedness of all URLs used by this method, this exception probably indicates the protocol was unknown.), or if a ResourceBundle is not found at the expected codebase

NullPointerException - if the passed locale parameter is null

14.14.9. Method equals(java.lang.Object)

public boolean equals(java.lang.Object o)


Compares passed ResourceBundleLoader to this ResourceBundleLoader for equality. Two ResourceBundleLoader objects are semantically equal if they have the equivalent base names and locales maps.

Parameters:

An - object to compare to this ResourceBundleLoader

14.14.10. Method strip(java.util.Set)

public com.artima.place.info.ResourceBundleLoader strip(java.util.Set preserveLocales)


Returns a ResourceBundleLoader that supports only the locales in the passed set. If the passed set does not contain the empty Locale, the empty locale will be included in the stripped ResourceBundleLoader anyway. If the length of the passed set is zero, only the empty Locale will be contained in the stripped ResourceBundleLoader. All Locales contained in the passed Set must be directly supported by this ResourceBundleLoader, i.e., must be included in the Set returned by the getSupportedLocales method of this ResourceBundleLoader. This method may iterate over the passed Set, so the client is responsible for ensuring that the passed Set is not modified while this method is executing.

Parameters:

preserveLocales - the set of locales to preserve

Throws:

NullPointerException - if the passed Set reference is null, or if any element in the passed Set is null

IllegalArgumentException - if any of the elements contained in the passed Set are not Locales, or if any of the Locales contained in the passed Set are not directly supported by this ResourceBundleLoader.

14.14.11. Method hashCode()

public int hashCode()


Computes the hash code for this ResourceBundleLoader.

ServiceUI is a trademark of Artima Software, Inc.