public final class WitsmlUnitManager extends Object
The unit manager provides an optional service for client programs that are doing computational operations on numerical WITSML data.
Units (such as "meter" or "bar") are organized by WITSML in quantities (such as "length" or "pressure"). Each quantity defines a base unit (typically the SI unit) and potentially a set of derived units.
WITSML defines an elaborate set of units and unit conversions. More than 2.300 units of more than 250 different petroleum related quantities exists. The following piece of code lists all quantities and associated units defined by WITSML:
// Get the unit manager singelton WitsmlUnitManager unitManager = WitsmlUnitManager.getInstance(); // Get all known quantities List<String> quantities = unitManager.getQuantities(); // Loop over all quantities and list all associated units 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. In fact JWitsml by default always requests values in their SI units. 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 locally:
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
toBaseUnit
convenience method:
// Get current wellbore MD in meters Value currentMd = wellbore.getCurrentMd(); currentMd = unitManager.toBaseUnit(currentMd);
Note that using the JWitsml unit module never causes any remote WITSML server calls. The unit database of WITSML is part of the JWitsml delivery and thus local to the client program.
JWitsml uses version 2.2 of the Energistics unit database which is compatible with WITSML 1.4 and PRODML 1.1. JWitsml has made a number of modifications to this database in order to tune some incompatibilities and defects.
This class is immutable.
Modifier and Type | Method and Description |
---|---|
double |
convert(WitsmlUnit fromUnit,
WitsmlUnit toUnit,
double value)
Convert a specified value between two units.
|
WitsmlUnit |
findBaseUnit(WitsmlUnit unit)
Find the base unit of the specified unit.
|
WitsmlUnit |
findUnit(String unitSymbol)
Find unit instance based on the specified unit symbol.
|
static WitsmlUnitManager |
getInstance()
Return the sole instance of this class.
|
List<String> |
getQuantities()
Return names of all known quantities.
|
List<WitsmlUnit> |
getUnits(String quantityName)
Return all units of the specified quantity.
|
String |
getVersion()
Return the version of the WITSML unit database.
|
Value |
toBaseUnit(Value value)
Convert the specified value instance to base unit
if possible.
|
String |
toString() |
public static WitsmlUnitManager getInstance()
public String getVersion()
public List<String> getQuantities()
public List<WitsmlUnit> getUnits(String quantityName)
quantityName
- Quantity to get units for. Non-null.IllegalArgumentException
- If quantityName is null or unknown.public WitsmlUnit findUnit(String unitSymbol)
unitSymbol
- Symbol of unit to find. Non-null.IllegalArgumentException
- If unitSymbol is null.public WitsmlUnit findBaseUnit(WitsmlUnit unit)
unit
- Unit to find base unit for. Non-null.IllegalArgumentException
- If unit is null.public double convert(WitsmlUnit fromUnit, WitsmlUnit toUnit, double value)
fromUnit
- Unit to convert from. Non-null.toUnit
- Unit to convert to. Non-null.value
- Value to convert.IllegalArgumentException
- If fromUnit or toUnit is null or
if the two units are incompatible.public Value toBaseUnit(Value value)
TODO: Return Double instead.
value
- Value to convert. May be null.Copyright © 2023 Petroware AS - https://petroware.no