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  /* 
18  
19   */
20  
21  package org.apache.wsrp4j.producer.provider;
22  
23  import oasis.names.tc.wsrp.v1.types.PortletContext;
24  import oasis.names.tc.wsrp.v1.types.RuntimeContext;
25  import oasis.names.tc.wsrp.v1.types.UserContext;
26  
27  /**
28   * <p>This interface provides methods generating URLs or namespacing
29   * tokens that should be called within the getMarkup method of a service.</p>
30   * <p>There are two kinds of methods:
31   * <ul>
32   *   <li>Methods defining URLs or tokens to be rewritten by the consumer.</li>
33   *   <li>Methods defining complete URLs or namespaced tokens according to the
34   *       templates delivered by the Consumer.</li>
35   * </p> 
36   *
37   * @author <a href="mailto:stefan.behl@de.ibm.com">Stefan Behl</a>
38   * @author <a href="mailto:stephan.laertz@de.ibm.com">Stephan Laertz</a>
39   */
40  public interface URLComposer {
41  
42      // create URLs that have to be rewritten by the consumer
43  
44      /**
45       * Creates an complete parameter string for a blocking action link. Depended on
46       * the passed <code>RuntimeContext</code> and appearance of a non-null
47       * (secure)blockingaction or (secure)default template the url are either furnished with embracing rewrite 
48       * tokens or not. 
49       * Passing a null value for any of the provided parameters implicates that
50       * these url-parameters will not be included in the resulting url.
51       * Passing a null RuntimeContext or a RuntimeContext with a null blockingAction
52       * and default templates implicates the generation of url's which need to be rewritten at the 
53       * consumer side. Otherwise the consumers template is used to generate the urls.
54       * If a <code>UserContext</code> and/or <code>PortletContext</code> is also passed
55       * then the portlethandle and userContextKey from these strutures is used to make
56       * the produce url specific to that values. 
57       *    
58       * @param  portletMode       The portlet mode to be inserted into the parameter
59       *                           string of the url.
60       * @param  navigationalState The navigational state to be inserted into the
61       *                           parameter string of the url.
62       * @param  interactionState  The interaction state to be inserted into the
63       *                           parameter string of the url.
64       * @param  windowState       The window State to be inserted into the parameter
65       *                           string of the url.
66       * @param  secureURL         Boolean flag indicating if secure
67       *                           communications should be used when activating
68       *                           the link.
69       * 
70       * @param  runtimeContext    The <code>RuntimeContext</code> object from the
71       *                            wsrp request. Passing a null results in url's wich
72       *                            require consumer rewriting.
73       * @param portletContext     If a portlet context is passed with a valid portlet handle
74       *                            then this handle is used to be inserted in the url only
75       *                            if the runtimecontext contained a valid blockingAction or default template.
76       **/
77      public String createBlockingActionURL(String portletMode,
78              String navigationalState, String interactionState,
79              String windowState, boolean secureURL,
80              RuntimeContext runtimeContext, PortletContext portletContext,
81              UserContext userContext);
82  
83      /**
84       * Creates an complete parameter string for a render link. Depended on
85       * the passed <code>RuntimeContext</code> and appearance of a non-null
86       * render or default template the url are either furnished with embracing rewrite 
87       * tokens or not. 
88       * Passing a null value for any of the provided parameters implicates that
89       * these url-parameters will not be included in the resulting url.
90       * Passing a null RuntimeContext or a RuntimeContext with a null render and default
91       * templates implicates the generation of url's which need to be rewritten at the 
92       * consumer side. Otherwise the consumers template is used to generate the urls.
93       * If a <code>UserContext</code> and/or <code>PortletContext</code> is also passed
94       * then the portlethandle and userContextKey from these strutures is used to make
95       * the produce url specific to that values. 
96       *    
97       * @param  portletMode       The portlet mode to be inserted into the parameter
98       *                           string of the url.
99       * @param  navigationalState The navigational state to be inserted into the
100      *                           parameter string of the url.
101      * @param  windowState       The window State to be inserted into the parameter
102      *                           string of the url.
103      * @param  secureURL         Boolean flag indicating if secure
104      *                           communications should be used when activating
105      *                           the link.
106      * 
107      * @param  runtimeContext    The <code>RuntimeContext</code> object from the
108      *                            wsrp request. Passing a null results in url's wich
109      *                            require consumer rewriting.
110      * @param portletContext     If a portlet context is passed with a valid portlet handle
111      *                            then this handle is used to be inserted in the url only
112      *                            if the runtimecontext contained a valid render or default template.
113      **/
114     public String createRenderURL(String portletMode, String navigationalState,
115             String windowState, boolean secureURL,
116             RuntimeContext runtimeContext, PortletContext portletContext,
117             UserContext userContext);
118 
119     /**
120      * Creates an complete parameter string for a resource link. Depended on
121      * the passed <code>RuntimeContext</code> and appearance of a non-null
122      * render or default template the url are either furnished with embracing rewrite 
123      * tokens or not. 
124      * Passing a null value for any of the provided parameters implicates that
125      * these url-parameters will not be included in the resulting url.
126      * Passing a null RuntimeContext or a RuntimeContext with a null render and default
127      * templates implicates the generation of url's which need to be rewritten at the 
128      * consumer side. Otherwise the consumers template is used to generate the urls.
129      * If a <code>UserContext</code> and/or <code>PortletContext</code> is also passed
130      * then the portlethandle and userContextKey from these strutures is used to make
131      * the produce url specific to that values.
132      *
133      * @param  url               Provides the actual url to the resource.
134      * @param  rewriteResource   Boolean flag informing the Consumer that the
135      *                           resource needs to be parsed for URL rewriting.
136      * @param  secureURL         Boolean flag indicating whether secure
137      *                           communications should be used when activating
138      *                           the link.
139      * @param  runtimeContext    The <code>RuntimeContext</code> object from the
140      *                            wsrp request. Passing a null results in url's wich
141      *                            require consumer rewriting.
142      * @param portletContext     If a portlet context is passed with a valid portlet handle
143      *                            then this handle is used to be inserted in the url only
144      *                            if the runtimecontext contained a valid resource or default template.
145      **/
146     public String createResourceURL(String url, boolean rewriteResource,
147             boolean secureURL, RuntimeContext runtimeContext,
148             PortletContext portletContext, UserContext userContext);
149 
150     /**
151      * Marks a token that has to be namespaced by the consumer.
152      * If a <code>RuntimeContext</code> with a non-null namespace prefix
153      * attributed is passed then this prefix is used to namespace the given token.
154      * Passing a null RuntimeContext results in a namespace url that requires consumer
155      * rewriting. 
156      *
157      * @param  token Token to be namespaced.
158      * @param  runtimeContext A <code>RuntimeContext</code> with a valid namespaceprefix or null.
159      */
160     public String createNamespacedToken(String token,
161             RuntimeContext runtimeContext);
162 }