001// Copyright 2008-2014 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
015package org.apache.tapestry5.internal.structure;
016
017import org.apache.tapestry5.ComponentResources;
018import org.apache.tapestry5.Link;
019import org.apache.tapestry5.ioc.Messages;
020import org.apache.tapestry5.ioc.OperationTracker;
021import org.apache.tapestry5.ioc.services.PerThreadValue;
022import org.apache.tapestry5.ioc.services.PerthreadManager;
023import org.apache.tapestry5.model.ComponentModel;
024import org.apache.tapestry5.services.ContextValueEncoder;
025import org.apache.tapestry5.services.pageload.ComponentResourceSelector;
026import 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 */
032public 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
146    /**
147     * Returns true if component element tracing is enabled. When enabled, rendering of the component produces
148     * additional comments to identify what component and stage is rendering.
149     *
150     * @since 5.4
151     */
152    boolean isRenderTracingEnabled();
153}