SpringSource dm Server™ User Guide

The SpringSource dm Server requires Java SE 5 or later to be installed. Java is available from Sun and elsewhere.

To start SpringSource dm Server run the startup.sh (Linux) or startup.bat (Windows) script. For both platforms, the script is located in the SERVER_HOME/bin directory.

prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh
	

[2009-03-30 12:12:12.111] Deployer Recovery <SPPM0002I> Server open for business with profile 'web'.

prompt> cd %SERVER_HOME%
prompt> bin\startup.bat
	

[2009-03-30 12:12:12.111] Deployer Recovery <SPPM0002I> Server open for business with profile 'web'.

When you start dm Server in clean mode, the startup script removes the SERVER_HOME/work directory (and hence all running applications) as well as all trace, log and dump files. It leaves the SERVER_HOME/repository and SERVER_HOME/pickup directories untouched, which means that any applications previously hot deployed will be automatically reinstalled.

prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -clean
	

prompt> cd %SERVER_HOME%
prompt> bin\startup.bat -clean
	

Use the -configDir option to specify an alternate config directory, different from the default SERVER_HOME/config directory. This option allows you to use the same SpringSource dm Server installation to run multiple instances of dm Server . Simply create a config directory for each instance, specify unique port numbers, logging and tracing directories, and so on. and then specify that directory when starting SpringSource dm Server.

If you specify a relative path for the -configDir parameter, the startup script interprets the path as relative to the root of the SpringSource dm Server installation, and not relative to the directory from which you execute the startup script.

prompt$ cd $SERVER_HOME
prompt$ bin/startup.sh -configDir /config/node1
			

prompt> cd %SERVER_HOME%
prompt> bin\startup.bat -configDir c:\config\node1
			

To use the SpringSource Admin Console, start the SpringSource dm Server and then enter the following URL in your browser of choice.

http://localhost:8080/admin

Replace localhost with the hostname of the computer on which the SpringSource dm Server is running if it is not the same as the computer on which you are running your browser. The Admin Console uses basic authentication, therefore you will need to enter the default administration ID and password.

ID: admin 
Password: springsource
		

To change the ID and password for the Admin Console, update the SERVER_HOME/config/servlet/tomcat-users.xml file, which is in the standard Tomcat users-file format. Change the values of the username and password attributes of the <user> element with the admin role. For example, if you want change the administration username to hamlet with password tobeornottobe change the file as follows:

<user username="hamlet" password="tobeornottobe" roles="admin">

The Admin Console runs against the admin role, therefore this cannot be changed.

The main Admin Console page displays several sections. The Deployed Applications section shows a list of all the deployed artifacts and the modules that comprise them. When you first install dm Server, there will be two artifacts deployed: the Admin Console itself and a splash screen application. As these artifacts both contain Web components, the Admin Console provides a link so you can quickly view them in your browser. The Admin Console provides a similar link for all deployed artifacts that contain Web components.

The other fields in the table give the 'Name' of the artifact, which is the name of the actual file if no specific name is supplied. The 'Origin' describes how the artifact was deployed. The possible values are Hot Deployed if the artifact was dropped in the pickup directory, Admin Console if deployed using the console and Programmatic if deployed programmatically, that is, through the integrated artifact deployer in the SpringSource dm Server Tools. The version is 0 if no specific version is supplied by the artifact. The 'Date' column shows when the artifact was last deployed to dm Server.

In the Deploy an Application section, you can upload a file that will be deployed automatically to the SpringSource dm Server. Once the artifact is deployed it will appear in the Deployed Applications table. You can use the Browse button to browse your local computer for the file. Note that the specific GUI for uploading varies according to your browser and platform.

When clicked, the 'Upload' button reloads the page. This may take a few seconds while the file is uploaded and deployed. If any problems occurred, the Admin Console outputs a status message at the top of the page. If the file deployed with no problems, the messages says Application deployed.

For more information on how to work with artifacts see Chapter 6, Working with Applications.

At the bottom of the main page, the Information section provides details of the dm Server you have accessed. This is useful for verifying that you have accessed the correct dm Server instance. The Server Properties table lists basic properties of the dm Server instance, such as the version of the embedded Tomcat server and the operation system on which the dm Server instance is running. The Serviceability Destinations table lists the locations of the dump, log, and trace files.

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:

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.

Application-TraceLevels: *=info,com.myapp.*=verbose
                

[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!
			

A service dump is triggered when one of the following events occurs:

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.

You can deploy artifacts to SpringSource dm Server using either the hot-deploy directory on the file system or by using the Admin Console.

prompt$ cp myapp.par $SERVER_HOME/pickup

[2009-03-08 17:00:00.000] fs-watcher   <SPDE0010I> - Deployment of 'myapp.par' version '0' completed.

You can undeploy artifacts from SpringSource dm Server using either the hot-deploy directory on the file system, or by using the Admin Console.

prompt$ cd $SERVER_HOME/pickup
prompt$ rm myapp.par

[2009-03-08 17:00:05.000] fs-watcher     <SPDE0012I> - Undeployment of 'myapp.war' version '0' completed.

The serviceability subsystem of the SpringSource dm Server is configured in the serviceability.config file found in the SERVER_HOME/config directory of the dm Server installation. Any relative paths in this file are relative to the root of the installation, SERVER_HOME.

"trace": {
     "global" : {
         "directory": "serviceability/trace",
         "levels": {
             "*" : "warn"
             "com.foo.*" : "verbose",
             "com.foo.TheClass" : "debug",
             "com.bar.AnotherClass" : "verbose"
         }
     },
     "trickle": {
         "windowSize": 10000,
         "levels": {
             "*" : "debug",
             "org.apache.commons.digester.*" : "warn"
          }
     }
}

"logs": {
    "directory": "serviceability/logs"
}

"dump": {
    "directory": "serviceability/dump"
},
"heapDump": {
    "enabled": false
} 

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",
    "realm" : {
        "className" : "org.apache.catalina.realm.MemoryRealm",
        "pathname" : "tomcat-users.xml"
    },
    "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": "../../config/management/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": {
        /* accessLogDir should be either an absolute path or relative to the SERVER_HOME directory */
        "accessLogDir": "serviceability/logs/access",
        "defaultAccessLogFormat": "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\"",
        "globalAccessLogging": true,
        "perApplicationAccessLogging": true
    },
    "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"
            }
        ]
    }*/
}
}

	Disabling configuration elements
	Listener and Connector configuration elements can be disabled by setting the enabled flag to false. This allows you to disable but still retain the configuration for such elements without the need to delete the configuration.

Servlet Container Configuration

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 SERVER_HOME directory.

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 SERVER_HOME directory.	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 - 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 SERVER_HOME directory.	(see description)	serviceability/logs/access
logs - defaultAccessLogFormat	The style to use for formatting the access log.	Any legal Tomcat log format string	%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\"
logs - globalAccessLogging	Boolean flag for enabling the global access logging for web all applications on the server.	true or false	true
logs - perApplicationAccessLogging	Boolean flag for enabling access logging on a per-application basis. Once enabled applications will still need to opt into per-application access logging using the Web-AccessLog manifest header.	true or false	true
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

Connector Configuration

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 keystore file which contains a single self-signed SSL Certificate. The password for this keystore file is changeit. Please note that the provided keystore file is intended for testing purposes only. For detailed instructions on how to configure Tomcat's SSL support, consult the official Tomcat SSL Configuration HOW-TO.

You can configure the telnet console of Equinox by updating the osgi.config file in the $SERVER_HOME/config directory and editing the enabled and port entries of the osgiConsole component. By default the console is enabled and listens on port 2401:

"osgiConsole" : {
    "enabled" : true,
    "port" : 2401
}

You can configure two properties of deployment: the pickup directory into which you copy applications for hot-deployment and the deployment timeout. To change either of these properties, edit the deployer.config file in the $SERVER_HOME/config directory and change the value of the pickupDir or deploymentTimeoutSeconds options. The following listing displays the default configuration distributed with the dm Server.

{
    "deployer" : {
        "pickupDir" : "pickup",
        "version" : 1.0,
        "deploymentTimeoutSeconds" : 300
    }
}

As the default configuration shows, the default pickup directory is SERVER_HOME/pickup and the deployment timeout is 300 seconds. If you want to disable deployment timeout, set the option to 0.

The version option is for internal SpringSource dm Server use; do not change that value.

You configure the locations that SpringSource dm Server includes in its repository by editing the repository.config file in the $SERVER_HOME/config directory. This file inclues the following two components: repositories and respositoryChain.

The repository component specifies the actual directories, or searchpaths, for the different types of bundles or libraries that can live in the repository, such as sub-system bundles or user-defined libraries. Each of the searchpaths is given a name, such as bundles-subsystems or libraries-user and whether the searchpath is external or internal. The repositoryChain component specifies the order in which SpringSource dm Server searches the directories when it looks for dependencies. The repositoryChain component uses the names of the searthpaths as specified in the repositories component.

The default configuration is as follows:

"repositories" : {
   "bundles-subsystems" : {
        "type" : "external",
        "searchPattern" : "repository/bundles/subsystems/{subsystem}/{component}"
   },
   "bundles-ext" : {
         "type" : "external",
         "searchPattern" : "repository/bundles/ext/{bundle}"
   },
   "bundles-usr" : {
         "type" : "external",
         "searchPattern" : "repository/bundles/usr/{bundle}"
   },
   "libraries-ext" : {
         "type" : "external",
         "searchPattern" : "repository/libraries/ext/{library}"
   },
   "libraries-usr" : {
         "type" : "external",
         "searchPattern" : "repository/libraries/usr/{library}"
   }
},
"repositoryChain" : [
          "bundles-subsystems",
          "bundles-ext",
          "bundles-usr",
          "libraries-ext",
          "libraries-usr"
]

This default configuration shown above has five paths, each of which will be searched when locating entries for inclusion in the repository. The respositoryChain component shows the order in which the paths are searched.

SpringSource dm Server requires that you always include the bundles-subsystem, bundles-ext, and libraries-ext searchpaths, as shown above, in your repository configuration. You can configure the user-related paths as you wish.

"repositories" : {
   "bundles-subsystems" : {
        "type" : "external",
        "searchPattern" : "repository/bundles/subsystems/{subsystem}/{component}"
   },
   "bundles-ext" : {
         "type" : "external",
         "searchPattern" : "repository/bundles/ext/{bundle}"
   },
   "bundles-usr" : {
         "type" : "external",
         "searchPattern" : "${user.home}/.ivy2/cache/{org}/{name}/{version}/{bundle}.jar",
   },
   "libraries-ext" : {
         "type" : "external",
         "searchPattern" : "repository/libraries/ext/{library}"
   },
   "libraries-usr" : {
         "type" : "external",
         "searchPattern" : "repository/libraries/usr/{library}"
   }
}

"repositories" : {
   "bundles-subsystems" : {
        "type" : "external",
        "searchPattern" : "repository/bundles/subsystems/{subsystem}/{component}"
   },
   "bundles-ext" : {
         "type" : "external",
         "searchPattern" : "repository/bundles/ext/{bundle}"
   },
   "bundles-usr" : {
         "type" : "external",
         "searchPattern" : "${user.home}/.maven/repository/**/{bundle}.jar",
   },
   "libraries-ext" : {
         "type" : "external",
         "searchPattern" : "repository/libraries/ext/{library}"
   },
   "libraries-usr" : {
         "type" : "external",
         "searchPattern" : "repository/libraries/usr/{library}"
   }
}

SpringSource dm Server uses a work directory for internal work; by default this directory is SERVER_HOME/work. You can change this directory by updating the SERVER_HOME/config/io.config file and changing the value of the workDirectory option; as always, relative paths are relative to the root SERVER_HOME directory. The following listing show the default contents of the io.config file:

{
    "io" : {
        "workDirectory" : "work"
    }
}

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.

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.