jaxfront developer manual · commons-beanutils.jar apache jakarta common beanutils 1.5...

JAXFront Developer Manual – Java Client Renderer Version 2.61

www.jaxfront.com 1-39

xcentric technology & consulting Oberwiesenstrasse 5 CH - 8057 Zurich Switzerland +41 (0)43 255 01 69

JAXFront®

Developer Manual Java Client-Renderer

V2.70

http://www.jaxfront.com [email protected]



Document description

Author(s) M.Leber, S.Portmann [email protected]

Version 2.70

Web link http://www.jaxfront.com/download/JAXFront-Developer-Manual-V2.pdf

Classification

not classified internal confidential secret

Processing status

draft/in processing

Ready for acceptance

definitive version

Conventions used in this document

Image Meaning

Points to an example-syntax in XML.

Points to a code example in Java.

Refers to important information.

Describes a previously presented example..

Copyright © 2001 - 2011 xcentric technology & consulting GmbH. All Rights Reserved.

Use of this documentation and related software is governed by a License Agreement. This document does not imply a legal contract. Readers assume responsibility for the use and interpretation of the information contained herein. xcentric technology & consulting GmbH strives to ensure the accuracy of the provided instructions but it does not accept any liability or damages for omissions contained in this manual.



TABLE OF CONTENTS 1 INTRODUCTION .................................................................................................................. 5

2 SETTING UP ENVIRONMENT ............................................................................................. 6

2.1 BASIC INSTALLATION ............................................................................................................ 6 2.2 DIRECTORY STRUCTURE ....................................................................................................... 6 2.3 RUNTIME ENVIRONMENT ....................................................................................................... 7 2.3.1 JAXFront license file deployment .................................................................................... 8 2.3.2 How to integrate/use a plugin in the XUI-Editor .............................................................. 9

2.4 RUN JAXFRONT ................................................................................................................... 9 2.5 UNINSTALLING JAXFRONT .................................................................................................... 9 2.6 EXPLORE JAXFROM DEMO SUITE ....................................................................................... 10

3 BUILDING A JAXFRONT DOM ......................................................................................... 11

3.1 THE JAXFRONT DOCUMENT OBJECT MODEL (DOM) ............................................................ 11 3.1.1 Build a new JAXFront DOM .......................................................................................... 11

3.1.1.1 How to create a JAXFront DOM from a XML Schema (xsd) ......................................................................... 11 3.1.1.2 How to create a JAXFront DOM from a XML Schema (xsd) based on a specific root node ......................... 11 3.1.1.3 How to create a JAXFront DOM from a XML Schema (xsd) binded with an existing xml instance file ......... 11 3.1.1.4 How to create a JAXFront DOM from a XML Schema (xsd) binded with a W3C DOM ................................. 11 3.1.1.5 How to create a JAXFront DOM from a XML Schema (xsd) with an existing xui file .................................... 11 3.1.1.6 How to create a JAXFront DOM from a XML Schema (xsd) binded with an existing xml instance file and an existing xui file .............................................................................................................................................. 12 3.1.1.7 How to bind data of a W3C DOM to an existing JAXFront DOM .................................................................. 12

3.1.2 Working with a JAXFront DOM ..................................................................................... 12 3.1.2.1 How to validate a JAXFront DOM against the underlying xsd and defined xui rules..................................... 12 3.1.2.2 How to validate a JAXFront DOM only against the defined xui rules ............................................................ 12 3.1.2.3 How to validate a JAXFront DOM only against the underyling xsd ............................................................... 12 3.1.2.4 How to validate a JAXFront DOM only against the underyling xsd ............................................................... 12 3.1.2.5 How to get all validation errors of a JAXFront DOM ..................................................................................... 12 3.1.2.6 How to add a new error to the error controller .............................................................................................. 12 3.1.2.7 How to serialize the content of a JAXFront DOM.......................................................................................... 12 3.1.2.8 How to serialize the content of a JAXFront DOM to a W3C Document ........................................................ 13 3.1.2.9 How to save the content of a JAXFront DOM into a file ................................................................................ 13 3.1.2.10 How to set a JAXFront DOM non-editable .................................................................................................. 13 3.1.2.11 How to set another language to a JAXFront DOM ...................................................................................... 13 3.1.2.12 How to get the root node of a JAXFront DOM ............................................................................................ 13

4 JAVA SWING INTEGRATION ........................................................................................... 14

4.1 (1) BUILD AN EDITOR PANEL ................................................................................................ 15 4.2 (2) CREATE VISUALIZERS (UI FACTORY) ............................................................................... 15 4.3 (3) WRITE YOUR OWN CONDITION ........................................................................................ 17 4.4 (4) WRITE YOUR OWN ACTION ............................................................................................. 18 4.5 (5) WRITE YOUR OWN FUNCTION ......................................................................................... 19 4.6 (6) WRITE YOUR OWN PLUGIN ............................................................................................. 22 4.6.1 Plugin Reference Implementation ................................................................................. 23 4.6.2 Use JAXFront within your eclipse plugin ....................................................................... 24

4.7 (7) WRITE YOUR OWN TREE POPUP MENU ............................................................................ 25 4.8 (8) USING THE XPATH ENGINE ............................................................................................. 26 4.9 (9) USING THE EVENT HANDLING ......................................................................................... 27 4.10 (10) FIRE UI ACTIONS ....................................................................................................... 28 4.11 (11) IMPLEMENT YOUR OWN CODESET .............................................................................. 29 4.12 (12) ADDING AN OWN ERROR ............................................................................................ 30 4.13 REPLACE SYSTEM DEFAULT VISUALIZERS WITH OWN IMPLEMENTATIONS ............................. 30 4.14 HOW TO MANIPULATE THE XML SERIALIZATION .................................................................... 32

5 PERFORMANCE ............................................................................................................... 33

5.1 DISABLE GLOBAL UI DEFINITIONS ....................................................................................... 33 5.2 ENABLE ALTERNATE XPATH IMPLEMENTATION ...................................................................... 34

6 THIRD PARTY PATCHES ................................................................................................. 34

7 EXAMPLE APPLICATION - TESTFRAME ........................................................................ 35

7.1 GETTING STARTED ............................................................................................................. 35 7.2 FUNCTIONS ........................................................................................................................ 36 7.2.1 Examples ...................................................................................................................... 36 7.2.2 Edit ............................................................................................................................... 37 7.2.3 Language ...................................................................................................................... 38

8 LIMITATIONS .................................................................................................................... 39


www.jaxfront.com Seite 5-39

1 Introduction This document describes the most important interfaces for a developer working with JAXFront. Setting up the environment, integration & most used classes/methods of the JAXFront API are the main issues. It further contains a short manual to the example application “TestFrame”.



2 Setting Up Environment

2.1 Basic Installation

To install JAXFront follow these steps:

1. Go to www.jaxfront.com and download the current version of the install file

(JAXFront_XX.jar, where XX stands for the current version, e.g. V1.60).

Alternatively, insert the installation CD in your computer and navigate to the installation file.

2. Double-click the installation file: JAXFront_XX.jar. If the executable jar does not

start, switch to your command line and type in: java –jar JAXFront_XX.jar.

3. Follow the Installation Wizard, which leads you through the installation process.

2.2 Directory structure After you have installed JAXFront (into the directory c:\Program Files\JAXFront, for example), the directory structure will look like this:



Explanation:Explanation:Explanation:Explanation: JAXFront

The main directory of JAXFront incl. batch files for starting the XUIEditor and DemoSuite application.

config

Directory with JAXFront runtime configuration files. (e.g. functions, actions, .. incl. helptext). If the config folder doesn’t exist, jaxfront will search in the jar files.

examples

Directory containing xui examples. Find a complex example about all possible style & behaviour options in the folder “demo-suite”.

examples/com

Directory containing java example source code (how to implement your own visualizers, actions, popups,... and how to integrate jaxfront in your application).

html-renderer

The directory includes all the html runtime files (incl. Apache Tomcat Version 4.1) needed for the HTML rendering.

lib

JAXFront system jar files and all used Libraries. (e.g. Log4J, xerces, ...).

uninstaller Directory containing the uninstaller jar file (just double click to run it).

2.3 Runtime Environment

1. Be sure you have installed a Java virtual machine (JRE 1.5+). Include all of the following libraries to your classpath:

Library name Description Version

jaxfront-core.jar jaxen JEP

jaxfront core classes Universal Java XPath Engine Math Expression Parser

1.0 2.2.4

jaxfront-dbm.jar hsqldb.jar castor-1.0M2.jar jta1.0.1.jar

jaxfront xml-db mapping Java RDB (hypersonic SQL) Caster Mapping Framework Java Transaction API

1.8.0 1.0M2 1.0.1

jaxfront-demo.jar jaxfront demo

jaxfront-html.jar freemarker.jar

jaxfront html renderer Template Engine Framework

2.3.4

jaxfront-pdf.jar iText

jaxfront pdf renderer Java PDF Framework

1.4

jaxfront-swing.jar jaxfront swing renderer

jaxfront-xuieditor.jar jaxfront xuieditor

commons-beanutils.jar Apache Jakarta Common BeanUtils 1.5

commons-collections.jar Apache Jakarta Common Collection Tools 1.1dev

commons-logging.jar Apache Jakarta Common Logging 1.04

looks-1.3.1.jar Jgoodies Look&Feel 1.3.1

log4j-1.2.8.jar Apache Logging Framework 1.2.8

resolver.jar Apache Resolver Tool 1.1

xercesImpl.jar Apache XML Schema Parser 2.6.2



xml-apis.jar W3C XML DOM/SAX API 1.2.01

2. Put all your classes into a jar file (e.g. projectX.jar) and include it in the classpath too. Be sure all your functions are registered in the config/functions.xml file.

3. Place the config folder into the classpath folder or into one of your project jar files (e.g. projectX.jar). Be aware of the loading sequence of the jar files. If you don’t delete the config folder in the jaxfront-core.jar you have to place your jar files before the jaxfront jar’s.

4. Write a java start batch file including your jar files like:

"%JAVA_HOME%\bin\javaw" -noverify -classpath projectX.jar;..;.;..\lib;..\lib\jaxfront-core.jar;..\lib\jaxfront-swing.jar;..\lib\jaxfront-xuieditor.jar;..\lib\jimi.jar;..\lib\jaxfront-pdf.jar;..\lib\xercesImpl.jar;..\lib\xml-apis.jar;..\lib\resolver.jar;..\lib\commons-logging.jar;..\lib\commons-collections.jar;..\lib\commons-beanutils.jar;..\lib\log4j.jar;..\lib\jgoodiesLF.jar com.jaxfront.demo.TestFrame

5. Deploy the application

2.3.1 JAXFront license file deployment If you deploy your own product where the JAXFront runtime JARS are embedded, be sure you place your JAXFront license into your deployment package to get rid of the JAXFront watersign. There are two different possibilities:

1) Add a directory called “lic” into your deployment root package and place your JAXFront license there. If your “user.dir” Java system variable points to a location where this directory (./lib) can be found at runtime, JAXFront will load the license from there first.

2) Rename your JAXFront license file (e.q. JAXFront-Customer-XYZ-2006-01-01-4567.lic) to “jaxfront.lic” and place it anywhere in your runtime classpath. We suggest to put the renamed license file into the jaxfront-core.jar.



2.3.2 How to integrate/use a plugin in the XUI-Editor The PlugIns used by JAXFront are listed in the JAXFront Preferences, under the Plug-in tab. Refer to chapter 3.6.3 in the XUIEditor Manual. To let the XUIEditor find your plugin class, you need to add the compiled java class and all its dependent classes to the classpath of the starting XUIEditor. To do this, you need to copy your own jar (with all your plugin classes and dependencies) to the directory called “lib” under the JAXFront installation directory. Now you can edit the manifest file in the jaxfront-xuieditor.jar. The file is located in the directory called “lib” in the JAXFront installation directory. Update the file /META-INF/MANIFEST.MF in the jaxfront-xuieditor.jar by adding your own jar(s) (e.q. myclasses.jar) where the plugin(s) are located. Manifest-Version: 1.0 Ant-Version: Apache Ant 1.6.1 Created-By: 1.4.2_03-b02 (Sun Microsystems Inc.) Main-Class: com.jaxfront.xuieditor.XUIEditor Class-Path: jaxfront-xuieditor.jar jaxfront-core.jar jaxfront-swing.ja r jaxfront-html.jar jaxfront-pdf.jar xercesImpl.jar xml-apis.jar reso lver.jar jimi.jar commons-logging.jar commons-collections.jar commons

-beanutils.jar log4j.jar jgoodiesLF.jar myclasses.jar

If you want to see your plugin listed in the XUIEditor plugin tab, you have to register the plugin class in the config/plugins.xml file. To use your own plugin in the XUIEditor, please refer to chapter 3.4.2.5 in the XUIEditor Manual.

2.4 Run JAXFront To run JAXFront (XUI-Editor) just start the XUIEditor.bat located in your JAXFront installation directory.

If the XUI-Editor does not start (i.e. instead starting the winzip or another archive viewer), the JAVA_HOME variable is not set properly. Set the JAVA_HOME variable in your system settings or start the XUI-Editor with the following command line:

2.5 Uninstalling JAXFront

To uninstall JAXFront from your Windows system:

1. Locate the folder on your system, where the XUI-Editor was installed. The file

Uninstaller.jar is located in the JAXFront Uninstaller folder.

2. Double-click the Uninstaller.jar file, to run it. The originally installed JAXFront

folder is deleted. If the executable jar does not start, switch to your command line and type in: java –jar Uninstaller.jar.



2.6 Explore JAXFrom Demo Suite Load the JAXFront demo suite example in the XUI-Editor to explore the full spectrum of JAXFront.

Click on the button named ‘load’ on the Complete Demo Suite line to load the demo suite. If you do not see the ‘Welcome’ panel, click ‘Welcome’ in the menu named ‘Help’.



3 Building a JAXFront DOM The heart of JAXFront is the JAXFront document object model (DOM). The first step in using JAXFront is to create a DOM.

3.1 The JAXFront Document Object Model (DOM) The class Document (com.jaxfront.core.dom.Document) represents a JAXFront DOM which combines XML Schema (meta level), XML Instance data (optional) and graphical informations (XUI Definitions).

3.1.1 Build a new JAXFront DOM The class DOMBuilder acts as a factory for creating JAXFront documents. Here are the most used methods: 3.1.1.1 How to create a JAXFront DOM from a XML Schema (xsd)

URL xsdURL = new URL("file:///c:\\temp\\mySchema.xsd");

Document dom = DOMBuilder.getInstance().build(null,xsdURL);

3.1.1.2 How to create a JAXFront DOM from a XML Schema (xsd) based on a specific root node

URL xsdURL = new URL("file:///c:\\temp\\mySchema.xsd"); String rootName = “purchaseOrder”; Document dom = DOMBuilder.getInstance().build(null,xsdURL, rootName);

3.1.1.3 How to create a JAXFront DOM from a XML Schema (xsd) binded with an existing xml instance file

URL xsdURL = new URL("file:///c:\\temp\\mySchema.xsd"); URL xmlURL = new URL("file:///c:\\temp\\myXML.xml");

Document dom = DOMBuilder.getInstance().build(null,xsdURL, xmlURL, null, null);

3.1.1.4 How to create a JAXFront DOM from a XML Schema (xsd) binded with a W3C DOM

URL xsdURL = new URL("file:///c:\\temp\\mySchema.xsd"); org.w3c.dom.Document w3cDOM = DOMHelper.createDocument(xmlAsString); Document dom = DOMBuilder.getInstance().build(null,xsdURL, w3cDOM, null, null);

3.1.1.5 How to create a JAXFront DOM from a XML Schema (xsd) with an existing xui file

URL xsdURL = new URL("file:///c:\\temp\\mySchema.xsd"); URL xuiURL = new URL("file:///c:\\temp\\myFirstXUI.xui");

Document dom = DOMBuilder.getInstance().build(null,xsdURL, null, xuiURL, null);



3.1.1.6 How to create a JAXFront DOM from a XML Schema (xsd) binded with an existing xml instance file and an existing xui file

URL xsdURL = new URL("file:///c:\\temp\\mySchema.xsd"); URL xmlURL = new URL("file:///c:\\temp\\myXML.xml"); URL xuiURL = new URL("file:///c:\\temp\\myFirstXUI.xui");

Document dom = DOMBuilder.getInstance().build(null,xsdURL, xmlURL, xuiURL, null);

3.1.1.7 How to bind data of a W3C DOM to an existing JAXFront DOM

dom.bind(w3cDOM);

3.1.2 Working with a JAXFront DOM 3.1.2.1 How to validate a JAXFront DOM against the underlying xsd and defined xui rules

dom.validate();

3.1.2.2 How to validate a JAXFront DOM only against the defined xui rules

dom.validateXUIRules(false); // for validating only on the client side dom.validateXUIRules(true); // for validating only on the server side

3.1.2.3 How to validate a JAXFront DOM only against the underyling xsd

dom.validateSchemaConstraints();

3.1.2.4 How to validate a JAXFront DOM only against the underyling xsd

dom. validateKeyRefIntegrity (true); //true notify the error controller about changes

3.1.2.5 How to get all validation errors of a JAXFront DOM

dom.getController().getErrorController().getAllErrors(); // returns a Collection of Error objects

3.1.2.6 How to add a new error to the error controller

Type sourceType = dom.getRootType(); Error error = new UserError(“identifier”, sourceType); dom.getController().getErrorController().addError(myError);

3.1.2.7 How to serialize the content of a JAXFront DOM

try { dom.serialize();

} catch (ValidationException e) {

e.printStackTrace();



}

3.1.2.8 How to serialize the content of a JAXFront DOM to a W3C Document

try { org.w3c.dom.Document w3cDocument = serializeToW3CDocument();

catch (Exception e) { e.printStackTrace();

}

3.1.2.9 How to save the content of a JAXFront DOM into a file

try { File xmlFile = new File("c:\\temp\\myXML.xml");

dom.saveAs(xmlFile); } catch (ValidationException e) {

e.printStackTrace(); }

3.1.2.10 How to set a JAXFront DOM non-editable

dom.setImmutable(true);

3.1.2.11 How to set another language to a JAXFront DOM

dom.getGlobalDefinition().setLanguage(“en”); //to refresh the views, do the following: TypeVisualizerFactory.getInstance().releaseCache(dom); //Recreate your EditorPanel and add it to the container again EditorPanel panel = new EditorPanel(dom.getRootType(), myFrame); myFrame.getContentPane().removeAll(); myFrame.getContentPane().add(panel, BorderLayout.CENTER);

3.1.2.12 How to get the root node of a JAXFront DOM

dom.getRootType(); // returns a JAXFront Type that represents the root node of the xsd



4 Java Swing Integration To explore the Java Swing Integration, open the XUI Editor and load the „JAXFront API“ example.

Press the preview button and explore the 10 examples by clicking on the tree nodes.



4.1 (1) Build an editor panel The class EditorPanel (com.jaxfront.swing.ui.editor.EditorPanel) represents the main GUI component of JAXFront. It includes a navigation tree on the left (if desired) and the workspace on the right in which the generated components are drawn.

See class com.jaxfront.demo.api.UseEditorPanel. public class UseEditorPanel extends AbstractCompositeView { protected void defaultBuild() { setLayout(new BorderLayout());

try { URL xsdURL = URLHelper.getUserURL("examples/purchaseOrder/po.xsd"); URL xmlURL = URLHelper.getUserURL("examples/purchaseOrder/po.xml"); URL xuiURL = URLHelper.getUserURL("examples/purchaseOrder/po.xui"); Document dom = DOMBuilder.getInstance().build(null,xsdURL, xmlURL, xuiURL,"purchaseOrder");

EditorPanel editorPanel = new EditorPanel(dom.getRootType(), getEditor().getWindow()); add(editorPanel, BorderLayout.CENTER); } catch (DocumentCreationException ex) {

LogRegistry.getInstance().warn(getClass(), "Error while creating po.xsd DOM: " + ex); } } public void setApplicationRequired(boolean aBoolean) {} public void setRequired(boolean aBoolean) {} }

Create an instance of EditorPanel and plugin in the JPanel instance where ever you want.

4.2 (2) Create visualizers (UI factory) The class TypeVisualizerFactory acts as a factory that creates visualizers (JAXFront GUI components) for a JAXFront type (a representation of a schema node). It allows to create a bundle of GUI elements that might be placed on different panels or frames. The created GUI components implements the interface Visualizer.

See class com.jaxfront.demo.api.OwnLayoutManager public class OwnLayoutManager extends AbstractCompositeView implements ListSelectionListener{ private Document _dom; private JPanel _detailPanel; protected void defaultBuild() { setLayout(new BorderLayout()); try { URL xsdURL = URLHelper.getUserURL("examples/purchaseOrder/po.xsd"); URL xmlURL = URLHelper.getUserURL("examples/purchaseOrder/po.xml"); URL xuiURL = URLHelper.getUserURL("examples/purchaseOrder/po.xui"); _dom = DOMBuilder.getInstance().build(null,xsdURL, xmlURL, xuiURL, "purchaseOrder"); JPanel upperPanel = new JPanel(new GridBagLayout()); GridBagConstraints c = new GridBagConstraints(); c.fill = GridBagConstraints.HORIZONTAL; Type purchaseOrderRoot = _dom.getRootType();



JComponent visualizer = (JComponent)TypeVisualizerFactory.getInstance().getVisualizer(purchaseOrderRoot.getDirectChild("orderDate")); c.weightx = 0.5; c.gridx = 0; c.gridy = 0; upperPanel.add(visualizer, c); visualizer = (JComponent)TypeVisualizerFactory.getInstance().getVisualizer(purchaseOrderRoot.getDirectChild("deliveryOption")); c.gridx = 1; c.gridy = 0; upperPanel.add(visualizer, c); visualizer = (JComponent)TypeVisualizerFactory.getInstance().getVisualizer(purchaseOrderRoot.getDirectChild("email")); c.gridx = 0; c.gridy = 1; upperPanel.add(visualizer, c); JPanel lowerPanel = new JPanel(new BorderLayout()); _detailPanel = new JPanel(new BorderLayout()); JList list = new JList(new String[]{"shipTo", "billTo", "paymentMethod", "item"}); list.addListSelectionListener(this); list.setBorder(BorderFactory.createEtchedBorder()); JScrollPane scrollPane = new JScrollPane(list); scrollPane.setPreferredSize(new Dimension(200,200)); JPanel listPanel = new JPanel(new BorderLayout()); listPanel.add(scrollPane, BorderLayout.NORTH); lowerPanel.add(listPanel, BorderLayout.WEST); lowerPanel.add(_detailPanel, BorderLayout.CENTER); add(upperPanel, BorderLayout.NORTH); add(lowerPanel, BorderLayout.CENTER); } catch (DocumentCreationException ex) { LogRegistry.getInstance().warn(getClass(), "Error while creating po.xsd DOM: " + ex.getLocalizedMessage()); } } public void setApplicationRequired(boolean aBoolean) {} public void setRequired(boolean aBoolean) {} public void valueChanged(ListSelectionEvent e) { _detailPanel.removeAll(); String name = (String)((JList)e.getSource()).getSelectedValue(); JComponent visualizer = (JComponent)TypeVisualizerFactory.getInstance().getVisualizer(_dom.getRootType().getDirectChild(name)); _detailPanel.add(visualizer, BorderLayout.CENTER); _detailPanel.updateUI(); } }

Create a JComponent from any type you want. The returned JComponent will care about event handling (populate model/populate view) and rules defined in the XUI.



4.3 (3) Write your own condition Within a XUI rule one can define their own condition implementation. A condition gets checked if an event occurs and will fire a set of actions if the condition is true (ECA, Event-Condition-Action). Instead of using the built in formula engine to define a condition, you can use your own condition implementation. If you define a formula engine condition in combination with an own condition implementation, both conditions will be checked and have to return true to fire the actions.

The class need to implement the com.jaxfront.core.rule.Condition interface. If you click on the

button next to the text field ( ), JAXFront will try to load the class (through the specified classpath) and check if the Condition interface is implemented. A red bullet indicates that the class can not be loaded or it does not implement the Condition interface. com.jaxfront.core.rule.Condition Name Description

doesConcern(Type) Returns true if the passed type does concern this condition. This may be important if the scope of the event definition is not just ‘sourceOnly’. In this case just check if the passed type equals the source of the condition or is derrived from it.

isTrue() Returns true if the condition is true. Check any status based on the underlying source type.

setSourceType(Type) Sets holder of the condition.

See class com.jaxfront.demo.api.OwnCondition



This Condition just checks if the source of the defined rule holds a future date. public class OwnCondition extends Object implements Condition { Type _sourceType;

public boolean isTrue() throws FormulaException {

SimpleType simpleType = (SimpleType)_sourceType; String dateString = simpleType.getValue(); try { SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd"); Date inputDate = format.parse(dateString); Date currentDate = new Date(); return inputDate.compareTo(currentDate) > 0; } catch (ParseException ex) { //do nothing } return false; }

public boolean doesConcern(Type checkType) {

return checkType == _sourceType; } public void setSourceType(Type sourceType) {

_sourceType = sourceType; } }

4.4 (4) Write your own action Within a XUI rule it's possible to define own actions to get fired. Conditions get checked if an event occurs, if the condition is true all corresponding actions are fired(ECA, Event-Condition-Action). Instead of using the built in actions (uiActions), one can provide an own action implementation. If a predefined UI action is choosen in combination with an custom action implementation, both actions will be fired. The inverse action is usually a inverse implementation of the main action.



The class need to implement the Action interface: com.jaxfront.core.rule.Action Name Description

perform(Type) This method gets called if the condition is true. The passing type is the target type of the action as defined in the xui rule (Target Node). If the target node is not specified, the source of the rule definition will become the target. If no target node is defined in the inververse action, the target node from the main action will be choosen.

See class com.jaxfront.demo.api.OwnMainAction This Action marks the visualizer of the target node with a green border. public class OwnMainAction extends Object implements Action { public void perform(Type target) { AbstractSimpleTypeView component = (AbstractSimpleTypeView)TypeVisualizerFactory.getInstance().getVisualizer(target); component.getEditorField().setBorder(BorderFactory.createEtchedBorder(Color.green, Color.green)); } }

See class com.jaxfront.demo.api.OwnInverseAction This Action resets the border of the target node with an empty line border. public class OwnInverseAction implements Action { public void perform(Type target) { AbstractSimpleTypeView component = (AbstractSimpleTypeView)TypeVisualizerFactory.getInstance().getVisualizer(target); component.getEditorField().setBorder(BorderFactory.createLineBorder(Color.black)); } }

4.5 (5) Write your own function



A function can be used everywhere within the rule engine (condition expression, nls text). A predefined set of functions already exists. To register the own function, open the “Preferences” dialog in the XUI Editor (“View” menu) and add a new function. After adding/modifying the functions, the XUI Edtior needs to be closed and started again.

Implementing an own function means to extend the “com.jaxfront.core.jep.JaxfrontMathCommand” class . In the field “Implementation Class” enter the class name which extends this class. In the field “Category” add an existing category name or a new one. You will see all categories when using the formula engine.



The class needs to extend the “com.jaxfront.core.jep.JaxfrontMathCommand” class: Name Description

run(Stack) Each function should use it's own run() method for evaluating the function. This includes popping off the parameters from the stack, and pushing the result back on the stack.

See class com.jaxfront.demo.api.OwnFunction This function checks if the passed node values is a future date. public class OwnFunction extends SuperTypeNode { public void run(Stack stack) throws ParseException {

// Check if stack is null checkStack(stack); Object param = null; String xPath = null; boolean isFutureDate = false; if (curNumberOfParameters == 1) { Type baseType = getCommunicator().getRootType(); param = stack.pop(); if (param == NULL._null) { stack.push(NULL._null); return; } else if (param instanceof Type) { baseType = (Type) param; } else if (param instanceof String) { xPath = (String) param; } Type resultType = null; if (xPath != null && xPath.length() > 0) { resultType = TypePathExecuter.getInstance().getTypeForXPath( baseType, xPath.trim(), true, true); } else resultType = baseType; if (resultType != null) { if (resultType.isSimple()) { SimpleType simpleType = (SimpleType)resultType; String dateString = simpleType.getValue(); if (dateString != null) { try { SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd"); Date inputDate = format.parse(dateString); Date currentDate = new Date(); isFutureDate = inputDate.compareTo(currentDate) > 0; } catch (java.text.ParseException ex) { //do nothing } } } else { throw new ParseException(this.getClass() + " Invalid target type (must be simple)"); } } if (isFutureDate) { stack.push(SuperTypeNode.isTrue); } else {



stack.push(SuperTypeNode.isFalse); } } else { throw new ParseException(this.getClass() + " Invalid parameter type"); } } }

4.6 (6) Write your own plugin Write a plugin (Java Bean) if you want to have your own graphical implementation of any node in your XML document. The easiest way to create a plugin is to extend one of these abstract classes: Class Name Description

com.jaxfront.swing.ui.beans.AbstractSimpleVisualizer This class is a template to write its own primitive visualizer component.

com.jaxfront.swing.ui.beans.AbstractComplexVisualizer This class is a template to write its own complex visualizer component (composite).

com.jaxfront.swing.ui.beans.AbstractListVisualizer This class is a template to write its own list visualizer component.

If you do not want to inherit from the given abstract classes, you need to enable the interaction with the JAXFront core engine. One needs to implement the Java interface Visualizer. The graphical representation and the data binding is up to the imlementor of the interface.

com.jaxfront.core.ui.Visualizer Name Description

getLabelText() Returns the text of the label.

getModel() Returns the underlying JAXFront model (Type).

jumpTo() Sets the focus on this component and brings it to front.

markError() Do whatever you want to mark this visualizer as an error (e.q. draw a red border).

populateModel() Schreibt den aktuellen Wert aus der Komponente in das zugrunde liegende Modell (Type).

populateView() Populates the current value from the model to the view.

postInitialization() Gets called after the UI factory has created this visualizer. Do whatever you want here.

release() Releases all allocated system resources for this bean (e.q. listeners).

removeLabel() Removes the label from the widget.

resetError() Removes the error indication (e.q. red border).

setApplicationRequired(boolean) Sets the component as application required. This is different to the required flag from the XML Schema. An application required field gets its own defined background color (defined in the global settings).



setEditable(boolean) Sets the component as editable or protected.

setEnabled(boolean) Activates or deactivates this component.

setLabelColor(Color) Sets the foreground color of the label text.

setModel(Type) Sets the JAXFront model (Type).

setRequired(boolean) Sets the component as required or not. If is is required, the background color should change (as defined in the global settings).

setVisible(boolean) Sets the visibility of this component.

showLabel(boolean) Defines if the label is visible or not.

4.6.1 Plugin Reference Implementation

Below you find a reference implementation for a JAXFront Plugin. This plugin just displays a label, a text area with 4 rows, a certain textfont and a fat green border around the control.

com.jaxfront.demo.api.OwnPlugin public class OwnPlugin extends AbstractSimpleVisualizer { private JTextArea _textArea; public String getLabelText() { return "Simple Plugin Example"; } public String getText() { if (_textArea != null) return _textArea.getText(); return null; } public void populateView() { if (getModel() != null && _textArea != null) { String value = ((SimpleType)getModel()).getValue(); if (value != null) { _textArea.setText(value); } } } protected JComponent createEditorComponent() { _textArea = new JTextArea(); _textArea.setForeground(Color.blue); setBorder(BorderFactory.createMatteBorder(20,20,20,20,Color.GREEN)); _textArea.addFocusListener(this); _textArea.setFont(new Font(null,1,20)); _textArea.setRows(4); _textArea.setLineWrap(true); _textArea.addFocusListener(this); _firstFocusableComponent = _textArea; return _textArea; } }



4.6.2 Use JAXFront within your eclipse plugin The JAXFront eclipse integration works through the IBM’s SWT-Swing bridge component. This component does only work properly under Windows with eclipse 3+ and JRE 1.5+. If you intend to use the JAXFront eclipse plugin on any other OS than Windows, you need to use JRE 1.5. The SWT-Swing bridge should be fully supported in JRE 1.5 To create your own JAXFront SWT composite components, you need to use the JAXFrontPanelFactory. Just pass a SWT composite (parent) and a JAXFront DOM to the factory and you will get your own SWT composite including the JAXFront editor. Composite composite = new Composite(getContainer(), SWT.EMBEDDED); URL xsdURL = URLHelper.getUserURL("c:\\jaxfront_swing\\examples\\po\\po.xsd"); URL xmlURL = URLHelper.getUserURL("c:\\jaxfront_swing\\examples\\po\\po.xml"); URL xuiURL = URLHelper.getUserURL("c:\\jaxfront_swing\\examples\\po\\po.xui"); try { _dom = DOMBuilder.getInstance().build(xsdURL, xmlURL, xuiURL, null); JAXFrontPanelFactory.createComposite(composite, _dom);

FillLayout layout = new FillLayout(); composite.setLayout(layout); int index = addPage(composite); setPageText(index, "JAXFront"); } catch (DocumentCreationException ex) { ex.printStackTrace(); }

See chapter 8 for the whole example code.

At runtime your plugin needs the following libraries:



4.7 (7) Write your own tree popUp menu To implement your own tree popUp menu for any tree node, one need to extend from class “com.jaxfront.swing.ui.editor.AbstractPopUpMenu”.

com.jaxfront.demo.api.OwnTreePopUpMenu public class OwnTreePopUpMenu extends AbstractPopUpMenu { public OwnTreePopUpMenu(NavigationTree tree, com.jaxfront.core.ui.TreeNode treeNode) { super(tree, treeNode); initialize(); } private void initialize() { OwnSwingTestAction testAction = new OwnSwingTestAction("test"); testAction.putValue(XUITypes.VALUE_DOM, getTreeNode().getType().getDOM()); testAction.putValue(XUITypes.VALUE_SOURCE, getTreeNode().getType()); add(testAction); } }



4.8 (8) Using the xpath engine You may use the builtin xpath engine to evaluate your own xpath expressions any time in your code. The following examples shows how the xpath engine is used within an own action implementation. This implementation will address all list items underneath which matches a certain pattern. The pattern is based on a field value from another type.

com.jaxfront.demo.api.XPathAction public class XPathAction implements Action { public void perform(Type source) { Type patternType = source.getChild("simpleGroup").getDirectChild("A"); String pattern = source.getChild("simpleGroup").getDirectChildValue("A"); String xpath = ".//A[.='" + pattern + "']"; ListType listType = (ListType)source.getDirectChild("list"); List found = TypePathExecuter.getInstance().processXPath(listType, xpath);

AbstractView view = (AbstractView)TypeVisualizerFactory.getInstance().getVisualizer(patternType); String message = "Found (" + found.size() + " items) for XPath ("+ xpath + "). Going to delete them..."; view.showHint(message, false, Color.RED, true); Iterator iterator = found.iterator(); while (iterator.hasNext()) { listType.removeChild(((Type)iterator.next()).getParent()); } } }



4.9 (9) Using the event handling To demonstrate the event handling, see the following implementation how to listen for any property- or dom-change event. This plugin will register for all event and display the event object within its text area as soon as an event occurs.

com.jaxfront.demo.api.EventHandling public class EventHandling extends AbstractCompositeView implements PropertyChangeListener, DOMChangeListener{ private JTextArea _textArea; protected void defaultBuild() { setLayout(new BorderLayout()); JComponent visualizer = (JComponent)TypeVisualizerFactory.getInstance().getVisualizer(getModel().getDirectChild("simpleGroup")); add(visualizer, BorderLayout.NORTH); visualizer = (JComponent)TypeVisualizerFactory.getInstance().getVisualizer(getModel().getDirectChild("list")); add(visualizer, BorderLayout.CENTER); _textArea = new JTextArea(); JScrollPane scrollPane = new JScrollPane(_textArea); scrollPane.setPreferredSize(new Dimension(300, 300)); add(scrollPane, BorderLayout.SOUTH); getModel().getDOM().getController().addPropertyChangeListener(this);

getModel().getDOM().addDOMChangeListener(this);

} public void propertyChange(PropertyChangeEvent event) { super.propertyChange(event); _textArea.setText(event.toString()); } public void domChanged(DOMChangeEvent event) { super.domChanged(event); _textArea.setText(event.toString()); } public void setApplicationRequired(boolean aBoolean) {} public void setRequired(boolean aBoolean) {} }



4.10 (10) Fire UI actions The builtin UI actions can be fired any time within your own code. The following example shows how to call the setVisible, collapse/expand and adTreeNode/removeTreeNode method within an own action implementation.

com.jaxfront.demo.api.ChangeState public class ChangeState extends AbstractAction { private boolean _visible = true; private boolean _collapse = false; private boolean _treeNode = false; public void actionPerformed(ActionEvent event) { Document dom = (Document)getValue(XUITypes.VALUE_DOM); Type source = (Type)getValue(XUITypes.VALUE_SOURCE); String actionName = event.getActionCommand(); Type target = source.getParent().getDirectChild("list"); Visualizer targetVisualizer = TypeVisualizerFactory.getInstance().getVisualizer(target); if (actionName.equals("visibility")) { _visible = !_visible;

targetVisualizer.setVisible(_visible);

} else if (actionName.equals("collapse")) { _collapse = !_collapse; if (_collapse)

((AbstractView)targetVisualizer.getInplementation()).getBorderPanel().collapseInitially();

else ((AbstractView)targetVisualizer.getInplementation()).getBorderPanel().expandInitially();

} else if (actionName.equals("treeNode")) { _treeNode = !_treeNode; if (_treeNode)

((AbstractView)targetVisualizer.getInplementation()).addTreeNode(true);

else ((AbstractView)targetVisualizer.getInplementation()).removeTreeNode(true);

} } }



4.11 (11) Implement your own CodeSet A codeset is an XML file containing codes and descriptions in multiple languages. To load a codset, a simple url pointing to a valid codeset xml is enough. If you want to implement your own strategy or caching mechanism how to load and where to load the codeset from (i.e. fetch from DB, etc.), just implement the CodeSet interface.

com.jaxfront.demo.api.OwnCodeSetResolverImpl public class OwnCodeSetResolverImpl implements CodeSet { public Reader getCodeSet(Type type, String codeSetName, String versionNo) { //for demo purposes, load the codeset file from local jar/file system String fileName = "examples/purchaseOrder/po.codes"; URL codeSetURL = URLHelper.getUserURL(fileName); try { if (codeSetURL != null) { String xmlContent = FileHelper.readFileAsString(codeSetURL); return new StringReader(xmlContent); } } catch (IOException ex) { LogRegistry.getInstance().warn(getClass(), "Unable to open file: " + fileName); } return null; } }



4.12 (12) Adding an own error If you want to add your own error object anytime through the Java API, just instantiate an UserError object and add it to the ErrorController. Be sure you also implement the inverse action to remove the error again.

com.jaxfront.demo.api.AddUserError public class AddUserError implements Action { public void perform(Type target) { Error myError = new UserError("test-identifier", target, "message", Error.CLASSIFICATION_WARNING); target.getDOM().getController().getErrorController().addError(myError); } }

com.jaxfront.demo.api.RemoveUserError public class RemoveUserError implements Action { public void perform(Type target) { target.getDOM().getController().getErrorController().removeUserError("test- identifier", target); } }

4.13 Replace system default visualizers with own

Implementations It's possible to replace all default visualizer with an custom implementation. This is useful if you have special components to visualize specific datatypes e.g a special date picker bean. To do this you have to create and map a Visualizer which has to fulfill following requirements: Requirements for a Default Visualizer:

• Needs to implement the Visualizer Interface

• Need Constructor with (Type model,Type context) parameters

• Extends the JComponent class Two ways to add a custom visualizer to visualizer mapping:

1. jaxfront.xml: <property mutable="true"> <key>SimpleTypeDateView</key> <value>com.jaxfront.swing.ui.beans.DateBean</value> </property>

2. API: JAXFrontProperties.getInstance().setStringProperty(“SimpleTypeDateView”,”com.jaxfront.s wing.ui.beans.DateBean”);



List of default visualizer:

Name Description

RecursionWrapper Visualize a recursion

PagingView Visualize a page layout

ComplexGroupView Visualize a complex group

ComplexGroupListView Visualize a complex group list

SimpleGroupView Visualize a simple group

SimpleGroupListView Visualize a simple group list

KeyView Visualize a key

KeyRefView Visualize a referenced key

SimpleTypeColorView Visualize a color

SimpleTypeRadioView Visualize simple items as radio view

SimpleTypeComboView Visualize simple items as a combobox

SimpleTypeStringView Visualize a simple string

SimpleTypeBooleanView Visualize a boolean value

SimpleTypeNumericView Visualize a numeric value

SimpleTypeDateView Visualize a date value

SimpleTypeDateTimeView Visualize a data time value

SimpleTypeTimeView Visualize a time value

SimpleTypeDurationView Visualize a duration

SimpleTypeListView Visualize a simple list

Default Visualizer Example:

com.jaxfront.demo.ui.OwnDefaultVisualizerImplementation



Mapping: JAXFrontProperties.getInstance().setStringProperty("SimpleTypeDateTimeView", "com.jaxfront.demo.ui.OwnSimpleImplementation");

4.14 How to manipulate the xml serialization It's possible to register a SerializationModifier to modify the xml serialization output for specific needs. To do this you need to write a modifier class that implements the com.jaxfront.core.dom.SerializationModifier interface.

package com.jaxfront.demo.ui; import java.awt.BorderLayout; import javax.swing.JComponent; import javax.swing.JLabel; import javax.swing.JTextArea; import com.jaxfront.core.type.Type; import com.jaxfront.core.ui.Visualizer;

public class OwnDefaultVisualizerImplementation extends JComponent implements com.jaxfront.core.ui.Visualizer { private Type _context; private Type _model;

public OwnDefaultVisualizerImplementation(Type model, Type context) { _model = model; _context = context; setSize(100, 100); setLayout(new BorderLayout()); add(new JLabel("my own impl"), BorderLayout.WEST); add(new JTextArea("my own textarea"), BorderLayout.CENTER); } public Type getContext() {return _context;} public Visualizer getImplementation() {return this;} public String getLabelText() {return null;} public Type getModel() {return _model;} public boolean isViewReleased() {return false;} public void jumpTo() {} public void markError() {} public void populateModel() {} public void populateView() {} public void postInitialization() {} public void release() {} public void removeLabel() {} public void resetError() {} public void setApplicationRequired(boolean required) {} public void setEditable(boolean enabled) {} public void setEnabled(boolean enabled) {} public void setLabelColor(Color color) {} public void setLabelText(String text) {} public void setModel(Type type) {} public void setRequired(boolean required) {} public void setVisible(boolean visible) {} public void showLabel(boolean show) {}



How to register:

API: dom.setSerializationModifier (modifier);

5 Performance Jaxfront offers two settings to improve the system performance significantly.

5.1 Disable Global UI definitions Using Global UI definitions gives the xui designer the ability to reuse xui declarations and has thus a great effect at the number of declared xui definitions. This reduction leads on the other hand to an higher cpu utilization even more for large xml schemas. JAXFront resolves global type dependencies at runtime and this causes the slowdown in execution speed. If you don't need Global UI definitions you can turn this feature off: Disable Global UI definitions for: All ui's:

• jaxfront.xml: <property mutable="true">

<key>jaxfront.ui.useGlobalUIDefinitions</key> <value>false</value> </property>

• API: JAXFrontProperties.getInstance(getDOM().getAppContext()).setUsingGlobalUIDefinitions(false);

Single ui:

• API: jaxfrontDom.getGlobalDefinition().setUseGlobalTypes(false);

public static class Mody implements SerializationModifier { public void modifyStartTag(Type type, StringBuffer ser, int start) { if (v.dom.getRootType().equals(type)) { System.out.println(type.getName()); System.out.println(ser); ser.insert(start, " xmlns=\"acme.com.mst\""); } } public void modifySimpleTagValue(Type type, String value, StringBuffer serialization) { } public void modifyCompositeTagValue(Type type, String value, StringBuffer serialization, int start) { } }



5.2 Enable alternate xpath implementation Xpath's are heavily used in all parts of the system and has a significant effect at the runtime behaviour especially for a large amout of xui components and rules. The alternative implementation is approximately 10 times faster as the jaxen implementation but has the disadvantage of a reduced functionality. The alternative engine can only process short syntax xpaths like: /a/b/c /*/b //a /a//b/* /a/b[1]/c /a/b[list] It's not possible to evaluate conditional xpaths like: /a/b[./c=“a“] /a/b[position(.)==1] If a non supported xpath is processed the engine will automatically fall back to the jaxen xpath engine.

6 Third party patches Xerces: This is a patch for xerces <= 2.9.1 regarding stack overflow in matchString method. See: XERCESJ-589

https://issues.apache.org/jira/browse/XERCESJ-589?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12569187#action_12569187

Patched Class: org.apache.xerces.impl.xpath.regex. RegularExpression



7 Example Application - TestFrame The class TestFrame (com.jaxfront.demo.TestFrame) is a good example application that shows the usage and integration of JAXFront in an own frame. It even allows you to view your own example files (xsd, xml, xui).

7.1 Getting started The TestFrame application may simply be run as follows:

java com.jaxfront.demo.TestFrame

You will find the source code for this in the installation folder “/examples/com/jaxfront/demo/TestFrame.java”. To run the example simple start the TestFrame.bat in the installation folder “/examples”.



7.2 Functions

7.2.1 Examples The TestFrame application offers three different views of the purchase order example. By clicking on the image (on the right), the choosen example will be shown/refreshed.

Screenshot 1: Examples

� XML Schema only

shows only the XML Schema by using the default rendering mechanism.

� Including XML data shows the XML Schema and an XML Instance by using the default rendering mechanism.

� Including an individual XUI definition shows the XML Schema, an XML Instance and a XUI extension that performs the defined style and behaviour.



7.2.2 Edit The edit menu offers three actions:

� Serialize Shows the xml syntax of the current dom.

� Validate

Validates the current dom against the xsd and xui rules and shows the validation errors in a table.

� Open XUIEditor

Opens the XUI Editor for the choosen example.

Screenshot 2: Action „Serialize“



Screenshot 3: Action „Validate“

7.2.3 Language The menu language allows you to change the language of the current visible dom. The Editor Panel will be redrawn to perform the language changes on all components (labels, buttons, captions, titles, error messages, ...).



8 Limitations If you wish to extend JAXFront or want to have new features implemented, do not hesitate to contact us ([email protected]). A technical representative will contact you. Please notify the following limitations.

. � The derivedBy ‘Union’ is not supported yet. � Substitution groups are not supported yet. � The use of namespaces may lead to some problems concerning the use of global XUI

definitions. � Be aware that the size of your XML schema in combination with the size of the XML

Instance may lead to Out-Of-Memory problems within your JavaVM if you do not provide sufficient memory allocation.

jaxfront developer manual · commons-beanutils.jar apache jakarta common beanutils 1.5...

Documents