net.jxta.pipe
Interface InputPipe

public interface InputPipe

InputPipe defines the interface for receiving messages from a PipeService. 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.

The binding of output pipes to an input pipes is done dynamically at runtime via the pipe resolver protocol. The pipe resolver mechanism searches for a pipe advertisement and an instance of the pipe (Input or output) running on the closest available peer.

The non-localization of pipes and the pipe resolver protocol make JXTA pipes unique by allowing applications and services to find themselves and open communication channels via the resolution of a pipe advertisement. Futhermore, the pipe resolution protocol enables to have pipe channels to adapt to their environment in a transparent manner, by allowing applications and services to find the "closest" instance of a pipe instance in their horizon of discovery.

The pipe resolver mechanism is powerful to create JXTA high-availability services by allowing pipes to be dynamically connected on different peers in a fully decentralized and transparent manner.

Since:

JXTA 1.0

See Also:

OutputPipe, Message, PipeAdvertisement, Pipe, GenericResolver

Method Summary

void	close() close the pipe
Message	poll(int timeout) Poll for a message from the pipe
Message	waitForMessage() wait for a message to be received

Method Detail

waitForMessage

public Message waitForMessage()
                       throws java.io.IOException

wait for a message to be received

Returns:

Message message received

Throws:

java.io.IOException - input pipe error

Since:

JXTA 1.0

poll

public Message poll(int timeout)
             throws java.io.IOException

Poll for a message from the pipe

Parameters:

timeout - minimum time poll is supposed to block (in milliseconds)

Returns:

Message message received

Throws:

java.io.IOException - input pipe error

Since:

JXTA 1.0

close

public void close()

close the pipe

Since:

JXTA 1.0