This package contains the core classes of Slide arranged around the concept of a domain.

A domain is an aggregation of one or more namespaces. If we use the UNIX filesystem analogy, a domain represents the root ("/") anchor where filesystems (in this case, namespaces) are mounted.

The domain controls access to its registered namespaces and performs initialization and connection management on behalf of the namespaces.

From the client application's perspective, the domain represent the only directly accessible object. It is through this object that the client gains access to namespaces, using `Domain.accessNamespace(SecurityToken securityObject, String namespace)` static method call.

Since the domain acts as the root of a directory service, it is a static entity and there can be only one domain per Java VM.

### Initialization

When Slide is first initialized, the Domain configuration is loaded. Once again, if you are familiar with UNIX, the domain configuration file is the equivalent of the `fstab` file. The path to the domain configuration file is given through the `org.apache.slide.domain` property in your `slide.properties` file (which must be located somewhere in your `CLASSPATH`).

The domain configuration is written by an administrator and tells how to initialize each Namespace. The namespace initialization includes information like:

- The low-level services the namespace uses (structure store, content store ...).
- The namespace base topology, which includes the location of the base actions and paths in the namespace.

More details about those configuration files are given in the First Steps section.

### Access and Security

After the initialization is complete, the client application can request access to the domain. It uses one of the two different functions calls:

- `Domain.accessNamespace(SecurityToken securityObject, String namespace)`, is used to access a specific namespace. This method returns a `NamespaceAccessToken`, which is used thereafter by the application for performing operations on the namespace
- `Domain.accessDomain(SecurityToken securityObject)`, enumerates the registered namespaces with this domain. This allows application to browse the list of available namespaces.

The Domain uses an object (argument `securityObject`) to decide whether or not the client should be granted access. A good candidate is a reference to the client servlet. If the Domain decides to grant access, it hands out one or more `NamespaceAccessToken(s)` to the client.

The `NamespaceAccessToken` is a wrapper object which is used to completely hide the real Namespace object reference from the client application. It is used by Slide to authenticate and control every operations on the Namespace object.

Using the `NamespaceAccessToken`, the application can obtain access to "helper" functions. These helper interfaces group the namepsace operations into operational categories, such as `Structure`, `Security`, `ContentManagement` and `Locking`.

The NamespaceAccessToken object implements the `UserTransaction` interface (see the Java Transaction API documentation for more details) to allow the client to control transaction demarcation.

A `SlideToken` is retrieved from the servlet container, and is given as the first parameter of every helper function. It is used by the helper functions to identify the current security `Principal` and/or its credentials. It also is used to store information about the user transaction state.

What's very important to point out is that a client application placed in a properly configured environment has no mean of accomplishing any action except if the servlet container hands him a Principal object (from the `java.security package`). So the servlet only has, at a given time, the credentials of the principal who performs an action through it. By itself, it can't do anything.