raw (P2J - Progress 4GL to Java Conversion and Runtime)

java.lang.Object
- com.goldencode.p2j.util.LazyUndoable
- - com.goldencode.p2j.util.BaseDataType
  - - com.goldencode.p2j.util.BinaryData
    - - com.goldencode.p2j.util.raw

All Implemented Interfaces:

Undoable, java.io.Externalizable, java.io.Serializable, java.lang.Comparable
```
public class raw
extends BinaryData
```
A class that implements common services for a Progress 4GL compatible raw data type whose data is mutable. Only a subset of the Progress language features are supported.
Format string related processing is handled in method toString(String).
All RAW features other than string formatting are implemented in the common base class BinaryData which is shared with MEMPTR types.
In Progress 4GL, the actual maximum size of a RAW cannot be reliably determined. The largest value that has been found to consistently work is 31990. But supposedly up to 32000 should work. It turns out these don't work in practice. This implementation works to the 32000 size. Although the documentation suggests that 32kb (32768 bytes or 32 times 1024) is the limit, attempting to use values of that size actually cause memory access violations and abends, regardless of what the 4GL documentation states. This class does NOT duplicate the instability or 4GL process abends, but is otherwise compatible.

See Also:

Serialized Form

Nested Class Summary
- Nested classes/interfaces inherited from class com.goldencode.p2j.util.BinaryData
  BinaryData.RangeCheck
- Nested classes/interfaces inherited from class com.goldencode.p2j.util.BaseDataType
  BaseDataType.Type, BaseDataType.WrapperHandler

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`MAX_SIZE` The maximum size of the binary data stored in an instance.
`private byte[]`	`value` Stores the state of this instance as an array of bytes.

Fields inherited from class com.goldencode.p2j.util.BinaryData
unknown

Constructor Summary

Constructors
Constructor and Description
`raw()` Default constructor, creates an instance that represents a 0 length byte array.
`raw(BaseDataType value)` This is a special c'tor which should be used only when converting the value returned by a function or method with polymorphic return type into the expected type (i.e.
`raw(byte[] val)` Constructor which creates an instance which is initialized based on the given binary data.
`raw(character value)` Constructs an instance which converts the contents of the given Progress 4GL compatible string form of a raw value into the proper binary form.
`raw(raw value)` Constructs an instance after copying the parameter's data into the internal representation of this class.
`raw(java.lang.String value)` Constructs an instance which converts the contents of the given Progress 4GL compatible string form of a raw value into the proper binary form.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected byte[]`	`asByteArray()` Return the entire contents of the current buffer as an array.
`void`	`assign(BaseDataType data)` Sets the state (data and unknown value) of this instance based on the state of the passed instance.
`protected void`	`clearUnknown()` Sets the state of this instance's `unknown` flag to `false`.
`int`	`compareTo(java.lang.Object obj)` Compares this instance with the specified instance and returns a -1 if this instance is less than the specified, 0 if the two instances are equal and 1 if this instance is greater than the specified instance.
`protected void`	`deallocate()` Release any resources associated with the instance.
`raw`	`duplicate()` Does the same as standard `Object.clone()` method but returns an instance of `BaseDataType` and doesn't throw the `CloneNotSupportedException`.
`protected void`	`extendBytes(long len)` Helper to create a new byte array with the same contents as the given byte array and the specified length.
`protected long`	`findNextNull(long pos)` Returns the next index position into the array which is the `null` byte, starting at a given index position.
`BaseDataType.Type`	`getType()` Get the type
`BaseDataType`	`instantiateDefault()` Creates a new instance of the same type that represents the default initialized value.
`BaseDataType`	`instantiateUnknown()` Creates a new instance of the same type that represents `unknown`.
`static raw`	`instantiateUnknownRaw()` Creates a new instance of the same type that represents `unknown`.
`protected long`	`internalLength()` Reports the current length of the buffer.
`protected boolean`	`isAutoExtend()` Determines if the array of binary data stored in an instance of this class must be automatically extended in length when operations write past the current length.
`protected boolean`	`isIncompatibleTypesOnConversion(BaseDataType value)` Returns true if dynamic data type conversion should not be attempted, it can also throws in case of incompatible types for a POLY conversion.
`protected boolean`	`isLengthLimited()` Determines if the array of binary data stored in an instance of this class must be limited in length.
`boolean`	`isUninitialized()` Reports if this instance represents an uninitialized buffer.
`protected long`	`lengthLimit()` Determines the maximum length of the array of binary data stored in an instance of this class.
`protected byte`	`readByte(long pos)` Read the byte at the given location.
`protected byte[]`	`readByteRange(long pos, long len, boolean endian)` Read the bytes at the given location.
`void`	`readExternal(java.io.ObjectInput in)` Replacement for the default object reading method.
`protected void`	`replaceContents(byte[] value)` Replace the entire contents of the current buffer with the given array.
`BinaryData`	`setLength(long len)` Sets the array to a given length, which may result in either extending or truncating the array.
`void`	`setUnknown()` Sets the state of this instance's `unknown` flag to `true`.
`java.lang.String`	`toString()` Creates a default string representation of the instance data which will be equivalent to the result of `toStringExport()`.
`java.lang.String`	`toString(java.lang.String fmt)` Creates a string representation of the instance data using the given format string.
`java.lang.String`	`toStringExport()` Creates a string representation of the instance data using the 'export' format in which the data is written as a base64 string prepended with 6 hexadecimal bytes of "header" information.
`java.lang.String`	`toStringMessage()` Creates a string representation of the instance data in a form that is compatible with the `MESSAGE` language statement.
`protected long`	`visibleLength()` Reports the current length of the buffer.
`protected void`	`writeByte(byte val, long pos)` Write the byte into the given location.
`protected void`	`writeByteRange(byte[] data, long pos, long len, boolean endian)` Write the bytes at the given location.
`void`	`writeExternal(java.io.ObjectOutput out)` Replacement for the default object writing method.

Methods inherited from class com.goldencode.p2j.util.BinaryData
assign, assign, assign, defaultFormatString, genIndexError, genLimitedLengthError, genUninitializedError, getByte, getByte, getByteArray, getBytes, getBytes, getBytes, getBytes, getDouble, getDouble, getFloat, getFloat, getInt64, getInt64, getLong, getLong, getShort, getShort, getString, getString, getString, getString, getString, getString, getUnprocessedDouble, getUnsignedLong, getUnsignedLong, getUnsignedShort, getUnsignedShort, hashCode, isUnknown, length, length, lengthOf, reverseBytes, setByte, setByte, setByte, setByte, setBytes, setBytes, setBytes, setDouble, setDouble, setDouble, setDouble, setFloat, setFloat, setFloat, setFloat, setInt64, setInt64, setInt64, setInt64, setLength, setLength, setLong, setLong, setLong, setLong, setShort, setShort, setShort, setShort, setString, setString, setString, setString, setString, setString, setString, setString, setString, setString, setString, setString, setString, setUnsignedLong, setUnsignedLong, setUnsignedLong, setUnsignedLong, setUnsignedShort, setUnsignedShort, setUnsignedShort, setUnsignedShort

Methods inherited from class com.goldencode.p2j.util.BaseDataType
assign, assign, calcFormatLength, createProxy, createProxy, deepCopy, elementsOfType, equals, fallback, formatLength, fromTypeName, generateDefault, generateUnknown, getAssigner, getSize, getTypeName, incompatibleTypesOnConversion, initialize, initializeDefaultExtent, instantiateDefaultExtent, invalidInitializer, isAllKnown, isAllKnown, isAssignDirect, isProxy, isUnknownValue, maximum, minimum, notUnknownValue, sameType, val, variable

Methods inherited from class com.goldencode.p2j.util.LazyUndoable
changed, checkUndoable, checkUndoable, checkUndoable, getTransLevel, isGlobal, isUndoable, markUndoable, popBlock, rollback, setGlobal

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

- Field Detail
  - MAX_SIZE
```
public static final int MAX_SIZE
```
    The maximum size of the binary data stored in an instance.
    
    See Also:
    
    Constant Field Values
  - value
```
private byte[] value
```
    Stores the state of this instance as an array of bytes. This is independent of the state of whether or not this instance represents unknown.
- Constructor Detail
  - raw
```
public raw()
```
    Default constructor, creates an instance that represents a 0 length byte array.
  - raw
```
public raw(BaseDataType value)
```
    This is a special c'tor which should be used only when converting the value returned by a function or method with polymorphic return type into the expected type (i.e. DYNAMIC-FUNCTION()). In such cases, the 4GL does some automatic type conversion (see assign(BaseDataType)).
    
    Parameters:
    
    value - The value to be used for this instance.
  - raw
```
public raw(raw value)
```
    Constructs an instance after copying the parameter's data into the internal representation of this class.
    If the parameter's represents unknown, this instance will also represent unknown.
    
    Parameters:
    
    value - The value to be used for this instance.
  - raw
```
public raw(byte[] val)
```
    Constructor which creates an instance which is initialized based on the given binary data.
    
    Parameters:
    
    val - The binary data to be used as the contents or if null then the instance will represent unknown.
  - raw
```
public raw(java.lang.String value)
```
    Constructs an instance which converts the contents of the given Progress 4GL compatible string form of a raw value into the proper binary form. When Progress converts a raw value into a string, it inserts 6 hexadecimal characters at the front of the string and then formats all other data as a single Base64 encoded value (it is NOT split into 76 character line segments). The first 2 hexadecimal characters are always 02 and the following 4 hexadecimal characters are a hexadecimal representation of the length of the resulting value. These 6 preceding bytes are simply dropped.
    
    Parameters:
    
    value - The Base64 value to be converted into the resulting instance binary data.
  - raw
```
public raw(character value)
```
    Constructs an instance which converts the contents of the given Progress 4GL compatible string form of a raw value into the proper binary form. When Progress converts a raw value into a string, it inserts 6 hexadecimal characters at the front of the string and then formats all other data as a single Base64 encoded value (it is NOT split into 76 character line segments). The first 2 hexadecimal characters are always 02 and the following 4 hexadecimal characters are a hexadecimal representation of the length of the resulting value. These 6 preceding bytes are simply dropped.
    
    Parameters:
    
    value - The Base64 value to be converted into the resulting instance binary data. If this is the unknown, then the result is the unknown.
- Method Detail
  - compareTo
```
public int compareTo(java.lang.Object obj)
```
    Compares this instance with the specified instance and returns a -1 if this instance is less than the specified, 0 if the two instances are equal and 1 if this instance is greater than the specified instance. This is the implementation of the Comparable interface.
    The algorithm will fail to give meaningful results in the case where one tries to sort against other objects that do not represent compatible values.
    
    Specified by:
    
    compareTo in interface java.lang.Comparable
    
    Overrides:
    
    compareTo in class BinaryData
    
    Parameters:
    
    obj - The instance to compare against.
    
    Returns:
    
    -1, 0 or 1 depending on if this instance is less than, equal to or greater (respectively) than the specified instance obj.
  - instantiateUnknownRaw
```
public static raw instantiateUnknownRaw()
```
    Creates a new instance of the same type that represents unknown.
    
    Returns:
    
    An instance that represents unknown.
  - getType
```
public BaseDataType.Type getType()
```
    Get the type
    
    Specified by:
    
    getType in class BaseDataType
    
    Returns:
    
    type
  - duplicate
```
public raw duplicate()
```
    Does the same as standard Object.clone() method but returns an instance of BaseDataType and doesn't throw the CloneNotSupportedException.
    
    Specified by:
    
    duplicate in class BaseDataType
    
    Returns:
    
    A clone of this instance.
  - instantiateUnknown
```
public BaseDataType instantiateUnknown()
```
    Creates a new instance of the same type that represents unknown.
    
    Specified by:
    
    instantiateUnknown in class BaseDataType
    
    Returns:
    
    An instance that represents unknown.
  - instantiateDefault
```
public BaseDataType instantiateDefault()
```
    Creates a new instance of the same type that represents the default initialized value.
    
    Specified by:
    
    instantiateDefault in class BaseDataType
    
    Returns:
    
    An instance that represents the default value.
  - isUninitialized
```
public boolean isUninitialized()
```
    Reports if this instance represents an uninitialized buffer. Being uninitialized is not the same as being of zero length. Rather it means that the buffer was never allocated. Being unknown is also different from being uninitialized.
    
    Specified by:
    
    isUninitialized in class BinaryData
    
    Returns:
    
    true if this instance is uninitialized.
  - toString
```
public java.lang.String toString()
```
    Creates a default string representation of the instance data which will be equivalent to the result of toStringExport(). If the instance represents unknown, a '?' will be returned.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    The formatted string.
  - toString
```
public java.lang.String toString(java.lang.String fmt)
```
    Creates a string representation of the instance data using the given format string. A null format string is equivalent to the result of toStringExport(). If the instance is unknown, a '?' will be returned.
    
    Specified by:
    
    toString in class BaseDataType
    
    Parameters:
    
    fmt - The format string to use.
    
    Returns:
    
    The formatted string.
  - toStringMessage
```
public java.lang.String toStringMessage()
```
    Creates a string representation of the instance data in a form that is compatible with the MESSAGE language statement. If the instance represents unknown, a '?' will be returned.
    
    Specified by:
    
    toStringMessage in class BaseDataType
    
    Returns:
    
    The 'message' formatted string.
  - toStringExport
```
public java.lang.String toStringExport()
```
    Creates a string representation of the instance data using the 'export' format in which the data is written as a base64 string prepended with 6 hexadecimal bytes of "header" information. Warning: this method is hard-coded to produce a header string starting with "02" (this seems to be a fixed value for normal raw data in Progress, but it may be different when records or other structured data is written) and this is followed by 4 bytes specifying the length of the data.
    If the instance represents unknown, a '?' will be returned.
    
    Specified by:
    
    toStringExport in class BaseDataType
    
    Returns:
    
    The 'export' formatted string.
  - setLength
```
public BinaryData setLength(long len)
```
    Sets the array to a given length, which may result in either extending or truncating the array.
    
    Specified by:
    
    setLength in class BinaryData
    
    Parameters:
    
    len - New length of the array.
    
    Returns:
    
    The current instance is returned.
  - readExternal
```
public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException
```
    Replacement for the default object reading method. The latest state is read from the input source.
    
    Specified by:
    
    readExternal in interface java.io.Externalizable
    
    Overrides:
    
    readExternal in class BinaryData
    
    Parameters:
    
    in - The input source from which fields will be restored.
    
    Throws:
    
    java.io.IOException - In case of I/O errors.
    
    java.lang.ClassNotFoundException - If payload can't be instantiated.
  - writeExternal
```
public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException
```
    Replacement for the default object writing method. The latest state is written to the output destination.
    
    Specified by:
    
    writeExternal in interface java.io.Externalizable
    
    Overrides:
    
    writeExternal in class BinaryData
    
    Parameters:
    
    out - The output destination to which fields will be saved.
    
    Throws:
    
    java.io.IOException - In case of I/O errors.
  - setUnknown
```
public void setUnknown()
```
    Sets the state of this instance's unknown flag to true.
    Warning: the data stored in this instance WILL BE deallocated after calling this method.
    
    Overrides:
    
    setUnknown in class BinaryData
  - clearUnknown
```
protected void clearUnknown()
```
    Sets the state of this instance's unknown flag to false.
    
    Overrides:
    
    clearUnknown in class BinaryData
  - deallocate
```
protected void deallocate()
```
    Release any resources associated with the instance.
    
    Specified by:
    
    deallocate in class BinaryData
  - isLengthLimited
```
protected boolean isLengthLimited()
```
    Determines if the array of binary data stored in an instance of this class must be limited in length.
    
    Specified by:
    
    isLengthLimited in class BinaryData
    
    Returns:
    
    true if the length must be limited.
  - lengthLimit
```
protected long lengthLimit()
```
    Determines the maximum length of the array of binary data stored in an instance of this class.
    
    Specified by:
    
    lengthLimit in class BinaryData
    
    Returns:
    
    Always MAX_SIZE (32KB).
  - isAutoExtend
```
protected boolean isAutoExtend()
```
    Determines if the array of binary data stored in an instance of this class must be automatically extended in length when operations write past the current length. Such extensions will pad with null bytes.
    
    Specified by:
    
    isAutoExtend in class BinaryData
    
    Returns:
    
    true if the length must automatically extended.
  - replaceContents
```
protected void replaceContents(byte[] value)
```
    Replace the entire contents of the current buffer with the given array.
    The BinaryData.unknown flag is also cleared, only if value is not null and if the length is greater than 0.
    
    Specified by:
    
    replaceContents in class BinaryData
    
    Parameters:
    
    value - The new contents.
  - asByteArray
```
protected byte[] asByteArray()
```
    Return the entire contents of the current buffer as an array. This may be a copy of the data, depending on the subclass' implementation. DO NOT MODIFY the data that is returned, since it is undefined as to whether the changes will or will not be reflected in the actual storage.
    
    Specified by:
    
    asByteArray in class BinaryData
    
    Returns:
    
    The contents of the instance (possibly a copy). If the instance is uninitialized the returned value will be a 0 length array. If the instance is unknown or has an undefined size, then null will be returned.
  - visibleLength
```
protected long visibleLength()
```
    Reports the current length of the buffer.
    
    Specified by:
    
    visibleLength in class BinaryData
    
    Returns:
    
    The length or 0 if uninitialized.
  - internalLength
```
protected long internalLength()
```
    Reports the current length of the buffer.
    
    Specified by:
    
    internalLength in class BinaryData
    
    Returns:
    
    The length or 0 if uninitialized.
  - findNextNull
```
protected long findNextNull(long pos)
```
    Returns the next index position into the array which is the null byte, starting at a given index position.
    
    Specified by:
    
    findNextNull in class BinaryData
    
    Parameters:
    
    pos - The 0-based index into the array at which to start searching.
    
    Returns:
    
    The next index into the array which is the null byte or the length of the array if no null byte exists.
  - extendBytes
```
protected void extendBytes(long len)
```
    Helper to create a new byte array with the same contents as the given byte array and the specified length. If the given target length is smaller than the source array length, the output array is truncated to the specified size. If the target length is larger than the source array length, the output array is extended to the given size and any additional bytes are initialized to '\0'.
    This is safe to use on 0 length arrays.
    If the instance is unknown, this silently returns without making any changes.
    
    Specified by:
    
    extendBytes in class BinaryData
    
    Parameters:
    
    len - The output array length. Negative values are silently ignored. Positive values up to MAX_SIZE are accepted. Values greater than MAX_SIZE will cause an error condition to be raised.
  - readByte
```
protected byte readByte(long pos)
```
    Read the byte at the given location. All boundary checking and error handling must have already been done in the caller such that this is known to be a valid access. Any unexpected failure may cause a platform-specific exception that terminates the process!
    
    Specified by:
    
    readByte in class BinaryData
    
    Parameters:
    
    pos - The 0-based index position at which to read the byte.
    
    Returns:
    
    The byte at that location.
  - writeByte
```
protected void writeByte(byte val,
                         long pos)
```
    Write the byte into the given location. All boundary checking and error handling must have already been done in the caller such that this is known to be a valid access. Any unexpected failure may cause a platform-specific exception that terminates the process!
    
    Specified by:
    
    writeByte in class BinaryData
    
    Parameters:
    
    val - The byte to write.
    
    pos - The 0-based index position at which to read the byte.
  - readByteRange
```
protected byte[] readByteRange(long pos,
                               long len,
                               boolean endian)
```
    Read the bytes at the given location. All boundary checking and error handling must have already been done in the caller such that this is known to be a valid access. Any unexpected failure may cause a platform-specific exception that terminates the process!
    
    Specified by:
    
    readByteRange in class BinaryData
    
    Parameters:
    
    pos - The 0-based index position at which to read the bytes.
    
    len - The number of bytes to read.
    
    endian - true to force the returned data to be interpreted by the endian-ness of the native platform. The returned data will be in little endian order if this flag is set (but on a big endian platform the bytes will be reversed first).
    
    Returns:
    
    The byte range at that location.
  - writeByteRange
```
protected void writeByteRange(byte[] data,
                              long pos,
                              long len,
                              boolean endian)
```
    Write the bytes at the given location. All boundary checking and error handling must have already been done in the caller such that this is known to be a valid access. Any unexpected failure may cause a platform-specific exception that terminates the process!
    
    Specified by:
    
    writeByteRange in class BinaryData
    
    Parameters:
    
    data - The bytes to write.
    
    pos - The 0-based index position at which to start writing the bytes.
    
    len - How many bytes should be written. -1 means write everything to the end of the array.
    
    endian - true to honor the endian-ness of the platform. The data array MUST be ordered in little-endian order if the endian flag is on.
  - isIncompatibleTypesOnConversion
```
protected boolean isIncompatibleTypesOnConversion(BaseDataType value)
```
    Description copied from class: BaseDataType
    
    Returns true if dynamic data type conversion should not be attempted, it can also throws in case of incompatible types for a POLY conversion. (e.g. DYNAMIC-FUNCTION()).
    
    Overrides:
    
    isIncompatibleTypesOnConversion in class BaseDataType
  - assign
```
public void assign(BaseDataType data)
```
    Description copied from class: BinaryData
    
    Sets the state (data and unknown value) of this instance based on the state of the passed instance.
    If the value is of type BinaryData, the result will be the same as calling BinaryData.assign(BaseDataType). If the type is the unknown literal the instance will be set to unknown value.
    If the value is not of type BinaryData an error condition will be thrown because the 4GL does not support automatic type conversion for other BDT's (even character and longchar are not accepted).
    This variant is meant to handle the cases of built-in functions and methods in the 4GL which have polymorphic return types (e.g. DYNAMIC-FUNCTION()). This should NOT be used for non-polymorphic assignments.
    
    Overrides:
    
    assign in class BinaryData
    
    Parameters:
    
    data - The instance from which to copy state.

Class raw

Nested Class Summary

Nested classes/interfaces inherited from class com.goldencode.p2j.util.BinaryData

Nested classes/interfaces inherited from class com.goldencode.p2j.util.BaseDataType

Field Summary

Fields inherited from class com.goldencode.p2j.util.BinaryData

Constructor Summary

Method Summary

Methods inherited from class com.goldencode.p2j.util.BinaryData

Methods inherited from class com.goldencode.p2j.util.BaseDataType

Methods inherited from class com.goldencode.p2j.util.LazyUndoable

Methods inherited from class java.lang.Object

Field Detail

MAX_SIZE

value

Constructor Detail

raw

raw

raw

raw

raw

raw

Method Detail

compareTo

instantiateUnknownRaw

getType

duplicate

instantiateUnknown

instantiateDefault

isUninitialized

toString

toString

toStringMessage

toStringExport

setLength

readExternal

writeExternal

setUnknown

clearUnknown

deallocate

isLengthLimited

lengthLimit

isAutoExtend

replaceContents

asByteArray

visibleLength

internalLength

findNextNull

extendBytes

readByte

writeByte

readByteRange

writeByteRange

isIncompatibleTypesOnConversion

assign