org.apache.wink.server.utils.BaseLinksBuilder 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.wink.server.utils;
import java.net.URI;
import java.util.List;
import javax.ws.rs.core.UriInfo;
import org.apache.wink.common.model.synd.SyndLink;
/**
* Base interface for the the two types of link builders.
*
* @param the derived type of the links builder
* @see SingleLinkBuilder
* @see SystemLinksBuilder
*/
public interface BaseLinksBuilder {
/**
* Set the resource class that the generated links should link to. If no
* resource is set then the active resource is used. Setting the resource
* clears any sub-resource path previously set.
*
* @param resource a resource class annotated with the
* {@link javax.ws.rs.Path} annotation
* @return this links builder
*/
public T resource(Class resource);
/**
* Set the resource instance that the generated links should link to. If no
* resource is set then the active resource is used. Setting the resource
* clears any sub-resource path previously set.
*
* @param resource a resource instance, or null to use the current resource
* @return this links builder
*/
public T resource(Object resource);
/**
* Set the sub-resource path that the generated links should link to,
* relative to the resource set in the builder.
*
* @param template the template path of the sub-resource
* @return this links builder
*/
public T subResource(String template);
/**
* Set the base uri for this builder. If not set, or if set to
* null, then the base uri as obtained from
* {@link UriInfo#getBaseUri()} is used.
*
* @param base the base uri for this builder, or null
* @return this links builder
*/
public T baseUri(URI base);
/**
* Set the uri that the generated links will be relative to, if the
* generation mode is relative uri's. The uri being set must be absolute and
* must be prefixed with the base uri set on this links builder. If not set,
* or if set to null, then the generated links will be relative
* to the path obtained from {@link UriInfo#getPath()}.
*
* @param relativeTo the relative uri for this builder, or null
* @return this links builder
*/
public T relativeTo(URI relativeTo);
/**
* Set the value of a template path parameter to be used during the building
* of the links.
*
* @param name the name of the path parameter
* @param value the value of the path parameter
* @return this links builder
*/
public T pathParam(String name, String value);
/**
* Set the value of a query parameter to be added to the generated links
*
* @param name the name of the query parameter to add to the generated links
* @param value the value of the query parameter
* @return this links builder
*/
public T queryParam(String name, String value);
/**
* Set whether the links should be generated absolute or relative,
* overriding any configuration and request settings. If this method is not
* called, the behavior is taken from the value of the "relative-urls" query
* parameter on the request. If the request does not have the query
* parameter, the behavior is taken from the
* wink.defaultUrisRelative configuration property.
*
* @param relativize true to produce relative links,
* false to produce absolute links
* @return this links builder
*/
public T relativize(boolean relativize);
/**
* Set whether the to automatically add to the generated links the "alt"
* query parameter indicating the link type. The "alt" query parameter will
* never be added automatically in case if it was added manually. If this
* method is not called, the default behavior is taken from the
* wink.addAltParam configuration property.
*
* @param addAltParam true to add the "alt" parameter
* @return
*/
public T addAltParam(boolean addAltParam);
/**
* Build the link(s) and add them to the provided list. The state of the
* builder is not affected by this method.
*
* @param out the output list of links to add the generated link(s) to. If
* the provided list is null then a new list is
* created.
* @return the provided (or new) output list.
*/
public List build(List out);
}