By Gorkem Ercan
December 13, 2005

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.

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" />
		
		

	

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

    iiop://127.0.0.1:2001

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.

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>
			
			

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

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>
		

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>
		
		

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.

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.

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.