View Javadoc

1   /*
2    * Copyright 2003,2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.pluto;
17  
18  import java.util.Properties;
19  import java.io.IOException;
20  
21  import javax.portlet.PortletException;
22  import javax.servlet.ServletConfig;
23  import javax.servlet.http.HttpServletRequest;
24  import javax.servlet.http.HttpServletResponse;
25  
26  import org.apache.pluto.om.window.PortletWindow;
27  import org.apache.pluto.services.PortletContainerEnvironment;
28  
29  /***
30   * The <CODE>PortletContainer</CODE> interface is the entrance point of the portlet
31   * container. This singleton is normally called by the aggregation in a specific
32   * order, meaning that each method of this singleton has to be called in a
33   * defined way.<P>
34   * The base functionality of the portlet container can be enhanced or even
35   * modified by PortletContainerServices.
36   *
37   * <P>
38   * The methods of this class have to be called in the following order:
39   * <UL>
40   * <LI>only once</LI>
41   *   <UL>
42   *   <LI>{@link #init(java.lang.String, javax.servlet.ServletConfig, org.apache.pluto.services.PortletContainerEnvironment, java.util.Properties)}</LI>
43   *   <LI>{@link #shutdown()}</LI>
44   *   </UL>
45   * <LI>for each request</LI>
46   *   <UL>
47   *   <LI>{@link #renderPortlet(org.apache.pluto.om.window.PortletWindow, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)} (for each portlet)</LI>
48   *   </UL>
49   * <LI>optional for each request</LI>
50   *   <UL>
51   *   <LI>{@link #processPortletAction(org.apache.pluto.om.window.PortletWindow, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)} (for portlet receiving the action request)</LI>
52   *   </UL>
53   * </UL>
54   * 
55   * @version $Id: PortletContainer.java 36010 2004-07-30 14:16:06Z ddewolf $
56   */
57  public interface PortletContainer
58  {
59  
60      /***
61       * Initializes the portlet container.
62       * 
63       * @param uniqueContainerName container name that must be unqiue across all containers defined within this JVM. This name must be identical across JVMs.
64       * @param servletConfig the servlet configuration
65       * @param environment the portlet container environment including all services
66       * @param properties the portlet container specific properties may vary from container to container
67       * @exception PortletContainerException
68       *                if an error occurs while initializing the container
69       */
70      public void init(String uniqueContainerName,
71                       ServletConfig servletConfig,
72                       PortletContainerEnvironment environment,
73                       Properties properties) throws PortletContainerException;
74  
75      /***
76       * Shuts down the portlet container.
77       * After calling this method it is no longer valid to call any method on the portlet container.
78       * 
79       * @exception PortletContainerException
80       *                if an error occurs while shutting down the container
81       */
82      public void shutdown() throws PortletContainerException;
83  
84      /***
85       * Calls the render method of the given portlet window.
86       * 
87       * @param portletWindow
88       *                 the portlet Window
89       * @param request  the servlet request
90       * @param response the servlet response
91       * @exception PortletException
92       *                   if one portlet has trouble fulfilling the request
93       * @exception IOException
94       *                   if the streaming causes an I/O problem
95       * @exception PortletContainerException
96       *                   if the portlet container implementation has trouble fulfilling the request
97       */
98      public void renderPortlet(PortletWindow portletWindow,
99                                HttpServletRequest request,
100                               HttpServletResponse response)
101     throws PortletException, IOException, PortletContainerException;
102 
103 
104     /***
105      * Indicates that a portlet action occured in the current request and
106      * calls the processAction method of this portlet.
107      * 
108      * @param portletWindow
109      *                 the portlet Window
110      * @param request  the servlet request
111      * @param response the servlet response
112      * @exception PortletException
113      *                   if one portlet has trouble fulfilling the request
114      * @exception PortletContainerException
115      *                   if the portlet container implementation has trouble fulfilling the request
116      */
117     public void processPortletAction(PortletWindow portletWindow,
118                                      HttpServletRequest request,
119                                      HttpServletResponse response)
120     throws PortletException, IOException, PortletContainerException;
121 
122     /***
123      * Indicates that the portlet must be initialized
124      * 
125      * @param portletWindow
126      *                 the portlet Window
127      * @param servletRequest  the servlet request
128      * @param servletResponse the servlet response
129      * @exception PortletException
130      *                   if one portlet has trouble fulfilling the request
131      * @exception PortletContainerException
132      *                   if the portlet container implementation has trouble fulfilling the request
133      */
134     public void portletLoad(PortletWindow portletWindow,
135                             HttpServletRequest servletRequest,
136                             HttpServletResponse servletResponse )
137     throws PortletException, PortletContainerException;
138 
139     /***
140      * Returns whether the container is already initialized or not.
141      * 
142      * @return <code>true</code> if the container is initialized
143      */
144     public boolean isInitialized();
145 }