View Javadoc

1   /* This file is part of COPAL (COntext Provisioning for All).
2    *
3    * COPAL is a part of SM4All (Smart hoMes for All) project.
4    *
5    * COPAL is free software: you can redistribute it and/or modify
6    * it under the terms of the GNU Lesser General Public License as published by
7    * the Free Software Foundation, either version 3 of the License, or
8    * (at your option) any later version.
9    *
10   * COPAL is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13   * GNU Lesser General Public License for more details.
14   *
15   * You should have received a copy of the GNU Lesser General Public License
16   * along with COPAL. If not, see <http://www.gnu.org/licenses/>.
17   */
18  package at.ac.tuwien.infosys.sm4all.copal.rest;
19  
20  import java.net.URI;
21  import javax.ws.rs.DELETE;
22  import javax.ws.rs.GET;
23  import javax.ws.rs.POST;
24  import javax.ws.rs.PUT;
25  import javax.ws.rs.Path;
26  import javax.ws.rs.PathParam;
27  import javax.ws.rs.core.Context;
28  import javax.ws.rs.core.Response;
29  import javax.ws.rs.core.UriInfo;
30  import at.ac.tuwien.infosys.sm4all.copal.api.event.XMLContextEventType;
31  import at.ac.tuwien.infosys.sm4all.copal.api.listener.ContextListener;
32  import at.ac.tuwien.infosys.sm4all.copal.api.processor.ContextProcessor;
33  import at.ac.tuwien.infosys.sm4all.copal.api.publisher.ContextPublisher;
34  import at.ac.tuwien.infosys.sm4all.copal.api.query.ContextQuery;
35  import at.ac.tuwien.infosys.sm4all.copal.api.query.ProcessedEventQuery;
36  import at.ac.tuwien.infosys.sm4all.copal.rest.model.Event;
37  import at.ac.tuwien.infosys.sm4all.copal.rest.model.RESTfulListener;
38  import at.ac.tuwien.infosys.sm4all.copal.rest.model.RESTfulPublisher;
39  
40  /**
41   * Interface for COPAL REST service.
42   * 
43   * @author sanjin
44   */
45  public interface Service {
46  
47      /**
48       * Returns a {@link Response} with all registered
49       * {@link XMLContextEventType}s.
50       * 
51       * @return the {@link Response} with all registered
52       *         {@link XMLContextEventType}s.
53       */
54      @GET
55      @Path("events")
56      Response getEventTypes();
57  
58      /**
59       * Registers specified {@link XMLContextEventType}.
60       * 
61       * @param uriInfo the {@link UriInfo} to create {@link URI} to registered
62       *        {@link XMLContextEventType}.
63       * @param eventType the {@link XMLContextEventType}.
64       * @return the {@link Response}.
65       */
66      @PUT
67      @Path("events")
68      Response register(@Context UriInfo uriInfo, XMLContextEventType eventType);
69  
70      /**
71       * Returns a {@link Response} with registered {@link XMLContextEventType}
72       * that has specified name.
73       * 
74       * @param name the name of the {@link XMLContextEventType}.
75       * @return the {@link Response} with registered {@link XMLContextEventType}
76       *         with specified name.
77       */
78      @GET
79      @Path("events/{name}")
80      Response getEventType(@PathParam("name") String name);
81  
82      /**
83       * Unregisters specified {@link XMLContextEventType}.
84       * 
85       * @param name the name of the {@link XMLContextEventType}.
86       * @return the {@link Response} with unregistered
87       *         {@link XMLContextEventType}.
88       */
89      @DELETE
90      @Path("events/{name}")
91      Response unregisterEventType(@PathParam("name") String name);
92  
93      /**
94       * Returns a {@link Response} with all registered {@link ContextPublisher}s
95       * that publish events with specified name.
96       * 
97       * @param eventName the name of published events.
98       * @return the {@link Response} with all registered {@link ContextPublisher}
99       *         s that publish events with specified name.
100      */
101     @GET
102     @Path("events/{eventName}/publishers")
103     Response getPublishers(@PathParam("eventName") String eventName);
104 
105     /**
106      * Returns a {@link Response} with all registered {@link ContextProcessor}s
107      * that process events with specified name.
108      * 
109      * @param eventName the name of processed events.
110      * @return the {@link Response} with all registered {@link ContextProcessor}
111      *         s that process events with specified name.
112      */
113     @GET
114     @Path("events/{eventName}/processors")
115     Response getProcessors(@PathParam("eventName") String eventName);
116 
117     /**
118      * Returns a {@link Response} with all non-destroyed {@link ContextQuery}s
119      * that listen on events with specified name.
120      * 
121      * @param eventName the name of listened events.
122      * @return the {@link Response} with all registered {@link ContextQuery} s
123      *         that listen on events with specified name.
124      */
125     @GET
126     @Path("events/{eventName}/queries")
127     Response getQueries(@PathParam("eventName") String eventName);
128 
129     /**
130      * Returns a {@link Response} with all registered {@link ContextPublisher}s.
131      * 
132      * @return the {@link Response} with all registered {@link ContextPublisher}
133      *         s.
134      */
135     @GET
136     @Path("publishers")
137     Response getPublishers();
138 
139     /**
140      * Registers specified {@link RESTfulPublisher}.
141      * 
142      * @param uriInfo the {@link UriInfo} to create {@link URI} to registered
143      *        {@link RESTfulPublisher}.
144      * @param publisher the {@link RESTfulPublisher}.
145      * @return the {@link Response}.
146      */
147     @PUT
148     @Path("publishers")
149     Response register(@Context UriInfo uriInfo, RESTfulPublisher publisher);
150 
151     /**
152      * Returns a {@link Response} with registered {@link ContextPublisher} that
153      * has specified source ID.
154      * 
155      * @param sourceID the source ID of the {@link ContextPublisher}.
156      * @return the {@link Response} with registered {@link ContextPublisher}
157      *         with specified source ID.
158      */
159     @GET
160     @Path("publishers/{sourceID}")
161     Response getPublisher(@PathParam("sourceID") String sourceID);
162 
163     /**
164      * Publishes specified {@link Event} using a {@link RESTfulPublisher} that
165      * has specified source ID.
166      * 
167      * @param sourceID the source ID of the {@link RESTfulPublisher}.
168      * @param event the {@link Event} to be published.
169      * @return the {@link Response}.
170      */
171     @POST
172     @Path("publishers/{sourceID}")
173     Response publish(@PathParam("sourceID") String sourceID, Event event);
174 
175     /**
176      * Unregisters specified {@link RESTfulPublisher}.
177      * 
178      * @param sourceID the source ID of the {@link RESTfulPublisher}.
179      * @return the {@link Response} with unregistered {@link RESTfulPublisher}.
180      */
181     @DELETE
182     @Path("publishers/{sourceID}")
183     Response unregisterPublisher(@PathParam("sourceID") String sourceID);
184 
185     /**
186      * Returns a {@link Response} with all registered {@link ContextProcessor}s.
187      * 
188      * @return the {@link Response} with all registered {@link ContextProcessor}
189      *         s.
190      */
191     @GET
192     @Path("processors")
193     Response getProcessors();
194 
195     /**
196      * Returns a {@link Response} with registered {@link ContextProcessor} that
197      * has specified name.
198      * 
199      * @param name the name of the {@link ContextProcessor}.
200      * @return the {@link Response} with registered {@link ContextProcessor}
201      *         with specified name.
202      */
203     @GET
204     @Path("processors/{name}")
205     Response getProcessor(@PathParam("name") String name);
206 
207     /**
208      * Returns a {@link Response} with all non-destroyed {@link ContextQuery}s.
209      * 
210      * @return the {@link Response} with all non-destroyed {@link ContextQuery}
211      *         s.
212      */
213     @GET
214     @Path("queries")
215     Response getQueries();
216 
217     /**
218      * Creates specified {@link ProcessedEventQuery}.
219      * 
220      * @param uriInfo the {@link UriInfo} to create {@link URI} to registered
221      *        {@link ProcessedEventQuery}.
222      * @param query the {@link ProcessedEventQuery}.
223      * @return the {@link Response}.
224      */
225     @PUT
226     @Path("queries")
227     Response create(@Context UriInfo uriInfo, ProcessedEventQuery query);
228 
229     /**
230      * Returns a {@link Response} with non-destroyed {@link ContextQuery} that
231      * has specified name.
232      * 
233      * @param name the name of the {@link ContextQuery}.
234      * @return the {@link Response} with non-destroyed {@link ContextQuery} with
235      *         specified name.
236      */
237     @GET
238     @Path("queries/{name}")
239     Response getQuery(@PathParam("name") String name);
240 
241     /**
242      * Destroys specified {@link ContextQuery}.
243      * 
244      * @param name the name of {@link ContextQuery}.
245      * @return the {@link Response} with destroyed {@link ContextQuery}.
246      */
247     @DELETE
248     @Path("queries/{name}")
249     Response destroy(@PathParam("name") String name);
250 
251     /**
252      * Returns a {@link Response} with all {@link ContextListener}s that are
253      * registered with {@link ContextQuery} that has specified query name.
254      * 
255      * @param queryName the name of the {@link ContextQuery}.
256      * @return the {@link Response} with all {@link ContextListener}s that are
257      *         registered with {@link ContextQuery} that has specified name.
258      */
259     @GET
260     @Path("queries/{queryName}/listeners")
261     Response getListeners(@PathParam("queryName") String queryName);
262 
263     /**
264      * Registers specified {@link RESTfulListener} with {@link ContextQuery}
265      * that has specified query name.
266      * 
267      * @param uriInfo the {@link UriInfo} to create {@link URI} to registered
268      *        {@link RESTfulListener}.
269      * @param queryName the name of the {@link ContextQuery}.
270      * @param listener the {@link RESTfulListener}.
271      * @return the {@link Response}.
272      */
273     @PUT
274     @Path("queries/{name}/listeners")
275     Response register(@Context UriInfo uriInfo,
276             @PathParam("name") String queryName, RESTfulListener listener);
277 
278     /**
279      * Returns a {@link Response} with a {@link ContextListener} that has
280      * specified name and is registered with {@link ContextQuery} that has
281      * specified query name.
282      * 
283      * @param queryName the name of the {@link ContextQuery}.
284      * @param name the name of the {@link ContextListener}.
285      * @return the {@link Response} with the {@link ContextListener} that has
286      *         specified name and is registered with {@link ContextQuery} that
287      *         has specified query name.
288      */
289     @GET
290     @Path("queries/{queryName}/listeners/{name}")
291     Response getListener(@PathParam("queryName") String queryName,
292             @PathParam("name") String name);
293 
294     /**
295      * Unregisters specified {@link RESTfulListener} from {@link ContextQuery}
296      * that has specified query name.
297      * 
298      * @param queryName the name of the {@link ContextQuery}.
299      * @param name the name of the {@link ContextListener}.
300      * @return the {@link Response} with unregistered {@link RESTfulListener}.
301      */
302     @DELETE
303     @Path("queries/{queryName}/listeners/{name}")
304     Response unregisterListener(@PathParam("queryName") String queryName,
305             @PathParam("name") String name);
306 }