Chapter 1: OVERVIEW

searchcoilΛογισμικό & κατασκευή λογ/κού

15 Αυγ 2012 (πριν από 5 χρόνια και 3 μήνες)

248 εμφανίσεις

Chapter 1:
OVERVIEW

XmlGem Control and
XmlGem Designer

XmlGem

Control

is
a Swing
-
ba
se
d JavaBean

component that can be
in
voked by
Java application
s

to

generate
user interface
s

for presenting and
updating XML data
.

The user interface XmlGem Control generates

at runtime
is created at design time by an interface designer by using an interface design
tool, the XmlGem Designer.

The structure of XML data is typically
describe
d by an XML schema, which
serves as
an

input
to

XmlGem Designer

a
s
shown

in Figure

1.1
.

T
he design
tool supports interface designers to create a user interface

template

(UI
template)

bound to the schema while enforcing the structural constraints
imposed by the schema during
an interface layout

design
.

XmlGem Designer
also produces a

“grammar”
,

which is a simplified representation of the input
schema
.

A developer uses XmlGem Control to build XML
-
related applications.

At

run
time
, XmlGem Control
,

under the control of an application, takes

t
he

grammar

and the

UI template
produc
ed
by XmlGem Designer

as inputs. It then
generates a user interface for users to create and edit XML data based on the
UI template. Since the UI template represents an interface layout constrained
by the given schema,

XmlGem Control is able to always produce XML data
compliant

with the XML schema.

Figure 1.2 shows a t
ypical

user interface created by using XmlGem Designer
and presented by XmlGem Control. The user interface is composed of Swing
components, such as JLabel, JTextField, and JTabbedPane.

This sample user
interface ha
s been created for the

widely known

p
urchase
o
rder

schema

given

in the W3C XML Schema Part 0: Primer (
http://www.w3.org/TR/xmlschema
-
0/
)
.
In such a user interface, e
ach

Swing

component

is bound to an

XML

el
ement

or

attribute
in the

schema.
A

user can
thus
enter or update

XML

data

by

interacting with the Swing components.

A user can also insert XML data
dynamically, such as adding new items to the item list.

The resulting XML data
is guaranteed to be valid against the given schema.

Figure 1.1: XmlGem Control and

XmlGem

Designer




Figure 1.2: Purchase Order



Xml

Data


XmlGem Control

UI Template


Grammar


XmlGem Designer

DESIGN TIME


RUN TIME

Xml
Schema


Application

The current document is a guide for developers to use XmlGem Control in
Java applications. To use XmlGem Designer, please refer to the separate
XmlGem Designers


Guide. The

component and tool facilitates a clean
separation of work. Interface designers use XmlGem Designer to design the
user interface without requiring programming skill while programmers use
XmlGem Control in applications without worrying about the artistic wo
rk of user
interface design.

Chapter 2: First Program with XmlGem Control

This
chapter

takes you through the basics of using XmlGem control to
create a user interface based on the output of XmlGem Designer. In this
chapter
, we

are going to

use NetBeans ID
E 5.5.1
as our developing
environment
to demonstrate: 1. how to import XmlGem control to Java IDE, 2.
how to use XmlGem control in our java application, and 3. how to save the
result edited by XmlGem control. This
chapter

begins with using XmlGem
control i
n Java IDE and ends with programming. After this tutorial, we will have
a Java application which hosts XmlGem control to provide XML editing, like
following image
, figure 2.1
.


Figure 2.1: An example of XmlGem Control.

2.
1 Using XmlGem control in Java IDE

To use XmlGem control, we need to import it to Java IDE, NetBeans

5.5.1
.
That falls into three methods: 1. from a JAR file, 2. from a Project, 3. from a
Library. The first method, from a JAR file, is to import a JavaBean from a single
JAR file. This metho
d doesn’t maintain class dependencies. Instead of first
method, the second provides class dependencies support, but it needs to
create a Project to host the source code
s
. Because XmlGem control is a bunch
of JAR files which contain complex dependencies, fr
om a Library is the one
suitable to our application.

The first step to import XmlGem control to NetBeans is to create a library
named XmlGem in Tools
-
> Library Manager of main menu, figure
2
.
2
.


Figure
2
.
2
: Creating XmlGem library.

Second
, to add XmlGem
to palette, we need to

open Swing/AWT Palette
Manager from Tools
-
> Palette Manager
-
> Swing/AWT Components and click
“Add from Library” button. In the first step of Install Components to Palette
wizard, we choose XmlGem as our library, figure
2
.
3
., and cl
ick Next button.


Figure
2
.
3
: Select Library.

It may take much time to enumerate JavaBeans in XmlGem library. Once
all the JavaBeans have been evaluated, we choose XmlGem as our JavaBean,
figure
2
.
4
, and click Next button.

In the final step, we choose Bea
ns as our palette category and click Finish
button. After these steps, we can have an XmlGem control in Swing/AWT
palette, figure
2
.
5
.


Figure
2
.
4
: Select Components.


Figure
2
.
5
: XmlGem control in palette.

2.
2 Preparing an application project in NetBean
s

To use XmlGem control, we need to create a Java application project in
NetBeans. In this
chapter
, TestingApp is the Java application project we create
in NetBeans. Besides a Java application, we also create a JFrame Form
named NewJFrame which hosts XmlG
em control in TestingApp project.
Because XmlGem control is in XmlGem library, we also have to add XmlGem
library to satisfy dependencies. It can be done by right clicking on TestingApp
and choosing Project Properties in context menu, figure 2.
6
. Finally,
we will
have a project which looks like figure 2.
7
.


Figure 2.
6
: Project dependency.


Figure 2.
7
: Java Application project.

2.
3 Creating user interface and XmlGem control


Let us open NewJFrame and complete user interface design. First, we
use a JSplitP
ane which fills the whole frame to host XmlGem control and its
insertion view, which is a
nother

Java user interface component and needs to
be visible. The right pane of JSplitPane is responsible for hosting XmlGem
control and left pane is for hosting inser
tion view of XmlGem control. The
procedure of hosting insertion view is taken up in next section.

While creating an XmlGem control instance, a JScrollPane that wraps
XmlGem control is needed. We can then drag a JScrollPane into the right pane
of JSplitPan
e and drag an XmlGem control into the JScrollPane from
Swing/AWT component palette. After having XmlGem control, we need to
provide a UI template file and a grammar file to XmlGem control by property
sheet. In this tutorial, we use UITemplate.ui as our UI
template file and
Purchase.grammar as our grammar file.

Finally, NewJFrame will look like figure
2
.
8
. Here we get nearer to final
application.


Figure
2
.
8
: XmlGem control in NewJFrame.

2.
4 Programming XmlGem control


Let us leave user interface alone and

return to programming. The purpose
of this section is to program what we left in the previous sections: 1. hosting
insertion view, and 2. saving result.

a. Hosting insertion view

The following program, program
2
.1, is to obtain the insertion view of
XmlG
em control and host it in the left pane of JSplitPane. The insertion view of
XmlGem control is provided by UI Cotnroller. We can use
xmlGem1.getXmlGem(). getRootController() to get the root UI Controller. Once
having root UI Controller, we can use getInser
tionView() of UI Controller to get
the insertion view.
The
getInsertionView()
method
may return null.
I
f a

root UI
Controller doesn’t support insertion view. So, we have to check it before
adding to JSplitPane.

Program
2
.1:


/** Creates new form NewJFr
ame2 */


public NewJFrame() {


initComponents();


if(xmlGem1.getXmlGem().getRootController().


getInsertionView()!=null){


jSplitPane1.setLeftComponent(xmlGem1.getXmlGem().


getRootController().
getInsertionView());


}


}


After hosting insertion view, we can use “Run File” to test NewJFrame. We
can select NewJFrame file in Projects view and press “Shift + F6”, or rich click
on NewJFrame file and choose “Run File” item in context menu to

do so. The
result should look like figure
2
.
9
. For testing, we may click on XmlGem control
to let it recalculate insertion menu, and double click on the insertion menu to
insert some items to XmlGem control.


Figure
2
.
9
: the result of “Run File”.

b. Savi
ng result edited by XmlGem control

In this
chapter
, Java application

needs to

save result while user is closing
the NewJFrame. We add the following code, program
2
.2, in the NewJFrame
class and invoke them in window closing event to do so. In doSave method
,
we display a file dialog to choose a file name and use RunnableModel which
can obtain by xmlGem1.getRootGroup() to get the result edited by XmlGem
control. With

the

result, we use UTF
-
8 to encode our content and save it as
XML.

Program
2
.2


/** Create
s new form NewJFrame2 */


public NewJFrame() {


initComponents();


if(xmlGem1.getXmlGem().getRootController().


getInsertionView()!=null){


jSplitPane1.setLeftComponent(xmlGem1.getXmlGem().


get
RootController().getInsertionView());


}


this.addWindowListener(new WindowAdapter(){


public void windowClosing(WindowEvent e) {


doSave();


}


});


}




private void doSave(){


JFi
leChooser oChooser=new JFileChooser();


oChooser.setFileFilter(new FileFilter() {


public boolean accept(File pathname) {


return pathname.isDirectory() ||


pathname.getName().endsWith(".xml");



}


public String getDescription() {


return "Xml File";


}


});


oChooser.setDialogType(JFileChooser.SAVE_DIALOG);


oChooser.showSaveDialog(NewJFrame.this);


File oFile=oChooser.getSele
ctedFile();


if(oFile==null){


return;


}


try {


RunnableModel oRM=(RunnableModel) xmlGem1.getRootGroup();


// Do Save


FileOutputStream oOutput =new FileOutputStream(oFile);


oOu
tput.write("<?xml version=
\
"1.0
\
" encoding=
\
"utf
-
8
\
"?>".getBytes("utf8"));


oOutput.flush();


oOutput.write(oRM.getInstanceTree().getRootNode().


getUnderlyingRepresentation().toString().getBytes("utf8"));



oOutput.close();


} catch (IOException ex) {


ex.printStackTrace();


}


}

Chapter 3:
The
Structure

of XmlGem Control


This chapter discusses the system structure of XmlGem Control and gives
an overview of all items in the sy
stem structure. After this chapter, we will have
an overview of the structure of XmlGem Control, including: grammar, binding,
user interface, and their relationships.

3.1
The
Components

in

XmlGem Control

XmlGem is comprised of 7 blocks, figure
3.1
. Each of

them is pluggable.
The following paragraphs explain
each of them from bottom to top
:

1.

Supporting Services

Supporting services block in XmlGem provides a lot of services for
other blocks, like clipboard service, undo/redo service, convenient
functions, etc.

In the service and service table chapter, we will discuss it
deeper.

2.

UI Controllers

UI Controllers are one of the core blocks in XmlGem. They handle the
execution of XmlGem. A UI controller decides what kinds of bindings,
templates and building blocks it
uses. Currently, XmlGem has a default UI
controller which exposes a lot of controllers. In the following chapters, we
will go into the default UI controller and these controllers exposed by the
default UI controller.

3.

XmlGem Model

XmlGem Model, whose code
name is Gollum, is one of the core
blocks in XmlGem. It handles the underlying data structure. Currently, the
implementation we have handles XML and XML Schema. XmlGem Model
is comprised of grammar and instance. We will discuss grammar and
instance in the
later sections of this chapter.


Figure
3.1
: The Structure of XmlGem.

4.

UI
-
Model Bindings

UI
-
Model Bindings are binding objects in XmlGem. They

driven by UI
Controllers

bind a user interface with an instance item of XmlGem Model.

5.

Templates

Templates are out
put of XmlGem Designer. XmlGem Control uses
them to know how to render the user interface and which bind object
should use to bind the user interface with instance item.

6.

XmlGem Building Blocks

XmlGem Bui
lding Blocks are user interface

objects

in XmlGem. Al
l
user interfaces displayed in XmlGem are instances of UIComponent or
UIContainer. We will discuss them in the later section

7.

Other Widgets

Besides XmlGem Building Blocks, XmlGem Control uses other Swing
objects to help it to layout user interface. Like, bo
rder, layout manager,
color, font, etc.

3.2
User Interface in XmlGem

There are two major user interface object proposed by XmlGem,
UICompnoent and UIContainer. All use interfaces used in XmlGem are
descendents of these two classes and are built from Swing
user interfaces. It is
very important that you should use the APIs of UIComponent and UIContainer
instead of Swing

APIs
. Once using Swing APIs, you may break the state of
UIComponent or UIContainer

and make XmlGem
fragile
.

UIComponent is the base class of
all user interfaces in XmlGem. It is built
from JPanel. All descendents of UIComponent can add other Swing user
interface upon it. Like XComboBox, it adds a JComboBox

as its user interface
.

UIContainer is
the base class of all container
s
in XmlGem. It is d
escended
from UIComponent. The base implementation of UIContainer uses JPanel as
its content pane. All descendents may use other object as their content pane.
Like XTabbedPane, it uses JTabbedPane as its content pane.

3.3
Grammar and Instance

Grammar and I
nstance is the model of XmlGem. They provide an abstract
layer of underlying data structure. An XmlGem component can manipulate
instance without the knowledge of underlying data structure. A Grammar
document is the definition of a kind of Instance in XmlGe
m. Like XML Schema,
Grammar also has the definition of operators and node types, which is
elements or attributes in XML Schema. Like XML document, an Instance
document is a document instance of Grammar. But, unlike XML document, an
Instance document still
has instances of operators in it. The operators in
Instance document make the structure more similar to Grammar. That helps
users know the relationship between Grammar and Instance.


The default implementation of Grammar and Instance uses the XML
Schema an
d XML document as its underlying data structure. So, the following
paragraphs are going into deeper about Grammar and Instance and the
relationships between “Grammar and Instance” and “XML Schema and XML
document”.

The structure of Grammar likes the struct
ure of XML Schema. It has
operators and nodes. Unlike XML Schema has operators, elements, attributes,
complex types, simple types, Grammar only have operators and node types.
An element or attribute will be mapped to node type in XmlGem. And complex
types
or simple types which are used by elements or attributes are expanded
in the node types.


Unlike XML document, the structure of Instance in XmlGem is similar to
Grammar. As we mentioned before, Instance is a document instance of
Grammar. So, the main diffe
rence between is the operators or nodes in
Grammar are definitions, and the operators and nodes in Instance are
instances.

3.4
Transformation between XML Schema and Grammar


As we known, Grammar is a kind of definition like XML Schema and
XmlGem has an imp
lementation to transform from XML Schema to Grammar.
So, here is how XmlGem does when transformation is needed.


Let’s look at the following XML Schema, the Purchase Order from W3C,
figure
3.2

and
3.4, and XmlGem Grammar, figure 3.3 and 3.5
. Because of
doc
ument size, we discuss this XML Schema in two parts. The first part of
Purchase Order contains a few attributes and three major element, shipTo,
billTo, and comment. Another part contains the items element which has an
iteration of item element. We will di
scuss these two portions in the following
paragraphs. To identify the XML Schema and Grammar, we will use elements
and attributes to denote items in XML Schema, and we will use nodes to
denote items in Grammar.


Figure
3.2
: A portion of Purchase Order Sch
ema from W3C.


Figure
3.2

is the first part of Purchase Order from W3C. Figure
3.3

is the
first portion of Purchase Order transformed to Grammar. As we seen, there is
also a node named purchaseOrder in Grammar mapped to purchaseOrder
element. Under purchas
eOrder node, we find a Sequence node mapped to the
sequence element in XML Schema. But unlike sequence in Purchase Order
XML Schema, this Sequence node contains the orderDate attribute and all
child nodes.


Figure
3.3
: The first portion of Purchase Order
Grammar


Unlike orderDate attribute in XML Schema, orderDate mapped to
@orderDate is under the Sequence node and there is also another Sequence
node with #Text node under @orderDate. So, all of attributes are transformed
into this kind of fashions. Another

example of Sequence node with #Text node
under some node is all elements with simple type, such as name, street, city,
state, zip, and comment.


There is a node named Optional as the parent of @country. That means
the @country node is an optional node whi
ch mapped to country attribute of
shipTo. So, all optional elements or attributes are wrapped with an Optional
node to denote it is an optional node, the minimum occurrence equal to 0.


The following two figures,
3.4

and
3.5
, are the second part of Purchas
e
Order XML Schema and Grammar.


Figure
3.4
: Another portion of Purchase Order from W3C.


In this portion of Purchase Order, our focus is changed to items elements
of Purchase Order. The item element contains a list of item element. Mapping
to Grammar, th
ere is also an items node which contains an Iteration node. With
this Iteration node, XmlGem knows the following node, item, has a maximum
occurrence greater than 1.


Like the first portion of Purchase Order, the partNum attribute and other
elements are tr
ansformed to a node with a Sequence and @Text node under it.


There is another important transformation which didn’t display in these
figures. If there are two or more elements using the same complex type, such
as shipTo and billTo use USAddress complex ty
pe, the first layer of elements
or attributes are transformed to a referrer node in Grammar, such as @country,
name, street, city, state, and zip.


Figure
3.5
: Another portion of Purchase Order Grammar

3.5
The Rules of Sub
-
tree Identification


XmlGem divi
des the grammar tree into a lot of small sub
-
trees. With these
sub
-
trees, users can layout the user interface freedom. In this sub
-
tree
mechanism, XmlGem promises that there is only one unique node in a
sub
-
tree. So, a sub
-
tree is comprised of a sub
-
tree r
oot, a few non
-
leaf nodes,
and a few leaf nodes. It is very important that a sub
-
tree root is the leaf node of
its parent sub
-
tree. So, the sub
-
tree root exists in two different sub
-
trees if it is
not the grammar tree root. There are 7 rules proposed by Xm
lGem. If a
grammar node matches one of them, that node is the root of another sub
-
tree.
These rules are:

1.

If a node is a grammar tree root, it is a sub
-
tree root.

2.

If a node is a choice operator, it is a sub
-
tree root.

3.

If a node is an iteration operator, it

is a sub
-
tree root.

4.

If there is a node whose parent is a choice operator, it is a sub
-
tree root.

5.

If there is a node whose parent is an iteration operator, it is a sub
-
tree
root.

6.

If a node refers to another node, it is a sub
-
tree root.

7.

If a node is referre
d by another node, it is a sub
-
tree root.


Someone may think what about an instance tree. Does an instance tree
have sub
-
trees? The answer is “yes”. An instance tree also has sub
-
trees in it.
But to identify sub
-
trees is depended on grammar sub
-
tree this i
nstance tree
uses.


The figure
3.6

is an example of sub
-
tree identification. All sub
-
tree roots
are marked with an asterisk:



The purchaseOrder node is matched to rule 1.



The @country node is matched to rule 6, because of the
transformation.



The name node

is matched to rule 6, because of the transformation.



The street node is matched to rule 6, because of the transformation.



The city node is matched to rule 6, because of the transformation.



The state node is matched to rule 6, because of the transformation
.



The zip node is matched to rule 6, because of the transformation.



The comment node is matched to rule 6.



The Iteration node is matched to rule 3.



The item node is matched to rule 5.


Figure
3.6
: The example of sub
-
tree identification.

3.6
Binding


A Bi
nding is an object who binds a user interface and an instance node.
There are two kinds of binding in XmlGem, Structure Binding and Data Binding.
Structure Binding binds the structure among instance tree and user interface
tree. Data Binding synchronizes t
he value of an instance node and the value of
a user interface. If you are not a plug
-
in developer, you should not need to
know the mechanism of Binding.


Currently, XmlGem has IterationStructureBinding, ChoiceStructureBinding,
and SequenceStructureBinding

as its Structure Bindings; it has
XTextBoxDataBinding, XButtonGroupDataBinding, XButtonDataBinding,
XLabelDataBinding, XMultipleButtonGroupDataBinding and
XComboBoxDataBinding as its Data Bindings.

3.7
Binding, UI, Grammar and Instance


Binding, UI, Gram
mar and Instance are the main building blocks in
XmlGem. Binding binds UI and Instance and checks the value inputted in UI
against to Grammar. It is very hard to know the real relationship between them.
Let’s look at the following figure
3.7
:

A
D
_
_
D
C
Structure Binding
Structure Binding
C
G
_
_
F
Boundary Helper
A
B
C
E
F
G
D
Instance
Data Binding
Data Binding
Data Binding
Data Binding
?
?
Bound UI
?
Unbound UI
Sub
-
tree Root
?
Node

Figure
3.7
: Binding, UI, Grammar, and Instance


Figure
3.7

is an example. Let’s start from Instance block. In Instance block,
the A and C node are sub
-
tree root. So, we have two sub
-
trees in this example.
The sub
-
tree root A is mapped to a

bound UI named A controlled by a
StructureBinding, and sub
-
tree root C is mapped to another bound UI named C
controlled by another StructureBinding. There is a special service named
BoundaryHelper who helps UI A to display the UI C under it.


As to DataBi
ndings, All elements with simple type can have the
DataBinding object linked with UI widget, such as node G and node F have
their owned DataBinding linked with UI G and UI F. The most special part of
DataBinding in this figure is we can use two different D
ataBinding to bind the
same node with different UI widgets, such node D.