View Javadoc

1   /*
2    * Copyright (C) 2017-2019 Centre National d'Etudes Spatiales (CNES).
3    *
4    * This library is free software; you can redistribute it and/or
5    * modify it under the terms of the GNU Lesser General Public
6    * License as published by the Free Software Foundation; either
7    * version 3.0 of the License, or (at your option) any later version.
8    *
9    * This library is distributed in the hope that it will be useful,
10   * but WITHOUT ANY WARRANTY; without even the implied warranty of
11   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12   * Lesser General Public License for more details.
13   *
14   * You should have received a copy of the GNU Lesser General Public
15   * License along with this library; if not, write to the Free Software
16   * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
17   * MA 02110-1301  USA
18   */
19  package fr.cnes.doi.resource;
20  
21  import fr.cnes.doi.application.AbstractApplication;
22  import fr.cnes.doi.utils.spec.Requirement;
23  import java.util.List;
24  import org.apache.logging.log4j.Logger;
25  import org.restlet.data.Form;
26  import org.restlet.data.MediaType;
27  import org.restlet.data.Status;
28  import org.restlet.ext.wadl.DocumentationInfo;
29  import org.restlet.ext.wadl.MethodInfo;
30  import org.restlet.ext.wadl.ParameterInfo;
31  import org.restlet.ext.wadl.ParameterStyle;
32  import org.restlet.ext.wadl.RepresentationInfo;
33  import org.restlet.ext.wadl.RequestInfo;
34  import org.restlet.ext.wadl.ResponseInfo;
35  import org.restlet.ext.wadl.WadlServerResource;
36  import org.restlet.resource.ResourceException;
37  
38  /**
39   * Abstract resource.
40   *
41   * Each resource must extend from this abstract class. This abstract class
42   * allows the WADL description.
43   *
44   * @author Jean-Christophe Malapert (jean-christophe.malapert@cnes.fr)
45   * @see <a href="https://www.w3.org/Submission/wadl/">WADL</a>
46   */
47  @Requirement(reqId = Requirement.DOI_DOC_010, reqName = Requirement.DOI_DOC_010_NAME)
48  public abstract class AbstractResource extends WadlServerResource {
49  
50      /**
51       * Logger.
52       */
53      private volatile Logger LOG;
54  
55      /**
56       * Init
57       *
58       * @throws ResourceException When an Exception happens
59       */
60      @Override
61      protected void doInit() throws ResourceException {
62          super.doInit();
63          this.LOG = ((AbstractApplication) getApplication()).getLog();
64      }
65  
66      /**
67       * Tests if the form is not null and the parameter exists in the form.
68       *
69       * @param form submitted form
70       * @param parameterName parameter name in the form
71       * @return True when the form is not null and the parameter exists in the
72       * form otherwise False
73       */
74      public boolean isValueExist(final Form form,
75              final String parameterName) {
76          LOG.traceEntry("Parameters : {} and {}", form, parameterName);
77          final boolean result;
78          if (isObjectNotExist(form)) {
79              result = false;
80          } else {
81              result = form.getFirstValue(parameterName) != null;
82          }
83          return LOG.traceExit(result);
84      }
85  
86      /**
87       * The opposite of {@link #isValueExist}
88       *
89       * @param form submitted form
90       * @param parameterName parameter name
91       * @return False when the form is not null and the parameter exists in the
92       * form otherwise True
93       */
94      public boolean isValueNotExist(final Form form,
95              final String parameterName) {
96          LOG.traceEntry("Parameters : {} and {}", form, parameterName);
97          return LOG.traceExit(!isValueExist(form, parameterName));
98      }
99  
100     /**
101      * Test if an object is null.
102      *
103      * @param obj object to test
104      * @return True when the object is not null otherwise False
105      */
106     public boolean isObjectExist(final Object obj) {
107         LOG.traceEntry("Parameter : {}", obj);
108         return LOG.traceExit(obj != null);
109     }
110 
111     /**
112      * Test if an object is not null.
113      *
114      * @param obj object to test
115      * @return True when the object is null otherwise False
116      */
117     public boolean isObjectNotExist(final Object obj) {
118         LOG.traceEntry("Parameter : {}", obj);
119         return LOG.traceExit(!isObjectExist(obj));
120     }
121 
122     /**
123      * Adds Wadl description of the request to a method.
124      *
125      * @param info method description
126      * @param param Request parameters
127      */
128     protected void addRequestDocToMethod(final MethodInfo info,
129             final ParameterInfo param) {
130         final RequestInfo request = new RequestInfo();
131         request.getParameters().add(param);
132         info.setRequest(request);
133     }
134 
135     /**
136      * Adds Wadl description of the request to the method.
137      *
138      * @param info Method description
139      * @param params Request parameters
140      */
141     protected void addRequestDocToMethod(final MethodInfo info,
142             final List<ParameterInfo> params) {
143         final RequestInfo request = new RequestInfo();
144         for (final ParameterInfo param : params) {
145             request.getParameters().add(param);
146         }
147         info.setRequest(request);
148     }
149 
150     /**
151      * Adds Wadl description of the request to the method.
152      *
153      * @param info Method description
154      * @param params Request parameters
155      * @param rep Representation entity of the request
156      */
157     protected void addRequestDocToMethod(
158             final MethodInfo info,
159             final List<ParameterInfo> params,
160             final RepresentationInfo rep) {
161         addRequestDocToMethod(info, params);
162         info.getRequest().getRepresentations().add(rep);
163     }
164 
165     /**
166      * Adds Wadl description of the response to a method.
167      *
168      * @param info Method description
169      * @param response Response description
170      */
171     protected void addResponseDocToMethod(final MethodInfo info,
172             final ResponseInfo response) {
173         info.getResponses().add(response);
174     }
175 
176     /**
177      * Creates a textual explanation of the response for a given status.
178      *
179      * @param status HTTP Status
180      * @param doc textual explanation
181      * @return Response Wadl description
182      */
183     protected ResponseInfo createResponseDoc(final Status status,
184             final String doc) {
185         final ResponseInfo responseInfo = new ResponseInfo();
186         responseInfo.getStatuses().add(status);
187         responseInfo.setDocumentation(doc);
188         return responseInfo;
189     }
190 
191     /**
192      * Creates a textual explanation of the response for a given status.
193      *
194      * @param status HTTP status
195      * @param doc textual explanation
196      * @param refRepresentation reference to the representation of the response
197      * @return the response Wadl description
198      */
199     protected ResponseInfo createResponseDoc(
200             final Status status,
201             final String doc,
202             final String refRepresentation) {
203         final ResponseInfo response = createResponseDoc(status, doc);
204         final RepresentationInfo rep = new RepresentationInfo();
205         rep.setReference(refRepresentation);
206         response.getRepresentations().add(rep);
207         return response;
208     }
209 
210     /**
211      * Creates a textual explanation of the response for a given status.
212      *
213      * @param status HTTP status
214      * @param doc textual description
215      * @param representation Representation of the response
216      * @return the response Wadl description
217      */
218     protected ResponseInfo createResponseDoc(
219             final Status status,
220             final String doc,
221             final RepresentationInfo representation) {
222         final ResponseInfo response = createResponseDoc(status, doc);
223         response.getRepresentations().add(representation);
224         return response;
225     }
226 
227     /**
228      * Creates a query parameter.
229      *
230      * @param name query parameter name
231      * @param style Style (header, template, ...)
232      * @param doc textual description
233      * @param isRequired optional or required
234      * @param datatype data type
235      * @return the query Wadl description
236      */
237     protected ParameterInfo createQueryParamDoc(
238             final String name,
239             final ParameterStyle style,
240             final String doc,
241             final boolean isRequired,
242             final String datatype) {
243         final ParameterInfo param = new ParameterInfo();
244         param.setName(name);
245         param.setStyle(style);
246         param.setDocumentation(doc);
247         param.setRequired(isRequired);
248         param.setType(datatype);
249         return param;
250     }
251 
252     /**
253      * Creates query representation.
254      *
255      * @param identifier representation identifier
256      * @param mediaType media type
257      * @param doc textual description
258      * @param xmlElement XML element of the schema
259      * @return Wadl element for the representation
260      */
261     protected RepresentationInfo createQueryRepresentationDoc(
262             final String identifier,
263             final MediaType mediaType,
264             final String doc,
265             final String xmlElement) {
266         final RepresentationInfo rep = new RepresentationInfo();
267         rep.setIdentifier(identifier);
268         rep.setMediaType(mediaType);
269         rep.setDocumentation(doc);
270         rep.setXmlElement(xmlElement);
271         return rep;
272     }
273 
274     /**
275      * projects representation
276      *
277      * @return Wadl representation for projects
278      */
279     protected RepresentationInfo stringRepresentation() {
280         final RepresentationInfo repInfo = new RepresentationInfo();
281         repInfo.setMediaType(MediaType.TEXT_PLAIN);
282         final DocumentationInfo docInfo = new DocumentationInfo();
283         docInfo.setTitle("String Representation");
284         docInfo.setTextContent("The representation contains a simple string.");
285         repInfo.setDocumentation(docInfo);
286         return repInfo;
287     }
288 
289     /**
290      * projects representation
291      *
292      * @return Wadl representation for projects
293      */
294     protected RepresentationInfo htmlRepresentation() {
295         final RepresentationInfo repInfo = new RepresentationInfo();
296         repInfo.setMediaType(MediaType.TEXT_HTML);
297         final DocumentationInfo docInfo = new DocumentationInfo();
298         docInfo.setTitle("HTML Representation");
299         docInfo.setTextContent("The representation contains the HTML representation.");
300         repInfo.setDocumentation(docInfo);
301         return repInfo;
302     }
303 
304 }