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.*;
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 {@link RestMethod#converters()} annotation.
*
*
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()} 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, ClassMeta)} and return back a
* 'converted' object.
* It's up to the implementer to decide what this means.
*
*
* Converters must implement a no-args constructor.
*
*
Predefined converters
*
* The following converters are available by default.
*
* -
* {@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.
*
*/
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.
* @param cm
* The {@link ClassMeta} on the object from the bean context of the servlet.
* Can be used to check if the object has any filters.
* @return The converted object.
* @throws RestException Thrown if any errors occur during conversion.
* @throws SerializeException
*/
public Object convert(RestRequest req, Object res, ClassMeta cm) throws RestException, SerializeException;
}