Project JXTA

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

Field Summary
static int HandChecking
           
static int NonBlocking
           
static int Propagate
           
 
Method Summary
 void addAddresses(PipeAdvertisement adv, java.util.Enumeration addrs)
          Teach the PipeService Polcicy about the localisation of a PipeService.
 InputPipe createInputPipe(PipeAdvertisement adv)
          create an InputPipe from a pipe Advertisement
 Message createMessage()
          Creates a new Message
 OutputPipe createOutputPipe(PipeAdvertisement adv, int type, java.util.Enumeration peers, long timeout)
          create an OutputPipe from the pipe Advertisement giving a PeerId(s) where the corresponding InputPipe is supposed to be.
 OutputPipe createOutputPipe(PipeAdvertisement adv, int type, long timeout)
          create an OutputPipe from the pipe Advertisement
 
Methods inherited from interface net.jxta.service.Service
getAdvertisement, getInterface
 
Methods inherited from interface net.jxta.platform.Application
init, startApp, stopApp
 

Field Detail

NonBlocking

public static final int NonBlocking

HandChecking

public static final int HandChecking

Propagate

public static final int Propagate
Method Detail

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 Pipes
timeout - 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 pipe
addrs - Enumeration of EndpointAddress of the pipe
Since:
JXTA 1.0

Project JXTA