Dev Guide
Dev Guide
For
Server Side Java Thin Client
Development
On
WSBCC
Page 1
Guidelines for
Server Side Java Thin Client Development
on WSBCC
Table of Contents
1. Introduction
4. Analysis Stage
5. Design Stage
6. Implementation Stage
7. Testing/Debugging Stage
8. Common Beans
Page 2
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 1
1. Introduction
The ‘Server Side Java Thin Client Development ’ is based on the IBM framework,
WebSphere Business Component Composer (WSBCC). The guidelines provided in this
document is based on the Rational Unified Process (RUP) with special adaptation for the
use of the WSBCC Version 4.
- Designers
A guideline to the Object Oriented Analysis and Design for ‘Server Side
Java Thin Client’ application development. It provides the technology specific
methodology.
- Developers
A guideline to the application system implementation and testing for ‘Server Side
Java Thin Client’ development. It is also specifically prepared for the WSBCC.
Page 1
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 2
The diagram below illustrates different phases of project development and its
relationship:
From the macro angle, the project development as a whole is still adopting the traditional
system development life cycle. However, the new development methodology adopted
would enhance the quality and robustness of the final product.
Page 2
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 2
The iterative life cycle should also consider as a risk-mitigation-driven process. Technical
risk are assessed and prioritized early in the life cycle and are reviewed during the
development of each architectural release. Risks are attached to each iteration so that its
successful completion would mitigate the attached risks. The releases are scheduled to
ensure that the highest risks are tackled first.
Though the methodology is iterative, in each iteration cycle, there are still different stages
of SDLC, such as analysis, design, implementation and testing. The relationship between
each different stages of iterative methodology are illustrated below:
Conceptualisation
Prior to the development process, it should undergo the conceptualization process to
establish core requirement. The activities that occur involve the solicitation of ideas, the
prioritization of tasks to be accomplished, and possibly the “proof-of-concept” prototype.
The output from this process is a set of core requirements for the system.
Analysis
Analysis is the process of capturing and understanding the complete and consistent set of
system requirements. It is the “what” of the problem, not the “how’ of the problem. Use
case are developed for each of the major external actors identified in the context
diagram. For each use case, scenarios are developed and shown graphically onto the use
case diagram.
Page 3
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 2
Design
Design is the process of identifying the classes and objects. The object structure and
behavior are captured as attributes and operations in the class. The relationship between
the objects and class has to be refined to reflect it onto the class /state
diagram.
Implementation
During this phase, the system is matured by implementing a succession of executable
releases. Each release is an increment of the system, and added onto the functionality
provided by all previous releases.
Testing/Maintenance
The last step of this phase is to perform the initial testing on the evolved product release
and to carry out the maintenance to the evolved product. The users can also participate in
the testing and have an early taste on the ‘Close-to-end’ product.
The details of each development phases in the iterative life cycle will be elaborated in the
later section of the document.
Maintenance
With the production implementation, ongoing support and maintenance to the production
system will be provided. It involves future enhancement, error fixing and day-to-day
support activities. It is essential to ensure the deliverables prepared in various phases are
kept updated.
2.4 Tools
Analysis/Design
Rational Rose is the selected tool used for the object model analysis and design.
Page 4
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 2
Implementation
WebSphere Business Component Composer (WSBCC) is the selected development
framework for the front-end system implementation.
VisualAge for Java Visual base tools for Java Servlet, Applet development
Testing
Rational Team Test is one of the selected tool for the testing purpose.
Page 5
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 3
The HFE application is based on the WSBCC infrastructure for the building of browser
base thin client solution.
Java Client
(Applet/ XML
Application)
Server-side Server-side
Presentation Logic Business &
HTML HTML Integration
Client Logic
Java
Page 6
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 3
Context
A context is an object that defines and encapsulates a set of resources (data and services)
according to functional or business organizational entities. It is a basic entity of the
framework that maintains the data model for operation processing. A context can be
linked to another in a parent-child relationship, and multilevel context structures can be
created dynamically. The architectural rationale for using contexts is that they minimize
the amount of information that needs to be defined when adding an operation or service
and also the amount of information that needs to be passed to request an operation. The
ability to link contexts encourages the reuse of existing data and service definitions,
which can result in shortened project cycles. Examples of contexts that may be
appropriate for a banking organization are Branch context, Workstation context, User
context, Customer Session context and Business Operation context.
Contexts are chained in a hierarchical way, according to the business organization, from
more general to more specific (for example, from Branch to Workstation to Operation).
The resulting hierarchy or context structure is thus an n-array context tree that allows
teller operations to have access to the resources in a very structured, yet flexible way.
Data
Each operation manages a set of data items, whose values are input from the client
operation, shared from the contexts chain, received from external services, and so forth.
These data elements may be used in various ways, such as being sent to the host, written
as an electronic journal record, printed on a form, or passed to the client operation as
results. For each operation step, data elements can be formatted differently, depending on
the interacting service requirements.
The framework provides five base classes for dealing with data elements: DataElement,
DataField, DataCollection, KeyedCollection, and IndexedCollection. The data elements
hierarchy is extensible, and new classes can be derived easily when more functionality is
needed. The classes that conform to the data hierarchy do not have exactly the same
interface: only DataFields have value; and only collections have add(), remove(), or at()
methods. However, they have common instance variables such as name, and they share a
common base class to be included inside collections (generally, collections deal with data
elements). Methods for adding, retrieving, and deleting data elements are provided. There
are also methods for setting and getting the value of the data elements contained in a
collection. To maximize reusability of code, the DataElement class follows the
Composite design pattern, which is one in which any element of the collection can itself
be a collection.
Page 7
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 3
Typed Data
Data elements are not aware of the type of the business objects they represent. Typed
data elements can represent business objects, such as Date, ProductNumber, Money, and
have behavior that reflects the business rules that pertain to the business object they
represent. The implementation of some business operations may require typed
information in the data elements.
The framework provides the ability to work with or without typed data. Typed and
untyped data elements can coexist at run time, and this allows each operation to be
designed and implemented in the appropriate data typing mode. For example, a typed
data element knows how to format itself for display, how to clone itself, and the nature of
any validation required when requested to change its value.
Data is validated
JSP Servlet
Data is converted
This diagram shows the data flow for a typed data element. When a request is made, any
data sent to the servlet will go through a validation process before being updated to the
context. Any data sent from the servlet to the browser will go through a conversion
process to translate it to displayable/usable objects.
The typed elements are defined in dsetype.xml. Here is an example of a type definition :
Page 8
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 3
In this example HAmount is defined with a converter and validator. The converter will
handle two conversion types: “default, CCY”, it is also possible to define more than one
converter per type if needed. For HAmount another converter can be added by adding
the following line:
<hAmountConverter convTypes="XML"
implClass="com.hsbc.cgd.types.HAmountXMLConverter"/>
In this line another class has been associated with any conversion of type XML. More
than one converter is needed only when the business rules for conversion cannot be
handled by one class instance.
In this example incomeData is a typed element that contains two other typed elements
“amount” and “periodicity”. “amount” is of type HAmount and periodicity is of type
“String”. It is important to note that when defining typed elements any type being
referred to must be previously defined in the dsetype.xml file.
Therefore in this example the type definition for “HAmount” and “String” must be
written before the “incomeData” type definition.
After the definition for a new typed element has been defined in the dsetype.xml, the
property descriptor, converter(s) and validator classes must be implemented.
Property Descriptor:
Property descriptors are classes that associate itself with a type. Its responsibilities are to
provide information on the nature of the type through the use converters and validators.
When creating a new property descriptor it must extend
com.ibm.dse.base.types.AbstractPorpertyDescriptor. Then 3 methods must be
implemented.
Page 9
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 3
2. cloneDescriptee(Object): the method should provide an exact clone of the associated
type.
3. getImplClass(): this method should return either the class name for java.lang.String or
java.lang.String[] depending on how the type is sent to the server from the browser.
Converters:
Converters are responsible for translating an object in context to a usable object (most
likely a String) to the calling JSP page. Converters extend the class
com.ibm.dse.base.types.AbstractConverter and one of its methods must be implemented.
Debugging: When the data in not being formatted correctly in the JSP you can look in
this method. When this method is finished converting the associated type it will write it
into a output stream by calling the method writer.write(Object anObject). Inspecting this
method will indicate what is really being sent to the JSP.
Validators:
Validators are responsible for taking a string or string array from a JSP, applying business
rules to them and then returning the resulting object. Validators extend the class
com.ibm.dse.base.types.AbstractValidator and one of its methods must be implemented.
Debugging: If an exception is thrown when updating the context with a typed element
then this method is a good place to debug. Make sure that the object to be validated is the
right type that the validator is expecting and then step through your validation rules to
look for any errors.
Format
Data formatting is one of the key aspects of HFE. Each operation manages a set of data
items, whose values may be taken from input screens, other devices (MSR or check
Page 10
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 3
readers), shared data repositories (branch data, user data), host replies to a transaction,
etc. This data must be formatted and combined to build the messages that are used in
various ways, such as to send a transaction to the host, write a journal record, print a
form, and so forth. For each of these steps, the data items can be formatted differently
depending on the interacting object requirements (such as a host, electronic journal,
financial printer), making the formatting process increasingly complex.
Format classes in WSBCC helps to reduce the complexity. The objective of the
hierarchies of Format classes is to automate the formatting process as much as possible.
The provided set of classes handles a large number of formatting situations. In addition,
Format classes are designed with extensibility as one of their main objectives because
extending a class is the usual way of adding new required functionality.
Operation
An operation is the entity responsible for performing the set of tasks needed to complete
a basic financial operation, including data input and validation, interaction with external
services, and management of the results and data received. An operation has a client that
requests its execution, provides input data, and eventually receives the results. The
operation client can be a Java application, an applet, a batch command processor, another
more general operation, etc. Since an operation is completely separated from the observer
(the entity that launches an operation), the same operation can potentially be run by
different types of observers.
Automaton
The Automaton has been realized as the Processor class, with a standard externalizer
class, DSEProcessorExternalizer. A given instance of the Processor is initialized from its
external definition, which includes all possible states that the process can be in, the entry
actions and transitions for each of those states, and the definitions for every transition
inside a state. The data for transitions inside a state includes the name of the event
triggering the Transition, the target state to assume after executing the actions, the
Actions to be executed, and their related GuardConditions.
When an instance of the Processor is initialized, all of the possible states that the
abstracted business process can assume, as well as the corresponding entry actions,
transitions, and data for internal transitions within each state are cached in memory
without actually being instantiated. Objects from these definitions are only created at run
time when they are required during the life cycle of the process.
Page 11
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 3
Page 12
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 4
4. Analysis Stage
Responsibilities:
User
Provide workflow document (of the new system) for the development teams
Discuss and explain the workflow document with the development teams
Provide information about the screen layout (for mock-up creation)
Test the screen mock-up and provide feedback to the F/E team
Provide the general screen flow
Prerequisite:
Function Scope
Before the system analysis starts, the team needs to know the scope of the function to be
developed. The scope of the function defines what the function does in general, and to
what extent the business requirements are covered. For example, an account opening
process can be a function by itself, or it can be broken down into smaller functions under
smaller scopes like “open chequing account for a new customer” or “open term deposit
account for an existing customer”. The function scopes in these two scenarios are greatly
different. The function scope helps to define the boundary of the function, keeping the
analysis process in focus. The function scope can be in the form of a short description of
the function. It should be identified from the scope document of the project.
Page 13
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 4
If the function to be developed is an existing business function, an existing workflow
document will be very useful for the team to understand the current implementation. If a
workflow document is not readily available, the users need to explain the current
workflow either verbally or in writings. Understanding the current workflow allows the
development team to capture the requirement of the new system more easily.
Deliverables:
1. Requirement specification document (Optional)
2. Use case documents
3. Use case diagrams
4. Activity diagrams
5. Data dictionary
6. Screen Mock-Up
Migration deliverables:
In a migration project, the business requirement does not change and therefore there is no
need to produce another workflow document. Also, since the workflow is the same, the
activities diagrams and use case diagrams are the same as the existing system. The only
change that applies to the analysis process is the screen layout and screen flow. Since a
migration project often involves transforming the existing system using a different
technology, the same screen flow or screen layout may not be technically feasible or
desirable using a different technology. Also, some functions may be lost or require
workarounds. In these cases, the team should identify these constraints in the system
analysis stage and capture those in a function specific migration requirement document to
which designers and developers can refer. The deliverables in a migration project can be
summarized as the following:
1. Screen mock-up
2. Function specific migration requirement
This is by far the most important stage of the whole analysis and design process. An
accurate definition of the business process facilitates easy identification of system
requirement and thus a clearer and better design specification.
It is all too easy to start the requirement discussion with a wish list of system features but
remember that requirement analysis is about scrutinizing the business process itself and
identifying how the system can automate / facilitate the process. Too much focus on the
features at the beginning can easily lead to a project scope creep.
The requirement specification document is the starting point of this exercise. For each
system function, it describes the associated business process and its usage. It describes
Page 14
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 4
how the user will interact with the system and how the system should respond to the user
input. Very often graphics (e.g. screen mock-ups) helps to describe the process but it
should be noted that they are just a means to communicate requirement and should not be
taken as screen designs which would be better left as a GUI designer’s job. This section
will form the basis of a detailed use case document.
The requirement specification also describes the data exchanged between the user and the
system. E.g. names and addresses to be entered by users, how the system will print them
on chequebooks etc. For each data fields, the specification should specify:
• Display name
• Required? Mandatory?
• Business rules for this field (how to validate the entries, NOT how it looks as GUI!)
This section of the specification will form the basis of the data dictionary. Once this
specification is completed, it is to be put under a central document repository (e.g. Team
Assist or PMO).
With the specification providing the business context of the system, it is crucial to ensure
the mutual and correct understanding on the requirement between the users and the
designers. Instead of communicating through the correspondences, walk-through and
face-to-face discussion with the users could strengthen the understanding on the
requirement.
Page 15
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 4
The sample screen could focus on the body of the application function. It will provide an
initial taste about the look and feel of the application function. Furthermore, it can
include certain business logic into the prototype screen, and it could also extend to
include the brief description on the possible screen navigation.
Navigation logic
Also, it can include short notes of the application screen behavior and the possible
question or clarification required from the user department and the other counter parties.
Page 16
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 4
The prototype could also include the approach of invoking the application function, such
as the menu tree invocation and its behavior.
Page 17
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 4
Gathering the necessary information through the prototype discussion, a more rigorous
definition of the system behavior can now be documented by the use case document. The
use case plays a system behavior contract between the users and the system. For a
detailed guideline of how to write a use case please refer to the Use Case Writing Style
Guidelines [1] and the use case word document template [2]. Each use case should
include a reference (e.g. section number) to the requirement specification document.
Apart from the main system behavior which is described in the System Flow section of
the use case, certain GUI behavior requirement can be described in the User Interface
Comments section. If the use case is not written by the HUC users, it should be passed to
them for verification.
As use cases are collected and compiled, it is important to document the relationships
between them and how the user would navigate from one to another. This information
would help the task of system integration, adding a new function and determining if a
change in a certain function would impact other parts of the system. This is an important
basis when we define the inter-process formats and sub-flow calls. We use the use case
diagram to describe such information. A typical use case diagram looks like this:
Page 18
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 4
We use state diagrams in Rose to represent the activity diagrams in a use case. An activity
diagram is a high level representation of the overall system process flow. It is constructed
in a manner that can be understood by a non-technical reader who is familiar with flow
charts. Typically, an activity diagram (Fig. 3) has one initial state and one or more final
states. Each final state corresponds to an ending point in the use case. A process contains
states which can be displaying a page waiting for user actions, retrieving information
from the host system or manipulating data on the server. Transitions, which can be
triggered by user events or system events, connect the states. Notes can be attached to the
states or transitions to explain system GUI behavior. The point here is to construct a
visual representation of the process that can be understood by someone not familiar with
the technology behind the implementation.
Page 19
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 4
To add a new activity diagram, right click on the use
case and select new State Diagram (Fig. 4).
The data dictionary describes the attributes of each data fields. For each field, it specifies:
• length
• numeric/alpha/alphanumeric
• range (valid values or which standing data table)
The data dictionary will form the basis of JSP construction and MQ message definition.
For a sample data dictionary definition see [3].
After completing the above-mentioned documents and diagrams, the last step in the
analysis process is to prepare the screen mock-ups. It is a very useful and important
means to validate the concepts that are built so far in the analysis stage. It also
guarantees ‘no surprise’ to users when the function or the system is implemented and
delivered.
As the system is a web-based thin client application, the natural and standard approach
should require the analyst using HTML and JavaScript to construct the screen mock-ups.
WebSphere Studio is the suggested tool to facilitate this process.
In comparing screen mock-up with prototyping or modeling, the former involves more
development details. It requires the analyst to implement the GUI as detail as possible.
Therefore, it is desirable to have the GUI designer to help developing the user interface in
this early stage of analysis.
The screens developed should be very close, if not exactly the same, to the final GUI that
users will interact. The followings are considerations for developing the screen mock-up:
The menu item or button action should simulate the intended business or operations
process.
The link navigation should simulate the real screen or operations flows.
Page 20
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 4
From the users’ perspective, the screen mock-up is something concrete out of the
requirement specifications. The mock-up screens should give them a pretty good ‘look
and feel’. They should be able to ‘see’ the fields, ‘choose’ the menu item, ‘get’ the data
(hardcode, of course), ‘press’ the buttons and ‘navigate’ the links.
Although the process involves a detailed GUI design; the data provided are still hardcode,
and the functions are only simulated in terms of button and link actions to allow user
navigation. It is very important to emphasis that this exercise is still focus on ‘what’ data
to provide instead of ‘how’ to provide data. It copes with the approach of objected
oriented design that the implementation and technical details are hidden from the
interface. It is a conceptualization tool; and by utilizing it can make an early ‘interactive’
user walk through possible.
After the mock-up screens are developed, the next step is to present to users these ‘live’
requirement documentations. Users should be encouraged to play around with the
screens for some time. Feedbacks should be obtained afterwards. It is inevitable that the
requirement documentations and diagrams or even the prototype itself may need to be
changed or further refined. It is important that all the documentations should be kept up-
to-date especially those produced in the analysis phase, as they are the foundations of the
system development process.
Lastly, the difference between prototyping and screen mock-up is the level of
implementation details. The former is always primitive and will be thrown away in the
end usually. The latter, however, produces useful elements for deployment in the later
design and implementation phases. The flows (screens and simulated business
operations) described by the screen mock-ups can be directly translated to a state diagram
that will be produced in the design stage. The HTML tags and JavaScript coding
included in the screens also constitute the static part of the JSP that is going to be
developed in the implementation stage. It also has a consequence that it allows the
segregation of task between GUI designers (who focus on providing static data) and
application developers (who focus on providing dynamic data).
Page 21
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 5
5. Design Stage
Responsibilities
Prerequisite:
Deliverables from the Analysis stage
Deliverables:
1. State diagrams
2. Format class diagram
3. Operation/Format collaboration diagram
4. Data/Context class diagram
5. MQ message definition
6. Operation steps/ Automaton elements class diagrams
7. Data Dictionary
The next logical step is the detailed design. The deliverables from this stage will be
passed to the developers for actual implementation. Therefore the specification will be
implementation technology specific. The artifacts listed above will be based on the use of
WSBCC v4.0 for web application architecture. Note that the order listed above does not
imply an absolute sequential procedure but rather a general order in which they will
materialize.
To start the design modeling of the system, open the Logical View of the model. Open the
correct system folder (CRMS/ HFE). Create a package and control it. Name it as Design-
_function_name_.cat
Page 22
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 5
The starting point is to map the
system process as outlined in the
activity diagram to an actual state
machine (1) and how the data will
flow under such state machine (2).
Fig.5 shows a typical state diagram.
Think of the state machine as the
controller in the MVC paradigm.
Page 23
In WSBCC, the final state will fire an event to the parent process (if any) so the calling
process can handle such event. Open the final state specification and add an send event
entry action and specify the final event name. The developer will use that as the
typeIdInfo attribute of the final state.
Each operation has it own operation contexts. An operation context should be self-
contained, meaning that it has definition of all the data it would need for sending to host
and receiving from host. In general, to use an operation in a process, the data will flow
from JSP page -> Process Context -> Operation Context -> Process Context. -> JSP page.
WSBCC facilitates information passing between operations and process using
input/output mapping formats. Details of its usage can be found in WSBCC
documentation. The formats used are named as:
If you are using subflows you should also specify the inter-process formats here.
The mapping formats can be named in a similar as the one above except the
prefix should be like <proc name>To<proc name>. E.g.
custSearchToCreateJointAcctOutputMapFmt for mapping data from
the custSearch subflow back to the create joint account process.
Page 24
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 5
Another view of the relationship between the operation and the format elements
can be described by the operation / format collaboration diagram (3). It shows the
sequence in which the operations are called and the formats are used.
keyed collection, name it with the (from dsec txt) <<dsedata>> serialNumberItemData
errMessageData (from dsedata)
(from dsedata) serialNumber
Each host message operation has a Fig. 8 Data / Context class diagram
msgIdentifier and a collection
errMessageData for the common operation steps to operate. The msgIdentifier is
used to identify the message to the host and the errMessageData is used to hold
the host error messages.
For each context keyed collection, if at least one field is a date or amount, typed
data elements should be used to facilitate server validation and formatting. Apart
from validation and formatting, typed data elements also provide object-cloning
ability. Consult WSBCC documentation and respective type data element
specification for detail functioning. If a data collection is typed, the stereotype is
<<dsetype>>. Otherwise it is <<dsedata>>. For typed fields, if it is a string, the
type can be left blank. Otherwise it should specify the type descriptor used (date
or HAmount).
For the contexts, the stereotype is <<dse_procCtx>> for process context and
<<dse_operCtx>> for operation contexts. This will translate to the type attribute
of the operation definition. (type proc and op respectively).
Page 25
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 5
The operation step / format collaboration diagram (5) (Fig. 10) is used by the
developers to define the dseoper file. As you can see from Fig 10 one
operation is composed up of many “opsteps” which is illustrated by the branches
in the rose diagram. An opstep are discrete parts of an operation responsible for
completing a specific task (One opstep is implemented by one Java class). For
example opstep1 can be assigned to initialize a piece of data and opstep2 is then
responsible for sending that piece of data to the host. A good feature provided by
WSBCC is the flexibility to control the flow of the opsteps within an operation.
To elaborate, the xml file can map control from one opstep to another based on
the return code. (examples can be found under the Implementation section). The
rose diagram should define what opstep is to be used and their sequence of
execution in the workflow. Fig 10 shows a very straightforward example in
which the opsteps are executed one after the other.
Once this document is completed, place it in the central document repository and
include the URL in the format element definition in the rose model. Note that
THE MQ MESSAGE DEFINITION DOCUMENT SHOULD BE KEPT UP-
TO-DATE AT ALL TIME! This document will be heavily used in
implementation and testing stages for problem determination.
Page 26
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 5
From this definition, identify the detail and repeating item formats needed. As a
convention, the uphost messages are defined as (header/detail/etc.) requestFmt
and the downhost messages are defined as (header/detail/etc.)replyFmt.
Remember that in the design state diagram we have used a lot of conditions and
actions? For the developers to implement them we need to define the class
specifications for them. Create a class diagram and create the class definitions.
For the conditions’ evaluate() and initializeFrom() methods and actions’ execute()
specify its behavior in the documentation boxes.
Page 27
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 5
so if others want to modify it they will know. When you finish the changes update
the status to e.g. Create Lead MQ Msg definition updated 10/09/2000.
5.2 References
Page 28
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
6. Implementation Stage
This section provides the details in the process involved during the Implementation stage
for the Browser Base Thin Client development on WSBCC.
6.1 Assumption/Prerequisite:
1. The design documents are ready for implementation. Please refer to the design
document.
2. Developers should process the necessary WSBCC knowledge. They are required
to attend the WSBCC training and completed the necessary assignment during the
training. Please let your supervisor know if you do not have the proper training.
3. Installation of all the following necessary software from our software library.
Please ask your supervisor if you are not sure what versions we are currently
using.
After that, Press F2, add Features, and Select IBM Execution Monitor 1.1.
This will load into the workspace a set of projects that we need. Also, import
the following extra projects into your workspace:
WebSphere Business Components Composer Project
HTML CRMS
HTML HFE
HTML Infrastructure
In conclusion, please make sure all the following necessary projects are
loaded into your workspace:
HTML CRMS
HTML HFE
HTML Infrastructure
IBM Data Access Beans 3.0
IBM IDE Utility class Libraries 3.0
IBM Java Implementation 3.0
IBM Persistence EJB library 3.0
Page 29
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
IBM Servlet IDE Utility class libraries 3.0
IBM WebSphere Test Environment 3.0
IBM XML Parser for Java 2.0
Java class libraries 1.1.7A
JFC class libraries 1.0.3
Secure Socket Layer 3.0
Servlet API Classes 2.1
Sun class libraries PM Win32 1.1.7A
WebSphere Business Components Composer.
Description:
It is <user> responsibility to add the class description here!
If he didn't, why did <user> create this class ?
• WebSphere Studio
This is the development tool for generating the HTML and JSP pages.
Currently, this is link to our team connection environment for source code
control. Please refer to the Helping setup the WebSphere Application server to
run the WSBCC V4 Integration test server. The companion document is
HFE_Studio.doc.
Page 30
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
Page 31
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
6.2 Procedures:
In the design document, it should show the both the context structure and the
associate data structures. For example, the rose diagram of the create sole account
process will be like:
Page 32
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
Depends on situation, the parent context is not necessary to state explicitly in the
XML file.
In the design document, the class diagram (data) shows the data structure
relationship among them.
Page 33
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
<kColl id="openSoleDDAccountProcData">
<refData refId="custPersonalData" />
<refData refId="availableSerialNumberData" />
<refData refId="productData" />
<kColl id="custPersonalData">
<refData refId="countryCode"/>
<refData refId="groupMember"/>
<refData refId="branchNumber"/>
Page 34
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
<field id="serialNumber"/>
<field id="Classification"/>
<field id="marketSector"/>
<field id="Manager"/>
<field id="lastName"/>
<field id="firstName"/>
<field id="middleName"/>
<field id="preferredName"/>
<field id="Title"/>
<field id="iDType"/>
<field id="iDNumber"/>
<field id="Nationality"/>
<field id="countryOfResidence"/>
<field id="Sex"/>
<field id="dateOfBirth"/>
<field id="introduceToBank"/>
</kColl>
Operation Steps
Currently, we defined the following generic operation steps to format and
unformat the MQ message
FormatHeaderServerOpStep:
It responsible for formatting the Header Section of the CRMS/HFE
Message format. It will look for the Format Label name:
mqHeaderRequestFormat. Then, it will retrieve the corresponding refId
format in dseFmt.xml. In the above example, it will retrieve
mqHeaderRequestFmt in the dsefmt.xml. Furthermore, it will determine if
it is required to send the continuation message Section.
FormatDetailServerOpStep:
It responsible for formatting the Detail Section of the CRMS Message
format. It will look for the Format Label name: mqDetailRequestFormat.
Then, it will retrieve the corresponding refId format in dseFmt.sgml. In the
above example, it will retrieve mqCustSearchDetailRequestFmt in the
dsefmt.xml.
Page 35
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
ParseHeaderServerOpStep:
It is responsible for unformatting the Header Section of the CRMS
Message format. It will look for the Format Label name:
mqHeaderReplyFormat. Then, it will retrieve the corresponding refId
format in dseFmt.sgml. In the above example, it will retrieve
mqHeaderReplyFmt in the dsefmt.xml.
ParseDetailServerOpStep:
It is responsible for unformatting the Detail Section of the CRMS Message
format. It will look for the Format Label name: mqDetailReplyFormat.
Then, it will retrieve the corresponding refId format in dseFmt.xml. In the
above example, it will retrieve mqCustSearchDetailReplyFmt in the
dsefmt.xml.
ParseRepeatItemServerOpStep:
It is responsible for unformatting the Repeating Section of the CRMS
Message format. It will look for the all the Format Label name defined
in the dsedata:
<kColl id=repeatingItemsFormat>
<field id=mqSearchResultReplyFormat value=SrchResR>
<field id=mqProductDetailReplyFormat value=ProdDtlR>
<field id=mqContactReplyFormat value=ContactR>
<field id=mqMoreContactReplyFormat
value=MoreContactR>
<field id=mqCrossSellReplyFormat value=CrossSellR>
<field id=mqErrMsgReplyFormat value=ErrMsgR>
</kColl>
LookupErrorMsgServerOpStep:
This operation step will loop through all the error messages (stored in
errMesssageData), if any, and assign the value of the status indicator of the
MQ message to the msgType field of each individual error message. The
status of a message can be “N”(normal), “X” (warning), and “R”
(rejected). Although all the error messages in one MQ message from host
will be assigned the same value in the msgType field by this opStep, such
assignment is useful when a process involves more than one MQ message
and different types of error message (from different MQ messages) need to
be differentiated. This method is necessary in most operations because the
msgType field is used in the presentation of the error messages on the JSP.
Without this opStep, the error messages will not be shown properly.
In the design diagram, the operation step / format collaboration diagram shows all
the opsteps, which are used in the operation. Let’s use the MaintainCustomerInfo
Operation as an example.
Page 36
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
In the diagram, designer has already specified the opsteps it will use. Also, it
shows the formats that are related to each opsteps.
From the above diagram, developer can convert it into DSEOPER.XML file as
shown.
Page 37
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
In addition to the generic opSteps introduced, a developer can always add an
opStep to the operation where needed. Please follow these steps:
1. If the Java class for the desired opStep is not available, write a new class
extending com.ibm.dse.base.OperationStep, and name the class with suffix
“OpStep”. Then implement the “int execute()” method.
2. Add the definition of the opStep in dse.ini by putting a line like this in the
keyed collection “operations”:
<field id="the name of the opStep to be used in dseoper.xml " value="the Java class name of the opStep"/>
3. Add the opStep in an appropriate place in the operation definition. (See figure
6 and the associated sample operation definition.)
The execute() method in the opStep class should return an Integer. By convention,
the opStep should return “0” if it is run successfully, “1” if it encounters some
exceptions, and other integers for other specific situations. These integers will be
used to determine whether the operation should continue execute the next opStep,
skip the next opStep, or “return” the operation altogether. Define the “on0Do”,
“on1Do”, and “onOtherDo” in the opStep tag in the operation definition to obtain
the desired flow of opSteps.
Operation steps in WSBCC are designed to be a highly reusable part by its nature,
so writing opSteps for tasks specific to a given process or operation which are not
commonly shared by other processes/operations is not a good design. The
developer should consider writing an action or operation, which are more flexible,
to handle the task.
In the previous example the operation only had one flow of execution (top to
bottom). However one can control the sequence of execution of the opsteps by
utilizing the on?Do attribute of the opsteps in the dseoper.xml. Our previous
example had only the values “return” or “next” for this attribute, but instead, you
can put an opstep’s id as a value and the flow of execution would then jump to
that opstep specified by the id.
For Example:
Page 38
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
<!--------------------------customerNotebookPage ------------------------------------->
<htmlState id="custNotebookPage" type="page" typeIdInfo="customerNotebook.jsp">
<transitions>
<htmlTransition id="custNotebookPage.ok"
targetState="maintainCustomerInfoOp" />
</transitions>
</htmlState>
<!-------------------------maintainCustomerInfoOp ------------------------------------->
<htmlState id="maintainCustomerInfoOp" type="operation" >
Page 39
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
<entryActions>
<executeHostOperationAct id="maintainCustomerInfoOpAct"
operationName="maintainCustomerInfoOp" linkContextTo="processor"
inputMapFmt="maintainCustomerInfoInputFmt"
outputMapFmt="maintainCustomerInfoOutputFmt" refreshActiveView="true" />
</entryActions>
<transitions>
<htmlTransition id="maintainCustomerInfoOpAct.rejected"
targetState="maintainCustomerInfoErrorPage" />
<htmlTransition id="maintainCustomerInfoOpAct.warning"
targetState="maintainDDAccountOp" />
<htmlTransition id="maintainCustomerInfoOpAct.ok"
targetState="maintainDDAccountOp" />
</transitions>
</htmlState>
<!-------------------------maintainDDAccountOp ------------------------------------->
<htmlState id="maintainDDAccountOp" type="operation" >
<entryActions>
<executeHostOperationAct id="maintainDDAccountOpAct"
operationName="maintainDDAccountOp" linkContextTo="processor"
inputMapFmt="maintainDDAccountInputMapFmt"
outputMapFmt="maintainDDAccountOutputMapFmt" refreshActiveView="true" />
</entryActions>
<transitions>
<htmlTransition id="maintainDDAccountOpAct.rejected"
targetState="maintainDDAccountErrorPage" />
<htmlTransition id="maintainDDAccountOpAct.warning"
targetState="errorPage" />
<htmlTransition id="maintainDDAccountOpAct.ok"
targetState="confirmationPage" />
</transitions>
</htmlState>
Page 40
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
</htmlProcessor>
Note that WSBCC also provides self defined processor alternative, please see
Appendix F for the details about self defined processor.
Page 41
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
Also, please remember to include the following text into the JSP if there is a need
to use the context service.
7. Validation Alternatives
In the ‘thin client browser base’ configuration, the validation processing should
generally be undertaken at the page level rather than on the field level. However,
this validation principle may incur additional complexity on the validation logic
applied to the client tier.
JavaScript Validation
Due to the fact that the JavaScript validation cannot be ensure all the time, the
validation logic applied to the client tier, through the JavaScript, should be simple
and straight-forward validation. The validation, if at all possible, should be
limited to the individual field level. Any complex validation should be undertaken
at the middle and backend tier.Example for JavaScript validation, the
alpha/numeric field validation, restricting the input of incorrect data type.
Page 42
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
they represent. In the Data definition file, the DataElement could be defined its
reference type and linked to the objects through the Property Descriptors. The
data validation would be performed when the Data Element is requested to change
its value.
The validation would be performed simultaneously at the server when the page is
transmitted from the client. All the errors with the exception could be prompted
and displayed for user’s modification in one go.
The sample coding and steps involved are elaborated below for reference:
Step One:
In the Data definition file, find all refData tags,
1. if the related field is string type, then define its refType as String and
descriptor as StringDescrpitor in the typedData definition file;
2. if the related field is date type, define its refType as Date and descriptor as
DateDescriptor,
3. if it is amount type, then define its refType as HAmount and descriptor as
HAmountDescriptor.
4. If it is account/customer number, its refType as HAccount and descriptor as
HAccountDescriptor.
5. If it is KeyedCollection, define its descriptor as KcollDescriptor
6. If it is IndexedCollection, define its descriptor as IcollDescriptor
For the DateDescriptor, the default validator and converter are defined at the top
of the file. The validator is called when an HTML request includes an input to the
date object. The converter is called when a date object is to be displayed on a
Page 43
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
page. You DON’T need to define them in your dataCollection unless you want a
different mask or pattern. They are defined like this:
<DateDescriptor id="dateOfBirth" refType="Date">
<dateConverter convTypes="default" implClass="com.ibm.dse.base.types.ext.DateConverter"
mask="yyyy/MM/dd"/>
<dateValidator implClass="com.ibm.dse.base.types.ext.DateValidator" pattern="yyyy/MM/dd"/>
</DateDescriptor>
The validator pattern specifies the expected format of the date from the HTML
request. The converter mask specifies the format of the date to be displayed on
the page.
Step Two:
In the context declaration, the refType tag is a reference to the collection of typed
data (custSearchProData) to be instantiate when the context is created. Find the
refKColl tag for custSearchProcCtx and change it to refType.
Step Three:
1. In Jsp file, find all date type data and change the value equal to
utb.getStringValue(“...”).
For example,
original:dateOfBirth=(String)context.getValueAt("custOverviewData.otherCustData.dateOfBirth");
change to: dateOfBirth= utb.getStringValue("custOverviewData.otherCustData.dateOfBirth");
2. In some cases the dataElement cannot be referenced from the context directly
(e.g. certain element within an IndexedCollection), you can always get the
element with your own method and then cast it to the typed element (e.g.
HAmount). Remember to add “<%@ page import="
com.hsbc.cgd.gui.*"%>” in the beginning of the file in that case. Once it has
been casted you can call the toString() of the typed element. E.g.
((HAmount)kc.getValueAt("..”)).toString().
Page 44
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
In WSBCC V4, it introduces the finite state machine, the Automaton, in
controlling the business flow. When WSBCC automaton is used, a cross
validation mechanism is provided for developer to put in their cross validation
logic.
The WSBCC HTML request handler will perform the user-specified cross
validation after the field level validation is finished. The cross validation logic has
access to the process context and it can be performed at the process level
(whenever this process receives any events) or at the event level (when the
process receives a specific event).
If the cross validation fails, the framework pretends the transition (event) never
happens. Its HTML client support also provides the facility to display the error
messages from the cross validation.
The sample coding and steps involved are elaborated below for your reference:
Steps:
1. Define a validation class for the process extending
com.ibm.dse.automaton.html.HtmlProcessorXValidate:
public class CustSearchXVal extends com.ibm.dse.automaton.html.HtmlProcessorXValidate {
public final static java.lang.String CRITERIASTATE_OK = "custSearchPage.OK";
}
You can define event names as statics in this class for later reference.
if(transitionName.equals(CRITERIASTATE_OK)) {
String critType = (String)context.getValueAt("critType");
if (critType.equals("acctNum") && isEmpty((String)context.getValueAt("
custSearchRequestOpData.custAcctData.fullAcctNumberData.acctNumber”)))
{
addMessage("You have selected to search by HUB account number. Please enter it.");
}
}
}
Page 45
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
4. To indicate xvalidation logic in the rose model, if this is a general validation,
described it as a note. If this is an event based validation, put it in the
documentation box of the transition.
5. Note that if cross validation fails, the state acts as if the event never happens
and thus the process remains in the same state. WSBCC requires us to
specifies what page to be displayed in the JSP:
<%= utb.getErrorPageHtml ( "custSearch.jsp" ) %>
6. To display the error messages of the cross validation, you can get the
String[] of messages by this:
String[] eMsgs = (String[])context.getValueAt(HtmlConstants.ERRORMESSAGES);
For example, in my customer search criteria page, if no criteria is entered,
the xval will fail and a message produced. I set the error page to be the
criteria page again and display the error messages at the top of the page.
Page 46
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
<fmtDef id="mqMaintainCustInfoDetailRequestFmt">
<record dataName="maintainCustomerInfoRequestOpData">
<fString dataName="maintenanceCode"/> <nullCheck/> <fixedLength length="1" justify="left" padChar=" "/>
<fString dataName="custPersonalData.countryCode"/> <nullCheck/> <fixedLength length="2" justify="left" padChar="
"/>
<fString dataName="custPersonalData.groupMember"/> <nullCheck/> <fixedLength length="4" justify="left" padChar="
"/>
<fString dataName="custPersonalData.branchNumber"/> <nullCheck/> <fixedLength length="3" justify="left"/>
<fString dataName="custPersonalData.serialNumber"/> <nullCheck/> <fixedLength length="6" justify="left" padChar="
"/>
<fString dataName="custPersonalData.Classification"/> <nullCheck/> <fixedLength length="3" justify="left" padChar="
"/>
<fString dataName="custPersonalData.marketSector"/> <nullCheck/> <fixedLength length="5" justify="left" padChar="
"/>
<fString dataName="custPersonalData.Manager"/> <nullCheck/> <fixedLength length="50" justify="left" padChar=" "/>
<fString dataName="custPersonalData.lastName"/> <nullCheck/> <fixedLength length="35" justify="left" padChar=" "/>
<fString dataName="custPersonalData.firstName"/> <nullCheck/> <fixedLength length="35" justify="left" padChar=" "/>
Page 47
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
<fString dataName="custPersonalData.middleName"/> <nullCheck/> <fixedLength length="35" justify="left" padChar="
"/>
<fString dataName="custPersonalData.preferredName"/> <nullCheck/> <fixedLength length="35" justify="left"/>
<fString dataName="custPersonalData.Title"/> <nullCheck/> <fixedLength length="10" justify="left" padChar=" "/>
<fString dataName="custPersonalData.iDType"/> <nullCheck/> <fixedLength length="1" justify="left" padChar=" "/>
<fString dataName="custPersonalData.iDNumber"/> <nullCheck/> <fixedLength length="20" justify="left" padChar=" "/>
<fString dataName="custPersonalData.Nationality"/> <nullCheck/> <fixedLength length="2" justify="left" padChar=" "/>
<fString dataName="custPersonalData.countryOfResidence"/> <nullCheck/> <fixedLength length="2" justify="left"
padChar=" "/>
<fString dataName="custPersonalData.Sex"/> <nullCheck/> <fixedLength length="1" justify="left" padChar=" "/>
<fString dataName="custPersonalData.dateOfBirth" /> <nullCheck/> <fixedLength length="8" justify="left" padChar=" "/>
<fString dataName="custPersonalData.introduceToBank"/> <nullCheck/> <fixedLength length="3" justify="left"
padChar=" "/>
</record>
</fmtDef>
With the WSBCC V4, our development also make use of the Data Mapper
Format. It has two inner format elements to serve the purpose of copying the data
from one context to another context. For example, the simple account process will
copy the data from the process context into the operation context for host
communication. The formats used are different from those for MQ formats. In
MQ format, there is a fixed length constraint by the system (the communication
agreement between AS/400 and F/E), a fixedLength decorator is necessary for all
MQ formats. However, the delimiters are used in all the map formats since the
map formats are purely used by the F/E. Also, developers is encouraged to use a
more structured format in all formats as it is easy for maintenance.
Developer can convert the design document to the dsefmts.xml like this:
Page 48
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
<fmtDef id="maintainAddressInputSrcFmt">
<record>
<record dataName="custPersonalData">
<fString dataName="countryCode"/> <nullCheck/> <delim delimChar="~"/>
<fString dataName="groupMember"/> <nullCheck/> <delim delimChar="~"/>
<fString dataName="branchNumber"/> <nullCheck/> <delim delimChar="~"/>
<fString dataName="serialNumber"/> <nullCheck/> <delim delimChar="~"/>
</record>
<record dataName="custMaintainAddressData">
<fString dataName="addressId"/> <nullCheck/> <delim delimChar="~"/>
<fString dataName="addressCategory"/> <nullCheck/> <delim delimChar="~"/>
<fString dataName="custName"/> <nullCheck/> <delim delimChar="~"/>
<fString dataName="addressLine2"/> <nullCheck/> <delim delimChar="~"/>
<fString dataName="addressLine3"/> <nullCheck/> <delim delimChar="~"/>
<fString dataName="addressLine4"/> <nullCheck/> <delim delimChar="~"/>
<fString dataName="addressLine5"/> <nullCheck/> <delim delimChar="~"/>
<fString dataName="postalCode"/> <nullCheck/> <delim delimChar="~"/>
<fString dataName="homePhoneNumber"/> <nullCheck/> <delim delimChar="~"/>
<fString dataName="workPhoneNumber"/> <nullCheck/> <delim delimChar="~"/>
</record>
There are 2 methods that a developer needs to implement for the Format class:
1) String formatField(DataField aDataElement)2) DataField unformatField(String
aString, DataField aDataField)
The formatField() method takes a Data field and format the value of the data field
into a String. The unformatField() takes a String, put the correct values into the
data field specified and returns the data field.
The developer can also implement the “Object initialzeFrom(Tag aTag)” method
to capture values of special attributes for the particular format assigned in the
format definition.
To use the new format class in a format definition, follow these steps:
1. Add the definition of the opStep in dse.ini by putting a line like this in the
keyed collection “formats”:
Page 49
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
<field id="the name of the format to be used in dsefmts.xml " value="the Java class name of the format"/>
2. Use the format for the appropriate data field in the format definition in
dsefmts.xml. (See figure 2 and the associated sample format definition.)
Page 50
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
com.ibm.dse.base.Context.reset();
com.ibm.dse.base.Settings.reset("c:\\dse\\server\\dse.ini");
com.ibm.dse.base.Settings.initializeExternalizers
(com.ibm.dse.base.Settings.MEMORY );
By using the simple scrapbook, developers can easily to test and inspect the
created structure in the context, data, format and calculate the length of the
formats.
Page 51
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
This section provides the information of the way for the displaying of error
message and the mechanism supported in WSBCC V4.
Alternatives
The sample coding and steps involved are elaborated for reference:
Example below shows the coding involved in displaying the error message for
the Customer Number field on Customer Search Screen. The line in BOLD
indicates where and how to retrieve the error message for displaying.
<TD>
<INPUT size="2" type="text" id="acct1" name="custSearchRequestOpData.custAcctData.hubAcct"
maxlength="2" maxlength="2" value="<%=(String)sessCtx.getValueAt("countryCode")%>" minlength="2"
autoTab="Y" inMask="Alpha" outMask="Uppercase"
onfocus="textFocus(this,event);critType[0].checked=true" onblur="textBlur(this,event);"
onkeyup="textKeyUp(this,event)" onkeypress="return textKeyPress(this,event)">
<INPUT size="4" type="text" name="custSearchRequestOpData.custAcctData.hubAcct" maxlength="4"
value="<%=(String)sessCtx.getValueAt("groupMember")%>" minlength="4" autoTab="Y" inMask="Alpha"
outMask="Uppercase" onfocus="textFocus(this,event);critType[0].checked=true" onblur="textBlur(this,event)"
onkeyup="textKeyUp(this,event)" onkeypress="return textKeyPress(this,event)">
<INPUT size="3" type="text" name="custSearchRequestOpData.custAcctData.hubAcct" part="B"
maxlength="3" minlength="3" autoTab="Y" inMask="Numeric" padChar="0" padStyle="Before"
onfocus="textFocus(this,event);critType[0].checked=true" onblur="hAcctBlur(this,event)"
onkeyup="textKeyUp(this,event)" onkeypress="return textKeyPress(this,event)">
<INPUT size="6" type="text" name="custSearchRequestOpData.custAcctData.hubAcct" part="N"
maxlength="6" minlength="6" autoTab="Y" inMask="Numeric" padChar="0" padStyle="Before"
onfocus="textFocus(this,event);critType[0].checked=true" onblur="hAcctBlur(this,event)"
onkeyup="textKeyUp(this,event)" onkeypress="return textKeyPress(this,event)">
The sample screen below shows the error message displaying next to the data
field:
Page 52
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
The sample screen below shows the error message displaying on top of the page:
Page 53
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
Page 54
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
After the updateContext method is executed, the process context should contain
the update information. So, developers can check if all the information from the
HTTP request can be updated to the process context successfully.
13. Create Dummy MQ Message for Normal, Error and warning cases.
Before the real interface test with the host team, F/E developers can simulate the
uphost and dnhost messages to/from host. The generated dummy message is
useful to the F/E team as we can minimize the dependency on the host program.
Hence, F/E developers can proceed further for the next phase. Furthermore,
developers can simulate different scenarios of the process like Rejected by HOST,
EXCEPTION BY HOST, etc.
com.hsbc.cgd.crms.oper_svr.FormatHeaderServerOpStep
com.hsbc.cgd.crms.oper_svr.FormatDetailServerOpStep
com.hsbc.cgd.crms.oper_svr.ParseHeaderServerOpStep
com.hsbc.cgd.crms.oper_svr.ParseDetailServerOpStep
com.hsbc.cgd.crms.oper_svr.ParseRepeatItemServerOpStep
Page 55
Guidelines for
Browser Base Thin Client Development
on WSBCC Section 6
16. Operation Context to Process Context testing
It is similar to the Process Context to Operation Context testing, developers can
set the break point at the mapContents(context, context) method of the
com.ibm.dse.base.DataMapperFormat class.
These are the common classes usually needed to be extended to cater for
application needs. Some of these classes may have a method called
“initiliazeFromTag()”. This method is very important because this is where the
mapping of xml parameters to your class occurs. Make sure when extending the
classes that do have this method you look at the superclass implementation to see
if you may need to call the super() from you class.
Page 56
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
7. Testing/Debugging Stage
7.1 Testing
The Rational Team Test is the selected tool serving the testing purpose. The
details testing arrangement and procedure will be provided in the later stage.
Page 57
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
7.2 Debugging
This diagram shows in stages the actual classes that the server will run to execute
a process-operation. It is divided into 4 main parts.
o Stages 1and 8: Data Mapping.
o Stages 2-3: Formatting OpSteps.
o Stage 4: MQ Message OpStep.
o Stages 5-7:Parsing OpSteps
Below are these stages described in more detail to help developers decide where
to put breakpoints during debugging.
Page 58
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
Page 59
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
3. This line will populate the outputContext depending on the outputFormat and
contents. When inspecting this line, the return value is the keyedCollection of the
populated outputContext. This is a good point to check if all the necessary
information from the inputContext is transferred into the outputContext.
Page 60
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
After the operation context has been populated, the operation must then send a
request message to the host and then wait for the reply. The message that is sent
to the host is contructed by the formatting OpSteps:
com.hsbc.cgd.crms.oper_svr.FormatHeaderServerOpStep and
com.hsbc.cgd.crms.oper_svr.FormatDetailServerOpStep. The execute() methods
of these two classes are very similar. Below is the execute() for
FormatHeaderServerOpStep with some key pointers.
1
2
Page 61
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
2. This the MQ header format. If an error occurs here check to see if this format
exists in the DSEFMTS.XML; if it does exist, then check your operation
definition in DSEOPER.XML to verify that the format is declared within your
operation.
3. This line will convert the information of the context to a string and then save it
into the CRMSServer’s in buffer. If any errors occurs here make sure that all the
elements defined in the format can be accessed in the operation context.
Page 62
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
1. This line extracts the host message into a string. Developers may check the
hostReply to see if there are any errors.
1. key is the uphost message generated by the formatting OpSteps. All the pre-generated
downhost messages are kept in a hashtable, this line will retrieve the downhost message
specific to the uphost message. result should not be null, if it is, make sure the key
matches one of the pre-generated uphost message created by the Dummy utility.
Page 63
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
After the host message has been sent down. The myCRMSServerOp object will contain
the message as a string in it’s fieldOutBuffer. The message will contain a standard
header information, followed by a detailed section and then a repeating items section if
any. This message is parsed and then formatted into the operation’s context by the
parsing OpSteps. The parsing is done by the following classes:
com.hsbc.cgd.crms.oper_svr.ParseHeaderServerOpStep,
com.hsbc.cgd.crms.oper_svr.ParseDetailServerOpStep and
com.hsbc.cgd.crms.oper_svr.ParseRepeatItemServerOpStep. The execute() methods
of ParseHeaderServerOpStep and ParseDetailServerOpStep are very similar; however,
ParseRepeatItemServerOpStep is a bit different.
Page 64
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
1. One common error can occur in this line. Make sure the format defined in
DSEFMTS.XML corresponds to what the server sends down. The endIndex is the length
of the the message the server sends down, it should match the length of the format.
2. This line is common to all the parsing OpSteps. Developers can instpect this line to see
what data in formatted into the context and too see if any exceptions are thrown.
Page 65
1
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
7.3 General Debugging Methods
When a function does not behave as expected, the developer needs to find out why it fails
before he can fix it. This section will first present the facilities that a developer can use
for error or bug diagnosis, then several kinds of common errors will be discussed.
Error Diagnosis
The following facilities can be used to find out why the system fails:
1. Trace
2. Standard output (console)
3. Break points (in IBM VisualAge for Java)
4. Exception tracking (in IBM VisualAge for Java)
Trace
In the dse.ini file, the developer can configure WSBCC to trace the activities of the
system to a file and/or to display. In the <kColl id="traces"> section, turn on the trace by
setting the fields “traceToDisplay” or “traceToFile” to “yes”. During run time, a trace
window will appear on the server machine showing the traces if “traceToDisplay” is set
to “yes”.
If
“traceToFile” is set to “yes”, a file with the file name and path specified in the
“traceFileName” field will be created, logging all the traces. Many other features of the
trace facility in WSBCC can be configured. Please refer to the WSBCC documentation.
By convention, the WSBCC Java classes use this trace facility whenever an exception is
caught. The trace can also be used in other classes of the application where the developer
finds appropriate. Here is a sample usage of the trace facility in a Java class.
Page 66
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
try{
…….
…….
}catch (com.ibm.dse.base.types.DSETypeException te) {
if (Trace.doTrace(Constants.COMPID, Trace.Low, Trace.Error))
Trace.trace(Constants.COMPID, Trace.Low, Trace.Error, Settings.getTID(), "Error when
clearing typed context: " + te.getMessage());
}
The “if” clause helps to filter out the trace when the trace level setting in the trace
configuration does not require tracing a certain level of errors, and certain type of events
(“Low” and “Error” in this case). The “Trace.trace()” method use the trace facility to
track down the information about the event.
If the Java classes call the Trace facility properly at appropriate places, the trace file or
the trace display can provide very useful information about where the program fails. The
developer should read it carefully when debugging the program. However, there may be
too much to read in a trace file and most of them does not provide important information.
In this case the developer may want to set the trace level lower (trace less) or change the
kinds of event the trace is keeping track of in order to obtain a more readable record of
events.
Standard Output
Some information in the application may use the standard output to provide debugging
information. This is especially true for system initialization. The developer may choose
not to use the trace facility to log system initialization information because it is very
likely that this piece of log should be always available despite the settings of trace. To
insert a line in the standard output, put in the following line in the Java class that requires
logging:
System.out.println(“your String”);
The standard output is presented in the console when the application is running under
“IBM WebSphere Test Environment” in IBM VisualAge for Java.
Page 67
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
When the application is running in IBM WebSphere Application Server, the standard
output appears in the form of a text file called “default_server_stdout.log” in the “/log”
sub-directory under the directory where WebSphere Application Server is installed.
Break Points
Setting break points in Java classes in IBM VisualAge for Java is another way to
diagnose the problem encountered. The developer can set the break points in his/her
program and find out how it is executed. Please see IBM VisualAge for Java
documentation for details about how to use break points and the debugger.
If WSBCC source code is available, the following methods are good candidates for break
points when debugging is needed:
Page 68
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
DSEHtmlProcessor: changeState(String newStateName, boolean activate, TransitionDescriptor
transition)
This method is a good place to start debugging automaton related errors. It shows the
process when one state changes to another. By stepping into other methods called, the
developer can identify which step fails.
DSEHtmlProcessor: updateContext(Context aContext)
When a form is submitted from an HTML page, the fields of the form will be used to
update the context of the operation or processor specified in the form. If the update is not
successful, break points can be put in the above method so that the developer can find out
which data element fails during the update.
DataMapperFormat:mapContent(Context inputContext, Context outputContext)
This method is called whenever data needs to be mapped between processor context,
operation context, sub-processor context, action context, and/or transition context. When
the developer sees the Exception thrown in the trace window or trace file indicating that
the system cannot map data between certain contexts, setting a break point in this method
helps to determine exactly where the problem is.
Exception Tracking
The debugger in IBM VisualAge for Jave has a feature to track the lines where certain
types of exception is thrown. If the developer has tried many other ways and still does not
have any clue why the system throws a certain exception causing the error, he can track
the particular type of exception using the debugger.
Page 69
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
When the program runs into a line where the specified exception is to be thrown, the
debugger will break like how it works with the break points. The developer can look the
flow of executions (i.e. which method calls which) and finds out how the system comes
to this line.
Page 70
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
However, please be reminded that the debugger will probably break at many places that
are not related to the problem, because WSBCC sometimes uses the exception handling
mechanism in Java to execute some rather normal program flows. Please see the
documentation about the debugger in IBM VisualAge for Java for details about tracking
exceptions in the debugger. Important exceptions include:
DSEObjectNotFoundException
DSEInvalidArgumentException
DSETypeException
IndexOutOfBoundsException
StringIndexOutOfBoundsException
Common Problems:
Besides errors and exceptions that occur in the Java classes, problems may also be found
in the XML files and the JSP files. The following section explains some common
problems encountered in the development of the XML files and the JSP files.
XML problems
Page 71
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
In some cases, the reply page only informs the developer that a certain typed data element
cannot be initialized, without providing the exact line where initialization fails. A very
common reason for this error is that a certain type is referenced before it is declared in
dsetype.xml. Although the order of declaration of elements does not matter in most “dse”
files, it does matter in dsetype.xml. The declaration of a type has to be put ahead of types
that reference it physically in the file. For example,
<?xml version="1.0"?>
<dsetype.xml>
</destype.xml>
is incorrect because when “myType” tries to reference the type “String”, “String” is not
declared yet. The developer has to resolve the dependencies of the types and order them
accordingly to avoid such problems.
Formatting
During formatting and unformatting of data, WSBCC may throw exceptions indicating
that it cannot find the data element specified in the dsefmts.xml
(DSEObjectNotFoundException). In this case, check the dsetype.xml and dsedata.xml
files to see if the data names declared agree with the format definition. Also, sometimes
the format may include the data name of the KeyedCollection of the processor or
operation context, which is not necessary and leads to failure in formatting/unformatting.
For example, a process, processA, has a context called processACtx. The
KeyedCollection of processACtx is called processAKColl, and it is defined as the
following:
<KColl id= “processAKColl”>
<KColl id= “2ndLevelKCollA”>
<field id= “myField1”/>
<field id= “myField2”/>
</KColl>
<KColl id= “2ndLevelKCollB”>
Page 72
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
</KColl>
</KColl>
JSP problems
Cannot Compile
When the system replies with messages indicating that the JSP cannot be compiled, it is
very likely that there are some basic syntax problems with the JSP file. If there is a
mismatch of brackets ( (, ), {, }, <%, and %>), or quotes (“,”, ‘,’), or missing “;”, the
JSP file will not be compiled and the error message will not be very informative. In other
cases where compilation is not successful, the error messages are more informative.
Examples are wrong method calls and wrong use of reserved words.
Cache Files
Sometimes the developer may find that the changes he made are not reflected in the
system. One reason is that the browser is using a cached HTML file stored in the client
machine without making a request to the server. This can cause other problems when the
cached file has an expired session ID that the server no longer recognizes. The developer
should configure the browser such that it does not use cached HTML files.
Another scenario where the changes in the JSP is not reflected in the system is that the
system has not re-compiled the JSP into the servlet that generates the HTML code. In this
case, the developer needs to delete the respective servlet class in the “JSP Page Compile
Generated Code” project in VisualAge for Java if he is running the test in IBM
WebSphere Test Environment. If the system is running on the WebSphere Application
Server, the developer needs to delete the respective classes in the
“/temp/default_host/default_app” sub-directory.
Page 73
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 7
Page 74
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 8
Common beans are common components that can be shared by all applications.
They are classified as GUI beans and Desktop beans.
GUI beans are common components that can be reused in any applications.
Common beans that belong to this category are: Text Field, Amount, Combo Box,
Double Combo Box and Date Picker.
HTML Text Field bean is a regular HTML text field that also has some additional
self-defined intelligent behaviour. It can be included in a JSP page by including
this line in a JSP header:
To define a specific behaviour for that field, type in the corresponding attribute
with value. Then define the JS Handler method name for the JS Event as specified
in the table. Also if there are related attributes to be defined for this behaviour to
work, they are listed in the Related Attributes column. If for a particular JS event
additional behaviour is required and the default JS handler cannot provide that,
additional self-defined function is required and that handler needs to include a call
for that. For detailed description of the text field functions please refer to spec.
Page 75
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 8
"Uppercase" : conver to onBlur textBlur()
upper case
outMask "Lowercase" : convert to
lower case
"None" : no convertion
The character used to fill
the field with the onBlur textBlur() Minlength,
padChar patch()
minimum character if the padStyle
padStyle is not "None"
"Before" : Fill the text
with leading padChar(s). onBlur textBlur() Minlength, padChar
"After" : Fill the text with
padStyle patch()
trailing padChar(s).
"None" : no padding will
perform
Also for a field to restored typed (as opposed to formatted) field content,
onTextFocus needs to be handled.
HTML Text Field includes a Javascript validation on input mask. The InMask
attribute accepts either “Numeric”, “Alpha”, or “AlphaNumeric”. If the input
type does not match with the specified attribute value, the HTML Text Field
would not allow any of the input display on the screen.
For example, the following defines a field with padding of 0’s in front and
autotab. The field only accepts numerical value. Note that when the handlers are
called this object and the event are passed along. If you define your own methods
make sure they are part of the parameters list.
HTML Account bean is another HTML Text Field type that has account number
or customer number input capability. A account number has five input fields
while a customer number has four input fields. To use this bean in a JSP, the JSP
header has to include the following lines:
Page 76
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 8
At the place where you want to put an account number, create 5 input fields ( 4
for customer). Note the attributes to be defined for each visible fields: size,
maxlength, minlength, autoTab, inMask, outMask. The event handler attributes
needed are: onfocus, onblur, onkeyup and onkeypress.
<TD class="sLgt">
</TD>
Note that all five fields have the same field name.
Page 77
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 8
The part attributes (in bold) are used to identify whether the field is the branch (B)
or serial (N). The utb function call at the end is for displaying any type validation
error.
There is also Javascript validation in place for HTML account. The Account.js
includes a checksum logic for validating the customer number. The logic involves
manipulating each digit of the customer number. Odd position digit (except the
ninth digit) multiplies itself by one while even position digit multiplies itself by
two. If the result value is over ten, the value of the two digits needs to be added
together. The final checksum value is calculated by adding all these result values
and the value of the ninth digit together. The customer number is valid only if the
final checksum value is a multiple of ten. If the customer number does not meet
this requirement, the customer number text field is then filled with yellow.
For example, customer numbers such as 001000009 and 020000048 are valid,
while 001000008 and 020000047 are invalid.
Page 78
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 8
HTML Amount bean displays amount with currency. The currency is displayed in
a HTML Combo Box while the corresponding amount is displayed in a input text
field.
To include this bean in a JSP, create a currency combo box (SELECT element of
name, initialValueAmount in this example) with a combo box model
(InitialValueModel in this example). Note that the model properties be similar to
the following:
Notice that the currency field and the amount field have to be the same name
(initialValueAmount in this example). In dsetype.xml, the HAmount typed
element should have been defined as follows:
Page 79
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 8
Note that the currency and the amount need to be defined separately although they
are using the same name.
HTML Combo Box bean is a single drop down list. Items in the drop down list
usually are coming from the local server’s database.
Page 80
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 8
<% IdTypeModel.setUseFieldValue(false); %>
</jsp:useBean>
After that, create an instance of the HTMLComboBox Model bean and set
properties, as follows:
After all the properties are set, the combo box can be declared by using the
SELECT tag to get the HTML property as follows:
HTML Double Combo Box bean is similar to the HTML Combo Box bean above.
The difference is that the Double Combo Box bean has a parent and child drop
down list. The child drop down list items depends on which item has been
selected for the parent drop down box.
The usage of the Double Combo Box bean is similar to the Single Combo Box
bean. Each of the combo box uses the RefDataModel. The selected value of the
first one is to be stored in the context.
For the second combo box model, set the where clause to “parent_id = “ +
context.getValueAt(“productClassCode”)
Where productClassCode in this case is the selected value of the first combo box
in the context.
Date Picker bean is a GUI calendar that user to select and set the date. To include
the Date Picker in the page, place the following code in the place where you want
take a date:
Page 81
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 8
<INPUT class="inp" id="date_from" size="10" type="text"
name="leadsRequestProcData.dateFrom" maxlength="9" minlength="0" autoTab="Y"
onBlur="textBlur(this, event)" onkeyup="textKeyUp(this, event)"
onfocus="textFocus(this,event)"
value='<%=utb.getStringValue("leadsRequestProcData.dateFrom")%>'>
</TD>
Note that the id and name has to be unique throughout that JSP. When the user
clicks on the calendar image, a new window is opened with a calendar, showing
the current date. When the user selects a date, the window is closed and the date
selected is shown in the field referenced by “window.dateField”.
The Customer Status Bar bean is responsible for generating HTML elements
(text, image and link) that constitutes the customer bar. The customer bar displays
information such as the customer status, customer name and customer number.
The customer status is represented by an image to indicate that the customer is
either suspect or blacklist. The customer status is considered as normal if there is
no image.
In the HEAD of the JSP page, use JSPBean tags to create an instance of the bean
and set properties, as follows:
Page 82
Guidelines for
Server Side Java Thin Client Development
on WSBCC Section 8
Inside the body, place the “<jsp:getProperty …>” where the Customer Status Bar
is going to be placed, as follows:
The name in this tag is the same as the id in the jsp:useBean tag.
Page 83
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix A
Style Guidelines
The following is a list of assumptions regarding font, type size, and language usage.
• Use the “Use-Case Template” document – it is pre-configured for the correct styles and structure.
• Describe requirements as generically as possible.
• Do not indicate design information, indicate functional/behavioral requirements.
• Use domain terminology and spelling as the use cases are to be written from/for the customer/user
perspective/comprehension.
• Where applicable, use the terms from the tables below when describing use-case flows.
• Use active voice. The actor and the system perform actions.
• Use present tense. “The actor selects…”
• Use definitive and precise language when stating an action within a use case. In particular, don’t use “should”,
“may”, etc. If something is truly optional, use “The … optionally …”.
• To qualify the plain-language and ambiguous use of “or”, either use “either … or …” to indicate “exclusive or”
or use “and/or” to indicate “inclusive or”.
• Don’t express opinions or conjectures; be factual and accurate.
• Within the use-case flows, rely upon explanations to communicate concepts, instead of using examples.
• Where possible, write an action from the point of view of the actor, not from the point of view of the system –
e.g., The Banker selects the Mumble from the collection of Mumble Foos presented by the system.
• If the actor represents a single role, name the actor (e.g., Teller). If the actor represents multiple roles which do
not have a specific domain-related name, use the generic a term (e.g., “Banker”) to name the actor.
• Express information/data-oriented concepts at the highest level of abstraction that applies to the specific detail
for a given use-case flow. Where more detail is available – either in the form of additional (data) structure or
additional (data) attributes – use the data dictionary to capture the detail as it relates to the higher-level, use-case
concept. Be sure to stick to information that is clearly indicated by the use case. Do not engage in a priori data-
modeling attempts.
• Enumerated values for applicable information/data elements are not identified in the use case, unless you need
to refer to them directly; e.g., in an alternative condition. However, enumeration values are detailed in the data
dictionary as they are discovered during analysis.
• Each use-case concept that is not a term that would be understood in everyday discussions must have a
corresponding Glossary entry.
• All acronyms and abbreviations must have a corresponding Glossary entry.
• Data dictionaries are to be developed for “Maintain” use cases only – i.e., use cases that describe the
requirements for the maintenance of fundamental informational classes (i.e., classes of stereotype “entity”).
Each data element referred to in a use case, regardless of the level of abstraction (field, row, class, category),
must have a corresponding Data Dictionary entry. The Data Dictionary will often include many other entries
that are not directly referred to in the “Maintain” use case.
• Inter-field/information dependencies are to be included within the flow of the use case. Many other aspects –
such as size/length/type requirements, validation requirements, and default-value requirements – will not be
described in the use case because they are contained in the Data Dictionary.
• If the “Detailed Flow” section contains complicated inter-dependencies, a table can be used to clearly describe
the detail.
Page 1
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix A
• The default (data entry) ordering of the fields - as presented and selected by the system and the user - are
stipulated by the order of the entries in the Data Dictionary. Use-case flows should mirror the Data Dictionary
field ordering.
• Algorithms, formulas, and/or other specific/detailed design constraints can be defined as glossary items then
“referred to” in the use case, or the details of the algorithm can be specified in the “Design Comments” section
of the use case.
• The activity of a human Actor selecting and the System indicating that selection normally will simply be
described as the human Actor performing the selection – i.e., by default, it is implied that a selection activity is
immediately followed by an indication activity to present the selection to the human Actor
• Similarly, the activity of updating application content information assumes that the System updates any and all
“live” views/presentations of that information once the change has been completed (or during the change
process) and, as such, the activity of the System updating the views/presentations will not normally be explicitly
described in the Use Case
• Nearly all Use Cases are described assuming that the application has been started and that an “application
desktop is present”
Page 2
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix A
- e.g., Generate a GL Report. Note that report is not used as a verb when writing use
cases. (See also, Summary)
Summary An noun used when naming a use case wherein the primary requirements are to
gather, select, sort, summarize, and present information in a summary, read-only, and
often hard-copy, form – e.g., Process a GL Summary. (A Summary is a specific form
of a Report)
View The verb used when naming a use case wherein the primary requirements are to
gather, select, sort, and present information in a read-only form via an interactive
mechanism (such as a monitor). (A Summary is a specific form of a Report)
Page 3
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix A
Terms Used in the Data Dictionary
Word Usage description
Mandatory A “yes” value indicates a data item that cannot be null (i.e., where a non-null value is
required). A “no” value indicates a data item that can null. This restriction applies
whether the data item is acquired interactively or computed by the system.
Is A Requirement A “yes” value indicates that the data item exists due to a specific requirement and
cannot be changed during the design process without agreement from the analysts
(e.g., it may be necessary to pass audits required by regulatory agencies). A “no”
value indicates that the data item does not exist due to a “hard” requirement and thus
indicates that it can be modified/transformed during the design process. Such
modification requires that other information be kept in sync with the changes (e.g.,
the use case).
Data Dictionary
The data dictionary is used to define stored (persistent) data elements referred to in a use case. Often these data
elements will ultimately be mapped to the actual database table and field names (where they may differ).
Page 4
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix B
Use Case
<Use Case Name>
Amendment Record
Page 1
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix B
Name: enter the use-case Name here (in “Title style” style)
State the name of the use case; be sure to adhere to the “Terms Used for Use-Case
Naming” in the “Use-Case Style Guide”. Use “Heading 1” style for the Name and other
titles.
Business Context:
Optionally, describe the business context here (in “Body Text” style).
The business context indicates the business processes for which automated support is
desired and for which this use case specifies the required functionality to complete that
automated support. The business context should not be required to understand the
behavior expressed in the use-case flow, but may be useful to understand where the use
case fits into the larger, business-operation picture.
Pre-Conditions:
• List any pre-conditions here (in “bullet text” style).
A pre-condition is a constraint that must be true before this use case can operate. Often
other use cases are stated as pre-conditions.
Overview:
Supply a general description of use-case (i.e., the functional requirements) here (in “Body
Text” style).
The overview should capture the essence of the use case’s functionality for the
predominant flow(s). It should begin with “The use case starts when <the actor> <does
something> …” and usually consists of from three to five concise sentences. The ending
should be also be explicitly stated as “The use case ends when …” or “… <something
happens> and the use case ends”. A document containing only the use-case names and
the corresponding overview statements should provide a good overview of the overall
system’s behavior.
Detailed Flows:
Supply the detailed flow descriptions here (in “numbered text” style).
Detailed flows consist of the primary flow or the primary alternative flows, other
alternative flows, and exception and /or warning flows. Alternative flows are generally
considered to be choices that are intentionally made by the actor. In contrast, warning
flows are generally considered to be choices that are not intentionally made by the actor
and normally result from non-fatal or non-controlling, erroneous conditions. Exception
flows are generally considered to be choices that are not intentionally made by the actor
and normally result from significant error conditions.
Alternative flows must be clearly delineated by the alternative label and a descriptive
phrase – for example:
[A1] Phrase describing condition that got us here:
Page 2
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix B
The behavior goes here…
It is often the case that multiple erroneous situations require the same behavior. A
common requirement for error-handling can be stated as vaiants of “The <actor> is
informed of the error and provided the opportunity to correct the situation or cancel the
activity. If the <actor> corrects the error, the use case continues as though this flow had
not been encountered. If the <actor> indicates that the operation is to be cancelled, the
use case ends.”
Post-Conditions:
• List any post-conditions here (in “bullet text” style).
A post-condition is a constraint that must be true after this use case operates.
Non-Functional Requirements: (use “Body Text” style and “bullet text” style, as
appropriate)
Identify any requirements that are related to this use case but not part of the actual flow. For
example, if the use case described an output, and if the customer required the implementation
for the output to use a Word template, then the details of these requirements should be
explained here. This section identifies both pre-stated design constraints and suggestions that
might be captured during analysis. Each entry needs to be identified as either an actual
customer-required, non-functional requirement, or as merely a suggestion.
Glossary
This section describes some of the terms used in this use case document.
Data Dictionary
Page 3
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix B
Page 4
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix C
Page 1
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix C
initialValueAmount Initial Value Amount A 24
initialValueCurrency Initial Value Currency A 3
isCorrection Is Correction A 1
isLead Is Lead A 1
jointDate Customer Joint Date N 8 yyyymmdd
lastName Customer Last Name A 45
logonDate Logon Date: Obtain from N 8 yyyymmdd
host at signon
logonTime LogonTime: Obtain from N 6 hhmmss
host at signon
managerCode Manager Code A 3
mediaId Media Id (4A: TCID, A 10
6A:blank – future use)
msgIdentifier Message Type(2A:System A 10
code, 3A: Deal code, 5A:
blank-future use)
msgVersion Message Version A 10
Id(2A:Core Msg Ver;
2A:Local Msg Ver,
6A:blank-future use) first
core version:’0100 ‘
Nationality Nationality A 25
nationalityCode Nationality Code A 2
newAcctNumber New Account Number A 20
newActionDate Next Action Date N 8 yyyymmdd
newCustFlag New Customer Flag A 1
noteLine1 Notes Line 1 A 60
noteLine2 Notes Line 2 A 60
noteLine3 Notes Line 3 A 60
noteLine4 Notes Line 4 A 60
Package Package A 25
packageCode Package Code A 5
productClass Product Class A 25
productClassCode Product Class Code A 3
Product Product Description A 25
productCode Product Code A 3
prospectNumber Prospect Number A 9
referToId Refer To User Id A 4
Result Result A 48
resultCode Result Code A 3
sentById Sent By User Id A 4
statusIndicator Status A 1
Indicator(‘N’-Normal’,
‘R’- Reject with Error
Message, ‘X’ – with
Page 2
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix C
Exception Message)
Source Source A 50
sourceCode Source Code A 3
Title Title A 3 e.g. MR
updateDate Update Date Z 8 yyyymmdd
updateTime Update Time Z 6 hhmmss
userid Logon User Id A 4
workPhoneAreaCode Work Phone Area Code A 10
workPhoneNumber Work Phone Number A 32
workstationId Logon workstation Id A 4
writtenLanguage Preferred Written A 15
Language
writtenLanguageCode Preferred Written A 2
Language Code
Page 3
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix D
Revision History
Page 1
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix D
cust.serial Domestic Customer Serial 6 N
prospectSerial Potential Customer Serial 6 N
Classification GHO classification 3 A
marketSector Market Sector 5 N
Manager Relationship Manager Code 3 A
languageCode Language Code 1 A
reason How introduced to Bank 3 A
<constant> Blank Filler (for sole customer info) 247 A
<constant> Joint Information 1 A ‘J’
lastName Joint Name 70 A
corrName Correspondence Name 35 A
shortName Short Name 28 A
jointName2nd Joint Name – 2nd Language 70 A
corrName2nd Correspondence Name – 2nd Language 35 A
shortName2nd Short Name – 2nd Language 28 A
basicDD DD Account Indicator 1 A
groupMember Group Member 4 A
acct.prefix Account Branch 3 N
acct.serial Account Serial 6 N BLANK
acct.suffix Account Suffix 3 N BLANK
instantATM Instant ATM Card Indicator 1 A
productCode Product Type Code 3 A
Currency Currency code 3 A
Repeati
ng Section
groupId Group ID 10 A IndCustNos
Number Of Number Of Items 5 N automatic
Items
Item Length Item length 5 N 0015
jointCustList.*. Individual customer’s full customer number 15 A
cust (CCGGGGBBBNNNNNN)
Page 2
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix D
d
logonTime Logon Time: Obtain from host at sign on 6 Z hhmmss
msgIdentifier Message Type(2A:System Code, 3A:Deal 10 A “SSCAC
code, 5A: blank-future use) MNT’’
msgVersion Message Version Id (2A:Core Msg Ver, 10 A First core
2A:Local Msg Ver, 6A:blank-future use) version:
first core version:’0100 ‘ ’0100
‘
statusIndicator Status Indicator(‘N’-Normal, ‘R’-Reject 1 A
with Error Message, ‘X’- Warning with
Exception Message)
workstationId Logon Workstation Id 4 A
Detail Section:
groupId Group ID 10 A ‘DetailS’
dtlLen Length of detail session 5 Z 31
cust Customer Number 15 A
(CCGGGGBBBNNNNNN)
acct Account Number 16 A
(GGGGBBBNNNNNNSSS)
Message
Section:
groupId Group Id 10 A ‘ErrMsgR
’
no. of Items Number of items 5 Z
no. of chars/line Number of chars per line 5 Z
msgId Message Id 10 Z
msgLine Detail Message 80 A
Page 3
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix D
Page 4
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix D
Page 5
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix D
Repeati
ng Section
groupId Group ID 10 A IndCust
Nos
Number Of Number Of Items 5 N automat
Items ic
Item Length Item length 5 N 0015
jointCustList.*. Individual customer’s full customer number 15 A
cust (CCGGGGBBBNNNNNN)
Page 6
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix D
Message
Section:
groupId Group Id 10 A ‘ErrMsgR
’
no. of Items Number of items 5 Z
no. of chars/line Number of chars per line 5 Z
msgId Message Id 10 Z
msgLine Detail Message 80 A
Page 7
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix E
Data/Type Diagram
- Data Collection (KColl or IColl) – Represented by
a class.
- Simple field – Represented as an attribute within
the enclosing collection.
- Fields without type specified assumed to be String
(using default String Descriptor ).
- Typed fields have their types (e.g. HCustomer,
HDate etc) specified in the Type column in the
model.
- Any descriptor/converter/validator/initial values
other than the default one can be specified in the
initial value column.
- Indexed collection size is indicated by the
multiplicity of the association.
- A KColl containing another KColl or IColl is represented by
an aggregation relationship.
<<dsefmts>>
custSearchToCreateJointOutFmt
: <record>
Format Diagram jointAcctCustList : iColl = times=1 append=true
- Formats are represented by class. custRecord : <record>
lastName : fString = ~
- Format tags are specified as types of the attributes, e.g. firstName : fString = ~
<record>, <fString> etc. middleName : fString = ~
partialAddress : fString = ~
- decorators (e.g. nullCheck or delim) are specified in the countryCode : fSring = ~
initial values. groupMember : fString = ~
- repeating times and append mode of IColl formats can be custNumber : fString = ~
Classification : fString = ~
specified in the initial value column as well. custStatus : fString = ~
Index : fString = ~
soleJointIndicator : fString = ~
newCustFlag : fString = ~
Context Diagram Title : fString = ~
- Context is represented as a class. preferredName : fString = ~
Gender : fString = ~
- Context HAS a data collection (class). dateOfBirth : fString = ~
- static context chaining as represented by uni-directional idType : fString = ~
navigable association. nationalityCode : fString = ~
countryOfResidenceCode : fString = ~
: </record>
: </iColl>
Page 1 : </record>
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix E
Operation Diagram
- event from final states are represented by send event entry action in the final state.
Transition spec
Page 2
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix F
The WSBCC version 4.0.3 self defined processor is not as developer friendly as expected – the
developer needs to re-start the application server (ie. SERunner) when there is any change on the
WSBCC server self defined XML files, and the “dataMapper” fails to recognize self define files .
Therefore, the self defined processor is recommended to be used only when the development of
the sub system to be self defined is stabilized, that is minimum change to the self defined XML
files.
When a sub system is ready to be self defined, a developer can create a server xml for the sub
system, which includes processor, data, type, format, operation, context definitions for the sub
system, and enclosed them within the “<[ProcName].XML>…</<[ProcName].XML>” tags.
Then save the xml file with the name of “[ProcName].XML”.
The “modularity field for the settings” on the dse.ini required to be set as value “mixed” in order
to use both sets of non self defined and self defined XML files. The file name
“[ProcName].XML” of the self defined processor for the sub system is also defined in the dse.ini
file.
<kColl id="settings">
<! Define SGML modularity function mode: grouped, splitted or mixed>
<! Default is: grouped>
<field id="modularity" value="mixed"/>
:
<! Name of the definitions files>
<! Self defined operations definitions files>
<kColl id="files">
:
<kColl id="processors">
:
<procDef id="addressProc" value="customerInfoAddressProc.XML" path="c:\dse\server"/>
:
</kColl>
</kColl>
:
Page 1
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix G
This utility contains two macros. The first macro is “genFieldName” which is used to convert
the data name from Host data definition to the name that is used in XML. The second macro is
“scanTable” which is used to generate the data definition for “dsetype.xml” and the MQ format
with the map format for “dsefmts.xml”.
The “scanTable” basically runs through the first table by row, and the result data field name will
be produced in the second column of the table.
Instruction: Copy the data name from Host data definition and paste it in the first column. From
the “Tools” menu, select “Macro” then “Macros”. A screen that displays all the available
macros will pop up. Select the “genFieldName” and press “Run”. When the macro is being run,
it will exclude all the “(“ and “)” in the first column and convert them into XML data name
format in the second column.
Note: The current implementation of “genFieldName” will always go through the first table that
is specified inside the “dsexml1.doc”.
The “scanTable” runs through the second and third tables specified in “dsexml1.doc” and
generate the XML code as specified in the table. In the table, type in “Separator” to specifies that
the second cell of the current row will be used as a separator for the entire table. This means that
the user can type in the prefix, body, or suffix after the “Separator” cell. The current
implementation of “scanTable” can handle up to 100 separators. After the separators, the
“scanTable” will go through the remaining table by row. The first column string will be inserted
between the first and second separators; the second column string will be inserted between the
second and third separators; this process will continue up to the 99th column as long as user has
provided enough separators.
Page 1
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix G
screen that displays all the available macros will pop up. Select the “scanTable” and press “Run”.
The resulting list is as shown below.
Generated List
--------------
<StringDescriptor id="custNumber" refType="String"/>
<StringDescriptor id="atmCardNumber" refType="String"/>
Generated List
--------------
<fString dataName="custNumber"/> <nullCheck/> <fixedLength length="12" justify="left"
padChar=" "/>
<fString dataName="atmCardNumber"/> <nullCheck/> <fixedLength length="12" justify="left"
padChar=" "/>
Generated List
--------------
<fString dataName=" custNumber "/> <nullCheck/> <delim delimChar="~"/>
<fString dataName="atmCardNumber "/> <nullCheck/> <delim delimChar="~"/>
Page 2
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix G
Note: The current implementation of “genFieldName” will always go through the second and
third tables that are specified inside the “dsexml1.doc”.
Page 3
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix H
Before the real interface test with host, the uphost and downhost messages to/from host can be
simulated by the creation of a dummy message and the use of a dummy host. This allows the
developers to minimize the dependency on the host program and to test different scenarios of the
process like Normal, Rejected or Warning status.
To generate dummy messages you can use the GeneralEnqDummyMessage.xls file. This file
can be found in Team Assist.
Page 1
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix H
To generate the dummy message, just input the name, the length, the type and the value for each
one of the fields that compose each section. Do not input anything in the blue zone.
The last column shows the dummy message generated after input the information for each field.
At the end of the spreadsheet, the whole message generated is under Complete Message.
The next step is to concatenate uphost and downhost messages, using =, and to copy the message
into the D:\IBMVJava\IDE\ project_resources\IBM WebSphere Test
Environment\MQMessage.txt file.
- Run the application in the same way, as you would do it for a real host
Page 2
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix I
Generic message is a common message used for some enquiry and maintenance
functions. The first level of the generic message is ‘customerInfoData’, which includes all of the
group indicators and groups. All of the group indicators are defined in
‘customerInfoSectionData’, which is renamed as ‘section’ in ‘customerInfoData’. Besides, each
group has its own definition under its groupID like ‘KeyJoint’ or ‘Overview’.
In the enquiry generic uphost message, the first part - ‘DetailS’ includes indicators for
each group. The default value for each indicator is ‘N’. However, programmers can turn on the
group indicators in order to let host know which groups of data host should send to front-end.
Similarly, programmers should turn off the group indicators that are no more needed from host.
For example, in Customer Overview, programmers can turn on the ProdDtlR group indicator by
using the method – ‘com.hsbc.cgd.wsbcc.actions.SetFieldStringValue’ to set the value in the
processor context and send the enquiry generic message to host. In desproc.xml, set as follow:
Then, when the programmers send the maintenance generic message to host, the group ProdDtlR
is no more needed. Therefore, the programmers have to turn off this group indicator before the
message is sent.
Besides, programmers should aware that if they turn on a group indicator but has no data
returned from host, problem may appear when they map data between contexts. In order to
prevent this, programmers can fill in blank data into the group and set the group size to 1 by
using the method - ‘com.hsbc.cgd.wsbcc.actions.SetICollSize’. In dseproc.xml, set as follow:
In the maintenance generic uphost message, programmers have to pack the groups of data
and send them to host. Therefore, in the dseoper.xml, programmers have to provide the formats
for packing the group data. Also, an additional step - ‘FormatSectionItemOpStep’ is used for
packing up the group data. In dseoper.xml, set as follow:
Note: Section name have to be defined in the additional opStep in order to make it work.
Page 1
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix I
Furthermore, some of the formats for generic message are well written. Programmers can
reuse these formats instead of writing their own ones.
Note: Since some formats are different for request and reply, some format name may
have only ‘RequestFmt’ or ‘ReplyFmt’.
Page 2
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix J
Background
JetForm Central is a server-based forms application that enables you to manage and
administer your electronic forms in a networked environment. JetForm Central runs on a
machine on a local area network(LAN), with access to two directories, a control directory and a
collector direcotry. The control directory is intended primarily for messages that direct the
operation of JetForm Central. The collector directory contains the business transactions that
JetForm Central processes. Business transactions include print tasks. The business transactions
that Jetform Central processes are referred to as transaction files. The Print Agent is the output
module of JetForm Central. The Print Agent enables applications to output data merged with
electronic forms designed in JetForm Design. Output can be in print format, fax format or PDF
format. JetForm Central initiates the Print Agent when a transaction file with an output task
appears in the JetForm Central collector directory.
JetForm central is used as print server application in HFE. WSBCC will generate a data file (or
transaction file) with .dat extension. The dat file name is usually a 6 digit random number as the
file name such as 138479.dat. Then, the generated transaction files are sent to c:\jfsrvr of the
print server. Please note that the print server is not necessary to be the same server as the HFE
server. Following that, the print agent merges the data file and compiled form file with .mdf
extension and the output are sent to printer.
Page 1
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix J
After JetForm central is installed, you can configure the followings for HFE. For the details of
JetForm Central installation procedure, please refer to “Central” documentation from Vendor.
1. After JetForm central is installed, you can start the JetForm Central from task bar
Page 2
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix J
3. Configure jobs by clicking File->Job Management Database->Jobs from menu and make
sure HFEPRINT is defined.
3.1 If HFEPRINT is not defined, click New Job and input the following parameter for
configuration.
Page 3
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix J
4. Make sure the logon ID has the authority to start JetForm service in NT
Page 4
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix J
5.2 Highlight the “JetForm Central service” and click start (if the service is not started yet)
Debugging Hint
1. Nothing to print
1. Make sure the JetForm Central can start successfully.
2. Make sure if the .dat file is generated successfully in c:\jfsrvr directory.
Example: the data file name can be 133256.dat
3. Make sure the complied form file is available in c:\jfsrvr directory.
Example: the complied file name can be acctopen.mdf.
4. Make sure the job name is defined correctly in JetForm Central.
Page 5
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix J
^JOB HFEPRINT
^FORM ACCTOPEN.MDF
^FIELD HOMENAME
LOTUS
^FIELD HOMEADDRESSLINE1
ADR
^FIELD HOMEADDRESSLINE2
…..
2. After clicking print button in WSBCC, it seems the arrow cursor is not coming back.
Make sure all the field definitions such as HOMENAME are defined as the same name in
the form template of JetForm designer.
3. Log files
Jet Form Central provides a log file to show error messages.
Page 6
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix J
Page 7
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix K
Other tools that we adopt for the implementation, testing and maintenance are SpaceAgent,
Rational PerformanceStudio, IBM VisualAge TeamConnection, Microsoft Notepad, and
Macromedia Dreamweaver.
SpaceAgent
In order to improve the performance of application, one area that has been looked at is to
minimize the size for the JSP pages. Currently, there are a lot of unnecessary spaces and tabs in
our JSP pages that can be omitted to make the pages smaller in size. SpaceAgent is a utility that
can do that automatically as well as generating a report on the optimized files regarding how
much space it saved. SpaceAgent processes web pages and removes unnecessary spaces, tabs,
and tags in the HTML code, and yet leaves the JSP coding untouched.
Currently the utility has a limitation where it can not recognize files with “.jsp” suffix as files
contain HTML codes. Pages with “.jsp” suffix have to be manually renamed to “.html” in order
to be optimized by the utility, and renamed back to “.jsp” after optimization.
PerformanceStudio
In order to test the server stability, PerformanceStudio was being used. It has the ability to
record GUI scripts and virtual user scripts to perform the automate testing. The testing can be
broken into three areas, they are functionality testing, performance testing and stress testing.
For the performance testing, HFE used virtual user scripts to simulate multiple users accessing
the same transaction type at the exact same moment. The virtual script can be recorded using the
PerformanceStudio tool, Virtual User Script generator. The process for recording a script requires
access to a licensed PerformanceStudio server. When the system is proved to be working and the
transaction you are testing has performed in the desired way, then recording can begin.
The recording script allows the developer to specify how many users you wish to perform a
transaction at a certain interval. For example 10 users may perform cash withdrawal transactions
while 3 users perform customer search.
The current version of the PerformanceStudio has a limitation where it restricts the number of
multiple user testing to be 50 Virtual Scripts plus 1 GUI script, and license restricted to 51 users.
Page 1
Guidelines for
Server Side Java Thin Client Development
on WSBCC Appendix K
TeamConnection
Notepad
Since all JSP pages, XML and properties files are saved in plain text format, notepad is the most
convenient text editing software that comes with MS Windows. It provides most of the basic
functions that we need for editing a text file such as search, find and replace, cut and paste, and
word wrap.
Although it is a freeware that comes in with MS Windows, it has many limitations. For example,
it can only open a single file in one notepad window; it does not provide color-coding interface
and spell checking mechanism; it does not provide line number for the current location. These
are very inconvenient for developers who have to work on a text file with over 500 lines of code.
Dreamweaver
One of the Web editing tools that HFE is currently using is Dreamweaver, which gives the
functionality to design and implement professional Web pages. It provides a user-friendly
interface for HTML development and quick HTML tag editing. It helps developer to write
cleaner code and provides tools for creating cascading stylesheets. By using Dreamweaver,
developer is no longer required to know HTML. Developers can simply use its drag and drop
functionality to create Web pages.
The current limitation with this software is that it can only recognize HTML tags, developer will
have to modify the HTML source to change the JSP related coding.
Page 2