SOClass Modular version

1 - Basic example

Subject BasicTutorial
Version ADK 244
Issue date 16/07/2005
Beneficiaries Developers
File Tutorial - 1 - Basic example.doc
Status Final
Checked by Asycuda World - Lyon Competence center
Copyrights United Nations Conference on Trade and Development
 Developer Guide
Version ADK 244
1 - Basic example

Table of contents
1. MODULE CREATION ....................................................................................... 5
1.1. GLOBAL ARCHITECTURE GENERATION, USING SOMWIZARD............................. 5
2. DOCUMENT CREATION................................................................................ 10
2.1. DEFAULT FILES NEEDED ................................................................................ 10
2.1.1. Shared parts ............................................................................................ 10
2.1.2. Client side................................................................................................ 12
2.1.3. Server side ............................................................................................... 16
3. MODULE CONFIGURATION ........................................................................ 18
3.1. DATABASE CONFIGURATION.......................................................................... 19
3.2. BUSINESS UNIT .............................................................................................. 20
3.3. BINDER.......................................................................................................... 20
3.4. DOCUMENT LIBRARY ..................................................................................... 21
3.5. PROPERTIES FILE ........................................................................................... 22

United Nations Conference on Trade and Development Page 1 of 23

 Developer Guide
Version ADK 244
1 - Basic example

Figures
FIGURE1 - THIS IS AN EXAMPLE OF FIGURE........................................................................... 3
FIGURE2 - GUI TO OBTAIN ................................................................................................... 4
FIGURE3 - SOM WIZARD FIRST SCREEN ............................................................................... 5
FIGURE4 - LIST OF INSTALLED MODULES.............................................................................. 6
FIGURE5 - CREATION OF A NEW MODULE ............................................................................. 6
FIGURE6 - GENERAL INFORMATION ABOUT THE MODULE..................................................... 7
FIGURE7 - SPECIFIC INFORMATION ABOUT THE MODULE ...................................................... 8
FIGURE8 - DEPENDENCIES BETWEEN MODULES .................................................................... 9

Source code
SOURCE 1 - THIS IS AN EXAMPLE OF SOURCE CODE ................................................................ 3
SOURCE 2 - GLOBAL.PROPERTIES NEW LINES .......................................................................... 9
SOURCE 3 - ADDING GLOBAL CONSTANTS IN THE C_TUTORIAL1 CLASS .............................. 11
SOURCE 4 - DATA MODEL BASIC METHODS IN THE D_TUTORIAL1 CLASS ........................... 11
SOURCE 5 - BUSINESS RULES IN THE DC_TUTORIAL1 CLASS ............................................... 12
SOURCE 6 - VISUAL DOCUMENT DECLARATION IN THE VD_TUTORIAL1 CLASS ................... 12
SOURCE 7 - VISUAL FORM DECLARATION IN THE VF_TUTORIAL1 CLASS............................. 13
SOURCE 8 - VISUAL PAGE DECLARATION IN THE VP_TUTORIAL1 CLASS ............................. 15
SOURCE 9 - S_TUTORIAL1 CLASS ......................................................................................... 16
SOURCE 10 - PROP.XML DATABASE CONNECTION .................................................................. 19
SOURCE 11 - INSTALL_SRC.XML DATABASE DEFINITION ........................................................ 20
SOURCE 12 - BUSINESS UNIT DECLARATION IN THE INSTALL_SRC.XML FILE .......................... 20
SOURCE 13 - BINDER DECLARATION IN THE INSTALL_SRC.XML FILE ...................................... 21
SOURCE 14 - SHORTCUT DECLARATION IN THE INSTALL_SRC.XML FILE ................................. 21
SOURCE 15 - UN.ASYTUTORIAL.PROPERTIES MODIFICATIONS ................................................ 22

United Nations Conference on Trade and Development Page 2 of 23

 Developer Guide
Version ADK 244
1 - Basic example

How to read this document

This symbol indicates advice and recommendations. Information on best
practices and recommended procedures related to the current topic is
contained here.

Keyword Definition

This symbol indicates a warning. Information on common pitfalls or dangers

associated with the current topic is contained here.

This symbol indicates an example to further illustrate the current topic.

Source 1 -
This is an example
of source code Source code.

Phase 1 Phase 2 Phase 3

Figure1 - This is an example of figure

United Nations Conference on Trade and Development Page 3 of 23

 Developer Guide
Version ADK 244
1 - Basic example

Objective
In this document you will learn
a. How to create the global architecture of a module
b. How to create the default classes of a document

This tutorial will only present basic structure of a module, and all required files. A module
wizard is used to create this architecture.

Figure2 - GUI to obtain

United Nations Conference on Trade and Development Page 4 of 23

 Developer Guide
Version ADK 244
1 - Basic example

1. Module creation

1.1. Global architecture generation, using somwizard

The SOClass platform contains a tool to create the global architecture of a module: SOM
wizard. The needed directories and files are generated.

This tool is installed in the \adk\bin\ directory.

Figure3 - SOM wizard first screen

United Nations Conference on Trade and Development Page 5 of 23

 Developer Guide
Version ADK 244
1 - Basic example

On the next screen, the list of installed modules is shown. Don’t select any and press the
next button. The utility will ask for the creation of a new module.

Figure4 - List of installed modules

Figure5 - Creation of a new module

United Nations Conference on Trade and Development Page 6 of 23

 Developer Guide
Version ADK 244
1 - Basic example

The global information about the module has to be entered on the next screen.

Figure6 - General information about the module

United Nations Conference on Trade and Development Page 7 of 23

 Developer Guide
Version ADK 244
1 - Basic example

In the next screens, fill the module description and license screen, then the select specific
information screen is displayed.

Figure7 - Specific information about the module

United Nations Conference on Trade and Development Page 8 of 23

 Developer Guide
Version ADK 244
1 - Basic example

A module can have dependencies with others. It will be used during the installation. Select
modules if necessary.

Figure8 - Dependencies between modules

Click on the OK button to begin the document architecture generation phase.

At the end of the generation a message indicate that our new module has been created.
The asytutorial architecture module has been created under C:\abc\un\asytutorial directory.
Additional lines had been added in C:\abc\adk\build\global.properties file. These
new lines contain information for somwizard tool as following (see Module Architecture
document for details):

Source 2 -
global.properties #Module asytutorial
new lines #Wed May 26 11:30:03 CEST 2004
mod.un.asytutorial.client.jar=${mod.un.asytutorial}/lib/asytutorialc.jar
mod.un.asytutorial.shared.jar=${mod.un.asytutorial}/lib/asytutorial.jar
mod.un.asytutorial.server.jar=${mod.un.asytutorial}/lib/asytutorials.jar
mod.un.asytutorial=${un_dir}/asytutorial
mod.un.asytutorial.dsc=test tutorial

United Nations Conference on Trade and Development Page 9 of 23

 Developer Guide
Version ADK 244
1 - Basic example

2. Document creation

Presented notions
• Declaration of the minimal variables
• Creation of the Data Model file
• Definition of the Graphical User Interface (GUI)
• Definition of the server side

Classes that will be created

• C_radical.java shared directory
• D_radical.java shared directory
• DC_radical.java client directory
• VD_radical.java client directory
• VF_radical.java client directory
• VP_radical.java client directory
• S_radical.java server directory

2.1. Default files needed

2.1.1. Shared parts

Shared parts are in the folder:
un\asytutorial\shared\src\un\asytutorial\tutorial1

The starting point is to define all the constants in the C_radical classes. However, in
this example, no Data Model will be implemented. This means that the only necessary
constants to be declared are the ones related to the creation of a new instance of an e-
document. Consequently, only a nil operation called “Null” is going to be created.

United Nations Conference on Trade and Development Page 10 of 23

 Developer Guide
Version ADK 244
1 - Basic example

Source 3 -
Adding global package un.asytutorial.tutorial1;
constants in the
C_Tutorial1 class import so.kernel.core.*;

public interface C_Tutorial1 {

/**
* Definition of the Constant data
*/

// Operation name
public static final String OP_NULL = "Null";

// Operation identificator
public static final int OI_NULL = Operation.INTERNAL_OPERATIONS_MAX+1;

Next step is to define the Data Model class, D_radical. If there is no Data Model,
there is no definition within this class. However, this is the right time to define the
basic methods that will be implemented later for more complex documents.

Operation Method name

Data model definition public void define_DataModel()
Finder definition public void define_FinderModel()
Reference table alias declaration public void define_ReferenceModel()
Data Model business rules definition public void define_ClientBusinessRule()

Source 4 -
Data Model basic package un.asytutorial.tutorial1;
methods in the
D_Tutorial1 class import so.kernel.core.*;

public final class D_Tutorial1 extends KDocument implements C_Tutorial1 {

/**
* Document constructor - Sets the document name
*/
public D_Tutorial1() {
super("Document name");
}

/**
* Definition of the Data Model
*/
public void define_DataModel() { }

/**
* Definition of the Finder Model
*/

United Nations Conference on Trade and Development Page 11 of 23

 Developer Guide
Version ADK 244
1 - Basic example

public void define_FinderModel() { }

/**
* Definition of the Reference Model
*/
public void define_ReferenceModel() { }

/**
* Definition of the Client Business Rules
*/
public void define_ClientBusinessRule() { }
}

2.1.2. Client side

The four necessary classes to create the graphical aspect are in the
un\asytutorial\client\src\un\asytutorial\tutorial1\client
folder.
Even though business rules related to the client are defined in separate classes, they
have to be declared in the DC_radical class. In this simple case there is none, that is
the reason why the initRules method is empty.

Source 5 -
Business rules in package un.asytutorial.tutorial1.client;
the DC_Tutorial1
class import un.asytutorial.tutorial1.*;
import so.kernel.client.*;
import so.kernel.core.*;

public class DC_Tutorial1 extends ClientDocument implements C_Tutorial1,

KernelEventConstants {

void initRules(D_Tutorial1 doc) { }

void initRules(D_Tutorial1 doc, VD_Tutorial1 vd) { }

}

VD_radical (VD stands for Visual Document) is the single class that contains the
global definition for the visual document. This is where the visual form(s) has / have
to be declared. In our example, there is only one visual form, VF_Tutorial1.

Source 6 -
Visual document package un.asytutorial.tutorial1.client;
declaration in the
VD_Tutorial1 class import so.kernel.client.*;
import un.asytutorial.tutorial1.C_Tutorial1;

public class VD_Tutorial1 extends KVisualDocument implements C_Tutorial1 {

United Nations Conference on Trade and Development Page 12 of 23

 Developer Guide
Version ADK 244
1 - Basic example

/** Creates new VD_Tutorial1 */

public VD_Tutorial1() {
super();
setTitle(lng("Document title"));
setHelp("Help.html");
}

public void initializeForms() {

VF_Tutorial1 form = new VF_Tutorial1();
addForm(form);
setSize(getPreferredSize());
}

/**
* Retrieves a property string in the current working language.
*/
public static String lng(String property) {
return so.i18n.IntlObj.createMessage("Tutorial", property);
}
}

The main form of the document corresponds to the class VF_radical (VF stands for
Visual Form). Every other form of the visual document is defined in a separate class.
The visual page(s) is/are also defined in the main visual form class
(VF_radical.java).

Source 7 -
Visual form package un.asytutorial.tutorial1.client;
declaration in the
VF_Tutorial1 class import so.kernel.client.VisualForm;

public class VF_Tutorial1 extends VisualForm {

/** Creates new VF_Tutorial1 */

public VF_Tutorial1() {
super(lng("form name"));
}

public void initializePages() {

VP_Tutorial1 page = new VP_Tutorial1();
addPage(page);
}

/**
* Retrieves a property string in the current working language.
*/
public static String lng(String property) {
return so.i18n.IntlObj.createMessage("Tutorial", property);
}
}

The main page of the main form corresponds to the class VP_radical, (where VP
stands for Visual Page).

United Nations Conference on Trade and Development Page 13 of 23

 Developer Guide
Version ADK 244
1 - Basic example

Every other page of the visual document is defined in a separate class. This is the class
where all the visual controls are going to be defined.
In our example, there is no visual control, only a title stripe and a label. Furthermore,
as there is not even a connection to the database, there is no facet definition within it.

United Nations Conference on Trade and Development Page 14 of 23

 Developer Guide
Version ADK 244
1 - Basic example

Operation Method name

Visual controls definition No method, directly declared within the class
Display parameters definition public void initVisualPage()
Visual controls initialisation public void initVisualControls()
Facets creation public void initFacets()
Server business rules declaration public void initRules()

Source 8 -
Visual page package un.asytutorial.tutorial1.client;
declaration in the
VP_Tutorial1 class import java.awt.Color;
import java.awt.Font;
import so.kernel.client.KVisualPage ;
import so.kernel.client.elf.ElfVisualPage;
import un.asytutorial.tutorial1.C_Tutorial1;

public class VP_Tutorial1 extends ElfVisualPage implements C_Tutorial1 {

/** Creates new VP_Tutorial1 */

public VP_Tutorial1() {
super();
initVisualPage();
initVisualControls();
}

public void initVisualPage() {

setSize(550, 475);
setBackgroundFilter(new Color(0, 0, 0, 255), true);
setBackgroundGradientFilter(200, 200, new Color(255, 255, 255, 255), 0, 0,
new Color(0, 0, 102, 255), 2);
setDefaultKTitleStripeFont(new Font("Arial Black", Font.PLAIN, 15));
setDefaultJLabelFont(new Font("Tahoma", Font.PLAIN, 14));
setDefaultJLabelColor(new Color(245, 248, 255, 255),
new Color(204, 204, 255, 65), false);
setDefaultJLabelBorder(KVisualPage.borders[0]);
}

// Initialization: Visual controls

public void initVisualControls() {
// Title stripe
addTitleStripe( 0, 4, 444, 24, lng("example of e-Doc"));

// Label
// syntax: add( X, Y, Width, Height, lng("label caption"));
add(20, 50, 200, 20,lng("This is your first e-Document."));
}

public void initFacets() { }

public void initRules() { }

/**
* Retrieves a property string in the current working language.
*/
public static String lng(String property) {
return so.i18n.IntlObj.createMessage("Tutorial", property);
}
}

United Nations Conference on Trade and Development Page 15 of 23

 Developer Guide
Version ADK 244
1 - Basic example

2.1.3. Server side

Eventually, the S_radical class describes the server behaviour. This is the class
where we find the definition of the cycle of life of the document (called Document
Path Processing or DPP), the universe of operation definition and database connection
management. The table below describes the most significant methods used in this
class:

Operation Method name

Binder definition public void defineBinder()
Document processing path declaration protected DPP createDPP()
Operation groups and sub operations creation protected Operations
createValidOperations()
Initialisation of the connection to the database public void initializeDatabase()
Translation manager definition public static so.kernel.core.i18n.IntlObj
lng(String property)

Server parts are in the folder:

un\asytutorial\server\src\un\asytutorial\tutorial1\server

Source 9 -
S_Tutorial1 class package un.asytutorial.tutorial1.server;

import so.kernel.core.Operation;
import so.kernel.core.Operations;
import so.kernel.server.OperationFactory;
import so.kernel.server.DPP;
import so.kernel.server.GCFServerBinder;
import un.asytutorial.tutorial1.C_Tutorial1;

/**
* Server side class that manages the binding document/database
*/
public class S_Tutorial1 extends GCFServerBinder implements C_Tutorial1 {

// Define the Document processing path

protected DPP createDPP() {
DPP dpp = new DPP();
dpp.add(null, OP_NULL, null);
return dpp;
}

public void defineBinder() {

// Define the Document processing path
setDPP(createDPP());
}

protected Operations createValidOperations() {

Operations ops = super.createValidOperations();
// "Nil" operation
Operation op_nil = OperationFactory.makeNilOperation(OI_NULL, OP_NULL);
ops.add(op_nil);
return ops;
}

United Nations Conference on Trade and Development Page 16 of 23

 Developer Guide
Version ADK 244
1 - Basic example

public void initializeDatabase() {}

The DPP (Document processing path) is very simple : only one operation, and one
state. But it is mandatory to create one, otherwise the operation is not visible.

United Nations Conference on Trade and Development Page 17 of 23

 Developer Guide
Version ADK 244
1 - Basic example

3. Module configuration
We have to prepare all configuration files.

In this chapter you will learn

Prepare properties files for deployment.

Properties files that will be modified

install_src.xml \server\som
prop.xml \server\som
un.asytutorial.properties \server\som\config

The install_src.xml file is in folder: un\asytutorial\server\som

Install_src.xml is used to create the som file by using ant som command in server
directory (see Installation Guide for details).
During the module deployment, som file is used by mast tool to install the module on the
ASYCUDA server.
So we need to modify the install_src.xml to prepare our document installation.
We will create database declaration, Business Unit, Binder and Document Library shortcut.

United Nations Conference on Trade and Development Page 18 of 23

 Developer Guide
Version ADK 244
1 - Basic example

3.1. Database configuration

In our example, we need to define a database even though we don’t use it for our
document. Our database will called asytutorialGCF.

The GCF database, or "Government Class Framework", offers document

historical tracking, versioning, ownership, e-signature, security and DPP
(Document Processing Path). The GCF is the backbone of the management
of SO-Class e-documents. It allows users to access all versions of a
particular document and to retrace the evolution of an e-document.
For GCF e-documents, two databases are created: one to store all e-
documents in their latest version, and one to store the previous versions of
each e-document. The version-database stores serialized objects containing
all necessary information about a version of an e-document. A GCF e-
document is identified by a primary key composed of an Instance
Identification to identify uniquely a document's instance independently of its
data elements

The prop.xml, which is situated in un\asytutorial\server\som folder, has to be

modified, as follow:

Source 10 -
Prop.xml database <properties>
connection <group type="connection">
<property name="gcf.drv_manager" from="driver" />
<property name="gcf.url" from="url" default="asytutorialGCF" />
<property name="gcf.user_name" from="user" />
<property name="gcf.password" from="password" />
<description><![CDATA[Connection to database Module asytutorialGCF is required.
This database is available. You can create new or use the same database.
Then enter connection properties in this form.]]></description>
</group>

</properties>

Don’t forget to create an empty database named asytutorialGCF.mdb in

our database folder c:\abc\mDatabase.

United Nations Conference on Trade and Development Page 19 of 23

 Developer Guide
Version ADK 244
1 - Basic example

The file install_src.xml have to be modified as follow:

Source 11 -
install_src.xml <db manager="${gcf.drv_manager}" url="${gcf.url}" user="${gcf.user_name}"
database definition password="${gcf.password}">
<GCF>
<table type="History" name="un_asytutorial_History"/>
<table type="IED" name="un_asytutorial_IED"/>
<table type="Locks" name="un_asytutorial_Locks"/>
<table type="Track" name="un_asytutorial_Track"/>
</GCF>
<appserver dbsource="jdbc/un.asytutorial.gcf" name="un.asytutorial.gcf">
<pool minPoolSize="1" maxPoolSize="-1" maxIdleTime="5"/>
</appserver>
</db>

3.2. Business unit

In this example, we will create a business unit called “BUtutorial”. The business unit is
declared within <system> XML tags

Business Unit represents a general name for all authorized persons who
have the same claims.

Source 12 -
business unit
declaration in the <BU name="BUasytutorial">tutorial BU</BU>.
install_src.xml file

The Business Units on a document could be defined manually filling this file or using the
ASYCUDA client application. The defined Business Units will be added automatically in
ASYCUDA environment with the appropriated rights if they are defined in the
install_src.xml file.

3.3. Binder
Binder is usually situated after business unit definition within <system> XML tags.

Binder A server side class that manages the binding of the

document and the database and the Document
Processing Path. It defines the document server binder
business logic that, for security and architectural
reasons, has to be executed on the server. It
encompasses server rules attached to operations, and
table connectors.

United Nations Conference on Trade and Development Page 20 of 23

 Developer Guide
Version ADK 244
1 - Basic example

Source 13 -
Binder declaration ...
in the <binder name="B_TUTORIAL_1" status="">
install_src.xml file <field name="server" value="un.asytutorial.tutorial1.server.S_Tutorial1"/>
<field name="dom" value="un.asytutorial.tutorial1.D_Tutorial1"/>
<field name="client" value="un.asytutorial.tutorial1.client.DC_Tutorial1"/>
<access bu="BUasytutorial">
<full/>
</access>
</binder>
…

3.4. Document library

Shortcut is usually situated after binder tags definition within <DL> XML tags.

Document The holder of shortcuts to applications bound to the

library system. Users will view those shortcuts according to
their user permissions.

Shortcut have a sense only if a binder is defined.

Source 14 -
Shortcut
declaration in the …
install_src.xml file <DL>
<folder name="Basic Tutorials" icon="">
<access bu="BUasytutorial">
<full/>
</access>
<item name="Tutorial 1 : Basic Example" icon="">
<field name="binder" value="B_TUTORIAL_1"/>
<field name="skin" value="un.asytutorial.tutorial1.client.VD_Tutorial1"/>
<access bu="BUasytutorial">
<full/>
</access>
</item>
</folder>
</DL>
…

United Nations Conference on Trade and Development Page 21 of 23

 Developer Guide
Version ADK 244
1 - Basic example

3.5. Properties file

The file un.asytutorial.properties created by somwizard tool and situated in
un\asytutorial\server\som\config have to be modified as follow:

Source 15 -
Un.asytutorial.prop module.un.asytutorial.gcf.url=$[un.asytutorial.gcf_URL]
erties modifications module.un.asytutorial.gcf.user=$[un.asytutorial.gcf_User]
module.un.asytutorial.gcf.password=$[un.asytutorial.gcf_Password]
module.un.asytutorial.gcf.tables.ied=un_asytutorial_IED
module.un.asytutorial.gcf.tables.history=un_asytutorial_History
module.un.asytutorial.gcf.tables.locks=un_asytutorial_Locks
module.un.asytutorial.gcf.tables.track=un_asytutorial_Track

Now you can compile and deploy your module with Ant tools.

United Nations Conference on Trade and Development Page 22 of 23