Generic server - Server Definition file explained
Generic server - Server Definition file explained
 

By Gorkem Ercan
December 13, 2005

Introduction
 
 

Generic server is a special server and runtime implementation of base server tooling that can adjust its behaviour by a server type definition file. Server type definition files are XML based meta information files that are introduced using "org.eclipse.jst.server.generic.core.serverdefinition" extension point

 

This document describes the different parts of the server definition files.

 
Server definition file introduction
 
 

A server definition file virtually has two parts; Properties and Server information. Properties are variables that is something that can be manipulated and changed using generic server graphical user interface. Server information is used by the generic server to perform server tooling functionality. This information can be defined so that properties are used to determine their values.

If we define a property like;


	  <property id="serverAddress"
		label="Address:"
		type="string"
		context="server"
		default="127.0.0.1" />
		
		

And if we refer to this property in a server information element such as:
	

	<jndiConnection>
	    <providerUrl>iiop://${serverAddress}:2001</providerUrl>
	    <initialContextFactory>org.objectweb.carol.jndi.spi.MultiOrbInitialContextFactory</initialContextFactory>
	</jndiConnection>
	

When used in the generic server tooling the provider URL becomes
    iiop://127.0.0.1:2001

Properties to collect user data
 
 

The defined properties show up in the generic server user interface for collecting user data. A property element must have all the following attributes:

id: A property is referred in the server definition and the generic server APIs with this value. If you wish to refer to this property later in the server definiton file wrap it inside ${.. }. Ids must be unique.

label: User friendly alias for the property. This is value is shown to users.

type: Properties are string valued. This attribute determines the type of GUI to use. The allowed values, "string" renders a text widget, "boolean" renders a check box, "directory" renders a file path dialog, "file" renders a file dialog.

context:Determined whether the property is part of server runtime or a server instance. The user is asked for the value of the property in new Server Runtime wizard or New Server wizard depending on this value. Allowed values are "server", and "runtime"

default: This is the initial value presented to user.

Defining classpaths
 

Well defined classpaths are an important part of server definitions. A classpath definition can be referred in more than one section of the server definition. It can be used to start, stop server or define the entries to be added to a project' s build path. Classpaths are defined using the classpath element.

			

		<classpath id="jonas">
		    <archive path="${classPath}/lib/common/ow_jonas_bootstrap.jar" />
		    <archive path="${classPath}/conf" />
		</classpath>
			
			

id: Is the name that this classpath is referred to in server definition file and the generic server APIs

archive and path: this element points either to a directory or a java library that will be a part of the classpath.

If a flexible project is targeted for a generic server its build path is updated by the generic server tooling to include required libraries by the server. In server definition files the project element is used to determine which classpath definition is used for project build paths.

project: element contains only one element that refers to a classpath definition.

		<project>
		   <classpathReference>jonas</classpathReference>
		</project>
		    

Information to start and stop your server
 

The start and stop elements are very similiar tags that are used to define parameters to launch a server, and stop a running server respectively. They are both consist of the same elements. Generic server framework support two kinds of launches, java launch and external launch. The type of the launch used is determined by the launch configuration in the definition of the server type.

workingDirectory: This is the directory in which the application server starts.

programArguments: Specific values that the server is expecting (a user name or a URLs, configuration params, for example).

environmentVariable: These are the name and value pairs that are used as environment variables for launchs.

If a java launch is configured you should define mainClass, vmParameters, classpathReference tags in addition to above.

mainClass A java application server is a Java application after all. Like any other Java application you will need a class with a main method to start it. This the name of that class.

vmParameters: Values that are used as parameters to java virtual machine.

classpathReference: This is the classpath definition used to invoke the main class.

When defining an external launch use the external, and debugPort tags with workingDirectory and programArguments.

debugPort:This is the port number that eclipse debugger will connect to when the server is started in debug mode.

external:This is the external executable or script that will be used for launching the server. The os attribute in the tag indicates the platform of the definition. You can have as many external tags as the number of platform you wish to support.

The following is an example for an external launch definition.


		<start>
			<external>${startScript}</external>
			<workingDirectory>${domainDirectory}</workingDirectory>
			<debugPort>${debugPort}</debugPort>
			<environmentVariable>
				<name>debugFlag</name>
				<value>true</value>
			</environmentVariable>
		</start>
		

Publishers
 

Generic publishers are general purpose publishers that can be used for publishing to different servers. It is also possible to implement a server specific publisher, if the publishing mechanisms of the server requires it. A new publisher is introduced using org.eclipse.jst.server.generic.core.genericpublisher extension point. WTP includes the general purpose ANT publisher. ANT based publisher simply calls specific targets on an ANT script to publish modules to a server.

A server definition file can contain some server specific information that is used for initializing the publisher. The publisher element in the server definiton can be used for this purpose.


	    <publisher id="org.eclipse.jst.server.generic.antpublisher">
		    <publisherdata>
		        <dataname>build.file</dataname>
		        <datavalue>/buildfiles/jonas.xml</datavalue>
		    </publisherdata>
	</publisher>
		
		

id: This is the id of the publisher. This value must match the value in the plugin.xml where the publisher is defined.

publisherdata: A single name value pair that will be passed to publisher.

Modules
 

The module element shows the module types this server definition can work. It also includes information on publishing the module.

type: The module type. This value must match the value in the plugin.xml where the module type is defined.

publishDir: The directory where the final module will be published to.

publisherReference: The id of the generic publisher that should be used to publishing of this module type.

Ports
 

the port element indicates the ports and the protocols that the server starts on. These values are used to determine if a server is alive.

no: The port number.

protocol: The protocol supported by this port.

name: User friendly name of the port' s protocol.

JNDI properties
 

The JNDI properties for a server are needed for any clients that need jndi such as EJB testers. The jndiConnection element is used to provide the jndi information for accessing an application server.

providerUrl: The url to jndi server.

initialContextFactory: Name of the initial context factory class for the server' s jndi implementation.

jndiProperty: Name, value pairs that may be used for establishing jndi connection, such as usernames, passwords, etc.