2 Design Recommendations

Use Version-Aware References

Oracle recommends the use of version aware references wherever feasible to avoid issues associated with version agnostic references.

Oracle Healthcare Data Repository lets you update existing objects without prior retrieval if the object id is known. HDR can also create an object if it does not exist, or do nothing or update it if it does. While useful, careless use of these features may result in corrupt data, and technology limitations may cause further unexpected errors. These concepts also apply to messaging side effects because they use version agnostic references internally.

References are created by the makeReference method of the Act, Role, and Entity factories. References may be version aware or version agnostic. Version aware references are created by specifying the version number of the object being referenced when creating the reference, and only apply the updates to the version of the object specified. If that version is not the latest one an error occurs. Version agnostic references have no version specified and thus always apply to the latest version of the object, but note that there are problems in HDR with the implementation of version agnostic references.

My Oracle Support article XXXXXXXXX.1 identifies strategies for properly handling the concurrent update of information as well as strategies for dealing with errors that may sometime occur.

Follow J2EE Best Practices

HDR is based on Java 2 Enterprise Edition (J2EE). J2EE is an established family of technologies with a substantial amount of published reference information. You should leverage this information when designing your applications.

This provides two important benefits. First, it lets programmers easily compare the performance implications for using remote or local mode in their applications. Second, it can speed development in situations where programmers share an HDR instance. With a shared instance, programmers can develop and test their components in remote mode, letting each work within separate containers, while sharing a common HDR instance running in its own container. It would be better for each developer to have a separate HDR instance, but this is not always possible.

Note:

  • Oracle Technology Network, OTN, includes information describing good use of the Application Server, particularly the J2EE Design Pattern Samples
  • Sun Microsystems Enterprise BluePrints also provide valuable information

It is particularly important that you minimize the number of round-trips required by your application. HDR provides a number of mechanisms to assist with this, such as the bulk retrieval capabilities of the Rim Service.

Choose an Appropriate Deployment Model

HDR supports access to its services through local and remote EJBs. In remote mode, HDR runs in its own application server instance and client code communicates with it through RMI. In local mode, HDR and the client code are co-located on the same application server. Selection of the appropriate deployment model depends on the requirements of your application.

HDR hides the differences between the two deployment modes—thus permitting the same code to be executed largely without change in either mode (although some minor changes are required to set the mode to local.

For production purposes, the choice comes down to a balance between performance and flexibility. Accessing HDR in local mode performs better than remote mode in terms of throughput and latency. However, local deployment requires your application code to be co-located on the same application server. For many Web based applications, this may be acceptable, but there are other applications (such as rich clients) where this is not possible. In such cases, remote deployment may be preferable.

However, the choice between local and remote access is not absolute. HDR exposes all of its services as remote and local EJBs. In this way, it is possible to interact with HDR in different modes from within the same application. For example, you could split your business logic between a rich client-tier application in remote mode, and a customer middle-tier session bean in local mode, both of which could access HDR.

Package Custom Server-side Code in its Own EAR File

Client code that accesses HDR in local mode should be packaged into its own EAR file, and appropriate deployment options configured to connect the client code's EAR file to the HDR EAR file. You should never extract and add your own code to the HDR EAR file.

Design Your Own Business Level Services on Top of HDR

HDR supports a wide variety of applications, from message processing to patient admissions GUIs. It is therefore necessarily generic. For applications that are more specific, we recommend that you develop your own interfaces that encapsulate the business logic of your application. In doing so, you should consider the following:

  • HL7's RIM Objects (and by extension HDR's objects) are very generic and may provide fields and cardinalities that are of no relevance to your application. In such cases, defining your own simplified versions of RIM Objects may significantly reduce the complexity and increase the usability of your API.

  • Be careful of API granularity. If it is too fine-grained, it may require your code to make an excessive number of calls, eroding performance; if it is too coarse, it may be difficult to build on.

  • Use stateless rather than stateful designs. Stateless designs (where all necessary information is supplied to a service) are typically more scalable than stateful designs.

Design Your Own Domain Model to Take Full Advantage of GUI Frameworks

Current generation GUI frameworks such as Oracle's ADF provide excellent support for connecting GUI views and controllers with simple models based on Java Beans, and standard Java types such as String and BigDecimal.

HDR's RIM Objects use classes that implement the HL7 abstract data type specification. These data types are not JavaBeans and cannot be used directly by GUI frameworks without writing conversion routines. Because HDR RIM Objects are defined in terms of RIM Datatypes this also precludes their direct use by many GUI frameworks.

An obvious solution to this problem is to write the appropriate conversion utilities. The details describing how to do this vary from one GUI framework to another. This approach therefore has the potential to tie your application to a particular GUI framework, although you avoid the overhead of creating your own model.

An alternative approach is to convert HDR Objects into JavaBeans that are defined in terms of other JavaBeans and standard Java types. This framework-friendly model could then be used with any GUI framework that supports JavaBean components for its model. This model does not require a 1:1 mapping with the RIM; it might well represent a simplified model used by your business interfaces.

All things being equal, we recommend taking the second approach. Defining your own domain model using JavaBeans lets your business logic layer be more easily ported from one GUI framework to another, and you will have a ready made, simplified set of objects to pass to your business interfaces.

Consider Threading Issues

HDR's client-side components are not synchronized and are intended for use by one thread at a time. For most web applications this is not an issue, as each request receives a single thread and the programming model forbids spawning additional threads. We recommend that you take advantage of your development framework to avoid having to write your own thread handling code. If this is not possible, you should take the usual precautions that you would for an unsynchronized java.util.Collection, or any other regular, unsynchronized Java object.

Avoid Treatment of Your ServiceLocator as a Handle to a Session

Do not pool or otherwise cache ServiceLocators to maintain HDR sessions. Pooling or caching ServiceLocators to maintain HDR sessions can give rise to complicated, unnecessary schemes to cache ServiceLocators.

Avoid Deprecated Methods

HDR uses Java standard syntax to indicate deprecated methods. You should never use deprecated methods for new code because they may be dangerous, obsolete, or unsupported. Existing code should be migrated as soon as possible, as Oracle reserves the right to remove deprecated methods and classes completely from the HDR interface. Deprecated methods are identified in the following publications; refer to these documents for more details including alternative methods. Many development environments highlight the use of deprecated methods. We recommend that you make use of such features.

See Also:

Deprecated HDR methods are identified in the following Oracle publications:
  • Oracle Healthcare Data Repository API Documenation.

Use Oracle Identity Manager for Single Sign-On

HDR is deployed on WebLogic application server. HDR uses the standard J2EE application security mechanisms. Users, accessing the DR services, can configure security providers such as Oracle Identity Manager, LDAP, Single Sign-On, or custom security implementation to manage WebLogic security principals and credentials.

See Also:

  • Oracle Healthcare Data Repository Implementation Guide for more information about configuring user accounts.
  • Understanding WebLogic Security section in WebLogic Server Documentation.

Use HTTP Form Authentication

Single sign-on authentication is the preferred mechanism for deploying HDR and HDR-based web applications.

When single sign-on is not configured, we recommend using HTTP form authentication rather than HTTP basic authentication. With HTTP basic authentication, each client call to the web application performs login validation at least two times: once to determine if the client has permissions to access the web resource, and again during HDR API calls. With HTTP form authentication, the HTTP login form displays upon the first web access, and an HTTP cookie transparently authenticates the user.