Save This Page
Home » tapestry-src-5.0.19 » org.apache.tapestry5 » [javadoc | source]
    1   // Copyright 2006, 2007, 2008 The Apache Software Foundation
    2   //
    3   // Licensed under the Apache License, Version 2.0 (the "License");
    4   // you may not use this file except in compliance with the License.
    5   // You may obtain a copy of the License at
    6   //
    7   //     http://www.apache.org/licenses/LICENSE-2.0
    8   //
    9   // Unless required by applicable law or agreed to in writing, software
   10   // distributed under the License is distributed on an "AS IS" BASIS,
   11   // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   12   // See the License for the specific language governing permissions and
   13   // limitations under the License.
   14   
   15   package org.apache.tapestry5;
   16   
   17   import org.apache.tapestry5.ioc.Locatable;
   18   import org.slf4j.Logger;
   19   
   20   import java.util.Locale;
   21   
   22   /**
   23    * Operations shared by the public {@link org.apache.tapestry5.ComponentResources} interface and {@link
   24    * org.apache.tapestry5.internal.structure.ComponentPageElement} interface (on the internal side).
   25    */
   26   @SuppressWarnings({"JavaDoc"})
   27   public interface ComponentResourcesCommon extends Locatable
   28   {
   29       /**
   30        * Returns the simple (or local) id of the component. The id will be unique within the component's immediate
   31        * container. For a page's root component, the value null is returned.
   32        * <p/>
   33        * \
   34        */
   35       String getId();
   36   
   37       /**
   38        * Return a string consisting the concatinated ids of all containing components, separated by periods. In addition,
   39        * nested ids are always all lower case. I.e., "foo.bar.baz". Returns null for the root component of a  page.
   40        */
   41       String getNestedId();
   42   
   43   
   44       /**
   45        * Returns a string consisting of the logical name of the containing page, and the {@link #getNestedId() nested id}
   46        * of this component, separated by a colon. I.e., "MyPage:foo.bar.baz". For a page, returns just the page's logical
   47        * name.
   48        * <p/>
   49        * This value is often used to obtain an equivalent component instance in a later request.
   50        *
   51        * @see org.apache.tapestry5.services.ComponentSource#getComponent(String)
   52        */
   53       String getCompleteId();
   54   
   55       /**
   56        * A convienience for invoking {@link #triggerContextEvent(String, EventContext , ComponentEventCallback)}. Wraps
   57        * the context values into an {@link org.apache.tapestry5.EventContext}.
   58        *
   59        * @param eventType     event type (as determined from the request, or otherwise by design)
   60        * @param contextValues Values that may be provided to the event handler method as method parameters, or null if no
   61        *                      context values are available
   62        * @param callback      the handler to be informed of the result, or null if the event is a notification that does
   63        *                      not support return values from event handler methods (the value true is allowed even if the
   64        *                      handler is null).
   65        * @return true if any event handler was invoked (even if no event handler method returns a non-null value)
   66        * @throws org.apache.tapestry5.runtime.ComponentEventException
   67        *          if an event handler method throws a checked or unchecked exception
   68        * @see org.apache.tapestry5.internal.transform.OnEventWorker
   69        * @see org.apache.tapestry5.annotations.OnEvent
   70        */
   71       boolean triggerEvent(String eventType, Object[] contextValues, ComponentEventCallback callback);
   72   
   73       /**
   74        * Triggers a component event. A search for an event handling method will occur, first in the component, then its
   75        * container, and so on. When a matching event handler method is located, it is invoked. If the method returns a
   76        * value, the value is passed to the callback (if callback is null, then it is an error for a method to return a
   77        * non-null value).
   78        * <p/>
   79        * Resolution of event type to event handler methods is case insensitive.
   80        *
   81        * @param eventType event type (as determined from the request, or otherwise by design)
   82        * @param context   the context (as extracted from the request, or provided by the triggering component); these
   83        *                  values may be provided to event handler methods via their parameters (may not be null)
   84        * @param callback  the handler to be informed of the result, or null if the event is a notification that does not
   85        *                  support return values from event handler methods (the value true is allowed even if the handler
   86        *                  is null).
   87        * @return true if any event handler was invoked (even if no event handler method returns a non-null value)
   88        * @throws org.apache.tapestry5.runtime.ComponentEventException
   89        *          if an event handler method throws a checked or unchecked exception
   90        * @see org.apache.tapestry5.internal.transform.OnEventWorker
   91        * @see org.apache.tapestry5.annotations.OnEvent
   92        */
   93       boolean triggerContextEvent(String eventType, EventContext context, ComponentEventCallback callback);
   94   
   95       /**
   96        * Returns true if the component is currently rendering, false otherwise. This is most often used to determine if
   97        * parameter values should be cached.
   98        */
   99       boolean isRendering();
  100   
  101       /**
  102        * Returns the log instance associated with the component (which is based on the component or mixin's class name).
  103        *
  104        * @see org.apache.tapestry5.model.ComponentModel#getLogger()
  105        */
  106       Logger getLogger();
  107   
  108       /**
  109        * Returns the locale for the page containing this component.
  110        */
  111       Locale getLocale();
  112   
  113       /**
  114        * Returns the name of element that represents the component in its template, or the provided default element name
  115        * if the element was a component type (in the Tapestry namespace).
  116        *
  117        * @param defaultElementName element name to return if the element name is not known (may be null)
  118        * @return the element name
  119        */
  120       String getElementName(String defaultElementName);
  121   
  122       /**
  123        * Returns a block from the component's template, referenced by its id.
  124        *
  125        * @param blockId the id of the block (case insensitive)
  126        * @return the identified Block
  127        * @throws BlockNotFoundException if no block with the given id exists
  128        * @see #findBlock(String)
  129        */
  130       Block getBlock(String blockId);
  131   
  132       /**
  133        * As with {@link #getBlock(String)}, but returns null if the block is not found.
  134        *
  135        * @param blockId the id of the block (case insensitive)
  136        * @return the block, or null
  137        */
  138       Block findBlock(String blockId);
  139   
  140       /**
  141        * Returns the <em>logical</em> name of the page containing this component. This is the short name (it often appears
  142        * in URLs)
  143        *
  144        * @return the logical name of the page which contains this component
  145        */
  146       String getPageName();
  147   
  148   
  149       /**
  150        * Returns true if the element has a body and false otherwise.  Only components may have a body; pages and mixins
  151        * will return false.
  152        */
  153       boolean hasBody();
  154   
  155       /**
  156        * Returns the body of this component as a (possibly empty) block.  When invoked on a mixin, returns the containing
  157        * component's body.
  158        */
  159       Block getBody();
  160   }

Save This Page
Home » tapestry-src-5.0.19 » org.apache.tapestry5 » [javadoc | source]