wst/components/server/overview.xml - gerrit/www.eclipse.org/webtools - Git at Google

 <?xml version="1.0" encoding="utf-8"?>
 <?xml-stylesheet type="text/xsl" href="../../../wtp.xsl"?>
 <html>
 <head>
   <meta name="root" content="../../../../" />
   <title>wst.server API Overview</title>
 </head>
 <body>


 <h1>WTP Server Tools API Concepts and Roles</h1>

 <p>Last modified Feb 10, 2005</p>

 <p>[<i>This document is a work in progress. The document is an attempt to
 capture the key concepts required for understanding and working with the WTP
 Server Core API. Note that the concepts may differ subtly from what is currently
 found in the currently released
 <a href="http://dev.eclipse.org/viewcvs/index.cgi/wst/components/server/plugins/org.eclipse.wst.server.core/?cvsroot=WebTools_Project">org.eclipse.wst.server.core</a>
 plug-in. Once this document is finalized, our intent is to bring the code
 and specs into line with this document.]</i></p>

 <p>The key concepts for understanding the API (and SPI) are servers and modules.
 The notions of server runtimes and server configurations play an important, but
 secondary role.</p>

 <p>Not surprisingly, the notion of <b>server</b> is central in the web tools
 server infrastructure. In this context we are to understand that the server is a
 web server of some ilk (a more exact definition is not required for our
 purposes). From a tool-centric point of view, a server is something that the
 developer is writing "content" for. (In a sense, the server exists,
 but lacks useful content. The development task is to provide that content.) The
 content can include anything from simple, static HTML web pages to complex,
 highly dynamic web applications. In the course of writing and debugging this
 content, they will want to test their content on a web server, to see how it
 gets served up. For this they will need to launch a server process running on
 some host machine (often the local host on which the Eclipse IDE is running), or
 attach to a server that's already running. And we must arrange that the newly
 developed content sitting in the developer's workspace ends up in a location and
 format that a running server can use for its serving purposes.</p>

 <p>(The server objects in the API are in fact intermediary "proxy"
 objects that mediate between the tools running in Eclipse and the real server. A
 server proxy object has a somewhat independent life from that of a real server.
 In cases where the server process must be launched, the proxy object exists in
 advance of the server process, and lives past the termination of the server
 process. The same server proxy may be serially reused to relaunch server
 processes. In cases where we are connecting to a server process running on a
 remote host, the server process may well outlive the proxy.)</p>

 <p>Servers have a <b>server runtime</b>. The server runtime corresponds to the
 installed code base for the server. The main role played by the server runtime
 is in identifying code libraries to compile or build against. In the case of
 local servers, the server runtime may play a secondary role of being used to
 launch the server for testing. Having the server runtimes identified as an
 entity separate from the server itself facilitates sharing server runtimes
 between several servers.</p>

 <p>Servers have an optional <b>server configuration</b>. The server
 configuration is information used to configure a running server. Simple types of
 servers might not require any configuration, whereas full-featured web server
 have an extensive set of parameters for adjusting the server's behavior. Even
 though server configuration information usually takes the form of one or more
 files, configuration information is treated separately from actual content.
 Actual web content can be deployed on different servers without change, whereas
 server configuration information is usually highly dependent on the particulars
 of the server. Having the server configuration identified as an entity separate
 from the server itself facilitates switching an existing server between
 configurations, and sharing server configurations between several servers (e.g.,
 a local test server and a remote server running on another host).</p>

 <p>The content that is developed for a server comes in <b>modules</b>. A
 module usually consists of a tree of files; a static HTML web is one simple
 example. Different types of modules consist of possibly constrained arrangements
 files of certain file types. The files making up a module under development
 reside in the Eclipse workspace. In order for a server to access the content
 within a module, the module in the workspace must be <b>published</b> to the
 server (we use the term <i>publish</i> rather than <i>deploy</i> which is
 overused in J2EE). The module is the unit of content that is published to a
 server. In the case of J2EE servers, the notion of module aligns with the J2EE
 notion of a module (a server concept). But that needn't be the case; some
 types of servers, such as a simple HTTP server, don't have a notion of module.
 Either way, publishing a module to the server entails whatever it takes to get
 the publishable content from the workspace to the server in a form that the
 server can access it. Different types of server runtimes are capable of support
 various module types. Some server types may be able to serve modules directly
 out of the workspace without copying.</p>

 <p>At any given time, the developer may be working with any number of servers.
 Each server has a set of modules and may have a server configuration. From the complete
 set of modules in the workspace, any particular server may see only a subset,
 although it is also possible for all servers to see all available modules. After
 the developer makes changes to the modules in the workspace and now wants to
 test their modification, they republish the modules to the server. Depending on
 the type of server, republishing a module may entail stopping and restarting the
 server.</p>

 <p>Some types of modules can have other modules as children. The standard
 example of this is a J2EE Enterprise Application (EAR) module, whose children are
 simple J2EE modules like Enterprise Java Beans and Web Applications. The
 parent-child relationship is weak: two parent modules can share the same child
 module, and the same child can be parented by several modules (on the same or on
 different servers). The file trees for modules are normally mutually disjoint.
 Module containment is not reflected by any sort of directory nesting. Parent and
 child modules map to non-overlapping file trees.</p>

 <p>Modules typically reside in the workspace. The arrangement is usually that each
 module exists in a single project, where the content usually
 corresponds to a particular folder within a project rather than the root of the
 project. This allows the project to contain other files (e.g., .project, .classpath,
 source code) that are not considered part of the module content proper. Each
 different type of module has its own rules for how the content files within it
 are laid out. For instance, a J2EE web module has the same structure as an
 unzipped WAR file. (Note that the module structure rules are largely implicit
 and not reflected directly in the APIs.) It is possible for a project to
 contains more than one module (although this arrangement is less common, and not
 as well supported).</p>

 <p>During development, projects containing modules can be <b>targeted</b> to a
 particular server runtime. Targeting allows the IDE to set up various
 development time properties of the project (such as the backbone of the Java
 build path) appropriately. The most common scenario is where the project is
 targeted to the server runtime for the server to which the module is being
 published. However, it is also possible to target one server runtime (e.g., a
 generic J2EE 1.3 server runtime) while publishing to a server with a different
 server runtime (e.g., a Tomcat v5.0 server). Targeting a project to a particular
 server runtime typically establishes the Java build classpath of the project to
 include the libraries containing the Java APIs for that server runtime (e.g.,
 the appropriate J2EE class libraries). The Java build classpath also needs to
 reflect inter-module dependencies; for J2EE module types, the appropriate
 entries are typically derived from the module's manifest.</p>

 <p>The main goals of the Server Core client APIs are to allow clients to create,
 configure, and launch instances of particular server types. Due to differences
 in the behavior (and APIs) of different server types, a client must generally be
 knowledgeable of rules for a particular server type. Clients that have no
 knowledge of any specific server type are limited to doing things like starting,
 stopping, and relaunching existing servers. In other words, the clients APIs are
 generally server-type-specific, rather than sever-type-generic.</p>

 <p>The web tools server architecture allows for an open-ended set of server
 types, server runtime types, and module types. New
 types are declared via extension points in the Server Core plug-in (org.eclipse.wtp.server.core).
 Server types are declared by the serverTypes extension point; server runtime
 types, by runtimeTypes; and module types, by moduleKinds.
 (Additional extension points are discussed below.)
 Associated with these extension points are core APIs designed for use by
 clients contributing to the Server Core extension points; these are more
 correctly called SPIs (service provider interfaces) to distinguish them from the
 code designed to be used by other clients (which we refer to here as client
 APIs).</p>

 <p>Many of the extension points provide for a dynamic code component in addition
 to the static information supplied in the extension declaration. These are
 termed <i>delegates</i>. For instance, all communication with the running server
 is handled by a <b>server delegate</b> contributed via the server type extension
 point. Clients generally deal directly with a layer of objects exposed by the
 API expressly for client use. In the case of server, clients deal with an
 IServer. IServer has a fixed, hidden implementation (the internal class Server),
 which hangs on to a lazily-created server delegate of type IServerDelegate. The
 IServerDelegate implementation is a server-type-specific object. The more
 interesting IServer methods (e.g., getServerState()) are handled by the
 delegate. There are also getDelegate() methods that bridge API to SPI, allowing
 clients to call methods on the delegate directly. Service providers may also
 choose to expose their delegate implementation as API. This allows, for example,
 the provider of a server type to offer additional API that is
 server-type-specific.</p>

 <p>A <b>module factory</b> is responsible for creating modules. There can be any
 number of registered module factories, declared via the
 org.eclipse.wtp.server.core.moduleFactory extension point. A module factory may
 create one or more types of modules (also declared in the extension point). The
 module factory API does not prescribe a way to create modules; it does, however,
 provide methods for retrieving extant modules that it was responsible for
 creating (IModuleFactoryDelegate.getModules() and
 IModuleFactoryDelegate.getModule(String memento)).</p>

 <p>To sync up changes in the local workspace with the server, clients call
 IServer.publish(IProgressMonitor monitor), which will publish the changes to
 the server. The server framework handles figuring out which modules have been
 changed and what resources have changed within the module, but the server
 delegate is called to do the actual publish operation.</p>

 <p>The client API exposes:</p>
 <ul>
   <li>Server runtime types as IRuntimeType. ServerCore.getRuntimeTypes() returns
     all known server runtime types.</li>
   <li>Server types as IServerType. ServerCore.getServerTypes() returns all known
     server types.</li>
   <li>Module types as IModuleType.</li>
 </ul>
 <p>The type-level relationships are:</p>
 <ul>
   <li>a server type has a server runtime type; this is the type of server
     runtime required to run the server; exposed as IServerType.getRuntimeType()</li>
   <li>a server type has an optional server configuration</li>
   <li>a server runtime type supports 0 or more module types; exposed as
     IRuntimeType.getModuleTypes()</li>
 </ul>

 <p>The API exposes server runtime instances as IRuntime.
 ServerCore.getRuntimes() returns all known server runtime
 instances. Server runtime instances are created (only) from server runtime types
 by IRuntimeType.createRuntime(String id), which returns an IRuntimeWorkingCopy.
 Any number of aspects of the server runtime instance (including location in the
 file system) can be established or adjusted from their defaults. When editing is
 complete, IRuntimeWorkingCopy.save(IProgressMonitor monitor) creates, registers,
 returns a server runtime instance (IRuntime) capturing the desired settings (the
 working copy is disposed of).</p>

 <p>The API exposes server instances as IServer.
 ServerCore.getServers() returns all known server instances.
 Server instances are created (only) from server types by
 IServerType.createServer(String id, IFile file, IRuntime runtime,
 IProgressMonitor monitor) or IServerType.createServer(String id, IFile file,
 IRuntime runtime, IProgressMonitor monitor). The file parameter is used to
 control where the server instance is serialized. Both return an
 IServerWorkingCopy. Any number of aspects of the server instance (host name,
 server runtime, server configuration, modules, ...) can be established or
 adjusted from their defaults. When editing is complete,
 IServerWorkingCopy.save(IProgressMonitor monitor) creates, registers, returns a
 server instance (IServer) capturing the desired settings (the working copy is
 disposed of).</p>

 <p>The instance-level relationship between servers and server runtimes and
 server configurations is exposed at the API: for a given server,
 IServer.getRuntime() returns the server runtime (IRuntime),
 IServer.getServerConfiguration() returns the server configuration (IServerConfiguration).</p>

 <p>IServer.start(String mode, IProgressMonitor monitor), stop(), and
 restart(String mode) are used to start, stop, and restart a server, respectively
 (there are also synchronous methods for starting and stopping). The predicates
 IServer.canStart(String mode), canRestart(String mode), and canStop() indicate
 whether the server is receptive to being controlled. IServer.getServerState()
 can be used to query the overall state of the server (one of starting, started,
 stopping, stopped, or unknown), and IServer.getModuleState(IModule module) can
 be used to query the state of any of its modules.</p>

 </body>
 </html>
	<?xml version="1.0" encoding="utf-8"?>
	<?xml-stylesheet type="text/xsl" href="../../../wtp.xsl"?>
	<html>
	<head>
	<meta name="root" content="../../../../" />
	<title>wst.server API Overview</title>
	</head>
	<body>


	<h1>WTP Server Tools API Concepts and Roles</h1>

	<p>Last modified Feb 10, 2005</p>

	<p>[<i>This document is a work in progress. The document is an attempt to
	capture the key concepts required for understanding and working with the WTP
	Server Core API. Note that the concepts may differ subtly from what is currently
	found in the currently released
	<a href="http://dev.eclipse.org/viewcvs/index.cgi/wst/components/server/plugins/org.eclipse.wst.server.core/?cvsroot=WebTools_Project">org.eclipse.wst.server.core</a>
	plug-in. Once this document is finalized, our intent is to bring the code
	and specs into line with this document.]</i></p>

	<p>The key concepts for understanding the API (and SPI) are servers and modules.
	The notions of server runtimes and server configurations play an important, but
	secondary role.</p>

	<p>Not surprisingly, the notion of <b>server</b> is central in the web tools
	server infrastructure. In this context we are to understand that the server is a
	web server of some ilk (a more exact definition is not required for our
	purposes). From a tool-centric point of view, a server is something that the
	developer is writing "content" for. (In a sense, the server exists,
	but lacks useful content. The development task is to provide that content.) The
	content can include anything from simple, static HTML web pages to complex,
	highly dynamic web applications. In the course of writing and debugging this
	content, they will want to test their content on a web server, to see how it
	gets served up. For this they will need to launch a server process running on
	some host machine (often the local host on which the Eclipse IDE is running), or
	attach to a server that's already running. And we must arrange that the newly
	developed content sitting in the developer's workspace ends up in a location and
	format that a running server can use for its serving purposes.</p>

	<p>(The server objects in the API are in fact intermediary "proxy"
	objects that mediate between the tools running in Eclipse and the real server. A
	server proxy object has a somewhat independent life from that of a real server.
	In cases where the server process must be launched, the proxy object exists in
	advance of the server process, and lives past the termination of the server
	process. The same server proxy may be serially reused to relaunch server
	processes. In cases where we are connecting to a server process running on a
	remote host, the server process may well outlive the proxy.)</p>

	<p>Servers have a <b>server runtime</b>. The server runtime corresponds to the
	installed code base for the server. The main role played by the server runtime
	is in identifying code libraries to compile or build against. In the case of
	local servers, the server runtime may play a secondary role of being used to
	launch the server for testing. Having the server runtimes identified as an
	entity separate from the server itself facilitates sharing server runtimes
	between several servers.</p>

	<p>Servers have an optional <b>server configuration</b>. The server
	configuration is information used to configure a running server. Simple types of
	servers might not require any configuration, whereas full-featured web server
	have an extensive set of parameters for adjusting the server's behavior. Even
	though server configuration information usually takes the form of one or more
	files, configuration information is treated separately from actual content.
	Actual web content can be deployed on different servers without change, whereas
	server configuration information is usually highly dependent on the particulars
	of the server. Having the server configuration identified as an entity separate
	from the server itself facilitates switching an existing server between
	configurations, and sharing server configurations between several servers (e.g.,
	a local test server and a remote server running on another host).</p>

	<p>The content that is developed for a server comes in <b>modules</b>. A
	module usually consists of a tree of files; a static HTML web is one simple
	example. Different types of modules consist of possibly constrained arrangements
	files of certain file types. The files making up a module under development
	reside in the Eclipse workspace. In order for a server to access the content
	within a module, the module in the workspace must be <b>published</b> to the
	server (we use the term <i>publish</i> rather than <i>deploy</i> which is
	overused in J2EE). The module is the unit of content that is published to a
	server. In the case of J2EE servers, the notion of module aligns with the J2EE
	notion of a module (a server concept). But that needn't be the case; some
	types of servers, such as a simple HTTP server, don't have a notion of module.
	Either way, publishing a module to the server entails whatever it takes to get
	the publishable content from the workspace to the server in a form that the
	server can access it. Different types of server runtimes are capable of support
	various module types. Some server types may be able to serve modules directly
	out of the workspace without copying.</p>

	<p>At any given time, the developer may be working with any number of servers.
	Each server has a set of modules and may have a server configuration. From the complete
	set of modules in the workspace, any particular server may see only a subset,
	although it is also possible for all servers to see all available modules. After
	the developer makes changes to the modules in the workspace and now wants to
	test their modification, they republish the modules to the server. Depending on
	the type of server, republishing a module may entail stopping and restarting the
	server.</p>

	<p>Some types of modules can have other modules as children. The standard
	example of this is a J2EE Enterprise Application (EAR) module, whose children are
	simple J2EE modules like Enterprise Java Beans and Web Applications. The
	parent-child relationship is weak: two parent modules can share the same child
	module, and the same child can be parented by several modules (on the same or on
	different servers). The file trees for modules are normally mutually disjoint.
	Module containment is not reflected by any sort of directory nesting. Parent and
	child modules map to non-overlapping file trees.</p>

	<p>Modules typically reside in the workspace. The arrangement is usually that each
	module exists in a single project, where the content usually
	corresponds to a particular folder within a project rather than the root of the
	project. This allows the project to contain other files (e.g., .project, .classpath,
	source code) that are not considered part of the module content proper. Each
	different type of module has its own rules for how the content files within it
	are laid out. For instance, a J2EE web module has the same structure as an
	unzipped WAR file. (Note that the module structure rules are largely implicit
	and not reflected directly in the APIs.) It is possible for a project to
	contains more than one module (although this arrangement is less common, and not
	as well supported).</p>

	<p>During development, projects containing modules can be <b>targeted</b> to a
	particular server runtime. Targeting allows the IDE to set up various
	development time properties of the project (such as the backbone of the Java
	build path) appropriately. The most common scenario is where the project is
	targeted to the server runtime for the server to which the module is being
	published. However, it is also possible to target one server runtime (e.g., a
	generic J2EE 1.3 server runtime) while publishing to a server with a different
	server runtime (e.g., a Tomcat v5.0 server). Targeting a project to a particular
	server runtime typically establishes the Java build classpath of the project to
	include the libraries containing the Java APIs for that server runtime (e.g.,
	the appropriate J2EE class libraries). The Java build classpath also needs to
	reflect inter-module dependencies; for J2EE module types, the appropriate
	entries are typically derived from the module's manifest.</p>

	<p>The main goals of the Server Core client APIs are to allow clients to create,
	configure, and launch instances of particular server types. Due to differences
	in the behavior (and APIs) of different server types, a client must generally be
	knowledgeable of rules for a particular server type. Clients that have no
	knowledge of any specific server type are limited to doing things like starting,
	stopping, and relaunching existing servers. In other words, the clients APIs are
	generally server-type-specific, rather than sever-type-generic.</p>

	<p>The web tools server architecture allows for an open-ended set of server
	types, server runtime types, and module types. New
	types are declared via extension points in the Server Core plug-in (org.eclipse.wtp.server.core).
	Server types are declared by the serverTypes extension point; server runtime
	types, by runtimeTypes; and module types, by moduleKinds.
	(Additional extension points are discussed below.)
	Associated with these extension points are core APIs designed for use by
	clients contributing to the Server Core extension points; these are more
	correctly called SPIs (service provider interfaces) to distinguish them from the
	code designed to be used by other clients (which we refer to here as client
	APIs).</p>

	<p>Many of the extension points provide for a dynamic code component in addition
	to the static information supplied in the extension declaration. These are
	termed <i>delegates</i>. For instance, all communication with the running server
	is handled by a <b>server delegate</b> contributed via the server type extension
	point. Clients generally deal directly with a layer of objects exposed by the
	API expressly for client use. In the case of server, clients deal with an
	IServer. IServer has a fixed, hidden implementation (the internal class Server),
	which hangs on to a lazily-created server delegate of type IServerDelegate. The
	IServerDelegate implementation is a server-type-specific object. The more
	interesting IServer methods (e.g., getServerState()) are handled by the
	delegate. There are also getDelegate() methods that bridge API to SPI, allowing
	clients to call methods on the delegate directly. Service providers may also
	choose to expose their delegate implementation as API. This allows, for example,
	the provider of a server type to offer additional API that is
	server-type-specific.</p>

	<p>A <b>module factory</b> is responsible for creating modules. There can be any
	number of registered module factories, declared via the
	org.eclipse.wtp.server.core.moduleFactory extension point. A module factory may
	create one or more types of modules (also declared in the extension point). The
	module factory API does not prescribe a way to create modules; it does, however,
	provide methods for retrieving extant modules that it was responsible for
	creating (IModuleFactoryDelegate.getModules() and
	IModuleFactoryDelegate.getModule(String memento)).</p>

	<p>To sync up changes in the local workspace with the server, clients call
	IServer.publish(IProgressMonitor monitor), which will publish the changes to
	the server. The server framework handles figuring out which modules have been
	changed and what resources have changed within the module, but the server
	delegate is called to do the actual publish operation.</p>

	<p>The client API exposes:</p>
	<ul>
	<li>Server runtime types as IRuntimeType. ServerCore.getRuntimeTypes() returns
	all known server runtime types.</li>
	<li>Server types as IServerType. ServerCore.getServerTypes() returns all known
	server types.</li>
	<li>Module types as IModuleType.</li>
	</ul>
	<p>The type-level relationships are:</p>
	<ul>
	<li>a server type has a server runtime type; this is the type of server
	runtime required to run the server; exposed as IServerType.getRuntimeType()</li>
	<li>a server type has an optional server configuration</li>
	<li>a server runtime type supports 0 or more module types; exposed as
	IRuntimeType.getModuleTypes()</li>
	</ul>

	<p>The API exposes server runtime instances as IRuntime.
	ServerCore.getRuntimes() returns all known server runtime
	instances. Server runtime instances are created (only) from server runtime types
	by IRuntimeType.createRuntime(String id), which returns an IRuntimeWorkingCopy.
	Any number of aspects of the server runtime instance (including location in the
	file system) can be established or adjusted from their defaults. When editing is
	complete, IRuntimeWorkingCopy.save(IProgressMonitor monitor) creates, registers,
	returns a server runtime instance (IRuntime) capturing the desired settings (the
	working copy is disposed of).</p>

	<p>The API exposes server instances as IServer.
	ServerCore.getServers() returns all known server instances.
	Server instances are created (only) from server types by
	IServerType.createServer(String id, IFile file, IRuntime runtime,
	IProgressMonitor monitor) or IServerType.createServer(String id, IFile file,
	IRuntime runtime, IProgressMonitor monitor). The file parameter is used to
	control where the server instance is serialized. Both return an
	IServerWorkingCopy. Any number of aspects of the server instance (host name,
	server runtime, server configuration, modules, ...) can be established or
	adjusted from their defaults. When editing is complete,
	IServerWorkingCopy.save(IProgressMonitor monitor) creates, registers, returns a
	server instance (IServer) capturing the desired settings (the working copy is
	disposed of).</p>

	<p>The instance-level relationship between servers and server runtimes and
	server configurations is exposed at the API: for a given server,
	IServer.getRuntime() returns the server runtime (IRuntime),
	IServer.getServerConfiguration() returns the server configuration (IServerConfiguration).</p>

	<p>IServer.start(String mode, IProgressMonitor monitor), stop(), and
	restart(String mode) are used to start, stop, and restart a server, respectively
	(there are also synchronous methods for starting and stopping). The predicates
	IServer.canStart(String mode), canRestart(String mode), and canStop() indicate
	whether the server is receptive to being controlled. IServer.getServerState()
	can be used to query the overall state of the server (one of starting, started,
	stopping, stopped, or unknown), and IServer.getModuleState(IModule module) can
	be used to query the state of any of its modules.</p>

	</body>
	</html>