Avitek

Medical Records 1.0

Architecture Guide

Copyright 1999, 2000, 2001, 2002 and 2003 BEA Systems, Inc. All Rights Reserved.

Restricted Rights Legend

This software and documentation is subject to and made available only pursuant to the terms of the BEA Systems License Agreement and may be used or copied only in accordance with the terms of that agreement. It is against the law to copy the software except as specifically allowed in the agreement. This document may not, in whole or in part, be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form without prior consent, in writing, from BEA Systems, Inc.

Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the

BEA Systems License Agreement and in subparagraph (c)(1) of the Commercial Computer

Software-Restricted Rights Clause at FAR 52.227-19; subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013, subparagraph (d) of the Commercial Computer Software--Licensing clause at NASA FAR supplement 16-52.227-86; or their equivalent.

Information in this document is subject to change without notice and does not represent a commitment on the part of BEA Systems. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND INCLUDING

WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. FURTHER, BEA Systems DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE, OR THE RESULTS OF THE USE, OF THE SOFTWARE OR WRITTEN MATERIAL IN TERMS OF CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE.

Trademarks or Service Marks:

BEA, WebLogic, Tuxedo, and Jolt are registered trademarks, and How Business Becomes

E-Business, BEA WebLogic E-Business Platform, BEA Builder, BEA eLink, BEA WebLogic Enterprise, BEA WebLogic Express, BEA WebLogic Integration, BEA WebLogic Personalization Server, BEA WebLogic Portal, and BEA WebLogic Server are trademarks of BEA Systems, Inc.

All other product names may be trademarks of the companies with which they are associated.

Table of Contents

1. Architecture Overview. 6

1.1. High-Level Architecture Diagram.. 6

2. Presentation Tier 6

2.1. Design Considerations. 6

2.2. Primary MedRec Client - Web Application. 6

2.3. Web Application Architecture Overview. 6

2.3.1. Model-View-Controller Design Pattern. 7

2.3.2. Struts Framework. 7

2.4. MedRec Web Application Architecture. 7

2.4.1. MedRec Differences From Struts. 7

2.5. Components Defined. 8

2.5.1. JavaServer Pages. 8

2.5.2. JavaBeans. 8

2.5.3. Tag Libraries. 8

2.5.4. Servlets. 9

2.5.5. ServiceLocator 9

2.5.6. Utilities. 9

2.5.7. Properties Files. 9

2.5.8. Configuration Files. 10

2.6. Localization. 10

2.6.1. Resource Files. 10

2.6.2. Character Encoding. 10

2.6.3. Displaying Localized Text 10

2.6.4. Changing Locale. 10

2.7. Exception Handling. 10

2.8. Logging. 10

2.8.1. Changing Logging Level 11

2.8.2. Default Logging Levels. 11

3. Service Tier 11

3.1. Design Considerations. 11

3.2. MedRec Service Tier Architecture. 11

3.3. Components Defined. 11

3.3.1. Value Objects. 11

3.3.2. Session Façades. 12

3.3.3. Entity Enterprise JavaBeans. 12

3.3.3.1. Performance Considerations. 12

3.3.3.1.1. Local Entities. 12

3.3.3.1.1.1. Value Object Usage Explained. 12

3.3.3.1.2. Field Groups. 12

3.3.3.2. WebLogic-EJB-QL. 12

3.3.4. Message-Driven Enterprise JavaBeans. 12

3.3.4.1. Email 13

3.3.4.2. XML Upload. 13

3.3.5. ServiceLocator 13

3.4. Exception Handling. 13

3.4.1. MedRecException. 13

3.4.2. DuplicateAccountException. 13

3.5. Logging. 13

4. Enterprise Information System Tier 13

4.1. PointBase. 13

4.1.1. MedRec Schema. 13

5. Web Services. 13

5.1. MedRec Implementation. 13

5.1.1. MedRec Web Service Delegate. 14

5.1.2. Assembling MedRec Web Service Delegate. 14

5.1.2.1. autotype. 14

5.1.2.2. source2wsdl 14

5.2. Exposed MedRec Functionality as Web Services. 14

5.2.1. Physicians. 14

5.2.2. Corporate Human Resource Registration. 14

6. Security. 14

6.1. MedRec Users. 14

6.1.1. Administrators. 14

6.1.2. Patients. 14

6.2. MedRec Groups. 14

6.2.1. MedRecAdmins. 14

6.2.2. MedRecPatients. 14

6.3. MedRec Roles. 15

6.3.1. MedRecAdmin. 15

6.3.2. MedRecPatient 15

6.4. Security Realm.. 15

6.4.1. Authentication. 15

6.4.1.1. WebLogic Authentication Provider 15

6.4.1.2. MedRec Sample Authentication Provider 15

6.4.1.3. Authentication Provider Configuration. 15

6.4.1.3.1. MedRec Configuration. 15

6.4.2. Authorization. 16

6.4.2.1. MedRec Implementation. 16

1. Architecture Overview

The Avitek Medical Records sample application (MedRec) is designed and implemented following the traditional three tier architecture model in which the client, server and datastore are independent from one another:

- Presentation Tier: The Presentation Tier is responsible for all user interaction; it is sometimes referred to as the Client Tier.
- Service Tier: The Service Tier is the middle tier that encapsulates the application’s business logic. The Service Tier processes requests from heterogeneous clients while interfacing with various backend systems including datastores. This tier is sometimes referred to as the Server Tier.
- Enterprise Information System (EIS) Tier: The Enterprise Information System Tier represents those systems that provide and/or store data such as legacy applications and databases. The EIS Tier is sometimes referred to as the datastore.

The sections that follow describe each tier in more detail.

1.1. High-Level Architecture Diagram

The following is a Visio document provides a high-level diagram of MedRec’s application architecture:

MedRec Arch Overview Diagram (Requires Microsoft Visio Viewer)

The following table contains high-level diagrams for each application that makes up MedRec.

Table 1 High-Level Sub-system Diagrams (Requires Microsoft Visio Viewer)

Diagram | Description
Admin Arch Overview Diagram | Shows the interaction of components in the administration application of MedRec.
Patient Arch Overview Diagram | Shows the interaction of components in the patient application of MedRec.
Physician Arch Overview Diagram | Shows the interaction of components in the physician application of MedRec.

2. Presentation Tier

The Presentation Tier is responsible for gathering and displaying application data, and provides the overall user experience for the MedRec application.

2.1. Design Considerations

This section outlines design considerations for MedRec’s Presentation Tier architecture. These objectives are the basis for all Presentation Tier design decisions:

Scalable

The most important design consideration for the Presentation Tier is that it be robust enough to handle high volumes of simultaneous requests. At the same time, the Presentation Tier must be small in size to manage resource usage.

Extendable, yet maintainable

The design of the Presentation Tier must allow for extensibility, while not compromising maintainability. This requires that the tier be modular so that changes can be made to a particular component or set of components without having to modify other parts of the application that are irrelevant to the desired functionality. In addition, creating new presentation features must be a pluggable exercise where new components are easily incorporated without changing the foundation or peer components.

Minimize application interdependence

The Presentation Tier must be designed so that inter-tier communication is limited only to the necessities. Similar to the Extendable yet maintainable objective, tier partitioning is crucial so that changes to dependent tiers are contained and do not have widespread influence.

2.2. Primary MedRec Client - Web Application

The Presentation Tier consists of several different clients, each with their unique set of users and usage scenarios. The Presentation Tier must provide avenues to the MedRec application in order to serve these demands.

The first version of MedRec focuses on a HTML-based client. Users make HTTP requests to, and interpret responses from, the Presentation Tier using a browser. This type of client is commonly referred to as a Web Application or webapp.

MedRec consists of two different Web Applications: one that provides MedRec administration controls and one that provides controls for MedRec’s patient users.

2.3. Web Application Architecture Overview

In order to meet the architectural design requirements, a Web Application framework is used to logically combine common Presentation Tier functionality into components. These components are the building blocks for the application.

The following section explains proven Web Application design concepts and introduces the framework called Struts, on which all of the MedRec Web Applications are developed.

2.3.1. Model-View-Controller Design Pattern

The Presentation Tier follows the Model-View-Controller (MVC) Model 2 paradigm. The MVC paradigm organizes the application’s presentation layer into segregated components that work together to provide interactive web functionality. In the MVC paradigm:

· The Model represents the information gathered and presented to the user. Information is encapsulated into data representations of entities and passed from component to component.

· The View is responsible for presenting and capturing data to and from the user.

· The Controller processes incoming requests and coordinates the flow of presentation.

For J2EE implementations, MVC is applied using JavaBeans as the Models, JavaServer Pages as the Views, and Java Servlets as the Controllers. JavaBeans are standard Java objects with attributes representing logical aggregations of data that is captured or displayed within JavaServer Pages. JavaServer Pages contain HyperText Markup Language (HTML) with embedded Java code. The HTML provides the page layout, and the Java provides the processing that is required to present the data contained in JavaBeans.

Upon submittal, the JSP dispatches the request, including JavaBeans, to a Servlet. The Servlet processes the request inside WebLogic Server, determining what is done and what backend services are called. The Servlet then passes control to the next JSP or Servlet.

For more information about Model-View-Controller, see Sun’s Web-Tier Application Framework Design.

2.3.2. Struts Framework

Struts is an open source web framework developed by Jakarta. Struts provides a foundation on which Web Applications can be built. The foundation includes an extensive number of classes, interfaces and protocols from which application-specific logic extends. Struts hides the complexity a web application by abstracting component definition and interaction to an XML based configuration file.

In Struts, Controllers are called Actions and inherit from a single Action class. This Action class processes the incoming request and redirects it to the appropriate custom Action mapped in Struts’ configuration file. Struts defines Views as standard JavaServer Pages and Models as JavaBeans that inherit from Struts’ Form Bean.

For more information see Struts.

2.4. MedRec Web Application Architecture

MedRec’s Web Applications are developed using the Struts framework. The first iteration of MedRec, MedRec 1.0 will be built upon Struts 1.0. The following section discusses the architectural details of MedRec’s Web Application framework.

MedRec Web Applications consist of the standard web components. JavaServer Pages (JSPs) are used to gather and present information. Standard HTML forms are used to submit information to Java Servlets, or Actions, who are responsible for a logical grouping of functionality such as:

· Registering a user

· Creating a medical record

· Viewing medical records

Upon submitting a form, JSP tags and Struts intelligence populate JavaBeans with the gathered information and attach the objects to the request before sending the request to the Action.

When information is passed to the Action for processing, the Action asks the JavaBean to validate itself. The JavaBean performs validation specific to its attributes, and, if applicable, populates error fields with the appropriate error messages. If errors are found, the Action passes the JavaBean to the appropriate JSP where error message are rendered.

If the JavaBean is valid, the Action will handle the Service Tier interaction, the processing of the JavaBean, and the presentation’s flow.

See the MedRec-Struts Impl Diagram (requires Microsoft Visio Viewer) for an abbreviated MedRec implementation diagram of Struts.

2.4.1. MedRec Differences From Struts

MedRec implements MVC Model 2 using Jakarta’s Struts, but diverges from the traditional approach in two key areas.

· MedRec’s implementation of Struts maintains Web Tier to Service Tier communication in the Controller. Model components are limited to encapsulating data structures and surface-level validation. The traditional approach is where the Model is responsible for business service logic as well as data encapsulation.

· Encapsulated data returned from the Service Tier is aggregated and/or reorganized into objects that represent the information presented and/or gathered from the user. This is different from the traditional approach where objects obtained from the Service Tier are carried to the presentation view.

These differences in approach are consistent with the goal to decouple Model components from the Service Tier and to centralize complexity in Controller components. This approach focuses the Model on the data and its particulars rather than its flow. Because the Controller is the natural leader in the MVC paradigm, it is logical that the component should take on the responsibility of layer communication.

2.5. Components Defined

The following section discusses the responsibilities of each component that makes up the Web Application.

2.5.1. JavaServer Pages

JavaServer Pages (JSP) consist of HTML with embedded Java code. Java code is solely responsible for creating and rendering data from and into JavaBeans. Business logic is not implemented within JSPs.

One of the underlining goals of JSP development is to efficiently segregate logical code from presentation code. Where appropriate, Java code (typically tag library functions) and HTML code are intermingled to provide functionality needed to logically gather and present application data.

Each JSP obtains application messages from a localized resource component. For further information see Localization below.

JSPs are not accessed directly. All flow in and out of JSPs is controlled by Actions.

For more information see JavaServer Pages and Programming WebLogic JSP.

2.5.2. JavaBeans

JavaBeans or Presentation Beans are standard Java objects that encapsulate all attributes gathered from or displayed within a JSP. These objects are also responsible for validating their data structure.

JavaBeans are specific to the Web Application. Data structures obtained from the Service Tier, called Value Objects, are transformed into one or more JavaBeans to be presented in a JSP. Similarly, JavaBeans containing captured user data are transformed into one or more Value Objects that aare passed to the Service Tier. These transformations are handled within the JavaBeans themselves.

All JavaBean attributes are of type java.lang.String in order to simplify presentation in JSPs. This is different from Value Objects where attributes are specific to their type (i.e., date is a java Date data type). These conversions are handled within the JavaBeans.

JavaBeans that require validation contain methods that check their data values for invalid information. Validation is limited to the existence of the value and the matching of expected data patterns. If an attribute is deemed invalid, a localized application resource provides the appropriate error message to be stored within an error mapping class, ActionErrors. Validation helper methods specific to the JavaBeans structure are local to the JavaBean. Common validation helper methods are provided in the BaseBean.

All beans extend the BaseBean object containing common attributes and helper functionality. The BaseBean extends org.apache.struts.action.ActionForm, which is used by Struts to perform callback validation.

See JavaBeans and Using JavaBeans in JSP for more information.

2.5.3. Tag Libraries

Tag Libraries are packages of Java classes that encapsulate core functionality common to JSPs. These classes are then used as tags within JSPs.

Tag libraries not only provide common functionality, but also are beneficial to separating Java code from HTML code. The clear division of Java and HTML improves the maintenance of JSPs.

Table 2 outlines the tag libraries used by MedRec Web Applications.

Table 2 MedRec Tag Libraries

Tag Name | Description
Bean | Struts library containing tags useful in accessing beans and their properties, as well as defining new beans that are accessible to the remainder of the page via scripting variables and page scope attributes.
HTML | Struts library containing tags used to create input forms, as well as other tags generally useful in the creation of HTML-based user interfaces.
Logic | Struts library containing tags that are useful in managing conditional generation of output text, looping over object collections for repetitive generation of output text, and application flow management.

For more information see Tag Libraries, Struts User Guide and Programming WebLogic JSP.

2.5.4. Servlets

Servlets, or Actions, are the central Controllers of the webapp. All requests from the web server or from proxy layers are processed by Actions. Action modules are separated by application tasks. For example, all client registration functionality is handled by a single Action called Register. Actions are primarily made up of controller logic that acts on JavaBeans obtained from requests. JavaBeans are asked to validate themselves and, based on discovery, are either passed as Value Objects to the Service Tier for business logic processing or returned to the presentation view for client re-evaluation.

Each Action extends BaseAction or BaseLookupDispatchAction depending on the chosen behavior of the child Action: BaseAction is used for plain vanilla Actions, and BaseLookupDispatchAction is used for handling multiple submits from a single JSP. Both base components encapsulate intercepting responsibilities as well as common functionality like session management, locale management, resource lookup and error handling.

The BaseAction extends org.apache.struts.action.Action. BaseLookupDispatchAction extends org.apache.struts.actions.LookupDispatchAction. Struts’ Action class acts as the proxy between requests and the application logic executed in extended Actions. All URL requests with the extension “*.do” are mapped to this Action class as defined in each Web Application’s web.xml descriptor. The Action class dissects the request and determines further processing through mappings in Struts’ configuration file, struts-config.xml. For example, a request to “Login.do” is mapped to the LoginAction where login functionality is maintained. For more information on Actions and Struts Configuration, see the Struts User Guide.

All JSPs are serviced by Actions. JSPs are not accessed directly. All flow in and out of JSPs is controlled by Actions.

For more information, see Java Servlets Technology, Struts User Guide and Programming WebLogic HTTP Servlets.

2.5.5. ServiceLocator

The ServiceLocator is responsible for looking up services available in the Service Tier. This includes handles to EJBs, JMS queues, and JDBC connection pools. The ServiceLocator is a single point of access to service handles. This abstraction provides a uniform mechanism for service lookup. The ServiceLocator may also cache services to improve performance.

See Service Locator for more information.

2.5.6. Utilities

Actions and JavaBeans use utility classes to perform common functionality.

Table 3 outlines utility modules used in MedRec’s Web Applications.

Table 3 MedRec Web Application Utilities

Name | Description
BeanHelper | Provides conversion functionality for arrays and java.util.Collections of JavaBean to Value Object and vice versa.
JNDINames | Provides constants values for service names.
MedRecWebAppUtilities | Provides various presentation functions such as date formatting and java.lang.String validation and manipulation.
MedRecMessageProperties | Provides access to MedRec messages within localized properties files.

2.5.7. Properties Files

Properties files are simple text files containing name-value pairs. Based on a name, values are retrieved and displayed to the user or are used to configure a resource within the application.

Table 4 outlines properties files used within MedRec’s Web Applications.

Table 4 MedRec Web Application Property Files

Name | Description
log4j.properties | Configuration for Log4J logging mechanism. The property file is initialized within a preloaded Servlet, Log4Init.
ApplicationResources.properties | Contains presentation titles, text tags and error messages. There is an ApplicationResources properties file for each locale.

2.5.8. Configuration Files

Configuration files are XML-based files used to define the behavior of resources in an application.

Table 5 summarizes configuration files used with MedRec’s Web Applications.

Table 5 MedRec Web Application Utilities Configuration Files

Name | Description
web.xml | The Servlet deployment descriptor defines components in the web application including Servlet deployment, tag libraries, context parameters, URL mapping, and login configuration. For more information, see the XML DTD for the Servlet 2.3.
weblogic.xml | The WebLogic Web Application deployment descriptor contains WebLogic Server-specific configuration attributes that define security, and HttpSession and JSP parameters. For more information, see weblogic.xml.
struts-config.xml | The Struts configuration file defines Web Application components and their relationships. Components include Form beans, Action Servlets, and dispatch mapping. See Struts Configuration File for more information on Struts’ configuration file.

2.6. Localization

MedRec Web Applications use the Struts localization framework to display internationalized content. MedRec is initially localized for English and Japanese.

2.6.1. Resource Files

Before localizing MedRec, the content of the Web Applications is internationalized. This is done by developing the Web Application in English and then translating the content to other languages. Web Application content is maintained within application resource files. There is a resource file for each supported language.

2.6.2. Character Encoding

All flow in and out of the Web Applications is encoded with UTF-8 (Unicode Transformation Format, 8 bit form) character encoding. To encode input as UTF-8, an encoding filter is employed to intercept all requests from clients and responses to a client. The encoding filter’s sole responsibility is to set the character encoding to UTF-8.

2.6.3. Displaying Localized Text

To instruct Struts to use the resource properties files (see Properties Files above), JSPs must contain <html:html locale="true">. When Struts encounters a <bean:message> tag, based on a key value the localized text is retrieved for the locale of the user. If the locale is unknown, then the browser’s default locale is used.

2.6.4. Changing Locale

The locale can be changed using a link on MedRec’s start page. When changed, the locale is stored in the user’s HttpSession and also written to a cookie for future locale lookups.

For more information on Struts localization, see Internationalized Messages.

2.7. Exception Handling

All exceptions that occur within a Web Application or that are obtained from the Service Tier are captured and re-thrown as client exceptions. Client exceptions contain the originating exception and a link for post-error navigation. Client exceptions may also contain additional information such as details on what might have occurred or general instructions on how to recover from a problem. Client exceptions, in addition to all other exceptions that occur in the Web Application framework, are captured within the Web Application’s base classes and transformed into Java error classes. The error class is then passed to the common error action class that uniformly displays the error message and link.

2.8. Logging

MedRec employs Log4j as the application-wide logging mechanism. Logging is configured within the log4j.properties file located in the root of the MedRec WLS domain directory. This file is read in through the Log4jInit class which is loaded upon webapp startup. The logging levels are controlled by package names in log4j.properties (see "log4j.category.*"). In each class you get an instance of log4j's Logger class. From there you use log4j's logging methods to determine when and how a particular string is logged.

2.8.1. Changing Logging Level

To change the logging levels, edit log4j.properties to set the package category to the desired logging level: FATAL, ERROR, WARN, INFO or DEBUG. Then redeploy the Web Application.

2.8.2. Default Logging Levels

The following are the default logging levels:

· log4j.category.org.apache.struts=WARN

· log4j.category.org.apache.commons.logging=WARN

· log4j.category.com.bea.medrec=INFO

See Log4j Project for more information on Log4j.

3. Service Tier

The Service Tier is the engine of the application, responsible for MedRec’s business logic. This tier receives requests from clients such as the Presentation Tier, or from external clients such as Web Services. The Service Tier processes requests by applying business-specific logic and interacting with the Enterprise Information System Tier to store or receive data. The Service Tier may also return information to the calling client to complete the work cycle. The Service Tier may also communicate with other applications by passing a request for asynchronous processing consumption.

3.1. Design Considerations

The following section outlines design considerations for MedRec’s Service Tier architecture. These objectives are the basis for all Service Tier design decisions

Scalable

The Service Tier’s major design consideration is that MedRec must be able to handle high volumes of simultaneous requests from numerous clients. At the same time, the Service Tier must be small in size in order to manage resource usage.

Accommodating

The Service Tier is accommodating to heterogeneous clients such as Java clients, XML-based clients, proprietary handheld devices, and .NET clients. The nature of MedRec is to interface with many types of users and many types of external systems. Each user and each system has different needs that must be addressed.

Extensible and modular

The Service Tier is designed so that each component’s responsibilities and duties are clearly defined. For example, business logic is contained within exclusive components called Session Facades. Similarly, service lookups like EJB Homes and JMS Topics are contained in a common factory component. This practice facilitates maintenance and allows for application growth.

Minimize application interdependence

The Service Tier is designed so that inter-tier communication is limited only to the necessities. Tier partitioning is important so that changes to dependent tiers are contained and do not have widespread influence. For example, the Service Tier is loosely tied to the Enterprise Information System Tier in the event that the data storage vendor changes.

3.2. MedRec Service Tier Architecture

MedRec’s Service Tier is primarily made of Enterprise JavaBeans (EJBs) that work together to process requests from Web Applications, Web Services, workflow applications, and future client applications. At the heart of the Service Tier are Stateless Session EJBs that encapsulate much of the MedRec’s business logic. These Stateless Session Beans are referred to as Session Facades, and they process all incoming requests. Session Facades interact with Container Managed Entity EJBs, other Stateless Session EJBs, Java Messaging Services, and helper modules in order to complete the work.

All MedRec EJBs are based on the EJB 2.0 specification.

3.3. Components Defined

The following section discusses the responsibilities of each component involved with the Service Tier.

3.3.1. Value Objects

Value Objects (VOs) encapsulate a set of related data that is passed from one tier to another. Value Objects are standard Java classes with attributes and getter and setter methods for each attribute. Typically, Value Objects are mapped one-to-one to Entity Beans.

Within MedRec, Entity EJBs retrieve information from the Enterprise Information System Tier and transform themselves into Value Objects that are consumed by other components. Similarly, data captured in the client tiers are transformed into Value Objects and passed to the Service Tier for consumption. These conversions allow different clients to communicate with the Service Tier. See Entity JavaBeans below for more information.

All Value Objects extend the Base Value Object class that contains common attributes and methods.

For more information, see Value Object.

3.3.2. Session Façades

Session Facades are Stateless Session EJBs containing the business logic of the Service Tier. Business logic includes medical record-related business and system rules that are applied to requests, as well as application logic like awareness of components in the system. In addition to applying business logic, the primary goal of Session Facades is to further separate tier responsibilities and minimize interdependence.

To process a request, Session Facades interact with other Service Tier components such as Value Objects, Entity EJBs, Messaging, and other J2EE services. This aggregation of control is contained within Session Facades to alleviate complex transactions. Client programs interface with one component, the Session Façade, rather than managing a number of contracts.

Typically Sessions Facades are mapped one-to-one with use cases. In MedRec, Sessions Facades are derived by grouping common functionality for each actor in the system. For example, the Admin Session Façade contains functionality common to the duties of administering MedRec (for example, approving Patient registration requests and uploading incoming medical records).

For more information, see Session Façade and Programming WebLogic Enterprise JavaBeans.

3.3.3. Entity Enterprise JavaBeans

The Service Tier uses Container Managed Persistence Entity Enterprise JavaBeans to manipulate data stored in a database located in the Enterprise Information System Tier.

All Entity EJB access is governed by Session Facades. In other words, Entity EJBs must go through Session Facades in order to obtain application data. This design is consistent with the principal of centralized responsibility.

3.3.3.1. Performance Considerations

The following section outlines EJB features that will be employed in order to improve overall EJB performance.

3.3.3.1.1. Local Entities

MedRec Entity EJBs implement local EJB interfaces and are deployed without exposing the JNDI tree. Local EJBs are called by reference, thus eliminating expensive remote invocation calls. This feature allows the Service Tier to pass Entity EJB references back to clients in the same Java Virtual Machine (JVM).

3.3.3.1.1.1. Value Object Usage Explained

To meet MedRec’s tier independence and accommodating design considerations, local EJBs are used only to a point. The Service Tier must rarely couple itself with other tiers, and it must also be able to accommodate calling clients who may or may not be within the same JVM.

For example, Web Applications deployed within the same WebLogic instance may use local EJBs. However, for proprietary systems outside this WebLogic instance (such as handheld devices) local EJBs may not be used. Because of the need to accommodate different client types, a common, standard data delivery mechanism, Value Objects, is used. All Entity EJBs provide the capability to transform their attributes in a Value Object.

3.3.3.1.2. Field Groups

Often a client is interested only in a subset of data that an Entity EJB provides. Field groups are used to return just the attributes that are required. Within an Entity EJBs descriptor, field groups are defined and associated with a particular finder method. When this finder method is called, the container understands that only a subset of attributes should be retrieved. This is particularly beneficial when an Entity EJB has relationships that are irrelevant to a calling client.

3.3.3.2. WebLogic-EJB-QL

Finder methods are defined using EJB-QL, but WebLogic-EJB-QL is used in order to utilize common SQL features not implemented in EJB 2.0. Specifically, WebLogic-EJB-QL ORDERBY is used where data retrieved in a collection of Entity EJBs is sorted by a set of desired attributes.

For more information, see Programming WebLogic Enterprise JavaBeans.

3.3.4. Message-Driven Enterprise JavaBeans

The Service Tier employs Message-Driven EJBs (MDBs) to handle asynchronous workloads. MDBs provide significant benefit where it is important to provide reliable processing without involving the client.

This section outlines MedRec’s usage of MDBs where functionality is designed to takes advantage of MDBs’ capability to provide reliable handling of large volumes of transactions.

3.3.4.1. Email

MedRec uses MDBs to handle all email transmissions. Mail messages are placed on a JMS queue where an MDB ensures the delivery of the email.

3.3.4.2. XML Upload

An MDB uploads incoming XML medical records. Instead of having a client-driven process that is responsible for transforming XML documents, MedRec’s process is divided among logical work units. First, a client parses the XML document into Value Objects. Then the client passes components to a queue where an MBD is responsible for storing the elements.

For more information, see Programming WebLogic Enterprise JavaBeans.

3.3.5. ServiceLocator

The ServiceLocator is responsible for looking up services available in the Service Tier. This includes handles to EJBs, JMS queues, and JDBC connection pools. The ServiceLocator is a single point of access to service handles. This abstraction provides a uniform protocol for service lookups. The ServiceLocator may also caches services to improve performance.

3.4. Exception Handling

All exceptions that occur within the Service Tier are logged and thrown back to the calling client. There are two types of business exceptions in the Service Tier.

3.4.1. MedRecException

MedRecException is the Service Tier’s business exception. This exception occurs when application data or behavior is found to be in violation of business rules embedded in the application logic.

3.4.2. DuplicateAccountException

This exception occurs when an existing users is registering.

3.5. Logging

The Service Tier uses Log4j as its logging mechanism. The Service Tier inherits Log4j configuration from the Web Application. See section 2.8 for more information.

4. Enterprise Information System Tier

The MedRec Enterprise Information System Tier is made up of a relational database management system. This tier could also refer to legacy systems or Web Services.

4.1. PointBase

MedRec application data is maintained in PointBase, a platform-independent, embedded relational database written in Java. PointBase is shipped with WebLogic Server.

For more information on PointBase, see PointBase.

4.1.1. MedRec Schema

WebLogic Server ships a sample PointBase database called DEMO. The MedRec schema exists within this database.

5. Web Services

Because of the nature of the medical industry, MedRec must be capable of interfacing with multiple medical institutions and delivering accurate and timely information to diverse, heterogeneous clients. To satisfy this complex requirement, Web services is used as a standard mechanism for exposing MedRec functionality.

Web services are Web-based applications that dynamically interact with other Web-based applications using open standards including XML, HTTP, and SOAP. Essentially, Service Tier components are exposed to the public via the Internet. Through a published URL, a service’s description and communication information (such as inputs and outputs) are defined.

For more information, see WebLogic Server: Web Services.

5.1. MedRec Implementation

In order to meet the needs of MedRec users, specific MedRec functionality is exposed through a Web Service delegate.

5.1.1. MedRec Web Service Delegate

The MedRec Web Service delegate is an EJB. The EJB delegate provides a level of abstraction from the internals of the Service Tier. This separation supports MedRec’s design objective of modularity where, changes made to a service have minimal impact to the calling components. In addition, the Web Service delegate can take advantage of EJB features such as security, transactions and other container-provided benefits.

5.1.2. Assembling MedRec Web Service Delegate

The MedRec Web Service delegate EJB is assembled into a Web Service. MedRec does so using the WebLogic Ant tasks.

See Assembling WebLogic Web Services Using Ant Tasks for more information.

5.1.2.1. autotype

To assemble the Web Service, autotype Ant task first converts non-built-in data types to equivalent XML schema data types so that Web Service runtimes can communicate structures to the client.

5.1.2.2. source2wsdl

The source2wsdl Ant task then generates the Web Service configuration file, web-services.xml.

5.2. Exposed MedRec Functionality as Web Services

Service Tier functionality is exposed in the EJB delegate based on the needs of MedRec users.

5.2.1. Physicians

MedRec patient information must be made available to medical institution applications such as physician offices. MedRec allows the physician application to search for patients, retrieve patient profiles and medical history, and record visit information such as diagnoses and medical prescriptions.

5.2.2. Corporate Human Resource Registration

MedRec also exposes the ability to register new patients. This functionality is useful to corporate human resource departments that wish to provide extra benefits to their employees.

6. Security

MedRec security takes advantage of the WebLogic Server security framework. MedRec Administrators are managed using WebLogic Server’s default security configuration. MedRec Patients are managed using a custom Authentication provider in conjunction with WebLogic Server’s default security configuration. Both the MedRec Administration and Patient websites are constrained using URL pattern matching.

For more information, see WebLogic Security.

6.1. MedRec Users

There are two types of users that MedRec maintains: administrators and patients. The following sections outline each user.

6.1.1. Administrators

MedRec administrator users are maintained in and managed by WebLogic’s default security configuration. Usernames, groups, and roles are stored within WebLogic’s embedded LDAP server, and are viewed, created, updated and deleted using the WebLogic Server Administration Console.

6.1.2. Patients

MedRec patient users are maintained in series of tables inside the relational database management system. Patient login credentials, profile, and group associations are stored in a relational database. Patient roles and their group associations are stored in WebLogic Server’s embedded LDAP server. The two sets of data are linked by a common group name stored in both the RDBMS and LDAP.

6.2. MedRec Groups

MedRec uses two types of groups – MedRecAdmins and MedRecPatients. The following sections outline each group.

6.2.1. MedRecAdmins

MedRec Administrators are assigned to the MedRecAdmins group. The MedRecAdmins group exists within WebLogic Server’s embedded LDAP server, and is assigned to users in WebLogic’s default security configuration.

6.2.2. MedRecPatients

MedRec Patient users are assigned to the MedRecPatients group. Patient group associations are maintained in the relational database. The MedRecPatients group also exists in WebLogic Server’s embedded LDAP server. The MedRecPatients group associates MedRec Patient information located in the RDBMS with MedRec’s WebLogic Server security configuration.

6.3. MedRec Roles

MedRec uses two types of roles – MedRecAdmin and MedRecPatient. The following sections outline each role.

6.3.1. MedRecAdmin

MedRec administration resources are constrained using the MedRecAdmin role. This role is assigned exclusively to the MedRecAdmins group. Users associated with the MedRecAdmins group are assigned the MedRecAdmin role.

6.3.2. MedRecPatient

MedRec patient resources are constrained using the MedRecPatient role. This role is assigned exclusively to the MedRecPatients group. Users associated with the MedRecPatients group are assigned the MedRecAdmin role.

6.4. Security Realm

The following section outline MedRec’s security configuration.

6.4.1. Authentication

Authentication is the process whereby the identity of clients, users or system processes, is proved or verified. The WebLogic Security Framework, together with the Java Authentication and Authorization Service (JAAS) classes, reliably and securely authenticate clients.

Authentication providers are central to this framework. Authentication providers are the mechanisms that remember, transport, and make that identity information available to various components of a system when needed. MedRec uses two Authentication providers: the WebLogic Authentication provider, and a custom MedRec Sample Authentication provider.

See JAAS and WebLogic Authentication for more information on J2EE and WebLogic authentication, respectively.

6.4.1.1. WebLogic Authentication Provider

The WebLogic Authentication provider manages MedRec Administrators, their groups, and group memberships. The WebLogic Administration Console calls the provider (referred to as the Default Authenticator) through the WebLogic Security Framework to create, view, update and delete users and groups that are stored in the embedded LDAP server. The framework also calls upon this provider when client authentication requests are made. By default, the WebLogic Authentication provider is configured out-of-the-box.

For more information about the WebLogic Server Default Authentication Provider, see Managing WebLogic Security and WebLogic Security Providers.

6.4.1.2. MedRec Sample Authentication Provider

The MedRec Sample Authentication provider is a custom provider that implements the Security Service Provider Interface. This standard interface allows custom providers to be integrated with the WebLogic Security Framework. The MedRec Sample Authentication Provider consists of a managed bean (MBean), LoginModule and database delegate. When client authentication requests are made, these components, in conjunction with the security framework, work together to obtain, validate, and store login credentials and group memberships.

The MedRec Sample Authentication provider obtains Patient users and their group memberships stored in the relational database. Storing Patient information outside of LDAP allows the application to take advantage of the flexibility and power of a database management system. Maintaining a relationship between Patient relational data and Patient LDAP data (roles) allows MedRec to take advantage of WebLogic’s security framework.

For more information on custom providers, see Developing Security Providers for WebLogic Server.

6.4.1.3. Authentication Provider Configuration

Authentication providers are configured through the WebLogic Administration Console by setting the Authentication Re-Ordering and the Control Flag for each provider. Each Authentication provider’s Control Flag is set to SUFFICIENT. SUFFICIENT indicates that if a provider succeeds, the authentication process is concluded.

6.4.1.3.1. MedRec Configuration

When an authentication request is made, the Default Authentication provider is called first to validate a user’s existence and login credentials. If the user is not found, the framework next uses the MedRec Sample Authentication provider to validate a user’s existence and login credentials. If the user is not found in any of the configured providers, authentication fails. If the user is found, the security framework does not continue to the next provider.

See JAAS Control Flags for more information about login sequence configuration.

6.4.2. Authorization

Authorization is the process whereby the interactions between users and WebLogic resources are controlled, based on user identity or other information. In WebLogic Server, an Authorization provider is used to manage the interactions between users and WebLogic resources to ensure integrity, confidentiality, and availability.

A WebLogic resource is a structured object used to represent an underlying WebLogic Server entity. A WebLogic resource can be protected from unauthorized access by using security roles and policies. Security policies are stored in an Authorization provider's database. By default, the WebLogic Authorization provider is configured and security policies are stored in the embedded LDAP server.

6.4.2.1. MedRec Implementation

When a client authentication request is made, the user’s login credentials and group memberships are stored. When a secured WebLogic resource is accessed, the security framework gathers the roles associated with the user’s groups and determines authorization based on these roles.

MedRec security is applied to the Administration and Patient Web Applications using the URL resource component. This component applies security policies to URL patterns. All HTTP requests are evaluated for matching URL patterns. If a pattern is secured by a policy, the framework determines if the requesting user has authorization.

For more information on WebLogic resources, see Types of WebLogic Resources.