Pipes

1
Pipes
2
Learning Objectives

• This module will help you...
• Understand key JXTA pipe concepts
• Understand how pipes work
• Gain familiarity with the JXTA Pipe Service API

3
Pipes

• Core mechanism for exchanging messages between
  JXTA applications or services
• Unidirectional
• Input pipes used to receive messages output
  pipes used to send messages
• Input/output pipes connected by the JXTA pipe
  service
• Several types of Pipe can be used
• JxtaUnicast unicast, unreliable, unsecure
• JxtaUnicastSecure unicast, reliable secure
• JxtaPropagate propagated, unreliable, unsecure

4
Pipe Advertisements

• Uniquely identifies a pipe
• Creating the advertisement must be done only once
  in the lifetime of a Pipe
• Peers can search for pipe advertisements using
  the discovery service
• Can be retrieved from local cache
• Can register an object to be notified when a new
  pipe advertisement is discovered
• Can be stored, or generated out of band

5
Pipe Service

• Defines a set of interfaces to create and access
  pipes within a peergroup
• JXTA messages exchanged between input and output
  pipes
• Application that wishes to receive messages
  creates an input pipe and binds it to a specific
  pipe advertisement
• Application publishes the pipe advertisement
• Other applications obtain the advertisement and
  create corresponding output pipe bound to the
  input pipe

6
(No Transcript)
7
Messages

• Pipe data is represented as JXTA messages
• Each message contains zero or more elements
• Each element can be named
• Both input and output pipe must agree on the
  element naming

8
Asynchronous Communication

• OutputPipeListener
• Called asynchronously by the JXTA platform when
  pipe endpoints are resolved
• InputPipeListener
• Called asynchronously by the JXTA platform
  whenever a message is received

9
Java API
Package net.jxta.pipe

• Interfaces
• PipeService defines the API to the JXTA Pipe
  Service
• InputPipe defines the interface for receiving
  messages
• OutputPipe defines the interface for sending
  messages
• Events
• OutputPipeEvent contains events received when
  an output pipe is resolved
• PipeMsgEvent contains events when a message is
  received
• Event Listeners
• PipeMsgListener the listener interface for
  receiving PipeMsgEvent events
• OutputPipeListener The listener interface for
  receiving OutputPipe resolution events

10
Pipe Service Java API

• createInputPipe(PipeAdvertisement
  adv)createInputPipe(PipeAdvertisement
  adv,PipeMsgListener listener)
• Create an input pipe from the pipe advertisement,
  and register the message listener
• createOutputPipe(PipeAdvertisement adv, long
  timeout)
• Attempts to resolve given pipe within timeout
• createOutputPipe(PipeAdvertisement adv, PeerID
  peer, long timeout)
• Attempts to resolve given pipe at specified peer
  within timeout
• createOutputPipe(PipeAdvertisement adv, PeerID
  pid , OutputPipeListener listener)
• createOutputPipe(PipeAdvertisement adv,
  OutputPipeListener listener)
• Attempts to resolve given pipe and notifies
  OutputPipeListener when resolved
• removeOutputPipeListener(String pipeid,
  OutputPipeListener listener)
• Remove an output pipe listener

11
Pipe Service Java API
Usage Notes

• Pipe service creates both input and output pipes
• Input pipes are created with a pipe advertisement
• Output pipes are created with the receiving end's
  pipe advertisement
• Resolution of output pipes
• Synchronously (resolved within a timeout)
• Asynchronously (listener notification)
• Pipe type is defined by the Pipe Advertisement

12
Input Pipe Output Pipe Java API

• InputPipe
• void close()
• Message poll(int timeout)
• Blocks until a message is received or timeout
  expires returns only one message, even if more
  are available
• Message waitForMessage()
• Wait indefinitely for a message
• OutputPipe
• void close()
• void send(Message msg)
• Send a message to the network

13
OutputPipeListener Java API

• OutputPipeListener
• Objects that implement this interface are
  notified each and every time the pipe service
  completes the resolution of a given output pipe
• void outputPipeEvent(OutputPipeEvent event)
• OutputPipeEvent
• An instance of OutputPipeEvent is sent to
  OutputPipeListeners whenever the pipe service
  resolves a new output pipe
• outputPipe getOutputPipe()
• outputPipe.getAdvertisement()

14
PipeMsgListener Java API

• PipeMsgListener
• Objects that implement this interface are
  notified whenever a new message is received for a
  given input pipe
• void pipeMsgEvent(pipeMsgEvent event)
• PipeMsgEvent
• An instance of PipeMsgEvent is sent to
  PipeMsgListener objects whenever a message is
  available on the pipe
• Message getMessage()

15
Pipe Example Java

• Two part tutorial
• Sending End
• Read in a predefined pipe advertisement
• Attempt to resolve the pipe instance(s),
• Take network events into consideration
• Receiving End
• Read in a predefined pipe advertisement
• Printout messages as they arrive on the pipe

16
Pipe Example (1)
public class PipeExample implements Runnable,
OutputPipeListener, RendezvousListener
public static void main(String args)
PipeExample myapp new PipeExample() myapp
.startJxta() myapp.run() private
void startJxta() try // create, and Start
the default jxta NetPeerGroup netPeerGroup
PeerGroupFactory.newNetPeerGroup() catch (
PeerGroupException e ) // get the pipe
service, and discovery pipe
netPeerGroup.getPipeService() rendezvous
netPeerGroup.getRendezVousService()
rendezvous.addListener( this ) discovery
netPeerGroup.getDiscoveryService()
System.out.println( "Reading in pipexample.adv"
) try FileInputStream is new
FileInputStream( "examplepipe.adv" )
pipeAdv (PipeAdvertisement)
AdvertisementFactory.newAdvertisement(
MimeMediaType.XMLUTF8, is )
is.close() catch ( Exception e )
System.out.println( "failed to read/parse pipe
advertisement" ) e.printStackTrace()
System.exit( -1 )
17
Pipe Example (2)
Public synchronized void run() try //
create output pipe with asynchronously
System.out.println( "Attempting to create a
OutputPipe" ) pipe.createOutputPipe( pipeAdv,
this ) // send out a second pipe resolution
after we connect to a rendezvous if (
!rendezvous.isConnectedToRendezVous() )
System.out.println( "Waiting for Rendezvous
Connection" ) try wait() //
ok we connected to a rendezvous, attempt to
resolve again pipe.createOutputPipe(
pipeAdv, this ) catch ( InterruptedExceptio
n e ) catch ( IOException e )
System.out.println( "OutputPipe creation failure"
) e.printStackTrace() System.exit( -1
) public synchronized void
rendezvousEvent( RendezvousEvent event )
if ( event.getType() event.RDVCONNECT )
notify()
18
Output Pipe Listener
Public void outputPipeEvent( OutputPipeEvent
event ) System.out.println( " Got an
output pipe event" ) OutputPipe op
event.getOutputPipe() try
System.out.println( "Sending message" )
Message msg new Message() Date
date new Date(System.currentTimeMillis())
StringMessageElement sme new
StringMessageElement(SenderMessage,
date.toString() ,
null) msg.addMessageElement(null,
sme) op.send( msg ) catch (
IOException e ) System.out.println(
"failed to send message" )
e.printStackTrace() op.close()
System.out.println( "message sent" )
19
MsgListener
Public class PipeListener implements
PipeMsgListener static PeerGroup
netPeerGroup null private final static
String TAG "PipeListenerMsg" private final
static String FILENAME "examplepipe.adv"
private PipeService pipeSvc private
PipeAdvertisement pipeAdv private InputPipe
pipeIn null public static void main(String
args) PipeListener myapp new
PipeListener() myapp.startJxta()
myapp.run() public PipeListener() //
Default constructor private void startJxta()
try // create, and Start the default
jxta NetPeerGroup netPeerGroup
PeerGroupFactory.newNetPeerGroup() catch
(PeerGroupException e) pipeSvc
netPeerGroup.getPipeService() System.out.printl
n("Reading in " FILENAME) try
FileInputStream is new FileInputStream(FILENAME)
pipeAdv (PipeAdvertisement)
AdvertisementFactory.newAdvertisement(
MimeMediaType.XMLUTF8, is) is.close()
catch (Exception e)
20
Msg Listener (2)
// create input pipe, and register as a
PipeMsgListener to be // asynchronously notified
of any messages received on this input
pipe public void run() try
System.out.println("Creating input pipe")
pipeIn pipeSvc.createInputPipe(pipeAdv,
this) catch (Exception e) if (pipeIn
null) System.out.println("Error
cannot open InputPipe") System.exit(-1)
System.out.println("Waiting for msgs on input
pipe") public void pipeMsgEvent (
PipeMsgEvent event ) Message msgnull msg
event.getMessage() if (msg null)
return // get the message element named
SenderMessage MessageElement msgElement
msg.getMessageElement(null,

SenderMessage) // Get message if
(msgElement.toString() null)
System.out.println("null msg received")
else Date date new Date(System.currentTimeM
illis()) System.out.println("Message received
at " date.toString()) System.out.println("Me
ssage created at " msgElement.toString())

21
Pipe Service C API
Jxta_status jxta_pipe_service_timed_accept
(Jxta_pipe_service service,
Jxta_pipe_adv adv, Jxta_time
timeout, Jxta_pipe
pipe) Jxta_status jxta_pipe_service_add_accept_
listener (Jxta_pipe_service service,
Jxta_pipe_adv adv, Jxta_listener
listener) Jxta_status jxta_pipe_service_ti
med_connect (Jxta_pipe_service service,
Jxta_pipe_adv adv, Jxta_time
timeout, Jxta_vector
peers, Jxta_pipe pipe)
Jxta_status jxta_pipe_service_connect
(Jxta_pipe_service service, Jxta_pipe_adv
adv, Jxta_time timeout,
Jxta_vector peers, Jxta_listener
listener)
22
Pipe Example C
static void send_message (Jxta_outputpipe op,
char userName,
char userMessage)
Jxta_message msg jxta_message_new()
Jxta_message_element el NULL Jxta_status
res JXTA_OBJECT_CHECK_VALID (op) el
jxta_message_element_new_1 ((char) SENDERNAME,
(char)
"text/plain",
userName,
strlen (userName),
NULL ) jxta_message_add_element (msg,
el) JXTA_OBJECT_RELEASE (el) el
jxta_message_element_new_1 ((char)
SENDERMESSAGE,
(char) "text/plain",
userMessage,
strlen (userMessage), NULL )
jxta_message_add_element (msg, el)
JXTA_OBJECT_RELEASE (el) res
jxta_outputpipe_send (op, msg) if (res !
JXTA_SUCCESS) printf ("sending failed
d\n", (int) res) JXTA_OBJECT_RELEASE
(msg) msg NULL
23
End Pipes