The Java Client Library is made up of two layers:
a basic layer, with package name "com.lightstreamer.ls_client",
which exposes a simple interface to communicate with Lightstreamer
Server, by opening and closing a connection, performing
subscriptions and unsubscriptions and receiving data andn advanced layer, with package name "com.lightstreamer.ls_proxy",
which builds upon the basic layer and exposes a "data oriented"
interface, in which the access to Lightstreamer Server is hidden
and optimized.
Clients can choose which layer to lean on, by creating an
object of type
LSClient.
or an object of type
LSProxy
Each LSClient and LSProxy object manages a private connection
to Lightstreamer Server.
Managing a connection through the "com.lightstreamer.ls_proxy"
interface offers some useful features, but requires that the
Metadata Adapter run by the Server is LiteralBasedProvider
or one with a similar behaviour.
The "com.lightstreamer.ls_proxy" interface offers:
- The decoupling of subscription and connection operations:
the subscriptions are always meant as subscriptions "to the
LSProxy object", not "to the Server"; the LSProxy object is
responsible of forwarding the subscriptions to the Server
and reforwarding all the subscriptions whenever the connection
is closed and then reopened.
- The automatic recovery from connection failures.
- The minimization of subscriptions toward Lightstreamer Server,
through the aggregation of similar subscriptions.
- The caching of fields state: field values coming from the
Server as "UNCHANGED" are resolved against the current value
of the field; with each update event, the user listeners can
see the old and the new value of each field.
A full explaination of the "com.lightstreamer.ls_proxy"
interface features can be found in the
LSProxy class javadoc.
With the "com.lightstreamer.ls_proxy" interface, each Item
to be subscribed to through Lightstreamer Server has to be
represented by an object of type
Item,
where all subscription preferences (e.g. mode, frequency
and so on) can be specified.
The subscription is made through the
subscribeItem or
subscribeItems method of the LSProxy object, where all the
subscribed field names have also to be specified.
The same Item can be subscribed more than once, with the same
or different subscription preferences and fields. In any case,
it should always be wrapped by different
"com.lightstreamer.ls_proxy.Item" objects.
The "com.lightstreamer.ls_proxy" interface is optimized for
the following scenario: the same Item can be subscribed in MERGE
mode by multiple internal consumers, with quite different field
schemas, and in RAW and DISTINCT mode, each one by at most one
internal consumer.
In this scenario, the subscription management policy ensures
small response times and bandwidth usage.