net.jxta.pipe
Interface Pipe
- All Superinterfaces:
- Application, Service
- public interface Pipe
- extends Service
A core service of Jxta Group is the PipeService service for
creating and accessing pipes within a peer group. The Pipe defines a
set of interfaces to create and access pipes within a peer group.
The Jxta Pipe defines an API and a Protocol.
Pipes are the core mechanism for exchanging messages
between two JXTA applications or services. Pipes provides a simple,
uni-directional and asynchronous channel of communication between two
peers. JXTA messages are exchanged between pipes (Input and Output
pipes). An application to open a receiving communication with other
peers will create an input pipe and bind it to a specific pipe
advertisement. The application will then publish the pipe advertisement
so other applications or services can obtain the advertisment and create
corresponding output pipes to send messages to that input pipe.
Pipes are uniquely identified throughout the JXTA world by a PipeId (UUID)
enclosed in a PipeAdvertisement. The pipe advertisement has a
unique id that is used to create the association between Input and
Output pipes.
Pipes are non-localized
communication channels not
binded to specific peers. This is a unique feature of JXTA pipes. The
mechanism to resolve the location of pipes to a physical peer is done in
a complete decentralized manner in JXTA via the JXTA PipeService
ResolverService protocol. The PipeService resolver protocol does not rely on a
centralized protocol such as DNS (bind Hostname to IP) to bind a pipe
advertisement (i.e.symbolic name) to an instance of a pipe on a physical
peer (i.e IP address). The resolver protocol uses a dynamic and adaptive
search mechanism that attempts at all time to find the closest peer
where an instance of that pipes is running leverage JXTA core DiscoveryService
mechanism.
Pipes are named with their XML advertisement. The generation of
the PipeService Advertisements is let to the applications. A Jxta PipeService
advertisement is an XML document (non validated) which contains at least
the following structure (but can be extended).
UUID
optional symbolic name than can be used by any search engine
Note that other tags can be provided by the application for its own
profit. Those extra tags are not interpreted by the PipeService Service.
The UUID needs to be a unique String (unique in time and space).
The optional tool package net.jxtax.pipe provides helper classes to
- Since:
- JXTA 1.0
- See Also:
InputPipe
,
Message
,
PipeAdvertisement
,
Pipe
,
GenericResolver
NonBlocking
public static final int NonBlocking
HandChecking
public static final int HandChecking
Propagate
public static final int Propagate
createInputPipe
public InputPipe createInputPipe(PipeAdvertisement adv)
throws java.io.IOException
- create an InputPipe from a pipe Advertisement
- Parameters:
adv
- is the advertisement of the PipeService.- Returns:
- InputPipe InputPipe object created
- Throws:
java.io.IOException
- error creating input pipe- Since:
- JXTA 1.0
createOutputPipe
public OutputPipe createOutputPipe(PipeAdvertisement adv,
int type,
long timeout)
throws java.io.IOException
- create an OutputPipe from the pipe Advertisement
- Parameters:
adv
- is the advertisement of the PipeService.type
- is an int and contains the name of the diffusion mode for
this OutputPipe (NonBlocking, HandChecking, Propagate).timeout
- time createOutputPipe will block: -1 means indefinitely,
otherwise, timeout in millisecond- Returns:
- OuputPipe Output pip object
- Throws:
java.io.IOException
- error creating output pipe- Since:
- JXTA 1.0
createOutputPipe
public OutputPipe createOutputPipe(PipeAdvertisement adv,
int type,
java.util.Enumeration peers,
long timeout)
throws java.io.IOException
- create an OutputPipe from the pipe Advertisement giving a PeerId(s) where
the corresponding InputPipe is supposed to be.
- Parameters:
adv
- is the advertisement of the NetPipe.type
- is an int and contains the name of the diffusion mode for
this OutputPipe.peers
- is an enumeration of the PeerId of thepeers where to look for the
corresponding Pipestimeout
- time createOutputPipe will block: -1 means
indefinitely, otherwise, timeout in millisecond- Returns:
- OuputPipe
- Throws:
java.io.IOException
- if none of the peers in the enumeration has
the corresponding OutputPipe- Since:
- JXTA 1.0
createMessage
public Message createMessage()
- Creates a new Message
- Returns:
- Message returns a newly allocated PipeService Message.
- Since:
- JXTA 1.0
addAddresses
public void addAddresses(PipeAdvertisement adv,
java.util.Enumeration addrs)
- Teach the PipeService Polcicy about the localisation of a PipeService. This
allows an application to help the PipeService ResolverService. Note that once
a set of EndpointAddresses has been set for a pipe, it cannot be
removed, because the PipeResolver may have already propagated the
addresses. This function should be used very cautiously.
XXX: maybe some sanity check should be added here, or special
credential. To be revisited.
- Parameters:
adv
- PipeService Advertisement of the pipeaddrs
- Enumeration of EndpointAddress of the pipe- Since:
- JXTA 1.0