TIBCO.SMARTSOCKETS Namespace

Provides methods to access the messages cached by the SmartSockets Cache daemon.

This class allows the properties of the callback to be altered.

An instance of this class is created through a factory class by createConnClient method.

The server created with createConnServer must be running before the client is created, otherwise the client has no one to connect to, and will fail.

The implementing class for client connections uses 2 internal threads to send and receive messages. A reader thread constantly fills an inbound queue of message as traffic arrives. Calling next will pop the messages from the queue. A writer thread sends messages pushed onto the outbound queue by send when flush is called.

Any TipcIOException thrown by the methods of this class should be considered fatal. The connection instance should be discarded, and a new connection made in its place. The responsibility for maintaining a connection is up to the user application.

This class defines an error number which may be set for some errors.

This exception can be thrown by check, next, check, sendRpc, mainLoop, read, next, search, searchType, searchType

Note: There are two versions of each method in this class. When multiple RTserver connections are created by the createSrv method, then the version that requires a TipcSrv object as its first argument should be used. If the RTserver connection was created using the Srv property, then use the version that does not take a TipcSrv object as its first argument.

The publish-subscribe architecture of SmartSockets allows RTclient process to easily send messages to each other, independent of where they reside on the network. In addition to enabling easy development of distributed applications, RTserver, RTmon, and RTclient processes also have monitoring capabilities built in. These additional services help to examine detailed information about your project, as well as determining where processes are located in your network.

From within an RTclient, hundreds of pieces of information can be gathered in real time about all parts of a running SmartSockets project, including:

• RTclients -- names, message buffers, message traffic statistics, message types, options, node they are on, subjects subscribed to, and so on
• RTservers -- names, message buffers, message traffic statistics, connections, options, CPU usage, memory usage, node they are on, options, current time, and so on
• Subjects -- names, RTclients that are subscribing, and so on
• Projects -- names

This information can be either polled once to provide a one-time snapshot of information or watched to provide asynchronous updates when changes occur. A monitoring request can specify either a specific object or all objects matching a wildcard scope filter. The information is delivered to the requesting program in standard message types TipcMt_Fields.MON_* The fields of these message types contain the information the RTclient is interested in.

All monitoring of a SmartSockets project goes through RTserver. Typically, a request for particular information is sent to RTserver, then RTserver proceeds in one of these ways:

• RTserver accesses the information in its internal tables and sends it back to the requesting RTclient.
• RTserver forwards the request to another RTclient or RTserver, which retrieves the information and sends it back to the first RTserver (to be delivered back to the requesting RTclient).
• RTserver notifies RTclient or RTserver to send the information whenever it changes. When it does change, RTserver receives the information and sends it to the RTclient that made the original request.

To initiate a monitoring request in an RTclient, call one of the functions in the TipcMon class. This sends a message of type TipcMt_Fields.MON_*_POLL_CALL or TipcMt_Fields.MON_*_SET_WATCH to the RTserver. The information is returned to the program by an RTserver using a TipcMt_Fields.MON_*_POLL_RESULT or TipcMt_Fields.MON_*_STATUS message. When the information returns, an RTclient message process callback (created with addProcessCb can be used to process the message.

The ss.monitor_scope option specifies the level of interest for SmartSockets monitoring in those monitoring categories with no parameters (such as RTclient names poll) or an RTclient or RTserver parameter of ALL (such as subject subscribe watch). ss.monitor_scope acts as a filter that prevents a large project from overloading a monitoring program. The default is "/*", which matches all subject names at the first level of the hierarchical subject namespace. All monitoring information is enabled (all filtering is disabled) if ss.monitor_scope is set to "/...", which matches all names. The value "/..." should be used with caution on large projects, as this gathers monitoring information for the entire project, and may cause noticeable peformance degradation.

Polling for information allows you to receive a one-time snapshot of information. Polling can be done at regular time intervals by issuing poll requests repeatedly. All polling of a project goes through RTserver. Typically, a request for particular information is sent to RTserver, then RTserver retrieves the information from its internal tables, from other RTservers, or from RTclients and sends it back to the requesting program.

When the results of a poll are returned in a TipcMt_Fields.MON_*_POLL_RESULT message, the message is processed in one of these two ways:

• blocking and using the searchType method to search for the message containing the poll results
• using an RTclient message process callback (created with addProcessCb

Typically, after performing a one-time poll for information, the program blocks and waits for the result before continuing. An example of this is to find out if any RTclients are subscribing to a subject before sending a message. When polling often, or watching for information, using callbacks is usually the preferred method, as it is unclear when the monitoring results may be returned to the program.

Watching information is very different from polling. When watching information, the RTclient that initiated the watch is notified asynchronously, through a message, whenever the item(s) of interest changes. All watching of a project goes through RTserver. Typically, a request to watch particular information is sent to RTserver. RTserver then notifies the process holding the information (the same RTserver, a different RTserver, or an RTclient) that a program is interested in watching the specified information. Then, whenever the information changes, the process holding the information sends it back to the requesting program in a message. Unlike polling, which is a one time request for information, watching causes status messages to continue to be sent until watching is turned off for that particular information.

To set up watching in your program, you set the watch status for the type of information of interest to true. In a similar fashion, watching is turned off by setting the watch status to false.

When the results of a watch are returned in a TipcMt_Fields.MON_*_STATUS message, the message can be processed using an RTclient message process callback (created with addProcessCb). Using callbacks to process the status messages that are returned as the result of a watch being enabled is the recommended method for processing watch results. The main reason for this is that the messages arrive asynchronously. It is often unclear as to when or how often the information may change.

Note: There are two versions of each method in this class. When multiple RTserver connections are created by the createSrv method, then the version that requires a TipcSrv object as its first argument should be used. If the RTserver connection was created using the Srv property, then use the version that does not take a TipcSrv object as its first argument.

Messages can only be created from the TipcSvc factory class with createMsg.

A message consists of a type TipcMt, properties, and zero or more fields. The field types are used to convert the field data from the format used by the sending platform to the format used by the receiving platform (byte order, etc.). These types are:

            BINARY - an array of uninterpreted bytes (byte[])
            CHAR   - a character (char)
            STR    - an array of signed bytes representing a string (String)
            INT2   - a signed 2 byte integer (short)
            INT4   - a signed 4 byte integer (int)
            INT8   - a signed 8 byte integer (long)
            REAL4  - a 4 byte real number (float)
            REAL8  - an 8 byte real number (double)
            REAL16 - a 16 byte real number (unsupported by .NET)
            MSG    - an embedded SmartSockets message (TipcMsg)
            BOOL   - a boolean value (boolean)
            BYTE   - a single byte (byte)
            UTF8   - an array of bytes representing a UTF-8 encoded string (String)
            XML    - a XML object (TutXml)
            OBJECT - a .NET object (Object)
            

A helper class that implements the Enumeration interface and returns TipcMsgEnumeratorElement when the nextElement method is invoked.

This is the Object that is returned when nextElement is invoked. This object can then be used to retrieve the appropriate field based on type.

            TipcMsg msg = null;
            char c = 'a';
            short short_value = 10;
            TipcMsgEnumerator msgEnumerator = null;
            try {
              msg = TipcSvc.createMsg(TipcMt_Fields.INFO);
              msg.appendChar(c);
              msg.appendUnknown(TipcMsg_Fields.FT_INT4);
              msg.appendInt2(short_value);
              msg.addNamedStr("test str name", "test str value");
            
              msgEnumerator = msg.Enumerator;
            
              TipcMsgEnumeratorElement enum_element = null;
              while(msgEnumerator.hasMoreElements()) {
                enum_element = (TipcMsgEnumeratorElement)msgEnumerator.nextElement();
            
                System.out.println("index = " + enum_element.Index);
                System.out.println("isNamed = " + enum_element.Named);
                if (enum_element.Named) {
                  System.out.println("Named field's name = " + enum_element.Name);
                }
                if (enum_element.Type == TipcMsg_Fields.FT_CHAR) {
                  System.out.println("CHAR VALUE = " + enum_element.Char);
                }
                if (enum_element.Type == TipcMsg_Fields.FT_INT2) {
                  System.out.println("INT2 VALUE = " + enum_element.Int2);
                }
                if (enum_element.Type == TipcMsg_Fields.FT_STR) {
                  System.out.println("STR VALUE = " + enum_element.Str);
                }
              }
            }  catch (TipcException e) { System.out.println(e.Message); }
            

This interface is used by TipcMt objects returned from the TipcSvc factory class to createMt user-defined message types and to lookupMt both user-defined messages types and standard SmartSockets message types.

The identifiers for the standard SmartSockets message types are contained in the TipcMt_Fields structure.

Note: All user-defined message type numbers must be greater than zero. All SmartSockets-defined message type numbers are less than zero. Zero is not a valid message type number.

The options database consists of a table of these objects. When a Property database is loaded, these objects are automatically created.

The value of all options is a String. However, these may be extracted as a boolean, an int, a double, or a Vector of Strings if the value contains a comma-separated list. Also, String values can be verified against a list of legal values (Enum), or mapped to a list of integers (EnumMap).

To set the value of a standard SmartSockets option, you may either get the TipcOption instance for that option, or you can use a convenience method:

            TipcOption opt = Tut.getOption("ss.project");
            opt.setValue("foo");
            - or -
            Tut.setOption("ss.project", "foo");
            

Options must be created before they can be set, retrieved, or removed. All of the standard SmartSockets options are created when the process starts up. If you wish to add your own options, you must use Tut.createOption to create the option and add it to the options table:

            TipcOption opt = Tut.createOption("foo", "bar");
            ...
            TipcOption opt = Tut.getOption("foo");
            String s = opt.getValueStr();
            - or -
            String s = Tut.getOptionStr("foo");
            

If you wish to create an Enum or EnumMap option, you must then add a list of legal values to the option with addEnumLegalValue and addEnumMapLegalValue. Enums and EnumMaps cannot be intermixed; a given option must support one or the other, not both:

            TipcOption opt = Tut.createOption("enum_foo", "baz");
            opt.addEnumMapLegalValue("baz", 0);
            opt.addEnumMapLegalValue("bat", 1);
            opt.addEnumMapLegalValue("bark", 2);
            ...
            TipcOption opt = Tut.getOption("enum_foo");
            int i = opt.getValueEnumMap();
            

The single, global RTserver connection instance of this class is returned through Srv.

This is a subclass of TipcConnClient, and much of the interesting functionality is provided by that class.

An RTserver must be running before any attempt is made to connect to it. This class will automatically try to connect to any RTservers that appear in the"ss.server_names" option, trying each RTserver in turn until it successfully connects to one.

A static factory class for the TipcMt, TipcMsg, TipcConnClient, TipcConnServer, and TipcSrv interfaces. Objects of the required concrete classes that implement these interfaces are created with this class.

For example, to create a connection to the RTserver and to create and send a SmartSockets message on the connection, you would do the following:

            // get the connection to the RTserver from the factory
            TipcSrv srv = TipcSvc.Srv;
            
            // create an INFO message from the factory
            TipcMsg msg = TipcSvc.createMsg(TipcMt_Fields.INFO);
            
            // publish the INFO message to the "/foo" subject on the connection
            msg.setDest("/foo");
            srv.send(msg);
            

All handling of settable global options is done here and in the TipcOption class. Options may also be set on a per connection basis through the TipcConnClient interface.

Options are loaded using the Properties mechanism, which requires text files containing key/value pairs. These files can either be loaded from the local filesystem, or remotely via a URL.

The keys in a property file are, by convention, stated in a heirarchy using dots as a separator. All SmartSockets options are in the "ss" hierarchy, so all of them start with "ss.". An example of an options file would be:

            ss.project: sat1
            ss.server_auto_connect: false
            ss.unique_subject: node1
            

Server create callbacks are called when an RTclient creates either a full or warm connection to the RTserver. If an RTclient creates and destoys its connection to the RTserver many times, it should use server create callbacks to create the other callbacks needed in the connection to RTserver.

Connection default callbacks are executed while processing a message if a process callback specific to the message type and/or destination has not been called. Default callbacks are useful for processing unexpected messages or for generic processing of most message types. For example, you have a client process to manage and display alarm messages. The only process callback you would want for that client process would be for messages of type "alarm". You could then write a default callback to process any other type of data received and display a warning.

Server destroy callbacks are called when an RTclient destroys its connection to the RTserver, leaving either a warm connection or no connection. Server destroy callbacks are the opposite of server create callbacks.

Server destroy callbacks are useful for RTclients that need to know when the connection to the RTserver no longer has a valid socket, such as RTclients that are also GUI programs.

Connection error callbacks are executed when an unrecoverable error occurs. These errors include socket problems and network failures such as:

• A read timeout has occured and the keep-alive then failed.
• A write timeout has occured.
• A read operation on the connection's socket failed. The most common cause of this error is that the process at the other end of the connection has destroyed its connection, which closed the socket.
• A write operation on the connection's socket failed. The most common cause of this error is that the process at the other end of the connection has destroyed its connection, which closed the socket.

TipcSrv automatically registers a default error callback that attempts to reconnect to the RTserver when the connection is lost. This default error callback may be replaced by first getting the default error callback with DefaultErrorCb, removing it with removeErrorCb, and adding your own error callback with addErrorCb.

Connection process callbacks are executed while processing a message. This callback type is the most frequently used. A process callback can be called for a specific type of message, on a specific subject (destination), or created globally and called for all messages. For example, a process callback can be created for the INFO message type. When any message of that type is processed by calling process or mainLoop, the process callback is called. If the process callback is created globally, it is called for all INFO messages as well as any other type of message.

Connection queue callbacks are executed when a message is inserted into or deleted from a connection's message queue. Queue callbacks are useful for watching the messages that have been read in from a connection's socket and inserted into the message queue, but not yet processed.

Connection read callbacks are executed when an incoming message is read from a connection's socket into the read buffer and first unpacked into a message. Read callbacks are most commonly used for writing incoming messages to message files.

Write buffer change callbacks are executed when data is either flushed from the write buffer or written into write buffer THROUGH the message interface (i.e. with send(msg)) ONLY.

The TipcDataOutput write() methods themselves are accessible throughout this package. If data is added to write buffer by calling them directly, this will NOT trigger the write buffer change callbacks. This is because the purpose of the write buffer change callback is to allow the sending of client congestion messages. When the callback is triggered, if the congestion threshold has now been met, a congestion message will be sent out. This means that triggering the callbacks may result in data being written into the write buffer.

This, of course, cannot be allowed to happen in the middle of a message write. A congestion message must only be allowed to be written into the buffer when the logical write (not just the write() method call-- a logical write can consist of more than one call to the write() method; see TipcMsgImpl.writeWire() for an example) has been completed. Therefore, the writing of a message will trigger the write buffer change callback only AFTER the full message has been written (which involves possibly mutliple calls to the write() method).

By contrast, if the write() methods are invoked directly, outside of the message writing framework, there is no way to know, at the end of the write() method, whether or not the logical write has been completed. Therefore, there is no way to know if congestion message data may be safely added to the buffer at that time.

Connection write callbacks are executed when an outgoing message is sent to a connection (that is, copied to a connection's write buffer). Write callbacks are most commonly used for writing outgoing messages to message files.

Messages can only be created from the TipcSvc factory class with createMsg.

A message consists of a type TipcMt, properties, and zero or more fields. The field types are used to convert the field data from the format used by the sending platform to the format used by the receiving platform (byte order, etc.). These types are:

            BINARY - an array of uninterpreted bytes (byte[])
            CHAR   - a character (char)
            STR    - an array of signed bytes representing a string (String)
            INT2   - a signed 2 byte integer (short)
            INT4   - a signed 4 byte integer (int)
            INT8   - a signed 8 byte integer (long)
            REAL4  - a 4 byte real number (float)
            REAL8  - an 8 byte real number (double)
            REAL16 - a 16 byte real number (unsupported by .NET)
            MSG    - an embedded SmartSockets message (TipcMsg)
            BOOL   - a boolean value (boolean)
            BYTE   - a single byte (byte)
            UTF8   - an array of bytes representing a UTF-8 encoded string (String)
            XML    - a XML object (TutXml)
            OBJECT - a .NET object (Object)