<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  The ASF licenses this file to You
  under the Apache License, Version 2.0 (the "License"); you may not
  use this file except in compliance with the License.
  You may obtain a copy of the License at
 
      http://www.apache.org/licenses/LICENSE-2.0
 
  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.  For additional information regarding
  copyright in this work, please see the NOTICE file in the top level
  directory of this distribution. -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Apache Abdera</title>
    <meta name="generator" content="DocBook XSL Stylesheets V1.70.1"/>
  </head>
  <body>
    <!-- Header -->
  <div id="banner">
    <h1><a href="http://incubator.apache.org/abdera">Apache Abdera</a></h1>
    <p>Version 0.4.0-incubating-SNAPSHOT</p>
    <hr/>
  </div>
  <div id="divider"></div>
  
      <h1>Implementing A Server</h1>
  
    <div class="article" lang="en">
    <div class="titlepage">
    <div><div class="author">
      <h3 class="author">Contributed by: <span class="firstname">Adam</span> <span class="surname">Constabaris</span></h3>
      </div>
    </div>
    </div>
    </div>
    <div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#intro">Introduction</a></span></dt><dt><span class="section"><a href="#providers">Implementing <code class="classname">Provider</code></a></span></dt><dt><span class="section"><a href="#app_assembly">Putting it all together</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro"/>Introduction</h2></div></div></div><p>The framework for implementing an APP server in Abdera is, as shipped, incomplete, but
            armed with a knowledge of how APP works, you shouldn't have too much trouble enabling
            APP access to an (appropriate!) domain model. In order to effectively use the classes in
            the framework, you'll have to know how to configure them and what you need to implement
            yourself. The first part of the document describes (loosely) how Abdera is configured,
            while the second part concerns notes about implementing some of the more important
            classes. I assume throughout that you are familiar with the Atom format, APP basics, and
            Abdera's general model for representing the Atom format. </p><p> Abdera is designed to use a controller servlet, and ships with a basic implementation
            that is be suitable for a range of situations. Changing your Abdera server configuration
            is largely achieved by setting properties of the form
                <code class="literal">some.abdera.framework.Interface=my.domain.abdera.InterfaceImplementation</code>;
            that is, the property's name is the fully qualified name of the interface whose
            implementation you want to specify, and the value is the fully-qualified name of a class
            that implements that interface. Swapping out Abdera's default parser factory for a
            SAX-based one, for example, would be done by setting
                <span class="property">org.apache.abdera.parser.ParserFactory</span> to (say)
                <span class="property">net.my.domain.MyParserFactory</span>. </p><p> Properties can be specified in a number of places; first, most of the crucial bits of
            core Abdera are specified in <code class="classname">org.apache.abdera.util.Constants</code>.
            You can also use the Java standard <a href="http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html#Service%20Provider" target="_top">service provider</a> mechanism, or a file named
            <code class="filename">abdera.properties</code> on the classpath (generally, values are looked up
            in this order, with later values overriding ones set by earlier mechanisms). While
            Abdera core ships with settings that allow you to parse or create feed documents without
            any special configuration, server implementations are more variable and so require more
            work. </p><p>As you might expect, this form of configuration makes heavy use of reflection, and
            default or well-known constructors. In general, if you don't need to supply a lot of
            helper classes or are happy using (e.g) JNDI lookup mechanisms to look up such things as
            database connections, you can use these mechanisms without too much fuss. It's also not
            much more work to use a dependency injection framework (such as Spring) for your server
            configuration. </p><p> The interfaces you need to implement in order to create an APP server are listed in
                <code class="classname">org.apache.abdera.protocol.server.util.ServerConstants</code>: </p><div class="variablelist"><dl><dt><span class="term">

                        <code class="classname">org.apache.abdera.protocol.server.servlet.RequestHandlerManager</code>
                    </span></dt><dd><p>Factory for objects that control the request processing.</p></dd><dt><span class="term">
                        <code class="classname">org.apache.abdera.protocol.server.auth.SubjectResolver</code>
                    </span></dt><dd><p>Factory for objects that determine the identity of calling
                        clients.</p></dd><dt><span class="term">
                        <code class="classname">org.apache.abdera.protocol.server.provider.TargetResolver</code>
                    </span></dt><dd><p>Factory for objects that determine the type of APP entity involved
                            in the request (e.g. entry, collection, media, service, categories)</p></dd><dt><span class="term">

                        <code class="classname">org.apache.abdera.protocol.server.ServiceContext</code>
                    </span></dt><dd><p>Controller: coordinates all of the other factory classes.</p></dd><dt><span class="term">
                        <code class="classname">org.apache.abdera.protocol.server.provider.ProviderManager</code>
                    </span></dt><dd><p>Factory for <code class="classname">Provider</code> implementations that
                            implement the CRUD operations of the APP server.</p></dd></dl></div><p>
        </p><p> The <code class="classname">org.apache.abdera.protocol.server.provider.Provider</code>

            interface defines all of the CRUD operations involved in the Atom protocol: this is
            where you put the code that gets entries, collections, service documents,and handles
            updates and deletions; most of the rest of these classes are involved in making sure an
            HTTP request is routed to the right method on the <code class="classname">Provider</code>. Since
            the <code class="classname">ProviderManager</code> class is responsible for instantiating and
            configuring your <code class="classname">Provider</code> objects, it has an important role to
            play. Concrete default implementations for most of the other interfaces are provided,
            but you will have to provide implementations for both
            <code class="classname">ProviderManager</code> and <code class="classname">Provider</code>. </p><p> An absolutely minimal APP server will also have to configure a target resolver, i.e. provide
            a way to determine which kind of APP entity is being operated on (i.e. it answers questions of
            the form "is this a request for a service document?").  In all likelihood, a subclass of
                <code class="classname">org.apache.abdera.protocol.server.util.RegexTargetResolver</code>

            will suffice here, since it maps request URIs that match a particular regular expression
            to entity types. Your subclass can supply the actual mapping that you're going to use
            (see <code class="classname">SimpleTargetResolver</code> in the server example).  Additionally, since the
        <code class="classname">ServiceContext</code> is responsible for getting references to all these other
            classes and configuring them (most importantly the <code class="classname">ProviderManager</code>), you'll 
            probably want to subclass it as well.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="providers"/>Implementing <code class="classname">Provider</code></h2></div></div></div><p>While the specifics are going to be largely determined by the type of information your
            server is processing and how it's stored (e.g. on a file system vs. rows in a database),
            there are a few things to look out for that apply to any <code class="classname">Provider</code>
            implementation. One thing you'll definitely need is need a system for turning objects in
            your domain model into Abdera's model objects, and vice-versa. This part has to be left
            as an exercise for the reader. </p><p>Most of the methods in the <span class="interface">Provider</span> interface are fairly well
            described by their names: <code class="methodname">getEntry</code>, for example, is called when
            the client has called <code class="literal">GET</code> on an entry URI. One exception here is the
                <code class="methodname">getInfo</code> method, which serves mainly to enable support for
            HTTP's <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.3" target="_top">conditional GET</a> [ <a href="http://fishbowl.pastiche.org/2002/10/21/http_conditional_get_for_rss_hackers" target="_top">see also</a> ]. </p><p> You'll notice that the various <code class="methodname">getXXX</code> methods return a
                <code class="classname">ResponseInfo</code> object, which encompasses the HTTP response,
            including the headers and response body. In addition to the
            <code class="classname">RequestContext</code> argument, these methods also accept a
                <code class="literal">boolean</code> argument that determines whether the method is evaluating
            the request for cacheability<sup>[<a id="d0e180" href="#ftn.d0e180">1</a>]</sup> or whether it should actually generate a response body. Let's refer to the
            first mode (where the boolean parameter is <code class="literal">false</code>) as "header mode"
            and the second as "full response mode". When the method is called in header mode, it
                <span class="emphasis"><em>may</em></span> check the <code class="literal">ETag</code> or
                <code class="literal">If-Modified-Since</code> HTTP headers submitted by the APP client
            against the entry's current tag or modification time. </p><p>So, if you're implementing conditional GET in your <code class="classname">Provider</code>,
            the <code class="methodname">getInfo</code> method can delegate to the appropriate
                <code class="methodname">getXXX</code> method in header mode. Even if your provider
                <span class="emphasis"><em>doesn't</em></span> support conditional GET, you'll probably want to
            support different header and full response modes, to avoid having to generate a
            potentially "expensive" document twice. A relatively straightforward way to do this is
            to have your methods return an <code class="classname">EmptyResponseContext</code> with a status
            code of 200 (or 404, if the user's requested an entry that doesn't exist) when they're
            called in header mode. The default request processing pipeline ensures that the method
            will be called again in full response mode.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="app_assembly"/>Putting it all together</h2></div></div></div><p>The default <code class="classname">AbderaServlet</code> class can be used as your servlet controller, but
        it is somewhat limited in how much "help" it can provide by way of making servlet or EJB container resources such as
            database connection pools available to your protocol implementation.  <code class="classname">AbderaServlet</code>

            uses the property-resolution mechanisms described above<sup>[<a id="d0e224" href="#ftn.d0e224">2</a>]</sup>.  The basic
            steps it uses to process a request are:
        </p><div class="procedure"><ol type="1"><li><p>Obtain a reference to a <code class="classname">ServiceContext</code> (via reflection).</p></li><li><p>Use the service context to get a reference to a <code class="classname">RequestHandlerManager</code>.</p></li><li><p>Use the request handler manager to obtain a <code class="classname">RequestHandler</code>.</p></li><li><p>Call <code class="methodname">process()</code> on the request handler.</p></li></ol></div><p>

            If your <code class="classname">ServiceContext</code> implementation can get references to 
            appropriately configured target resolvers and provider managers, then all you need to do
            is map the AbderaServlet to the desired URI and set the <span class="property">org.apache.abdera.protocol.server.ServiceContext</span>
            property to the name of your service context implementation.
        </p><p>
            If you require greater control over how the <code class="classname">ServiceContext</code> is instantiated or 
            configured, you should create your own servlet whose <code class="methodname">service</code> method executes 
            this basic process.
        </p></div><div class="footnotes"><br/><hr width="100" align="left"/><div class="footnote"><p><sup>[<a id="ftn.d0e180" href="#d0e180">1</a>] </sup>They can also check that certain preconditions are satisfied,
                    e.g. the "lost update" mechanism for a PUT (update) request, which checks
                    whether the ETag supplied by the client matches the current ETag for the 
                    associated entry, but I'll leave that part out.</p></div><div class="footnote"><p><sup>[<a id="ftn.d0e224" href="#d0e224">2</a>] </sup>With one twist: it also lets you specify your
                implementation classes via the servlet's initialization parameters.</p></div></div></div></body></html>