The service and tools classes are simple POJO classes that are annotated. Service annotations are generally defined in the package com.sun.faban.harness.services and tools annotations are generally defined in com.sun.faban.harness.tools with generic annotations defined in com.sun.faban.harness for both services and tools. Since annotations are not inherited when subclassed, we need to explicitly annotate the relevant methods in subclasses. The service and tool context also needs to be annotated as the harness will inject the variable with a real reference to the applicable service context or tool context.
The service objects are instantiated and invoked on the master, one object per service configuration entry (in the run configuration file). One service object controls multiple instances of the server in question on multiple systems, if applicable. In contrast, the tool objects are instantiated and invoked on the agent, the systems running the actual servers under observation.
The service annotations are defined in com.sun.faban.harness.service, and com.sun.faban.harness. The following are used for annotating service implementations:
@Context is used to annotate an instance variable. The variable has to be of type com.sun.faban.harness.service.ServiceContext. Right after the instantiation of the service, the variable will be injected with the service context. The service context is made available to the service right after it gets constructed and before the method annotated with @Configure gets called. The context is the entry point for service implementations to interface with the Faban harness as well as obtain information about the run. The service may use methods in RunContext including all exec and java methods. As the service usually runs on the master, most exec or java calls may be remote. The service can also execute code blocks through the RemoteCallable interface. The code block will execute on the target system. The ServiceContext is serializable and is designed to be passed along with the RemoteCallable so code blocks running remotely can have access to the service information. However, only the local versions of exec and java are available for such code blocks. Calls to remote versions of exec and java from a remote system will result in a NullPointerException.
The method annotated with @Configure gets called after the Faban infrastructure, including remote agents are set up. Having these in place allows you to make remote calls to configure or set up the services for a benchmark environment. The method implementation will commonly contain logic to start or restart servers or other supporting processes to run the benchmark, preparing and reloading data required to run the benchmark, etc.
The method annotated with @GetConfig is called to transfer the service configuration files to the run output directory.
The method annotated with @Start is called to start the server.
The method annotated with @Stop is called sometime after
the
start
method
terminates. The implementation of the end method must wait for the
driver processes to terminate before proceeding.
The method annotated with @GetLogs is called for trasferring server-specific logs from all the machines in the rig to the Faban master. These logs may be server logs in general or any specific logs of interest. For example, we'd not be interested in the access logs on web servers as they grow pretty large. Only error logs are needed in such cases.
The method annotated with @ClearLogs is called for
clearing the server-specific log files, thus preparing the system for
the next run.
The tool annotations are defined in com.sun.faban.harness.tools, except for @Context, which is defined in com.sun.faban.harness. Tools classes use the following annotations:
@Context is used to annotate an instance variable. The variable has to be of type com.sun.faban.harness.tools.ToolContext. Right after the instantiation of the tool, the variable will be injected with the tool context. The tool context is made available to the tool right after it gets constructed and before the method annotated with @Configure gets called. The context is the entry point for tool implementations to interface with the Faban harness and obtain relevant information about the run, and about the service the tool is observing. For instance, a MySQL tool needs to know the configuration of the MySQL instance it is monitoring. For execution and Java calls, tool implementations may use the convenient exec and java methods provided by the ToolContext. They may as well use the static versions provided by RunContext. Only the local exec and java calls are available to tools. Calls to remote versions of exec and java from a tool - which is already running on an agent system - will result in a NullPointerException.
The method annotated with @Configure is the one that gets
called
after the
Faban infrastructure, including remote agents are set up. Having these
in place allows you to make remote calls to configure or set up the
tools for a benchmark environment.
The method annotated with @Start is called to start the tool.
The method annotated with @Stop is called to stop the tool.
The method annotated with @Postprocess is called after all tools have stopped but before the results are transferred to the master, allowing it to post-process tool output on the systems the measurements were taken. Not all tools need this annotation - only when post-processing tool output is desired.