    001    // Copyright 2008, 2010, 2011 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.internal.structure;
    016
    017    import org.apache.tapestry5.ComponentResources;
    018    import org.apache.tapestry5.Link;
    019    import org.apache.tapestry5.ioc.Messages;
    020    import org.apache.tapestry5.ioc.OperationTracker;
    021    import org.apache.tapestry5.ioc.services.PerThreadValue;
    022    import org.apache.tapestry5.ioc.services.PerthreadManager;
    023    import org.apache.tapestry5.model.ComponentModel;
    024    import org.apache.tapestry5.services.ContextValueEncoder;
    025    import org.apache.tapestry5.services.pageload.ComponentResourceSelector;
    026    import org.slf4j.Logger;
    027
    028    /**
    029     * Provides access to common methods of various services, needed by implementations of {@link ComponentPageElement} and
    030     * {@link org.apache.tapestry5.internal.InternalComponentResources}.
    031     */
    032    public interface ComponentPageElementResources extends ContextValueEncoder, OperationTracker
    033    {
    034        /**
    035         * Returns the selector associated with this resources.
    036         *
    037         * @since 5.3
    038         */
    039        ComponentResourceSelector getSelector();
    040
    041        /**
    042         * Used to obtain a {@link org.apache.tapestry5.ioc.Messages} instance for a particular component. If the component
    043         * extends from another component, then its localized properties will merge with its parent's properties (with the
    044         * subclass overriding the super class on any conflicts).
    045         *
    046         * @param componentModel
    047         * @return the message catalog for the component, in the indicated locale
    048         * @see org.apache.tapestry5.services.messages.ComponentMessagesSource
    049         */
    050        Messages getMessages(ComponentModel componentModel);
    051
    052        /**
    053         * Performs a coercion from an input type to a desired output type. When the target type is a primitive, the actual
    054         * conversion will be to the equivalent wrapper type. In some cases, the TypeCoercer will need to search for an
    055         * appropriate coercion, and may even combine existing coercions to form new ones; in those cases, the results of
    056         * the search are cached.
    057         *
    058         * @param <S>
    059         *            source type (input)
    060         * @param <T>
    061         *            target type (output)
    062         * @param input
    063         * @param targetType
    064         *            defines the target type
    065         * @return the coerced value
    066         * @see org.apache.tapestry5.ioc.services.TypeCoercer
    067         */
    068        <S, T> T coerce(S input, Class<T> targetType);
    069
    070        /**
    071         * Gets the Class instance for then give name.
    072         *
    073         * @param className
    074         *            fully qualified class name
    075         * @return the class instance
    076         * @see org.apache.tapestry5.internal.services.ComponentClassCache
    077         */
    078        Class toClass(String className);
    079
    080        /**
    081         * Creates a link on behalf of a component.
    082         *
    083         * @param resources
    084         *            resources for the component
    085         * @param eventType
    086         *            type of event to create
    087         * @param forForm
    088         *            true if generating for a form submission
    089         * @param context
    090         *            additional event context associated with the link
    091         * @return the link
    092         * @since 5.1.0.0
    093         */
    094        Link createComponentEventLink(ComponentResources resources, String eventType, boolean forForm, Object... context);
    095
    096        /**
    097         * Creates a page render request link to render a specific page.
    098         *
    099         * @param pageName
    100         *            the logical name of the page to link to
    101         * @param override
    102         *            if true, the context is used even if empty (normally, the target page is allowed to passivate,
    103         *            providing a context, when the provided context is empty)
    104         * @param context
    105         *            the activation context for the page. If omitted, the activation context is obtained from the
    106         *            target page
    107         * @return link for a render request to the targetted page
    108         * @since 5.1.0.0
    109         */
    110        Link createPageRenderLink(String pageName, boolean override, Object... context);
    111
    112        /**
    113         * Creates a page render request link to render a specific page. Using a page class, rather than a page name, is
    114         * more refactoring safe (in the even the page is renamed or moved).
    115         *
    116         * @param pageClass
    117         *            identifies the page to link to
    118         * @param override
    119         *            if true, the context is used even if empty (normally, the target page is allowed to passivate,
    120         *            providing a context, when the provided context is empty)
    121         * @param context
    122         *            the activation context for the page. If omitted, the activation context is obtained from the
    123         *            target page
    124         * @return link for a render request to the targetted page
    125         * @since 5.1
    126         */
    127        Link createPageRenderLink(Class pageClass, boolean override, Object... context);
    128
    129        /**
    130         * Returns the event logger for the provided component logger. The event logger is based on the component logger's
    131         * name (which matches the component class name) with a "tapestry..events." prefix.
    132         *
    133         * @param componentLogger
    134         *            provides base name for logger
    135         * @return the logger
    136         */
    137        Logger getEventLogger(Logger componentLogger);
    138
    139        /**
    140         * Wrapper around {@link PerthreadManager#createValue()}.
    141         *
    142         * @since 5.2.0
    143         */
    144        <T> PerThreadValue<T> createPerThreadValue();
    145    }