11-1

PipesPipes

11-1

Learning Objectives

● This module will help you...– Understand key JXTA pipe concepts– Understand how pipes work– Gain familiarity with the JXTA Pipe

Service API

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

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

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

11-1

Peergroup Services

Services are accessible through the peergroup object:

JavapipeService = peerGroup.getPipeService();

CJxta_PG_get_pipe_service(group, &pipe);

PeerGroup Services

MembershipMembership

PipePipe

DiscoveryDiscovery

RendezvousRendezvous

ResolverResolver

EndpointEndpoint

PeerInfoPeerInfo

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

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

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

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-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

11-1

Input Pipe & Output Pipe – Java APIInputPipevoid 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

OutputPipevoid close()

void send(Message msg)– Send a message to the network

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()

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()

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

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 ); }}

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(); }}

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" ); }

11-1

MsgListenerPublic 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) {}

}

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 SenderMessageMessageElement msgElement = msg.getMessageElement(null,

SenderMessage);

// Get messageif (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());

}}

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);

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;}

11-1

End – PipesEnd – Pipes