Getting WITSML data from the server

All data is retrieved through a WitsmlServer instance which represents the WITSML server in the client program.

There are three different ways to get data:

1. Get multiple children of a given type from a specific parent

     
     // Get all wellbores from a given well instance
     List<WitsmlWellbore> wellbores = witsmlServer.get(WitsmlWellbore.class,
                                                       new WitsmlQuery(),
                                                       well);

     
     // Get all rigs from a given wellbore instance
     List<WitsmlRig> rigs = witsmlServer.get(WitsmlRig.class,
                                             new WitsmlQuery(),
                                             wellbore);

     
     // ... or through the wellbore ID
     List<WitsmlRig> rigs = witsmlServer.get(WitsmlRig.class,
                                             new WitsmlQuery(),
                                             "ID-wellbore");

     
     // Both parent and grandparent may be specified
     List<WitsmlMudLog> mudLogs = witsmlServer.get(WitsmlMudLog.class,
                                                   new WitsmlQuery(),
                                                   "ID-wellbore",
                                                   "ID-well");

     
     // Wells doesn't have parents so we can skip the parent argument
     List<WitsmlWell> wells = witsmlServer.get(WitsmlWell.class,
                                               new WitsmlQuery());

     
     // Attempt to get all rigs! Some servers will accept this approach
     // while others will require a valid wellbore parent.
     // The WITSML standard is unclear on this issue.
     List<WitsmlRig> rigs = witsmlServer.get(WitsmlRig.class,
                                             new WitsmlQuery());

  

2. Get a specific child of a given type from a specific parent

     
     // Get a specific log instance from a wellbore instance
     WitsmlLog log = witsmlServer.getOne(WitsmlLog.class,
                                         new WitsmlQuery(),
                                         "ID-log",
                                         wellbore);

     
     // ... or through the wellbore ID
     WitsmlLog log = witsmlServer.getOne(WitsmlLog.class,
                                         new WitsmlQuery(),
                                         "ID-log",
                                         "ID-wellbore");

     
     // Wells doesn't have parents so we can skip the parent argument
     WitsmlWell well = witsmlServer.getOne(WitsmlWell.class,
                                           new WitsmlQuery(),
                                           "ID-well");

  

3. Refresh an already instantiated object

     
     // Get all attributes from an already loaded wellbore instance
     witsmlServer.refresh(wellbore, new WitsmlQuery());
  

Each JWitsml class representing WITSML instances has getter methods for all the individual properties defined by WITSML for that type.

Attribute names in the JWitsml library does not necessarily correspond exactly to the WITSML definition as the former is specified in a human readable form. Names like dTimKickoff is translated into kickoffTime etc.

     WitsmlMudLog mudLog = ...

     System.out.println("Name: " + mudLog.getName());
     System.out.println("Time: " + mudLog.getTime());
     System.out.println("Mud log company: " + mudLog.getMudLogCompany());
     :
     :
  

Floating point values that may have a unit associated are represented by the Value type which is a compound of a double and a unit symbol string. 

The WitsmlQuery class

The WitsmlQuery class is used to control which properties to extract for each object as well as for object filtering.

A default WitsmlQuery instance as shown in the above examples simply means get all properties.

Getting only a subset of the properties of a type is done by specificly including the requested WITSML elements in the WitsmlQuery object:

     
     // Construct a query consisting of name and id only
     WitsmlQuery query = new WitsmlQuery();
     query.includeElement("id");
     query.includeElement("name");
     
     // Get all wells (name and id) from a given server
     List<WitsmlWell> wells = WitsmlServer.get(WitsmlWell.class,
                                               query);
  

Note that when specifying elements and attributes for the WitsmlQuery class, the WITSML terms as specified in the WITSML schema are being used.

Sometimes it is more convenient to get all elements but a few, perhaps elements representing bulk data. In the example below all trajectories of a wellbore are retrieved including all their properties except for the trajectory stations:

     
     // Get all trajectories for a wellbore, but exclude the stations
     WitsmlQuery query = new WitsmlQuery();
     query.excludeElement("stations");

     List<WitsmlTrajectory> trajectories = WitsmlServer.get(WitsmlTrajectory.class,
                                                            query,
                                                            wellbore);
  

When an object is initially instantiated with only a few properties, more properties can be loaded using the refresh() method:

     
     // Get name and id for a specific wellbore
     WitsmlQuery query = new WitsmlQuery();
     query.includeElement("id");
     query.includeElement("name");
     WitsmlWellbore wellbore = WitsmlServer.getOne(WitsmlWellbore.class,
                                                   query,
                                                   "ID-wellbore");
     
     // Get more wellbore properties 
     query = new WitsmlQuery();
     query.includeElement("statusWellbore");
     query.includeElement("mdCurrent");
     query.includeElement("tvdCurrent");
     query.includeElement("mdPlanned");
     query.includeElement("tvdPlanned");

     witsmlServer.refresh(wellbore, query);
  

Note that calls to the WitsmlServer.get(), getOne() and refresh() methods might be time consuming, and in most cases it is far more efficient to retrieve all attributes in a single server access. 

Filtering

The WitsmlQuery class can be used for object filtering as shown in the following example:

     
     // Get all active wellbores of a well
     WitsmlQuery query = new WitsmlQuery();
     query.addElementConstraint("statusWellbore", "active");

     List<WitsmlWellbore> wellbores = witsmlServer.get(WitsmlWellbore.class,
                                                       query,
                                                       well);
  

More than one filter may be specified in the same query, and the same filter may be set repeatedly in order to filter on more than one value:

     
     // Get log including a subset of the available curves and no bulk data
     WitsmlQuery query = new WitsmlQuery();
     query.addElementConstraint("mnemonic", "Depth");
     query.addElementConstraint("mnemonic", "GR");
     query.addElementConstraint("mnemonic", "Dens");
     query.excludeElement("logData");

     WitsmlLog log = witsmlServer.getOne(WitsmlWellbore.class,
                                         query,
                                         "ID-log",
                                         wellbore);
  

Unit of Measure

WITSML defines an elaborate set of units and unit conversions. JWitsml supports this information through a powerful yet simple API.

WITSML units are accessed through the WitsmlUnitManager singleton class.

Units (such as "meter" or "bar") are organised by WITSML in quantities (such as "length" or "pressure"). Each quantity defines a base unit (typically the SI unit) and potentially a set of derrived units.

The following piece of code lists all quantities and associated units defined by WITSML:

     import org.jwitsml.units.WitsmlUnitManager;
     import org.jwitsml.units.WitsmlUnit;

     :

     // Get the unit manager
     WitsmlUnitManager unitManager = WitsmlUnitManager.getInstance();

     // Get all known quantities
     List<String> quantities = unitManager.getQuantities();
     for (String quantity : quantities) {
       System.out.println("Quantity: " + quantity);

       // List all units of the quantity
       List<WitsmlUnit> units = unitManager.getUnits(quantity);
       for (WitsmlUnit unit : units)
         System.out.println("  " + unit);
     }
  

Converting between units is done using the convert() method of the WitsmlUnitManager:

     // Get units for feet and centimeters respectively
     WitsmlUnit ftUnit = unitManager.findUnit("ft");
     WitsmlUnit cmUnit = unitManager.findUnit("cm");

     // Convert between the two
     double ftValue = 1.0;
     double cmValue = unitManager.convert(ftUnit, cmUnit, ftValue);
  

When calling a WITSML server a client may specify the preferred return unit for a certain property. As such requests are defined by the WITSML standard to be regarded as hints only, the client can unfortunately never rely on this feature. Until this is properly sorted out by the standard, the client is always forced to handle unit conversions itself (null-checking omitted):

     Value currentMd = wellbore.getCurrentMd();

     WitsmlUnit unit = unitManager.findUnit(currentMd.getUnit());
     WitsmlUnit baseUnit = unitManager.findBaseUnit(unit);

     double currentMdInMeters = unitManager.convert(unit, baseUnit,
                                                    currentMd.getValue());
  

As this is such a common operation it can be done using the toBase() convenience method:

     // Get current wellbore MD in meters
     Value currentMd = wellbore.getCurrentMd();
     if (currentMd != null)
       currentMd = unitManager.toBase(currentMd);
  

Note that using the JWitsml unit module never causes any remote WITSML server calls. The unit data base of WITSML is part of the JWitsml delivery and thus local to the client software. 

Connection Logging

A client application may supervise the details of the WITSML server communication by adding a WitsmlAccessListener to the WitsmlServer:

     public class ClientListener implements WitsmlAccessListener {

       @Override
       public void accessPerformed(WitsmlAccessEvent event) {
         // Logging goes here
       }
     }
  

The accessPerformed() method is called after every JWitsml access to the remote WITSML server. The callback may be used by the client for basic logging operations or to produce advanced performance statistics etc.

The WitsmlAccessEvent instance contains information such as the low level WSDL procedure name, the XML query and response strings, the server response time in milliseconds, any exceptions thrown etc.

Threading

JWitsml is purposedly not thread-safe and if threaded access to JWitsml objects are required, the client software must implement this using a thread-safe facade.


Copied From : http://www.jwitsml.org/