001: // Copyright 2006, 2007 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.tapestry;
016:
017: import java.util.Locale;
018:
019: import org.apache.commons.logging.Log;
020: import org.apache.tapestry.annotations.OnEvent;
021: import org.apache.tapestry.internal.services.OnEventWorker;
022: import org.apache.tapestry.internal.structure.ComponentPageElement;
023: import org.apache.tapestry.ioc.Locatable;
024: import org.apache.tapestry.model.ComponentModel;
025: import org.apache.tapestry.services.ComponentSource;
026:
027: /**
028: * Operations shared by the public {@link ComponentResources} interface and
029: * {@link ComponentPageElement} interface (on the internal side).
030: */
031: public interface ComponentResourcesCommon extends Locatable {
032: /**
033: * Returns the id of the component. The id will be unique within the component's immediate
034: * container. For a page's root component, the value null is returned.
035: */
036: String getId();
037:
038: /**
039: * Return a string consisting the concatinated ids of all containing components, separated by
040: * periods. In addition, nested ids are always all lower case. I.e., "foo.bar.baz". Returns null
041: * for a page.
042: */
043: String getNestedId();
044:
045: /**
046: * Creates a component action request link as a callback for this component.
047: *
048: * @param action
049: * a name for the action associated with the link
050: * @param forForm
051: * if true, the link will be used as the action for an HTML form submission, which
052: * may affect what information is encoded into the link
053: * @param context
054: * additional objects to be encoded into the path portion of the link; each is
055: * converted to a string an URI encoded
056: */
057: Link createActionLink(String action, boolean forForm,
058: Object... context);
059:
060: /**
061: * Creates a render request link to a specific page.
062: *
063: * @param pageName
064: * the logical name of the page to link to
065: * @param override
066: * if true, the context is used even if empty (normally, the target page is allowed
067: * to passivate, providing a context, when the provided context is empty)
068: * @param context
069: * the activation context for the page. If omitted, the activation context is
070: * obtained from the target paget
071: */
072: Link createPageLink(String pageName, boolean override,
073: Object... context);
074:
075: /**
076: * Returns a string consisting of the fully qualified class name of the containing page, and the
077: * {@link #getNestedId() nested id} of this component, separated by a colon. I.e.,
078: * "MyPage:foo.bar.baz". For a page, returns just the page's logical name.
079: * <p>
080: * This value is often used to obtain an equivalent component instance in a later request.
081: *
082: * @see ComponentSource
083: */
084:
085: String getCompleteId();
086:
087: /**
088: * Triggers a component event. A search for an event handling method will occur, first in the
089: * component, then its container, and so on. When a matching event handler method is located, it
090: * is invoked. If the method returns a value, the value is passed to the handler (if handler is
091: * null, then it is an error for a method to return a non-null vavlue).
092: * <p>
093: * Resolution of event type to event handler methods is case insensitive.
094: *
095: * @param eventType
096: * event type (as determined from the request, or otherwise by design)
097: * @param context
098: * the context (as extracted from the request, or provided by the triggering
099: * component); these values may be provided to event handler methods via their
100: * parameters (may be null)
101: * @param handler
102: * the handler to be informed of the result, or null if the event is a notification
103: * that does not support return values from event handler methods (the value true is
104: * allowed even if the handler is null).
105: * @return true if any event handler was invoked (even if no event handler method returns a
106: * non-null value)
107: * @see OnEventWorker
108: * @see OnEvent
109: */
110: boolean triggerEvent(String eventType, Object[] context,
111: ComponentEventHandler handler);
112:
113: /**
114: * Returns true if the component is currently rendering, false otherwise. This is most often
115: * used to determine if parameter values should be cached.
116: */
117: boolean isRendering();
118:
119: /**
120: * Returns the log instance associated with the component (which is based on the component or
121: * mixin's class name).
122: *
123: * @see ComponentModel#getLog()
124: */
125: Log getLog();
126:
127: /** Returns the locale for the page containing this component. */
128: Locale getLocale();
129:
130: /**
131: * Returns the name of element that represents the component in its template, or null if the
132: * element was a component type (in the Tapestry namespace).
133: *
134: * @return the element name
135: */
136: String getElementName();
137:
138: /**
139: * Returns a block from the component's template, referenced by its id.
140: *
141: * @param blockId
142: * the id of the block (case insensitive)
143: * @return the identified Block
144: * @throws BlockNotFoundException
145: * if no block with the given id exists
146: * @see #findBlock(String)
147: */
148: Block getBlock(String blockId);
149:
150: /**
151: * As with {@link #getBlock(String)}, but returns null if the block is not found.
152: *
153: * @param blockId
154: * the id of the block (case insensitive)
155: * @return the block, or null
156: */
157: Block findBlock(String blockId);
158:
159: /**
160: * Returns the <em>logical</em> name of the page containing this component. This is the short
161: * name (it often appears in URLs)
162: *
163: * @return the logical name of the page which contains this component
164: */
165: String getPageName();
166: }
|