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.consumer;
22  
23  import oasis.names.tc.wsrp.v1.intf.WSRP_v1_PortletManagement_PortType;
24  import oasis.names.tc.wsrp.v1.intf.WSRP_v1_Registration_PortType;
25  import oasis.names.tc.wsrp.v1.intf.WSRP_v1_ServiceDescription_PortType;
26  import oasis.names.tc.wsrp.v1.types.PortletDescription;
27  import oasis.names.tc.wsrp.v1.types.RegistrationContext;
28  import oasis.names.tc.wsrp.v1.types.RegistrationData;
29  import oasis.names.tc.wsrp.v1.types.RegistrationState;
30  import oasis.names.tc.wsrp.v1.types.ReturnAny;
31  import oasis.names.tc.wsrp.v1.types.ServiceDescription;
32  
33  import org.apache.wsrp4j.exception.WSRPException;
34  
35  /**
36   * A consumer representation of a WSRP-producer providing WSRP-portlets.
37   * Generally a producer can expose up to four WSRP-Interfaces. These interfaces are 
38   * Markup-, Service Description-,Registration- and Portlet Management Interface. Whereas
39   * the Registration- and Portlet Management Interface are optional.
40   * 
41   * @author Stephan Laertz
42   **/
43  public interface Producer {
44  
45      /**
46       * Get the name of the producer.               
47       *
48       * @return The name of the producer
49       **/
50      public String getName();
51  
52      /**
53       * Set the name of the producer.
54       *
55       * @param name The name of the producer     
56       **/
57      public void setName(String name);
58  
59      /**
60       * Get the ID of the producer.
61       * 
62       * @return The ID of the producer
63       **/
64      public String getID();
65  
66      /**
67       * Set the ID of the producer to he given value.
68       * 
69       * @param id ID of the producer.
70       **/
71      public void setID(String id);
72  
73      /**
74       * Get a description of the producer.
75       *
76       * @return A description of the producer
77       **/
78      public String getDescription();
79  
80      /**
81       * Set a description of the producer.
82       *
83       * @param description Some descriptive information about the producer    
84       **/
85      public void setDescription(String description);
86  
87      /**
88       * Get the URL of the producers service description interface.
89       *
90       * @return URL of the service description interface.
91       **/
92      public String getServiceDescriptionInterfaceEndpoint();
93  
94      /**
95       * Set the URL of the producers service description interface.
96       *
97       * @param url of the service description interface.
98       **/
99      public void setServiceDescriptionInterfaceEndpoint(String url);
100 
101     /**
102      * Get the producers service description interface.
103      *
104      * @return service description interface.
105      **/
106     public WSRP_v1_ServiceDescription_PortType getServiceDescriptionInterface();
107 
108     /**
109      * Get the URL of the producers markup interface.
110      *
111      * @return URL of the markup interface.
112      **/
113     public String getMarkupInterfaceEndpoint();
114 
115     /**
116      * Set the URL of the producers markup interface.
117      *
118      * @param url of the markup interface.
119      **/
120     public void setMarkupInterfaceEndpoint(String url);
121 
122     /**
123      * Get the URL of the producers portlet management interface.
124      *
125      * @return URL of the portlet management interface.
126      **/
127     public String getPortletManagementInterfaceEndpoint();
128 
129     /**
130      * Set the URL of the producers portlet management interface.
131      *
132      * @param url of the portlet management interface.
133      **/
134     public void setPortletManagementInterfaceEndpoint(String url);
135 
136     /**
137      * Get the producers portlet management interface.
138      *
139      * @return portlet management interface.
140      **/
141     public WSRP_v1_PortletManagement_PortType getPortletManagementInterface();
142 
143     /**
144      * Get the URL of the producers registration interface.
145      *
146      * @return URL of the registration interface.
147      **/
148     public String getRegistrationInterfaceEndpoint();
149 
150     /**
151      * Set the URL of the producers registration interface.
152      *
153      * @param url of the registration interface.
154      **/
155     public void setRegistrationInterfaceEndpoint(String url);
156 
157     /**
158      * Get the producers registration interface.
159      *
160      * @return registration interface.
161      **/
162     public WSRP_v1_Registration_PortType getRegistrationInterface();
163 
164     /**
165      * Indicates wether or not the producer requires consumer registration.
166      *
167      * @return True if consumer registration is required.
168      **/
169     public boolean isRegistrationRequired();
170 
171     /**
172      * Define if the producer requires in-band registration or not.
173      * 
174      * @param registrationRequired True if the producer requires in-band registration
175      **/
176     public void setIsRegistrationRequired(boolean registrationRequired);
177 
178     /**
179      * Get the registration data the consumer uses to register at this producer.
180      * 
181      * @return The consumer registration data
182      **/
183     public RegistrationData getRegistrationData();
184 
185     /**
186      * Set the registration the consumer uses the register at this producer.
187      * 
188      * @param regData The registration data which is used to register at this producer
189      **/
190     public void setRegistrationData(RegistrationData regData);
191 
192     /**
193      * Get the service description of the producer
194      * 
195      * @param newRequest If set to true a new request is send to the producer otherwise a cached service description
196      * is used if available
197      * 
198      * @return Service description of the producer
199      **/
200     public ServiceDescription getServiceDescription(boolean newRequest)
201             throws WSRPException;
202 
203     /**
204      * Same as getServiceDescription(false)
205      **/
206     public ServiceDescription getServiceDescription() throws WSRPException;
207 
208     /**
209      * Get the portlet description of the portlet with the given handle or 
210      * null if the producer doesn't know an portlet with this handle.
211      * 
212      * @param portletHandle The portlet handle of the portlet
213      * 
214      * @return The portlet description of the portlet with the given handle
215      **/
216     public PortletDescription getPortletDescription(String portletHandle)
217             throws WSRPException;
218 
219     /**
220      * Add an portlet description to the producer. This portlet description is
221      * accessable through the portlet handle in the portlet description. If the
222      * producer has already an portlet description with this portlet handle than
223      * the old description will be overwritten.
224      * 
225      * @param portletDescription New portlet description 
226      **/
227     public void addPortletDescription(PortletDescription portletDescription);
228 
229     /**
230      * Get the current registration context of the consumer registered at this producer or null
231      * if no registration is required or happend so far.
232      * 
233      * @return The current registration context of the consumer at this producer or null.
234      **/
235     public RegistrationContext getRegistrationContext();
236 
237     /**
238      * Set the registration context.
239      * 
240      * @param registrationContext The registration context of a consumer registered at the producer.
241      **/
242     public void setRegistrationContext(RegistrationContext registrationContext);
243 
244     /**
245      * Method establishes a relationship between consumer and producer.
246      * 
247      * Note: A additional call of setRegistrationContext() is not neccesary 
248      *      
249      * @param registrationData Data which is used to register the consumer     
250      * 
251      * @return The registration context received by the producer      
252      **/
253     public RegistrationContext register(RegistrationData registrationData)
254             throws WSRPException;
255 
256     /**
257      * Can be used to modify the relationship between consumer and producer.
258      * 
259      * Note: A additional call of setRegistrationContext() is not neccesary
260      *     
261      * @param registrationData The new registration data                 
262      * 
263      * @return New registration context     
264      **/
265     public RegistrationState modifyRegistration(
266             RegistrationData registrationData) throws WSRPException;
267 
268     /**
269      * End an existing consumer producer relationship and remove the registration context        
270      * 
271      * @return Can be anything
272      **/
273     public ReturnAny deregister() throws WSRPException;
274 
275     /**
276      * Check wether the optional registration interface is supported
277      *
278      * @return true if a registration interface endpoint URL is set
279      */
280     public boolean isRegistrationInterfaceSupported();
281 
282     /**
283      * Check wether the optional portlet management interface is supported
284      *
285      * @return true if a portlet management interface endpoint URL is set
286      */
287     public boolean isPortletManagementInferfaceSupported();
288 
289 }