JBoss.orgCommunity Documentation

Chapter 11. TorqueBox Services

11.1. What Are Services?
11.2. Service Classes
11.3. Deploying Services
11.3.1. Configuration Format
11.4. Clustered Services
11.4.1. High Availability Singleton Services
11.4.2. Services Running on Every Node
11.5. Resource Injection with Services

Services are persistent background Ruby daemons deployed and managed by TorqueBox. Common uses for services include connecting to a remote service (IRC bot, Twitter Streaming API client) or starting a server to listen for incoming connections. A service may be deployed as part of a web application or as its own application without any web component. Services have full access to the entire Ruby environment. This means that a service deployed as part of a web application can use the app's database models, for example.

Each service maps to exactly one Ruby class that should optionally implement initialize(Hash), start() and stop() methods which should each return quickly. Typically the start method will spawn a new thread to start an event loop or other long-running task.

The service's start method will be invoked when the service is deployed, and stop will be invoked automatically when the service is undeployed. Thus a convenient hook is provided for cleanly shutting down any threads or other resources used by the service.

Services are deployed by creating a services section inside your application's deployment descriptor.

Within the internal torquebox.yml descriptor (or through an external *-knob.yml descriptor), services reside under a services key of torquebox.yml. Each key underneath services is either a unique name for the service or the name of the Ruby class implementing the service. Providing a unique name allows the reuse of the same Ruby class to provide multiple services. If the Ruby class name is not used as the key, it must be provided using the service key in the key/value pairs nested underneath the service entry as options for the service. Any value assigned to the config key underneath the service entry will be passed in as the parameter to the service's initialize method.

If you are using the DSL (via torquebox.rb) in your internal descriptor, each service is defined using the service directive, with very similar options to the YAML syntax described above. The DSL does not require a name for each job, unless you intend to share a job class across multiple jobs.

Service classes should be placed in a directory that is on the application's load path. For Rails applications, the convention is to put your service classes in $RAILS_ROOT/app/services/. For non-Rails applications, the convention is to use $RAILS_ROOT/services/. No matter what type of application you have, both directories will automatically be added to the load path.

TorqueBox supports highly-available singleton services. By default, a service only runs on one node in a cluster and if that node fails or the service is interrupted for any reason, it automatically starts on another node.

To use highly-available singleton services, you must start TorqueBox with a clustered configuration. For example:

 $ $JBOSS_HOME/bin/standalone.sh --server-config=standalone-ha.xml

Alternatively, use the torquebox command:

 $ torquebox run --clustered

HA services are configured using the singleton key in the services section of torquebox.yml. Its default value is true so you must manually configure it with a value of false for the service to run on every node in the cluster.

If a service requires access to other resources, such as messaging topics and queues, or Java CDI components these should be injected using the resource injection facilities provided by TorqueBox (see Chapter 12, TorqueBox Resource Injection).

In order for resource injection to function with services, they must reside either at the root of your application directory (typical for simple Rack applications), or underneath an app/services/ directory. If you place the service anywhere else, it may still function, but resources injection will not be available.