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.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
