Class ComponentBuilderData

  • All Implemented Interfaces:
    SimpleBeanStoreImpl.BeanContributor, Composite

    public class ComponentBuilderData
    extends Object
    implements Composite, SimpleBeanStoreImpl.BeanContributor

    A class for storing temporary data and the results of a form builder operation.

    For every call of a form builder an instance of this class is created. During the build process a couple of information is created. Some of this belongs to the final result, other parts need to be accessed later to resolve references or for different purposes. This class is a home for all these kinds of data.

    Especially the components created during a builder operation must be stored somewhere so that they can be combined to a resulting Form object. For this purpose this class provides an implementation of the ComponentStore interface and registers it as the default component store. To access the component store interested parties do not directly invoke the methods provided by ComponentStore, but access them through the storeXXXX() and getXXXX() methods defined in this class. These methods obtain the current store and delegate the call to it. During the builder operation a different ComponentStore can be temporarily set using the pushComponentStore() and popComponentStore() methods. This makes it possible for complex components to catch all the components created in their context; this way sub forms can be created that for instance represent a row in a table. With the pushFormContext() and popFormContext() methods a complete new form context can be created, i.e. all components will be added to the passed in form, and event registration can be performed on the components that belong to that form.

    To make the current form and all of its components available to the dependency injection framework, this class implements the SimpleBeanStoreImpl.BeanContributor interface and can therefore collaborate with a SimpleBeanStoreImpl. There is also a getBeanContext() method that returns a context for querying all available beans. Through this context the global beans (as defined by the application) can be queried and the objects created during the builder operation as well. To access the components and their associated handler classes the following naming scheme is used:

    • Components (i.e. the platform specific objects created by the ComponentManager) can be accessed using the name that is specified in the Jelly builder script. For instance (if builderData is an instance of ComponentBuilderData) builderData.getBeanContext().getBean("txtFirstName"); would return the input component associated with the name txtFirstName (probably a JTextField if Swing is used).
    • For accessing the ComponentHandlers for the managed components the prefix comp:: builderData.getBeanContext().getBean("comp:txtFirstName"); would return the ComponentHandler for the txtFirstName component.
    • FieldHandlers are also accessed using a special prefix: field:. So for obtaining the FieldHandler for the txtFirstName field you would write builderData.getBeanContext().getBean("field:txtFirstName");.
    • Each component is associated with a WidgetHandler. For obtaining a component's WidgetHandler the prefix widget: is used, as in builderData.getBeanContext().getBean("widget:txtFirstName");.
    • The Form object constructed during the current builder operation can also be accessed under a special reserved key: Form form = (Form) builderData.getBeanContext().getBean("CURRENT_FORM"); .
    • The BeanContext maintained by this instance can also be accessed (e.g. to be injected into a bean defined by the current builder script). This can be done using the key CURRENT_CONTEXT.
    • The current BuilderData object is available under the key BUILDER_DATA.
    • Finally the current ComponentBuilderData instance itself is exposed through the BeanStore implementation. The corresponding reserved key is named COMPONENT_BUILDER_DATA.
    To avoid naming conflicts the identifiers for components in the builder scripts should be chosen in a way that they do not interfere with this reserved keys. Note that this class also defines constants for these keys.

    The current instance of this class for the running builder process is stored in the Jelly Context, where it can be accessed from all tags. From here also references to the factories needed for creating components can be obtained. The root container object is maintained by this object, too.

    Implementation note: This class is not thread-safe. If it is accessed concurrently by multiple threads, proper synchronization must be ensured.

    Version:
    $Id: ComponentBuilderData.java 208 2012-02-11 20:57:33Z oheger $
    Author:
    Oliver Heger
    • Field Detail

      • KEY_COMPHANDLER_PREFIX

        public static final String KEY_COMPHANDLER_PREFIX
        Constant for the prefix for accessing component handlers. This prefix has to be used for obtaining the ComponentHandler of a component from the bean context managed by this class.
        See Also:
        Constant Field Values
      • KEY_FIELDHANDLER_PREFIX

        public static final String KEY_FIELDHANDLER_PREFIX
        Constant for the prefix for accessing field handlers. This prefix has to be used for obtaining the FieldHandler of a component from the bean context managed by this class.
        See Also:
        Constant Field Values
      • KEY_WIDGETHANDLER_PREFIX

        public static final String KEY_WIDGETHANDLER_PREFIX
        Constant for the prefix for accessing widget handlers. This prefix has to be used for obtaining the WidgetHandler of a component from the bean context managed by this class.
        See Also:
        Constant Field Values
      • KEY_FORM

        public static final String KEY_FORM
        Constant for the key for accessing the current form from the bean context managed by this class.
        See Also:
        Constant Field Values
      • KEY_COMPONENT_BUILDER_DATA

        public static final String KEY_COMPONENT_BUILDER_DATA
        Constant for the key for accessing the current instance of this class from the managed bean context.
        See Also:
        Constant Field Values
      • KEY_CURRENT_CONTEXT

        public static final String KEY_CURRENT_CONTEXT
        Constant for the key for accessing the current bean context. This name can be used to inject a context into beans defined in a Jelly builder script.
        See Also:
        Constant Field Values
      • KEY_BUILDER_DATA

        public static final String KEY_BUILDER_DATA
        Constant for the key for accessing the current BuilderData object from the bean context managed by this class. The BuilderData object allows access to some important, application-global objects.
        See Also:
        Constant Field Values
    • Constructor Detail

      • ComponentBuilderData

        public ComponentBuilderData()
        Creates a new instance of ComponentBuilderData.
    • Method Detail

      • initializeForm

        public void initializeForm​(TransformerContext tctx,
                                   BindingStrategy strategy)
        Initializes the main form to be maintained by the ComponentBuilderData object. This method must be called after the construction of this object to explicitly initialize the Form object.
        Parameters:
        tctx - the TransformerContext
        strategy - the BindingStrategy for the form
        Throws:
        IllegalArgumentException - if a required parameter is null
      • getBuilderName

        public String getBuilderName()
        Returns the name of the current builder.
        Returns:
        the builder name
      • setBuilderName

        public void setBuilderName​(String builderName)
        Sets the name of the current builder.
        Parameters:
        builderName - the builder name
      • getRootContainer

        public Object getRootContainer()
        Returns the root container.
        Returns:
        the root container
      • setRootContainer

        public void setRootContainer​(Object rootContainer)
        Sets the root container. All component tags that are not nested inside a container tag will add their created objects to this container object.
        Parameters:
        rootContainer - the root container to use
      • getComponentManager

        public ComponentManager getComponentManager()
        Returns the component manager.
        Returns:
        the component manager
      • setComponentManager

        public void setComponentManager​(ComponentManager componentManager)
        Sets the component manager. This object will be used to create and manipulate GUI components.
        Parameters:
        componentManager - the component manager to use
      • getFieldHandlerFactory

        public FieldHandlerFactory getFieldHandlerFactory()
        Returns the field handler factory.
        Returns:
        the field handler factory
      • setFieldHandlerFactory

        public void setFieldHandlerFactory​(FieldHandlerFactory fieldHandlerFactory)
        Sets the field handler factory. This object is used by input component tags for creating the field handlers that are then passed to the internal form object.
        Parameters:
        fieldHandlerFactory - the handler factory
      • getContainerSelector

        public ContainerSelector getContainerSelector()
        Returns the ContainerSelector used by this object.
        Returns:
        the ContainerSelector
        Since:
        1.3
      • setContainerSelector

        public void setContainerSelector​(ContainerSelector containerSelector)
        Sets the ContainerSelector to be used by this object.
        Parameters:
        containerSelector - the ContainerSelector
        Since:
        1.3
      • getDefaultResourceGroup

        public Object getDefaultResourceGroup()
        Returns the default resource group.
        Returns:
        the default resource group
      • setDefaultResourceGroup

        public void setDefaultResourceGroup​(Object defaultResourceGroup)
        Sets the default resource group. This group will be used if no specific group is specified in a resource request.
        Parameters:
        defaultResourceGroup - the default resource group
      • getForm

        public Form getForm()
        Returns the Form object. This object is created during the builder process. It contains all fields that have been created so far. Note: Before calling this method initializeForm() must have been invoked; otherwise an exception is thrown.
        Returns:
        the Form object
        Throws:
        IllegalStateException - if the form has not yet been initialized
      • getTransformerContext

        public TransformerContext getTransformerContext()
        Returns the transformer context.
        Returns:
        the transformer context
      • getEventManager

        public FormEventManager getEventManager()
        Returns the FormEventManager used by this builder operation. This object can be used to register event handlers at components created during the building process.
        Returns:
        the event manager object
      • setEventManager

        public void setEventManager​(FormEventManager evMan)
        Allows to set an event manager. All event handling logic, e.g. registering event listeners, will be done by this object. Normally it is not necessary to set a specific event manager; there is a default instance. This method is intended for complex components that need to hook into the event logic.
        Parameters:
        evMan - the new event manager to be set (can be null, then the default event manager for the current form will be set)
      • getToolTipManager

        public ToolTipManager getToolTipManager()
        Returns the ToolTipManager associated with this object. If no specific ToolTipManager has been set, a default instance is created and returned.
        Returns:
        the ToolTipManager
      • setToolTipManager

        public void setToolTipManager​(ToolTipManager toolTipManager)
        Sets the ToolTipManager for this object. This ToolTipManager is then used for manipulating tool tips for components. Normally it is not necessary to set a specific tool tip manager. If none is set, a default instance is created. This method can be used to inject a custom tool tip manager.
        Parameters:
        toolTipManager - the ToolTipManager to be used
      • getComponentStore

        public ComponentStore getComponentStore()
        Returns a reference to the current component store. This store will be used for searching and storing components.
        Returns:
        the currently used ComponentStore
      • pushComponentStore

        public ComponentStore pushComponentStore​(ComponentStore store)
        Adds a new component store to this object that will replace the current store. All newly created components will be added to this store. It will be active until popComponentStore() is called, then the replaced component store will become the current store again. The purpose of this method is to allow complex tags to install their own store so that all components created in their context are put into this store. Thus it is possible to create sub forms or things like that. Call backs that are registered using the addCallBack() method will also be affected: they are always created in the context of the current component store and executed when popComponentStore() is invoked.
        Parameters:
        store - the new store (must not be null)
        Returns:
        the old active store; this store is replaced by the new one
        Throws:
        IllegalArgumentException - if the passed in store is null
        See Also:
        popComponentStore()
      • popComponentStore

        public ComponentStore popComponentStore()
                                         throws FormBuilderException
        Removes a component store from this object. This method is the counter part of pushComponentStore(). It removes the last pushed component store, making the store before to the current store again. If any call backs have been registered for the popped component store, they will now be invoked.
        Returns:
        the store that was removed
        Throws:
        FormBuilderException - if an error occurs when invoking call backs
        EmptyStackException - if there are no more stores to pop
      • getEventManagerForForm

        public FormEventManager getEventManagerForForm​(Form f)
        Returns the event manager for the specified form. An event manager is always associated with a Form object; it uses the form's ComponentStore for retrieving the components, for which event listeners are to be registered. With this method an event manager for a given form can be requested. If no such event manager exists, it will be created now. Per default there will be a single event manager for the main form constructed during the build process. However if complex components are involved that construct sub forms (which need their own event handling logic), it may be necessary to have a different event manager.
        Parameters:
        f - the form the event manager is associated with
        Returns:
        the event manager for this form
      • addFormContextListener

        public void addFormContextListener​(FormContextListener listener)
        Adds a FormContextListener object to this data object. The listener receives notifications when a new form context is created or the current context is closed. This method can be called from an arbitrary thread
        Parameters:
        listener - the listener to be registered (must not be null)
        Throws:
        IllegalArgumentException - if the listener is null
        Since:
        1.3
      • removeFormContextListener

        public void removeFormContextListener​(FormContextListener listener)
        Removes the specified FormContextListener from this object.
        Parameters:
        listener - the listener to be removed
        Since:
        1.3
      • pushFormContext

        public void pushFormContext​(Form form,
                                    Object source)
        Installs a new form context for the specified form and passes information about the responsible source. This method can be called by complex components that create their own (sub) form instances. It has the following effect:
        • pushComponentStore() is called with the component store of the specified form. So newly created components will be added to this store.
        • The event manager for this form is obtained using getEventManagerForForm() and made to the active event manager. This ensures that event listener registration logic for the sub form is handled by the appropriate event manager.
        • Registered FormContextListener objects are notified about the newly created context.
        Parameters:
        form - the sub form of the new form context (must not be null)
        source - the source object responsible for the form context
        Throws:
        IllegalArgumentException - if the form instance is null
        Since:
        1.3
        See Also:
        pushComponentStore(ComponentStore), getEventManagerForForm(Form)
      • popFormContext

        public Form popFormContext()
                            throws FormBuilderException
        Removes the outer most form context. Works like the method with the same name, but no information about a source is provided.
        Returns:
        the Form instance of the removed form context
        Throws:
        FormBuilderException - if an error occurs when closing the current form context
        IllegalStateException - if pushFormContext() has not been called before (and the context to be removed is the root context)
      • popFormContext

        public Form popFormContext​(Object source)
                            throws FormBuilderException
        Removes the outer most form context passing in information about the responsible source. This method is the counter part of pushFormContext(). It makes the previous form to the active form again (and ensures that the correct component store and event manager are selected. This method must be called after processing of a sub form has completed. Note: This method calls popComponentStore() to make the component store of the previous form to the current one. Clients must be aware that the calls to the push and pop methods must be symmetric and correctly nested, otherwise the association between the current forms and their component stores may get lost!
        Parameters:
        source - the source object responsible for the form context
        Returns:
        the Form instance of the removed form context
        Throws:
        FormBuilderException - if an error occurs when closing the current form context
        IllegalStateException - if pushFormContext() has not been called before (and the context to be removed is the root context)
        Since:
        1.3
        See Also:
        pushFormContext(Form, Object)
      • getContextForm

        public Form getContextForm()
        Returns the form of the current form context. While the getForm() method always returns the main form of this builder operation, this method takes the current form context into account, i.e. if pushFormContext() has been called before, the form passed to this method will be returned.
        Returns:
        the form of the current form context
        See Also:
        pushFormContext(Form)
      • storeComponent

        public void storeComponent​(String name,
                                   Object component)
        Stores the specified component in the current ComponentStore. From there it can be accessed e.g. if another component defines a reference to it.
        Parameters:
        name - the name of this component
        component - the component itself
      • getComponent

        public Object getComponent​(String name)
        Returns the component with the given name from the currently active ComponentStore. If no such component can be found, the method tries to find a component handler with this name and extract the component object from this handler. If this fails, too, null is returned.
        Parameters:
        name - the name of the desired component
        Returns:
        the component
      • storeComponentHandler

        public void storeComponentHandler​(String name,
                                          ComponentHandler<?> handler)
        Stores the given component handler in the current ComponentStore. From there it can later be accessed, which is useful if it is referenced by other tags.
        Parameters:
        name - the name of this component handler
        handler - the handler itself
      • getComponentHandler

        public ComponentHandler<?> getComponentHandler​(String name)
        Returns the component handler with the specified name from the current ComponentStore. If no such handler can be found, return value is null .
        Parameters:
        name - the name of the desired handler
        Returns:
        the handler
      • storeFieldHandler

        public void storeFieldHandler​(String name,
                                      FieldHandler fld)
        Stores the specified field handler. This field will be added to the internally maintained form object. The component that is associated with the field handler will also be accessible by the getComponent(String) and getComponentHandler(String) methods.
        Parameters:
        name - the name of the field
        fld - the field handler
      • getFieldHandler

        public FieldHandler getFieldHandler​(String name)
        Returns the field handler with the specified name from the current ComponentStore object. If no handler exists with this name, null is returned.
        Parameters:
        name - the name of the desired field handler
        Returns:
        the field handler with this name
      • getWidgetHandler

        public WidgetHandler getWidgetHandler​(String name)
        Returns a WidgetHandler for accessing the component with the given name. A component with this name is searched in the current ComponentStore object. If it cannot be found, null will be returned. Otherwise the current ComponentManager is asked to create a WidgetHandler object for this component. A once created WidgetHandler object will be cached, so that it can be directly returned if it is queried for the second time.
        Parameters:
        name - the name of the component
        Returns:
        a WidgetHandler object wrapping this component
      • getWidgetHandlerForComponent

        public WidgetHandler getWidgetHandlerForComponent​(Object component)
        Returns a WidgetHandler object for the specified component. This method checks whether already a WidgetHandler for the passed in component has been created (by looking it up in the internal cache). If this is the case, it can be directly returned. Otherwise the current ComponentManager is asked to create a new WidgetHandler instance now. If the passed in component is null, null will be returned.
        Parameters:
        component - the component, for which a WidgetHandler is to be obtained
        Returns:
        the WidgetHandler for this component
      • addComponent

        public void addComponent​(Object comp,
                                 Object constraints)
                          throws FormBuilderRuntimeException
        Adds the specified component to the root container. This method is called by component tags that are not nested inside container tags.
        Specified by:
        addComponent in interface Composite
        Parameters:
        comp - the component to add
        constraints - the constraints for this component
        Throws:
        FormBuilderRuntimeException - if no root container was set
      • setLayout

        public void setLayout​(Object layout)
        Sets the layout for the root container. This method is called by layout tags that are not nested inside container tags.
        Specified by:
        setLayout in interface Composite
        Parameters:
        layout - the layout object to set
      • getContainer

        public Object getContainer()
        Returns the concrete container component. In this case this is the root container.
        Specified by:
        getContainer in interface Composite
        Returns:
        the container component
      • disableCallBacks

        public void disableCallBacks()
        Disables the call back mechanism. Newly added callbacks are ignored and will not be executed by invokeCallBacks(). Calls to this method can be nested. A corresponding number of enableCallBacks() is necessary in order to enable callbacks again.
        Since:
        1.3
      • enableCallBacks

        public void enableCallBacks()
        Enables the call back mechanism. This is the counter part of disableCallBacks().
        Since:
        1.3
      • isCallBacksEnabled

        public boolean isCallBacksEnabled()
        Returns a flag whether the call back mechanism is currently enabled. If this method returns false, all callbacks added to this object are ignored.
        Returns:
        true if callbacks are enabled, false otherwise
        Since:
        1.3
      • addCallBack

        public void addCallBack​(ComponentBuilderCallBack callBack,
                                Object param)
        Registers the specified call back at this builder data object. It will be invoked after the building operation is complete for the current form context.
        Parameters:
        callBack - the call back object
        param - a parameter object; this object is passed to the call back when it is invoked
      • invokeCallBacks

        public void invokeCallBacks()
                             throws FormBuilderException
        Invokes all call backs that are registered at this object for the current form context.
        Throws:
        FormBuilderException - if an exception is thrown by one of the call backs
      • beanNames

        public void beanNames​(Set<String> names)
        Returns a set with the names of all contained bean. This implementation returns the names of all stored components. If these components are associated with handlers, the correspondingly prefixed names are also contained in the set.
        Specified by:
        beanNames in interface SimpleBeanStoreImpl.BeanContributor
        Parameters:
        names - the set in which to store the names of the managed beans
      • getBean

        public Object getBean​(String name)
        Returns the bean with the given name. This implementation supports the names of the stored components. If for a component a ComponentHandler, a FieldHandler, or a WidgetHandler is available, the correspondingly prefixed name is also supported. In addition the other reserved keys as described in the header comment can be used.
        Specified by:
        getBean in interface SimpleBeanStoreImpl.BeanContributor
        Parameters:
        name - the name of the desired bean provider
        Returns:
        the bean with this name or null
      • initBeanStore

        public void initBeanStore​(SimpleBeanStoreImpl store)
        Initializes the specified bean store object. This method is called by the builder when the BeanContext used during the builder operation is constructed. This implementation will add the static beans to the given store and register this object as BeanContributor.
        Parameters:
        store - the store to be initialized
      • getBeanContext

        public BeanContext getBeanContext()
        Returns the BeanContext managed by this instance. If not context has been set, a default context will be returned, which allows access only to the beans defined in this object (i.e. the components created during the builder operation and their handlers). Typically the builder will create a context in the initialization phase of a builder operation.
        Returns:
        the context maintained by this instance
      • setBeanContext

        public void setBeanContext​(BeanContext ctx)
        Allows to set a specific BeanContext. This is not necessary normally, because the bean context is correctly set up automatically taking account the appropriate hierarchy of contexts and bean stores.
        Parameters:
        ctx - the new bean context to be used
      • getDefaultButtonName

        public String getDefaultButtonName()
        Returns the name of the default button. This can be null if no default button has been set.
        Returns:
        the name of the default button
      • setDefaultButtonName

        public void setDefaultButtonName​(String defaultButtonName)
        Sets the name of the default button. This method is called by a button tag if the button is marked as default button of the current window. Window tags can evaluate this property to decide whether some action is necessary to actually make this button the window's default button.
        Parameters:
        defaultButtonName - the name of the default button; can be null to clear the default button
      • getCancelButtonName

        public String getCancelButtonName()
        Returns the name of the cancel button set for the current window. This can be null if no cancel button has been set.
        Returns:
        the name of the cancel button or null
        Since:
        1.4
      • setCancelButtonName

        public void setCancelButtonName​(String cancelButtonName)
        Sets the name of the cancel button for the current window. This method is called by a button tag if the button is marked as cancel button. The property is then evaluated for the handling of the Escape key in windows.
        Parameters:
        cancelButtonName - the name of the cancel button; can be null to clear the property
        Since:
        1.4
      • put

        public void put​(org.apache.commons.jelly.JellyContext ctx)
        Stores this instance in the specified context. From there it can be retrieved using the get() method.
        Parameters:
        ctx - the Jelly context (must not be null)
        Throws:
        IllegalArgumentException - if the context is null
      • get

        public static ComponentBuilderData get​(org.apache.commons.jelly.JellyContext ctx)
        Returns the instance of this class stored in the specified Jelly context. If no such instance can be found, null is returned.
        Parameters:
        ctx - the Jelly context
        Returns:
        the instance of this class stored in this context
      • createEventManager

        protected FormEventManager createEventManager()
        Creates the event manager object. This method is called when the event manager is accessed for the first time. It creates a new instance of FormEventManager and initializes it with the platform specific event manager obtained from the component manager.
        Returns:
        the new event manager
        Throws:
        FormBuilderRuntimeException - if no component manager was set
      • createPlatformEventManager

        protected PlatformEventManager createPlatformEventManager()
        Creates the platform specific event manager. This method is called once on first access to the platform event manager. This implementation obtains the event manager from the component handler.
        Returns:
        the platform specific event manager
        Throws:
        FormBuilderRuntimeException - if no component manager was set
      • createToolTipManager

        protected ToolTipManager createToolTipManager()
        Creates the ToolTipManager. This method is called when the ToolTipManager is accessed for the first time, but no specific instance has been set. This implementation creates a default tool tip manager object.
        Returns:
        the new ToolTipManager instance