Based on the first draft of this document I separated the core EJX stuff from the EJX examples to make it a little bit more clear. Afterwards I implemented these changes in the EJX module of jBoss CVS server. If you now download the EJX module you can create a slim release of EJX without the examples. If you need them you can just jump to the examples directory and build the example from there (one by one) and only the examples you want or need.

To go through this document download the EJX module from the jBoss CVS server. Attention: Before you start with compiling any examples you have to run the compilation of the core project first. For this go to the "ejx/src/build" and start the build.bat file. This compiles the core project, copies the necessary jar-files to the right place and creates the necessary ejxeditor.jar file. Now you are ready for the examples.

This example can be found under "ejx/examples/plain.pane". This was my first example and the goal was to creat a Panel within EJX framework to display just a simple text. I used this example to find simplest example within EJX. According to the EJX spec the only necessary thing you have to to is:

Now the only thing left is to start EJX (go to ejx/dist/bin directory and start EJX with "java -jar ejx.jar"). When the EJX Frame comes up go to file/new and select "Plain Pane XML" and you will see our plugin coming up. Now let's have a closer look to the classes we created in our plugin.

Implements the com.dreambean.ejx.FileManagerFactory and enables the EJX framework to select the right file for you. But now let's delf into the code

Classes to be imported

                         import java.io.File; 
				 import javax.swing.filechooser.FileFilter; 
                         import com.dreambean.ejx.FileManager; 
                         import com.dreambean.ejx.FileManagerFactory; 
				 

Class definition (to extend this class from FileFilter is just convenience because it is needed either way):

                         public class FileManagerFactoryImpl extends FileFilter
                         implements FileManagerFactory 

These methods must be implement due FileManagerFactory interface. The first method creates the FileManager when a file is selected or in a given directory a new one can be created. The second method returns a FileFilter to select a file or directory and the last is used to get a name for the Plugin to select the right one.

  
                         public FileManager createFileManager() { 
					return new FileManagerImpl( this ); 
                         } 
				 public FileFilter getFileFilter() { 
					return this; 
				 } 
				 public String toString(){ 
					return "Plain Pane XML"; 
				 } 
				 

Implements the com.dreambean.ejx.FileManager and enables the plugin to decide what GUI element to display. For each file or directory selected a new instance of this class is created.

Classes to be imported

  
                         import java.awt.BorderLayout; 
				 import java.awt.Component;
                         import java.beans.beancontext.BeanContextServicesSupport;
                         import java.io.File; 
				 import javax.swing.JPanel; 
				 import javax.swing.JLabel; 
				 import com.dreambean.ejx.FileManager;
                         import com.dreambean.ejx.FileManagerFactory; 
				 

I am only so pitty about what classes are imported to show you at the header where the used classes are coming from. Constructor of the class:

 
                         FileManagerImpl( FileManagerFactory pCaller ) { 
					mFactory = pCaller; 
				 } 
				 

Methods must be overwriten by the class, The important part is the getComponent() method which is called by the EJX framework to get the GUI component to be displayed.

 
                         public boolean isChanged() { 
					return true; 
				 } 
				 public void createNew() {
				 } 
				 public void load( File file ) throws Exception {
				 } 
				 public void save( File f ) throws Exception{
                         } 
				 public File getFile() { 
					return null; 
				 } 
				 public void setFile( File pFile ) {
				 } 
				 public FileManagerFactory getFactory() {
				  return mFactory; 
				 } 
				 public Component getComponent() {
					 JPanel lPane = new JPanel( new BorderLayout() ); 
					 lPane.add( new JLabel(
                             "<HTML><BODY><H1>Hello World</H1>" 
					 + "<H2>Next Step</H2></BODY></HTML>" ), 
						BorderLayout.CENTER ); 
				   return lPane;
				 }
                         

This example can be found under "ejx/examples/simple.component". This example is an introduction to AWT and how it can be used to define a GUI by the XML description file, compiled and display on the Panel in the EJX framework. To shorten the further discussion I only show the important stuff having changed or is new.

The only thing with AWT you have to consider is that you have to use XMLBeans to compile the BeanInfo XML description into a Java class and then to compile it to a java bytecode class. For that have a look at the build.xml and look for xmlbeans.

According to the AWT spec the only necessary thing you have to to is:

That's it.

Like the one before except the getComponent() method:

              public Component getComponent() { // Create the Property Container and
                return its GUI component return new MainPane().getComponent(); 
	      } 
	      

This class now creates the GUI component using AWT to display the properties this class have.

Classes to be imported

                         import java.awt.BorderLayout; 
				 import java.awt.Component;
                         import java.beans.beancontext.BeanContextSupport; 
				 import java.beans.beancontext.BeanContextChildComponentProxy;
                         import javax.swing.JPanel; 
				 import com.dreambean.awt.GenericCustomizer; 
				 

This class has to supclass the BeanContextSupport

                         public class MainPane extends BeanContextSupport 

There are the properties the Main Pane offer and which can then be set by GUI component defined by the Bean Context Attention: All the properties in the BeanInfo XML file need here a public getter and setter method with the appropriate type.

 
                         public String getFirstProperty() { 
					return mFirstProperty;
                         } 
				 public void setFirstProperty( String pToSet ) {
					mFirstProperty = pToSet; 
				 } 
				 public String getSecondProperty() { 
					return mSecondProperty; 
				 } 
				 public void setSecondProperty( String pToSet ) { 
					mSecondProperty = pToSet; 
				 }
				 

This method returns the GUI component which contains the Generic Customizer need to display the properties of this instance accordingly to the Bean Info XML description mentioned above.

        		     public Component getComponent() { 
					JPanel lPane = new JPanel( new BorderLayout() );
				 lPane.add( new GenericCustomizer( this ), BorderLayout.CENTER ); 
				    return lPane; 
				 } 
			     

Eh voilà, that's it. When you build this example, start EJX and select Simple Component XML you will see two lines with the tag "First Property" and a Text Field (and also for Second Property).

That's all for now. In the next step I will delf further into AWT and how you can use the Bean Info XML description to describe more advanced application. In addition I will then use the save() and load() method to load XML files which are the persistent part of a plugin.

I anything is wrong or not correct please contact me at [email protected]. Also if you want to know more in detail or have a request for changes in this HowTo document.

From the last example of the first How To create and remove GUI Components (Tabbed Panes) dynamically and edit the properties of the data instance with the AWT editors.

First of all I want correct I mistake in the previous example. In the MainPane class it is said that getComponent() is implemented because of BeanContextChildComponentProxy which is not implemented in the class but it works because the caller does not relay on this fact. But in this example I fixed this. The question but still remains why it should (will maybe be explained later).

This example is really not a good example how to use EJX but it shows how to use EJX/AWT. The idea is to use a tabbed pane to display different views in our EJX frame. In addition the user can create and remove the tabbed pane as long as there is at least one left. And last but not least the user should be able to select a value through an editor instead of a plain input field.

As we saw in the last example the initial GUI component to show the plugin is created in the ResourceManager on the getComponent() call which is called by the BeanContext structure we use. But instead of create a Panel which just keeps the GUI of the plugin we create now a viewer of the plugin to display itself. This makes the design more flexible because it is now defined in the Viewer instead of the ResourceManager where it does not belong. Now the viewer is an inner class because it is so closely related to its outer component that it makes sense to be there.

The construct following is a little bit ugly and should not be MADE this way but it is enough for us. The ResourceManager getComponent() now calls the MainPane's getComponent() method and this instantiate its viewer and returns this Viewer as the GUI component to be shown.

When the users now hits the create a new Tab or remove this tab the appropriate method is called (by the BeanContext) and it will create a new MainPane instance and adds its also created Viewer instance as a new Tab to the tabbed pan or remove the actual shown tab from the tabbed pane. As you can see above the buttons we have a text input field and a drop down box letting the user select between two items. Both are AWT editors.

First lets have a look at the changes in the ResourceManager where the getComponent() just instanciate the MainPane and returns its GUI component.

              public Component getComponent() { 
	         // Create the Property Container and return its GUI component
                 return new MainPane().getComponent(); 
	      } 
	      

Now let's look at the new BeanInfo description of the MainPane:

    
              <bean class="com.madplanet.tabbedEditor.MainPane"
              displayname="Tab Pane and Editor's Main Pane"
              iconcolor16="/images/container.gif"> <property
              name="FirstProperty" class="java.lang.String"
              displayname="First Property"
              propertyeditor="com.dreambean.awt.editors.TextEditor"/>
              <property name="SecondProperty"
              class="java.lang.String" displayname="Second
              Property"
              propertyeditor="com.madplanet.tabbedEditor.editors.SecondPropertyEditor"/>
              <method name="createTab" displayname="Create a new
              Tab"> <parameter displayname="Title"/> </method>
              <method name="removeTab" displayname="Remove this
              Tab"> </method> </bean> 
              

As you can see there are property editors settings for the first and second property and the second property uses its own editors. In addition you have methods listed which appears as buttons in the GUI because we use the GenericCustomizer.

The new editor is just a simple subclass of the AWT TagsEditor defining what items it has to show and to what value the item relate to (you can use any Java Object you like):

              package com.madplanet.tabbedEditor.editors; 
              import com.dreambean.awt.editors.TagsEditor; 
              /** * Editor to select the Second Property in a DD - editor */
              public class SecondPropertyEditor extends TagsEditor
              { // Constructors
              --------------------------------------------------
                public SecondPropertyEditor() { 
            		super(new String[] {"First Selection","Second Selection"}, 
         		new Object []{"First", "Second"}); 
	        } 
	      } 

And as "Grande Finale" we come to the heart of the plugin to the MainPane class.

The new viewer class is an inner class to the MainPane and creates a GUI to display the instance of its outer class instance. It keeps a list of outer class instances to find the index of the tab to be removed. The setObject() creates a new tab and memorize the given outer class. The removeTab() looks for the given outer instance and removes its related tab (by this index).

                      public class Viewer extends JTabbedPane implements Customizer { // Attributes
                      ---------------------------------------------------
                      private Vector mDataObjectList = new Vector(); // Customizer implementation
                      ------------------------------------
                      public void setObject( Object pDataObject ) { 
				// Init UI
    	                  addTab( "Main", new GenericCustomizer( pDataObject ) );
	                  mDataObjectList.addElement( pDataObject ); 
			  } 
			  /** * Removes the given Tab with the given Data Object * from the
                      Tabbed Pane * * @param pDataObject Tab with this Data
                      Object has to be removed if found **/ 

			  public void removeTab(Object pDataObject ) { 
				int lIndex = mDataObjectList.indexOf(
                         pDataObject ); 
				if( lIndex >= 0 ) { 
					remove( lIndex );
     		            mDataObjectList.removeElementAt( lIndex ); 
				} 
			  } 
			 } 

These are the new methods (already defined in the BeanInfo see above) which are called if the appropriate button is pressed.

                      public void createTab( String pTitle ) throws Exception { 
			    System.out.println("Create new Tab with title: " + pTitle);
				MainPane lNewPane = new MainPane();
                        lNewPane.mCustomizer = mCustomizer;
                        lNewPane.mCustomizer.setObject(
                        lNewPane ); 
			  } 
			  public void removeTab() {
     	                 System.out.println( "Remove this tab"); 
				 ( (Viewer) mCustomizer ).removeTab(this ); 
			  }