001/*
002 * (C) Copyright 2006-2007 Nuxeo SAS (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Nuxeo - initial API and implementation
016 *
017 * $Id: DocumentViewCodecManager.java 22535 2007-07-13 14:57:58Z atchertchian $
018 */
019
020package org.nuxeo.ecm.platform.url.api;
021
022import java.io.Serializable;
023
024import org.nuxeo.ecm.platform.url.codec.api.DocumentViewCodec;
025
026/**
027 * Service used generate meaningful and permanent urls.
028 * <p>
029 * It handles a set of codecs, used to code/decode a document information between a url and a {@link DocumentView}
030 * instance.
031 *
032 * @author <a href="mailto:at@nuxeo.com">Anahide Tchertchian</a>
033 */
034public interface DocumentViewCodecManager extends Serializable {
035
036    /**
037     * Returns the default codec name.
038     * <p>
039     * This information is set on codec descriptors.
040     */
041    String getDefaultCodecName();
042
043    /**
044     * Returns a DocumentView applying for given url, or null.
045     * <p>
046     * Iterates over registered codecs, starting from the default codec, and if
047     * {@link DocumentViewCodec#handleUrl(String)} returns true, calls
048     * {@link DocumentViewCodec#getDocumentViewFromUrl(String)}. Stops iterating when a codec returns a non-null value.
049     *
050     * @param url the original url from request, including request parameters if any.
051     * @param hasBaseUrl boolean indicating if base url should be removed from given url.
052     * @param baseUrl value of the base url.
053     */
054    DocumentView getDocumentViewFromUrl(String url, boolean hasBaseUrl, String baseUrl);
055
056    /**
057     * Returns a DocumentView calling {@link DocumentViewCodec#getDocumentViewFromUrl(String, boolean, String)} on codec
058     * with given name.
059     *
060     * @param url the original url from request, including request parameters if any.
061     * @param hasBaseUrl boolean indicating if base url should be removed from given url.
062     * @param baseUrl value of the base url.
063     */
064    DocumentView getDocumentViewFromUrl(String codecName, String url, boolean hasBaseUrl, String baseUrl);
065
066    /**
067     * Returns an URL applying for given document view, or null.
068     * <p>
069     * Iterates over registered codecs, starting from the default codec, and if
070     * {@link DocumentViewCodec#handleDocumentView(DocumentView)} returns true, calls
071     * {@link DocumentViewCodec#getUrlFromDocumentView(DocumentView)}. Stops iterating when a codec returns a non-null
072     * value. am docView the original document view from request
073     *
074     * @param docView the original document view from request
075     * @param hasBaseUrl boolean indicating if base url should be added to the url returned by the codec.
076     * @param baseUrl value of the base url.
077     */
078    String getUrlFromDocumentView(DocumentView docView, boolean needBaseUrl, String baseUrl);
079
080/**
081     * Returns an URL calling
082     * {@link DocumentViewCodec#getUrlFromDocumentView(DocumentView) on codec
083     * with given name.
084     *
085     * @param docView the original document view from request
086     * @param hasBaseUrl boolean indicating if base url should be added to the
087     *            url returned by the codec.
088     * @param baseUrl value of the base url.
089     */
090    String getUrlFromDocumentView(String codecName, DocumentView docView, boolean needBaseUrl, String baseUrl);
091
092}