001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.cocoon.environment;
018:
019: import java.io.IOException;
020: import java.io.OutputStream;
021: import java.util.Enumeration;
022: import java.util.Map;
023:
024: /**
025: * Base interface for an environment abstraction
026: *
027: * @author <a href="mailto:bluetkemeier@s-und-n.de">Björn Lütkemeier</a>
028: * @author <a href="mailto:Giacomo.Pati@pwr.ch">Giacomo Pati</a>
029: * @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
030: * @version $Id: Environment.java 433543 2006-08-22 06:22:54Z crossley $
031: */
032: public interface Environment extends SourceResolver {
033:
034: /**
035: * Get the URI to process. The prefix is stripped off.
036: */
037: String getURI();
038:
039: /**
040: * Get the prefix of the URI in progress.
041: */
042: String getURIPrefix();
043:
044: /**
045: * Get the Root Context
046: */
047: String getRootContext();
048:
049: /**
050: * Get current context
051: */
052: String getContext();
053:
054: /**
055: * Get the view to process
056: */
057: String getView();
058:
059: /**
060: * Get the action to process
061: */
062: String getAction();
063:
064: /**
065: * Set the context. This is similar to changeContext()
066: * except that it is absolute.
067: */
068: void setContext(String prefix, String uri, String context);
069:
070: /**
071: * Change the context from uriprefix to context
072: */
073: void changeContext(String uriprefix, String context)
074: throws Exception;
075:
076: /**
077: * Redirect the client to the given URL
078: */
079: void redirect(boolean sessionmode, String url) throws IOException;
080:
081: /**
082: * Set the content type of the generated resource
083: */
084: void setContentType(String mimeType);
085:
086: /**
087: * Get the content type of the resource
088: */
089: String getContentType();
090:
091: /**
092: * Set the length of the generated content
093: */
094: void setContentLength(int length);
095:
096: /**
097: * Set the response status code
098: */
099: void setStatus(int statusCode);
100:
101: /**
102: * Get the output stream where to write the generated resource.
103: * @deprecated Use {@link #getOutputStream(int)} instead.
104: */
105: OutputStream getOutputStream() throws IOException;
106:
107: /**
108: * Get the output stream where to write the generated resource.
109: * The returned stream is buffered by the environment. If the
110: * buffer size is -1 then the complete output is buffered.
111: * If the buffer size is 0, no buffering takes place.
112: * This method replaces {@link #getOutputStream()}.
113: */
114: OutputStream getOutputStream(int bufferSize) throws IOException;
115:
116: /**
117: * Get the underlying object model
118: */
119: Map getObjectModel();
120:
121: /**
122: * Check if the response has been modified since the same
123: * "resource" was requested.
124: * The caller has to test if it is really the same "resource"
125: * which is requested.
126: * @return true if the response is modified or if the
127: * environment is not able to test it
128: */
129: boolean isResponseModified(long lastModified);
130:
131: /**
132: * Mark the response as not modified.
133: */
134: void setResponseIsNotModified();
135:
136: /**
137: * Binds an object to this environment, using the name specified. This allows
138: * the pipeline assembly engine to store for its own use objects that souldn't
139: * be exposed to other components (generators, selectors, etc) and therefore
140: * cannot be put in the object model.
141: * <p>
142: * If an object of the same name is already bound, the object is replaced.
143: *
144: * @param name the name to which the object is bound
145: * @param value the object to be bound
146: */
147: void setAttribute(String name, Object value);
148:
149: /**
150: * Returns the object bound with the specified name, or <code>null</code>
151: * if no object is bound under the name.
152: *
153: * @param name a string specifying the name of the object
154: * @return the object with the specified name
155: */
156: Object getAttribute(String name);
157:
158: /**
159: * Removes the object bound with the specified name from
160: * this environment. If the environment does not have an object
161: * bound with the specified name, this method does nothing.
162: *
163: * @param name the name of the object to remove
164: */
165: void removeAttribute(String name);
166:
167: /**
168: * Returns an <code>Enumeration</code> of <code>String</code> objects
169: * containing the names of all the objects bound to this environment.
170: *
171: * @return an <code>Enumeration</code> of <code>String</code>s.
172: */
173: Enumeration getAttributeNames();
174:
175: /**
176: * Reset the response if possible. This allows error handlers to have
177: * a higher chance to produce clean output if the pipeline that raised
178: * the error has already output some data.
179: * If a buffered output stream is used, resetting is always successful.
180: *
181: * @return true if the response was successfully reset
182: */
183: boolean tryResetResponse() throws IOException;
184:
185: /**
186: * Commit the response
187: */
188: void commitResponse() throws IOException;
189:
190: /**
191: * Notify that the processing starts.
192: */
193: void startingProcessing();
194:
195: /**
196: * Notify that the processing is finished
197: * This can be used to cleanup the environment object
198: */
199: void finishingProcessing();
200:
201: /**
202: * Is this environment external ? An external environment is one that
203: * is created in response to an external request (http, commandline, etc.).
204: * Environments created by the "cocoon:" protocol aren't external.
205: *
206: * @return true if this environment is external
207: */
208: boolean isExternal();
209:
210: /**
211: * Is this an internal redirect?
212: * An environment is on internal redirect if it is an internal request
213: * (via the cocoon: protocol) and used for a redirect.
214: */
215: boolean isInternalRedirect();
216: }
|