Project JXTA

net.jxta.pipe
Interface PipeService

All Superinterfaces:
Module, Service

public interface PipeService
extends Service

This class defines the API to the JXTA Pipe Service.

Pipes are the core mechanism for exchanging messages between JXTA applications or services.

Pipes are uniquely identified by a PipeAdvertisement which is associated with each pipe. Creating the advertisement of a Pipe must be done only once in the lifetime of a Pipe. In fact, a PipeAdvertisement represents the pipe on the JXTA network.

Several types of Pipe can be used:

The type of a Pipe is defined when creating its PipeAdvertisement.

WARNING: The message object used when sending a pipe message should not be reused or modified after the OutputPipe.send(Message) call is made. Concurrent modification of messages will produce unexpected result.

See Also:
PipeAdvertisement, InputPipe, OutputPipe, Message

Field Summary
static String PropagateType
          Propagated, unsecure and unreliable type of Pipe
static String UnicastSecureType
          End-to-end secured unicast pipe of Pipe
static String UnicastType
          Unicast, unreliable and unsecure type of Pipe
 
Fields inherited from interface net.jxta.platform.Module
START_AGAIN_PROGRESS, START_AGAIN_STALLED, START_OK
 
Method Summary
 InputPipe createInputPipe(PipeAdvertisement adv)
          Create an InputPipe from a pipe Advertisement
 InputPipe createInputPipe(PipeAdvertisement adv, PipeMsgListener listener)
          create an InputPipe from a pipe Advertisement
 Message createMessage()
          Deprecated. Use new Message.Message() instead.
 OutputPipe createOutputPipe(PipeAdvertisement adv, Enumeration resolvablePeers, long timeout)
          Deprecated. Use createOutputPipe(PipeAdvertisement, Set, long) instead.
 OutputPipe createOutputPipe(PipeAdvertisement adv, long timeout)
          Attempt to ceate an OutputPipe using the specified Pipe Advertisement.
 void createOutputPipe(PipeAdvertisement adv, OutputPipeListener listener)
          Attempt to ceate an OutputPipe using the specified Pipe Advertisement.
 OutputPipe createOutputPipe(PipeAdvertisement adv, PeerID peerid, long timeout)
          Deprecated. Use createOutputPipe(PipeAdvertisement, Set, long) with a Collections.singleton(Object) instead.
 void createOutputPipe(PipeAdvertisement adv, PeerID peerid, OutputPipeListener listener)
          Deprecated. Use createOutputPipe(PipeAdvertisement, Set, long) with a Collections.singleton(Object) instead.
 OutputPipe createOutputPipe(PipeAdvertisement adv, Set resolvablePeers, long timeout)
          Attempt to ceate an OutputPipe using the specified Pipe Advertisement.
 void createOutputPipe(PipeAdvertisement pipeAdv, Set resolvablePeers, OutputPipeListener listener)
          Attempt to ceate an OutputPipe using the specified Pipe Advertisement.
 OutputPipeListener removeOutputPipeListener(String pipeID, OutputPipeListener listener)
          Remove an OutputPipeListener previously registered with createOuputputPipe.
 
Methods inherited from interface net.jxta.service.Service
getImplAdvertisement, getInterface
 
Methods inherited from interface net.jxta.platform.Module
init, startApp, stopApp
 

Field Detail

UnicastType

public static final String UnicastType
Unicast, unreliable and unsecure type of Pipe

See Also:
Constant Field Values

PropagateType

public static final String PropagateType
Propagated, unsecure and unreliable type of Pipe

See Also:
Constant Field Values

UnicastSecureType

public static final String UnicastSecureType
End-to-end secured unicast pipe of Pipe

See Also:
Constant Field Values
Method Detail

createInputPipe

public InputPipe createInputPipe(PipeAdvertisement adv)
                          throws IOException
Create an InputPipe from a pipe Advertisement

Parameters:
adv - is the advertisement of the PipeService.
Returns:
InputPipe InputPipe object created
Throws:
IOException - error creating input pipe

createInputPipe

public InputPipe createInputPipe(PipeAdvertisement adv,
                                 PipeMsgListener listener)
                          throws IOException
create an InputPipe from a pipe Advertisement

Parameters:
adv - is the advertisement of the PipeService.
listener - PipeMsgListener to receive msgs.
Returns:
InputPipe InputPipe object created
Throws:
IOException - error creating input pipe

createOutputPipe

public OutputPipe createOutputPipe(PipeAdvertisement adv,
                                   long timeout)
                            throws IOException
Attempt to ceate an OutputPipe using the specified Pipe Advertisement. The pipe will be be resolved within the provided timeout.

Parameters:
adv - The advertisement of the pipe being resolved.
timeout - time duration in milliseconds to wait for a successful pipe resolution. 0 will wait indefinitely. All negative values will cause a wait of an inplementation defined non-infinite value. (this behaviour is deprecated and may eventually disappear).
Returns:
OutputPipe the successfully resolved OutputPipe.
Throws:
IOException - If the pipe cannot be created or failed to resolve within the specified time.

createOutputPipe

public OutputPipe createOutputPipe(PipeAdvertisement adv,
                                   PeerID peerid,
                                   long timeout)
                            throws IOException
Deprecated. Use createOutputPipe(PipeAdvertisement, Set, long) with a Collections.singleton(Object) instead.

Attempt to ceate an OutputPipe using the specified Pipe Advertisement. The pipe will be be resolved to one of the peers in the set of peer ids provided within the provided timeout.

Parameters:
adv - The advertisement of the pipe being resolved.
peerid - The peer id of the peer on which on which the pipe may be resolved. All elements of the enumeration must must be of type PeerID.
timeout - time duration in milliseconds to wait for a successful pipe resolution. 0 will wait indefinitely. All negative values will cause a wait of an inplementation defined non-infinite value. (this behaviour is deprecated and may eventually disappear).
Returns:
OutputPipe the successfully resolved OutputPipe.
Throws:
IOException - If the pipe cannot be created or failed to resolve within the specified time.

createOutputPipe

public OutputPipe createOutputPipe(PipeAdvertisement adv,
                                   Enumeration resolvablePeers,
                                   long timeout)
                            throws IOException
Deprecated. Use createOutputPipe(PipeAdvertisement, Set, long) instead.

Attempt to ceate an OutputPipe using the specified Pipe Advertisement. The pipe will be be resolved to one of the peers in the set of peer ids provided within the provided timeout.

Parameters:
adv - The advertisement of the pipe being resolved.
resolvablePeers - The non-empty enumeration of peers on which the pipe may be resolved. All elements of the enumeration must must be of type PeerID.
timeout - time duration in milliseconds to wait for a successful pipe resolution. 0 will wait indefinitely. All negative values will cause a wait of an inplementation defined non-infinite value. (this behaviour is deprecated and may eventually disappear).
Returns:
OutputPipe the successfully resolved OutputPipe.
Throws:
IOException - If the pipe cannot be created or failed to resolve within the specified time.

createOutputPipe

public OutputPipe createOutputPipe(PipeAdvertisement adv,
                                   Set resolvablePeers,
                                   long timeout)
                            throws IOException
Attempt to ceate an OutputPipe using the specified Pipe Advertisement. The pipe will be be resolved to one of the peers in the set of peer ids provided within the provided timeout.

Parameters:
adv - The advertisement of the pipe being resolved.
resolvablePeers - The set of peers on which the pipe may be resolved. All elements of the set must must be of type PeerID. If the Set is empty then the pipe may be resolved to any destination peer.
timeout - time duration in milliseconds to wait for a successful pipe resolution. 0 will wait indefinitely. All negative values will cause a wait of an inplementation defined non-infinite value. (this behaviour is deprecated and may eventually disappear).
Returns:
OutputPipe the successfully resolved OutputPipe.
Throws:
IOException - If the pipe cannot be created or failed to resolve within the specified time.

createOutputPipe

public void createOutputPipe(PipeAdvertisement adv,
                             OutputPipeListener listener)
                      throws IOException
Attempt to ceate an OutputPipe using the specified Pipe Advertisement. The pipe may be resolved to any destination peer. When the pipe is resolved the listener will be called.

Parameters:
adv - The advertisement of the pipe being resolved.
listener - the listener to be called when the pipe is resolved.
Throws:
IOException - If the pipe cannot be created.

createOutputPipe

public void createOutputPipe(PipeAdvertisement adv,
                             PeerID peerid,
                             OutputPipeListener listener)
                      throws IOException
Deprecated. Use createOutputPipe(PipeAdvertisement, Set, long) with a Collections.singleton(Object) instead.

Attempt to ceate an OutputPipe using the specified Pipe Advertisement. When the pipe is resolved to the peer id provided the listener will be called.

Parameters:
adv - The advertisement of the pipe being resolved.
peerid - The peer id of the peer on which on which the pipe may be resolved. All elements of the enumeration must must be of type PeerID.
listener - the listener to be called when the pipe is resolved.
Throws:
IOException - If the pipe cannot be created.

createOutputPipe

public void createOutputPipe(PipeAdvertisement pipeAdv,
                             Set resolvablePeers,
                             OutputPipeListener listener)
                      throws IOException
Attempt to ceate an OutputPipe using the specified Pipe Advertisement. When the pipe is resolved to one of the peers in the set of peer ids provided the listener will be called.

Parameters:
pipeAdv - The advertisement of the pipe being resolved.
resolvablePeers - The set of peers on which the pipe may be resolved. All elements of the set must must be of type PeerID. If the Set is empty then the pipe may be resolved to any destination peer.
listener - the listener to be called when the pipe is resolved.
Throws:
IOException - If the pipe cannot be created.

createMessage

public Message createMessage()
Deprecated. Use new Message.Message() instead.

Creates a new Message for sending via this Pipe Service.

Returns:
A newly allocated Message.

removeOutputPipeListener

public OutputPipeListener removeOutputPipeListener(String pipeID,
                                                   OutputPipeListener listener)
Remove an OutputPipeListener previously registered with createOuputputPipe.

Parameters:
pipeID - listener to remove
listener - listener to remove
Returns:
the listener which was removed or null if the key did not have a mapping.

JXTA J2SE