Page Comparison

Requires Platform 4.2+

• Plug-ins

• Plug-in Packaging

Plug-insThe

Nexaweb Client plug-in architecture allows developers to extend the functionality of the Nexaweb Client for Nexaweb Java applications by implementing their own tags, attributes and XML syntax. Developers commonly extend the functionality through new UI components; however, you can also implement logical operations, layout panes, or any other custom logic.

A typical use case involves including advanced charting capabilities in the Nexaweb Client. Although the client comes with some built in charting ability, it may not be sufficient to display certain advanced charts like those found in financial applications. Using the plug-in architecture, developers can integrate a 3rd-party chart component of their choice and define their own XML tags and format to display that chart. That chart can then be imbedded inside of standard XAL.

Example:

...

Client プラグインアーキテクチャは、開発者が独自のタグや属性、XML シンタックスを実装できるよう設計されており、これによってNexaweb Java アプリケーション用Nexaweb Client の機能を拡張できます。通常、開発者は新しいUI コンポーネントを通じて機能を拡張しますが、論理演算やレイアウトペインなどのカスタムロジックを実装することも可能です。

Nexaweb Client での一般的な使用例の1 つとして、高度なチャート機能の使用が挙げられます。Nexaweb Client には組み込みのチャート機能が付属していますが、この機能は財務アプリケーションに見られるような高度なチャートの表示には不十分な場合があります。プラ グインアーキテクチャを使用すると、開発者はサードパーティのチャートコンポーネントを統合して独自のXML タグを定義し、フォーマット設定してそのチャートを表示することができます。その後このチャートを標準のXAL の内部に組み込むことができます。

例:

<window>
    <borderPane/>
    <label text="A custom chart" borderPosition="north" />
   
    <!-- a specialized chart created via the plug-in architecture -->
    <financialChart title="Dow Jones by year" 
                borderPosition="center" onSelect="myPage.jsp>
    <xAxis start="1950" end="2005"/>
    <yAxis start="0" y="5000"/>
    <pointData points="1900,2000,2020 ...  <!-- a specialized chart created via the plug-in architecture -->
    <financialChart title="Dow Jones by year" 
       borderPosition="center" onSelect="myPage.jsp>
    <xAxis start="1950" end="2005"/>
    <yAxis start="0" y="5000"/>
    <pointData points="1900,2000,2020 ... "/>
    </financialChart>
</window>

Technical Overview

At the most basic level, a plug-in is a class that extends com.nexaweb.client.tags.AbstractTagImpl and listens for changes on XML elements. These changes come in the form of com.nexaweb.xml.events.StructureChangeEvent and com.nexaweb.xml.events.AttributeChangeEvent. These classes are called tag-handlers, as each tag name has its own handling class. These classes can also be referred to as bridge classes because they form a bridge between XML and implementation classes, referred to as peers.

AbstractTagImpl is the base class for all plug-ins. In addition, a number of subclasses exist to ease the creation of certain types of plug-ins. For example, you can use ContainerBridge or SwingBridge as subclasses to create UI Components based on java.awt.Component or javax.swing.JComponent. In addition, you can use JComponent to implement custom java.awt.LayoutManager classes.

In the example above, the developer has some third-party charting components that serve as the peers. The handling classes that extend AbstractTagImpl are responsible for manipulating these peers based on changes in the XML, as well as responding to changes in the peer classes.

AbstractTagImpl and its subclasses automatically listen for StructureChangeEvents and AttributeChangeEvents their associated XML elements. It is the responsibility of the individual subclasses to perform some meaningful operation when attributes change or child tags are added and removed. Similarly, subclasses can listen for changes to a peer object and fire events or update the UI Document Object Model (DOM) based on those changes. The bridge class is a two way bridge in that is listens for XML changes and passes them on to the peer, and listens for peer changes and fires events or updates the DOM based on those changes.

Care should be taken to ensure that plug-ins will run in the desired JVMs. A UI component plug-in based on Swing will only run on Swing-compatible (1.2+) JVMs.

Developing a JButton Plug-in

This section develops a simple plug-in that will map the <jButton> tag to a JButton component. The <jButton> tag will understand basic attributes such as backGroundColor. In addition the <jButton> tag will implement an attribute named "armed" as a boolean, and fire onCommand events when activated.

The first step in developing the <jButton> tag is creating the tag-handler that will map to the <jButton> tag. JButton is a Swing-based component, so our class will extend SwingBridge. When a <jButton> tag is first encountered, the parser will instantiate an instance of our JButtonBridge and call some initialization methods on it. One of those methods, init(), in turn calls createUiComponent(). We must override this method to create our desired UI component as follows:

public class JButtonBridge extends SwingBridge {
        public void createUiComponent(){
        setUiComponent(new JButton() );
    }
}

At this point, our bridge class will create a JButton component, and will automatically respond to basic attributes like bgColor. We would also like this tag to respond to the "armed" attribute. We can do this by overriding onAttributeSet() to handle the new attribute.

public void attributeSet(AttributeChangeEvent e) 
    throws AttributeConversionException {
    String attributeName = e.getName();
    String attributeValue = e.getNewValue();
    //if the attribute is "armed" set it to true or false
    if ("armed".equals(attributeName) ){
        ( (JButton)getUiComponent() ).getModel().
           setArmed(AttributeConverter.toBoolean(attributeValue));
    }
    //otherwise just fall through
    else super.attributeSet(e);
}

AttributeConverter is a utility class that provides methods that convert Strings to booleans, Color, enumerations and other data types. Overriding attributeSet and using AttributeConverter makes any errors in the XML report in the usual manner.

Now that our <jButton> can respond to an attribute change, we would also like the <jButton> to report "onCommand" events when the JButton ActionListener is called. We do that by implementing ActionListener and adding ourselves as a listener to the JButton. Then when actionPerformed() is called we simply call a method from AbstractTagImpl that handles the firing of the event. The following is the final code for JButtonBridge with the most recent changes highlighted.

 public class JButtonBridge extends SwingBridge 
                                  implements ActionListener{
    public void createUiComponent(){
        JButton b = new JButton();
        setUiComponent(b);
        //listen for action events so we can report them
        b.addActionListener(this); 
    }
     
    public void actionPerformed(ActionEvent e){
        //call the method from AbstractTagImpl that 
        //reports the event
        //fill in a ClientEvent object and calls the 
        //appropriate MCO/JSP/event handler
        fireEvent("onCommand",null);
    }
     
    public void attributeSet(AttributeChangeEvent e) 
                         throws AttributeConversionException{
        String attributeName = e.getName();"/>
    </financialChart>
</window>

技術的な概要

最も基本的なレベルでは、プラグインはcom.nexaweb.client.tags.AbstractTagImpl を拡張するクラスであり、XML 要素に対する変更をリスンします。このような変更は、

com.nexaweb.xml.events.StructureChangeEventおよび
com.nexaweb.xml.events.AttributeChangeEventの形式で行われます。これらのクラスは、各タグ名にそれぞれが処理するクラスが含まれるため、タグハンドラと呼ばれます。また、これらのクラスは、XML と実装クラス(ピア) 間のブリッジを形成するため、ブリッジクラスとも呼ばれます。

AbstractTagImpl は、すべてのプラグインの基本クラスです。また、プラグインをタイプ別に簡単に作成できるように、多数のサブクラスが存在します。たとえば、ContainerBridge またはSwingBridge をサブクラスとして使用すれば、

java.awt.Component またはjavax.swing.JComponent に基づいたUI コンポーネントを作成できます。さらに、JComponent を使用して、独自のjava.awt.LayoutManager クラスを実装することもできます。

上記の例では、開発者は、ピアとして機能するサードパーティ製チャートコンポーネントをいくつか使っています。AbstractTagImpl を拡張するハンドラクラスは、ピアクラスでの変更に応答するだけでなく、XML での変更に基づいてこれらのピアを操作します。
AbstractTagImpl とこのサブクラスは、StructureChangeEvents とAttributeChangeEvents、関連するXML 要素を自動的にリスンします。属性が変更されたり、子タグの追加や削除が行われた際には、各サブクラスが適切な操作を実行します。同様にサブクラスは、ピ アオブジェクトへの変更をリスンしてイベントを発生させたり、変更に基づいてUI DOM (Document Object Model) を更新することができます。ブリッジクラスは、双方向のブリッジです。一方ではXML の変更をリスンしてピアに渡し、他方ではピアの変更をリスンしてイベントを発生させたり、変更に基づいてDOM を更新します。

このプラグインを目的のJVM で実行するには、注意が必要です。Swing に基づいて作成されたUI コンポーネントプラグインは、Swing と互換性のある(1.2+) JVM でしか実行できません。

JButton プラグインの開発

ここでは、JButton コンポーネントに<jButton> タグをマップする簡単なプラグインを開発します。<jButton> タグは、backGroundColor などの基本的な属性を認識します。また、<jButton> タグは"armed" という名前のブール型の属性を実装し、有効化された際にonCommand イベントを発生させます。
<jButton> タグの開発での最初の手順では、<jButton> タグにマップするタグハンドラを作成します。JButton はSwing に基づいたコンポーネントなので、クラスはSwingBridge を拡張します。パーサーは、初めて<jButton> タグを検出した際に、このJButtonBridge のインスタンスをインスタンス化し、これに対する初期化メソッドを呼び出します。これらのメソッドの1 つであるinit() が、順にcreateUiComponent() を呼び出します。目的のUI コンポーネントを作成するには、次のようにこのメソッドをオーバーライドする必要があります。

public class JButtonBridge extends SwingBridge {
        public void createUiComponent(){
        String attributeValue = e.getNewValue(setUiComponent(new JButton() );
        //if the attribute is }
}

この時点で、ブリッジクラスがJButton コンポーネントを作成し、bgColor などの基本的な属性に自動的に応答します。また、このタグを"armed"

...

属性に応答させる必要があります。これには、onAttributeSet() をオーバーライドして、新しい属性を処理させます。

public void attributeSet(AttributeChangeEvent e) throws AttributeConversionException {
    String attributeName if ("armed".equals(attributeName) ){= e.getName();
    String attributeValue = e.getNewValue();
    //if ( (JButton)getUiComponent() ).getModel().
      the attribute is "armed" set it to true or false
    if  setArmed(AttributeConverter"armed".toBooleanequals(attributeValueattributeName) );{
        }
        //otherwise just fall through
    ( (JButton)getUiComponent() ).getModel().setArmed(AttributeConverter.toBoolean(attributeValue));
   else super.attributeSet(e); }
    }
}

Now that our JButtonBridge is complete we must add a mapping so that our <jButton> tag is defined and handled by the JButtonBridge class. To do this we must create a tag mapping file with the appropriate entry, then add that file to our list of tag mapping files in the client configuration. The tag mapping file itself is simply a list of tag names with the name of the handling class as the text. We will call this file customTagMappings.xml:

<tag-mappings>
    <jButton>JButtonBridge</jButton>
</tag-mappings>

Once this file is created we must add an entry to nexaweb-client.xml:

<client-tag-mapping>
    <tag-map-file>customTagMappings.xml</tag-map-file>
</client-tag-mapping>

Plug-in Architecture Class Survey

The following table lists and provides brief descriptions of the plug-in related classes:

...

The base class for all plug-ins.

...

A subclass of ContainerBridge for Swing-based plug-ins

...

Plug-in Class Lifecycle

When a new XAL block is appended to the existing UI DOM:

1. The name of the class associated with the root element is looked up.
2. The class is loaded if not loaded already.
3. A new instance of the handler class is created.
4. setSession() is called on the handler with the current ClientSession.
5. The handler is added to the XAL element as a StructureChangeListener and AttributeChangeListener.
6. setElement() is called on the handler with the XAL element.
7. init() is called on the handler.
8. The "onCreate" event is fired on the handler.

This process is performed only once for the entire XAL block. The root element of that block may have children and/or initial attributes set on it. AbstractTagImpl provides two methods which can be called in init() to handle these situations. The "parseInitialChildren()" method will repeat this parsing process for all children of the initial element. The "parseInitialAttributes()" method will feed the attributes on the initial element through onAttributeSet() as if they were being set after the element was created. In addition, ContainerBridge will call these methods by default in its init() method.

When an XAL block is removed from the UI DOM:

1. unload() is called on the handler for the root element.
2. The handler is removed from the XAL element as a StructureChangeListener and AttributeChangeListener
3. The handler calls afterChildRemoved(), which recursively repeats the process for each child element of the root Element being removed.

If there is a handler class override onChildRemoved(), it must be sure to call afterChildRemoved() to make sure the recursive clean-up takes place.

Packaging Plug-Ins

Plug-ins consists of three sets of resources: tag-mapping files, the tag-handler classes and the peer classes. In our example the JButton peer class is included in any Swing-compatible JVM, but often peer classes will come in separate JAR files.

Tag-handling classes and peer classes follow the same deployment rules as MCOs, and tag-mapping files are considered standard files. Some developers may find it easier to combine their tag-mapping files and classes into a JAR file. For example, our JButtonBridge class and customTagMappings.xml may be in a JAR filed called "jButtonPlugin.jar." In that case we would have to change the nexweb-client.xml classpath to include that jar, and change the tag-mapping location to use the "classpath://" specifier. See the documentation on nexaweb-client.xml for more on adjusting the client classpath.

<!-- classpath changed to include our plug-in jar file -->
<client-classpath>
    <pre-loaded-in-applet-def>
    <archive name="jButtonPlugin.jar" 
       path="/WEB-INF/client/lib/jButtonPlugin.jar"/>
    </pre-loaded-in-applet-def>
</client-classpath>

<!-- load the tag mapping file from the classpath -->
<client-tag-mapping>
    <tag-map-file>classpath://customTagMappings.xml</tag-map-file>
</client-tag-mapping>

One final packaging option is to make plug-in classes load on startup, rather than when the tag corresponding to that plug-in is first encountered. Classes loaded at startup load during the Nexaweb loading animation, whereas large plug-ins loaded on the fly can cause the Nexaweb application to freeze for a few seconds. If an application makes consistent and frequent use of a large plug-in, loading it at startup is often the better choice. This can be done by modifying the contents of the tag-mapping file as below:

<tag-mappings>
    <jButton loadPolicy="onStartup">JButtonBridge</jButton>
</tag-mappings>

Defining Plugin Namespaces

Namespaces can be defined for a set of tags.  An example is the Nexaweb Data Framework, which was implemented using the plugin architecture.  The XML that defines this plug-in is:

<tag-mappings namespace="http://openxal.org/core/data" 
    document="bindings">
    <mapping class="com.nexaweb.plugin.data.bridge.BindingBridge" 
        name="binding"/>
</tag-mappings> 

This declares the tag "binding" in the openxal.org/core/data namespace.
 

Overriding Built-in Components

Plugins can be used to replace the behavior of built in XAL tags.  For instance if a plugin was defined as <button> it would replace the built in behavior of button.

...

In Nexaweb 4.2.x, to package and distribute a plug-in for your Nexaweb application, you need to:

• Specify information about the plug-in in a plug-in manifest file
• Place the plug-in JAR file in your application's WEB-INF/client/plugins directory

Adding Plug-in Information to the Plug-in Manifest File

You must add information about each plug-in that you create for your application to the plug-in manifest file, plugin.xml. Nexaweb uses the plug-in manifest to determine the contents of plug-ins.

You add the following sections to the plugin.xml file for each plug-in: 

...

Identifies a unique plug-in to include with this application.

The opening tag can include an optional class attribute that specifies a lifecycle manager or some abstract MCO for the plug-in.

...

Defines tags that the plug-in adds to your application, specifies location of definition file for composite tags, and policy for when the application loads the plug-in.

 The following shows a sample plug-in manifest file:

//otherwise just fall through
    else super.attributeSet(e);
}

AttributeConverter は、文字列をブール型、Color、列挙型などのデータタイプに変換するメソッドを提供するユーティリティクラスです。attributeSet をオーバーライドしてAttributeConverter を使用すると、XML のエラーが通常の方法で報告されます。

<jButton> が属性の変更に応答できるようになったので、次は、JButton ActionListener が呼び出された際に<jButton> が"onCommand" イベントを報告するようにします。これには、ActionListener を実装して、自身をJButton のリスナとして追加します。こうしておけば、actionPerformed() が呼び出された際に、イベントの発生を処理するAbstractTagImpl からメソッドを呼び出すだけで済みます。JButtonBridge の最終的なコードは次のとおりです。最新の変更が強調表示されています。

public class JButtonBridge extends SwingBridge implements ActionListener{
    public void createUiComponent(){
        JButton b = new JButton();
        setUiComponent(b);
        //listen for action events so we can report them
        b.addActionListener(this); 
    }
     
    public void actionPerformed(ActionEvent e){
        //call the method from AbstractTagImpl that reports the event
        //fill in a ClientEvent object and calls the appropriate MCO/JSP/event handler
        fireEvent("onCommand",null);
    }
     
public void attributeSet(AttributeChangeEvent e) throws AttributeConversionException{
        String attributeName = e.getName();
        String attributeValue = e.getNewValue();
        //if the attribute is "armed" set it to true or false
        if ("armed".equals(attributeName) ){
            ( (JButton)getUiComponent() ).getModel().setArmed(AttributeConverter.toBoolean(attributeValue) );
        }
        //otherwise just fall through
        else super.attributeSet(e);
    }
}

JButtonBridge が完了したので、次はJButtonBridge クラスによって<jButton> タグが定義、処理されるよう、マッピングを追加する必要があります。これには、適切なエントリでタグマッピングファイルを作成する必要があります。その 後、このファイルをクライアントコンフィギュレーション内のタグマッピングファイルのリストに追加します。タグマッピングファイル自体は、ハンドラクラス の名前がテキストとして記載された、単なるタグ名のリストです。このファイルをcustomTagMappings.xml と呼びます。

<tag-mappings>
    <jButton>JButtonBridge</jButton>
</tag-mappings>

このファイルが作成されたら、nexaweb-client.xml にエントリーを追加しなくてはなりません。

<client-tag-mapping>
<tag-map-file>customTagMappings.xml</tag-map-file>
</client-tag-mapping>

Plug-in Architecture Class Survey

次の表は、plug-in関連クラスをリスト化し概要を説明しています。
 

Plug-in Class Lifecycle

新しいXALブロックが既存のUI DOMに加えられるとき :

1. ルートエレメントに関連したクラス名が検索される　
2. クラスがロードされていなければ、ロードされる。
3. handler クラスの新しいインスタンスが作成される。
4. 現在の ClientSession で setSession() がハンドラから呼び出される。
5. HandlerはStructureChangeListener とAttributeChangeListener として XAL elementに追加される。
6. setElement() はXAL element で handler に呼び出される。
7. init() はhandler に呼び出される。
8. "onCreate" イベントはハンドラにより呼び出される。

このプロセスは全てのXAL ブロックで一回のみ行われます。そのブロックのroot elementは、それに設定された子および/または最初の属性を持っている可能性があります。AbstractTagImplは、これらの状況に対処す るため、init() に呼び出されることができる2つのメソッドを提供しています。"parseInitialChildren()" メソッドはこのパーシングプロセスを初期elementの全ての子に反復し行います。"parseInitialAttributes()" メソッドは、element作成後に設定されたかのように、onAttributeSet()で初期elementの属性をフィードします。加え、 ContainerBridgeは、その init() メソッドでデフォルトによりこれらのメソッドを呼び出します。

XAL blockがUI DOMから除外された場合 :

1. unload() は root element に対し、handler に呼び出される。
2. handler は StructureChangeListener とAttributeChangeListener として XAL element から除外される。
3. handler は除外された root Element の各子エレメントのプロセスを再帰的に反復する afterChildRemoved() を呼び出します。

onChildRemoved()に優先するhandler classが存在する場合、再帰的更新が発生するようにafterChildRemoved()を呼び出さなくてはなりません。

Packaging Plug-Ins

プラグインはタグマッピングファイル、タグハンドラクラス、ピアクラスの3つのリソースで構成されています。我々の例では、JButton ピアクラスは全ての Swing の互換性のある JVM に含まれますが、時によりピアクラスが別の JAR ファイルに含まれます。

Tag-handling class とピアクラスは MCO と同じ展開ルールに従っていますが、タグマッピングファイルは、標準ファイルとして見なされます。一部の開発者は、タグマッピングファイルとクラスを組み 合わせ、JAR ファイルに入れるのが簡単だということがわかるかもしれません。例えば、JButtonBridge クラスとcustomTagMappings.xml は "jButtonPlugin.jar." と呼ばれるものの中に JAR ファイル化されています。その場合、nexweb-client.xml classpath を変更しその jar を含み、タグマッピングロケーションを変更し"classpath://" specifier. を使用します。nexaweb-client.xml のドキュメントの client classpath 調整についての詳細をご覧ください。

<!-- classpath changed to include our plug-in jar file -->
<client-classpath>
    <pre-loaded-in-applet-def>
    <archive name="jButtonPlugin.jar"
       path="/WEB-INF/client/lib/jButtonPlugin.jar"/>
    </pre-loaded-in-applet-def>
</client-classpath>
 
<!-- load the tag mapping file from the classpath -->
<client-tag-mapping>
    <tag-map-file>classpath://customTagMappings.xml</tag-map-file>
</client-tag-mapping>

最後一つのパッケージオプションは、スタートアップで、そのプラグインにあったタグが初めて遭遇した時に、plug-in class をロードさせることです。スタートアップでロードされたクラスは Nexaweb のローディングアニメーションの最中にロードされますが、一方で、オンザフライでロードされた大規模 plug-in だと Nexaweb のアプリケーションが数秒フリーズしてしまいます。アプリケーションが、大規模 plug-in をコンスタントに、また頻繁に使用される場合、スタートアップの際ロードする方が良いです。これは、以下のように tag-mapping を修正することで可能です。

<tag-mappings>
    <jButton loadPolicy="onStartup">JButtonBridge</jButton>
</tag-mappings>

Plugin Namespaceの定義

Namespaces は、タグ一式で定義することができます。以下の例は、Nexaweb Data Frameworkで、これはプラグイン アーキテクチャを使用し実装されます。このプラグインを定義するXMLは以下です。

<tag-mappings namespace="http://openxal.org/core/data"
    document="bindings">
    <mapping class="com.nexaweb.plugin.data.bridge.BindingBridge"
        name="binding"/>
</tag-mappings>

ここではopenxal.org/core/data namespace のタグ "binding" を宣言しています。

組込みコンポーネントより優先される

プラグインは組込み XAL タグの振る舞いを置換えるために使用することができます。例えば、プラグインが <button> として定義されると、button の本来の振る舞いを置換えます。 

Packaging and Distributing Nexaweb Application Plug-ins

• プラグインのマニフェスト ファイルでプラグインに関する情報を指定する
• プラグインの JAR ファイルをアプリケーションの WEB-INF/client/plugins ディレクトリに配置する

<plugin class="MyPlugins">

 <info>

...

  <provider-name>Nexaweb Technologies</provider-name>
  <author>James</author>
  

...

<description>This plug-in automates automatic automation.

...

</description>
  <version>10.3.4</version>
  <schema-location>schema/plugin.xsd</schema-location>
  <stylesheet-

...

location>stylesheet/stylesheet.

...

xss</stylesheet-location>
 </info>

 <tag-mappings namespace="http://nexaweb.com/charts" 

...

document="nxml">
  <mapping name="barChart" class="com.nexaweb.plugins.BarChart"

...

 icon="barChart.gif" loadPolicy="onStartup"/>
  <mapping name="loginDialog"

...

 class="com.nexaweb.plugins.LoginDialog"

...

 icon="loginDialog.gif" definitionFile="ui/loginDialog.nxml"/>
 </tag-mappings>
</plugin>

The following table provides descriptions of the tags contained in the <info> section:

...

The following table provides descriptions of the tags attributes contained in the <tag-mapping> section:

...

Specifies the namespace under which these tag mappings exist.

...

Specifies a tag name used by the plug-in and that this plug-in adds to the application.

Mapping Name Attributes

...

Specifies any image associated with this tag. Images are relative to the images folder.

...

Plug-in Directory Structure

Nexaweb Studio organizes plug-ins using unique directory structures for build and distribution.

Nexaweb Studio uses the directory structure described in the following table for building a plug-in: 

 Nexaweb Studio uses the directory structure described in the following table for distributing a plug-in: