JXTA

net.jxta.platform
Interface Module

All Known Subinterfaces:
AccessService, Application, DiscoveryService, EndpointService, MembershipService, PeerGroup, PeerInfoService, PipeService, RendezVousService, ResolverService, Service, ServiceMonitor
All Known Implementing Classes:
LightWeightPeerGroup

public interface Module

Defines the interface for modules loaded by PeerGroups. Message transports, services and applications need to implement this interface if they are to be loaded and started by a PeerGroup. Service and Application extend Module, PeerGroup implements Service and ShellApp implements Application, as a result both implement Module.

Jxta Modules are given their initialization parameters via the init() method rather than a non-default constructor.

Modules are passed the peer group within which they are created. From the peergroup object, Modules can access all the peer group services. The PeerGroup within which a PeerGroup runs is known as its parent.

The initial root peer group is known as the World Peer Group and is implemented by an object of class Platform, a subclass of PeerGroup. The "parent" PeerGroup of the World Peer Group is null.

See Also:
ModuleImplAdvertisement, ModuleClassID, PeerGroup, Advertisement, ID, Application, Service

Field Summary
static int START_AGAIN_PROGRESS
          This is to be used mostly by co-dependent services when started as a set (such as PeerGroup services) so that their startApp() method may be invoked multiple times.
static int START_AGAIN_STALLED
          This is to be used mostly by co-dependent services when started as a set (such as PeerGroup services) so that their startApp method may be invoked multiple times.
static int START_DISABLED
          This return result is used to indicate that the module refuses to start because it has been configured to be disabled or otherwise cannot run (missing hardware, missing system resources, etc.)
static int START_OK
          startApp() completed successfully.
 
Method Summary
 void init(PeerGroup group, ID assignedID, Advertisement implAdv)
          Initialize the module, passing it its peer group and advertisement.
 int startApp(String[] args)
          Complete any remaining initialization of the module.
 void stopApp()
          Stop a module.
 

Field Detail

START_OK

static final int START_OK
startApp() completed successfully. This module claims to now be fully functional and no further invocation of startApp is required.

See Also:
Constant Field Values

START_AGAIN_PROGRESS

static final int START_AGAIN_PROGRESS
This is to be used mostly by co-dependent services when started as a set (such as PeerGroup services) so that their startApp() method may be invoked multiple times.

This value indicates that startApp must be retried later in order for this module to become fully functional. However, some progress in functionality was accomplished.

This is a strong indication that some other modules may be able to advance or complete their initialization if their startApp() method is invoked again.

The distinction between START_AGAIN_STALLED and START_AGAIN_PROGRESS is only a hint. Each module makes an arbitrary judgment in this respect. It is up to the invoker of startApp to ensure that the starting of a set of modules eventually succeeds or fails.

See Also:
Constant Field Values

START_AGAIN_STALLED

static final int START_AGAIN_STALLED
This is to be used mostly by co-dependent services when started as a set (such as PeerGroup services) so that their startApp method may be invoked multiple times.

This value indicates that startApp must be retried later in order for this module to become fully functional. However, some progress in functionality was accomplished.

If all modules in a set return this value, it is a strong indication that the modules co-dependency is such that it prevents them collectively from starting.

The distinction between START_AGAIN_STALLED and START_AGAIN_PROGRESS is only a hint. Each module makes an arbitrary judgment in this respect. It is up to the invoker of startApp to ensure that the starting of a set of modules eventually succeeds or fails.

See Also:
Constant Field Values

START_DISABLED

static final int START_DISABLED
This return result is used to indicate that the module refuses to start because it has been configured to be disabled or otherwise cannot run (missing hardware, missing system resources, etc.) The module will not be functional and should be discarded but the failure to load may be ignored by the loader at it's discretion.

See Also:
Constant Field Values
Method Detail

init

void init(PeerGroup group,
          ID assignedID,
          Advertisement implAdv)
          throws PeerGroupException
Initialize the module, passing it its peer group and advertisement.

Note: when subclassing one of the existing PeerGroup implementations (which implement Module), it may not be recommended to overload the init method. See the documentation of the PeerGroup class being subclassed.

Parameters:
group - The PeerGroup from which this Module can obtain services. If this module is a Service, this is also the PeerGroup of which this module is a service.
assignedID - Identity of Module within group. modules can use it as a the root of their namespace to create names that are unique within the group but predictable by the same module on another peer. This is normally the ModuleClassID which is also the name under which the module is known by other modules. For a group it is the PeerGroupID itself. The parameters of a service, in the Peer configuration, are indexed by the assignedID of that service, and a Service must publish its run-time parameters in the Peer Advertisement under its assigned ID.
implAdv - The implementation advertisement for this Module. It is permissible to pass null if no implementation advertisement is available. This may happen if the implementation was selected by explicit class name rather than by following an implementation advertisement. Modules are not required to support that style of loading, but if they do, then their documentation should mention it.
Throws:
PeerGroupException - This module failed to initialize.

startApp

int startApp(String[] args)
Complete any remaining initialization of the module. The module should be fully functional after startApp() is completed. That is also the opportunity to supply arbitrary arguments (mostly to applications).

If this module is a PeerGroup service, it may be invoked several times depending on its return value.

Parameters:
args - An array of Strings forming the parameters for this Module.
Returns:
int A status indication which may be one of START_OK, START_AGAIN_PROGRESS, START_AGAIN_STALLED, which indicates partial or complete success, or any other value (negative values are recommended for future compatibility), which indicates failure.

stopApp

void stopApp()
Stop a module. This may be called any time after init() completes and should not assume that startApp() has been called or completed.

The Module cannot be forced to comply, but in the future we might be able to deny it access to anything after some timeout.


JXSE