*** empty log message ***
diff --git a/development/miscdocuments/server/Server Tools API Changes.html b/development/miscdocuments/server/Server Tools API Changes.html new file mode 100644 index 0000000..6f44d8e --- /dev/null +++ b/development/miscdocuments/server/Server Tools API Changes.html
@@ -0,0 +1,352 @@ +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<link rel="stylesheet" href="http://www.eclipse.org/default_style.css" type="text/css"> +<title>Server Tools API Changes</title> +<style> +td { font-family: arial, helvetica, geneva; font-size: 9pt; vertical-align: top; } +td.code { font-family: "Courier New", Courier, mono; font-size: 7.75pt} +</style> +</head> + +<body alink="#ff0000" bgcolor="#ffffff" link="#0000ee" text="#000000" vlink="#551a8b"> + +<table border="0" cellpadding="2" cellspacing="5" width="100%"> + <tbody><tr> + <TD WIDTH=60%> + <P ALIGN=LEFT><B><FONT SIZE=6><FONT FACE="Verdana, Arial, Helvetica, sans-serif">Server Tools API Changes</FONT></FONT></B><BR> + <FONT SIZE=1><FONT FACE="Arial, Helvetica, sans-serif"><FONT COLOR="#8080ff">Information on Server Tools API Changes</FONT></FONT></FONT> + </P> + </TD> + <td rowspan="2" width="19%"><img src="http://www.eclipse.org/images/Idea.jpg" border="0" height="86" width="120"></td> + </tr> +</tbody></table> + + +<table border="0" cellpadding="2" cellspacing="5" width="100%"> + <tbody><tr> + <td colspan="2" align="left" bgcolor="#0080c0" valign="top"><b><font color="#ffffff" face="Arial,Helvetica">M1 Changes</font></b></td> + </tr></tbody> +</table> + +Here are the Server Tools API changes that went into M1. + +<p/> + +<table border=1 cellspacing="0"> +<tr> + <th>Change</th> + <th>Reason</th> + <th>Old Code</th> + <th>New Code</th> +</tr> +<tr> + <td>Package renames:<br/> + com.ibm.wtp.server.core -> org.eclipse.wst.server.core<br/> + com.ibm.wtp.server.ui -> org.eclipse.wst.server.ui<br/> + com.ibm.wtp.server.util -> org.eclipse.wst.server.util<br/> + com.ibm.wtp.server.java.core -> org.eclipse.jst.server.core<br/> + com.ibm.wtp.server.java.ui -> org.eclipse.jst.server.ui<br/> + com.ibm.wtp.server.tomcat.core -> org.eclipse.jst.server.tomcat.core<br/> + com.ibm.wtp.server.tomcat.ui -> org.eclipse.jst.server.tomcat.ui<br/> + com.ibm.wtp.monitor.core -> org.eclipse.wst.monitor.core<br/> + com.ibm.wtp.monitor.ui -> org.eclipse.wst.monitor.ui<br/> + com.ibm.wtp.webbrowser -> org.eclipse.wst.webbrowser</td> + <td>Renaming for open source</td> + <td></td> + <td></td> +</tr> +<tr> + <td></td> + <td></td> + <td></td> + <td></td> +</tr> +</table> + + + + +<table border="0" cellpadding="2" cellspacing="5" width="100%"> + <tbody><tr> + <td colspan="2" align="left" bgcolor="#0080c0" valign="top"><b><font color="#ffffff" face="Arial,Helvetica">M2 Changes</font></b></td> + </tr></tbody> +</table> + +Here are the Server Tools API changes that went into M2. + +<p/> + +<table border=1 cellspacing="0"> +<tr> + <th>Change</th> + <th>Reason</th> + <th>Old Code</th> + <th>New Code</th> +</tr> +<tr> + <td>All java.util.Lists returned from methods have been changed to arrays of the corresponding + content type.</td> + <td>Stronger typed return values are safer, and returning a copy of the list (instead of the list + itself) blocks against clients modifying internal data structures.</td> + <td class="code">List list = ServerCore.getRuntimeTypes();</td> + <td class="code">IRuntimeType[] rt = ServerCore.getRuntimeTypes();</td> +</tr> +<tr> + <td>IResourceManager has been removed. Most of it's methods have been moved to the ServerCore + class, with the remaining ones in ServerUtil.</td> + <td>There was no client benefit of the resource manager, and it was misnamed.</td> + <td class="code">ServerCore.getResourceManager().getServers();</td> + <td class="code">ServerCore.getServers();</td> +</tr> +<tr> + <td>All extension point interfaces have been changed to abstract classes, and the "I" removed + from the name.</td> + <td>Allows for future support and maintenance without breaking existing interfaces.</td> + <td class="code"></td> + <td class="code"></td> +</tr> +<tr> + <td>Several interfaces were moved from the .core.model package to .core.</td> + <td>The .core.model package was meant for SPIs, not API. All API classes & interfaces will + be moved or remain in .core so that API users do not need to use the .core.model package.</td> + <td class="code">import org.eclipse.wst.server.code.model.IModule;</td> + <td class="code">import org.eclipse.wst.server.code.IModule;</td> +</tr> +<tr> + <td>IServerResourceListener renamed to IServerLifecycleListener. Several methods moved out to + new IRuntimeListener and IServerConfigurationListener interfaces.</td> + <td>"Resource" had to be removed from the name, and the interface contained methods for + runtimes and server configurations as well. They are split up so that API users do not + need to listen for all types of changes from a single interface.</td> + <td class="code">ServerCore.getResourceManager().addServerResourceListener(myListener);</td> + <td class="code">ServerCore.addRuntimeLifecycleListener(myListener);</td> +</tr> +<tr> + <td>Publishing interfaces completely rewritten & .core.resources package removed.</td> + <td>The publishing interface was outdated and written before the Eclipse team support, + ANT, or other recent publishing methods had been developed. The new API allows for + better support and for each server type to use it's own publishing mechanism.</td> + <td class="code"></td> + <td class="code"></td> +</tr> +<tr> + <td>IRuntimeDelegate and IRuntimeWorkingCopyDelegate merged into a single RuntimeDelegate. + IServerDelegate and IServerWorkingCopyDelegate reworked into + ServerDelegate and ServerBehaviourDelegate.</td> + <td>Making clients provide two separate classes for the delegates was excessive, + unnecessary, and ended up with too many SPI classes. Only a single delegate class is + now required for these extension points.</td> + <td class="code"></td> + <td class="code"></td> +</tr> +<tr> + <td>IRuntime.getDelegate(), IRuntime.getWorkingCopyDelegate() changed into IRuntime extending + IAdaptable. Similar for IServer and other delegates</td> + <td>IAdaptable is a common Eclipse mechanism, and allows for other extension as well. Clients + should still remember that calling this method may involve plugin loading, so it should + not be used in popup menus, etc.</td> + <td class="code">ITomcatRuntime tr = (ITomcatRuntime) runtime.getDelegate();</td> + <td class="code">ITomcatRuntime tr = (ITomcatRuntime) runtime.getAdapter(ITomcatRuntime.class);</td> +</tr> +<tr> + <td>IModuleType and IModuleKind interfaces merged.</td> + <td>IModuleKind was created late in the previous release cycle and couldn't be merged at the + time it was created.</td> + <td class="code"></td> + <td class="code"></td> +</tr> +<tr> + <td>IServerTask changed and IModuleTask removed.</td> + <td>The existing interfaces had an ITask directly returned as a delegate, and only allowed a + single task per extension point. The new IServerTask allows the delegate to return multiple + tasks from a single extension point, and it is not itself a task.</td> + <td class="code"></td> + <td class="code"></td> +</tr> +<tr> + <td>IServerConfiguration, IServerConfiguration, etc. removed</td> + <td>The server config was a relic and did not need to be a first class resource. ServerDelegates + are now directly responsible for maintaining the configuration.</td> + <td class="code"></td> + <td class="code">see Tomcat implementation</td> +</tr> +<tr> + <td>Various minor cleanup - methods renamed, parameters changed, etc.</td> + <td>Cleanup and future maintenance.</td> + <td class="code"></td> + <td class="code"></td> +</tr> +<tr> + <td>IModuleObjectAdapter -> IModuleArtifactAdapter, IModuleObject -> IModuleArtifact</td> + <td>Object was too generic and didn't have any real meaning. Artifact represents what the + IModuleObject really represents - resources within a module</td> + <td class="code"></td> + <td class="code"></td> +</tr> +<tr> + <td>getServerType(String id) -> findServerType(String id)</td> + <td>Lookup methods on ServerCore and ServerUtil renamed to be more accurate to what + they do.</td> + <td class="code">IServerType st = getServerType("com.x")</td> + <td class="code">IServerType st = findServerType("com.x")</td> +</tr> +<tr> + <td>Lots of methods & interfaces moved to internal packages</td> + <td>Need to trim down the exposed API to only what is required for ongoing maintenance. If + there is anything in an internal package that you were previously using, or plan to use + in the future, please contact me and we'll work out an API solution</td> + <td class="code"></td> + <td class="code"></td> +</tr> +<tr> + <td>Publishing changes - several interfaces and the org.eclipse.wst.server.core.resource + package removed</td> + <td>The old publishing mechanism did not allow flexibility in publishing options (e.g. + ANT, Eclipse team support, or some other mechanism) and used an outdated publishing + manager framework.</td> + <td class="code"></td> + <td class="code">ServerDelegate.publishStart(); // Called to tell the server that publishing is starting. + Can be used to connect to a remote server, etc.<br/> + ServerDelegate.publishStart(); // Called once to allow the server to publish any "global" + resources or a server config<br/> + ServerDelegate.publishStart(); // Called for each module to give the server a chance + to publish using any method it wants<br/> + ServerDelegate.publishFinish(); // Called to disconnect from the server or cleanup</td> +</tr> +<tr> + <td>IMonitorableServer merged with IServer</td> + <td>No need for additional interface</td> + <td class="code">IServerDelegate delegate = server.getDelegate()<br/> + if (delegate instanceof IMonitorableServer) {<br/> + IMonitorableServer ms = (IMonitorableServer) delegate;<br/> + List ports = ms.getServerPorts();<br/> + }</td> + <td class="code">IServerPort[] ports = server.getServerPorts();</td> +</tr> +<tr> + <td>Working copy changes</td> + <td>Previously, references were kept to every working copy, and clients had to save() or + release() them in finally blocks or else the reference would be dangling (and possibly + blocking other changes) forever. This code was unsafe and caused problems if a client + tried to use a working copy after it had been saved or released. + Now, clients can create a working copy at any time, and references are not kept. On + save, a client can specify whether the working copy changes should be forced, or not + (in which case the save will fail if someone else has made changes to the object in + the meantime). If the changes do not need to be saved, clients can just drop the + reference to the working copy at any time. As before, working copies should not be + used for long periods of time since it increases the chances that another client has + made changes</td> + <td class="code">IServerWorkingCopy wc = IServer.getWorkingCopy();<br/> + // do something with wc<br/> + wc.save(); or wc.release();</td> + <td class="code">IServerWorkingCopy wc = IServer.createWorkingCopy();<br/> + // do something with wc<br/> + wc.save(); or lose reference</td> +</tr> +<tr> + <td>Change IServer.isRestartNeeded() to match other methods</td> + <td></td> + <td class="code">IServer.isRestartNeeded();</td> + <td class="code">IServer.getServerRestartState();</td> +</tr> +<tr> + <td></td> + <td></td> + <td class="code"></td> + <td class="code"></td> +</tr> +</table> + + + +<table border="0" cellpadding="2" cellspacing="5" width="100%"> + <tbody><tr> + <td colspan="2" align="left" bgcolor="#0080c0" valign="top"><b><font color="#ffffff" face="Arial,Helvetica">M3 Changes</font></b></td> + </tr></tbody> +</table> + +Here are the Server Tools API changes that went into M3. + +<p/> + +<table border=1 cellspacing="0"> +<tr> + <th>Change</th> + <th>Reason</th> + <th>Old Code</th> + <th>New Code</th> +</tr> +<tr> + <td>Remove serverAction extension point</td> + <td>Duplicate function exists in Eclipse v3.0</td> + <td class="code"><extension point="org.eclipse.wst.server.ui.serverActions"><br/> + <serverAction id="org.eclipse.wst.server.ui.projects"<br/> + typeIds="org.eclipse.jst.*"<br/> + label="%actionModifyModules"<br/> + category="control"<br/> + icon="icons/ctool16/wiz_modify_modules.gif"<br/> + order="50"<br/> + class="org.eclipse.wst.server.ui.internal.actions.AddRemoveModulesAction"/><br/> +</extension></td> + <td class="code"><extension point="org.eclipse.ui.popupMenus"><br/> + <objectContribution<br/> + id="org.eclipse.wst.server.ui.popupMenu"<br/> + objectClass="org.eclipse.wst.server.core.IServer"<br/> + adaptable="true"><br/> + <filter name="typeIds" value="org.eclipse.jst.*"/><br/> + <action<br/> + id="org.eclipse.wst.server.ui.action.modifyModules"<br/> + label="%actionModifyModules"<br/> + icon="icons/ctool16/wiz_modify_modules.gif"<br/> + class="org.eclipse.wst.server.ui.internal.actions.ModifyModulesAction"><br/> + </action><br/> + </objectContribution><br/> +</extension></td> +</tr> +<tr> + <td>Remove objectClass attribute from moduleArtifactAdapter extension point and switch to expressions</td> + <td>Removal of IModuleArtifactAdapter class</td> + <td class="code"></td> + <td class="code"></td> +</tr> +<tr> + <td>IElement and IElementWorkingCopy removed</td> + <td>There was no point having common code between IRuntime and IServer, since they didn't really have + any common structure. Existing methods moved to correct location in IRuntime, IServer, and their working copies.</td> + <td class="code"></td> + <td class="code"></td> +</tr> +<tr> + <td>IModuleEvent and IModuleFactoryEvent changed to ModuleEvent and ModuleFactoryEvent</td> + <td>Event classes are not typically interfaces, and there was no reason to abstract these two classes.</td> + <td class="code">IModuleEvent<br/>IModuleFactoryEvent</td> + <td class="code">ModuleEvent<br/>ModuleFactoryEvent</td> +</tr> +<tr> + <td>IServerPreferences removed</td> + <td>IServerPreferences was not required as API and was not being used by external plugins. To clean up API, + it is being removed from the first API version.</td> + <td class="code"></td> + <td class="code"></td> +</tr> +<tr> + <td>ServerBehaviourDelegate.setLaunchDefaults() renamed</td> + <td>ServerBehaviourDelegate.setLaunchDefaults() was renamed to ServerBehaviourDelegate.setupLaunchConfiguration(). + It is now called on every launch instead of just the first time. This allows servers to update the launch + configuration before it is executed.</td> + <td class="code"></td> + <td class="code"></td> +</tr> +<tr> + <td></td> + <td></td> + <td class="code"></td> + <td class="code"></td> +</tr> +</table> + +</body> +</html> \ No newline at end of file
diff --git a/development/miscdocuments/server/Server Tools Package Renames.properties b/development/miscdocuments/server/Server Tools Package Renames.properties new file mode 100644 index 0000000..8fb5668 --- /dev/null +++ b/development/miscdocuments/server/Server Tools Package Renames.properties
@@ -0,0 +1,10 @@ +com.ibm.wtp.server.core=org.eclipse.wst.server.core +com.ibm.wtp.server.ui=org.eclipse.wst.server.ui +com.ibm.wtp.server.util=org.eclipse.wst.server.util +com.ibm.wtp.server.java.core=org.eclipse.jst.server.core +com.ibm.wtp.server.java.ui=org.eclipse.jst.server.ui +com.ibm.wtp.server.tomcat.core=org.eclipse.jst.server.tomcat.core +com.ibm.wtp.server.tomcat.ui=org.eclipse.jst.server.tomcat.ui +com.ibm.wtp.monitor.core=org.eclipse.wst.monitor.core +com.ibm.wtp.monitor.ui=org.eclipse.wst.monitor.ui +com.ibm.wtp.webbrowser=org.eclipse.wst.webbrowser \ No newline at end of file
diff --git a/development/miscdocuments/server/ServerToolsUseCases.html b/development/miscdocuments/server/ServerToolsUseCases.html new file mode 100644 index 0000000..4b81287 --- /dev/null +++ b/development/miscdocuments/server/ServerToolsUseCases.html
@@ -0,0 +1,325 @@ +<!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en"> +<html><head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + +<link rel="stylesheet" href="http://www.eclipse.org/default_style.css" type="text/css"> +</head> + + + +<body alink="#ff0000" bgcolor="#ffffff" link="#0000ee" text="#000000" vlink="#551a8b"> + +<table border="0" cellpadding="2" cellspacing="5" width="100%"> + + <tbody><tr> + + <TD WIDTH=60%> + <P ALIGN=LEFT><B><FONT SIZE=6><FONT FACE="Verdana, Arial, Helvetica, sans-serif">Server Tools Use Cases</FONT></FONT></B><BR><FONT SIZE=1><FONT FACE="Arial, Helvetica, sans-serif"><FONT COLOR="#8080ff">the + Server Tools Use Cases</FONT></FONT></FONT> + </P> + </TD> + + +</td> + +<!-- <td width="19%" rowspan="2"><img src="images/Idea.jpg" height=86 width=120></td> --> + + <td rowspan="2" width="19%"><img src="http://www.eclipse.org/images/Idea.jpg" border="0" height="86" width="120"></td> + + </tr> + + +</tbody></table> + +<table border="0" cellpadding="2" cellspacing="5" width="100%"> + + <tbody><tr> + + <td colspan="2" align="left" bgcolor="#0080c0" valign="top"><b><font color="#ffffff" face="Arial,Helvetica">Principles</font></b></td> + + </tr> +<tr> +<td> +<p>The purpose of this document is to list explicit use cases for the server tools component. These uses cases can be used to both help guide design (to make sure minimal API is sufficient to support these listed, and only these listed, use cases) and to help guide testing (both unit tests, and milestone/release testing).</p> + <P><B>Principle:</B> We'll consider starting point naive end users who + know nothing of servers, and they don't care, just want one installed + installed so they can focus on their web development. We'll consider + three levels: 1) User does near nothing, 2) user doesn't do much, but + may have to provide some configuration values and/or import + configuration values. 3) User has to provide many configuration + values, and in the worst cases, actually write ant scripts.</P> + <p><b>Principle:</b> In addition to "end user" use cases, +we'll specify "client code" uses-case that may +simply be specifying details of function needed for end-user use cases, but +will always have a unit test associated with it. Also, we'll specify "service provider" +use cases which can be used to define SPI's. </p> +</td> +</tr> +<tr> + <td colspan="2" align="left" bgcolor="#0080c0" valign="top"><b><font color="#ffffff" face="Arial,Helvetica">End User Use Cases</font></b></td> + </tr> + <tr> + <td> + <table width="95%" border="1" cellpadding="1" cellspacing="1"> + <tbody> + <tr> + <th style="width: 108px">Name</th> + <th style="width: 60px">Priority</th> + <th style="width: 360px">Description</th> + </tr> + <tr> + <td>Install a Server</td> + <td>2</td> + <td>From an update site, user can install a + server (using Eclipse standard update manager functions).</td> + </tr> + <tr> + <td>Configure a Jakarta-tomcat</td> + <td>1</td> + <td>Given a Jakarta-tomcat server (V5) installed + on local file system, user can "install" a server to WTP by + selecting from a list of available server adapters, selecting the one + for Jakarta-tomcat server, and specifying location of server's + install directory. + <table border="1"> + <tbody> + <tr> + <td>Variant 1</td> + <td style="width: 277px">JBoss Server instead</td> + </tr> + </tbody> + </table> + </td> + </tr> + + <tr> + <td>Export ANT build scripts for modules</td> + <td>1</td> + <td>User exports ANT build script that compiles and packages a module in for use outside the Eclipse, possibly for automated builds. </td> + </tr> + <tr> + <td>Drag a module/artifact to a server to publish it</td> + <td>3</td> + <td>Users drags a module or a artifact in it into a server, which would mean the same action as "Run on Server" .</td> + </tr> + + <tr> + <td>run on J2EE server</td> + <td>1</td> + <td>user can select a JSP and "run on + server", meaning it will be displayed in Eclipse web browser. + <table border="1"> + <tbody> + <tr> + <td style="width: 66px">Variant 1</td> + <td style="width: 348px">If no more than one installed, the user + will not get list to select from</td> + </tr> + </tbody> + </table> + <table border="1"> + <tbody> + <tr> + <td style="width: 69px">Variant 2</td> + <td style="width: 345px">If none installed, the user will be given + a chance to select and install one (see Install a Server)</td> + </tr> + </tbody> + </table> + <table border="1"> + <tbody> + <tr> + <td style="width: 65px">Variant 3</td> + <td style="width: 349px">If more than one installed, user given + the list</td> + </tr> + </tbody> + </table> + </td> + </tr> + <TR> + <TD>run on HTTP server</TD> + <TD></TD> + <TD>User can select an HTML file, and "run on server". This use case can be performed with WST only. (This use case has not gotten a lot of discussion, but support for "static projects" is mentioned in WTP/WST vision statement, and is a good case to make sure the architecture and design is correct). </TD> + </TR> + + <tr> + <td>Adapt to existing project/module layout<i>(I am not sure, this is may be a use case for project layout)</i></td> + <td>1</td> + <td>User describes the current project layout even if it is not a known layout of any kind. </td> + </tr> + + <tr> + <td>Add runtime</td> + <td>1</td> + <td>Add a new server runtime environment that exists on the user's machine. (Pick runtime from list. Enter name, location. Enter runtime specific information.)</td> + </tr> + + <tr> + <td>Edit or remove runtime</td> + <td>1</td> + <td>Modify runtime attributes or remove.</td> + </tr> + + <tr> + <td>Target project</td> + <td>1</td> + <td>Target a project to a specific runtime. This is optional and a project may only be targetted to one runtime at a time. (Some project types do + not need a target, some projects do need a target)</td> + </tr> + + <tr> + <td>Add server</td> + <td>1</td> + <td>Add (install) a new server. Enter name & hostname, pick a server type from a list, and enter server specific information. (Some server types may only support local, not remote. Some local servers may require a runtime.)</td> + </tr> + + <tr> + <td>Edit or remove server</td> + <td>1</td> + <td>Modify server attributes or remove.</td> + </tr> + + <tr> + <td>Start/Stop/Restart</td> + <td>1</td> + <td>Each server type may support some/all/none of these state changes. Each server type has an initial state (may be unknown), and must keep the state in sync once it is loaded. + Some of the state changes (start/stop) are not available unless the server is in the correct state. Console/Debug view, etc. should be sync'ed up or used as it makes sense + for the server type. Starting may be done in the regular Eclipse launch modes, e.g. Run, Debug, Profile, ... depending on what the server supports. Launch Configurations are + created and used as applicable.</td> + </tr> + + <tr> + <td>Add project</td> + <td>1</td> + <td>Add a module to a server. User is presented with a list of modules that are available to be added to the server, as well as a list of modules from the workspace that are + already on the server. In some cases, the server may present additional modules in the second list that are not from the workspace/user. User can move modules around and + when they are done, the module is configured on (and possibly published to) the server.</td> + </tr> + + <tr> + <td>Remove project</td> + <td>1</td> + <td>Same as above</td> + </tr> + + <tr> + <td>Publish/Sync</td> + <td>1</td> + <td>One way publish of all modules to a particular server. Syncs the module content - could be a delta or a full refresh depending on the implementation.</td> + </tr> + + <tr> + <td>Restart module</td> + <td>1</td> + <td>Optional based on server type support. Restart/refresh/remove cache for a particular module on the server to allow the newly published content to be served.</td> + </tr> + + <tr> + <td>Change notification</td> + <td>1</td> + <td>User makes a change to a module (e.g. edit a file). User should be notified of the impact to any running servers and what they need to do to get the change + propogated to the server. (e.g. nothing, republish, restart module, restart server) </td> + </tr> + + <tr> + <td>Auto update</td> + <td>2</td> + <td>Automatically or via a single click, do the above use case to keep server in sync at all times.</td> + </tr> + + <tr> + <td>Run/Debug/Profile on Server</td> + <td>1</td> + <td>From any artifact (UI selection, editor input, etc.), determine which module it belongs to, prompt to choose or create a server if necessary, publish/sync the module on the server, and display an + appropriate client to access (run) that artifact on the server.</td> + </tr> + +<!-- <tr> + <td></td> + <td>1</td> + <td></td> + </tr>--> + + </tbody> +</table> +</td></tr> + +<tr> + <td colspan="2" align="left" bgcolor="#0080c0" valign="top"><b><font color="#ffffff" face="Arial,Helvetica">API Use Cases</font></b></td> + </tr> + + +<tr><td> + <table width="95%" border="1" cellpadding="1" cellspacing="1"> + <tbody> + <tr> + <th style="width: 108px">Name</th> + <th style="width: 60px">Priority</th> + <th style="width: 360px">Description</th> + </tr> + + <tr> + <td>Create module type(s)</td> + <td>1</td> + <td>Define a new type of module (interface and id) so that other SPI providers can provide instances of these module or servers that support them.</td> + </tr> + + <tr> + <td>Provide module factory</td> + <td>1</td> + <td>Define a new module factory for creating/discovering the modules of an existing type. (.modules file?)</td> + </tr> + + <tr> + <td>Define runtime type</td> + <td>1</td> + <td>Define a new runtime type, along with the module types that it supports. Define what it means to target a project to this runtime.</td> + </tr> + + <tr> + <td>Define server type</td> + <td>1</td> + <td>Define a new server type, along with the module types this it supports. Provide implementations for add/remove modules, publishing, start/stop, etc.</td> + </tr> + + <tr> + <td>get list of server adapters</td> + <td>1</td> + <td>programmatically get list of known + Jakarta-tomcat servers adapters and their associated information + (name, version, whether installed or not, etc)</td> + </tr> + <tr> + <td>get list of installed servers</td> + <td>1</td> + <td>programmatically get list of installed + servers and their associated information (name, etc)</td> + </tr> + <tr> + <td>import/export server configuration</td> + <td>2</td> + <td>Can import or export server configuration + files, such as to give to another member of team. This file may best + be in XML format.</td> + </tr> + <tr> + <td>Server Providers can provide discoverable adapter</td> + <td>1 - SPI</td> + <td>The information needed to be listed as potential server adapter can be found completely in plugin.xml (not Java code, which would require activation of plugin). </td> + </tr> + + <tr> + <td>Provide classloader behavior</td> + <td>1</td> + <td>A client, a jsp/ejb compiler for example, learns the classloader behavior to mimic the server runtime environment</td> + </tr> + + </tbody> +</table> + </td> +</tr> +</tbody></table> + + +</body></html> \ No newline at end of file
diff --git a/development/miscdocuments/server/WTP Server Core APIs.ppt b/development/miscdocuments/server/WTP Server Core APIs.ppt new file mode 100644 index 0000000..bd46f3c --- /dev/null +++ b/development/miscdocuments/server/WTP Server Core APIs.ppt Binary files differ
diff --git a/development/miscdocuments/server/web_tools_server_api_concepts.html b/development/miscdocuments/server/web_tools_server_api_concepts.html new file mode 100644 index 0000000..8b4b23f --- /dev/null +++ b/development/miscdocuments/server/web_tools_server_api_concepts.html
@@ -0,0 +1,260 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>API Concepts and Roles</title> +</head> + +<body> + +<h1>WTP Server Tools<br> +API Concepts and Roles</h1> +<p>Last modified Nov. 2, 2004</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 +plug-in</a>. 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 web content that is developed for a web 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 use 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.</p> +<p>At any given time, the developer may be working with any number of servers. +Each server has a server configuration and a set of modules. From the complete +set of modules in the workspace, any particular server may see only a subset, +although it is also common 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 (EA) 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 reside in the workspace. The typical arrangement is that each module +has its own project, termed a <b>module project</b>. The module 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>A <b>server project</b> is a project used to hold serialized server (server +runtime, server configuration) instances. The project is tagged with a special +Eclipse server nature. The main reason behind server projects was as an +efficient means of making these serialized files visible in the resource +navigator and monitoring changes to them.</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, server configuration 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; server configuration types, by serverConfigurationTypes; +and module types, by moduleKinds. (Additional extension points are discussed +below.) Associated with these extension points are code 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>A <b>publish manager</b> is responsible for deciding whether a file resource +will be published or not (note: publishing includes file deletions as well as +file creations and modifications). Publish managers are declared via the +org.eclipse.wtp.server.core.publish extension point. +ServerCore.getPublishManagers() returns list of know publish managers. There are +two build-in headless publish managers. The Full Publish Manager is dumb, and +publishes all of the module's resource from workspace to server. The Smart +Publish Manager only publishes module resources that have been created, changed, +or deleted in the workspace, or ones that have been changed (somehow) on the +server. A publish operation initiated by IServer.publish(IProgressMonitor +monitor) uses the system-wide default publish manager, which defaults to the +Smart Publish Manager. (There's also a Visual Publish Manager that lets the user +pick and choose which files to publish.)</p> +<p>A <b>publisher</b> (IPublisher) is an object that actually publishes the file +of a particular module to a particular server. Each server type implements its +own publishers. On a particular occasion, the IServerDelegate.getPublisher(List +parents, IModule module) returns the publisher to use to publish the files of +the given module. IPublisher.publish(IModuleResource[] resource, +IProgressMonitor monitor) and IPublisher.delete(IRemoteResource[] resource, +IProgressMonitor monitor) do the heavy lifting.</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>Server configuration types as IServerConfigurationType. + ServerCore.getServerConfigurationTypes() returns all known server + configuration types.</li> + <li>Module types as IModuleKind. ServerCore.getModuleKinds() returns all known + module kinds.</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 type; this is the type + of server configuration required to configure the server; exposed as + IServerType.getServerConfigurationType()</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.getResourceManager().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 configuration instances as IServerConfiguration. +ServerCore.getResourceManager().getServerConfigurations() returns all known +server configuration instances. Server configuration instances are created +(only) from server types by +IServerConfigurationType.createServerConfiguration(String id, IFile file, +IProgressMonitor monitor) or IServerConfigurationType.importFromPath(String id, +IFile file, IPath path, IProgressMonitor monitor) or +IServerConfigurationType.importFromRuntime(String id, IFile file, IRuntime +runtime, IProgressMonitor monitor). The file parameter is used to control where +the server configuration instance is serialized. All 3 return an +IServerConfigurationWorkingCopy. (There are no aspects of the server +configuration instance to adjust.) +IServerConfigurationWorkingCopy.save(IProgressMonitor monitor) creates, +registers, returns a server configuration instance (IServerConfiguration) +capturing the desired settings (the working copy is disposed of). </p> +<p>The API exposes server instances as IServer. +ServerCore.getResourceManager().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>