API Documentation

      JWitsml Javadoc.

Main JWitsml features

Main features as of Q1/2017:
  • Complete coverage of all WITSML types
  • CRUD (Create, Read, Update, Delete) support for all types
  • Full WITSML 2.0 support through WebScoket/ETP
  • Full WITSML 1.4, 1.3 and 1.2 support through HTTP/Soap
  • Improved WITSML query engine
  • Thread-safeness: Scaled for multi-threaded client environment
  • Readily available for use on the Android mobile platform
  • All hand-coded to acheive best possible quality
  • Improved documentation


Illustrates the capabilities of JWitsml and how the library is used in Log Studio.
Shows how JWitsml is used in Log Studio to upload well log content from various sources to WITSML with single button clicks.

JWitsml architecture

The components of JWitsml are illustrated to the right.

The lowest levels contains the implementation of the WebSocket API and the ETP protocol.

The middle layer is the working horse of the system and contains the WitsmlServer instance and the query engine. This part is responsibe for converting between the Java API calls of the client and the XML specification syntax of the server. Queries (create/read/update/delete) specified by the client are converted to the equivalent (and minimal) XML syntax and sent to the server through the lower layers. The server response is disassembled and converted back to the Java model classes.

At the highest level all the WITSML object types are defined as Java objects with getters and setters for all defined properties. This is the clients convenient view of the WITSML data model.

The Unit Manager is an optional service provided for the client in order to do unit conversions on numeric data.

Design principles

Naming conventions

All top level WITSML objects exists as Java classes with Witsml prefix such as WitsmlWell, WitsmlWellbore, WitsmlLog etc.

Secondary types that are local to one containing type are implemented as inner classes on that type, such as WitsmlChangeLog.ChangeHistory, WitsmlTarget.Section, WitsmlTrajectory.Station, WitsmlRig.Bop.Component and so on.

Secondary types that are shared between many types are named without the Witsml prefix; CommonData, Location, Fluid etc.

The WITSML standard is known for its extensive use of cryptic names and abbreviations such as diaHole, numGovt, aziRef, dTimStn etc. In JWitsml properties are always named using human readable form, such as: holeDiameter, wellNumber, azimuthReference, time and so on.

The ETP messages are named according to their exact Energistics definition even if these are suboptimal in most cases. These are all methods on the EtpClient fundamental access class and will anyway not show up in the public API.

Data model

WITSML instances exists in a hierarchical relationship, but it is the responsibility of the JWitsml client application to maintain such dependencies.

This is why there is no methods like WistmlWell.getWellbores(), WitsmlWellbore.getLogs() etc. In order for JWitsml to guarantee the correctness of such calls in an interactive real-time environent it would need to go to the WITSML server each time to get this information. JWitsml instead leaves to the client application to decide when such updates are necessary.


JWitsml is lenient when it comes to converting Java API calls into equivalent WITSML queries; The query engine will transform the client requests into syntactically correct WITSML queries without validating the semantics of their content.

This means that it is the responsibility of the client to make sure that queries are according to the WITSML server requirements, i.e. that mandatory properties are specified and that other instance invariants are met.

Consequently a client developer should keep a close eye on the WITSML schema definition, and the client program should properly handle exceptions thrown by the JWitsml engine when performing remote server calls.


The ETP-based access is multi-threaded by nature. Some of the ETP messages are still poll based, and these are implemenetd through thread-blocking. Client code are always adviced to execute WITSML access code in threads, but it becomes increasingly important in these methods to avoid application hang.

JWitsml ensures thread-safeness on all data classes as well as support classes that naturally are shared between threads.

All classes representing top level WITSML objects are protected by a re-entrant read/write lock. Read operations on an object is guarded by a read lock and write operations are guarded by a write lock. In consequence, multiple threads may read JWitsml objects in parallel, while write permission is granted on a thread by thread basis, and by locking all other access.