1 /**
2 * Copyright (c) 2011, University of Konstanz, Distributed Systems Group
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 * * Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * * Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 * * Neither the name of the University of Konstanz nor the
13 * names of its contributors may be used to endorse or promote products
14 * derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19 * DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
20 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27 package org.jaxrx;
28
29 import java.io.InputStream;
30 import java.util.Set;
31 import javax.ws.rs.core.StreamingOutput;
32 import org.jaxrx.core.JaxRxException;
33 import org.jaxrx.core.QueryParameter;
34 import org.jaxrx.core.ResourcePath;
35
36 /**
37 * This interface assembles all interface methods for the GET, POST, PUT and
38 * DELETE requests. [...]
39 *
40 * @author Sebastian Graf, Christian Gruen, Lukas Lewandowski, University of
41 * Konstanz
42 *
43 */
44 public interface JaxRx {
45 /**
46 * This method returns all query parameters which are supported by the
47 * implementation.
48 *
49 * @return The {@link Set} containing the allowed parameters specified in
50 * {@link QueryParameter}.
51 */
52 Set<QueryParameter> getParameters();
53
54 /**
55 * This method is called by the GET and the POST method, if
56 * {@link QueryParameter#COMMAND} was specified in the HTTP request. This
57 * method performs a database command, based on the given resource path.
58 *
59 * @param command
60 * The command to be executed
61 * @param path
62 * Resource and parameter info
63 * @return The {@link StreamingOutput} containing the query output.
64 * @throws JaxRxException
65 * thrown if
66 * <ul>
67 * <li>the specified resource does not exist (code 404)</li>
68 * <li>the specified parameters are invalid or the command
69 * execution yields errors (code 400)</li>
70 * <li>an unexpected exception occurs (code 500)</li>
71 * </ul>
72 */
73 StreamingOutput command(final String command, final ResourcePath path)
74 throws JaxRxException;
75
76 /**
77 * This method is called by the GET and the POST method, if
78 * {@link QueryParameter#RUN} was specified in the HTTP request. This method
79 * runs a server-side query file, based on the given resource path.
80 *
81 * @param file
82 * The file to be run
83 * @param path
84 * Resource and parameter info
85 * @return The {@link StreamingOutput} containing the query output
86 * @throws JaxRxException
87 * thrown if
88 * <ul>
89 * <li>the specified resource or query file does not exist
90 * (status code: 404)</li>
91 * <li>the specified parameters are invalid or the command
92 * execution yields errors (status code: 400)</li>
93 * <li>an unexpected exception occurs (status code: 500)</li>
94 * </ul>
95 */
96 StreamingOutput run(final String file, final ResourcePath path)
97 throws JaxRxException;
98
99 /**
100 * This method is called by the GET and the POST method, if
101 * {@link QueryParameter#QUERY} was specified in the HTTP request. This
102 * method performs a query, based on the given resource path.
103 *
104 * @param query
105 * The query to be executed
106 * @param path
107 * Resource and parameter info
108 * @return The {@link StreamingOutput} containing the query output.
109 * @throws JaxRxException
110 * thrown if
111 * <ul>
112 * <li>the specified resource does not exist (status code: 404)</li>
113 * <li>the specified parameters are invalid or the query
114 * execution yields errors (status code: 400)</li>
115 * <li>an unexpected exception occurs (status code: 500)</li>
116 * </ul>
117 */
118 StreamingOutput query(final String query, final ResourcePath path)
119 throws JaxRxException;
120
121 /**
122 * This method is called by the GET and the POST method. The specified
123 * resource is returned. If no resource is specified, the root is returned,
124 * which can e.g. comprise a list of all resources.
125 *
126 * @param path
127 * Resource and parameter info
128 * @return The {@link StreamingOutput} containing the query output.
129 * @throws JaxRxException
130 * thrown if
131 * <ul>
132 * <li>the specified resource does not exist (status code: 404)</li>
133 * <li>an unexpected exception occurs (status code: 500)</li>
134 * </ul>
135 */
136 StreamingOutput get(final ResourcePath path) throws JaxRxException;
137
138 /**
139 * This method is called by the POST method. A new resource is added to the
140 * specified resource path.
141 *
142 * @param input
143 * The object containing the new content.
144 * @param path
145 * Resource and parameter info
146 * @return info message
147 * @throws JaxRxException
148 * thrown if
149 * <ul>
150 * <li>the specified resource does not exist (status code: 404)</li>
151 * <li>if the input is invalid (status code: 400)</li>
152 * <li>an unexpected exception occurs (status code: 500)</li>
153 * </ul>
154 */
155 String add(final InputStream input, final ResourcePath path)
156 throws JaxRxException;
157
158 /**
159 * This method is called by the PUT method. A new resource is created at the
160 * specified resource path. If the resource already exists, it is replaced
161 * by the new resource.
162 *
163 * @param input
164 * The incoming {@link InputStream}.
165 * @param path
166 * Resource and parameter info
167 * @return info message
168 * @throws JaxRxException
169 * thrown if
170 * <ul>
171 * <li>the input was invalid (status code: 400)</li>
172 * <li>an unexpected exception occurred (status code: 500)</li>
173 * </ul>
174 */
175 String update(final InputStream input, final ResourcePath path)
176 throws JaxRxException;
177
178 /**
179 * This method is called by the DELETE method. An existing resource is
180 * deleted, which is specified by the resource path.
181 *
182 * @param path
183 * Resource and parameter info
184 * @return info message
185 * @throws JaxRxException
186 * thrown if
187 * <ul>
188 * <li>the resource was not found (status code: 404)</li>
189 * <li>an unexpected exception occurred (status code: 500)</li>
190 * </ul>
191 */
192 String delete(final ResourcePath path) throws JaxRxException;
193 }