Adaptor nodes which are controlled outside of the SANDev environment
pose some unique deployment challenges, since they cannot be configured and
identified in the deployment configuration. They are essentially
"external" nodes which need to bridge into the main system somehow. There
is no one-size-fits-all solution to this problem, but this document seeks to
identify specific known cases and suggest possible approaches.
This document is limited to discussion of external adaptor nodes.
When creating an adaptor node to bridge between a SAND application and some
outside EIS, it is always easier if the adaptor node is part of the
deployment configuration and controlled off the
SandRoot. However this is not possible when the technology being adapted
itself needs to control the adaptor (such as an HTTP/HTML adaptor node
implemented as a servlet).
This document will evolve over time. To report additional cases or
request more info, please contact
info@sandservices.com.
One way to bridge between an external adaptor node and the SAND
application is through a gateway node. This is a node which is
reachable both through the standard SAND messaging mechanisms and through
an additional interface available to the external adaptor. The external
adaptor can then use the gateway as a bridge:
The gateway provides the external adaptor with access to generated
messaging methods, along with configuration and state parameters. By
keeping as much application logic as possible in the gateway, business
logic can remain independent of adaptor logic, and the adaptor node can
stay focused on being an adaptor.
As an example, consider WebUINode (an HTTP/HTML adaptor node
implemented as a servlet). By working in tandem with
TaskHeapUINode (a gateway node), the servlet-specific
processing is separated from communications processing. This is a flexible
approach that promotes modularity and even allows for multiple adaptors to
share a single gateway.
Without a gateway, the external adaptor would have to add additional
code and parameters to talk to the SandRoot, leading to separate code to
perform an existing function.
The remainder of this document is primarily concerned with strategies to
bridge between an external adaptor and a gateway node, or to make an
external adaptor node internal.
Gateway sharing is an architectural topic and beyond the scope of
this document, but it bears mentioning that gateways can also be configured
for cascading data flows, which also help localize business logic (and are
also very efficient, within optimized messaging).
Servlet access through singleton reference:
Probably the simplest way to bridge from an external adaptor node to a
gateway node is through a singleton reference provided by the gateway node.
For example a servlet adaptor node could be run in the same process space
as a gateway node, and then simply bridge by retrieving a reference. Since
the gateway can serve any number of incoming threads, a single gateway is
sufficient regardless of how many servlet instances are created.
The singleton reference is maintained by the gateway at startup and
shutdown, so that the servlet will retrieve a null reference when the
gateway is down. This provides a convenient way for the servlet to check
gross level system availability. Finer level information can be retrieved
from the status and statistics provided by the gateway when it is
available.
A singleton reference is completely adequate in many situations.
However it can be difficult to manage multiple gateways, and may be less
flexible when changing a configuration over time. A more flexible
alternative is access via named reference.
Servlet access through named reference:
When a configuration requires multiple gateway instances (due to multiple servers, alternate parameters to support of business logic, state information or other reasons), singleton references can cause problems for development and testing. Consider the relevant parts of two server configurations:
When this two-server config is run on a single machine (either temporarily for development/testing purposes, or due to a configuration change), the expected result is:
However, with singleton access semantics, both adaptorA and adaptorB
will both end up using the same gateway node. Whether it's gatewayA or
gatewayB depends on a lot of different things, but only one of them will
win the singleton initialization reference battle.
If the actual structure of message flow is important (testing multiple
simultaneous actions, statistical processing etc) then using singleton
access can lead to differences in development vs runtime behavior.
Although singleton access is powerful and convenient, it is inherently
dependent on the deployment configuration.
For functionally the same access, but without the potential problems, use a
SingletonAccessor to retrieve a node via its instance name. By using
a named reference, rather than a singleton, the data flow is preserved.
Retrieving the name of the gateway node:
When accessing a gateway via named reference, the servlet (like any external adaptor node) needs to know the instance name of its gateway. Again there is no one-size-fits-all solution. Some common approaches include:
The appropriate choice depends on your application, the complexity of
your deployment configuration, and other project requirements.
For a web UI, it is common to support N identical web servers
where N changes depending on load. From the perspective of a SAND
deployment configuration, the subpart of the total configuration
representing the webserver nodes needs to be replicated. In general, this
process is referred to as subconfig cloning.
Subconfig cloning can be done, provided:
Since most web UIs work by calling to retrieve information on demand,
and setting the SAND_SERVERNAME environment variable is unlikely to
conflict with any other server configuration requirements, cloning a
subconfig is straightforward. However it is strongly recommended that the
ServerDeclaration description include note stating that it is a
template, rather than a single server, to avoid any potential confusion.
Note that a deployment configuration utilizing subconfig cloning will
have multiple instances of the subconfig nodes at deployment (one instance
per server), and only one instance of each of these nodes during standard
development (where the entire config is run on a single server). Care must
be taken during application development and maintenance not to introduce
any explicit thread control (such as synchronized methods or data) that
would be innappropriate when the subconfig is replicated.