Writing Services in Trooper

This page describes features of the Trooper Service Profile and steps to develop, deploy, orchestrate and monitor service execution.

Trooper Service Profile

Service is one of the supported runtime profiles in Trooper. This means the following to its users:

• Provision for modular development, testing and deployment of services and optionally orchestration using the profile's features and supporting tools.
• Life-cycle management of services, configuration refresh using administrative console(s).
• Compile-and-run support for all service profile features - does not require any packaging for deployment and testing thereby saving development time, providing for easier debugging (via standard break-points in IDEs)
• Implementation of Convention-Over-Configuration practices to ease development, deployment
• Integration with Trooper libraries for Event publishing, JMX notifications, Data transformation to XML and JSON.
• Complete integration with Coda Hale metrics to get in depth statistical information regarding Services
• Getting notifications according to custom (user defined) rules about the metrics

Implement and configure a service

A Trooper service, by definition, is stateless abstraction of functionality that follows a request-response interaction model. The Request and Response objects define the service vocabulary and the service interface provides a single standard, known method for invocation.

Service implementations are required to follow these guidelines:

• Define the service vocabulary i.e. request-response objects. The preferred way to do this in Trooper is to define these as XML schemas (XSD files). The XSD files are compiled to produce Java representations of the request-response objects.
• Create a project (optional) to contain the service vocabulary files i.e. XSD files. Check the Trooper example-models. This project, when built, produces the Java equivalents for the schema defined objects.
• Write a POJO that implements org.trpr.platform.servicefw.spi.Service interface. Alternatively, extend org.trpr.platform.servicefw.impl.SimpleAbstractServiceImpl and benefit from features like monitoring. See org.trpr.example.service.greeting.SimpleGreetingService for example. Sample services are available in Trooper example-services
• Configure the service as a Spring bean in a file by name spring-services-config.xml. Bean id follows the naming convention : <service name>_<major version>.<minor version> Snippet from example service configuration is shown below:

<beans>
    <!-- The reference implementation services -->
    <bean id="simpleGreetingService_1.0" class="org.trpr.example.service.greeting.SimpleGreetingService">
        <property name="serviceContext" ref="serviceContext" />
    </bean>	
</beans>

The serviceContext bean referenced here (and other common service framework beans) are defined in /serviceframework-core/src/main/resources/packaged/common-spring-services-config.xml and loaded from classpath during Trooper service profile runtime start up.

Testing a service

The Trooper Service runtime provides a convenient way to test services. This is useful during development when one needs to make changes and run the service repeatedly a number of times. The service client is used to test service implementations. It is a command line utility that accepts the Trooper bootstrap.xml, the service name (version is resolved to latest) , request-response class names and the path to the service request XML/JSON file. See "Testing services (Service profile)" section in Build and run examples. Trooper Services Console even provides a UI for Testing Services. See (https://github.com/regunathb/Trooper/wiki/Trooper-Services-Web-Console) for details.

Service Context

A Service Context is available to every Trooper service for it to interact with the service container. This context is intended to be similar to a ServletContext in a servlet container. Useful behavior provided by the org.trpr.platform.servicefw.ServiceContext include:

• Methods for publishing service events, alerts and notifications. Destinations for these events are pre-defined while the event payload is service specific. A service may therefore publish an alert using data from the last executed service request for example.
• Methods to query the container. This may include in future the domain that a service belongs to, check-pointing support in the container, tracking service chaining path etc.

Service Statistics

The Service runtime profile exposes service statistics via JMX and is accessible on the console via the navigation path : org.trpr.platform.servicefw.impl-> AbstractServiceImpl and org.trpr.platform.servicefw.impl-> ServiceCompartmentImpl. The console displays statistics for each deployed service (service beans deployed in spring-services-config.xml that have been located and loaded by Trooper) like below:

These service statistics are even visible through Trooper Services Web Console. We recommend using the JSON output of these metrics (using the web console), if you want to programatically gather the Service metrics. See (https://github.com/regunathb/Trooper/wiki/Trooper-Services-Web-Console) for details. ![Web console statistics] (https://raw.github.com/regunathb/Trooper/master/docs/services%20listing.png)

Notifactions based on Metrics

Trooper Services profile enables you to define custom rules regarding the metrics. The rules are based on MVEL (http://mvel.codehaus.org/). When any of the rule is matched (evaluated as true), a notification is sent to a user defined listener class. You can define rules, such as greetingService_1.0.p50ResponseTime > 200. This rule will result in a notification if the P50 Response Time of greetingService excceds 200 ms. To enable this feature, you have to define a "MetricsListener" bean in the spring-services-config.xml, such as:

	<bean id="metricsListener" class="org.trpr.platform.servicefw.impl.notifier.MetricsListenerImpl">
		<property name="metricsEvaluators">
			<list>
				<bean class="org.trpr.platform.servicefw.impl.notifier.MetricsEvaluatorImpl">
					<property name="rules">
						<list>
							<value>greetingService_1.0.p50ResponseTime &gt; 30</value>
							<value>greetingService_1.0.activeRequestsCount != null</value>
						</list>
					</property>
					<property name="notificationReceivers">
					<list>
						<bean class="org.trpr.platform.servicefw.impl.notifier.SimpleMetricsEventReceiver" />
					</list>
					</property>
					<property name="serviceStatisticsGatherer" ref = "serviceStatisticsGatherer" />
				</bean>
			</list>
		</property>
		<property name="timer" ref="metricsTimer" />
		<property name="delay" value="100000" />
	</bean>

Please note that '&gt;', '&lt;', '&amp;' are escape sequences for '>', '<', '&' in an XML file. The notification listener class should implement MetricsEventListener. Since there is a complete MVEL support, even expressions like greetingService.p50ResponseTime > 50 && greetingService.p99ResponseTime > 150 are supported. For a detailed explanation of how this works, refer to the Java Docs of MetricsListener.java.

Trooper Task Framework

The Trooper Task framework defines a contract and implementation for decomposing functionality into sub-units of work that may then be executed locally or distributed. Trooper service examples demonstrate use of the Task framework to implement services. See Trooper Task Framework for design details and GreetingService (Service implemented using Tasks) for sample use.

Trooper Orchestration Profile

The Trooper Orchestration Profile enables chaining of a number of execution stages in a manner reminiscent of workflows. Each stage is implemented as a Trooper Service and this in turn means any Trooper service can participate in a workflow, with transformation and routing implemented outside the service. See Trooper Orchestration Profile for design details and examples.