After creating a configuration file, we can easily initialize the middleware using the file:

PSPort psPort = PSPortFactory.getPort("file " + CONFIG_PATH)

Where CONFIG_PATH is the path to the configuration file, for example:

PSPort psPort = PSPortFactory.getPort("file myConfig.ini");

or maybe you may want to hardcode the configuration:

//This defaults to address 127.0.0.1 and port 5434
PSPort port = PSPortFactory.getPort("PSPortTCP");

This initialization will return a PSPortTCP or a PSPortSSL object, depending on the configuration, but the underlying implementation will be transparent to the user, who should only need to use the PSPort interface. Once the PSPort is instantiated without throwing an Exception, the connection will already be established (and in the case of SSL, the handshake will also have been successful)

After connecting to the broker, you are free to use the methods of the API! The main methods of the API are:

• void disconnect(): This method will close the connection to the broker, leaving the PSPort unusable.
• void subscribe(String ... topics): This method will subscribe the client to a list of topics.
• void unsubscribe(String ... topics): This method will unsubscribe the client from a list of topics.
• void publish(MessagePublish publication): This method will publish a message on a topic. This message is created using one of the available MessagePublish constructors (see below).
• MessagePublication getLastSample(String topic): This method will return the last received message (a MessagePublish object) from a specific topic. Note that you need to be subscribed to the topic to actually receive the messages, this method only polls the locally stored messages.
• void addTopicListener(TopicListener listener): This method will add a listener in order to notify the implementation that a new message has arrived. Alternatively, you can poll with getLastSample(String topic).
• void removeTopicListener(TopicListener listener): This method removes the listener added before.
• String[] getAvailableTopics(): This method will return the available topics in the broker. If a topic is not listed here, getLastSample(String topic) will always return null. Conversely, if a topic is listed here, getLastSample(String topic) will never return null.

Message object has two variants:

• MessagePublish to send a message to the broker.

  • Contains:

    • The charset for the topic (ASCII String).
    • The topic of the message (String).
    • The actual data (byte[], you may send an Object via serialization).

  • How to create and send:

    • myPsPort.publish(new MessagePublish(String topic, byte[] data, String charset));
    • myPsPort.publish(new MessagePublish(String topic, byte[] data)); //Assumes charset = "UTF-8"
    • myPsPort.publish(new MessagePublish(String topic, Object data, String charset)); //Serializes data with ArrayUtils.serialize(Object obj)
    • myPsPort.publish(new MessagePublish(String topic, Object data)); //Assumes charset = "UTF-8" and serializes data

  • How to NOT create:

    • new MessagePublish(byte[] origin) is for deserialization when received from the network, you may NOT want to use this.

• MessagePublication received from the broker after subscribing to its topic when another client sends it.

  • Contains:
    • The charset for the topic and sender (ASCII String).
    • The topic of the message (String).
    • The actual data (byte[], you may receive an Object via serialization).
    • The identifier of the client who sent the message (String) (IP:port if plain TCP, or certificate name if SSL).
    • The timestamp of the message (set by the broker when received) (long) (System.currentTimeMillis()).
  • How to get data from a MessagePublication:
    • msg.getCharset()
    • msg.getTopic()
    • msg.getTimestamp()
    • msg.getSender()
    • msg.getData() //Get the data as a raw byte[]
    • msg.getDataObject() //Get the deserialized data Object, equivalent of ArrayUtils.deserialize(msg.getData())