1.0.2.RELEASE
Table of Contents
- 1. Installing
- 2. Start and Stop SpringSource dm Server
- 3. The Web based Administration Console
- 4. Provisioning Repository
- 5. Serviceability
- 6. Working with Applications
- 7. Configuring the SpringSource dm Server
- 8. Known Issues
- 9. Log Error Codes
- 10. Further Reading
The SpringSource dm Server requires Java SE 5 or later to be installed. Java is available from Sun and elsewhere.
SpringSource dm Server is distributed as a ZIP file. This can be downloaded from here. Follow the instructions to obtain a username and password.
To install the SpringSource dm Server on Linux, unzip the distribution package to the desired installation directory.
For example, to install into /opt:
unzip springsource-dm-server-1.0.2.RELEASE.zip -d /opt
This creates a directory called springsource-dm-server-1.0.2.RELEASE under /opt.
SpringSource dm Server requires write access to the installation directory, in this case /opt/springsource-dm-server-1.0.2.RELEASE.
Typically this means it must be run as the user that installed it, or the installation directory's ownership must be changed.
To install the SpringSource dm Server on Windows, unzip the distribution package to the desired installation directory. You should use a zip application such as 7zip, not the built-in folder decompression. Note that both Windows and Java 5 have some issues with long file names and file paths, so we recommend installing to the root directory of your chosen drive.
The SpringSource dm Server uses the JAVA_HOME environment variable to locate the java
executable. This environment variable must be configured to point to the home of a Java 5 or Java 6 installation.
As a convenience it is recommended to create an environment variable that points
to the SpringSource dm Server installation directory. Note that the SpringSource dm Server does not require that
such an environment variable has been set. This variable may have any name of your
choosing. The SpringSource dm Server's documentation assumes that the variable is named
SERVER_HOME.
Edit the .profile file in your home directory to
add the SERVER_HOME environment variable. For
example, if you installed into /opt:
export SERVER_HOME=/opt/springsource-dm-server-1.0.2.RELEASE/
From the Start menu, open the Control Panel and double-click on 'System'.
Click the 'Advanced' tab and select 'Environment Variables'. Next, click the 'Edit' button in the 'System Variables' section.
This will display the 'Edit System Variable' window. Enter
SERVER_HOME as the 'Variable name' and
the installation directory as the 'Variable value'. Click OK.
To start SpringSource dm Server run the startup script for your platform.
To start SpringSource dm Server run startup.sh:
cd $SERVER_HOME bin/startup.sh
Once SpringSource dm Server has started, the console will display a log message similar to the one shown below:
ingOsgiExtenderThread-38 <SPPM0002I> Server open for business with profile 'web'.
To start SpringSource dm Server run startup.bat:
(Open a command line) cd %SERVER_HOME% bin\startup.bat
Once SpringSource dm Server has started console will display a log message similar to the one shown below:
ingOsgiExtenderThread-38 <SPPM0002I> Server open for business with profile 'web'.
To clean start SpringSource dm Server run the startup script for your platform. Clean starting removes the SERVER_HOME/work directory (and hence all) running applications, and all trace, log and dump files. It leaves the SERVER_HOME/repository and SERVER_HOME/pickup directories untouched, so any applications previously hot deployed will be reinstalled.
To start SpringSource dm Server run startup.sh -clean:
cd $SERVER_HOME bin/startup.sh -clean
Once SpringSource dm Server has started, the console will display a log message similar to the one shown below:
ingOsgiExtenderThread-38 <SPPM0002I> Server open for business with profile 'web'.
To start SpringSource dm Server run startup.bat -clean:
(Open a command line) cd %SERVER_HOME% bin\startup.bat -clean
Once SpringSource dm Server has started console will display a log message similar to the one shown below:
ingOsgiExtenderThread-38 <SPPM0002I> Server open for business with profile 'web'.
To start SpringSource dm Server in debug mode, run
startup.sh passing in the
-debug argument:
cd $SERVER_HOME bin/startup.sh -debug
This will start the debug agent listening on port
8000 which is the default remote debug port used
by Eclipse. To start in debug mode with a specific port number, pass
this in as the value for the -debug argument:
cd $SERVER_HOME bin/startup.sh -debug 8001
This will start the debug agent listening on port
8001. To start in debug mode and suspend the VM
until a debugger attaches, pass in the -suspend
argument along with the -debug argument:
cd $SERVER_HOME bin/startup.sh -debug -suspend
This starts the debug agent, but prevents SpringSource dm Server from starting until a debugger attaches to the agent. This can be useful when trying to diagnose problems that occur during startup.
To start SpringSource dm Server in debug mode, run
startup.bat passing in the
-debug argument:
cd %SERVER_HOME% bin\startup.bat -debug
This will start the debug agent listening on port
8000 which is the default remote debug port used
by Eclipse. To start in debug mode with a specific port number, pass
this in as the value for the -debug argument:
cd %SERVER_HOME% bin\startup.bat -debug 8001
This will start the debug agent listening on port
8001. To start in debug mode and suspend the VM
until a debugger attaches, pass in the -suspend
argument along with the -debug argument:
cd %SERVER_HOME% bin\startup.bat -debug -suspend
This starts the debug agent, but prevents SpringSource dm Server from starting until a debugger attaches to the agent. This can be useful when trying to diagnose problems that occur during startup.
To start SpringSource dm Server with default JMX access enabled, run startup.sh passing
in no arguments:
cd $SERVER_HOME bin/startup.sh
This will start the SpringSource dm Server with JMX enabled for local attach. This allows for JConsole to be attached using the local connection option.
This will also start the SpringSource dm Server with JMX enabled for remote attach over SSL with username and password authentication. This allows for JConsole to be attached using the remote connection option on port 9875 with a default username and password of admin and springsource.
To start with the JMX remote access on a specific port number, pass this port number in as the value
for the -jmxport argument:
cd $SERVER_HOME bin/startup.sh -jmxport 9009
This will start the SpringSource dm Server with JMX enabled for remote attach on port
9009.
To start the JMX remote access using a custom username and password edit the file located at
$SERVER_HOME/control/jmx-users.properties. If you wish to use a different file
for authentication, pass this filename in as the value for the -jmxusers
argument:
cd $SERVER_HOME bin/startup.sh -jmxusers custom-jmx-users.properties
This will start the SpringSource dm Server with JMX enabled for remote attach using authentication
credentials from custom-jmx-users.properties.
To start the JMX remote access using a custom SSL certificate edit the file located at
$SERVER_HOME/control/keystore. If you wish to use a different keystore, pass
this filename in as the value for the -keystore argument and the keystore
password in as the value for the -keystorePassword argument:
cd $SERVER_HOME bin/startup.sh -keystore customKeystore -keystorePassword customeKeystorePassword
This will start the SpringSource dm Server with JMX enabled for remote attach using an SSL certificate from
customKeystore with a password of customKeystorePassword.
To start SpringSource dm Server with default JMX access enabled, run startup.sh passing
in no arguments:
cd %SERVER_HOME% bin\startup.sh
This will start the SpringSource dm Server with JMX enabled for local attach. This allows for JConsole to be attached using the local connection option.
This will also start the SpringSource dm Server with JMX enabled for remote attach over SSL with username and password authentication. This allows for JConsole to be attached using the remote connection option on port 9875 with a default username and password of admin and springsource.
To start with the JMX remote access on a specific port number, pass this port number in as the value
for the -jmxport argument:
cd %SERVER_HOME% bin\startup.sh -jmxport 9009
This will start the SpringSource dm Server with JMX enabled for remote attach on port
9009.
To start the JMX remote access using a custom username and password edit the file located at
%SERVER_HOME%\control\jmx-users.properties. If you wish to use a different file
for authentication, pass this filename in as the value for the -jmxusers
argument:
cd %SERVER_HOME% bin\startup.sh -jmxusers custom-jmx-users.properties
This will start the SpringSource dm Server with JMX enabled for remote attach using authentication
credentials from custom-jmx-users.properties.
To start the JMX remote access using a custom SSL certificate edit the file located at
%SERVER_HOME%\control\keystore. If you wish to use a different keystore, pass
this filename in as the value for the -keystore argument and the keystore
password in as the value for the -keystorePassword argument:
cd %SERVER_HOME% bin\startup.sh -keystore customKeystore -keystorePassword customeKeystorePassword
This will start the SpringSource dm Server with JMX enabled for remote attach using an SSL certificate from
customKeystore with a password of customKeystorePassword.
The -configDir option can be used to specify a config directory rather than using the
default SERVER_HOME/config directory. This option allows the same SpringSource dm Server
installation to be used to run multiple instances. Simply create a config directory for each
instance, specifying unique port numbers, logging and tracing directories, etc. and specify that directory
when starting SpringSource dm Server.
Note that if the path specified with -configDir is relative it will be interpreted
as being relative to the root of the SpringSource dm Server installation.
cd $SERVER_HOME bin/startup.sh -configDir /config/node1
To stop a running instance of SpringSource dm Server, run
shutdown.sh from a new console prompt:
cd $SERVER_HOME bin/shutdown.sh
To stop a running instance of SpringSource dm Server immediately, bypassing normal shutdown
processing, run shutdown.sh from a new console prompt with
the -immediate option:
cd $SERVER_HOME bin/shutdown.sh -immediate
To stop a running instance of SpringSource dm Server, run
shutdown.bat:
cd %SERVER_HOME% bin\shutdown.bat
To stop a running instance of SpringSource dm Server immediately, bypassing normal shutdown
processing, run shutdown.bat with the -immediate option:
cd %SERVER_HOME% bin\shutdown.bat -immediate
To use the SpringSource Admin Console, you must start the SpringSource dm Server and then enter the following address in your browser of choice.
http://localhost:8080/admin
Replace 'localhost' with the hostname of the system on which the SpringSource dm Server is running if it is not your local machine. The Admin Console uses basic security, therefore you will need to enter the default id and password.
ID: admin Password: springsource
To change the id and password for the Admin Console, go to the following file, which is in the standard Tomcat format. Change the 'username' and 'password' values. The Admin Console runs against the admin role, therefore this cannot be changed.
$SERVER_HOME/config/servlet/tomcat-users.xml
The main page displays several sections. The main section is a list of the installed artifacts and the modules that comprise them. The standard install of the dm Server will have two artifacts - the Admin Console itself and a splash screen application. As these artifacts both contain web components, a link is provided to view them in your browser.
The other fields in the table give the 'Name' of the artifact, which will be the file name if none is supplied. The 'Origin' describes how the artifact was deployed. The possible values are 'Hot Deployed' as described above, 'Admin Console' if deployed through the console and 'Programmatic' if deployed programmatically, that is, through the integrated artifact deployer in the SpringSource dm Server Tools. The version will be '0' if none is supplied from the artifact. The 'Date' shows when the artifact was last deployed to the dm Server.
The Admin Console allows you to upload a file, which will be deployed automatically to the SpringSource dm Server. Once the artifact is deployed it will appear in the list of artifacts in the Admin Console. Please note that the GUI for uploading varies according to the browser and operating system used.
When clicked, the 'Upload' button reloads the page. This may take a few seconds while the file is uploaded and deployed. The list of artifacts will display the newly deployed artifacts. If there have been any problems, you can check the status message at the top of the page. This message will otherwise report 'Application deployed'.
For more information on how to work with artifacts see the chapter entitled Chapter 6, Working with Applications.
At the bottom of the main page is a section giving details of the dm Server you have accessed. This may be useful for verifying that you have accessed the correct instance.
In SpringSource dm Server, all third-party dependencies needed by your applications, such as Spring Framework and Hibernate, are stored in the provisioning repository. All of these dependencies are stored as valid OSGi bundles in the provisioning repository. Dependencies that are not valid OSGi bundles are not supported.
When an application is installed, if it has a dependency that cannot be satisfied from the bundles that have already been installed,
the SpringSource dm Server will search the repository for a bundle that can satisfy that dependency. Dependencies between applications
and third-party libraries are typically expressed using Import-Package or Import-Library
(see Programmer's Guide).
Some third-party dependencies consist of multiple bundles but are logically one unit. To support this, the SpringSource dm Server introduces the concept of a library. A library is a collection of related bundles that can be referenced as a whole. More details on the creation and usage of libraries can be found in the Programmer's Guide.
Making a third-party dependency available to your application is simply a matter of adding its bundle or library to the appropriate location in the provisioning repository.
By default, the provisioning repository is located at $SERVER_HOME/repository and consists of three main directories:
bundles, libraries and installed.
The bundles directory contains all the bundles available in the repository. The libraries directory contains
all the library definitions. Note that libraries reference bundles that are installed elsewhere in the repository, e.g. by default under the
bundles directory. The installed directory is used by the SpringSource dm Server at runtime, and should not contain
used bundles or libraries.
The bundles directory is further subdivided into three directories: ext, subsystems and
usr.
The ext and usr directories are intended to contain third-party bundles, with ext containing
bundles supplied with the SpringSource dm Server and usr containing bundles installed by the end user. The subsystems
directory is for internal use only.
The libraries directory is similarly organized, with an ext and usr directory. As with bundles,
new libraries should be installed into libraries/usr.
To install a bundle into the bundle repository, copy it into the $SERVER_HOME/repository/bundles/usr directory. Bundles must
have unique names so it is considered best practice to include the version number in the file name, allowing for multiple versions of the
bundle to be installed.
In some cases the SpringSource dm Server manages to automatically detect changes in its provisioning repository at runtime, thereby avoiding the need to restart the dm Server.
Of specific relevance during development is picking up changes to an application's direct dependencies during deployment of the application. For example, if you deploy an application and receive a message that a dependency is missing, you can simply add the dependency to the repository and then redeploy the application. The redeploy will cause the new dependency to be picked up, allowing progress to be made without restarting the dm Server. For other changes such as addition of indirect dependencies, the SpringSource dm Server must be restarted to pick up any changes to the provisioning repository.
To install a library, copy its definition into the $SERVER_HOME/repository/libraries/usr directory. Ensure that all referenced
bundles have been installed as well.
The SpringSource Enterprise Bundle Repository is located here.
You can find bundles in the repository using a number of options. You use the 'Search' facility by typing in a keyword. The matching criteria returned can be explored by name, symbolic name, class, package or resource.
There is also the option of clicking on 'Browse by Bundle'. This gives an alphabetical list of bundles. You can select the desired bundle to see details and find the download link. Finally, you can also choose to 'Browse by Library', which allows you to browse the alphabetical list of libraries in the repository.
Details of how to configure a SpringSource dm Server installation's provisioning repository can be found in the Configuration chapter.
Log files are low-volume logs of important events in SpringSource dm Server. Each message written to a log file is accompanied by a 9-digit log code enclosed in angle brackets. An example is shown below:
[2008-03-08 17:25:28.007] server-dm-13 <SPSC0000I> - Creating ServletContainer on port 8080
For a breakdown of the code meanings, see the Section 9.1, “Log Codes”.
By default, log files are stored in
$SERVER_HOME/serviceability/logs.
The SpringSource dm Server's trace support serve two main purposes:
- It provides global trace files that capture high-volume information regarding the SpringSource dm Server's internal events. The files are intended for use by support personnel to diagnose runtime problems.
-
It provides application trace files that contain application-generated output. This includes output generated using popular logging and
tracing APIs, as well as output generated by calls to
System.outandSystem.err. These files are intended for use by application developers and system administrators.
Entries in trace files are of the form <timestamp> <thread-name> <source> <level> <entry-text>. For example:
[2008-05-15 09:09:46.940] server-dm-2 org.apache.coyote.http11.Http11Protocol I Initializing Coyote HTTP/1.1 on http-48080
By default, trace files are stored in $SERVER_HOME/serviceability/trace.
SpringSource dm Server provides advanced support for capturing and tracing application-generated output. It automatically partitions trace on a
per-application basis and will also capture any System.out and System.err output and direct it to the generating application's
trace.log file.
SpringSource dm Server uses SLF4J-based implementations of both Commons Logging and Log4J to route output generated by applications
using those APIs to its trace files. In addition to appending such output to the global trace.log it will also
append it to an application-specific trace file.
SpringSource dm Server writes application-specific trace to a file in a subdirectory of the configured trace directory. As described
above this directory is, by default, SERVER_HOME/serviceability/trace. The subdirectory's name is of
the form <application-name>-<version>. So, for example, an application named com.myapp at
version 1 will write its trace to a file in SERVER_HOME/serviceability/trace/com.myapp-1/.
The levels used to filter per-application trace can be configured by using a header in the application's manifest specifying a comma-separated list of package and class names. For example:
Application-TraceLevels: *=info,com.myapp.*=verbose
This example manifest header will enable info level tracing for everything other than classes in the com.myapp package for which verbose level tracing will be enabled.
SpringSource dm Server captures, and traces, all output generated via System.out and System.err.
This means that such output will be written to both the global trace.log file and to the trace file specific
to the application that generated the output. The trace entries for System.out and System.err
output are of the form:
[2008-05-16 09:28:45.874] server-tomcat-thread-1 System.out I Hello world! [2008-05-16 09:28:45.874] server-tomcat-thread-1 System.err E Hello world!
As you can see the third column indicates where the output came from, i.e. System.out or System.err
and, as indicated by the fourth column, System.out is traced at the Info level, and System.err is
traced at the error level.
A service dump is triggered when one of the following events occurs:
A failure is detected in the SpringSource dm Server code
A thread deadlock is detected
A service dump contains a snapshot of all the important state from the running SpringSource dm Server instance. This snapshot is not intended for end user consumption but is useful for service personnel.
By default, service dumps are created in
$SERVER_HOME/serviceability/dump.
Artifacts can be deployed into the SpringSource dm Server using either the hot-deploy directory on the file system or by using the admin console.
To hot deploy an artifact, copy it into the
$SERVER_HOME/pickup
directory:
cp myapp.par $SERVER_HOME/pickup
When the artifact is deployed, a message similar to the following will appear in the log (time stamps omitted):
[2008-03-08 17:00:00.000] <SPDE0010I> - Deployment of 'myapp.par' version '0' completed.
If there is a problem with the deployment the console and log will both show an error message to help with troubleshooting.
To use the SpringSource Admin Console please see the chapter entitled Chapter 3, The Web based Administration Console.
The Admin Console allows you to upload a file, which will be deployed automatically, from your local system to the SpringSource dm Server. Once the artifact is deployed it will appear in the list of artifacts in the Admin Console. Using the upload panel shown below, you can select a file. Please note that the GUI for uploading varies according to the browser and operating system used.
When clicked, the 'Upload' button reloads the page. This may take a few seconds while the file is transmitted and deployed. The list of artifacts will display the newly deployed artifact. If there have been any problems, you can check the status message at the top of the page. This message will otherwise report that 'Application deployed'.
The other fields in the table give the 'Name' of the artifact, which will be the file name if none is supplied. The 'Origin' describes how the artifact was deployed. The possible values are 'Hot Deployed' as described above, 'Admin Console' if deployed through the console and 'Programmatic' if deployed programmatically, that is, through the integrated artifact deployer in the SpringSource dm Server Tools. The version will be '0' if none is supplied. The 'Date' shows when the artifact was last deployed to the dm Server. Finally, the 'Type' tells you if it is an OSGi application or not.
When an artifact is deployed by either method it is copied to the 'work' directory of the SpringSource dm Server file structure. Several other activities take place, for example: it is registered with the SpringSource dm Server, any dependencies it has are checked to see if deployment can go ahead, and finally it is started. Because of this just dropping an artifact into the 'work' directory will not deploy the artifact.
When deploying bundles that have dependencies it is important that you deploy them in the correct order. The SpringSource dm Server will honor this ordering when redeploying artifacts on startup.
If you are using hot deployment, be sure to copy artifacts into the pickup
directory one-by-one. Copying the files in one group provides no guarantees of ordering.
Artifacts can be undeployed from the SpringSource dm Server using either the hot-deploy directory on the file system, or by using the admin console.
To hot-undeploy an artifact, remove the corresponding
artifact from the
$SERVER_HOME/pickup
directory:
cd $SERVER_HOME/pickup rm myapp.par
When the artifact is undeployed, a message similar to the following will appear in the log:
[2008-03-08 17:00:05.000] <SPDE0012I> - Undeployment of 'myapp.war' version '0' completed.
When undeploying an artifact you can only undeploy a whole artifact. You cannot undeploy the separate modules/bundles of an application. Each artifact that can be undeployed has a link to the right of the list of artifacts. Once you click the undeploy link, the page will be reloaded with that artifact removed from the list.
The only artifact that cannot be undeployed from the Admin Console is the Admin Console itself. This can be undeployed manually from the hot deploy directory if needed.
If any problems have occurred the status message at the top of the page will report the error.
The serviceability subsystem of the SpringSource dm Server
is configured in the server.config file found
in the config directory of the dm Server
installation. Any relative paths in this file are relative to the root
of the installation.
The tracing component provides two configurable settings. For example:
"trace": { "directory": "serviceability/trace", "levels": { "*" : "info", "com.foo.*" : "verbose", "com.foo.TheClass" : "debug", "com.bar.AnotherClass" : "verbose" } }
In this example, the tracing component will write its output to the
SERVER_HOME/serviceability/trace
directory. The trace component provides five different levels at which trace can be output. These are, in descending
order of severity: error, warn, info, debug, and verbose. The configured levels govern what trace is output and what
trace is filtered out. Trace levels can be configured for individual classes or for entire packages and package trees.
In this example, every class has info level tracing enabled except for those in the com.foo package and its subpackages
which have verbose level tracing enabled, com.foo.TheClass which has debug level tracing enabled, and
com.bar.AnotherClass which has verbose level tracing enabled. When determining what level of trace is enabled for any
given class, the tracing component will use the level of the most specific match, e.g. com.foo.TheClass is a more specific
match than com.foo.*. Any classes that are not matched by any of the configured levels will have trace disabled.
The logging component provides a single configurable setting. For example:
"logs": { "directory": "serviceability/logs" }
In this example the logging component will write its output to the
SERVER_HOME/serviceability/logs directory.
The SpringSource dm Server
embeds an OSGi-enhanced version of the Tomcat Servlet Container
in order to provide support for deploying Java EE WARs and Web Modules.
The embedded Servlet container can be configured via the servletContainer.config file
located in the SERVER_HOME/config directory. The following listing displays
the default configuration distributed with the dm Server.
{
"servletContainer": {
"version": 1.0,
/* configDir should be either an absolute path or relative to the SERVER_HOME directory */
"configDir": "config/servlet",
"hostName": "localhost",
"jvmRoute": "jvm1",
"listeners": [
{
/*
* APR library loader.
* Documentation at http://tomcat.apache.org/tomcat-6.0-doc/apr.html
*/
"enabled": true,
"className": "org.apache.catalina.core.AprLifecycleListener",
"SSLEngine": "on"
},
{
/*
* Initialize Jasper prior to loading webapps.
* Documentation at http://tomcat.apache.org/tomcat-6.0-doc/jasper-howto.html
*/
"enabled": true,
"className": "org.apache.catalina.core.JasperListener"
}
],
"connectors": [
{
/*
* HTTP Connector.
* Documentation at http://tomcat.apache.org/tomcat-6.0-doc/config/http.html
*/
"enabled": true,
"port": 8080,
"protocol": "HTTP/1.1",
"connectionTimeout": 20000,
"maxThreads": 150,
"emptySessionPath": false,
"redirectPort": 8443
},
{
/*
* HTTPS Connector.
* Documentation at http://tomcat.apache.org/tomcat-6.0-doc/config/http.html
* and http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html
*/
"enabled": true,
"port": 8443,
"protocol": "HTTP/1.1",
"scheme": "https",
"connectionTimeout": 20000,
"maxThreads": 150,
"emptySessionPath": false,
"clientAuth": false,
/* keystoreFile should be a path relative to the configured value for servletContainer:configDir */
"keystoreFile": "../control/keystore",
"keystorePass": "changeit",
"secure": true,
"SSLEnabled": true,
"sslProtocol": "TLS"
},
{
/*
* AJP Connector.
* Documentation at http://tomcat.apache.org/tomcat-6.0-doc/config/ajp.html
*/
"enabled": true,
"port": 8009,
"protocol": "AJP/1.3",
"connectionTimeout": 20000,
"redirectPort": 8443
}
],
"logs": {
"perApplicationLogging": true,
/* accessLogDir should be either an absolute path or relative to the SERVER_HOME directory */
"accessLogDir": "serviceability/logs/access",
"accessLogFormat": "long"
},
"threadPool": {
"minSize": 25,
"maxSize": 200,
"keepAlivePeriod": 60000
}
/*
* The next section of this file is configuration for Tomcat clustering. By default this is disabled.
*/
/*,
"cluster": {
"className": "org.apache.catalina.ha.tcp.SimpleTcpCluster",
"channelSendOptions": 8,
"heartbeatBackgroundEnabled": false,
"manager": {
"className": "org.apache.catalina.ha.session.DeltaManager",
"expireSessionsOnShutdown": false,
"notifyListenersOnReplication": true
},
"channel": {
"className": "org.apache.catalina.tribes.group.GroupChannel",
"membership": {
"className": "org.apache.catalina.tribes.membership.McastService",
"address": "228.0.0.4",
"port": 45564,
"frequency": 500,
"dropTime": 3000
},
"receiver": {
"className": "org.apache.catalina.tribes.transport.nio.NioReceiver",
"address": "auto",
"port": 4000,
"autoBind": 100,
"selectorTimeout": 5000,
"maxThreads": 6
},
"sender": {
"className": "org.apache.catalina.tribes.transport.ReplicationTransmitter",
"transport": {
"className": "org.apache.catalina.tribes.transport.nio.PooledParallelSender"
}
},
"interceptors": [
{
"className": "org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"
},
{
"className": "org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"
}
]
},
"valves": [
{
"className": "org.apache.catalina.ha.tcp.ReplicationValve",
"filter": ""
},
{
"className": "org.apache.catalina.ha.session.JvmRouteBinderValve"
}
],
"deployer": {
"className": "org.apache.catalina.ha.deploy.FarmWarDeployer",
"tempDir": "/tmp/war-temp/",
"deployDir": "/tmp/war-deploy/",
"watchDir": "/tmp/war-listen/",
"watchEnabled": false
},
"clusterListeners": [
{
"className": "org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener"
},
{
"className": "org.apache.catalina.ha.session.ClusterSessionListener"
}
]
}*/
}
}![[Tip]](images/tip.gif) | Disabling configuration elements |
|---|---|
Listener and Connector configuration elements can be disabled by
setting the |
The following table lists all top-level options for configuring the embedded Servlet container.
| Relative paths |
|---|---|
If the configured path to a directory or file does not represent an absolute path,
it will typically be interpreted as a path relative to the
|
Table 7.1. Servlet Container Configuration Values
| Entry | Description | Supported Values | Default Value |
|---|---|---|---|
version |
The configuration schema version. | 1.0 | N/A |
configDir |
The path to the Servlet container's config directory. This directory serves as the central location for implementation-specific configuration files. The config directory also serves as the base directory for any relative-path-based configuration resources for the Servlet container.
If the configured value does not represent an absolute path,
it will be interpreted as a directory relative to the
| config/servlet | N/A |
hostName |
The host name to use for the Servlet container's default host. | Any valid hostname for the system on which the dm Server is running. | localhost |
jvmRoute | A unique identifier for the Servlet container instance, used to configure a JVM route for load balancing. | A unique text value, typically purely alpha-numeric. | jvm1 |
listeners |
A list of LifecycleListener configuration elements. Consult the official
Tomcat documentation
for further information on available listeners.
| N/A | N/A |
connectors |
A list of Connector configuration elements.
See the connector configuration
section for details.
| N/A | N/A |
logs - perApplicationLogging |
Boolean flag for enabling access logging on a per-application basis. | true or false | true |
logs - accessLogDir |
The path to the access log directory where HTTP requests to the Servlet container will be logged.
If the configured value does not represent an absolute path, it will be
interpreted as a directory relative to the
| (see description) | serviceability/logs/access |
logs - accessLogFormat |
The style to use for formatting the access log. | short or long | long |
threadPool - minSize |
The minimum number of threads to be kept in the Servlet Container's threadpool. | Any positive int | 25 |
threadPool - maxSize |
The maximum number of threads to be kept in the Servlet Container's threadpool. | Any positive int | 200 |
threadPool - keepAlivePeriod |
The period of time, in milliseconds, that an idle thread will be kept alive in the Servlet Container's threadpool. | Any positive int | 60000 |
The SpringSource dm Server supports JSON-based configuration of any connector
supported by Apache Tomcat. See the default configuration above for syntax examples, and
for further details on the configuration properties supported for various
Connector implementations, consult the official
Tomcat HTTP Connector
documentation.
| Configuring SSL for Tomcat |
|---|---|
The SpringSource dm Server distribution includes a preconfigured |
The SpringSource dm Server supports JSON-based configuration of the load balancing supported by tomcat. See the default configuration for syntax examples.
The SpringSource dm Server supports JSON-based configuration of the clustering supported by Apache Tomcat. See the default configuration
(which is disabled) for syntax examples, and for further details on the configuration properties support for
Cluster implementations, consult the official
Tomcat Clustering/Session Replication HOW-TO
documentation.
In addition to the aforementioned configuration options, various parts of the
embedded Tomcat Servlet container can be configured via the following files
located in the Servlet container's configuration directory (see
configDir above). The syntax and usage of each file
comply with that of a standard Tomcat installation.
context.xml: XML based configuration file which will be loaded for each web application
Contextdeployed on the dm Server.tomcat-users.xml: XML based configuration file used to manage users, passwords, and roles for an in-memory security realm. This file is used by the dm Server to configure a
MemoryRealmfor the embedded Tomcat Servlet container.web.xml: The default
web.xmldeployment descriptor used for all web applications deployed on the dm Server. As each web application is deployed, this file is processed, followed by the/WEB-INF/web.xmldeployment descriptor packaged with the web application itself, if present.
To change the telnet console's configuration, find the
server.config
file in the
SERVER_HOME/config
directory and edit the 'enabled' and 'port' entries in the 'osgiConsole' section. By default the console is enabled
and listens on port 2401:
"osgiConsole" : { "enabled" : true, "port" : 2401 }
To change the deployment timeout, edit the
deployer.config
file in the
SERVER_HOME/config
directory. The following listing displays
the default configuration distributed with the dm Server.
{
"deployer" : {
"version" : 1.0,
"deploymentTimeoutSeconds" : 30
}
}
The locations which the SpringSource dm Server will include in its provisioning repository can be configured by editing the server.config file
in the SERVER_HOME/config directory. The default locations are implied, rather than being explicitly defined in the configuration file.
The default configuration is equivalent to the following node in the configuration file:
"provisioning" : { "searchPaths": [ "repository/bundles/subsystems/{name}/{bundle}.jar", "repository/bundles/ext/{bundle}", "repository/bundles/usr/{bundle}", "repository/libraries/ext/{library}", "repository/libraries/usr/{library}" ] }
This default configuration has five paths, each of which will be searched when locating entries for inclusion in the provisioning repository. The
repository/bundles/subsystems/{name}/{bundle}.jar, repository/bundles/ext/{bundle}, and
repository/libraries/ext/{library} are all required by a default installation and should always be included in a custom
configuration.
Each search path defines a location that is included in that SpringSource dm Server's provisioning repository and will therefore be searched when looking for a
library or bundle dependency. If a search path is relative its location is taken as being relative to the root of the installation, i.e. the
SERVER_HOMEdirectory.
Search paths provide support for wildcards. In the entries above, the path segments surrounded by curly braces, e.g. {bundle} and
{library}, are wildcards entries for a directory with any name. Allowing wildcards to be named in this way is intended to improve
the readability of search path configuration.
In addition to supporting the above-described form of wildcards, SpringSource dm Server also supports Ant-style paths, i.e. * and
** can be used to represent any directory and any series of directories respectively. For example,
repository/bundles/usr/{bundle} and repository/bundles/usr/* are directly equivalent.
A common usage of the ** wildcard is to allow dependencies stored in a directory structure of varying depth, e.g. a local
Maven repository, to be provisioned by the SpringSource dm Server.
In addition to support for wildcards, system properties can also be used within a search path. System properties are referenced as
${system.property.name}, e.g. a search path of ${user.home}/repository/bundles will reference the
repository/bundles directory in the user's home directory.
The following examples provide sample configuration that could be used for some common use cases.
"provisioning" : { "searchPaths": [ "repository/bundles/subsystems/{name}/{bundle}.jar", "repository/bundles/ext/{bundle}", "${user.home}/.ivy2/cache/{org}/{name}/{version}/{bundle}.jar", "repository/libraries/ext/{library}", "repository/libraries/usr/{library}" ] }
"provisioning" : { "searchPaths": [ "repository/bundles/subsystems/{name}/{bundle}.jar", "repository/bundles/ext/{bundle}", "${user.home}/.maven/repository/**/{bundle}.jar", "repository/libraries/ext/{library}", "repository/libraries/usr/{library}" ] }
The dm Server will fail to start correctly if it is prevented from
connecting to needed ports by the firewall. Typically this manifests
as error SPPM0003E . Configuring the firewall to
allow the dm Server process to bind to the necessary ports will prevent
this error from occurring.
As a result of Sun Java bug
4957990,
the SpringSource dm Server may consume more PermGen space than expected when running with the
server HotSpot compiler. This problem may be resolved by configuring the
JAVA_OPTS environment variable to specify an increased
MaxPermSize, for example -XX:MaxPermSize=128M.
Each log message is accompanied by a log code which is useful in understanding the current state
of the dm Server. Log codes are of the form: 'SPXY1234L', where
SP stands for Spring Server,
XY stands for the subsystem code, 1234 represents the
error number, and L conveys the level of severity of the event being logged.
Below is the list of subsystem codes and their corresponding subsystems:
CC - ConcurrentCN - ControlCO - ConfigDE - DeployerFF - FFDCKB - BootstrapKE - KernelOP - OSGiPM - ProfileSC - ServletWE - Web
The error numbers start from 0000 and typically increase by 1.
There is no upper limit for error numbers.
E - ErrorW - WarnI - Info
Error denotes that there are problems in the dm Server, such as incorrect
behaviour of the system. This is the most serious of the log events.
Warn denotes that errors exist, but they are not critical and may be overlooked.
Info provides information about events in the system that may be useful in diagnosing
warnings and errors. Such events are not severe.
In each instance where they appear, %s represents a variable which will be substituted with
a string, and %d represents a variable which will be substituted with a number.
Table 9.1. Concurrent Log Codes
| Code | Message |
|---|---|
CC0000E |
|
Table 9.2. Control Log Codes
| Code | Message | ||||
|---|---|---|---|---|---|
CN0000E |
| ||||
CN0001E |
| ||||
CN0002E |
| ||||
CN0003E |
| ||||
CN0004I |
|
Table 9.3. Config Log Codes
| Code | Message | ||||
|---|---|---|---|---|---|
CO0000E |
| ||||
CO0001E |
| ||||
CO0002E |
| ||||
CO0003E |
| ||||
CO0004E |
| ||||
CO0005E |
| ||||
CO0006E |
| ||||
CO0007E |
| ||||
CO0008E |
| ||||
CO0009E |
| ||||
CO0010W |
| ||||
CO0011E |
| ||||
CO0012W |
| ||||
CO1000E |
| ||||
CO1001E |
| ||||
CO1002E |
| ||||
CO1003E |
| ||||
CO1004E |
| ||||
CO1005E |
| ||||
CO1006E |
| ||||
CO1007E |
| ||||
CO1008E |
| ||||
CO1009E |
| ||||
CO1010E |
| ||||
CO1011E |
| ||||
CO1100E |
|
Table 9.4. Deployer Log Codes
| Code | Message | ||||
|---|---|---|---|---|---|
DE0000E |
| ||||
DE0002E |
| ||||
DE0003E |
| ||||
DE0004E |
| ||||
DE0005E |
| ||||
DE0006E |
| ||||
DE0007E |
| ||||
DE0008E |
| ||||
DE0009E |
| ||||
DE0010I |
| ||||
DE0011E |
| ||||
DE0012I |
| ||||
DE0013E |
| ||||
DE0014I |
| ||||
DE0015E |
| ||||
DE0016E |
| ||||
DE0017W |
| ||||
DE0018E |
| ||||
DE0019I |
| ||||
DE0020E |
| ||||
DE0021E |
| ||||
DE0022E |
| ||||
DE0023E |
| ||||
DE0024E |
| ||||
DE0025E |
| ||||
DE0026E |
| ||||
DE0027E |
| ||||
DE0028E |
| ||||
DE0029E |
| ||||
DE0030E |
| ||||
DE0031E |
| ||||
DE0032E |
| ||||
DE0033E |
| ||||
DE0034E |
| ||||
DE0035E |
| ||||
DE0036E |
| ||||
DE0037E |
| ||||
DE0038E |
| ||||
DE0039E |
| ||||
DE0040E |
| ||||
DE0041E |
| ||||
DE0042E |
| ||||
DE0043E |
| ||||
DE0044E |
| ||||
DE0045E |
| ||||
DE0046E |
| ||||
DE0047E |
| ||||
DE1000E |
| ||||
DE1001E |
| ||||
DE1002E |
| ||||
DE1003E |
| ||||
DE1004E |
| ||||
DE1005E |
| ||||
DE1006E |
| ||||
DE1007E |
| ||||
DE1008E |
| ||||
DE1009E |
| ||||
DE1025W |
| ||||
DE1026W |
| ||||
DE1027W |
| ||||
DE1028W |
| ||||
DE1029W |
| ||||
DE1030W |
| ||||
DE1031W |
| ||||
DE1032W |
| ||||
DE1033W |
| ||||
DE1034W |
| ||||
DE1050I |
| ||||
DE1051I |
| ||||
DE1052I |
| ||||
DE1053I |
| ||||
DE1054I |
| ||||
DE1055I |
| ||||
DE1056I |
| ||||
DE1057I |
| ||||
DE1058I |
| ||||
DE1059I |
| ||||
DE1085E |
|
Table 9.5. FFDC Log Codes
| Code | Message | ||||
|---|---|---|---|---|---|
FF0000E |
| ||||
FF0001I |
| ||||
FF0002I |
| ||||
FF0003E |
|
Table 9.7. Kernel Log Codes
| Code | Message | ||||
|---|---|---|---|---|---|
KE0000I |
| ||||
KE0001I |
| ||||
KE0051E |
|
Table 9.8. OSGi Log Codes
| Code | Message | ||||
|---|---|---|---|---|---|
OP0001W |
| ||||
OP0002W |
| ||||
OP0003W |
| ||||
OP0004W |
|
Table 9.9. Profile Log Codes
| Code | Message | ||||
|---|---|---|---|---|---|
PM0000I |
| ||||
PM0001I |
| ||||
PM0002I |
| ||||
PM0003E |
| ||||
PM0004W |
|
Table 9.10. Servlet Log Codes
| Code | Message | ||||
|---|---|---|---|---|---|
SC0000I |
| ||||
SC0001I |
| ||||
SC0002I |
| ||||
SC0003E |
| ||||
SC0004E |
| ||||
SC1000I |
| ||||
SC1001I |
| ||||
SC1002I |
| ||||
SC1003E |
| ||||
SC1004E |
| ||||
SC2000E |
|
Table 9.11. Web Log Codes
| Code | Message | ||||
|---|---|---|---|---|---|
WE1000E |
| ||||
WE1001E |
|