org.apache.juneau.rest.RestConverter Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
// * with the License. You may obtain a copy of the License at *
// * *
// * http://www.apache.org/licenses/LICENSE-2.0 *
// * *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
// * specific language governing permissions and limitations under the License. *
// ***************************************************************************************************************************
package org.apache.juneau.rest;
import org.apache.juneau.rest.annotation.*;
import org.apache.juneau.rest.converters.*;
import org.apache.juneau.serializer.*;
/**
* REST method response converter.
*
*
* Implements a filter mechanism for REST method calls that allows response objects to be converted to some other POJO
* after invocation of the REST method.
*
*
* Converters are associated with REST methods through the following:
*
* - {@link RestResource#converters()}
*
- {@link RestMethod#converters()}
*
- {@link RestContext#REST_converters}
*
- {@link RestContextBuilder#converters(Class...)}
*
- {@link RestContextBuilder#converters(RestConverter...)}
*
*
* Example:
*
* public class RequestEchoResource extends RestServlet {
*
* // GET request handler
* @RestMethod (name=GET , path="/*" , converters={Queryable.class ,Traversable.class })
* public HttpServletRequest doGet(RestRequest req) {
* res.setTitle("Contents of HttpServletRequest object" );
* return req;
* }
* }
*
*
*
* Converters can also be associated at the servlet level using the {@link RestResource#converters() @RestResource(converters)} annotation.
*
Applying converters at the resource level is equivalent to applying converters to each resource method individually.
*
*
How to implement
*
* Implementers should simply implement the {@link #convert(RestRequest, Object)} and return back a 'converted' object.
*
It's up to the implementer to decide what this means.
*
*
* Subclasses must implement one of the following constructors:
*
* public T(); // No-arg constructor
* public T(PropertyStore); // Property store of the RestContext
*
*
*
* Subclasses can also be defined as inner classes of the resource class.
*
*
Predefined converters
*
* - {@link Traversable} - Allows URL additional path info to address individual elements in a POJO tree.
*
- {@link Queryable} - Allows query/view/sort functions to be performed on POJOs.
*
- {@link Introspectable} - Allows Java public methods to be invoked on the returned POJOs.
*
*
* See Also:
*
* - {@link RestContext#REST_converters} - Registering converters with REST resources.
*
- {@doc juneau-rest-server.Converters}
*
*/
public interface RestConverter {
/**
* Performs post-call conversion on the specified response object.
*
* @param req The servlet request.
* @param res The response object set by the REST method through the {@link RestResponse#setOutput(Object)} method.
* @return The converted object.
* @throws RestException Thrown if any errors occur during conversion.
* @throws SerializeException
*/
public Object convert(RestRequest req, Object res) throws RestException, SerializeException;
}