    001    // Copyright 2008, 2010 The Apache Software Foundation
    002    //
    003    // Licensed under the Apache License, Version 2.0 (the "License");
    004    // you may not use this file except in compliance with the License.
    005    // You may obtain a copy of the License at
    006    //
    007    // http://www.apache.org/licenses/LICENSE-2.0
    008    //
    009    // Unless required by applicable law or agreed to in writing, software
    010    // distributed under the License is distributed on an "AS IS" BASIS,
    011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    012    // See the License for the specific language governing permissions and
    013    // limitations under the License.
    014
    015    package org.apache.tapestry5.services;
    016
    017    import org.apache.tapestry5.EventContext;
    018
    019    /**
    020     * A service to provide utilities needed for event context encoding and decoding to and from (partial) URL paths. This
    021     * is used for both component event contexts and page activation contexts.
    022     */
    023    public interface ContextPathEncoder
    024    {
    025        /**
    026         * Encodes a single value via the {@link ContextValueEncoder} service, returning the resulting string. Even null
    027         * is encoded, as per {@link URLEncoder#encode(String)}.
    028         *
    029         * @since 5.2.2
    030         */
    031        String encodeValue(Object value);
    032
    033        /**
    034         * Encodes the context values into a path string. Each context value (if non-null) is first value encoded into a
    035         * string via the {@link org.apache.tapestry5.services.ContextValueEncoder} service. Those values are then encoded,
    036         * via {@link URLEncoder#encode(String)} into URL-safe strings. The URL-safe strings are then concatenated
    037         * together, separated with "/" characters.
    038         *
    039         * @param context
    040         *            an array of objects to encode as the context (may be null)
    041         * @return the path-encoded context, or the blank string if the context is empty
    042         */
    043        String encodeIntoPath(Object[] context);
    044
    045        /**
    046         * Encodes the context into a string. Returns the empty string if the context is empty.
    047         *
    048         * @param context
    049         *            to encode
    050         * @return encoded values separated by "/" characters, or the empty string
    051         * @since 5.1.0.2
    052         */
    053        String encodeIntoPath(EventContext context);
    054
    055        /**
    056         * Inverse of {@link #encodeIntoPath(Object[])}; the path is split into strings, and the string are decoded and
    057         * constructed into an {@link org.apache.tapestry5.EventContext}.
    058         *
    059         * @param path
    060         *            to decode, possibly empty or null
    061         * @return corresponding event context
    062         */
    063        EventContext decodePath(String path);
    064    }