001: /*
002: * Copyright 2002 Sun Microsystems, Inc. All
003: * rights reserved. Use of this product is subject
004: * to license terms. Federal Acquisitions:
005: * Commercial Software -- Government Users
006: * Subject to Standard License Terms and
007: * Conditions.
008: *
009: * Sun, Sun Microsystems, the Sun logo, and Sun ONE
010: * are trademarks or registered trademarks of Sun Microsystems,
011: * Inc. in the United States and other countries.
012: */
013: package com.sun.portal.providers.context;
014:
015: import java.util.List;
016: import java.util.Map;
017:
018: import javax.servlet.http.HttpServletRequest;
019: import javax.servlet.http.HttpServletResponse;
020:
021: import com.sun.portal.providers.Provider;
022: import com.sun.portal.providers.ProviderException;
023:
024: import com.sun.portal.desktop.dp.DPNode;
025:
026: /**
027: * An environment for container provider execution. More formally, this
028: * class adds container channel functionality to the
029: * <code>ProviderContext</code> interface. Container channel functionality
030: * includes getting provider objects, fetching content, content caching
031: * features, and getting / setting selected and available channel lists.
032: *
033: * @see com.sun.portal.providers.context.ProviderContext
034: */
035:
036: public interface ContainerProviderContext extends ProviderContext {
037: /**
038: * Separator character for nested channel names.
039: * Channels configuration can be defined in a nested, hierarchical manner
040: * within containers. This affects the name of the channel. For example,
041: * if channel A was defined with container X, the full name of the channel
042: * would be <code>X + CHANNEL_NAME_SEPARATOR + A</code>. This name is used
043: * in all <code>ContainerProviderContext</code> and <code>ProviderContext</code>
044: * methods that accept a channel name. Examples of this are:
045: * <ul>
046: * <li>ProviderContext.getProvider()
047: * <li>ProviderContext.getContent()
048: * <li>ContainerProviderContext.copyChannel()
049: * <li>ContainerProviderContext.createChannel()
050: * </ul>
051: */
052: public char CHANNEL_NAME_SEPARATOR = DPNode.CHANNEL_NAME_SEPARATOR;
053:
054: /**
055: * Tests if channel configuration exists.
056: *
057: * @param channel a <code>String</code>, the channel name.
058: * @return a <code>boolean</code>, <code>true</code> if the
059: * channel has been added, otherwise <code>false</code>.
060: */
061: public boolean existsChannel(String channel);
062:
063: /**
064: * Creates a new channel.
065: * A new channel is created based on the named provider.
066: * To create a nested channel, supply a hierarchical channel
067: * name. For example, to create channel A inside of container X, based on
068: * provider P:<br><br>
069: * <code>createChannel("X" + CHANNEL_NAME_SEPARATOR + "A", "P");</code>
070: * <p>
071: * This method only modifies the underlying configuration and
072: * does not create a <code>Provider</code>
073: * object. After calling this method, to get the provider object
074: * that backs this channel, call <code>getProvider()</code>.
075: *
076: * @param channelName Name of the channel being created.
077: * @param providerName Symbolic name of the provider that will back the channel being created.
078: * @exception ProviderContextException if an error occurs in creating the
079: * new global scope channel.
080: * @see #getProvider(HttpServletRequest, String, String)
081: */
082: public void createChannel(String channelName, String providerName)
083: throws ProviderContextException;
084:
085: /**
086: * Creates a new container channel.
087: * A new container channel is created based on the named provider.
088: * To create a nested container channel, supply a hierarchical channel
089: * name. For example, to create container C inside of container X, based on
090: * provider P:<br><br>
091: * <code>createContainer("X" + CHANNEL_NAME_SEPARATOR + "C", "P");</code>
092: * <p>
093: * This method only modifies the underlying configuration and
094: * does not create a <code>Provider</code>
095: * object. After calling this method, to get the provider object
096: * that backs this channel, call <code>getProvider()</code>.
097: *
098: * @param channelName Name of the channel being created.
099: * @param providerName Symbolic name of the provider that will back the container being created.
100: * @exception ProviderContextException if an error occurs in creating a
101: * global scope container channel.
102: * @see #getProvider(HttpServletRequest, String, String)
103: */
104: public void createContainer(String channelName, String providerName)
105: throws ProviderContextException;
106:
107: /**
108: * Copies a channel.
109: * A copy of the source channel is created and named as the destination channel.
110: * All properties of the source channel are copied to the destination channel.
111: * The destination channel will use the same provider as the source.
112: * To copy a channel into a container, supply a hierarchical channel
113: * name. For example, to copy channel A inside of container X, renaming it
114: * as channel B:
115: * <code>copyChannel("A", "X" + CHANNEL_NAME_SEPARATOR + "B");</code>
116: * <p>
117: * This method only modifies the underlying configuration and
118: * does not create a <code>Provider</code>
119: * object. After calling this method, to get the provider object
120: * that backs this channel, call <code>getProvider()</code>.
121: * <p>
122: * This method copies container channels as well as channels. To copy a container
123: * channel, simply supply its name as the source.
124: *
125: * @param srcName Name of the source channel, the channel to be copied.
126: * @param dstName Name of the destination channe, the channel copy.
127: * @exception ProviderContextException if an error occurs copying the channel.
128: * @see #getProvider(HttpServletRequest, String, String)
129: */
130: public void copyChannel(String srcName, String dstName)
131: throws ProviderContextException;
132:
133: /**
134: * Removes a global scope channel.
135: * <p>
136: * This method only modifies the underlying configuration and does not
137: * modify the references of the channel in other places in the
138: * configuration.
139: *
140: * @param channelName Name of the channel being removed.
141: * @exception ProviderContextException if an error occurs in removing the
142: * global scope channel.
143: */
144: public void removeChannel(String channelName)
145: throws ProviderContextException;
146:
147: /**
148: * Gets a provider.
149: *
150: * This method returns an instance of a <code>Provider</code> object
151: * for the named channel. This method will return null if the provider
152: * object is not available.
153: * <br><br>
154: * The HTTP request object parameter must contain implementation
155: * specific initialization information.
156: *
157: * @param req an <code>HttpServletRequest</code> object
158: * containing provider initialization information.
159: * @param container Container channel name, or <code>null</code> if the
160: * channel is not contained.
161: * @param channel a <code>String</code>, the channel name.
162: * @return <code>Provider</code> object for the given channel name.
163: */
164: public Provider getProvider(HttpServletRequest req,
165: String container, String channel);
166:
167: /**
168: * Gets the content view for the named channel.
169: *
170: * This method is provided for convenience. It gets the provider object
171: * for the named channel and calls
172: * <code>Provider.getContent(HttpServletRequest, HttpServletResponse)</code>.
173: *
174: * @param req an <code>HttpServletRequest</code> object to pass on to the
175: * provider object.
176: * @param res an <code>HttpServletResponse</code> object to pass on to the
177: * provider object.
178: * @param container Container channel name, or <code>null</code> if the
179: * channel is not contained.
180: * @param name Channel name.
181: * @return a <code>StringBuffer</code> that is the channels content view, or
182: * null if there is an error in getting the channel content or if the
183: * channel is not presentable for that
184: * particular client type.
185: * @exception ProviderException if an error occurs in the provider's
186: * <code>getContent()</code> method.
187: * @see com.sun.portal.providers.Provider#getContent(HttpServletRequest, HttpServletResponse)
188: */
189: public StringBuffer getContent(HttpServletRequest req,
190: HttpServletResponse res, String container, String channel)
191: throws ProviderException;
192:
193: /**
194: * Initializes a set of channels. This method is provided for convenience.
195: * It gets the provider object for each channel and calls its
196: * <code>Provider.init()</code> method. Channel initialization can be
197: * an expenesive operation. This method allows said operation to
198: * be done for all channels at one time allowing for optimizations
199: * such as parallelization.
200: *
201: * @param req a <code>HttpServletRequest</code> object passed to each
202: * channel for initialized.
203: * @param container Container channel name, or <code>null</code> if the
204: * channel is not contained.
205: * @param channels a <code>List</code> of <code>String</code> objects;
206: * the channel names.
207: * @param timeout an <code>int</code> specifying the time to wait for
208: * all channels to complete initialization.
209: * @see com.sun.portal.providers.Provider#init(String, HttpServletRequest)
210: */
211: public void initProviders(HttpServletRequest req, String container,
212: List channels, int timeout);
213:
214: /**
215: * Gets the content view for a set of channels. This method is provided
216: * for convenience. It gets the provider object for each channel and calls
217: * its <code>Provider.getContent()</code> method. Fetching a channel's
218: * content view can be an expensive operation. This method allows said
219: * operation to be done in bulk for all of the channels constributing
220: * to the page allowing for optimizations such as parallelization.
221: *
222: * @param req a <code>HttpServletRequest</code> object passed to each
223: * channel in the request for its content view.
224: * @param res a <code>HttpServletResponse</code> object passed to each
225: * channel in the request for its content view.
226: * @param container Container channel name, or <code>null</code> if the
227: * channel is not contained.
228: * @param channels a <code>List</code> object of <code>String</code>s;
229: * the channel names.
230: * @param timeout an <code>int</code> specifying the time to wait for
231: * all channels to complete getting their content view.
232: * @return a <code>Map</code> object; mapping <code>String</code>
233: * channel names to
234: * <code>StringBuffer</code> content, or mapping <code>String</code>
235: * channel names to null if there is an error in getting the channel
236: * content or if the channel is
237: * not presentable for that particular client type.
238: * @exception ProviderException if an error occurs in the provider's
239: * <code>getContent()</code> method.
240: * @see com.sun.portal.providers.Provider#getContent(HttpServletRequest, HttpServletResponse)
241: */
242: public Map getContent(HttpServletRequest req,
243: HttpServletResponse res, String container, List channels,
244: int timeout) throws ProviderException;
245:
246: /**
247: * Gets the cached content view for a channel.
248: * When a channel's content view is retrieved from a channel, it is
249: * cached if the channel's provider object returns non-zero from its
250: * <code>getRefreshTime()</code> method. This method then gets this
251: * cached content for the channel. If containers wish to support
252: * this type of content caching, they can use this method.
253: * <br><br>
254: * Note that neither of the <code>getContent()</code> methods
255: * in this interface call this method automatically. It is up to the
256: * client of this interface to manually check the cache time
257: * and either call this method or call <code>getContent()</code>
258: * for the channel. It is not mandatory that a container channel
259: * use these features and thereby support content caching.
260: *
261: * @param name a <code>String</code>, the channel name.
262: * @return a <code>StringBuffer</code>, the cached content, or
263: * <code>null</code> if there is no cached content for the channel.
264: * @see com.sun.portal.providers.Provider#getRefreshTime()
265: * @see #getCachedTime(String)
266: */
267: public StringBuffer getCachedContent(String name);
268:
269: /**
270: * Puts the cached content into a map and using the provider name as the
271: * key. The cached map is controlled internally in the implementation
272: * of this interface.
273: * <br><br>
274: *
275: * @param name a <code>String</code>, the channel name.
276: * @param content <code>StringBuffer</code>, the cached content
277: * for the channel.
278: */
279: public void putCachedContent(String name, StringBuffer content);
280:
281: /**
282: * Gets the content view cache time for a channel. When the content
283: * view for a channel is cached (see <code>getCachedContent()</code>)
284: * the time that it was cached is also recorded. This information
285: * can be used by the client to decide if the cached value is
286: * stale.
287: *
288: * @param name a <code>String</code>, the channel name.
289: * @return a <code>long</code>, the cache time, in milliseconds, or -1
290: * if the content is not cached.
291: * @see #getCachedContent(String)
292: */
293: public long getCachedTime(String name);
294:
295: /**
296: * Gets the selected channels for the container channel that this is
297: * providing an environment for. Note that the selected channels are
298: * independent of the available channels. In other words, there may be
299: * channels
300: * that are selected but not available. This method will still include
301: * those channels and does not manipulate the result in any way.
302: * Ideally, however, a set of selected channels should be a subset of
303: * availble channels.
304: *
305: * @param container Container channel name.
306: * channel is not contained.
307: * @exception ProviderContextException if an error occurs in getting the
308: * selected channels for the named container.
309: * @return A <code>List</code> of <code>String</code>s; the channel names.
310: */
311: public List getSelectedChannels(String container)
312: throws ProviderContextException;
313:
314: /**
315: * Gets the available channels for the container channel that this is
316: * providing an environment for.
317: *
318: * @param container Container channel name.
319: * @return A <code>List</code> of <code>String</code>s; the channel names.
320: * @exception ProviderContextException if an error occurs in getting the
321: * available channels for the named container.
322: */
323: public List getAvailableChannels(String container)
324: throws ProviderContextException;
325:
326: /**
327: * Sets the selected channels for the container channel that this is
328: * providing an environment for.
329: *
330: * @param container Container channel name.
331: * @param selected <code>List</code> of
332: * <code>String</code>s; the channel names.
333: * @exception ProviderContextException if an error occurs in setting the
334: * selected channels for the named container.
335: */
336: public void setSelectedChannels(String container, List selelected)
337: throws ProviderContextException;
338:
339: /**
340: * Sets the available channels for the container channel that this is
341: * providing an environment for.
342: *
343: * @param container Container channel name.
344: * @param available <code>List</code> of
345: * <code>String</code>s; the channel names.
346: * @exception ProviderContextException if an error occurs in setting the
347: * available channels for the named container.
348: */
349: public void setAvailableChannels(String container, List available)
350: throws ProviderContextException;
351: }
|