My favorites ▼ | Sign in
Project Home Downloads Wiki Issues Source
Search
for
V2Server  
V2 APP Server
Updated Oct 15, 2011 by a...@milowski.com

Goals

A new server design is being developed with the following goals:

  • merging the "server" and the "web server" via Restlet mechanism so applications and APP server components can run side-by-side,
  • using a single XML configuration for the APP server so that the server isn't a closed system,
  • direct ability to mix any Restlet code/application with the APP server,
  • removal of atom feeds configuration (to much self-recursion and too complicated),
  • reliance on an XQuery-enabled database for feed storage,
  • use of XProc for APP implementation,
  • agnostic user authentication and management.

Getting Started

Current Release - 2.0.m5

Available for download at 2.0.m5

Installing

Once you have downloaded the jar archive, just run the archive to run the install process: 

   java -jar atomojo-app-server-2.0.m5.jar

Within the configuration directory you will find a number of XML configuration files. Some of these files are the configuration of the core APP implementation:

  • admin.xml - configuration of service administration
  • collections.xml - configuration of collection management
  • service.xml - the main service interface
  • query.xml - the query interface

The file named server.xml is the main configuration file. It references private.xml for most of the the server configuration with the exception of SSL certificate keystores. Also, users.xml is referenced by private.xml if you are going to use Google ClientLogin for authentication.

Configuration

Once you've installed the server, you just need to do two things to get started:

  1. Change the marklogic server host, port, username, and password in private.xml
  2. Configure you media handling.

If you plan on using Google's ClientLogin, you must define the users and their roles in conf/users.xml.

User Configuration

Any user assigned the role http://www.atomojo.org/Role/Administrator is allowed to administrate the server.

Any user assigned the role http://www.atomojo.org/Role/Query is allowed to query a database.

If the login.type parameter is set to google.ClientLogin, the user authentication process will attempt to authenticate users via Google. You must list the users allowed to access the database in the referenced users.xml document.

Otherwise, server will attempt to authenticate against the service configured using the Authentication Protocol's /auth service and the roles returned by that service will be used.

The server will attempt to assign a session to the client via the I cookie. If that cookie is sent and has not expired, user authentication will not be required for future requests. Identities are cached by the server for the duration of the session.

Database Configuration

A MarkLogic database is required for this version. You need to have a different XDBC service for each database defined for your database. Just point the server at the XDBC connection and make sure you have an XDBC user that can add, delete, and query collections.

Each database must contain configuration parameters typically located in the private.xml file. Each parameter must be prefixed with the database name. For example, for a database named db, each parameter in private.xml is prefixed with db.. 

<!-- MarkLogic User -->
<parameter name="db.xdb.user" value=""/>
<parameter name="db.xdb.password" value=""/>
<parameter name="db.xdb.host" value=""/>
<parameter name="db.xdb.port" value=""/>

All the MarkLogic parameters are suffixed with xdb.user, 'xdb.password, xdb.host, xdg.port` and must be set.

The conf/server.xml already defines the media storage to be file-based in the conf/private.xml file: 

<attribute name="app.media.storage" class="org.atomojo.app.server.collections.FileMediaStorage" ref="app-server"/>

To use file-based media storage, each database must define the directory to use by setting a database-specific parameter: 

<attribute name="db.app.media.href" href="../media"/>

In the above example, the database db will use a directory ../media/ relative to the element's base URI. Note that the use of the 'href' attribute will resolve the directory relative to the base URI of the element. If the value attribute is used instead, the directory must be an absolute path.

Using Amazon S3 for Media Storage

Amazon S3 can be used to store media by changing the app.media.storage attribute: 

<attribute name="app.media.storage" class="org.atomojo.app.server.collections.S3MediaStorage" ref="app-server"/>

Each database must then define an app.s3.bucket suffixed parameter with the name of the S3 bucket name: 

<parameter name="db.app.s3.bucket' value='my-media'/>

The Amazon S3 media storage system will attempt load the Amazon AWS key and secret from the parameters aws.key and aws.secret, respectively.

If you do not want to expose the AWS key and secret as a parameter to the whole application, you can package them into a jar file and instantiate them as an attribute named app.s3.credentials. The instance must implement com.amazonaws.auth.AWSCredentials: 

<attribute name="app.s3.credentials" class="com.example.aws.Credentials" ref="aws.s3"/>

The ref attribute must refer to a definition contained at the top of your conf/server.xml configuration document: 

<define name="aws.s3" ref="app-server">
   <library href="example.com.aws.jar"/>
</define>

and the jar file example.com.aws.jar must contain the compiled classes.

Starting the Server

You can start the server by running the server script created by the installer: 

   server conf/server.xml

where conf/server.xml is the server configuration you modified in the previous section. You can also run the server by Java directly: 

   java -jar atomojo-v2-server.jar conf/server.xml

Once you've run the server, every database you configure will be accessed via the root of the server at: 

/{database}/ ...

You should create a new workspace by posting an app:workspace element to the /{database}/admin/workspaces/ path: 

POST /db/admin/workspaces/ HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Type: application/atomsvc+xml;type=workspace
Content-Length: nnn
Slug: test

<app:workspace xmlns:app="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom">&#xa;
<atom:title>My Workspace</atom:title>
<app:collection href="*"/>
</app:workspace>

Each app:collection element should just be a reference to a defined collection. The href attribute must either by * (every collection) or an exact match to a specific collection. These elements will be replaced by the configured collection description.

Service Quick Start

Service Interface

The service document is available at the root of the server: 

GET /db/ HTTP/1.1
Host: example.org

HTTP/1.1 200 Ok
Date: Tues, 23 Aug 2011 17:18:11 GMT
Content-Length: nnn
Content-Type: application/atomsvc+xml;charset="utf-8"

<app:service xmlns:app="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom">
   <app:workspace>
      <atom:title>Test Workspace</atom:title>
      <app:collection href="/collections/test/">
         <atom:title>Test</atom:title>
      </app:collection>
   </app:workspace>
</app:service>

Every collection has a URI path: 

/{database}/collections/{name}/

Every entry has a path: 

/{database}/collections/{name}/_/{id}.atom

Every media resource has a path: 

/{database}/collections/{name}/{file}

Every collection is listed in the collections feed located at: 

/{database}/collections/

Creating Collections

You can create a new collection by posting an app:collection element to this feed and an entry will be created in the collections feed: 

POST /db/collections/ HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Type: application/atomsvc+xml;type=collection
Content-Length: nnn
Slug: test

<app:collection xmlns:app="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom">
<atom:title>Test Collection</atom:title>
</app:collection>

The Slug header is accepted on the collection feed and has the same effect as in the APP protocol. It will name the collection path segment. If no Slug header is specified, a name will be generated by the server.

Once a collection is created, the standard APP protocol (RFC 5023) is available on the collection URI. The collection itself can be deleted by deleting the corresponding entry from the collections feed.

Querying Collections

You can now query a database by posting an XQuery to: 

/{database}/query/

The query must have the media type application/xquery. Any query parameters on the URI will be passed as parameters (external variables) to the query. The result is serialized and returned as the response entity.

Entries and media are organized into collections. Each feed has two collections: entries and media. For example, if your feed URI is https://localhost/db/collections/test/, then your entry collection is: 

app://collections/test/entry

and your media collection is: 

app://collections/test/media

You may query any content you have stored in your database.

Tools for Handling Media

There is a new tool called media-tool that will upload new media (e.g. image files) to a collection. It maintains a collection of the same name as a directory on the server.

For example, if you have a directory named "Pictures", you can synchronize it against a service: 

   media-tool - https://app.example.com/test/ Pictures

The first argument to the media-tool command is the user authentication information. If you specify -, it will prompt you for your username and password. You may also pass your username or username:password and it will prompt for what it needs.

This tool only maintains one level of hierarchy. You must specify each directory you want to synchronize.

A directory is only synchronized in an additive method where new files or updated files will be uploaded. If a file is deleted locally, it will not be deleted on the server. Similarly, if a file is deleted on the server, it will not be deleted locally. A future version of this tool may support these operations.

Milestone Releases

See the Change Log.


► Sign in to add a comment
Powered by Google Project Hosting