US.2. Terminology
This section defines terms and discusses concepts that may be referenced throughout the helper utilities and services specifications. While the terms and concepts that appear in this section are general in nature and may apply to multiple components specified in this collection, each specification may define additional terms and concepts to further facilitate the understanding of a particular component. Each specification may also present supplemental information about some of the terms defined in this section and their relationship with the component being specified.
Because this document makes use of a number of terms defined in the “Jini Technology Glossary”, reviewing the glossary is recommended. A number of the terms defined in the glossary are also defined in this section to provide easy reference because those terms are used extensively in the helper utilities and services specifications. Additionally, this section augments the definitions of some of the terms from the glossary with details relevant to those specifications.
In addition to the glossary, the Jini Technology Core Platform Specification (referred to as the core specification) presents detailed definitions of a number of terms and concepts appearing both in this section and throughout the helper utilities and services specifications. When appropriate, the relevant specification will be referenced.
US.2.1. Terms Related to Discovery and Join
The Jini Technology Core Platform Specification, “Discovery and Join”, defines a discovering entity as one or more cooperating software objects written in the Java programming language (Java software objects), executing on the same host, that are in the process of obtaining references to Jini lookup services. That specification also defines a joining entity as one or more cooperating Java software objects, on the same host, that have received a reference to a lookup service and are in the process of obtaining services from, and possibly exporting services to, a federation of Jini technology-enabled services and/or devices and Jini lookup services referred to as a djinn. The lookup services comprising a djinn may be organized into one or more sets known as groups. Multiple groups may or may not be disjoint. Each group of lookup services is identified by a logical name represented by a String object.
The Jini Technology Core Platform Specification, “Discovery and Join” defines two protocols used in the discovery process: the multicast discovery protocol and the unicast discovery protocol.
When a discovering entity employs the multicast discovery protocol to discover lookup services that are members of one or more groups belonging to a set of groups, that discovery process is referred to as group discovery.
The utility class net.jini.core.discovery.LookupLocator is defined in The Jini Technology Core Platform Specification, “Discovery and Join”. Any instance of that class is referred to as a locator. When a discovering entity employs the unicast discovery protocol to discover specific lookup services, each corresponding to an element in a set of locators, that discovery process is referred to as locator discovery.
US.2.2. Jini Clients and Services
For the purposes of the helper utilities and services specifications, a Jini client is defined as a discovering entity that can retrieve a service (or a remote reference to a service) registered with a discovered lookup service and invoke the methods of the service to meet the entity’s requirements. An entity that acts only as a client never registers with (requests residency in) a lookup service.
A Jini service is defined as both a discovering and a joining entity containing methods that may be of use to some other Jini client or service, and which registers with discovered lookup services to provide access to those methods. Note that a Jini service can also act as a Jini client.
The term client-like entity may be used, in general, when referring to Jini clients and Jini services that act as clients.
Note that when the term entity is used, that term may be referring to a discovering entity, a joining entity, a client-like entity, a service, or some combination of these types of entities. Whenever that general term is used, it should be clear from the context what type of entity is being discussed.
US.2.3. Helper Service
A Jini technology-enabled helper service is defined in this document as an interface or set of interfaces, with an associated implementation, that encapsulates behavior that is either required or highly desirable in service entities that adhere to the Jini technology programming model (or simply the Jini programming model). A helper service is a Jini service that can be registered with any number of lookup services and whose methods can execute on remote hosts.
In general, a helper service should be of use to more than one type of entity participating in the Jini application environment and should provide a significant reduction in development complexity for developers of such entities.
US.2.4. Helper Utility
This document distinguishes between a helper utility and a helper service. Helper utilities are programming components that can be used during the construction of Jini services and/or clients. Helper utilities are not remote and do not register with a lookup service. Helper utilities are instantiated locally by entities wishing to employ them.
US.2.5. Managed Sets
When performing discovery duties, entities will often maintain references to discovered lookup services in a set referred to as the managed set of lookup services. The entity may also maintain two other notable sets: the managed set of groups and the managed set of locators.
Each element of the managed set of groups is a name of a group whose members are lookup services that the entity wishes to be discovered via group discovery. The managed set of groups is typically represented as a String array, or a Collection of String elements.
Each element of the managed set of locators corresponds to a specific lookup service that the entity wishes to be discovered via locator discovery. Typically, this set is represented as an array of net.jini.core.discovery.LookupLocator objects or some other Collection type whose elements are LookupLocator objects.
Note that when the general term managed set is used, it should be clear from the context whether groups, locators, or lookup services are being discussed.
US.2.6. What Exceptions Imply about Future Behavior
When interacting with a remote object, an entity may call methods that result in exceptions. The specification of those methods should define what each possible exception implies (if anything) about the current state of the object. One important aspect of an object’s state is whether or not further interactions with the object are likely to be fruitful. Throughout the helper utilities and services specifications, the following general terms may be used to classify what a given exception implies about the probability of success of future operations on the object that threw the exception:
Bad object exception: If a method invocation on an object throws a bad object exception, it can be assumed that any further operations on that object will also fail.
Bad invocation exception: If a method invocation on an object throws a bad invocation exception, it can be assumed that any retries of the same method with the same arguments that are expected to return the same value will also fail. No new assertions can be made about the probability of success of any future invocation of that method with different arguments or if a different return value is expected, nor can any new assertions be made about the probability of success of invocations of the object’s other methods.
Indefinite exception: If a method invocation on an object throws an indefinite exception, no new assertions can be made about the probability of success of any future invocation of that method, regardless of the arguments used or return value expected, nor can any new assertions be made about the probability of success of any other operation on the same object.
Unless otherwise noted, the throwing of a bad object, bad invocation, or indefinite exception by one object does not imply anything about the state of another object, even if both objects are associated with the same remote entity.
These terms can be used in the specification of a method to describe the meaning of exceptions that might be thrown, as well as in the specification of what a given utility or service will, may, or should do when it receives an exception in the course of interacting with a given object.
If a specification does not say otherwise, the following classification is used to categorize each RuntimeException, Error, or java.rmi.RemoteExceptions as a bad object, bad invocation, or indefinite exception:
Bad object exceptions:
Any java.lang.RuntimeException
Any java.lang.Errorexcept one that is a java.lang.LinkageError or java.lang.OutOfMemoryError
Any java.rmi.NoSuchObjectException
Any java.rmi.ServerError with a detail field that is a bad object exception
Any java.rmi.ServerException with a detail field that is a bad object exception
Bad invocation exceptions:
Any java.rmi.MarshalException with a detail field that is a java.io.ObjectStreamException
Any java.rmi.UnmarshalException with a detail field that is a java.io.ObjectStreamException
Any java.rmi.ServerException with a detail field that is a bad invocation exception
Indefinite exceptions
Any java.lang.OutOfMemoryError
Any java.lang.LinkageError
Any java.rmi.RemoteExceptionexcept those that can be classified as either a bad invocation or bad object exception
US.2.7. Unavailable Lookup Services
While interacting (or attempting to interact) with a lookup service, an entity may encounter one of the exception types described in the previous section. When the entity does receive such an exception, what may be concluded about the state of the lookup service is dependent on the type of exception encountered.
If an entity encounters a bad object exception while interacting with a lookup service, the entity can usually conclude that the associated proxy it holds can no longer be used to interact with the lookup service. This can be due to any number of reasons. For example, if the lookup service is administratively destroyed, the old proxy will never be capable of communicating with any new incarnations of the lookup service, allowing the entity to dispose of the old proxy since it is no longer of any use to the entity.
If an indefinite exception occurs while interacting with a lookup service, the entity can interpret such an occurrence as a communication failure that may or may not be only temporary.
Finally, entities that encounter a bad invocation exception while interacting with a lookup service should view the lookup service as being in an unknown, possibly corrupt state, and should discontinue further interaction with that lookup service until the problem is resolved.
Whenever an entity receives any of these exceptions while interacting with a lookup service, the affected lookup service is referred to as unavailable or unreachable. For most entities the unavailability of a particular lookup service should not prevent the entity from continuing its processing, although in other situations an entity might consider at least some of these exceptional conditions unrecoverable. In general, when an entity encounters an unreachable lookup service, the exception or error indicating that the lookup service is unavailable should be caught and handled, usually by requesting that the lookup service be discarded (see the next section), and the entity should continue its processing.
US.2.8. Discarding a Lookup Service
When an already discovered lookup service is removed from the managed set of lookup services, it is said to be discarded. The process of discarding a lookup service is initiated either directly or indirectly by the discovering entity itself or by the utility that the entity employs to perform the actual discovery duties.
Whenever a lookup service is discarded by a utility employed by the entity, the utility sends to all of the entity’s discovery listeners, a notification event referencing both the discarded lookup service and the member groups to which the lookup service belongs. This event is referred to as a discarded event. It may be useful to note that discarded events can be classified by two characteristics:
Whether the event was generated as a direct consequence of an explicit request made by the entity itself (active) or as a consequence of a determination made by some utility employed by the entity (passive)
Whether the event is related to communication problems or to the entity losing interest in discovering the affected lookup services
US.2.8.1. Active Communication Discarded Event
When the occurrence of exceptional conditions causes an entity to conclude that a lookup service is unreachable, the entity typically will request that the lookup service be discarded. When the entity itself requests that such an unreachable lookup service be discarded, the resulting discarded event may be referred to as an active communication discarded event. The term active is used because the entity takes specific action to request that the lookup service be discarded. Because the entity cannot communicate with the unreachable lookup service, the event is associated with communication.
US.2.8.2. Active No-Interest Discarded Event
Whenever the entity makes a request that results in the removal of an element from the relevant managed set of groups or locators, one or more of the lookup services associated with the removed groups or locators may be discarded—even though the lookup services are still reachable. The lookup services may be discarded in this situation because the contents of the sets of groups and locators the entity wishes to discover may have changed in such a way that one or more of the previously discovered lookup services are no longer of interest to the entity. In this case, if any already discovered lookup service is found to belong to none of the groups in the new managed set of groups or if its locator no longer belongs to the entity’s new managed set of locators, a discarded event is generated and sent to all of the entity’s discovery listeners. This type of discarded event may be referred to as an active no-interest discarded event (active because the entity itself executed an action that resulted in the discarding of one or more lookup services).
US.2.8.3. Passive Communication Discarded Event
If the utility that the entity uses to perform group (multicast) discovery determines that one of the previously discovered lookup services has stopped sending multicast announcements, that utility may discard the lookup service. That is, the utility may remove the lookup service from the managed set and send a discarded event to notify the entity that the lookup service is unavailable. The discarded event sent in this situation is often referred to as a passive communication discarded event.
US.2.8.4. Passive No-Interest Discarded Event
If the utility that the entity uses to perform group discovery determines that the member groups of one of the previously discovered lookup services has changed, the utility may discard that lookup service. The lookup service may be discarded in this situation because the lookup service may no longer be a member of any of the groups the entity wishes to discover; that is, the lookup service is no longer of interest to the entity. In this case, the utility sends a discarded event to all of the entity’s discovery listeners. This type of discarded event may be referred to as a passive no-interest discarded event (passive because the entity itself did not explicitly request that the lookup service be discarded).
If a lookup service is discarded because it was found to be unreachable (associated with a communication discarded event), that lookup service will be made eligible for rediscovery. In this case, the process of discarding a lookup service— either actively or passively—can be viewed as a mechanism for the removal of stale entries in the managed set of lookup services. Discarding such a lookup service removes the need for operations such as lease renewal attempts on a lookup service that is currently unavailable. Upon rediscovery of the discarded lookup service, the entity typically processes the rediscovered lookup service as if it were discovered for the first time.
Any lookup service corresponding to a no-interest discarded event is no longer eligible for discovery until one of the following occurs:
The entity changes its managed set of locators or its managed set of groups to include, either the discarded lookup service’s locator or at least one of its member groups respectively.
The set of member groups of the discarded lookup service is changed to include one or more of the groups the entity is currently interested in discovering.
US.2.8.5. Changed Event
An event related to the discarded event is referred to as a changed event. This event notifies the entity of changes in the contents of the member groups of one or more of the lookup services in the managed set. If the entity registers interest in such an event and if the utility that the entity uses to perform group discovery determines that one or more of those member group sets has indeed changed, then a changed event is sent.
US.2.8.6. Remote Objects, Stubs, and Proxies
The “Jini Technology Glossary” defines a remote object as an object whose methods can be invoked from a Java virtual machine (JVM)[1], potentially on a different host. Furthermore, the glossary states that such an object is described by one or more remote interfaces.
[1] The terms “Java virtual machine” or “JVM” mean a virtual machine for the Java platform.
When invoking methods remotely through Java Remote Method Invocation (RMI), it is useful to think of the invocation as consisting of two components: a client component and a server component. When the client component initiates a remote method call, the server component carries out the execution of the remote method, and RMI facilitates the necessary communication between the two parties. Note that in discussing concepts related to RMI, the term server (or remote server) is sometimes used in place of the term remote object.
To initiate an invocation of a remote method, the client must have access to an object referred to as the stub of the remote object. The stub is an object local to the client that acts as the “representative” of the remote object. The stub implements the same set of remote interfaces that the remote object implements. From the point of view of the client, the stub is the remote object. When the client invokes a method on the local stub, communication with the remote object occurs, resulting in the execution of the corresponding method in the remote object’s JVM.
The term proxy is used extensively throughout the helper utilities and services specifications. With respect to remote objects in general, and entities operating within a Jini application environment in particular, a proxy is simply an intermediary object through which one entity (the client) may request the invocation of the methods provided by another entity (the remote object or the service).
Proxies can take a number of different forms. A smart proxy typically consists of a set of local methods and a set of one or more remote object references (stubs). Clients invoke one or more of the local methods to access the methods of the remote objects referenced in the proxy.
Another form that a proxy can take is that of the stub of a remote object. That is, all stubs are simply proxies to their corresponding remote objects. Except for the local methods equals and hashCode, this type of proxy consists of remote methods only.
Some proxies are implemented as strictly local. Proxies of this form consist of only local methods, each executing in the client’s JVM. Unlike smart proxies, no remote invocations result when any method of a strictly local proxy is invoked.
Typically, Jini services provide a proxy that has one of the forms described above. When a service registers with a lookup service, the service’s proxy is copied (through serialization) into the lookup service. When a client looks up the service, the service’s proxy is downloaded to the client. The client can then invoke the methods contained in the service’s proxy. If the invoked method is a local method, then execution will occur in the JVM of the client. If the invoked method is a remote method (or results in a remote invocation), then execution is initiated in the client’s JVM, but ultimately occurs in the JVM of the service.
Note that the term front-end proxy (or simply front end) is often used interchangeably with the term proxy. Similarly, the term back-end server (or simply, back end) is often used interchangeably with the term remote object. Thus, the back end of a service is the part of the service’s implementation that satisfies the contract advertised in the service’s remote interface.
US.2.9. Activation
The glossary defines active object as a remote object that is instantiated and exported in a JVM on some system. Remote objects can be implemented with the ability to change their state from inactive to active, or from active to inactive; the process of doing so is referred to as activation or deactivation, respectively. Many Jini services that wish to conserve computational resources may find this capability desirable. When the back end of any Jini service is implemented with the ability to activate and deactivate, the service is referred to as an activatable service. Refer to the Java Remote Method Invocation Specification for the details of activation.