Berin Loritsch wrote:
>
> Currently, the Environment system has grown to provide an abstraction
> layer so that Cocoon logic can function equally well depending on whatever
> the environment is. This is a good thing, and in my opinion very necessary.
> However, what we have in our API can get confusing both for Cocoon app
> developers, and for environment adaptor providers.
>
> Because Cocoon began life as a Servlet, the environment is heavily slanted
> in that direction. While I do not want to reinvent the wheel that the
> servlet vendors have created, we can simplify our API so that app developers
> have an easier time. Currently, the Environment consists of the following
> interfaces:
>
> * Environment
> * Context
> * Cookie
> * Redirector
> * Request
> * Response
> * Session
> * Source
> * SourceResolver
>
> In addition to this we have the Avalon Context that we are using within
> the rest of the API for Cocoon system properties. Some of this is a bit
> much, and can be merged, and we can have a simpler API because of it.
> Granted that this would require deprecating some pieces in the HEAD
> branch of CVS, but I think we would be better for it in the long run.
> First, we have to consider what each piece is used for.
>
> INSTALLATION SPECIFIC API
> org.apache.avalon.framework.context.Context
> org.apache.cocoon.environment.Context
> SourceResolver
> Source
>
> SESSION SPECIFIC API
> Session
>
> REQUEST SPECIFIC API
> Redirector
> Request
> Response
> Map (ObjectModel)
>
> PERSISTENT CLIENT STORAGE
> Cookie
>
> In addition to all this, the ObjectModel is simply a Map that allows access
> to all of the APIs as we need them. It is clear that too many indirections
> (i.e. Maps) create a more cluttered API. What should we do then? Clearly
> there are two major categories of Context. There is the system context which
> provides meta information about the installation. Then there is the request
> specific context which allows us to pass information between stages, and
> access the session and client storage mechanisms.
>
> In order to simplify, I believe that there should be 2 Context objects to
> worry about: SystemContext and RequestContext. The SystemContext object
> would extend the AvalonContext--and be passed to any Contextualizable
> Component. So what would this look like:
>
> public interface SystemContext extends org.apache.avalon.framework.context.Context {
> Source resolve(String uri);
> org.apache.cocoon.environment.Context getEnvironmentContext();
> Object get(Object key); // from Avalon context
> }
>
> This removes the need for the SourceResolver interface to be exposed or passed
> as an argument to Components. Components that do not need it or use it will
> have access to a simpler API.
>
> The other Context woudl be the RequestContext. That API would be like this:
>
> public interface RequestContext extends Map {
> Request getRequest();
> Session getSession();
> Session getSession(boolean forceNew);
> Response getResponse();
> void redirect(String uri); // throws IllegalStateException if called after
>generator setup.
> Object get(Object key); // from Map
> void put(Object key, Object value); // from Map
> }
>
> This makes the RequestContext compatible with ObjectModel as it stands now--
> not forcing any MAJOR changes to the API. It also removes the need of exposing
> the Redirector interface to the clients as a passed argument. While it may
> seem tempting to do so, most developers will get the clue very quickly that
> it can only be done from the SetUp method. This will expose it to be used to
> generators and transformers alike, but the distinct difference is that the
> setup and generate commands are separate.
>
> This also simplifies client code--and the get/put methods in the RequestContext,
> but it also minimizes the overhead involved in looking up the specific environment
> interfaces from a generic Map.
>
> You'll notice that the Environment interface is missing. That is because the
> Environment interface has been identified as the contract between the sitemap
> and the environment that Cocoon is living in.
>
> Lastly, this will also open up API optimizations in that we can simplify the
> signatures to setUp(RequestContext context, String source, Parameters params);
> If there is some new interface that needs to be supplied to the sitemap
> components, it will be done through the RequestContext or SystemContext objects
> as is appropriate.
Everything sounds very reasonable.
I'm all in favor of doing something like this. +1.
Stefano.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
