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.pluto;
018:
019: import java.io.IOException;
020:
021: import javax.portlet.PortletException;
022: import javax.servlet.ServletContext;
023: import javax.servlet.http.HttpServletRequest;
024: import javax.servlet.http.HttpServletResponse;
025:
026: import org.apache.pluto.descriptors.portlet.PortletAppDD;
027:
028: /**
029: * The publicized entry point into Pluto. The base functionality of the portlet
030: * container can be enhanced or even modified by PortletContainerServices.
031: * <p/>
032: * <P> The methods of this class have to be called in the following order:
033: * <TABLE> <TR><TH>Method</TH><TH>Description</TH><TH>Constraints</TH></TR>
034: * <TR><TD>{@link #init(javax.servlet.ServletContext)}</TD> <TD>Initialized the
035: * portlet container.</TD> <TD>Performed only once per container
036: * lifecycle.</TD></TR>
037: * <p/>
038: * <TR><TD>{@link #doAction(org.apache.pluto.PortletWindow,
039: * javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)}</TD>
040: * <TD>Perform the action for the targeted portlet</TD> <TD>Optionally performed
041: * for a single portlet per request</TD></TR>
042: * <p/>
043: * <TR><TD>{@link #doRender(org.apache.pluto.PortletWindow,
044: * javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)}</TD>
045: * <TD>Render the portlet</TD> <TD>Performed once for each portlet per
046: * request.</TD></TR>
047: * <p/>
048: * <TR><TD>{@link #destroy()}</TD> <TD>Destroy and remove container from
049: * service.</TD> <TD>Performed only once per container lifecylce</TD></TR>
050: * @version $Id: PortletContainer.java 36010 2004-07-30 14:16:06Z ddewolf $
051: */
052: public interface PortletContainer {
053:
054: /**
055: * Initializes the container for use within the given servlet context.
056: * @param servletContext the servlet context.
057: * @throws PortletContainerException if an error occurs.
058: */
059: void init(ServletContext servletContext)
060: throws PortletContainerException;
061:
062: /**
063: * Shuts down the container. After calling this method it is no longer valid
064: * to call any method on the portlet container.
065: * @throws PortletContainerException if an error occurs while shutting down
066: * the container
067: */
068: void destroy() throws PortletContainerException;
069:
070: /**
071: * Calls the render method of the given portlet window.
072: * @param portletWindow the portlet Window
073: * @param request the servlet request
074: * @param response the servlet response
075: * @throws PortletException if one portlet has trouble fulfilling
076: * the request
077: * @throws IOException if the streaming causes an I/O problem
078: * @throws PortletContainerException if the portlet container implementation
079: * has trouble fulfilling the request
080: */
081: void doRender(PortletWindow portletWindow,
082: HttpServletRequest request, HttpServletResponse response)
083: throws PortletException, IOException,
084: PortletContainerException;
085:
086: /**
087: * Indicates that a portlet action occured in the current request and calls
088: * the processAction method of this portlet.
089: * @param portletWindow the portlet Window
090: * @param request the servlet request
091: * @param response the servlet response
092: * @throws PortletException if one portlet has trouble fulfilling
093: * the request
094: * @throws PortletContainerException if the portlet container implementation
095: * has trouble fulfilling the request
096: */
097: void doAction(PortletWindow portletWindow,
098: HttpServletRequest request, HttpServletResponse response)
099: throws PortletException, IOException,
100: PortletContainerException;
101:
102: /**
103: * Indicates that the portlet must be initialized
104: * @param portletWindow the portlet Window
105: * @param servletRequest the servlet request
106: * @param servletResponse the servlet response
107: * @throws PortletException if one portlet has trouble fulfilling
108: * the request
109: * @throws PortletContainerException if the portlet container implementation
110: * has trouble fulfilling the request
111: */
112: void doLoad(PortletWindow portletWindow,
113: HttpServletRequest servletRequest,
114: HttpServletResponse servletResponse)
115: throws PortletException, IOException,
116: PortletContainerException;
117:
118: /**
119: * Indicates that the portal needs to perform administrative
120: * actions upon the portlet and/or portlet application. An
121: * administrative request will be spawned and any registered
122: * handlers invoked.
123: * @param portletWindow the portlet window
124: * @param servletRequest the servlet request
125: * @param servletResponse the servlet response
126: * @throws PortletContainerException if the request can not be fullfilled.
127: */
128: void doAdmin(PortletWindow portletWindow,
129: HttpServletRequest servletRequest,
130: HttpServletResponse servletResponse)
131: throws PortletException, IOException,
132: PortletContainerException;
133:
134: /**
135: * Returns whether the container is already initialized or not.
136: * @return <code>true</code> if the container is initialized
137: */
138: boolean isInitialized();
139:
140: /**
141: * Retrieve the unique container name
142: * @return the container name.
143: */
144: String getName();
145:
146: /**
147: * Retreive the required container services associated with this container.
148: * @return the required container services associated with this container.
149: */
150: RequiredContainerServices getRequiredContainerServices();
151:
152: /**
153: * Retrieve the optional container services associated with this contianer.
154: * @return the container services provided by either the portal or the defaults.
155: */
156: OptionalContainerServices getOptionalContainerServices();
157:
158: /**
159: * Retrieve the {@link PortletAppDD} for the portlet
160: * located at the supplied context.
161: *
162: * Must not return null.
163: *
164: * @param context the context of the portlet
165: * @return the portlet application descriptor
166: * @throws PortletContainerException if the container has trouble obtaining
167: * the context of the portlet, or retrieving
168: * the <code>PortletAppDD</code>
169: */
170: PortletAppDD getPortletApplicationDescriptor(String context)
171: throws PortletContainerException;
172: }
|