Package com.nexaweb.client.mco

Provides classes for creating and managing MCOs.

See:
Description

Interface Summary

ContainerLifecycleObject

This interface provides containment-change callbacks to objects placed in application containers, including the MCO container.

Class Summary

AbstractMco	AbstractMco is an optional base class for MCO classes.
Container	Houses objects associated with an application and provides some lifecycle management and notification for objects that implement the ContainerLifecycleObject interface.
McoContainer	McoContainer holds MCOs that are declared via XML, as well as MCOs that are added to the application programatically.

Package com.nexaweb.client.mco Description

Provides classes for creating and managing MCOs.


Intro to MCOs:
MCO stands for managed client object. An MCO is a Java object with a no argument constructor that optinally extends AbstractMco. An MCO can be declare and configured in XML or can be programatically added to an application at runtime.

An MCO can be used as an event-handler defined in XML or can be called via XML directly.

An MCO as an event handler:
<button onCommand="mco://myMco.doSomething()"/>

An MCO called directly from XML:
<mco:execute>myMco.doSomething()</execute>"
The MCO XML Reference contains the exact syntax for declaritive use of MCOs, including initial declaration and configuration of properties, specifying MCOs as event handlers, and invoking MCO methods in XML directly.


MCO Lifecycle Management:
Whenever an MCO is declared in XML, it replaces any MCO that has the same ID as the MCO being added. This MCO being replaced is removed from the MCO container and will have unload() and/or removedFromContainer() called on it.

MCOs can be declared in MCOs as a group or as singular MCOs. A singular MCO is considered a group of size one. When a group is declared, the following operations are performed in order:

1. Any existing MCO with the same ID is removed from the MCO container.
2. The no-argument constructor for each MCO is called.
3. The MCO is added to that ClientSession's McoContainer. From this point forward the MCO can get the ClientSession by calling McoContainer.getClientSessionFromMco(this) or if it extends AbstractMco by calling getSession().
4. Each MCO is configured with the initial properties declared in the XML.
5. The onLoad method (if any) of each MCO is called.

MCOs can be added to a ClientSession programatically rather than declaritively though XML by constructing an Object and calling McoContainer.addMco(). From this point forward the MCO can get the ClientSession by calling McoContainer.getClientSessionFromMco(this) or if it extends AbstractMco by calling getSession().

When an application exits all the MCOs in the MCO container are removed from the MCO container and will have unload() and/or removedFromContainer() called on them.


MCO Parameters:
Declarative (XML) MCO calls can use parameters in the following fashion:

• this - indicates the current element
• this.attName - indicates attribute value of "attName" on the current element
• 5 - an integer
• 5.5 - a double
• true/false - a boolean
• "string" - a string surrounded by double quotes. To include a freestanding " use \" , to include a freestanding \ use \\. Example: "Dave said \"hello\" "
• 'string' - a string surrounded by single quotes. To include a freestanding ' use \' , to include a freestanding \ use \\. Example: 'Dave said \'hello'\ '
• elementId - an element in the UI dom
• elementId.attName - indicates attribute value of "attName" on an element in the UI dom
• container://name - indicates an object in the given container. Container names include "mco" and "document"
• container://name.method(...) - indicates a method call on an obect in the given container
• name.method(...) - indicates a method call on a system service availabe in XML.

An example of MCO parameters
<button text="Press Me" onCommand="mco://myMco.doSomething("hello", true, 5, 5.5, this.text,this)"/>
public void doSomething(String s, boolean b, int i, double d, String attribute, Element e){...}


MCO Threading and Execution:
When an MCO event handler is invoked, it is invoked on the Java event thread. This means that MCO event handlers will block the update of the UI until the event handler is complete. For long operations, MCOs should spawn separate threads or use asynchronous methods.

MCOs invoked via XML directly (using <execute>) can also be invoked in the event thread. (In Java VMs 1.2+)


Thread Safety Considerations:
Whenever an MCO accesses or changes a Document such as the UI Document or a DataSet, the MCO should synchronize on Document.getDomSynchronizationObject(). This includes calls to XPath.

In addition, changes to the UI Document should always occur on the thread the MCO was originally called on. If a background thread needs to modify the UI Document it should do so using the methods in com.nexaweb.client.UiEventQueue, which operates similarly to the SwingUtilities invocation methods like invokeAndWait() and invokeLater().


Compiling and Deploying MCOs:
MCOs should be compiled with the -1.1 target and be Java 1.1 compliant if you intend to use them in the Microsoft or Netscape 4 JVM. In addition, those MCOs should be compiled with a 1.3 compiler rather than 1.4 or 1.5 to ensure maximum compatibility.

Compiled MCOs can be deployed as individual classes or as JAR collections. See the configuration documentation on nexaweb-client.xml for details.