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.util.template;
18  
19  // Jetspeed
20  import org.apache.jetspeed.portal.Portlet;
21  import org.apache.jetspeed.om.profile.Entry;
22  import org.apache.jetspeed.om.profile.Portlets;
23  
24  // Turbine
25  import org.apache.turbine.util.DynamicURI;
26  import org.apache.turbine.util.RunData;
27  
28  /***
29   * <p>A customized version of the TemplateLink which can handle portlet
30   * references.</p>
31   *
32   * <p>It is inserted into the template context by Turbine, via request tools.</p>
33   *
34   * <p>Each portlet must call setPortlet(this) on it before entering the template
35   * rendering code. This is done currently in VelocityPortlet.</p>
36   *
37   * @author <a href="mailto:paulsp@apache.org">Paul Spencer</a>
38   * @version $Id: JetspeedLink.java,v 1.15 2004/03/11 03:08:53 paulsp Exp $
39   */
40  public interface JetspeedLink {
41      
42      public static int CURRENT = 101;
43      public static int DEFAULT = 102;
44      public static int GROUP = 201;
45      public static int ROLE = 202;
46      public static int USER = 203;
47      public static int PANE_ID = 301;
48      public static int PANE_NAME = 302;
49      public static int PORTLET_ID = 303;
50      public static int PORTLET_NAME = 304;
51      public static int PORTLET_ID_QUERY = 305;
52      
53      
54      /***
55       * Adds a name=value pair to the path_info string.
56       *
57       * @param name A String with the name to add.
58       * @param value An Object with the value to add.
59       * @return DynamicURI that to the desired page
60       */
61      public DynamicURI addPathInfo(String name, Object value);
62      
63      /***
64       * Adds a name=value pair to the query string.
65       *
66       * @param name A String with the name to add.
67       * @param value An Object with the value to add.
68       * @return DynamicURI that to the desired page
69       */
70      public DynamicURI addQueryData(String name, Object value);
71      
72      /***
73       * Return the action key.  Used by velocity templates, i.e. $jlink.ActionKey
74       *
75       * @return the action parameter name
76       */
77      public String getActionKey();
78      
79      /***
80       * Return link to the home page without user,
81       * page, group, role, template, action, media type, language, or country
82       * in link.
83       * @return DynamicURI to the home page
84       */
85      public DynamicURI getHomePage();
86      
87      /***
88       * This will initialise a JetspeedLink object that was
89       * constructed with the default constructor
90       *
91       * @param rundata to be a RunData object
92       */
93      public void init(RunData rundata);
94      
95      /***
96       * Return a link that includes the template
97       * from rundata
98       *
99       * @return DynamicURI to template
100      */
101     public DynamicURI getTemplate();
102     
103     /***
104      * Is the PSML for the anonymous user?
105      *
106      * @return True = PSML is for the anonymous user
107      */
108     public boolean getAnonymous();
109     
110     /***
111      * Return country of the PSML file
112      *
113      * @return Country of PSML, or null if no country
114      */
115     public String getCountry();
116     
117     /***
118      * Return Group name of the PSML file
119      *
120      * @return Group name of PSML, or null if no Group name
121      */
122     public String getGroupName();
123     
124     /***
125      * Return Language of the PSML file
126      *
127      * @return Language of PSML, or null if no Language
128      */
129     public String getLanguage();
130     
131     /***
132      * Return Media Type of the PSML file
133      *
134      * @return Media Type of PSML, or null if no Media Type
135      */
136     public String getMediaType();
137     
138     /***
139      * Return Page name of the PSML file
140      *
141      * @return Page name of PSML, or null if no Page name
142      */
143     public String getPageName();
144     
145     /***
146      * Return Role name of the PSML file
147      *
148      * @return Role name of PSML, or null if no Role name
149      */
150     public String getRoleName();
151     
152     /***
153      * Return User name of the PSML file
154      *
155      * @return User name of PSML, or null if no User name
156      */
157     public String getUserName();
158     
159     /***
160      * Return a link that includes an action
161      *
162      * @param action action
163      * @return DynamicURI that includes the desire action
164      */
165     public DynamicURI getAction(String action);
166     
167     /***
168      * Return a link that includes an action to a specific portlet, as defined
169      * by an entry
170      *
171      * @param action Desired action
172      * @param entry to receive the action
173      * @return DynamicURI that includes the desire action
174      */
175     public DynamicURI getAction(String action, Entry entry);
176     
177     /***
178      * Return a link that includes an action to a specific portlet, as defined
179      * by a portlet
180      *
181      * @param action Desired action
182      * @param portlet to receive the action
183      * @return DynamicURI that includes the desire action
184      */
185     public DynamicURI getAction(String action, Portlet portlet);
186     
187     /***
188      * Return a link that includes an action to a specific portlet, as defined
189      * by a portlets
190      *
191      * @param action Desired action
192      * @param portlet to receive the action
193      * @return DynamicURI that includes the desire action
194      */
195     public DynamicURI getAction(String action, Portlets portlet);
196     
197     /***
198      * Return a link that includes an action to a specific portlet, as defined
199      * by a PEID
200      *
201      * @param action Desired action
202      * @param peid Id of portlet to receive the action
203      * @return DynamicURI that includes the desire action
204      */
205     public DynamicURI getAction(String action, String peid);
206 
207     /***
208      * Return a link to a default page for the group
209      *
210      * @param group Desired group
211      * @return DynamicURI that to the desired page
212      */
213     public DynamicURI getGroup(String group);
214     
215     /***
216      * Return a link to a desired page for the group
217      *
218      * @param page Desired page
219      * @param group Desired group
220      * @return DynamicURI that to the desired page
221      */
222     public DynamicURI getGroup(String group, String page);
223     
224     /***
225      * Return a link to a default page for the
226      * current user, group, or role.
227      *
228      * @return DynamicURI that to the desired page
229      */
230     public DynamicURI getPage();
231     
232     /***
233      * Return a link to a desired page for the
234      * current user, group, or role.
235      *
236      * @param page Desired page
237      * @return DynamicURI that to the desired page
238      */
239     public DynamicURI getPage(String page);
240     
241     /***
242      * Return a link to a desired page and pane for the
243      * current user, group, or role.
244      *
245      * @param page Desired page
246      * @param paneName Name of desired pane
247      * @return DynamicURI that to the desired page
248      */
249     public DynamicURI getPage(String page, String paneName);
250     
251     /***
252      * Return an link to a specific portlet using the portet's id
253      *
254      * @param peid of the portlet
255      * @return DynamicURI to specific portlet
256      *
257      */
258     public DynamicURI getPortletById(String peid);
259     
260     /***
261      * Add a portlet reference in the link.
262      *
263      * Note: This must be used with caution, since a portlet may exist may times
264      * in a PSML.  setPortletById() is the perfered method.
265      *
266      * @param portletName the name of the portlet to link to
267      * @return a DynamicURI referencing the named portlet for easy link construction in template
268      *
269      * @deprecated Use getPortletById()     
270      */
271     public DynamicURI getPortletByName(String portletName);
272     
273     /***
274      * Return a link to a default page for the role
275      *
276      * @param role Desired role
277      * @return DynamicURI that to the desired page
278      */
279     public DynamicURI getRole(String role);
280     
281     /***
282      * Return a link to a desired page for the role
283      *
284      * @param role Desired role
285      * @param page Desired page
286      * @return DynamicURI that to the desired page
287      */
288     public DynamicURI getRole(String role, String page);
289     
290     /***
291      * Return a link to the template.
292      *
293      * @param template to add to link
294      * @return DynamicURI to specific portlet
295      */
296     public DynamicURI getTemplate(String template);
297     
298     /***
299      * Return a link to a default page for the user
300      *
301      * @param user Desired user
302      * @return DynamicURI that to the desired page
303      */
304     public DynamicURI getUser(String user);
305     
306     /***
307      * Return a link to a desired page for the user
308      *
309      * @param page Desired page
310      * @param user Desired user
311      * @return DynamicURI that to the desired page
312      */
313     public DynamicURI getUser(String user, String page);
314 
315     /***
316      * Return a link that includes an action
317      *
318      * @param action action
319      * @return DynamicURI that includes the desire action
320      * @deprecated Use getAction()
321      */
322     public DynamicURI setAction(String action);
323     
324     /***
325      * Return a link that includes an action to a specific portlet, as defined
326      * by an entry
327      *
328      * @param action Desired action
329      * @param entry to receive the action
330      * @return DynamicURI that includes the desire action
331      *
332      * @deprecated use getAction()
333      */
334     public DynamicURI setAction(String action, Entry entry);
335     
336     /***
337      * Return a link that includes an action to a specific portlet, as defined
338      * by a portlet
339      *
340      * @param action Desired action
341      * @param portlet to receive the action
342      * @return DynamicURI that includes the desire action
343      *
344      * @deprecated use getAction()
345      */
346     public DynamicURI setAction(String action, Portlet portlet);
347     
348     /***
349      * Return a link that includes an action to a specific portlet, as defined
350      * by a portlets
351      *
352      * @param action Desired action
353      * @param portlet to receive the action
354      * @return DynamicURI that includes the desire action
355      *
356      * @deprecated use getAction()
357      */
358     public DynamicURI setAction(String action, Portlets portlet);
359     
360     /***
361      * Return a link to a default page for the group
362      *
363      * @param group Desired group
364      * @return DynamicURI that to the desired page
365      *
366      * @deprecated use getGroup()
367      */
368     public DynamicURI setGroup(String group);
369     
370     /***
371      * Return a link to a desired page for the group
372      *
373      * @param page Desired page
374      * @param group Desired group
375      * @return DynamicURI that to the desired page
376      *
377      * @deprecated use getGroup()
378      */
379     public DynamicURI setGroup(String group, String page);
380     
381     /***
382      * Return a link to a default page for the
383      * current user, group, or role.
384      *
385      * @return DynamicURI that to the desired page
386      *
387      * @deprecated use getPage()
388      */
389     public DynamicURI setPage();
390     
391     /***
392      * Return a link to a desired page for the
393      * current user, group, or role.
394      *
395      * @param page Desired page
396      * @return DynamicURI that to the desired page
397      *
398      * @deprecated use getPage()
399      */
400     public DynamicURI setPage(String page);
401     
402     /***
403      * Return a link to a desired page and pane for the
404      * current user, group, or role.
405      *
406      * @param page Desired page
407      * @param paneName Name of desired pane
408      * @return DynamicURI that to the desired page
409      *
410      * @deprecated use getPage()
411      */
412     public DynamicURI setPage(String page, String paneName);
413     
414     public DynamicURI setMediaType(String mediaType);
415 
416     /***
417      * Return an link to a specific portlet using the portet's id
418      *
419      * @param peid of the portlet
420      * @return DynamicURI to specific portlet
421      *
422      * @deprecated use getPortletById()
423      */
424     public DynamicURI setPortletById(String peid);
425     
426     /***
427      * Return an link to a specific portal element
428      *
429      * @param peid of the portal element
430      * @return DynamicURI to specific portal element
431      *
432      * @deprecated use getPortletById or getPaneById()
433      */
434     public DynamicURI setPortalElement(String peid);
435     
436     /***
437      * Add a portlet reference in the link.
438      *
439      * Note: This must be used with caution, since a portlet may exist may times
440      * in a PSML.  setPortletById() is the perfered method.
441      *
442      * @param portletName the name of the portlet to link to
443      * @return a DynamicURI referencing the named portlet for easy link construction in template
444      *
445      * @deprecated use getPortletByName()
446      */
447     public DynamicURI setPortletByName(String portletName);
448     
449     /***
450      * Return a link to a default page for the role
451      *
452      * @param role Desired role
453      * @return DynamicURI that to the desired page
454      *
455      * @deprecated use getRole()
456      */
457     public DynamicURI setRole(String role);
458     
459     /***
460      * Return a link to a desired page for the role
461      *
462      * @param role Desired role
463      * @param page Desired page
464      * @return DynamicURI that to the desired page
465      *
466      * @deprecated use getRole()
467      */
468     public DynamicURI setRole(String role, String page);
469     
470     /***
471      * Return a link to the template.
472      *
473      * @param template to add to link
474      * @return DynamicURI to specific portlet
475      *
476      * @deprecated use getTemplate()
477      */
478     public DynamicURI setTemplate(String template);
479     
480     /***
481      * Return a link to a default page for the user
482      *
483      * @param user Desired user
484      * @return DynamicURI that to the desired page
485      *
486      * @deprecated use getUser()
487      */
488     public DynamicURI setUser(String user);
489     
490     /***
491      * Return a link to a desired page for the user
492      *
493      * @param page Desired page
494      * @param user Desired user
495      * @return DynamicURI that to the desired page
496      *
497      * @deprecated use getUser()
498      */
499     public DynamicURI setUser(String user, String page);
500     
501     /***
502      * Return a URL, as a string, the the root page or pane.
503      *
504      * @return a URL, as a string, the the root page or pane.
505      */
506     public String toString();
507     
508     /***
509      * Return a link to a specific pane using the pane's id
510      *
511      * @param paneId of the Pane
512      * @return URI to specific portlet
513      * @deprecated Use getPaneById()
514      */
515     public DynamicURI setPaneById(String paneId);
516             
517     /***
518      * Return a link to a specific pane using the pane's id
519      *
520      * @param paneId of the Pane
521      * @return URI to specific portlet
522      */
523     public DynamicURI getPaneById(String paneId);
524     
525     /***
526      * Return a link to a specific pane using the pane's id
527      *
528      * @param paneName Name of the Pane
529      * @return URI to specific portlet
530      */
531     public DynamicURI getPaneByName(String paneName);
532 
533     /***
534      * depreceted methods from JetspeedTemplateLink.
535      */
536     
537     /***
538      * <p> Set the portlet giving context to this Link object.</p>
539      *
540      * This method is from JetspeedTemplateLink and is only here
541      * for backward compatibility. This it should not be used for
542      * any new development.  Also any problems with this method will
543      * not be fixed
544      *
545      * @param portlet the name of the active portlet
546      * @deprecated Use getLink() or getAction() or getPortletById() or getPortletByName().
547      */
548     public void setPortlet(Portlet portlet);
549     
550     /***
551      * Return a link to a desired page.  This is allows the inclusion of a Group/Role/User,
552      * page, template, action, media type, language, and country.
553      *
554      * @param rootType Type of root PSML docuument.  The should be one of the following:
555      *                 <dl>
556      *                   <dt>JetspeedLink.CURRENT</dt><dd>The link will retain the current Group/Role/User referance. rootValue is not used</dd>
557      *                   <dt>JetspeedLink.DEFAULT</dt><dd>Default Group, Role, or User. rootValue is not used</dd>
558      *                   <dt>JetspeedLink.GROUP</dt><dd>Link will be to a Group PSML.  rootValue is a Group Name</dd>
559      *                   <dt>JetspeedLink.ROLE</dt><dd>Link will be to a Role PSML.  rootValue is a Role Name</dd>
560      *                   <dt>JetspeedLink.USER</dt><dd>Link will be to a User PSML.  rootValue is a User Name</dd>
561      *                 </dl>
562      * @param rootValue  See description of rootType
563      * @param pageName  Name of page. null = default page
564      * @param elementType
565      *                 <dl>
566      *                   <dt>JetspeedLink.CURRENT</dt><dd>The link will retain the current Pane/Portlet referance. elementValue is not used</dd>
567      *                   <dt>JetspeedLink.DEFAULT</dt><dd>The link will NOT referance a pane or portlet. elementValue is not used</dd>
568      *                   <dt>JetspeedLink.PANE_ID</dt><dd>Link will be to a Pane using it's ID.  elementValue is a Pane's ID</dd>
569      *                   <dt>JetspeedLink.PANE_NAME</dt><dd>Link will be to a Pane using it's Name.  elementValue is a Pane's Name</dd>
570      *                   <dt>JetspeedLink.PORTLET_ID</dt><dd>Link will be to a Portlet using it's ID.  elementValue is a Portlet's ID</dd>
571      *                   <dt>JetspeedLink.PORTLET_NAME</dt><dd>Link will be to a Portlet using it's Name.  elementValue is a Portlet's Name</dd>
572      *                 </dl>
573      * @param elementValue  See description of elementType
574      * @param actionName Name of action. If no action is desired use JetspeedLink.NO_ACTION.
575      * @param templateName Name of template. If no template is desired use JetspeedLink.NO_TEMPLATE.
576      * @param mediaType Desired media type. null = default media type
577      * @param language Desired language. null = default language
578      * @param country Desired country.  null = default language
579      * @return  URI to specific portlet
580      */    
581     public DynamicURI getLink(int rootType, String rootValue, String pageName, int elementType, String elementValue, String actionName, String templateName, String mediaType, String language, String country);
582     /***
583      * @see # org.apache.jetspeed.util.template.JetspeedLink.getLink( int, String, String, int, String, String, String, String, String, String
584      */    
585     public DynamicURI getLink(int rootType, String rootValue, String pageName, int elementType, String elementValue, String actionName, String templateName, String mediaType, String language);
586     public DynamicURI getLink(int rootType, String rootValue, String pageName, int elementType, String elementValue, String actionName, String templateName, String mediaType);
587     public DynamicURI getLink(int rootType, String rootValue, String pageName, int elementType, String elementValue, String actionName, String templateName);
588     public DynamicURI getLink(int rootType, String rootValue, String pageName, int elementType, String elementValue, String actionName);
589     public DynamicURI getLink(int rootType, String rootValue, String pageName, int elementType, String elementValue);
590     
591 }