10-1 JXTA Messages

10-1 Learning Objectives ● This module will help you... – Develop applications and services which exchange messages either through JXTA Pipes or directly with other peers

10-1 Message Components ● Ordered Sequence of Message Elements – Messages can have multiple parts – Ordered so you can do streaming ● Each element belongs to a namespace – Namespaces provide protocol segregation ● Two Default Namespaces – “”(empty) ● The default namespace – “jxta” ● For the JXTA Core Protocols

10-1 Message Element Components ● Name – UTF8 Character String – Need not be unique ● MIME Type – UTF8 Character String – Same as for web content or ● Data – Bytes is bytes... almost ● Signature/Hash – Another Message Element

10-1 Message Element Data ● We said: – Has a MIME-type ● “application/octet-stream” default – Uninterpreted Bytes Content ● Bindings may add Interpretation to Content – Streams, Files, XML Documents – Strings, Objects, Complex Data ● MIME-type is used as key – MIME parameters help the helper

10-1 Message Element Signature ● We said: – It is also a Message Element ● So.... – Element Name can be used – MIME-type can be used to describe format – Signature can contain arbitrary data – Helper can present signature as an Object ● JXTA does not validate signatures automatically

10-1 Message Serialization ● J XTA Bindings deal with messages in an abstract way ● To send a message it must be serialized ● Message Transports choose Wire Formats for efficiency, everyone else shouldn't care ● Wire formats follow rough requirements of RFC 1521:MIME ● XML, DIME, MIME, Java Serialization have all been used; default is “JXTA Binary Message Wire Format”

10-1 Messages Within JXTA ● Transport Layer – Messages are sent to a transport defined address – Simple point-to-point messaging – Only valid while the transport is valid ● Endpoint – Messages are sent to an abstract “Peer” address – Peer may move within the network, change transports, physical addresses, etc. ● Pipes – Messages are sent to an abstract “Pipe” address – May be served by a single peer, redundantly by any one of a number of peers or cooperatively by a federation of peers. This may also change over time.

10-1 Summary Thus Far... ● Messages are abstract containers ● Messages contain elements in namespaces ● Elements have a name, a type, data and a signature ● Messages are serialized for sending ● Bindings provide functionality for manipulating messages ● Messages are sent to Pipes, Peers, Transports

10-1 Using Messages with JXTA-C ● Message and Message Element API ● Building a message ● Sending a message ● Receiving a message

10-1 JXTA-C : Message API Jxta_message* jxta_message_new(void); – Create a new Message Jxta_message* jxta_message_clone(Jxta_message* msg); – Clone a Message, all elements are shared Jxta_status jxta_message_read(Jxta_message* msg, char const * mime_type, ReadFunc read_func, void *stream ); – Read a Message from a stream Jxta_status jxta_message_write(Jxta_message* msg, char const * mime_type, WriteFunc write_func, void *stream); – Write a Message to a stream Jxta_endpoint_address* jxta_message_get_{source|destination}( Jxta_message* msg); – Get the source or destination Endpoint Address of a Message Jxta_status jxta_message_set_{source|destination}( Jxta_message* msg, Jxta_endpoint_address *src); – Set the source or destination of a Message Jxta_status jxta_message_to_jstring(Jxta_message* msg, char const * mime_type, JString* string ); – Serialize a message in wire format to a JString

10-1 JXTA-C : Message API (cont.) Jxta_status jxta_message_add_element(Jxta_message* msg, Jxta_message_element* el); – Add a Message Element to a Message Jxta_status jxta_message_get_element_*(Jxta_message* msg, char const * qname, Jxta_message_element** el ); – Get a Message Element from a Message Jxta_vector* jxta_message_get_elements(Jxta_message* msg ); – Get a Vector of all the elements of a Message Jxta_vector* jxta_message_get_elements_of_namespace( Jxta_message* msg, char const *Namespace ); – Get a Vector of all the elements of a single namespace Jxta_status jxta_message_remove_element_*(Jxta_message* msg, char const * ns, char const * name ); – Remove a Message Element from a Message

10-1 JXTA-C : Message Element API Jxta_message_element* jxta_message_element_new_*( char const *ns, char const *ncname, char const *mime_type, char const *value, size_t length, Jxta_message_element* sig ); – Create a new Message Element from bytes Jxta_message_element* jxta_message_element_new_3( char const *ns, char const *ncname, char const *mime_type, Jxta_bytevector* value, Jxta_message_element* sig ); – Create a new Message Element from a share byte vector\ char const* jxta_message_element_get_namespace( el ); – Get namespace of an element char const* jxta_message_element_get_name(Jxta_message_element* el); – Get name of an element char const* jxta_message_element_get_mime_type( el ); – Get mime type of an element Jxta_bytevector* jxta_message_element_get_value( el ); – Get value an element as a shared byte vector Jxta_message_element* jxta_message_element_get_signature( el ); – Get signature element of element

10-1 JXTA-C : Building a Message const char * HELLO = “Hello World!”; const char * MIME = “text/plain; charset='UTF8'”; Jxta_bytevector* bytes = jxta_bytevector_new_1 ( 50 ); jxta_bytevector_add_bytes_at( bytes, HELLO, 0, strlen(HELLO) ); Jxta_message* msg = jxta_message_new(); Jxta_message_element* el1 = jxta_message_element_new_2( “jxta”, “hello”, MIME, HELLO, strlen(HELLO), null ); jxta_message_add_element(msg, el1); Jxta_message_element* el2 = jxta_message_element_new_3( “”, “hello”, MIME, bytes, null ); jxta_message_add_element(msg, el2);

10-1 JXTA-C : Sending A Message jxta_message_set_source( msg, localPeerAddr ); jxta_message_set_destination( msg, destAddr ); Jxta_status res = jxta_message_write( msg, “application/x-jxta-msg”, HTTP_SendFunc, httpStream );

10-1 JXTA-C : Receiving A Message msg = jxta_message_new(); res = jxta_message_read( msg, NULL, HTTP_ReadFunc, httpStream ); jxta_message_get_element_2( msg, “jxta”, “hello”, el1 ); Jxta_bytevector bytes = jxta_message_element_get_value(el1); char const * data = (char const *) malloc( jxta_bytevector_size( bytes ) + 1); jxta_bytevector_get_bytes_at( bytes, data, 0, jxta_bytevector_size( bytes ) ); data[jxta_bytevector_size( bytes )] = 0; printf( “Someone says : %s”, data );

10-1 Using Messages with JXTA-J2SE ● Message and Message Element APIs ● Building a message ● Sending a message ● Receiving a message

10-1 JXTAJ2SE : Message API Message(); – Construct a new message Object clone(); – Clone a message, elements are not copied boolean equals( Object target ); – Compare two messages String toString(); – Show message number and lineage void addMessageElement( MessageElement add ); – Add an element to default namespace void addMessageElement( String namespace, MessageElement add ); – Add an element to specified namespace MessageElement replaceMessageElement( String namespace, MessageElement replacement ); – Replace first occurrence of an element in specified namespace Iterator getMessageNamespaces( ); – Get list of namespaces in message MessageElement getMessageElement( String namespace, String name ); – Get a message element by name ElementIterator getMessageElements( ); – Get all elements of message ElementIterator getMessageElements( String namespace, String name ); – Get all elements matching name from namespace

10-1 JXTAJ2SE : Message API (cont.) ElementIterator getMessageElementsOfNamespace( String namespace ); – Get all elements of specified namespace ElementIterator getMessageElements( String namespace, MimeMediaType type ); – Get all elements of specified type from namespace boolean removeMessageElement( MessageElement remove ); – Remove specified element from any namespace boolean removeMessageElement( String namespace, MessageElement remove ); – Remove first occurrence of element from specified namespace void clear(); – Clear all elements from message synchronized long getByteLength(); – Get cumulative length of all elements int getMessageModCount(); – Number of times a message has been modified int getMessageNumber( ); – Get message number which was assigned at creation Iterator getMessageLineage( ); – Get list message numbers of ancestors of this message Object setMessageProperty( Object key, Object value ); – Associate a transient property with message Object getMessageProperty( Object key ); – Retrieve a transient property with message

10-1 JXTAJ2SE : Message Element API String toString( ); – Get String representation of element data String getElementName(); – Get name of the element MimeMediaType getMimeType(); – Get MIME type of message long getByteLength(); – Get length of element data in bytes byte[] getBytes( boolean copy ); – Get element data as byte array, optionally copied InputStream getStream() throws IOException; – Get element data as byte stream void sendToStream( OutputStream sendTo ) throws IOException; – Send element data to stream MessageElement getSignature(); – Get element signature as another element Object setElementProperty( Object key, Object value ); – Set transient property for element

10-1 J2SE: Building a Message Message msg = new Message(); MessageElement el1 = new StringMessageElement( “hello”, “Hello World!”, null ); msg.addMessageElement( el1 ); msg.addMessageElement( “jxta”, el1 );

10-1 J2SE: Sending a Message EndpointService endp = group.getEndpointService(); EndpointAddress destAddr = new EndpointAddress( dest, “welcome”, null ); Messenger messenger = endp.getMessenger( destAddr, null ); messenger.sendMessage( msg );

10-1 J2SE: Receiving A Message EndpointService endp = group.getEndpointService(); endp.addIncomingMessageListener( new EndpointListener() { void processIncomingMessage( Message msg, srcAddr, destAddr ) { MessageElement el1 = msg.getMessageElement( “jxta”, “hello” ); System.out.println( srcAddr + “ says: “ + el1 ); } }, “welcome”, null ); // wait for messages...

10-1 Summary ● Messages form the basis for JXTA and application protocols ● The same messages work for physical destinations, peers and pipes ● JXTA Bindings let you work with messages without worrying about wire representation

10-1 End – JXTA Messages