Dev-guide

Guidelines For Server Side Java Thin Client Development On WSBCC

Group Systems Development Centre HSBC

May 2001 Version 1.2

Page 1

Guidelines for Server Side Java Thin Client Development on WSBCC

Table of Contents 1.

Introduction

2.

Project Development Methodology/Process

3.

WebSphere Business Component Composer Overview (WSBCC)

4.

Analysis Stage

5.

Design Stage

6.

Implementation Stage

7.

Testing/Debugging Stage

8.

Common Beans

Appendix A - Use case writing style guideline Appendix B - Use case word document template Appendix C - Sample data dictionary definition Appendix D - Sample MQ message definition document Appendix E - UML Notation Appendix F - WSBCC Self Defined Process Appendix G - How to generate XML using dsexml1.doc utility Appendix H - How to apply dummy host for HFE Appendix I - Generic Host Message Appendix J - JetForm Central Service and Debugging hints Appendix K - Other Tools

Page 2

Guidelines for Server Side Java Thin Client Development on WSBCC 1.

Section 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. This document aims at providing the followings to: All level of audience The project development methodology, the iterative life cycle and the highlevel elaboration on various developments phases.

1.1

-

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.

Review History

Review

Document Version/Date

Editor/Audience

(1)

Draft Version 1 Oct 2000 Version 1.0 Jan 2001 Version 1.1 Apr 2001 Version 1.2 May 2001

CGD

(2) (3) (4)

Page 1

CGD CGD CGD

Guidelines for Server Side Java Thin Client Development on WSBCC

Section 2

2.

Project Development Methodology/Process In this section, the project development methodology and process is briefly highlighted and made as a referencefor ease of presnetation in subsequent section. The details of the development life cycle and different methodology should refer to HSBC Group ITIM.

2.1

System Development Life Cycle The traditional system development life cycle involves various phases of project development, such as Conceptualization, Analysis, Design, Implementation/Testing, Integrated System Testing, User Acceptance Testing and Maintenance. 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. 2.2

Development Methodology The development methodology adopted here is the Iterative/Incremental development methodology. In an iterative and incremental life cycle, development proceeds as a series of application function release that evolve into the final system. The iterative model is a ‘Vertical ’model, of which evolves with certain basic functions developed in first iteration and with additional functions plugged in subsequent iterations to form the final end 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:

2.3

Development Process 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. Iterative Life Cycle With the establishment of the core requirement, the next step is to move onto the iterative development phases: 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. Integrated System Testing Due to the complexity of the application system and its supporting environment, it is essential to put together all the evolved products and its counterpart application system, and perform the full scale integrated system testing. Naturally, the full scale performance testing, involved end-to-end processing, would also be conducted along with the integrated system testing. User Acceptance Testing The user acceptance testing is the stage for the user departments to perform the final testing on the product prior to the formal release to production environment. With the satisfactory testing result, the user department will provide a formal signoff for the release to the production environment. 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. Its associated product, Websphere Studio V3 Web applications development on JSPs, full HTML, JavaScript and DHTML support WSBCC Workbench

XML preparation

VisualAge for Java

Visual base tools for Java Servlet, Applet development

DreamWeaver

Visual base tools for HTML page design

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

3.

WebSphere Business Component Composer Overview (WSBCC) This document provides the development guidelines for server side Java thin client development, of which is tightly coherent with the WebSphere Business Component Composer (WSBCC). It is essential to have certain understanding and knowledge on WSBCC. This section provides the architecture overview of WSBCC and its major components.

3.1

Architecture Overview WSBCC is IBM’s Java application infrastructure that is designed to rapidly deliver multichannel banking solution. WSBCC supports externalization of workflow, data structure, message formats, database services and communication services in XML, and creates the object using object builders in runtime. By employing extensive parameterization, WSBCC minimizes code development and promotes reusability. In addition, a large set of pre-built WSBCC services are included that help developers to overcome common technical hurdles. WSBCC provides a number of presentation components that facilitates development of application clients including Java, HTML, WML, and other JSP based clients. The HFE application is based on the WSBCC infrastructure for the building of browser base thin client solution. WSBCC architecture overview

Java Client (Applet/ Application)

XML

HTML Client

HTML

Server-side Presentation Logic

Java WML

WAP Client

Web Server

XML WML(WAP)

JSP XML

XML Client

Other Client

Server-side Business & Integration Logic

HTML

Presentation Operation

WSBCC IBM WebSphere

Local Data WSBCC

XML

(e.g., Siebel)

Servlets

Page 6

Business Operation

Enterprise Information System

Guidelines for Server Side Java Thin Client Development on WSBCC 3.2

Section 3

Major Components 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 Flow with Typed Data Elements 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. Defining a Typed Data Element The typed elements are defined in dsetype.xml. Here is an example of a type definition : Ex: HAmount typed element 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: 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. <StringDescriptor id="periodicity" refType="String"/> 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. 1. The contstructor ex myPropertyDescriptor(String, Hashtable, String): The new descriptor is responsible for initializing the value(s) of the associated type. Debugging: The constructors of the Property Descriptor, Converter and Validator is good place to look for typed element errors. Most errors occur when initializing data used by the associated type. This is during the method keyValuePairs.get(String); inspecting this method will indicate any errors or typo’s made in the XML definitions.

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. 1. formatToWriterForType(Object value, String conversionType, java.io.Writer writer, com.ibm.dse.base.types.PropertyDescription desc, java.util.Locale locale) This method will convert the associated type located in the context to an object specified by the conversionType. This method is called when the JSP calls the method UTB.getStringValue(String, String). By specifying the conversion type the string can be preformatted for example: you can have an amount with or without currency by specifying the conversion type. 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. 1. validateForType(Object toValidate, com.ibm.dse.base.types.PropertyDescription descriptor) This method will take an object (String or String[]) and validate it according to the business rules for the associated type. The object to be validated is usually transformed to an object the same as the assosciated type. For example for in HAmountValidator a String[] will be validated and converted into a HAmount object. 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 A framework Flow Processor (also known as an Automaton) is the conceptualization of a business process as a single object and modeled as a state machine. The responsibility of the Automaton is to provide and manage complex conditional logic within the flow of a known business process. 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

Page 12

Section 3

Guidelines for Server Side Java Thin Client Development on WSBCC 4.

Section 4

Analysis Stage Actors: Requirement analysts (front-end and host), users from HUC Responsibilities: Requirement Analyst from Front End Team Produce the data dictionary Produce screen mock-ups Produce activities diagram Produce use case diagram Participate in the discussion of requirements Raise technical feasibility concerns Suggest alternative screen flows and screen layout that overcome technical difficulties or improve the use of technology Requirement Analyst from Host Team Participate in the discussion of requirements Raise technical feasibility concerns Provide F/E team with information about the fields maintained in Host concerning the function Verify the data dictionary 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. Existing Workflow Document 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. Joint Application Design The requirement specification could be prepared and submitted by the user department. It can also be jointly developed by the end users and the requirement analysts through the Joint Application Design process. The JAD is a process of soliciting the user requirements through an intensive discussion between the end users and requirement analysts. 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. To facilitate and to encourage an interactive way of discussion, it is recommended to construct the application screen in simple HTML format with minimum business and navigation logic. It can be considered as a mini-prototype for that specific function. As a general human behavior, it will trigger more thinking when viewing on the real product.

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

Question for users 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

Fig.1 Use case diagram

To start defining a use case in the Rose model, go to the Use case view (Fig.2). In the use case models folder find the correct system folder (CRMS or HFE). Add a new folder and control it. Name it UseCaseModel-<use case name>.cat. Then add the new use case to it. The use case should be associated with the URL of the use case documents in the central document repository.

Fig.2 Use Case View

The use case diagram is the root of the Use Case Models folder. The relationships between use cases should be kept updated always. This diagram can be shown to the users to see if they have the same understanding of the navigation path. 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 To add a new activity diagram, right click on the use case and select new State Diagram (Fig. 4).

Section 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: o o o o o

The data presentation Field caption Purpose (display only, optional input, mandatory input, etc.) Display type (radio button, drop down list, text field, text area, etc.) Style (font, size, effects, color, etc.) Position

The data grouping o Relative position o Format and layout (list, table, scrollable, non-scrollable etc.) 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 upto-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 5.

Section 5

Design Stage Actors: Designers (front-end and host) Responsibilities Designer from Front End Team Produce State diagrams Produce Format class diagram Produce Operation/Format collaboration diagram Produce Data/Context class diagram Produce Operation steps/ Automaton elements class diagrams Provide Host team with a list of fields necessary in the down host message Discuss with Host about MQ message definition when necessary Revise and confirm Data Dictionary according to the finalized screen layout and MQ message definition Designer from Host Team Provide up-host and down-host MQ message definitions Verify Data Dictionary 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 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.

Section 5

As in the analysis level activity diagram, there will be one initial state and one or more final states. In WSBCC, a state can have 5 stereotypes: initial, final, page, Fig. 5 A simple state diagram operation and subflow. Each state type has different type specific information (e.g. JSP filename for <<page>>, process name for <<subflow>>. Refer to WSBCC documentation [4] for details) which will be captured in the documentation box of the state specification. Also because WSBCC’s implementation of the state machine is slightly different from the UML specification, so some extra information will be captured in the documentation box of transitions and states. It is therefore important to remind the developers to check the documentation boxes of those elements when viewing the model. A lot of the flow information is captured by the transitions. The notation of a transition is an arrow with its label specifying the transition specification in the following semantics (also see example in fig.6): EventName [ condition1(param1, param2 …).TRUE/FALSE && or || more conditions] / actionName(params)

Notice that as opposed to 1 action per event in UML’s Fig.6 Transition specification, WSBCC allows multiple actions per event. It may therefore be necessary to utilize the documentation box of the transition to elicit the extra actions. Also WSBCC allows changing state on the evaluation of a guard condition. Once there is a change state Reuse: Subflow? Operation? Page? event occurs on a condition evaluation, In general, if a significant portion of the flow the subsequent actions for this event will logic is wanted, re-use the subflow (e.g. a still execute but none of the subsequent page, an uphost and then another page). If just event produced will be processed. a page with an uphost message, maybe it is Consult WSBCC documentation when in easier to just re-use the page and the doubt. operation. The cross validation inside a state machine can be done through the process

Page 23 Fig. 7 Format class diagram

Guidelines for Browser Base Thin Client Development on WSBCC Section 5 cross validator. For detail functioning of this feature please refer to the How to do Cross Validation document[6]. To indicate the use of the cross validation class, attach a note in the design state diagram with the name of the validation class. 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. An operation state will have an executeHostOperationAct as an entry action. It will execute the operation specifies in its parameters. In general a process will execute one or more operations (to retrieve information from or send information to the host system) using the information in the process context. The Format class diagram shows how the data flows between operation contexts and the process context (fig. 7). Each operation has it own operation contexts. An operation context should be selfcontained, 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: Process to Operation Operation to Process

Mapping format …InputMapFmt

Input source …InputSrcFmt

Input Target …InputTgtFmt

…OutputMapFmt

…OutputSrcFmt

…OutputTgtFmt

Defining self-contained operations and using formats to communicate with the process (as opposed to relying on the process for data definition) facilitates operation re-use without any naming restrictions by de-coupling the process context and the operation context. The price to pay is the time spent on the round trips of formatting. In the rare case where the data naming in the process context is exactly the same as the operation context, you can use the ignoreOpCtxOperationAct that uses the process context as its operation context and thus no mapping is needed. You should consider this approach if performance seems to be an issue. 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. The next important design artifact is the data / context class diagram (4) (Fig. 8). It lays out how the data are defined in the contexts and developers will based on this to define the dsedata or dsetype. As a general rule, if something is a keyed collection, name it with the suffix data. The class attributes will describe the simple fields in that keyed collection.

<> b ra nchData (from dsedata)

<> branchCtx (from dsectx t)

countryCode groupMember branchId branchName branchAddress mediaId

<> htmlSessionCtx (from dsectx t)

<> openSoleDDAccountProcCtx (from dsec txt)

<> openSoleDDAccountProcData (from dsedata)

<> getSerialNumberOpCtx (from dsec txt)

<> availableSerialNumberData (from dsedata)

0..n <> serialNumberItemData (from dsedata) serialNumber

<> errMessageData (from dsedata)

<> getSerialNumberOpData (from dsedata)

<> getSerialNumberRequestOpData (from dsedata) startingSerialNumber endingSerialNumber msgIdentifier = S SSERENQ

0..n <> getSerialNumberReplyOpData (f rom dsedata) statusInd icato r

<> errorMessageItemData (from dsedata) mseId msgType msgLine

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 <>. Otherwise it is <>. 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 <> for process context and <> for operation contexts. This will translate to the type attribute of the operation definition. (type proc and op respectively). To define the data elements, create a class diagram in the function design folder and name it as _function_name-DATA. Drag and drop the common contexts and data elements from the dse folders and Fig. 9 Defining data in context then add those specific to your function inside the class diagram. Those elements will then appear under your function folder (Fig. 9).

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. This collaboration diagram is also is defined alongside with the MQ message definition (6) (See the sample definition [5]). A message definition document should be drafted (either by host and front-end team) and verified by both parties.

Fig. 10 Operation Step / Format collaboration diagram

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 UPTO-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.

The cross validation class behavior should be defined in the documentation box of the doXValidate() method. The behavior should be described in key value pairs of event name and behavior description (Fig. 11). If you have special operation steps you should also do the specification in this class diagram as well.

Fig. 11 Cross validation

5.1

Documentation Logistics This section talks about the access control to the various documentation. The Rational Rose model has been divided into multiple .cat files. When you get a copy of the model and you modify the model, you will modify some of the .cat files. Take note of what .cat files you have modified. When you try to update the master model (through the model custodian), check that if others are modifying the same files, in which case you will have to talk to the other designer for synchronization arrangement. Otherwise, backup a copy of all the .cat files and .mdl and zip it up. Then replace the .cat files that you have changed. For the word documents stored in the central document repository (e.g. use cases, MQ message definition, data dictionary etc.), when you have taken out a copy for modification, please update the task status saying what document is being updated 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 Appendix A - Use case writing style guideline Appendix B - Use case word document template Appendix C - Sample data dictionary definition Appendix D - Sample MQ message definition document Appendix E - UML Notation Appendix F - WSBCC Self Defined Process AppendixG - How to generate XML using dsexml1.doc utility AppendixH - How to apply dummy host for HFE Appendix I - Generic Host Message Appendix J - JetForm Central Service and Debugging hints

Page 28

Guidelines for Browser Base Thin Client Development on WSBCC 6.

Section 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. •

VisualAge of Java 3.0 This is the main development tool for developing Java components. After installation, the repository should connect to: EMSRV Server Address: Repository Name:

NTSVR01 f:\repos\btf\vaj23.dat

Please verify it by pressing F2 and select Repository Management, then Change Repository. 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 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.

Section 6

Lastly, please press Window->Options->Coding->Typed Javadoc. Then cut and paste the following description. Copyright (c) 2000 HSBC. All Rights Reserved. This software is the confidential and proprietary information of HSBC. ("Confidential Information"). It is not to be used for any other purposes, copied, distributed or transmitted in any form or any means without the prior written consent of the HSBC. Creation date: @author: <user> Description: It is <user> responsibility to add the class description here! If he didn't, why did <user> create this class ? Please add the comment <user> !!! Author Date Version Comments -------------------------------------------------------------------------------<user> 31AUG2000 initial Class created Please add a line to describe what you have changed.

•

Team Connection Client This is a Software Configuration Management (SCM) product. It helps us to keep track of the JSP source and a tight version control. Please refer to the Teamconnection environment setup and user guide. It provides the information required for setting up the environment. The companion document is Team ConnGuide.doc.

•

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 6.2

Section 6

Procedures: 1.

Know the requirement Read through the User Requirement documentation, use cases, analysis diagram and sample screen layout to get a general idea of what the users want. Afterwards, developer should read the design documents provided by the designer. Designer has the responsibility to explain the flow and any special instruction to the developer like introducing a new opstep. Developer should raise question if the design document is unclear. Also, the design documents should cover all the naming of the JSP page, new classes, etc. If not, please ask the designer, as we need to keep our naming match with our naming standard. Hence, it is easier for other people to read, investigate and debug.

2.

Declare context structure from Rose diagram(DSECTXT.XML) A context is an object that defines and encapsulates a set of resources (data and services) according to the functional and business organizational entities. Usually, one process will associate to one data resource (a dsedata data structure) and if necessary one or more services like MQ service. 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:

Figure 2 Context diagram of OpenSoleDDAccount

Page 32

Guidelines for Browser Base Thin Client Development on WSBCC

Section 6

As shown in the diagram, the opensoleDDAccountProcCtx contains the openSoleDDAccountProcData. Furthermore, the process involves a maintainCusomertInfo operation, which contains the maintainCustomerInforOpData. Therefore, developer should be able to convert this diagram into the DSECTXT.XML. Like: Depends on situation, the parent context is not necessary to state explicitly in the XML file.

3.

Declare DataElement structure from Rose Diagram (DSEDATA.XML ) DSEDATA.XML file stores the data element information of the operation. It shared from the context chain, received from external services like MQ, and so forth. These data elements may be used in various ways. There are a few common use data elements such as DataField, KeyedColletion, Typed data Element and IndexedCollection. Please refer to the IBM WSBCC Core component training manual for more details. In the design document, the class diagram (data) shows the data structure relationship among them. From the class diagram shown

Page 33

Guidelines for Browser Base Thin Client Development on WSBCC

Section 6

Figure 1 Data diagram of OpenSoleDDAccount

Page 34

Guidelines for Browser Base Thin Client Development on WSBCC 4.

Section 6

Declare DSEOPER.XML from Rose diagram An operation is the entity responsible for performing the set of tasks needed to complete a basic financial operation. In our development, an operation is defined as a MQ processing unit. It means it is responsible to format the uphost message, send the uphost message to the host using MQ, receive the downhost message and unformat the downhost message. 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:

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.

Figure 6 Maintain Customer Operation From the above diagram, developer can convert it into DSEOPER.XML file as shown.

How to add opSteps in an operation

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”:

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. How to control the workflow of an operation. 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

This operation “leadsOnMeOp” is similar to the previous example except the operation will loop back to the first opstep if the opstep ParseRepeatItemServerOpStep returns a 2. This is specified by the “on2Do=FormatHeaderServerOpStep” attribute in the opstep definition of ParseRepeatItemServerOpStep within this operation. With this WSBCC feature on controlling the execution flow of opsteps, an operation can perform complex logic to implement business rules. However, opsteps are designed to be generic and therefore should not contain specific business rules but rather they be defined at processor level instead of in an operation. 5.

Declare DSEPROC.XML from Rose diagram A framework Flow Processor (also known as an Automation) is the conceptualization of a business process as a single object and modeled as a state machine. The responsibility of the Automation is to provide and manage complex conditional logic within the flow of a known business process. The statechart diagram of open sole DD Account Process is as shown in Figure 1. Developer can base on the diagram to generate the corresponding DSEPROC.XML. Furthermore, the design document should show if the process apply any Map format (It is a copy context mechanism in WSBCC). If this is apply, designer should specify in the design document.



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> <executeHostOperationAct id="maintainDDAccountOpAct" operationName="maintainDDAccountOp" linkContextTo="processor" inputMapFmt="maintainDDAccountInputMapFmt" outputMapFmt="maintainDDAccountOutputMapFmt" refreshActiveView="true" />

Page 40

Guidelines for Browser Base Thin Client Development on WSBCC

Section 6



Note that WSBCC also provides self defined processor alternative, please see Appendix F for the details about self defined processor. 6.

Create JSP pages JSP is a user interface. It collects the information entered by the user and displays the result to the user. It can be a JavaScript processing between Create the necessary JSP pages according to the design diagram. Let use create sole and simple account process as an example. Let’s look at the design diagram of the process:

Figure 1 StateChart diagram of OpenSoleAccount Page 41

Guidelines for Browser Base Thin Client Development on WSBCC

Section 6

As shown in the state diagram, there is a <<page>> custNotebook. The stereotype <<page>> means this page state should be implemented by JSP. So, developer should be able to create the JSP page in WebSphere studio with the necessary support document like screen sample layout, user requirement, use case, etc. During the developing of the JSP page, the developer should keep in mind if there is any need to use the existing common beans like the Account Number bean., double combo box, etc. Usually, designer will specify explicitly if they want to use Opstep, Action instead of Javascript to perform some behavior. If there is no instruction, Javascript can be use. But the use of Javascript should be keep to minimal for easier maintenance. If developer has any doubt, he should ask the designer for assistance. Furthermore, the name of the input field should match exactly the same as the data Element defined in the dsedata.xml. If not, the WSBCC could not copy the input field to the context. Also, please remember to include the following text into the JSP if there is a need to use the context service. <jsp:useBean id="utb" scope="page" class="com.ibm.dse.cs.html.DSEJspContextServices"> <% utb.initialize ( request ); %>

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. The following section illustrates the details of different validation alternatives: 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. Typed Data Validation In WSBCC version 4, it provides the ‘Typed Data Element’ definition and reference. The idea is to decouple the DataElement from the business objects, but have the behavior that reflects the business rules that pertain to the business object 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 example, the custSearchProData data definition has a default descriptor, KCollDescriptor. The custSearchProData data definition specifies eight descriptors which define its structure: seven of type KeyedCollection called ‘custRecordData’, ‘custDemographicsData’, ‘custContactHistoryData’, ‘custOverviewData’, ‘custSearchRequestOpData’, ‘custSearchReplyOpData’ and ‘searchResultRequestOpData’ and one of type String called ‘critType’. For each keyed collection in custSearchProData defined in the dsedata file, specifies the corresponding descriptor to define its structure. The bottom level typed data are defined before the top level. <StringDescriptor id="creditGradeCode" refType="String"/> <StringDescriptor id="creditGrade" refType="String"/>

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:

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. The same goes for the HAmount descriptor:

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().

Cross Field Validation 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. 2. In the doXValidate method, put in your validation logic. This validation is called every time an HTML request is trying to update the process context. Therefore you can either validate every time this is updated (to keep context consistent) or on an event basis (like this example). public void doXValidate(com.ibm.dse.base.Context context, String transitionName) throws Exception { if(context == null || transitionName == null) return ; 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."); } } }

3. In dseproc.xml, add the xVal to the process definition:

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.

8.

Declare DSEFMT.XML from Rose diagram Format classes are example of the Composite design pattern. It is used by operations, services, or operation steps to convert data items into formatted strings or to parse formatted strings and update data items. It has 2 basic kinds of formats. They are RecordFormat and IndexedCollectionFormat. The Record format is used to format/unformat the KeyedCollection in the context while IndexedCollectionFormat is to format/unformat the IndexedCollection in the context. Designers will specify all the formats used in the design document. Developer should check if the formats is already defined by some other people already like MQHeaderRequestFormat, MQHeaderReplyFormat and all those repeating item formats. It is unclear, please ask the designer for help.

Page 46

Guidelines for Browser Base Thin Client Development on WSBCC

Section 6



Page 47

Guidelines for Browser Base Thin Client Development on WSBCC

Section 6



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. Here is the design diagram for the map format.

Figure 2 Format Design

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

<delim delimChar="~"/> <delim delimChar="~"/> <delim delimChar="~"/> <delim delimChar="~"/> <delim delimChar="~"/> <delim delimChar="~"/> <delim delimChar="~"/> <delim delimChar="~"/> <delim delimChar="~"/> <delim delimChar="~"/> <delim delimChar="~"/> <delim delimChar="~"/> <delim delimChar="~"/> <delim delimChar="~"/> <delim delimChar="^"/>

How to add a new format A new format may be needed to handle the formatting of a new typed data or a new data field class (extended from com.ibm.dse.base.DataField). A new format class should extend com.ibm.dse.base.FieldFormat, if it will be used to format a DataField (whether typed or not); com.ibm.dse.base.KeyedCollectionFormat if it will be used to format a KeyedCollection; or com.ibm.dse.base.IndexedCollectionFormat if it will be used to format an IndexedCollection. In most cases, the new class will be extended from FieldFormat because only in very special situation that a special handling of KeyedCollection or IndexedCollection would be needed. By convention, the new class should have “Format” as its suffix, and the type name (eg. HTextArea), if any, as its prefix. 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



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 9.

Section 6

Inspect WSBCC Data element After all the XML files have been created, developers should be able to perform the following testing to see if the data elements can be read. Put the following code in the scrapbook. 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 ); // Get specific Data from dsectx com.ibm.dse.base.Context aContext = (com.ibm.dse.base.Context) com.ibm.dse.base.Context.readObject("openSoleDDAccountProcCtx"); aContext; // Get specific Data from dsedata com.ibm.dse.base.DataElement aData = (com.ibm.dse.base.DataElement) com.ibm.dse.base.DataElement.readObject("custAddressData"); aData; // Get specific Format from dseformat com.ibm.dse.base.FormatElement aFormat = (com.ibm.dse.base.FormatElement) com.ibm.dse.base.FormatElement.readObject("mqMaintainAddressDetailRequ estFmt"); aFormat; // Calculate Format Length com.ibm.dse.base.FormatElement aFormat = (com.ibm.dse.base.FormatElement) com.ibm.dse.base.FormatElement.readObject("mqMaintainAddressDetailRequ estFmt"); int formatLength = com.hsbc.cgd.crms.oper_svr.FixedLengthFormatUtil.calcFixedLengthFormatLe ngth(aFormat); formatLength; 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.

10.

Error Handling

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 Next to the Data Field To cope with the validation methodology for Typed Data Field validation described in the previous section, the validation error message could be easily displayed together with the implementation of JavaScript. It is suggested to display the error message next to the related data field. This approach provides the clear reference to the users on which error field requires modification and alteration. It is very useful in managing the error message display especially for the context with multiple data fields bearing the same data type definition. 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. " 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)"> " 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)"> <%= utb.getFieldErrorDecorated ( "custSearchRequestOpData.custAcctData.hubAcct", 0 ) %>

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

Top of the Screen The other approach in displaying the error message is to embed the message within the HTML pages. The error message could then be displayed on top of the page. The cross validation feature provided in WSBCC V4 requested to specify on what page the error message to displayed in the JSP. The sample coding is described in steps 5 and 6 in section 8 Cross Validation section. 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

11.

Section 6

JSP to Process Context Testing The aim of this testing is to check if the input field defined in the JSP can update the context successfully when the user press the action button. Developers can set a break point in the updateContext(collection) method of the com.ibm.dse.automation.html.DSEHTMLProcesserOperation class. While the program break at this breakpoint, you can inspect the Collection object, which stores the HTTP request object from the JSP. So, developers can check if there is something not correct. At the same time, he can check the Process Context before the update process by inspecting this (DSEHTMLProcessor) object.

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. 12.

Process Context to Operation Context testing The purpose of this testing is to ensure the information from the process context is passed to operation context by using the Map Format. Developers can set a break point at the mapContents(context, context) method of the com.ibm.dse.base.DataMapperFormat class. DataMapperFormat is a concrete class for implementing the inputMapFmt and outputMapFmt associated in the processor. While the program breaks at this point, developers can inspect the process context and operation context before and after the data is copied.

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. Please refer to the documentation came with the DummyHost Utility.

14.

The uphost message generation testing As the current MQ message structure is agreed with the HOST side and it contains a number of section. To cater for that, we have different operation steps to generate different message sections. So, it is a good to set the break points in the execute() methods of the following operation steps and check the if there is anything goes wrong. com.hsbc.cgd.crms.oper_svr.FormatHeaderServerOpStep com.hsbc.cgd.crms.oper_svr.FormatDetailServerOpStep

15.

Unformatting dnhost message testing Similar to the uphost message, developers can set the following break points at the execute() method of the following classes: 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. 17.

Process Context to JSP testing This is the user interface display to the user. It is easy to test as it is the final results we want to achieve.

18.

Real MQ Interface Test with HOST This is the real interface test with the host. Developers will concentrate on the both generated uphost message and received dnhost message to see if we have any misunderstanding with the host program.

19.

Extending WSBCC classes At any stage during implementation you may find that the classes the framework provides inadequate for your application needs. In this case you my need to extend the classes for your customization. Here is a list of classes which you may need to extend given certain situations: For new Actions: com.ibm.dse.automaton.DSEAction For new Cross Validators: com.ibm.dse.automaton.html.HtmlProcessorXValidate0 For new Services: com.ibm.dse.base.Service For new Typed Elements: com.ibm.dse.base.types.AbstractPropertyDescriptor For new Validators: com.ibm.dse.base.types.AbstractValidator For new Converters: com.ibm.dse.base.types. AbstractConverter For new Formats: com.ibm.dse.base. FieldFormat For new Operations: com.ibm.dse.base.OperationStep 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 7.2

Section 7

Debugging The following is a general outline of a process-operation logical flow.

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

Stag 1 and Stage8: Data Mapping Data Mapping is the act of mapping data from a processor’s context to an operation’s context and vice versa. It is implemented through the java class com.ibm.dse.base.DataMapperFormat. Data mapping is executed twice, once for before a request and another after a reply.

1 2

3

Page 59

Guidelines for Server Side Java Thin Client Development on WSBCC

Section 7

1. FormatElement inputFormat: this format element is the “Source” format. It will format the inputContext which is the processor’s context in Stage 1 and the operation’s context for Stage 8. 2. FormatElement outputFormat: this format element is the “Target” format. It will format the outputContext which is the operation’s context in Stage 8 and the processor’s context for Stage 1. 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

Stage 2 and Stage3: Formatting OpSteps 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

3

1. myCRMSServerOp is the operation instance. While debugging it is a good idea to inspect this object’s fieldInBuffer and fieldOutBuffer. It’s fieldInBuffer is where the uphost message will be put (during the format OpSteps) and the fieldOutBuffer will contain the downhost message after communicating with the host. The parsing OpSteps will work with the fieldOutBuffer to populate the operation context.

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. Stage 4: MQ Messaging OpSteps The implementation of the communication with host via MQ Message is done through this class com.hsbc.cgd.crms.oper_svr.MQSendandReplyServerOpStep. However, there are situations where the host environment is not accessible in this case we use com.hsbc.cgd.crms.oper_svr.DummySendAndReplyServerOpStep class to simulate the offline scenario.

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. This is the com.hsbc.cgd.crms.oper_svr.DummySendAndReplyServerOpStep class used for offline simulation. This class works with the “Dummy MQ Message” utility. A set of uphost and corresponding downhost messages should be already be created prior to running the program. with this OpStep.

1

1

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

Stage 5, Stage 6 and Stage 7: Parsing OpSteps 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.

1

2

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.

1. The execute() for ParseRepeatItemServerOpStep is similar to the other parsing OpSteps except the method can parse the fieldOutBuffer multiple times depending on how many repeating items there are. The currentFormat is the format associated with the current repeating item to be parsed and formatted. A common error that may occur here is that the currentGroup can not be found in the DSEDATA.XML in which case currentFormat will be null. The repeating items are defined with their formats in the DSEDATA.XML, make sure that the table is complete.

Page 65 1

Guidelines for Server Side Java Thin Client Development on WSBCC 7.3 General Debugging Methods

Section 7

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 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

Initialization of XML files During system initialization, the XML files will be parsed and read into respective “externalizers” (eg. DataExternalizer). When the XML files are not parsed successfully, the developer should see error messages on the reply page, indicating which line in which file fails. The developer can then go to that line or related sections to check the syntax. 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, <StringDescriptor id=”myField1” refType=”String”/> <StringDescriptor id=”myField2” refType=”String”/> <StringDescriptor id="typeDefault"> <stringConverter convTypes="default,host" implClass="com.ibm.dse.base.types.ext.StringConverter"/>

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:

Page 72

Guidelines for Server Side Java Thin Client Development on WSBCC

Section 7



When a format needs to refer to myField1, it only needs to point to “2ndLevelKCollA.myField1” instead of “processAKColl.2ndLevelKCollA.myField1” because the format element starts at the first level of the KeyedCollection and it does not need to know the ID of the first level. Exception thrown after an HTML form is submitted In some cases, a developer may find that after a form on an HTML page is submitted to the server and the system replies with an error page or receives an exception, com.ibm.dse.base.DSEInvalidArgumentException: Unable to find a transition in the state. This means the event sent from the HTML form is not defines in the automaton in dseproc.xml. The developer should check the processor definition and verify the transition names with those sent from the HTML form. 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. Scriplet and Other Errors If the JSP is compiled successfully but does not behave as expected, the developer should set break points in the servlet classes compiled (from the JSP). They are located in the “JSP Page Compile Generated Code” project. The name of the servlet is generally given as “name of the JSP_jsp_0”. Page 73

Guidelines for Server Side Java Thin Client Development on WSBCC

Section 7

Services Not Started If the system initializes successfully but it cannot utilize certain external resources like MQ services or database services, this is probably due to the absence of the resources needed for the services defined in “dsesrvce.xml”. If any resource needed for services defined in “dsesrvce.xml” is not available at the time of system initialization (eg. MQ connection, DB2 service), the initialization will still be successful but it is in fact lacking some services. The developer should ensure that the required services/third party applications are started as the services defined in “dsesvrce.xml” require. Class Path Missing Sometimes the system does not initialize successfully even though the all the “dse” files are constructed correctly. The system may indicate that some classes are not found after it fails to initialize. This is likely to be caused by an incomplete class path. If the test is run on IBM WebSphere Test Environment, check the file path for the class “com.ibm.servlet.SERunner”. If the system is running on the IBM WebSphere Application Server, check the file path for the application.

Page 74

Guidelines for Server Side Java Thin Client Development on WSBCC 8.0

Section 8

Common Beans Common beans are common components that can be shared by all applications. They are classified as GUI beans and Desktop beans.

8.1

GUI 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.

8.1.1

HTML Text Field 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: <SCRIPT LANGUAGE="JavaScript" SRC=" /js/TextField.js "> 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.

Attribute Name maxlength minlength autoTab autoClear

inMask

Description JS Event JS Handler Related Attribute(s) JS Methods Maximum no. of characters Minimum no. of onBlur textBlur() textBlur() characters Change focus to the next field if the maximum no. onKeyUp textKeyUp() autoTab() maxlength of characters has reached. Select all the characters autoClear() when the field has focus onFocus textFocus() "Alpha" : A to Z, a to z, a space and a character onKeyPress textKeyPress() from the extended Nixdorf Character Set. "Numeric" : 0 to 9, +, -, procInMask() and dot "AlphaNumeric" - Alpha + Numeric "None" : Allow every characters

Page 75

Guidelines for Server Side Java Thin Client Development on WSBCC outMask

padChar

padStyle

"Uppercase" : conver to upper case "Lowercase" : convert to lower case "None" : no convertion The character used to fill the field with the minimum character if the padStyle is not "None" "Before" : Fill the text with leading padChar(s). "After" : Fill the text with trailing padChar(s). "None" : no padding will perform

Section 8 onBlur

textBlur()

onBlur

textBlur()

Minlength, padStyle

onBlur

textBlur()

Minlength, padChar

patch()

patch()

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.

8.1.2 HTML Account 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: <SCRIPT language="JavaScript" src="/js/Textfield.js"> <SCRIPT language="JavaScript" src="/js/Account.js">

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.           <%=utb.getFieldValidationErrorDecorated("acctNumber", 0)%> 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. In dsetype.xml, one typed element (acctNumber in this example) needs to be defined. That HAccount object can extract any of its attributes (branch, serial etc.). It can be declared as follows: In dsefmts.xml, fAccount needs to be used to format an HAccount. For the fAccount, specify the mask as CCGGGGBBBNNNNNNSSS (for account number) or CCGGGGBBBNNNNNN (for customer number). The following is an example of how it can be declared:

8.1.3 HTML Amount

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: <%-- initial value combo box --%> <jsp:useBean id="InitialValueModel" class="com.hsbc.cgd.html.RefDataModel" scope="session"> <jsp:setProperty name="InitialValueModel" property="serviceAlias" value="refData"/> <jsp:setProperty name="InitialValueModel" property="fieldName" value="ID"/> <jsp:setProperty name="InitialValueModel" property="collectionName" value="CCYCollection"/> <jsp:setProperty name="InitialValueModel" property="displayColumnName" value="ID"/> <jsp:setProperty name="InitialValueModel" property="tableName" value="CURRENCY"/> <jsp:setProperty name="InitialValueModel" property="sys" value="NULL"/> <% InitialValueModel.setUseFieldValue(true); %> <jsp:useBean id="InitialValue" class="com.hsbc.cgd.html.HTMLComboBox" scope="page"> <% InitialValue.setModel(InitialValueModel);%> Also create a text input field for the amount: <SELECT class="lstMnu" name="initialValueAmount"> <% InitialValue.setSelectedOption(utb.getStringValue("initialValueAmount", "CCY")); %> <jsp:getProperty name="InitialValue" property="html"/> 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

In dsefmts.xml, fAmount should be defined as follows: Note that the currency and the amount need to be defined separately although they are using the same name. 8.1.4 HTML Combo Box 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. To include a HTML Combo Box bean, create an instance of the RefDataModel bean and set properties using JSP tags as follows: <jsp:useBean id="IdTypeModel" class="com.hsbc.cgd.html.RefDataModel" scope="session"> <jsp:setProperty name="IdTypeModel" property="serviceAlias" value="refData"/> <jsp:setProperty name="IdTypeModel" property="tableId" value="ID"/> <jsp:setProperty name="IdTypeModel" property="sys" value="SS"/> <jsp:setProperty name="IdTypeModel" property="fieldName" value="ID"/> <jsp:setProperty name="IdTypeModel" property="collectionName" value="idTypeCollection"/> <jsp:setProperty name="IdTypeModel" property="displayColumnName" value="DESC"/> <jsp:setProperty name="IdTypeModel" property="orderByColumnName" value="DESC"/> <jsp:setProperty name="IdTypeModel" property="tableName" value="CONTROLDATA"/> Page 80

Guidelines for Server Side Java Thin Client Development on WSBCC <% IdTypeModel.setUseFieldValue(false); %>

Section 8

After that, create an instance of the HTMLComboBox Model bean and set properties, as follows: <jsp:useBean id="IdType" class="com.hsbc.cgd.html.HTMLComboBox" scope="page"> <% IdType.setModel(IdTypeModel);%> After all the properties are set, the combo box can be declared by using the SELECT tag to get the HTML property as follows: <SELECT name="ComboBox1"><jsp:getProperty name="idType" property="html"/>

8.1.5 HTML Double Combo Box 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.

8.1.6 Date Picker 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



 <%= strDateFrom %> 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”.

8.2

Desktop Beans Desktop beans are common components share by some applications. Currently only Customer Status Bar bean belongs to this category because this bean must be displayed in all customer-related applications.

8.2.1 Customer Status Bar 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: <%-- CustStatusBar --%> <jsp:useBean id="custStatusBar" class="com.hsbc.cgd.html.desktop.CustStatusBar" scope="page" /> <%custStatusBar.setContextService(utb);%>

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: <%-- CustStatusBar --%> <jsp:getProperty name="custStatusBar" property="HTML"/> 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

Appendix A – Use Case Writing Style Guidelines 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 datamodeling 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”

Naming and Notation Guidelines When referring to (data) fields that are to be added to the data dictionary, use a name that is unique to the entire data dictionary (i.e., to the entire system); for example, use the name “Branch number” rather than the simple name “Number”. In general, qualify names as much as possible to aid clarity. [A#]: identifies the alternative flow sections – alternative flows are generally considered to be choices that are intentionally made by the actor. [W#]: identifies the warning flow sections – warning flows are generally considered to be choices that are not intentionally made by the actor and normally result from non-fatal or noncontrolling, erroneous conditions. [E#]: identifies the exception flow sections – exception flows are generally considered to be choices that are not intentionally made by the actor and normally result from significant error conditions. Use the “numbered text” style to list the flow steps. See the “Use-Case Example” document for more explanation of the enumeration guidelines (by example) and the “Annotated Use-Case Example” document for more explanation regarding the section contents. Terms Used for Use-Case Naming Word Generate

Maintain

Process

Report

Usage description The verb used to indicate system-driven/programmatic creation of information; e.g., “The System generates an Audit Information entry containing …”. Generate is also the verb used when naming use cases that identify reporting requirements; e.g., Generate Posting Report or Generate Monthly Statements. The verb used when naming a use case wherein the primary requirements are to create, delete, and/or modify information. Normally this applies to information that will constitute classes of information that are of stereotype “entity”. The verb used when naming a use case (or use case “includes” stereotyped relation) wherein the primary requirements are to process information; i.e., provide functionality/behavior. An noun used when naming a use case wherein the primary requirements are to gather, select, sort, and present information in a read-only, and often hard-copy, form Page 2

Guidelines for Server Side Java Thin Client Development on WSBCC Summary

View

Appendix A

- e.g., Generate a GL Report. Note that report is not used as a verb when writing use cases. (See also, 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) 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)

Terms Used for Use-Case Writing Word Collection

Get Information

Initiate posting (of transaction) Initiate/start-up Logical delete

Physical delete

Present (verb) Receive Resolve Select Supply/Provide

Usage description The generic way to indicate a number of items without implying any data-structure and/or data-processing semantics (e.g., the Banker selects an Account Restriction from the collection of Account Restrictions). Indicates the process of actively obtaining information. The generic term used to indicate a (collection of) data – do not use computer terms such as record, field, form, etc. in the use case (e.g., The system retrieves and presents the Customer Information). Standard phrase used to indicate that the actor has posted, but the system has not yet posted the transaction (i.e., it still could be rejected by the system if it doesn’t pass the validation steps). Indicates the process of beginning a task. Indicates that an element of information has been “marked for deletion” and that it may be deleted by the next applicable purge operation (actual deletion is subject to the necessary consistency checks). The information remains until it has been purged. Items which have been logically deleted may or may not participate in other use-case flows, as determined by the requirements for that flow (e.g., may optionally be visible on forms and/or reports). Prior to a logically deleted item being purged, it may be able to be “undeleted” by a reversing capability (e.g., by “unmarking” the “marked for deletion” item). Indicates that an element of information has been removed from the system. The information is immediately and permanently made unavailable (where successful completion is subject to the necessary consistency checks). Indicates that information is shown; use instead of computer/design-limiting terms such as display. Indicates the process of passively obtaining information. Indicates an action that involves human decision-making. Indicates that an actor actively identifies/supplies an item from a collection of items that was presented by the system. The generic alternative to the computer-oriented, design-limiting term “enter”; e.g., the user supplies a value (different from selecting a value).

Page 3

Guidelines for Server Side Java Thin Client Development on WSBCC Terms Used in the Data Dictionary Word Mandatory

Is A Requirement

Appendix A

Usage description 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. 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).

Placeholders – Syntax: [the note indicating the stuff to be completed] You can use placeholders to signal something that’s incomplete and will be completed at a later date.

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).

Language to Avoid When Writing Use Cases Computer-based terms that should not appear in use cases: •

Database

•

Display – use present

•

Enter – use supply

•

Field – use value

•

Flag

•

Form

•

Key

•

Option – use parameter

•

Record

•

Wishes – capture behavior, not wishes

•

Fills in - use defaults (as a verb)

•

Will provide - use presents

•

Window

•

Tabs – use visits or selects

Page 4

Guidelines for Server Side Java Thin Client Development on WSBCC

Appendix B

Appendix B - Use case word document template

Use Case <Use Case Name> Amendment Record Version

Amendment Details

1.0

Page 1

Author

Date

Guidelines for Server Side Java Thin Client Development on WSBCC Name: enter the use-case Name here (in “Title style” style)

Appendix B

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 <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 The behavior goes here…

Appendix B

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 is informed of the error and provided the opportunity to correct the situation or cancel the activity. If the corrects the error, the use case continues as though this flow had not been encountered. If the 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. User-Interface Comments: (use “Body Text” style) State any GUI limitations, requirements, and/or suggestions and clearly identify them as either comments/suggestions or as customer-stated, design constraints. Design Comments: (use “Body Text” style) State any design comments and/or suggestions and clearly identify them as either comments/suggestions or as customer-stated, design constraints.

Glossary This section describes some of the terms used in this use case document. Data Dictionary Field Name

Description/Rules

Page 3

Action/Result

Guidelines for Server Side Java Thin Client Development on WSBCC

Page 4

Appendix B

Guidelines for Server Side Java Thin Client Development on WSBCC

Appendix C

Appendix C – Sample Data Dictionary Definition

Field Name

addrLine1 addrLine2 addrLine3 addrLine4 addrLine5 Classification contactBy contactById contactChannel contactChannelCode contactIndex contactPurpose contactPurposeCode contactDate countryCode creditGrade creditGradeCode custIndex custNoteLine1 custNoteLine2 custStatus custNumber dateFrom dateOfBirth dateTo firstName Gender groupMember headerVersion homePhoneAreaCode homePhoneNumber idNumber

Field Description Account Short Name Address Line 1 Address Line 2 Address Line 3 Address Line 4 Address Line 5 Customer Classification Contact By User Name Contact By User Id Contact Channel Description Contact Channel Code Contact Index Contact Purpose Contact Purpose Code Contact Date Country Code Credit Grade Credit Grade Code Customer Index Customer Note Line 1 Customer Note Line 2 Customer Status

Attribu te A A A A A A A A A A

Lengt h

A A A A N A A A A A A A

3 15 50 3 8 2 38 1 15 60 60 1

A N

15 8

yyyymmdd

N N

8 8

yyyymmdd yyyymmdd

A A A A A A A

28 1 4 2 10 32 20

Customer Number Date From – Start of a Date Range Date Of Birth Date To – End of a Date Range Customer First Name Gender Group Member Header Version Id Home Phone Area Code Home Phone Number Id Number Page 1

35 35 35 35 35 1 50 4 25

Notes

e.g. PRJ, PRS

yyyymmdd

e.g. C for Customer, P for Prospect

Guidelines for Server Side Java Thin Client Development on WSBCC initialValueAmount Initial Value Amount initialValueCurrency Initial Value Currency isCorrection Is Correction isLead Is Lead jointDate Customer Joint Date lastName Customer Last Name logonDate Logon Date: Obtain from host at signon logonTime LogonTime: Obtain from host at signon managerCode Manager Code mediaId Media Id (4A: TCID, 6A:blank – future use) msgIdentifier Message Type(2A:System code, 3A: Deal code, 5A: blank-future use) msgVersion Message Version Id(2A:Core Msg Ver; 2A:Local Msg Ver, 6A:blank-future use) first core version:’0100 ‘ Nationality Nationality nationalityCode Nationality Code newAcctNumber New Account Number newActionDate Next Action Date newCustFlag New Customer Flag noteLine1 Notes Line 1 noteLine2 Notes Line 2 noteLine3 Notes Line 3 noteLine4 Notes Line 4 Package Package packageCode Package Code productClass Product Class productClassCode Product Class Code Product Product Description productCode Product Code prospectNumber Prospect Number referToId Refer To User Id Result Result resultCode Result Code sentById Sent By User Id statusIndicator Status Indicator(‘N’-Normal’, ‘R’- Reject with Error Message, ‘X’ – with Page 2

Appendix C A A A A N A N

24 3 1 1 8 45 8

N

6

A A

3 10

A

10

A

10

A A A N A A A A A A A A A A A A A A A A A

25 2 20 8 1 60 60 60 60 25 5 25 3 25 3 9 4 48 3 4 1

yyyymmdd yyyymmdd hhmmss

yyyymmdd

Guidelines for Server Side Java Thin Client Development on WSBCC Exception Message) Source Source sourceCode Source Code Title Title updateDate Update Date updateTime Update Time userid Logon User Id workPhoneAreaCode Work Phone Area Code workPhoneNumber Work Phone Number workstationId Logon workstation Id writtenLanguage Preferred Written Language writtenLanguageCode Preferred Written Language Code

Page 3

Appendix C A A A Z Z A A A A A

50 3 3 8 6 4 10 32 4 15

A

2

e.g. MR yyyymmdd hhmmss

Guidelines for Server Side Java Thin Client Development on WSBCC

Appendix D

Appendix D – Sample MQ Message Definition Document MQ Message format for Create Joint Account Revision History Date 24Oct2000

Revision Initial

Description

Author JOE

Create Joint Customer with Joint Account Message Create Joint Customer with Joint Account Message -Request Message Field Name

Description

L Type

Value

Len Header Section: headerVersion countryCode groupMember mediaId userId logonDate logonTime msgIdentifier msgVersion statusIndicator workstationId Detail Section: groupId dtlLen maintCode cust.countryCo de cust.groupMem ber cust.branch

Header Version Id Country Code Group Member Media ID (4A:TCID, 6A:blank-future use) Logon User Id Logon Date: Obtain from host at sign on Logon Time: Obtain from host at sign on Message Type(2A:System Code, 3A:Deal code, 5A: blank-future use) Message Version Id (2A:Core Msg Ver, 2A:Local Msg Ver, 6A:blank-future use) first core version:’0100 ‘ Status Indicator(‘N’-Normal, ‘R’-Reject with Error Message, ‘X’- Warning with Exception Message) Logon Workstation Id

2 2 4 10 4 8 6 10

A A A A A Z Z A

10

A

1

A

4

A

Group ID Length of detail session Maintenance Code Country Code

10 5 1 2

A Z A A

Group Member

4

A

Domestic Customer Branch

3

N

Page 1

yyyymmdd hhmmss “SSCACMNT’ ’ First core version: ’0100 ‘

‘DetailS’ 575 ‘A’ (for Add)

Guidelines for Server Side Java Thin Client Development on WSBCC cust.serial Domestic Customer Serial prospectSerial Potential Customer Serial Classification GHO classification marketSector Market Sector Manager Relationship Manager Code languageCode Language Code reason How introduced to Bank Blank Filler (for sole customer info) Joint Information lastName Joint Name corrName Correspondence Name shortName Short Name jointName2nd Joint Name – 2nd Language corrName2nd Correspondence Name – 2nd Language shortName2nd Short Name – 2nd Language basicDD DD Account Indicator groupMember Group Member acct.prefix Account Branch acct.serial Account Serial acct.suffix Account Suffix instantATM Instant ATM Card Indicator productCode Product Type Code Currency Currency code Repeati ng Section groupId Number Of Items Item Length jointCustList.*. cust

Appendix D 6 6 3 5 3 1 3 247 1 70 35 28 70 35 28 1 4 3 6 3 1 3 3

N N A N A A A A A A A A A A A A A N N N A A A

Group ID Number Of Items

10 5

A N

IndCustNos automatic

Item length Individual customer’s full customer number (CCGGGGBBBNNNNNN)

5 15

N A

0015

‘J’

BLANK BLANK

Create Joint Customer with Joint Account Message -Reply Message Field Name

Description

L Type Value Len

Header Section: HeaderVersion CountryCode groupMember mediaId userId logonDate

Header Version Id Country Code Group Member Media ID (4A:TCID, 6A:blank-future use) Logon User Id Logon Date: Obtain from host at sign on Page 2

2 2 4 10 4 8

A A A A A Z

yyyymmd

Guidelines for Server Side Java Thin Client Development on WSBCC logonTime msgIdentifier

Appendix D

Logon Time: Obtain from host at sign on Message Type(2A:System Code, 3A:Deal code, 5A: blank-future use) Message Version Id (2A:Core Msg Ver, 2A:Local Msg Ver, 6A:blank-future use) first core version:’0100 ‘

6 10

Z A

10

A

Status Indicator(‘N’-Normal, ‘R’-Reject with Error Message, ‘X’- Warning with Exception Message) Logon Workstation Id

1

A

4

A

Group ID Length of detail session Customer Number (CCGGGGBBBNNNNNN) Account Number (GGGGBBBNNNNNNSSS)

10 5 15

A Z A

16

A

Message Section: groupId

Group Id

10

A

no. of Items no. of chars/line msgId msgLine

Number of items Number of chars per line Message Id Detail Message

5 5 10 80

Z Z Z A

msgVersion

statusIndicator workstationId Detail Section: groupId dtlLen cust acct

Page 3

d hhmmss “SSCAC MNT’’ First core version: ’0100 ‘

‘DetailS’ 31

‘ErrMsgR ’

Guidelines for Server Side Java Thin Client Development on WSBCC

Appendix D

Create Individual Customer Message Create Individual Customer Message -Request Message Field Name

Description

L Type

Value

Len Header Section: headerVersion countryCode groupMember mediaId userId logonDate

Header Version Id Country Code Group Member Media ID (4A:TCID, 6A:blank-future use) Logon User Id Logon Date: Obtain from host at sign on

2 2 4 10 4 8

A A A A A Z

Logon Time: Obtain from host at sign on Message Type(2A:System Code, 3A:Deal code, 5A: blank-future use) Message Version Id (2A:Core Msg Ver, 2A:Local Msg Ver, 6A:blank-future use) first core version:’0100 ‘

6 10

Z A

10

A

Status Indicator(‘N’-Normal, ‘R’-Reject with Error Message, ‘X’- Warning with Exception Message) Logon Workstation Id

1

A

4

A

Group ID

10

A

dtlLen maintCode

Length of detail session Maintenance Code

5 1

Z A

cust.countryCo de cust.groupMem ber cust.branch cust.serial prospectSerial Classification marketSector rmCode languageCode

Country Code

2

A

Group Member

4

A

Domestic Customer Branch Domestic Customer Serial Potential Customer Serial GHO classification Market Sector Relationship Manager Code Language Code

3 6 6 3 5 3 1

N N N A N A A

logonTime msgIdentifier msgVersion

statusIndicator workstationId Detail Section: groupId

Page 4

yyyymm dd hhmmss “SSCUS MNT’’ First core version: ’0100 ‘

‘DetailS ’ 860 ‘A’ (for Add)

Guidelines for Server Side Java Thin Client Development on WSBCC reason lastName firstName Initials Title preferredName lastName2nd firstName2nd Initials2nd Title2nd idType idNumber Nationality countryOfResid ence Sex dateOfBirth lastName corrName shortName jointName2nd corrName2nd shortName2nd Occupation employer.Name employer.Addre ss yearsCurrentE Mployer monthsCurrent Employer previousEmplo yer yearsPreviousE Mployer monthsPrevious Employer Income otherIncome otherIncomePer iodicity

Appendix D

How introduced to Bank Key Information Last Name First Name Initials Title Preferred Name Last Name – 2nd language First Name– 2nd language Initials– 2nd language Title– 2nd language Identity Document Type Identity Document Number Nationality Country of Residence

3 1 35 35 10 10 32 35 35 10 10 1 20 2 2

A A A A A A A A A A A A A A A

Sex Date Of Birth Joint Information Joint Name Correspondence Name Short Name Joint Name – 2nd Language Correspondence Name – 2nd Language Short Name – 2nd Language Sales Potential Information Occupation Employer name Employer Address (5x35)

1 8 1 70 35 28 70 35 28 1 2 35 175

A A A A A A A A A A A A A

BLANK BLANK BLANK BLANK BLANK BLANK BLANK BLANK BLANK BLANK BLANK

No. of years with current employer

2

N

BLANK

No. of months with current employer

2

N

Previous Employer Details

35

A

No. of years with Previous employer

2

N

No. of months with Previous employer

2

N

Income (Ccy + Amount + Sign) Other Income (Ccy + Amount + Sign) Other Income Periodicity

17 17 1

N N A

Page 5

‘K’

BLANK

BLANK BLANK BLANK

Guidelines for Server Side Java Thin Client Development on WSBCC sourceOtherInc ome educationLevel maritalStatus Dependents partnerName Repeati ng Section groupId Number Of Items Item Length jointCustList.*. cust

Appendix D

Source of other income

1

A

Education Level Marital Status No. of dependents Family Information Partner’s Name

1 1 1 1 35

A A N A A

Group ID

10

A

Number Of Items

5

N

Item length Individual customer’s full customer number (CCGGGGBBBNNNNNN)

5 15

N A

BLANK

BLANK

IndCust Nos automat ic 0015

Create Individual Customer Message -Reply Message Field Name

Description

L Type Value en

Header Section: HeaderVersion CountryCode groupMember mediaId userId logonDate logonTime msgIdentifier msgVersion

statusIndicator workstationId Detail Section: groupId

Header Version Id Country Code Group Member Media ID (4A:TCID, 6A:blank-future use) Logon User Id Logon Date: Obtain from host at sign on

2 2 4 10 4 8

A A A A A Z

Logon Time: Obtain from host at sign on Message Type(2A:System Code, 3A:Deal code, 5A: blank-future use) Message Version Id (2A:Core Msg Ver, 2A:Local Msg Ver, 6A:blank-future use) first core version:’0100 ‘

6 10

Z A

10

A

Status Indicator(‘N’-Normal, ‘R’-Reject with Error Message, ‘X’- Warning with Exception Message) Logon Workstation Id

1

A

4

A

Group ID

10

A

Page 6

yyyymmd d hhmmss ‘SSCUS MNT ’ First core version: ’0100 ‘

‘DetailS’

Guidelines for Server Side Java Thin Client Development on WSBCC dtlLen

Appendix D

Length of detail session Customer Number (CCGGGGBBBNNNNNN)

5 15

Z A

15

Message Section: groupId

Group Id

10

A

‘ErrMsgR ’

no. of Items no. of chars/line msgId msgLine

Number of items Number of chars per line Message Id Detail Message

5 5 10 80

Z Z Z A

cust

Page 7

Guidelines for Server Side Java Thin Client Development on WSBCC

Appendix E

Appendix E – UML Notation UML Notation for WSBCC This is a suggested interpretation of UML notations for development with WSBCC. It is not designed for automatic generation of XML files (which has to be absolutely unambiguous and syntactically strict) but rather for effective communication between the designer and the programmer (depend to a small extent on developers’ understanding of the framework). 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. Format Diagram - Formats are represented by class. - Format tags are specified as types of the attributes, e.g. , etc. - decorators (e.g. nullCheck or delim) are specified in the initial values. - repeating times and append mode of IColl formats can be specified in the initial value column as well. Context Diagram - Context is represented as a class. - Context HAS a data collection (class). - static context chaining as represented by uni-directional navigable association. Page 1

<> custSearchToCreateJointOutFmt : jointAcctCustList : iColl = times=1 append=true custRecord : lastName : fString = ~ firstName : fString = ~ middleName : fString = ~ partialAddress : fString = ~ countryCode : fSring = ~ groupMember : fString = ~ custNumber : fString = ~ Classification : fString = ~ custStatus : fString = ~ Index : fString = ~ soleJointIndicator : fString = ~ newCustFlag : fString = ~ Title : fString = ~ preferredName : fString = ~ Gender : fString = ~ dateOfBirth : fString = ~ idType : fString = ~ nationalityCode : fString = ~ countryOfResidenceCode : fString = ~ : : :

Guidelines for Server Side Java Thin Client Development on WSBCC -

Appendix E

process/operation context has special stereotype (dseProcCtx / dseOpCtx).

Operation Diagram -

Operation flow described by collaboration diagram Format references of an operation are described by association of operation/op steps to formats. Operation HAS an operation context (by aggregation).

State Diagram (for Process) - State type is described as state stereotypes (e.g. page, operation, subflow) - Initial/Final states are already represented by stereotyped states in Rose (with special circular icons). - special type info is described in the documentation box of the states (e.g. JSP page name). - Mapping formats are specified in transition documentation boxes. - Transition is described in the following syntax: EventName [ condition1(param1, param2 …).TRUE/FALSE && or || more conditions] / actionName(params)

-

event from final states are represented by send event entry action in the final state.

Transition spec Final state event

Page 2

Guidelines for Server Side Java Thin Client Development on WSBCC

Appendix F

Appendix F – WSBCC Self Defined Processor 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>…” 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. For example, “addressProc” is defined within the “customerInfoAddressProc.XML” file. The developer has to defined the “customerInfoAddressProc.XML”, which contains the “addressProc”. : :   : <procDef id="addressProc" value="customerInfoAddressProc.XML" path="c:\dse\server"/> : :

Page 1

Guidelines for Server Side Java Thin Client Development on WSBCC

Appendix G

Appendix G – How to generate XML using dsexml1.doc utility 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. Example on generating data field name: Cust Number ATM Card Number

custNumber atmCardNumber

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. Example on generating type definition: Separator <StringDescriptor id=" Separator " refType="String"/> CustNumber AtmCardNumber Instruction: On the first two rows, type in the separators for prefix and suffix. Then copy the data names that generated in table one and paste them after the separators. Leave the second column empty for these data names. From the “Tools” menu, select “Macro” then “Macros”. A 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" <StringDescriptor id="atmCardNumber"

refType="String"/> refType="String"/>

Example on generating MQ format: Separator CustNumber 12 AtmCardNumber 12 Instruction: On the first three rows, type in the separators for prefix, body and suffix. Then copy the data names that are generated in table one and paste them after separators. Copy the corresponding data field length from Host data definition and paste them on the second column. From the “Tools” menu, select “Macro” then “Macros”. A 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 ------------- Example on generate Map format: Separator <delim delimChar="~"/> custNumber atmCardNumber Instruction: On the first two rows, put down the separators for prefix and suffix. Then type in the data names that are generated in table one and paste them under “Separator”. Leave the second column empty for these data names. From the “Tools” menu, select “Macro” then “Macros”. A 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 ------------- <delim delimChar="~"/> <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

Appendix H - How to apply dummy host for HFE 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. How to generate dummy messages: To generate dummy messages you can use the GeneralEnqDummyMessage.xls file. This file can be found in Team Assist. The GeneralEnqDummyMessage.xls file is composed by three sections: - Header Section - Detail Section - Repeating Section

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. How to use dummy host and dummy message: -

Once the MQMessage.txt file is ready, comment the MQSendAndReplyOpStep operation step and uncomment the DummyMQSendAndReplyOpStep operation step in dseoper:


-

 

id="MQSendAndReplyOpStep"

 

on0Do="next"

Run the application in the same way, as you would do it for a real host

Page 2

onOtherDo="return"/>

 

on1Do="return" 

Guidelines for Server Side Java Thin Client Development on WSBCC

Appendix I

Appendix I – Generic Host Message 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: <SetFieldStringValue dataName="customerInfoData.section.ProdDtlR" value="Y"/> 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. <SetFieldStringValue dataName="customerInfoData.section.ProdDtlR" value="N"/> 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: <setICollSize iCollName="customerInfoData.overviewList" size="1"/> 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. For enquiry generic message: - Mapping from processor context to operation context: ‘customerInfoEnquiryInputMapFmt’ - Mapping from operation context to processor context: ‘customerInfoEnquiryOutputMapFmt’ For maintenance generic message: - Mapping from processor context to operation context: ‘customerInfoMaintenanceInputMapFmt’ - Mapping from operation context to processor context: ‘customerInfoMaintenanceOutputMapFmt’ For uphost MQ message: - Format name is like ‘mqCustomerInfoXXXRepeatItemRequestReplyFmt’ where XXX is the group name. (Example: mqCustomerInfoKeyJtNamesRepeatItemRequestReplyFmt) Note: Since some formats are different for request and reply, some format name may have only ‘RequestFmt’ or ‘ReplyFmt’. -

For the detail part of uphost message: Enquiry: ‘mqCustomerInfoEnqDetailRequestFmt’ Maintenance: ‘mqCustomerInfoMntDetailRequestFmt’

Page 2

Guidelines for Server Side Java Thin Client Development on WSBCC

Appendix J

Appendix J - JetForm Central Service and Debugging hints 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

JetForm central Configuration 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 2. Configure printers by clicking menu and choose File->Job Management Database->Printer

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

4. Make sure the logon ID has the authority to start JetForm service in NT

Page 4

Appendix J

Guidelines for Server Side Java Thin Client Development on WSBCC

Appendix J

5. Make sure that the JetForm service is started in NT 5.1 Go to control Panel and double click service icon 5.2 Highlight the “JetForm Central service” and click start (if the service is not started yet) 6. Start the JetForm Central in Server

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

Example: Sample file 133256.dat ^JOB HFEPRINT ^FORM ACCTOPEN.MDF ^FIELD HOMENAME LOTUS ^FIELD HOMEADDRESSLINE1 ADR ^FIELD HOMEADDRESSLINE2 ….. 1. HFEPRINT should be defined in Jobs definition in JetForm Central. 2. ACCTOPEN.MDF should be found in c:\jfsrver of JetForm Central server. 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

4. Data does not appears as expected in subforms. 1. Make sure all data in form are chopped as subforms. 2. Make sure the field name in key collection for the form are the same as the field name in the form of JetForm designer. 5. Some subforms shows repeatedly as unexpected. Make sure the printed data in the key collection are in the right order. The print agent will print the whole subform when any of the field name of the subform is found during printing.

Page 7

Guidelines for Server Side Java Thin Client Development on WSBCC

Appendix K

Appendix K - Other Tools 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 TeamConnection is a software configuration management tool designed for a team programming environment. It uses IBM's DB2 Universal database and repository technology to maintain the integrity of the development assets. TeamConnection tightly integrates: configuration and library management, version control, process control for change management, build management and support of electronic delivery. It supports application development in a LAN-based client/server team programming environment. In HFE, TeamConnection is being used as a central repository for all XML, JSP, CSS, images, and properties files. 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