XTCEItemValue (XML Telemetric and Command Exchange Toolkit 1.1.4 API)

java.lang.Object
- org.xtce.toolkit.XTCEItemValue

```
public class XTCEItemValue
extends Object
```
This class captures the attributes needed to encode or decode a raw value to or from an engineering value and provides public methods to do these tasks from the caller's application. The encode method is for converting an EU value provided to a raw value. The decode method does the opposite, which converts a raw value back to an EU value. Telemetry typically uses decode on the ground and Telecommanding typically uses encode on the ground, with the reverse of both happening on the satellite side. The implementation of this class might seem a little strange or less than efficient because it is extended by platform specific classes for other use cases that overload the population of the attributes such that it can be used for specific cots products. Those extended implementations are not included in this toolkit.

Author:

David Overeem

Constructor Summary

Constructors
Constructor and Description
`XTCEItemValue(XTCETypedObject item)` Constructor
`XTCEItemValue(XTCETypedObject item, org.omg.space.xtce.CalibratorType calibrator)` Constructor

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`String`	`bitSetToBinary(BitSet bits)` Convert the BitSet object from the encode() method over to a binary string of zeros and ones, ordered from most significant bit to least significant bit.
`String`	`bitSetToHex(BitSet bits)` Convert the BitSet object from the encode() method over to a hex byte string, ordered from the most significant byte to the least significant byte.
`BigInteger`	`bitSetToNumber(BitSet bits)` Convert the BitSet object from the encode() method over to a integral number, ordered from the most significant byte to the least significant byte.
`void`	`clearWarnings()` Clears the list of warning messages for this object, which can be useful if multiple raw or engineering values need to be generated, so that the list does not include previous issues.
`String`	`decode(BitSet rawValue)` Retrieve the Calibrated/Engineering value of this typed object when given the raw binary value.
`BitSet`	`encode(double euValue)` Retrieve the Raw value of this typed object when given the EU calibrated value.
`BitSet`	`encode(float euValue)` Retrieve the Raw value of this typed object when given the EU calibrated value.
`BitSet`	`encode(long euValue)` Retrieve the Raw value of this typed object when given the EU calibrated value.
`BitSet`	`encode(String euValue)` Retrieve the Raw value of this typed object when given the EU calibrated value.
`BitSet`	`encodeRawBits(BigInteger rawValue)` Function to create the raw binary bits for populating a container binary based on the encoded value of this named and typed item from the XTCE data model.
`String`	`getCalibratedFromUncalibrated(String uncalValue)` Retrieve the EU calibrated value of this typed object item when given the uncalibrated value.
`String`	`getItemName()` Retrieves the item name of the Parameter or Argument that is the basis for this item value encode()/decode() object.
`BitSet`	`getRawFromUncalibrated(BigDecimal uncalValue)` Retrieve the raw binary bits for encoding of this typed object when given the uncalibrated value.
`BitSet`	`getRawFromUncalibrated(BigInteger uncalValue)` Retrieve the raw binary bits for encoding of this typed object when given the uncalibrated value.
`BitSet`	`getRawFromUncalibrated(double uncalValue)` Retrieve the raw binary bits for encoding of this typed object when given the uncalibrated value.
`BitSet`	`getRawFromUncalibrated(float uncalValue)` Retrieve the raw binary bits for encoding of this typed object when given the uncalibrated value.
`BitSet`	`getRawFromUncalibrated(long uncalValue)` Retrieve the raw binary bits for encoding of this typed object when given the uncalibrated value.
`BitSet`	`getRawFromUncalibrated(String uncalValue)` Retrieve the raw binary bits for encoding of this typed object when given the uncalibrated value.
`String`	`getUncalibratedFromCalibrated(BigDecimal euValue)` Retrieve the uncalibrated value of an EU calibrated value for this typed object.
`String`	`getUncalibratedFromCalibrated(BigInteger euValue)` Retrieve the uncalibrated value of an EU calibrated value for this typed object.
`String`	`getUncalibratedFromCalibrated(double euValue)` Retrieve the uncalibrated value of an EU calibrated value for this typed object.
`String`	`getUncalibratedFromCalibrated(float euValue)` Retrieve the uncalibrated value of an EU calibrated value for this typed object.
`String`	`getUncalibratedFromCalibrated(long euValue)` Retrieve the uncalibrated value of an EU calibrated value for this typed object.
`String`	`getUncalibratedFromCalibrated(String euValue)` Retrieve the uncalibrated value of an EU calibrated value for this typed object.
`String`	`getUncalibratedFromRaw(BitSet rawValue)` Retrieve the uncalibrated value of this typed object item when given the raw binary value.
`List<String>`	`getWarnings()` Retrieve the list of warnings that have accumulated since this object was created or since the caller last cleared the warnings list.
`BigInteger`	`integerStringToBigInteger(String rawValue)` Convert a string representation of a Raw Value to a BigInteger.
`boolean`	`isFloatRawValueReasonable(double rawValue)` Check for reasonableness of the raw value to encode to a float type encoding.
`boolean`	`isIntegerRawValueReasonable(BigInteger rawValue)` Check for reasonableness of the raw value to encode to an integer type encoding.
`boolean`	`isValid()` Retrieves the validity flag from this item value encode/decode.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - XTCEItemValue
```
public XTCEItemValue(XTCETypedObject item)
```
    Constructor
    
    Parameters:
    
    item - XTCETypedObject containing the Parameter or Argument that is being encoded/decoded.
  - XTCEItemValue
```
public XTCEItemValue(XTCETypedObject item,
                     org.omg.space.xtce.CalibratorType calibrator)
```
    Constructor
    
    Parameters:
    
    item - XTCETypedObject containing the Parameter or Argument that is being encoded/decoded.
    
    calibrator - CalibratorType containing the contextually accurate calibrator for this item value evaluation.
- Method Detail
  - getItemName
```
public final String getItemName()
```
    Retrieves the item name of the Parameter or Argument that is the basis for this item value encode()/decode() object.
    
    Returns:
    
    String containing the name used when this object was constructed.
  - isValid
```
public final boolean isValid()
```
    Retrieves the validity flag from this item value encode/decode.
    
    Returns:
    
    boolean indicating if the encode/decode can be performed. If this is false, the encode/decode functions will throw an exception.
  - getWarnings
```
public final List<String> getWarnings()
```
    Retrieve the list of warnings that have accumulated since this object was created or since the caller last cleared the warnings list.
    
    Returns:
    
    List of String containing the warning messages.
    
    See Also:
    
    clearWarnings()
  - clearWarnings
```
public final void clearWarnings()
```
    Clears the list of warning messages for this object, which can be useful if multiple raw or engineering values need to be generated, so that the list does not include previous issues.
  - decode
```
public String decode(BitSet rawValue)
```
    Retrieve the Calibrated/Engineering value of this typed object when given the raw binary value. This method is a shortcut to calling both the getUncalibratedFromRaw() and getCalibratedFromUncalibrated() functions. Those functions contain additional details for the reader concerning the nature of the data and what is being performed. The user must interrogate the getWarnings() method to ensure that this function did not encounter any problems during conversion. In the event that warnings happened, then the return value cannot be used.
    
    Parameters:
    
    rawValue - BitSet containing the raw binary value that would be encoded on the wire or bitfield. The raw binary is always expected to be in the order read from the stream.
    
    Returns:
    
    String containing the proper Calibrated/Engineering representation of the raw encoded value provided by the caller.
  - getUncalibratedFromRaw
```
public String getUncalibratedFromRaw(BitSet rawValue)
```
    Retrieve the uncalibrated value of this typed object item when given the raw binary value. The raw value is provided as a Java BitSet to account for an arbitrary size of the raw value binary. The output of this function takes into account the encoding type to interpret the raw binary in the proper type and alignment.
    
    Parameters:
    
    rawValue - BitSet containing the raw binary value that would be encoded on the wire or bitfield. The raw binary is always expected to be in the order read from the stream.
    
    Returns:
    
    String containing the proper uncalibrated representation of the raw encoded value provided by the caller.
  - getCalibratedFromUncalibrated
```
public String getCalibratedFromUncalibrated(String uncalValue)
```
    Retrieve the EU calibrated value of this typed object item when given the uncalibrated value.
    
    Parameters:
    
    uncalValue - String containing the uncalibrated value that is derived from the encoded value on the wire or bitfield.
    
    Returns:
    
    String containing the proper EU calibrated representation of the uncalibrated value provided by the caller.
  - encode
```
public BitSet encode(String euValue)
```
    Retrieve the Raw value of this typed object when given the EU calibrated value. This method is a shortcut to calling both the getUncalibratedFromCalibrated() and getRawFromUncalibrated() functions. Those functions contain additional details for the reader concerning the nature of the data and what is being performed. The user must interrogate the getWarnings() method to ensure that this function did not encounter any problems during conversion. In the event that warnings happened, then the return value cannot be used.
    
    Parameters:
    
    euValue - String containing the EU calibrated value that would be encoded on the wire or bitfield.
    
    Returns:
    
    String containing the encoded BitSet suitable for encoding a stream with this item value.
  - encode
```
public BitSet encode(long euValue)
```
    Retrieve the Raw value of this typed object when given the EU calibrated value. This method is a shortcut to calling both the getUncalibratedFromCalibrated() and getRawFromUncalibrated() functions. Those functions contain additional details for the reader concerning the nature of the data and what is being performed. The user must interrogate the getWarnings() method to ensure that this function did not encounter any problems during conversion. In the event that warnings happened, then the return value cannot be used.
    
    Parameters:
    
    euValue - long containing the EU calibrated value that would be encoded on the wire or bitfield.
    
    Returns:
    
    String containing the encoded BitSet suitable for encoding a stream with this item value.
  - encode
```
public BitSet encode(double euValue)
```
    Retrieve the Raw value of this typed object when given the EU calibrated value. This method is a shortcut to calling both the getUncalibratedFromCalibrated() and getRawFromUncalibrated() functions. Those functions contain additional details for the reader concerning the nature of the data and what is being performed. The user must interrogate the getWarnings() method to ensure that this function did not encounter any problems during conversion. In the event that warnings happened, then the return value cannot be used.
    
    Parameters:
    
    euValue - double containing the EU calibrated value that would be encoded on the wire or bitfield.
    
    Returns:
    
    String containing the encoded BitSet suitable for encoding a stream with this item value.
  - encode
```
public BitSet encode(float euValue)
```
    Retrieve the Raw value of this typed object when given the EU calibrated value. This method is a shortcut to calling both the getUncalibratedFromCalibrated() and getRawFromUncalibrated() functions. Those functions contain additional details for the reader concerning the nature of the data and what is being performed. The user must interrogate the getWarnings() method to ensure that this function did not encounter any problems during conversion. In the event that warnings happened, then the return value cannot be used.
    
    Parameters:
    
    euValue - float containing the EU calibrated value that would be encoded on the wire or bitfield.
    
    Returns:
    
    String containing the encoded BitSet suitable for encoding a stream with this item value.
  - getRawFromUncalibrated
```
public BitSet getRawFromUncalibrated(String uncalValue)
```
    Retrieve the raw binary bits for encoding of this typed object when given the uncalibrated value.
    
    Parameters:
    
    uncalValue - String containing the uncalibrated representation of the value.
    
    Returns:
    
    BitSet containing the raw bits.
  - getRawFromUncalibrated
```
public BitSet getRawFromUncalibrated(BigInteger uncalValue)
```
    Retrieve the raw binary bits for encoding of this typed object when given the uncalibrated value.
    
    Parameters:
    
    uncalValue - BigInteger containing the uncalibrated representation of the value.
    
    Returns:
    
    BitSet containing the raw bits.
  - getRawFromUncalibrated
```
public BitSet getRawFromUncalibrated(long uncalValue)
```
    Retrieve the raw binary bits for encoding of this typed object when given the uncalibrated value.
    
    Parameters:
    
    uncalValue - long containing the uncalibrated representation of the value.
    
    Returns:
    
    BitSet containing the raw bits.
  - getRawFromUncalibrated
```
public BitSet getRawFromUncalibrated(BigDecimal uncalValue)
```
    Retrieve the raw binary bits for encoding of this typed object when given the uncalibrated value.
    
    Parameters:
    
    uncalValue - BigDecimal containing the uncalibrated representation of the value.
    
    Returns:
    
    BitSet containing the raw bits.
  - getRawFromUncalibrated
```
public BitSet getRawFromUncalibrated(double uncalValue)
```
    Retrieve the raw binary bits for encoding of this typed object when given the uncalibrated value.
    
    Parameters:
    
    uncalValue - double containing the uncalibrated representation of the value.
    
    Returns:
    
    BitSet containing the raw bits.
  - getRawFromUncalibrated
```
public BitSet getRawFromUncalibrated(float uncalValue)
```
    Retrieve the raw binary bits for encoding of this typed object when given the uncalibrated value.
    
    Parameters:
    
    uncalValue - float containing the uncalibrated representation of the value.
    
    Returns:
    
    BitSet containing the raw bits.
  - getUncalibratedFromCalibrated
```
public String getUncalibratedFromCalibrated(String euValue)
```
    Retrieve the uncalibrated value of an EU calibrated value for this typed object.
    
    Parameters:
    
    euValue - String containing a value of this item represented in EU/calibrated form.
    
    Returns:
    
    String containing the uncalibrated value.
  - getUncalibratedFromCalibrated
```
public String getUncalibratedFromCalibrated(BigInteger euValue)
```
    Retrieve the uncalibrated value of an EU calibrated value for this typed object.
    
    Parameters:
    
    euValue - BigInteger containing a value of this item represented in EU/calibrated form.
    
    Returns:
    
    String containing the uncalibrated value.
  - getUncalibratedFromCalibrated
```
public String getUncalibratedFromCalibrated(long euValue)
```
    Retrieve the uncalibrated value of an EU calibrated value for this typed object.
    
    Parameters:
    
    euValue - long containing a value of this item represented in EU/calibrated form.
    
    Returns:
    
    String containing the uncalibrated value.
  - getUncalibratedFromCalibrated
```
public String getUncalibratedFromCalibrated(BigDecimal euValue)
```
    Retrieve the uncalibrated value of an EU calibrated value for this typed object.
    
    Parameters:
    
    euValue - BigDecimal containing a value of this item represented in EU/calibrated form.
    
    Returns:
    
    String containing the uncalibrated value.
  - getUncalibratedFromCalibrated
```
public String getUncalibratedFromCalibrated(double euValue)
```
    Retrieve the uncalibrated value of an EU calibrated value for this typed object.
    
    Parameters:
    
    euValue - double containing a value of this item represented in EU/calibrated form.
    
    Returns:
    
    String containing the uncalibrated value.
  - getUncalibratedFromCalibrated
```
public String getUncalibratedFromCalibrated(float euValue)
```
    Retrieve the uncalibrated value of an EU calibrated value for this typed object.
    
    Parameters:
    
    euValue - float containing a value of this item represented in EU/calibrated form.
    
    Returns:
    
    String containing the uncalibrated value.
  - encodeRawBits
```
public BitSet encodeRawBits(BigInteger rawValue)
```
    Function to create the raw binary bits for populating a container binary based on the encoded value of this named and typed item from the XTCE data model. The caller provides the raw value in the form of a BigInteger and this function walks through the bits of that value, ensuring to use all the bits that are in the raw encoded size. It sets the BitSet such that bit 0 of the BitSet is the least significant bit and the highest (rawSizeInBits_) is the most significant bit. If the order is reversed by the encoding attribute @bitOrder, then the reverse happens.
    
    Parameters:
    
    rawValue - BigInteger containing the value to encode into a raw BitSet for inclusion into a container object, either Telemetry or Telecommand.
    
    Returns:
    
    BitSet suitable for inclusion into a Telemetry or Telecommand container by simply walking the length and placing the bits into the container. All ordering has already been handled.
  - bitSetToHex
```
public final String bitSetToHex(BitSet bits)
```
    Convert the BitSet object from the encode() method over to a hex byte string, ordered from the most significant byte to the least significant byte. The most significant bits are padded with zero in this case when the raw size is not on an even 8 bit boundary. This results in the function never returning a hex string that is less than 2 characters for each byte, with a minimum of 1 byte. A "0x" is prepended. If the exact raw size is needed, call the rawSizeInBits() method to determine which of the uppermost bits are extraneous.
    
    Parameters:
    
    bits - BitSet returned from the encode() function.
    
    Returns:
    
    String containing the hex of the raw value to be encoded, subject to the explanation above associated with this function.
  - bitSetToNumber
```
public final BigInteger bitSetToNumber(BitSet bits)
```
    Convert the BitSet object from the encode() method over to a integral number, ordered from the most significant byte to the least significant byte.
    
    Parameters:
    
    bits - BitSet returned from the encode() function.
    
    Returns:
    
    String containing the hex of the raw value to be encoded, subject to the explanation above associated with this function.
  - bitSetToBinary
```
public final String bitSetToBinary(BitSet bits)
```
    Convert the BitSet object from the encode() method over to a binary string of zeros and ones, ordered from most significant bit to least significant bit.
    
    Parameters:
    
    bits - BitSet containing the bits returned from the encode() function.
    
    Returns:
    
    String containing the binary zeros and ones, with all bit positions populated for the entire length of the raw size. The number of bits will always exactly equal the raw encoding size, with the upper possible unused bits padded with zeros.
  - integerStringToBigInteger
```
public BigInteger integerStringToBigInteger(String rawValue)
```
    Convert a string representation of a Raw Value to a BigInteger. All raw values are represented in the form of hexadecimal or perhaps in more rare occasions, a user may present a base 10 number. The BigInteger is a convenient container for an arbitrary length series of bytes that is easy to work with in hex form. A warning is logged if the string representation cannot be converted to numeric.
    
    Parameters:
    
    rawValue - String containing the candidate raw representation.
    
    Returns:
    
    BigInteger containing the raw value or zero if a warning was logged.
  - isIntegerRawValueReasonable
```
public boolean isIntegerRawValueReasonable(BigInteger rawValue)
```
    Check for reasonableness of the raw value to encode to an integer type encoding. This method first figures out the range of possible values based on the size in bits and the signed state. It then checks if the value should be restricted further by a possibly present ValidRange element. It applies those limits if they are intended for the raw value.
    
    Parameters:
    
    rawValue - BigInteger containing the raw value that will be encoded if it turns out to be reasonable.
    
    Returns:
    
    boolean indicating if this function thinks the value is reasonable to fit in the allowable size and range.
  - isFloatRawValueReasonable
```
public boolean isFloatRawValueReasonable(double rawValue)
```
    Check for reasonableness of the raw value to encode to a float type encoding. This method first figures out the range of possible values based on the size in bits of the floating point range. This is generally not very useful because the range is very wide. It then checks if the value should be restricted further by a possibly present ValidRange element. It applies those limits if they are intended for the raw value.
    
    Parameters:
    
    rawValue - double containing the raw value that will be encoded if it turns out to be reasonable.
    
    Returns:
    
    boolean indicating if this function thinks the value is reasonable to fit in the allowable size and range.

Class XTCEItemValue

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

XTCEItemValue

XTCEItemValue

Method Detail

getItemName

isValid

getWarnings

clearWarnings

decode

getUncalibratedFromRaw

getCalibratedFromUncalibrated

encode

encode

encode

encode

getRawFromUncalibrated

getRawFromUncalibrated

getRawFromUncalibrated

getRawFromUncalibrated

getRawFromUncalibrated

getRawFromUncalibrated

getUncalibratedFromCalibrated

getUncalibratedFromCalibrated

getUncalibratedFromCalibrated

getUncalibratedFromCalibrated

getUncalibratedFromCalibrated

getUncalibratedFromCalibrated

encodeRawBits

bitSetToHex

bitSetToNumber

bitSetToBinary

integerStringToBigInteger

isIntegerRawValueReasonable

isFloatRawValueReasonable