Clover coverage report - Code Coverage for tapestry release 4.0-alpha-3
Coverage timestamp: Mon May 16 2005 09:05:49 EDT
file stats: LOC: 327   Methods: 0
NCLOC: 43   Classes: 1
30 day Evaluation Version distributed via the Maven Jar Repository. Clover is not free. You have 30 days to evaluate it. Please visit http://www.thecortex.net/clover to obtain a licensed version of Clover
 
 Source file Conditionals Statements Methods TOTAL
IComponent.java - - - -
coverage
 1   
 // Copyright 2004, 2005 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.tapestry;
 16   
 
 17   
 import java.util.Collection;
 18   
 import java.util.Map;
 19   
 
 20   
 import org.apache.hivemind.ApplicationRuntimeException;
 21   
 import org.apache.hivemind.LocationHolder;
 22   
 import org.apache.hivemind.Messages;
 23   
 import org.apache.tapestry.engine.IPageLoader;
 24   
 import org.apache.tapestry.listener.ListenerMap;
 25   
 import org.apache.tapestry.spec.IComponentSpecification;
 26   
 
 27   
 /**
 28   
  * Defines an object which may be used to provide dynamic content on a Tapestry web page.
 29   
  * <p>
 30   
  * Components are created dynamically from thier class names (part of the
 31   
  * {@link IComponentSpecification}).
 32   
  * 
 33   
  * @author Howard Leiws Ship
 34   
  */
 35   
 
 36   
 public interface IComponent extends IRender, LocationHolder
 37   
 {
 38   
 
 39   
     /**
 40   
      * Adds an asset to the component. This is invoked from the page loader.
 41   
      */
 42   
 
 43   
     public void addAsset(String name, IAsset asset);
 44   
 
 45   
     /**
 46   
      * Adds a component to a container. Should only be called during the page loading process, which
 47   
      * is responsible for any checking.
 48   
      * 
 49   
      * @see IPageLoader
 50   
      */
 51   
 
 52   
     public void addComponent(IComponent component);
 53   
 
 54   
     /**
 55   
      * Adds a new renderable element to the receiver's body. The element may be either another
 56   
      * component, or static HTML. Such elements come from inside the receiver's tag within its
 57   
      * container's template, and represent static text and other components.
 58   
      * <p>
 59   
      * The method {@link #renderBody(IMarkupWriter, IRequestCycle)}is used to render these
 60   
      * elements.
 61   
      * 
 62   
      * @since 2.2
 63   
      */
 64   
 
 65   
     public void addBody(IRender element);
 66   
 
 67   
     /**
 68   
      * Returns the asset map for the component, which may be empty but will not be null.
 69   
      * <p>
 70   
      * The return value is unmodifiable.
 71   
      */
 72   
 
 73   
     public Map getAssets();
 74   
 
 75   
     /**
 76   
      * Returns the named asset, or null if not found.
 77   
      */
 78   
 
 79   
     public IAsset getAsset(String name);
 80   
 
 81   
     /**
 82   
      * Returns the binding with the given name or null if not found.
 83   
      * <p>
 84   
      * Bindings are added to a component using {@link #setBinding(String,IBinding)}.
 85   
      */
 86   
 
 87   
     public IBinding getBinding(String name);
 88   
 
 89   
     /**
 90   
      * Returns a {@link Collection}of the names of all bindings (which includes bindings for both
 91   
      * formal and informal parameters).
 92   
      * <p>
 93   
      * The return value is unmodifiable. It will be null for a {@link IPage page}, or may simply be
 94   
      * empty for a component with no bindings.
 95   
      */
 96   
 
 97   
     public Collection getBindingNames();
 98   
 
 99   
     /**
 100   
      * Returns a {@link Map}of the {@link IBinding bindings}for this component; this includes
 101   
      * informal parameters as well as formal bindings.
 102   
      * 
 103   
      * @since 1.0.5
 104   
      */
 105   
 
 106   
     public Map getBindings();
 107   
 
 108   
     /**
 109   
      * Retrieves an contained component by its id. Contained components have unique ids within their
 110   
      * container.
 111   
      * 
 112   
      * @exception ApplicationRuntimeException
 113   
      *                runtime exception thrown if the named component does not exist.
 114   
      */
 115   
 
 116   
     public IComponent getComponent(String id);
 117   
 
 118   
     /**
 119   
      * Returns the component which embeds the receiver. All components are contained within other
 120   
      * components, with the exception of the root page component.
 121   
      * <p>
 122   
      * A page returns null.
 123   
      */
 124   
 
 125   
     public IComponent getContainer();
 126   
 
 127   
     /**
 128   
      * Sets the container of the component. This is write-once, an attempt to change it later will
 129   
      * throw an {@link ApplicationRuntimeException}.
 130   
      */
 131   
 
 132   
     public void setContainer(IComponent value);
 133   
 
 134   
     /**
 135   
      * Returns a string identifying the name of the page and the id path of the reciever within the
 136   
      * page (seperated by a slash). Note that this extended id is indetned primarily for identifying
 137   
      * the component to the user (since slashes are legal characters within page names). Pages
 138   
      * simply return their name.
 139   
      * 
 140   
      * @see #getIdPath()
 141   
      */
 142   
 
 143   
     public String getExtendedId();
 144   
 
 145   
     /**
 146   
      * Returns the simple id of the component, as defined in its specification.
 147   
      * <p>
 148   
      * An id will be unique within the component which contains this component.
 149   
      * <p>
 150   
      * A {@link IPage page}will always return null.
 151   
      */
 152   
 
 153   
     public String getId();
 154   
 
 155   
     /**
 156   
      * Sets the id of the component. This is write-once, an attempt to change it later will throw an
 157   
      * {@link ApplicationRuntimeException}.
 158   
      */
 159   
 
 160   
     public void setId(String value);
 161   
 
 162   
     /**
 163   
      * Returns the qualified id of the component. This represents a path from the {@link IPage page}
 164   
      * to this component, showing how components contain each other.
 165   
      * <p>
 166   
      * A {@link IPage page}will always return null. A component contained on a page returns its
 167   
      * simple id. Other components return their container's id path followed by a period and their
 168   
      * own name.
 169   
      * 
 170   
      * @see #getId()
 171   
      */
 172   
 
 173   
     public String getIdPath();
 174   
 
 175   
     /**
 176   
      * Returns the page which ultimately contains the receiver. A page will return itself.
 177   
      */
 178   
 
 179   
     public IPage getPage();
 180   
 
 181   
     /**
 182   
      * Sets the page which ultimiately contains the component. This is write-once, an attempt to
 183   
      * change it later will throw an {@link ApplicationRuntimeException}.
 184   
      */
 185   
 
 186   
     public void setPage(IPage value);
 187   
 
 188   
     /**
 189   
      * Returns the specification which defines the component.
 190   
      */
 191   
 
 192   
     public IComponentSpecification getSpecification();
 193   
 
 194   
     /**
 195   
      * Invoked to make the receiver render its body (the elements and components its tag wraps
 196   
      * around, on its container's template). This method is public so that the
 197   
      * {@link org.apache.tapestry.components.RenderBody}component may operate.
 198   
      * 
 199   
      * @since 2.2
 200   
      */
 201   
 
 202   
     public void renderBody(IMarkupWriter writer, IRequestCycle cycle);
 203   
 
 204   
     /**
 205   
      * Adds a binding to a container. Should only be called during the page loading process (which
 206   
      * is responsible for eror checking).
 207   
      * 
 208   
      * @see IPageLoader
 209   
      */
 210   
 
 211   
     public void setBinding(String name, IBinding binding);
 212   
 
 213   
     /**
 214   
      * Returns the contained components as an unmodifiable {@link Map}. This allows peer components
 215   
      * to work together without directly involving their container ... the classic example is to
 216   
      * have an {@link org.apache.tapestry.components.Insert}work with an enclosing
 217   
      * {@link org.apache.tapestry.components.Foreach}.
 218   
      * <p>
 219   
      * This is late addition to Tapestry, because it also opens the door to abuse, since it is quite
 220   
      * possible to break the "black box" aspect of a component by interacting directly with
 221   
      * components it embeds. This creates ugly interelationships between components that should be
 222   
      * seperated.
 223   
      * 
 224   
      * @return A Map of components keyed on component id. May return an empty map, but won't return
 225   
      *         null.
 226   
      */
 227   
 
 228   
     public Map getComponents();
 229   
 
 230   
     /**
 231   
      * Allows a component to finish any setup after it has been constructed.
 232   
      * <p>
 233   
      * The exact timing is not specified, but any components contained by the receiving component
 234   
      * will also have been constructed before this method is invoked.
 235   
      * <p>
 236   
      * As of release 1.0.6, this method is invoked <em>before</em> bindings are set. This should
 237   
      * not affect anything, as bindings should only be used during renderring.
 238   
      * <p>
 239   
      * Release 2.2 added the cycle parameter which is, regretfully, not backwards compatible.
 240   
      * 
 241   
      * @since 0.2.12
 242   
      */
 243   
 
 244   
     public void finishLoad(IRequestCycle cycle, IPageLoader loader,
 245   
             IComponentSpecification specification);
 246   
 
 247   
     /**
 248   
      * Returns component strings for the component. Starting in release 4.0, this method is
 249   
      * unimplemented (and is automatically injected into each component implementation).
 250   
      * 
 251   
      * @since 3.0
 252   
      */
 253   
 
 254   
     public Messages getMessages();
 255   
 
 256   
     /**
 257   
      * Returns the {@link INamespace}in which the component was defined (as an alias).
 258   
      * 
 259   
      * @since 2.2
 260   
      */
 261   
 
 262   
     public INamespace getNamespace();
 263   
 
 264   
     /**
 265   
      * Sets the {@link INamespace}for the component. The namespace should only be set once.
 266   
      * 
 267   
      * @since 2.2
 268   
      */
 269   
 
 270   
     public void setNamespace(INamespace namespace);
 271   
 
 272   
     /**
 273   
      * Sets a property of a component.
 274   
      * 
 275   
      * @param propertyName
 276   
      *            the property name
 277   
      * @param value
 278   
      *            the provided value
 279   
      */
 280   
     public void setProperty(String propertyName, Object value);
 281   
 
 282   
     /**
 283   
      * Gets a property of a component.
 284   
      * 
 285   
      * @param propertyName
 286   
      *            the property name
 287   
      * @return Object the value of property
 288   
      */
 289   
     public Object getProperty(String propertyName);
 290   
 
 291   
     /**
 292   
      * Returns true if the component is currently rendering.
 293   
      * 
 294   
      * @since 4.0
 295   
      */
 296   
 
 297   
     public boolean isRendering();
 298   
 
 299   
     /**
 300   
      * Invoked after {@link #finishLoad(IRequestCycle, IPageLoader, IComponentSpecification)}to
 301   
      * switch the component from its initial construction state into its active state. The
 302   
      * difference concerns parameters, whose defaults values may be set from inside
 303   
      * {@link #finishLoad(IRequestCycle, IPageLoader, IComponentSpecification)}.
 304   
      * 
 305   
      * @since 4.0
 306   
      */
 307   
 
 308   
     public void enterActiveState();
 309   
 
 310   
     /**
 311   
      * Returns a {@link IBeanProvider}&nbsp;from which managed beans can be obtained.
 312   
      * 
 313   
      * @since 4.0
 314   
      */
 315   
 
 316   
     public IBeanProvider getBeans();
 317   
 
 318   
     /**
 319   
      * Returns a {@link ListenerMap}&nbsp;for the component. The map contains a number of synthetic
 320   
      * read-only properties that implement the {@link IActionListener}&nbsp;interface, but in fact,
 321   
      * cause public instance methods to be invoked (via reflection).
 322   
      * 
 323   
      * @since 4.0
 324   
      */
 325   
 
 326   
     public ListenerMap getListeners();
 327   
 }