JWitsml for Java: Javadoc
Main JWitsml featuresMain features as of Q1/2017:
JWitsml architectureThe 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 principlesNaming 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.
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.