1. 11-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. 11-1 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. 11-1 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. 11-1 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. 11-1 Peergroup Services Services are accessible through the peergroup object: Java pipeService = peerGroup.getPipeService(); C Jxta_PG_get_pipe_service(group, &pipe); PeerGroup Services Membership Pipe Discovery Rendezvous Resolver Endpoint PeerInfo

7. 11-1 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. 11-1 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. 11-1 Java API 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 Package net.jxta.pipe

10. 11-1 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 Pipe Service – Java API

11. 11-1 Pipe Service – Java API ● 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 Usage Notes

12. 11-1 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. 11-1 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. 11-1 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. 11-1 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. 11-1 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. 11-1 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 ( InterruptedException 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. 11-1 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. 11-1 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.println("Reading in " + FILENAME); try { FileInputStream is = new FileInputStream(FILENAME); pipeAdv = (PipeAdvertisement) AdvertisementFactory.newAdvertisement( MimeMediaType.XMLUTF8, is); is.close(); } catch (Exception e) {} }

20. 11-1 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 msg=null; 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.currentTimeMillis()); System.out.println("Message received at :"+ date.toString()); System.out.println("Message created at :"+ msgElement.toString()); }

21. 11-1 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_timed_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. 11-1 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. 11-1 End – Pipes