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 recommend