PMP Protocol Specification

This document provides a detailed technical description of the ProSyst Message Protocol.

Contents:

• Communication Levels
  • Messages
  • Operations
• Operations
• Connect
• Disconnect
• Get Reference
• Get Reference by ID
• Get Method
• Invoke Method
• Invoke Method with Remote Reference Arguments
• Dispose
• Add Listener
• Remove Listener
• Connect Reply
• Reference
• Methods
• Method
• Object
• Add/Remove Listener Success
• Add/Remove Listener Failure
• Event Type Registered
• Event
• Transferred Data Types
  • Primitive Data Types
  • Objects
• References

Communication Levels

PMP has two communication level - message and operation. An operation may be a request as well as a response. An operation is transported over the network using several messages.

Messages

Each message carried by PMP has the following structure:

• Message ID - A 2 bytes long field that contains the unique identifier of the message. For requests the Message ID starts from 101. A PMP Service replies to a request with the same Message ID as the one in the request. Posted events have Message IDs from 0 to 100.
• Message Length - A 2 bytes long field that indicates the length of the message.
• More - A 1 byte long flag that shows if this is the last message of the current operation. If this is the last message, More is 1.
• Message Body - The field that holds the message data.

Operations

Every operation in PMP consists of one or more messages. All messages within a single operation have the same Message ID.

• Operation ID - A 1 byte long field that holds the unique identifier of an operation.
• Operation Body - The field that carries operation-specific information.

Invoking Methods. PMP is a powerful means for remote invocation of service methods. The protocol point-to-point communication includes the following operations:

1. The PMP point on framework A issues a Connect command to connect to the PMP point on framework B which authenticates it. Currently, a user name and a password provide authentication.
2. The PMP point on framework B examines the login parameters of the point on framework A, and if the latter is a valid framework user, sends Connect Reply.
3. To get a reference to a service by its interface and a search filter, a Get Reference request is sent.
4. The PMP point on framework B point sends back the requested reference by performing a Reference operation.
5. To invoke a method or methods, Get Method is issued.
6. The PMP point on framework B returns the requested method or methods if such exist in a Method or Methods reply.
7. To invoke the method, the PMP point on framework A issues an Invoke Method request.
8. The PMP point on framework B returns the result as primitive data or as a serialized object in an Object response.
9. After you receive all necessary data, you can dispose engaged resources on the PMP point through a Dispose command.
10. If there is an error in the PMP point while executing requests, it sends a Disconnect command to terminate the connection.

Receiving Events. To receive a notification about certain events from another framework, a PMP point should subscribe an event listener. Next, it is able to perform specific operations in response.

Events are standard and custom. Standard events are about the mBS framework, bundles and services. Custom events are created by the PMP consumers and are posted in more specific situations.

Supposing that you have already connected to a PMP point, the following message sequence takes place:

1. To subscribe an event listener to an event type, the PMP point sends an Add Listener request.
2. If the listener is successfully registered, the point receives Add Listener Success. If the registration fails, it gets Add Listener Failure.
3. On an event on the remote framework, the PMP point is notified through Event.
4. To dismiss the event listener, the PMP point sends a Remove Listener request.
5. For confirmation, the PMP point gets Remove Listener Success. For an error, it receives Remove Listener Failure.

Refer to the "Registering Event Listeners" section of the PMP Bundle description for information about using Java for event subscription.

Operations

Connect

• Operation ID: 129.
• Operation Body:

  

• Login - A dictionary of the user account properties required by the Simple Login service. Initially, login contains the user name and password.
• Standalone - When 1, the other side is running on an OSGI framework.

Disconnect

• Operation ID: 64.
• Operation Body: contains only the error message as a string.

Get Reference

• Operation ID: 130.
• Operation Body:



• Interface - The class name of the interface of the requested service.
• Filter - The search filter.

Get Reference by ID

• Operation ID: 134.
• Operation Body:



• Interface - The class name of the target service.
• Filter - The search filter.
• Bundle ID - the ID of the bundle that registered the service.

Get Method

• Operation ID: 160.
• Operation Body:

• Object ID - The unique identifier of the object whose method(s) will be retrieved.
• Method Name - The name of the target method. If all methods of an object are requested, this field is empty.
• Arguments - The number of arguments that will be used to invoke the method.
• Argument 1 Type ... Argument n Type - The class names of the method arguments.

Invoke Method

• Operation ID: 132.
• Operation Body:



• Object ID - The unique identifier of the object on which the method is invoked.
• Method ID - The unique identifier of the invoked method.
• Serialization - A flag that specifies how to return the method result. If the flag is 1, the result will be a serialized object. If it is 0, the result is received as a reference.
• Argument 1 ... Argument n - The arguments of the invoked method. They are always serialized.

Invoke Method with Remote Reference Arguments

This operation takes place when a method is invoked with arguments provided as remote reference objects.

• Operation ID: 140
• Operation Body:

  

  The operation body is similar to the one of the Invoke Method operation above. The difference is that before each argument there is a Reference flag. If the flag is 0, then the argument that follows is a remote reference.

Dispose

• Operation ID: 192.
• Operation Body: contains only the Object ID as an integer value of the object to dispose. This operation provides remote garbage collection.

Add Listener

• Operation ID: 136.
• Operation Body:



• Type - A 1 byte long field that can be:
  • 1 - for adding a bundle listener;
  • 2 - for adding a service listener;
  • 3 - for adding a framework listener;
  • 4 - for adding a custom event listener.
• Event Type - An optional part that exists only if Type is 4, i.e. when adding a custom event listener. Event Type specifies the type of the custom event the listener wants to receive.

Remove Listener

• Operation ID: 152.
• Operation Body: it is the same as the body of the Add Listener operation.

Connect Reply

• Operation ID: 1.
• Operation Body:



• Success - A flag that indicates connection success. If the connection is successful, it is 0. Otherwise, the flag is 1 and is followed by an error message. In such case, the connection is closed.
• Error Message - An optional field that presents if the connection fails. It contains a message about the error that caused the failure.

Reference

The Reference operation returns objects by reference.

• Operation ID: 2.
• Operation Body:



• Object ID - The unique identifier of the reference. If this field is 0, there is an error on the executor. An error message is appended in Error Message.
• Error Message - An optional field that exists only if the operation fails. It contains a message about the error that caused the failure.

Methods

• Operation ID: 32.
• Operation Body:



• Length - The length of the transmitted information.
• Method Description 1 ... Method Description n - descriptions of the requested methods. Each Method Description has the following structure:



• Method Name - the name of the method.
• Return Type- the method return type.
• Arguments - the number the method arguments.
• Argument Type - the type of the each method argument.

Method

• Operation ID: 96.
• Operation Body:



• Method ID - The unique identifier of the requested method. If this field is 0, then an error has occurred while retrieving the method. In this case, a field with an error message follows (Error Message).
• Return Type - The return type of the method.

Object

The Object operation returns method's results by value.

• Operation ID: 4.
• Operation Body:

or

The first byte indicates whether the invoked method has thrown an exception or not. If it is 0, then there has been an exception, and an error message follows. If it is 1, then the operation is successful and the result is in its body.

Add/Remove Listener Success

• Operation ID: 8.
• Operation Body: none.

Add/Remove Listener Failure

• Operation ID: 24.
• Operation Body: contains only the error message as a string.

Event Type Registered

This operation confirms the registration of a custom event.

• Operation ID: 48.
• Operation Body: contains a string with the new event type.

Event

• Operation ID: 16.
• Operation Body: has several modifications according to the first field of the body. This field indicates the event type and can be:
  • 1 - bundle event.

  

  • Type - The specific type of the bundle event. It shows that a bundle was started, stopped and so on.
  • Bundle ID - The ID of the bundle related to the event.
  • 2 - service event.

    

    • Type - The specific type of the service event.
    • Length - The number of the interface names of the service that originated the event.
    • Interface Name 1 ... Interface Name n - the names of the interfaces under which the service is registered.
  • 3 - framework event.

    

    • Type - The specific type of the framework event. If type is BasicEvent.F_ERROR, the operation body contains the ID of the bundle that caused the error and a message about this error.
    • Bundle ID - An optional part that exists if an error in the framework is indicated as described above.
    • Error Message - An optional message about the framework error.
  • 4 - custom event.

    

    • Event Type - String identifier of the custom event. This is the string that was used to register or unregister a custom event listener.
    • Bundle ID - The ID of the bundle from which the event derived.
    • Custom Event - The event object.

Transferred Data Types

PMP uses several data types for information transfer.

Primitive Data Types

The PMP supports the int, byte and long primitive types. Such data is carried as with java.io.DataInputStream and java.io.DataOutputStream.

Objects

Each object is transported by PMP in the following format:

• null Flag - A flag that indicates whether the object exists or not. If the null Flag is 0, then the object is null and the rest of the message is missing.
• Name Flag - If the Name Flag is 1, then a Class Name follows.
• Class Name - The class name of the transferred object and the field exists only if Name Flag is 1.
• Object - The encoded object.

Primitive Type Wrappers. Primitive type wrappers are objects that represent primitive types of data: java.lang.Integer, java.lang.Boolen, and so on. The primitive value of such objects is extracted and transported as with java.io.DataOutputStream.

Strings. PMP transfers java.lang.String objects as bytes in the following format:

• Length - the number of bytes.
• Bytes - the bytes that represent the original string.

Arrays. PMP carries arrays using the following format:

• Length - The number of array elements.
• Element 1 ... Element n - The element data. Each element has the following structure:

  

  • null Flag - A flag with value 0 that indicates if the corresponding element is null. In such a case, the Object field is missing.
  • Name Flag - If the Name Flag is 1, then a Class Name follows.
  • Class Name - The class name of the transferred element and the field exists only if Name Flag is 1.
  • Object - The encoded object element.

com.prosyst.util.io.Externalizable. Developers may implement the Externalizable interface to serialize objects. PMP transfers only data that is assigned in the writeObject and readObject methods.

java.io.InputStream. PMP delivers data in java.io.InputStream objects as bytes in the following format:

• Length - The number of bytes to carry. The value of this field is taken from the available method.
• Bytes - The data bytes. Their value is retrieved with call to the read(byte[]) method.

java.io.Serializable. PMP delivers Serializable objects through the standard java.io.ObjectInputStream and java.io.ObjectOutputStream.

References

• PMP Bundle description.
• PMP Service API Documentation.
• Event API Documentation.
• I/O Utilities API.

RPC Category