View Javadoc

1   /*
2    * Copyright 2000-2001,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  
17  package org.apache.jetspeed.portal;
18  
19  import org.apache.jetspeed.util.MimeType;
20  import org.apache.turbine.util.RunData;
21  import org.apache.ecs.ConcreteElement;
22  
23  import java.io.Serializable;
24  /***
25  A portlet is an implementation of a small control (usually rendered in HTML)
26  that is available to a client application.  Portlets were designed to be
27  extensible so that 3rd parties implement their own Portlets.
28  
29  @author <a href="mailto:burton@apache.org">Kevin A. Burton</a>
30  @version $Id: Portlet.java,v 1.48 2004/03/29 21:38:42 taylor Exp $
31  */
32  public interface Portlet extends Serializable
33  {
34  
35      public int PORTLET_NORMAL = 0;
36      public int PORTLET_MINIMIZED = 1;
37      public int PORTLET_MAXIMIZED = 2;
38  
39      /***
40      Returns a name for this portlet.  This is used by PSML to identify a Portlet
41      within the PortletRegistry
42      */
43      public String getName();
44  
45      /***
46      Sets the name on this Portlet.
47  
48      @see #getName()
49      */
50      public void setName(String name);
51  
52      /***
53      <p>
54      Allows a Portlet to define its title.  This can be used by a PortletControl
55      for rendering its content.
56      </p>
57  
58      <p>
59      In order to define a default title you should not override this but should
60      call setTitle() within your init() method
61      </p>
62  
63      <p>
64      This should return null if not specified.
65      </p>
66      */
67      public String getTitle();
68  
69      /***
70       * Get a title for this instance of the portlet.  This method is called
71       * from the context variable portlet_instance and from PortletInstance
72       *
73       * If you wish to append to the title, then you code should look like
74       *    getTitle( String instanceTitle)
75       *    {
76       *      return super.getTitle( instanceTitle) + " - Appened title text";
77       *    }
78       *
79       * @param instanceTitle Title from PSML
80       */
81      public String getTitle( String instanceTitle);
82  
83      /***
84      Set the title for this Portlet
85      */
86      public void setTitle( String title );
87  
88      /***
89      <p>
90      Returns a description of this portlet.  This should describe what the
91      capabilities of the portlet and how it can help the user.
92      </p>
93  
94      <p>
95      In order to define a default title you should not override (in the
96      AbstractPortlet implementation) this but should call setDescription()
97      within your init() method
98      </p>
99  
100     <p>
101     This should return null if not specified.
102     </p>
103     */
104     public String getDescription();
105 
106     /***
107      * Get a Description for this instance of the portlet.  This method is called
108      * from the context variable portlet_instance and from PortletInstance
109      *
110      * If you wish to append to the Description, then you code should look like
111      *    getDescription( String instanceTitle)
112      *    {
113      *      return super.getDescription( instanceDescription) + " - Appened Description text";
114      *    }
115      *
116      * @param instanceDescription Description from PSML
117      */
118     public String getDescription( String instanceDescription);
119 
120     /***
121     Set the description for this Portlet
122     */
123     public void setDescription( String description );
124 
125     /***
126      * Getter for property image. 
127      * @return Name of portlet image, icon.  The name is expected to be in the form of a URL.
128      */
129     public String getImage(String instanceImage);
130     
131     /***
132      * Setter for property image. 
133      */
134     public void setImage(String instanceImage);
135 
136     /***
137     Returns an HTML representation of this portlet.  Usually a Portlet would
138     initialized itself within init() and then when getContent is called it
139     would return its presentation.
140     */
141     public ConcreteElement getContent(RunData rundata);
142 
143 
144     /***
145     All initialization should be performed here.  If your Portlet wants to
146     do any work it should be done here.  You are not guaranteed that any
147     particular order of method call will happen just that init() will happen
148     first. Therefore if you have to calculate things like a title, a
149     description, etc it should happen here.
150     */
151     public void init( ) throws PortletException;
152 
153 
154     /***
155     Set's the configuration of this servlet.
156     */
157     public void setPortletConfig(PortletConfig pc);
158 
159 
160     /***
161     Get the config of this servlet.
162     */
163     public PortletConfig getPortletConfig();
164 
165     /***
166     <p>Return true if this portlet is allowed to be edited in the rundata's context .</p>
167 
168     <p>Note:  PortletControl implementations should pay attention to this so
169     that they don't allow this option if it returns false.</p>
170     */
171     public boolean getAllowEdit( RunData rundata );
172 
173     /***
174     <p>Return true if this portlet is allowed to be viewed in the rundata's context .</p>
175 
176     <p>Note:  PortletControl implementations should pay attention to this so
177     that they don't allow this option if it returns false.</p>
178     */
179     public boolean getAllowView( RunData rundata );
180     
181     /***
182     <p>Return true if this portlets is allowed to be maximized.</p>
183 
184     <p>Note:  PortletControl implementations should pay attention to this so
185     that they don't allow this option if it returns false.</p>
186     */
187     public boolean getAllowMaximize( RunData rundata );
188 
189     /***
190     Get the creation time for this Portlet
191     */
192     public long getCreationTime();
193     
194     /***
195      * Returns TRUE if the title bar in should be displayed. The title bar includes
196      * the portlet title and action buttons.  This
197      * 
198      * @param rundata The RunData object for the current request
199      */
200     public boolean isShowTitleBar(RunData rundata);
201 
202     /***
203     Set the creation time for this Portlet
204     */
205     public void setCreationTime( long creationTime );
206     
207     /***
208     Returns true portlet is able to output content for given mimetype
209     */
210     public boolean supportsType( MimeType mimeType );
211 
212     /***
213      * Retrieve a portlet attribute from persistent storage
214      *
215      * @param attrName The attribute to retrieve
216      * @param attrDefValue The value if the attr doesn't exists
217      * @param rundata The RunData object for the current request
218      * @return The attribute value
219      */
220     public String getAttribute( String attrName, String attrDefValue, RunData rundata );
221 
222 
223     /***
224      * Stores a portlet attribute in persistent storage
225      *
226      * @param attrName The attribute to retrieve
227      * @paarm attrValue The value to store
228      * @param rundata The RunData object for the current request
229      */
230     public void setAttribute( String attrName, String attrValue, RunData rundata );
231 
232 
233     /***
234      * Gets the portlet instance associated with this portlet.
235      *
236      * @return PortletInstance
237      */
238     public PortletInstance getInstance(RunData rundata);
239 
240     /***
241     Retrieve a unique portlet id 
242     */
243     public String getID();
244 
245     public void setID(String id);
246 
247     /***
248     * @return true if the portlet does its own customization
249     */
250     public boolean providesCustomization();
251     
252 }
253