AtomServer ConfigurationThis document describes specific details about configuring AtomServer; where to put configuration files, how to define your own Workspaces, etc.
For a further, detailed description of the actual protocol, either
- See the Atom Publishing Protocol Reference for further information about the elements of the feed itself. Note that we do not exhaustingly document this information ourselves, because we are using Atom entirely as dictated by the standard.
- See the AtomServer
Protocol
Basics document for general information about communicating with
the atomserver service.
Nor does this document explain the basics of XML, namespaces, syndicated feeds, and the GET, POST, PUT, and DELETE requests in HTTP, as well as HTTP's concept of a "resource." For more information about those things, see the Additional resources section of this document.
Contents
Atomserver's Classpath
For most uses of Atomserver, you won't need to write any code - a
bit of XML configuration is all you'll need. If you DO need to
extend Atomserver with your own custom code, it is very easy to do -
all of Atomserver's runtime context is wired together with Spring, and
injecting your own beans into the server's configuration is
straightforward.Whether you're adding your own classes, or just adding configuration files, Atomserver discovers your extensions as classes an resources on the java classpath. Because Atomserver is a java web application, the default classpath is comprised of the /WEB-INF/classes directory, and any .jar files in the /WEB-INF/lib directory inside the Atomserver .war file. The default classloader is extended to recognize several additional configuration locations, defined by two System Properties - atomserver.conf.dir, and atomserver.ops.conf.dir.
atomserver.conf.dir is the primary place for you to put additional application configuration. It acts very much like a web app's WEB-INF directory, in that it expects there to be a classes subdirectory, which is added to the classpath directly, and optionally a lib subdirectory, which contains .jar files - each of which will be added to the classpath.
One of the most common things you will do is add your own Spring Configuration files to Atomserver (see Extending Atomserver with Spring), particularly to configure your server's workspaces. An example of this would look like:
first, set up the following directory structure:
/homenext, put your Spring configuration file into the org.atomserver.spring.ext package:
`-/you
`-/atomserver-conf
|-/classes
| `-/org
| `-/atomserver
| `-/spring
| `-/ext
`-/lib
/homeif you need any additional java libraries, you can put the .jar files in the /lib directory:
`-/you
`-/atomserver-conf
|-/classes
| `-/org
| `-/atomserver
| `-/spring
| `-/ext
| `-/myAtomserverBeans.xml
`-/lib
/homefinally, you just need to make sure that the system property atomserver.conf.dir is set to your configuration directory (/home/you/atomserver-conf in this example.). If you are starting up with the standard atomserver.sh server, you can just set the environment variable ATOMSERVER_CONF_DIR and the script will take care of setting the System Property for you.
`-/you
`-/atomserver-conf
|-/classes
| `-/org
| `-/atomserver
| `-/spring
| `-/ext
| `-/myAtomserverBeans.xml
`-/lib
`-/myJar.jar
atomserver.ops.conf.dir is an additional configuration directory, designed to allow for configuration that is managed separately from the main configuration directory (say, to allow operations people to specify DB usernames/passwords for production machines, keeping that information hidden from the application developers.) The "ops" conf dir is injected directly into the classpath - there are no /classes or /lib subdirectories. This property is configured in atomserver.sh from the value of the ATOMSERVER_OPSCONF_DIR environment variable.
When using these configuration directories, the full search order for classes and resources is:
- the bootstrap classloader
- the default web application class loader (/WEB-INF/classes and .jar files in /WEB-INF/lib)
- the "ops" configuration dir {atomserver.ops.conf.dir}/
- the "normal" configuration dir ({atomserver.conf.dir}/classes and .jar files in {atomserver.conf.dir}/lib)
Atomserver Environment
The Atomserver environment defines a set of properties that configure the behavior of Atomserver. The environment is set via the System Property atomserver.env. When using the atomserver.sh startup script, you can specify the environment with the command-line argument -env - for example, atomserver.sh -env prod start to start Atomserver with the "prod" environment.The environment name is used to load properties from the classpath - these properties are made available to the Spring context in addition to the standard java System Properties. Atomserver loads /env/{atomserver.env}.properties and /env/{atomserver.env}-ops.properties from the classpath -- properties in {atomserver.env}-ops.properties override the ones in {atomserver.env}.properties. The search order for these properties files is as defined in the above section (note that the {atomserver.env}-ops.properties does not necessarily HAVE to be in the {atomserver.ops.conf.dir}, nor does the {atomserver.env}.properties file need to be in the normal conf dir, but in any case only ONE file with each name will be loaded, and the search order is defined by the classloader. if you define both properties files in the ops conf dir, then those two WILL be loaded, and no others.)
Additional resources
You may find the following third-party documents useful:* Overview of Atom from IBM
* HTTP 1.1 method definitions; specification for GET, POST, PUT, and DELETE
* HTTP 1.1 status code definitions
* Atom Syndication Reference (from Atom-enabled)
* Getting to know the Atom Publishing Protocol (from IBM)