Connectors > Smallworld > Smallworld Client

The same fileset used for the Smallworld Connector also provides Client functionality. This allows you to access the resources included in a DTS project from the Magik console or from Magik code.

Preparation

The Smallworld Client is enabled using the following steps:

•Open a Smallworld image - anything based on swaf (or swaf itself) is sufficient;

•Load the DTS Smallworld product and module in the image;

•Set the environment variables for accessing DTS:

Variable	Value
DTS_JAVA_HOME	The path to the Java binary directory
DTS_DIST_HOME	The path to the Smallworld Connector's jars directory
DTS_REDIS_HOST_NAME	The hostname or IP address of the Redis server (default is localhost)
DTS_REDIS_PORT	The port for the Redis server (default is 6379)

Being based on the Client Java Library, the Smallworld Client also responds to all other environment variables specified there.

If the security scheme is enabled in the DTS cluster, the Smallworld Client must also implement it. See Security Setup for details.

•Boot the client:

Magik> dts_manager.activate_consumer("<project_name>")

API

Once the Client is booted, you have access to the dts_remote_manager singleton exemplar where you can begin accessing resources.

Here are the currently available methods for dts_remote_manager:

Method	Result
connectors	equality set of the available connectors (dts_remote_connector), keyed by name

Each connector entry value is a dts_remote_connector, where you can access:

Method	Result
collections	equality set of the available collections for the connector (dts_remote_collection), keyed by native identifier
functions	equality set of the available routines for the connector (dts_remote_function), keyed by native identifier
topics	equality set of the available topics for the connector (dts_remote_topic), keyed by native identifier

For a dts_remote_collection, you can call:

Method	Result
get_record(_optional p_predicate)	the first record in the collection (that matches the predicate) p_predicate can be any regular Magik predicate or a dts_predicate
get_records(p_size, _optional p_predicate)	the first p_size records in the collection (that match the predicate)
get_record_stream(_optional p_predicate)	opens a stream on the collection (using the predicate) and returns it as a dts_remote_record_stream object
descriptor	returns the dts_type_descriptor (see below) object that describes the collection

For a dts_remote_topic, you can call:

Method	Result
subscribe(_optional p_group_id, p_properties)	subscribes to the topic and returns a dts_remote_record_stream object p_group_id must be a a string and p_properties can be a property_list or equality_property_list
push(p_key, p_msg)	pushes the p_key, p_msg pair to the Topic and returns DONE or raises a condition
push_lists(p_keys, p_msgs)	pushed all pairs p_keys[i], p_msgs[i] to the Topic and returns DONE or raises a condition
push_properties(p_properties)	pushes all key-value pairs in p_properties (which should be a property_list or equality_property_list) and returns DONE or raises a condition
descriptor	the descriptor for the topic as a dts_topic_descriptor
record_wrapper_descriptor	the dts_type_descriptor for the topic's stream records

For a dts_remote_record_stream, you can call:

Method	Result
get()	gets a single record from the stream
get_upto_n(p_size)	gets p_size records from the stream or how many are left if less than p_size
poll()	special implementation of get_upto_n() for Topics with no size and no has_more? impact
has_more?	whether or not there are more records to get from the stream (for Topic streams it always returns _true)
close()	closes the stream
unsubscribe()	same as close() but in Topic vernacular

For a dts_remote_function, you can call:

Method	Result
execute(_gather p_args)	executes the remote routine using the provided arguments (p_args) and returns the results
input_wrapper_descriptor	returns the dts_type_descriptor (see below) object that describes the inputs of the routine (in the form of a wrapper object whose attributes are the actual inputs)
output_wrapper_descriptor	returns the dts_type_descriptor (see below) object that describes the outputs of the routine (in the form of a wrapper object whose attributes are the actual inputs)

For remote collection and routine metadata, dts_type_descriptor objects provide the following:

Method	Result
key	the type key of the resource structure
attributes	a simple_vector containing the resource structure's attributes as dts_attribute_descriptor objects
stream_exemplar	the Magik exemplar used for wrapping resource structures of this type for ACPT data marshalling

Each dts_attribute_descriptor provides the following:

Method	Result
name	the name of the attribute
type	the type key of the attribute
category	the type category of the attribute
details	details regarding the attribute as a simple_vector of dts_attribute_detail objects, each answering to .name and .info
get_detail_info(p_detail_name)	returns the value of the detail identified by p_detail_name
can_be_unset?	returns whether or not the attribute can be _unset (i.e. the value of the "unset?" detail)
is_vector?	returns whether or not the attribute is a vector (i.e. the value of the "vector?" detail)

Each dts_topic_descriptor provides the following:

Method	Result
key	the native identifier of the topic
record_wrapper_type_key	the type key for the topic's stream record
key_type_key	the type key for the topic's key field
msg_type_key	the type key for the topic's msg field

Sometimes, attributes can have type keys that represent other slotted (structure) types. To access the dts_type_descriptor for any type key, you can use:

Magik> dts:dts_types_repository.types["<type_key>"].descriptor

Shutdown

To disconnect from DTS , use:

Magik> dts_manager.shutdown()

The Smallworld Client will automatically shutdown whenever quit() is invoked in the Smallworld session.

Other Considerations

•The DTS Smallworld Client keeps processes running in the background. In the event of an improper shutdown of the session, these processes can be left orphaned and impede subsequent client operations. In such situations, it is recommended that sw_magik and java processes running on the machine are audited and manually stopped as necessary.

•The Magik language is weakly typed, so there is not type enforcement on objects fed as parameters for the routines and collection operations DTS makes available. Most often, improper types will be met with ACPT exceptions generated by the Smallworld data marshalling engine that the Smallworld Connector employs.