org.apache.juneau.rest.converter.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.converter;
import org.apache.juneau.http.response.*;
import org.apache.juneau.rest.*;
import org.apache.juneau.rest.annotation.*;
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 Rest#converters()}
*
- {@link RestOp#converters()}
*
- {@link org.apache.juneau.rest.RestOpContext.Builder#converters()}
*
*
* Example:
*
* public class RequestEchoResource extends BasicRestServlet {
*
* // GET request handler
* @RestGet (path="/*" , converters={Queryable.class ,Traversable.class })
* public HttpServletRequest doGet(RestRequest req , RestResponse res ) {
* res .setTitle("Contents of HttpServletRequest object" );
* return req ;
* }
* }
*
*
*
* Converters can also be associated at the servlet level using the {@link Rest#converters() @Rest(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(ContextProperties); // 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 org.apache.juneau.rest.RestOpContext.Builder#converters()}
*
- 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#setContent(Object)} method.
* @return The converted object.
* @throws BasicHttpException Thrown if any errors occur during conversion.
* @throws SerializeException Generic serialization error occurred.
*/
Object convert(RestRequest req, Object res) throws BasicHttpException, SerializeException;
}