The SC supports message exchange between requesting applications (client) and responding applications (server), providing services. Client and server are the logical communication endpoints. The SC always acts in between the communicating partners, controlling the entire message flow.

One server application may provide one or multiple service. Therefore multithreaded or multisession servers are necessary. Multiple server applications may run on the same server node, each providing different services. Services are independent on each other.

Download Service Connector Documentation

• Service oriented architecture
• Flexible connection topology concept (individual cascading)
• Stateful Session Service Communication (session oriented)
• Stateful Publish Service Communication (subscription oriented)
• Synchronous, asynchronous message delivery
• Upload / Download files Service
• HTTP Redirection service
• TCP/IP or HTTP communication protocol
• Support of large messages exchange
• Message caching
• Cache Coherency Model
• Message fan-out mechanism
• Support for single and multisession server
• Java SC API for Client and stand-alone Server
• Java SC Server API for Tomcat integration (servlet based)
• WebUI for monitoring
• Command line util to manage SC
• Utilities to run SC as Windows service or unix deamon
• Open protocol SCMP (Service Connector Message Protocol)

Client application, server application and the SC may reside on the same node or on separate nodes. The connection can either utilize HTTP protocol or direct TCP/IP communication. No assumption about the physical network topology is done. Multiple firewalls can be located on the path between the communicating partners. The SC supports following connection topology:

• Client↔SC↔Server = Direct connection
• Client↔ SC↔SC↔Server = Connection via cascaded SC.

Multiple SC may be placed on the path between the client and service.

Different connection topology types from left to right:

• Client connected to one service
• Client connected simultaneously to SCs and two services
• Two clients connected to one service via cascaded service and cascaded SC
• Two clients connected to three services via cascaded service on different server nodes
• Complex configuration with three clients connected to three services on different server nodes via cascaded SCs and SC offloaded to its own node. One server can be registered to multiple services and different SCs. However this is possible for multisession servers only.

Limitation: The same service can be accessed by one SC only. When the same service should be used on different nodes, it must have a different name (e.g. node suffix).

Two different transport types can be individually configured for each network segment i.e. between the Client↔SC, SC↔SC or SC↔Server.

• HTTP
  Such connection may pass screening firewalls and is appropriate for communication within the customer organization e.g. Client↔SC or SC↔SC.
• TCP/IP
  Such connection would not pass firewalls without explicit security rules. It is useful for connection within the same node e.g. SC↔Server.

The SC is relaying on a service model to route packages and to adapt communication behavior.

Therefore an SC instance needs a service definition. The SC supports 3 types of services.

• Session Service (request / response service)
• Publish Service (subscribe / publish service / mesage fan-out)
• File Service (file transfer service)
• HTTP Redirection Service

Session Service

A session service is a stateful request/response communication initiated by the client. For session services the client and the server exchange messages in context of a logical session through the SC.

The client controls the creation and deletion of a session and so the allocation of a server. When the client starts the session, SC allocates a server instance for this session. The SC acts like a message broker and is never a direct executor of the service. The client may have multiple concurrent sessions to the same or to different services. Only one pending request per session is possible at a time.

Publish Service

Publishing services allows the server to send single message to many clients through the SC. In order to receive a published message, the client must subscribe to a service.

The client sends a subscription mask to the service, and declares its interest on certain type of a message. The application server providing the message contents must designate the message with a mask. When the message mask matches the client mask, the message will be sent to the client. Multiple clients may subscribe for the same service at the same time. In such a case multiple clients can get the same copy of the message. A message that does not match any client subscription is discarded. Multiple server instances may publish their messages to the same service. (Not allowed when large messages are published!) All services are independent on each other.

Message Fan-Out

For publishing services SC implements message fan-out in cascaded configurations. Message published by a server is distributed to the clients on the most upper cascade level. Between the SC nodes the message is transported only once. This allows efficient distribution of a message to large number of clients within a very short time.

The efficient usage of the fan-out is dependent on the design and structure of the subscription mask. It must contain items reflecting the cascade hierarchy.

File Service

The file service supports download, upload and listing of files to, from a server. The client initiates the upload or download of the file over a service.

The SC configuration maps a service name to a directory on the server (virtual host). This enables the client to upload or download file to different server locations. Operations are synchronous and client can initiate only one file transfer over one service at the same time. PHP is required on the Web Server in order to support file services. The provided PHP upload script may be adapted e.g. for sending notification mail after file upload.

HTTP Redirection Service

The SC supports redirecting of regular HTTP traffic to another server. HTTP traffic through the SC infrastructure is possible without service and session context. SC receives the http requests on a dedicated port and passes all HTTP traffic to a configured server. It does not act like a HTTP proxy.The requested URL must be resolved (DNS) by the underlying network infrastructure. SC does not provide any name resolution. The SC configuration has one remote node definition for redirection of the HTTP traffic.

Multiple http redirection services may be defined to different targets, each one listening on a different TCP/IP port.

Caching of messages is one of the key features supported by the SC. It can be activated on every instance of SC. This simply means messages routed by session services are stored in the SC instances. The cache is loaded by the first client requesting the messages. All subsequent clients will get the message from the cache, bypassing the server processing. This highly reduces communication and speeds up the processes on client side. The cache is shared for all services. Security is not affected because message exchange is possible only in a scope of a valid session. The definition, which message should be cached, how it is identified and how long it is valid, is matter of agreement between the communicating parties.

Download SC Cache Coherency Documentation

Cache Coherency (from SC V1.3-023)

Cache coherency refers to the consistency of data stored in local caches of every SC node. The coherency protocol addresses the problem of maintaining the consistency of all caches in a system of distributed shared memory. Therefore a coherence model has been specified which enables the server application to send Appendix, Removes and Initial Data (Replacements) for existing content in the caches.

Session Monitoring

Session monitoring is based on echo messages, exchanged periodically for each active session between the client and the SC. This enables the SC to observe clients and their sessions and to inform the server about broken session and timeouts.

Server Monitoring

The SC monitors the servers the same way as the sessions of the clients. Small messages are exchanged between Server and SC. On server abort all relevant sessions or subscriptions are discarded.

WebUI

WebUI is a simple monitoring instrument showing the current SC activity. It can be disabled in the configuration. It can be used from any remote node having web access to SC.

Download SC Operation Guide

SC Console Operations

SC console is a tool which allows sending of simple management commands to SC from the command line. It may be used in scripts embedded into other management tools.

SC Configuration

The SC is configured with a single configuration file sc.properties. Additional user specific configurations may be included within this file or an additional file. More information is available in the operation guide.

SC Logging

Standard open source package log4j is used for SC logging. It is configured with a single configuration file log4j-sc.properties.

There are 5 loggers configured for logging:

• defaultLogger
  This is a hierarchical logger used to produce regular log output to console and file. All errors will appear here. All levels are in use
• connectionLogger
  This is specific logger used to log connection problems. It has only TRACE or DEBUG level
• messageLogger
  This is specific logger used to log messages. It has only TRACE or DEBUG level.
• sessionLogger
  This is specific logger used to log session events. It has INFO, DEBUG or TRACE level.
• subscriptionLogger
  This is specific logger used to log subscription events. It has INFO, DEBUG or TRACE level
• cacheLogger
  This is specific logger used to cache events. It has only TRACE level.
• performanceLogger
  This is specific logger used to log messages. It has only TRACE level.

Load balancing

The SC does not provide any load balancing features. Established sessions will not be replicated to another server node during its life time.

Failover

The SC does not provide any failover features. Aborted communication must be reestablished by the communicating partners. The client application must identify a service which is alive.

Security

The SC does not implement any security feature. The environment where SC is used must provide all required authentication, authorization, encryption, tunneling etc. features. Message transport over https is not supported a the moment.

The entire network where SC is used is assumed to be safe and secure. Users may use screening firewall to protect the components. It is recommended to use SC within a DMZ. SC is not designed to withstand network attacks like DOS or SYNC flood.

SC is Open Source and distributed under Apache License, v2.0. You may download either a kit or build the software from scratch. There are two kit types available:

1. Binary kit - containing only binaries (suitable for upgrade)
2. Source kit - containing binaries, examples, sources and documentation (suitable for starting with SC)

The kits can be downloaded from:

• GitHub (selected versions)
• Stabilit download site (latest released version)

If you want to build the Service Connector from the source code you may fetch it from the Git repository hosted on GitHub. The access is read-only.

If you want to contribute to the project please contact

Add the following repository and dependency section to your pom.xml:

If you are using maven. The Stabilit repository is located under STABILIT Software Repository

The SC project is exclusively bases on open source software. The core relies on the Netty project (http://netty.io). For caching the EhCache is used (http://ehcache.org). JDK 1.5 (or above) is at least needed.

Please communicate problems, comments and suggestions to

SC version has the format V9.9-999 e.g. V3.2-023 means: 3 = Release number, 2 = Version number, 023 = Revision number. The detailed description is in documentation SC_0_SCMP. Java applications using the SC API can get the current version as SCVersion.CURRENT.toString(). There is no reason to set it or to check it when the SC API is used.

Processing:

The Client must set its own version number as scVersion attribute and send it in the ATTACH message. The Server must set its own version number as scVersion attribute and send it in the REGISTER_SERVER message. In SC Java API for client and server this is done behind the scenes and does not need any care. When SC receives these messages it performs the compatibility check. If the SC property root.commandValidationEnabled=false than version check is not done! In case the versions are not compatible it will send an error back to the client or server. The error message contains the precise reason what is incompatible and what has been passed. E.g. scErrorCode = 423, scErrorText = "Incompatible SC version nr. [V5.4-456]" In SC Java API for client and server the attach() and register()methods will throw a validation exception. In cascaded configurations the attach() does not reach all cascaded components but only the top level. For this reason the validation exception mentioned above can possibly be thrown also by the subscribe() or createSession() methods. In other APIs the error message must be handled properly and signaled to the caller.

Compatibility rules:

In real life this means:

• New SC can communicate with older client or server (upward compatibility)
• Old SC cannot communicate with newer client or server and must be updated

Practical usage:

The revision number is incremented every time after the software has been delivered (tagged). The version number is incremented when a new compatible features has been added. Release number is incremented when the new software is incompatible or when the software was completely redesigned.

SCMP version is part of the message headline and so a part of every message. It has the format 9.9 e.g. 2.5 means: 2 = Release number, 5 = Version number. The detailed description is in the SCMP documentation. Java applications using the SC API can get the current version as SCMPVersion.CURRENT.toString(). This is just for information. There is no reason to set it or to check it when SC API is used.

Processing:

The sender must set the version number in each message. The receiver must check this number against its own SCMP Version number every time a message is received! This is done in SC Java API in all components, e.g. in the Client, SC and in the Server. Other APIs must implement the same logic. When the receiver detects an incompatible number, it must discard the message and log an error. The receiver must not sent back any error response to the sender. This would cause another error.

Compatibility rules:

In real life this means:

• New receiver understands older messages (upward compatibility)
• Old receiver cannot understand newer messages and must be updated

Practical usage:

The version number will be incremented when a new element (header) will be added or when a change compatible to the previous version was done. Release number is incremented when the new protocol is incompatible or it was redesigned completely.