Pointer

java.lang.Object
- com.heirloomcomputing.epli.runtime.Pointer<T>

All Implemented Interfaces:

java.lang.Comparable<Pointer<T>>

Direct Known Subclasses:

Offset
```
public class Pointer<T>
extends java.lang.Object
implements java.lang.Comparable<Pointer<T>>
```
Simulates the PL/I POINTER, which can reference any object through either a direct pointer reference to that object or a handle to a direct pointer of that other object (double-pointer reference). Pointers and handles are also used by EPLI to handle pass-by-reference BYADDR parameter declarations and the ADDR() builtin functions.
Direct pointers can be typed, e.g., Pointer<FixedBin> or Pointer<MyLevel1>, or untyped, e.g, Pointer<Object> or Pointer<?>.
Direct pointers may be assigned and referenced to access the underlying object. In Java, the assignment results in replacing the object instance to which the pointer refers (Java cannot update the value of immutable classes like Integer or String). So long as programs always refer to the pointer (via its ref() method) it will appear as if the "immutable" object is changeable. Typed and untyped Pointers are efficient when used in these ways.
Typed direct pointers contain a reference to another variable as in one passed to a BYADDR PROCEDURE parameter as new Pointer<FixedBin>(MyFB53) the reference would hold the object pointer to MyFB53 as in,
```
    FixedBin MyFB53 = new FixedBin("10.111B", 5,3); // 2-7/8ths
    Pointer<FixedBin> typedPointer = new Pointer<FixedBin>(MyFB53);
    System.out.println(typedPointer.ref().toString()); // 2.875
 
```
The type for the Pointer<?> constructor and the variable type must agree (for structures the Group type would be and Group methods perform mapping among disparate Groups). The ref() function returns the Object reference of the type associated with the Pointer and assign(x) assigns the Pointer reference to the new Object also of the same type. In other words, you cannot assign typed pointers an object reference that differs in type
```
    // *** DOES NOT WORK ***
    Short MyShort = Short.valueOf(22);
    Pointer<Long> = badPointer = new Pointer<Long>(MyShort); // compile error
 
```
Untyped direct pointers are declared and used to hold Object objects as in,
```
    Short MyShort = Short.valueOf(22);
    Pointer<Object> untypedPointer = new Pointer<Object>(MyShort);
 
```
A reference to a untyped direct pointers can't be used directly, of course, but can be cast to the type they hold as in,
```
    if (untypedPointer.ref() instanceof Short) {
        short s = ((Short) untypedPointer.ref()).shortValue();
        ...
    }
 
```
A typed or untyped indirect handle is used to reference a variable of a different type when it is desirable to indirectly map between the different classes. This is most often used when the PL/I program requires a redefine of one variable to the type of another as in the PL/I construct
```
    DCL TABULADOR_ASCII        BIT (08) INIT('00000101'B);
    DCL TAB_ASCII              CHAR(01) BASED(ADDR(TABULADOR_ASCII));
 
```
in which case variable mapping occurs between the two. Handles are created by constructing a Pointer with a Pointer, such as,
```
    @CHAR(2) Pointer<String> MyChar = new Pointer<String>();
    MyChar.assign(new String("ab"));
    Pointer<Short> handlePointer = new Pointer<Short>(MyChar2);
    if (handlePointer.ref().shortValue() == (short) 0x6162) return true;
 
```
or by assigning a Pointer with another pointer, such as,
```
    @CHAR(2) Pointer<String> MyChar = new Pointer<String>();
    MyChar.assign(new String("ab"));
    Pointer<Short> handlePointer = new Pointer<Short>();
    handlePointer.assign(MyChar);
    if (handlePointer.ref().shortValue() == (short) 0x6162) return true;
 
```
The ref() and assign() methods of a handle refer to the underlying object associated with the handle and mapping to it occurs with each reference. (assign does not reset a handle to a different object pointer). Since effectively a type conversion occurs with each use of a handle they are slower than direct Pointers.

The epli compiler will produce typed pointers when the POINTER is only used with a single object so that Java casts are not necessary to "dereference". The ref() method is used to "dereference" a Pointer. Dereferencing NULL pointers will throw the NULLPOINTER ERROR Condition.
PL/I code
```
   DCL P POINTER;
   DCL 1 A BASED(P),
         2 B FIXED BIN(15),
         2 C FIXED BIN(31),
         2 D CHAR(10);
   ALLOCATE A SET(P);
   P->C = 11;
 
```
Java code
```
   class A extends Group {
         @OFF(0) b Short = new Short((short)0);
         @OFF(2) c Integer = Integer.valueOf((int)0);
         @OFF(6) @CHAR(10) d String = new String("          ");
   }
   Pointer<A> p = new Pointer<A>(new A());
   p.ref().c = 11;
 
```
This is a wrapper class of either a typed or untyped object class primarily to cover raising the PL/I NULLPOINTER ERROR Condition instead of Java NullPointerException.

Note: There are several notions of "assigning a pointer" depending on the type of pointer and desired outcome. Dereference a pointer with ref() and use an assignment statement to change the value of a field within a group (e.g., myPtrToGroupA.ref().myFieldOfGroupA = 22;). Use assign(Object) to assign either the pointer reference in this or the handle's pointer. Use assign(Pointer) to assign the handle itself to refer to a different REDEFINED object. Use assign(Object, Area) to change a portion of the object to which this handle Pointer refers. Finally, dereferencing a pointer with ref() and replacing the entire object with a new object instance (e.g., MyPtrToInteger.ref() = Integer.valueOf(22); probably never results in the desired effect because the reference within the pointer refers to a old object rather than the one being assigned. The assign(Object) (e.g., MyPtrToInteger.assign(Integer.valueOf(22);) should be used in this case.
Author:

Heirloom Computing, Inc.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`BYTES` size in bytes if converted to a byte array
`T`	`model` it is so difficult to find the class of T at runtime, and in many ways impossible due to javac's _class erasure_, we require a "model" object (any instance of T, which is not modified) to be passed when creating handles to assist in pointer datatype conversions.
`static Pointer<java.lang.Object>`	`NULL` an undefined POINTER
`protected T`	`ref` the Object to which this static Pointer refers

Constructor Summary

Constructors
Constructor and Description
`Pointer()` Construct a untyped null Pointer.
`Pointer(EPLITYPES type)` Construct a typed null Pointer.
`Pointer(T ref)` Construct a typed Pointer referencing another object of that type.
`Pointer(T model, Pointer<?> handle)` Construct a handle mapped to an object contained within another pointer.
`Pointer(T model, Pointer<?> handle, int offset)` Construct a handle mapped to an object contained within another pointer with a offset, as is the case in a variable DEFINED on another with a POSITION, as in, DCL A CHAR(4); // 4 chars, overlaid with DCL B DEFINED A CHAR(2) POSITION(3); // last 2 chars of A

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Pointer<T>`	`assign(int off, int len, java.lang.Object source)` Assign a portion of a (usually) Group member of class T a value referred to by this HANDLE.
`Pointer<T>`	`assign(Pointer<T> ptr)` Assign a handle to a new object pointer.
`Pointer<T>`	`assign(T source)` Assign the pointer a reference to the given object of type T.
`Pointer<T>`	`assign(T ref, Area inArea)` Assign a pointer within an area a new object reference.
`int`	`compareTo(Pointer<T> op2)` compareTo - compare two typed pointers
`boolean`	`equal(java.lang.Object ob2)` equal - compare two typed pointers
`void`	`free()` Invalidate the object reference.
`void`	`free(boolean ignore)` Invalidate the object reference, ignoring the ONNULL condition.
`Pointer<T>`	`fromBytes(byte[] bytes)` turn a sequence of bytes into a Pointer
`Pointer<?>`	`handle()` Return the "handle" to an object of this type T used with this HANDLE or "template" structure associated with this HANDLE or REDEFINED structure.
`boolean`	`isNull()` return true if this Pointer is null
`static void`	`main(java.lang.String[] args)` Pointer unit test
`T`	`model()` Return the "model" or "template" of the class on which this Pointer is based as class "T".
`T`	`ref()` De-reference the POINTER by returning the object, regardless of whether the Pointer is used to hold direct pointers or indirect handles.
`T`	`ref(EPLITYPES check)` De-reference the POINTER by returning the object, first checking to see if it is a valid POINTER reference for this variable type.
`T`	`ref(java.lang.String check)` De-reference the POINTER by returning the object, first checking to see if it is a valid POINTER reference for this variable type.
`Pointer<T>`	`refAssign(byte[] bytes)` assign the underlying (referenced) structure to which this POINTER points the sequence of bytes
`byte[]`	`toBytes()` turn a Pointer into a sequence of bytes
`java.lang.String`	`toString()` for debugging info, dump ptr info, put list ptr, etc.
`EPLITYPES`	`typeof()` return the EPLITYPES type of the object pointed to by this pointer or handle

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

- Field Detail
  - BYTES
```
public static final int BYTES
```
    size in bytes if converted to a byte array
    
    See Also:
    
    Constant Field Values
  - NULL
```
public static final Pointer<java.lang.Object> NULL
```
    an undefined POINTER
  - ref
```
protected T ref
```
    the Object to which this static Pointer refers
  - model
```
public final T model
```
    it is so difficult to find the class of T at runtime, and in many ways impossible due to javac's _class erasure_, we require a "model" object (any instance of T, which is not modified) to be passed when creating handles to assist in pointer datatype conversions. This public, final field may be referenced directly or through the model() method which checks for use only with handles
- Constructor Detail
  - Pointer
```
public Pointer()
```
    Construct a untyped null Pointer.
  - Pointer
```
public Pointer(EPLITYPES type)
```
    Construct a typed null Pointer.
    
    Parameters:
    
    type - - the EPLITYPES (e.g., FIXEDBIN31).
  - Pointer
```
public Pointer(T ref)
```
    Construct a typed Pointer referencing another object of that type.
    
    Parameters:
    
    ref - - an object of type T that is the reference to the variable this pointer holds.
  - Pointer
```
public Pointer(T model,
               Pointer<?> handle)
```
    Construct a handle mapped to an object contained within another pointer.
    
    Parameters:
    
    model - - an object of type T that helps in converting a handle's value from its type T to this type T. Required because of Javas type erasure concept for parameterized classes. Helper's value is inconsequential, but typically ZERO.
    
    handle - - a pointer of a different type other than T to which this pointer is mapped.
  - Pointer
```
public Pointer(T model,
               Pointer<?> handle,
               int offset)
```
    Construct a handle mapped to an object contained within another pointer with a offset, as is the case in a variable DEFINED on another with a POSITION, as in, DCL A CHAR(4); // 4 chars, overlaid with DCL B DEFINED A CHAR(2) POSITION(3); // last 2 chars of A
    
    Parameters:
    
    model - - an object of type T that helps in converting a handle's value from its type T to this type T. Required because of Javas type erasure concept for parameterized classes. Helper's value is inconsequential, but typically ZERO.
    
    handle - - a pointer of a different type other than T to which this pointer is mapped.
    
    offset - - an int indicating the offset within the handle the model object is to point
- Method Detail
  - ref
```
public T ref()
```
    De-reference the POINTER by returning the object, regardless of whether the Pointer is used to hold direct pointers or indirect handles.
    
    Returns:
    
    the object reference this POINTER is for.
    
    Throws:
    
    ERROR - Condition with NULLPOINTER for null pointers.
  - ref
```
public T ref(java.lang.String check)
```
    De-reference the POINTER by returning the object, first checking to see if it is a valid POINTER reference for this variable type.
    
    Parameters:
    
    check - - a String representation of the Java class name to verify before returning the pointer.
    
    Returns:
    
    the object reference this POINTER is for.
    
    Throws:
    
    ERROR - Condition with NULLPOINTER or WRONGPOINTER for null or invalid pointers.
  - ref
```
public T ref(EPLITYPES check)
```
    De-reference the POINTER by returning the object, first checking to see if it is a valid POINTER reference for this variable type.
    
    Parameters:
    
    check - - an EPLITYPES of the PL/I datatype to verify before returning the pointer.
    
    Returns:
    
    the object reference this POINTER is for.
    
    Throws:
    
    ERROR - Condition with NULLPOINTER or WRONGPOINTER for null or invalid pointers.
  - assign
```
public Pointer<T> assign(T source)
```
    Assign the pointer a reference to the given object of type T. Assign the handle's pointer a new object of the type of associated with the handle's pointer by converting it from the argument to that type.
    
    Parameters:
    
    source - the object to assign to this pointer or handle.
    
    Returns:
    
    this to allow chaining with other Pointer methods.
    
    Throws:
    
    ERROR - Condition with NULLPOINTER or WRONGPOINTER for null or invalid pointers.
  - assign
```
public Pointer<T> assign(int off,
                         int len,
                         java.lang.Object source)
```
    Assign a portion of a (usually) Group member of class T a value referred to by this HANDLE.
    
    Parameters:
    
    off - - the offset within the handle's reference to begin assigning
    
    len - - the length from the offset within the handle's reference to assign
    
    source - - the data to assign
    
    Returns:
    
    this to allow chaining with other Pointer methods.
  - assign
```
public Pointer<T> assign(Pointer<T> ptr)
```
    Assign a handle to a new object pointer.
    
    Parameters:
    
    ptr - the Pointer to replace this with.
    
    Returns:
    
    this to allow chaining with other Pointer methods.
    
    Throws:
    
    ERROR - Condition WRONGPOINTER for null or invalid pointers.
  - assign
```
public Pointer<T> assign(T ref,
                         Area inArea)
```
    Assign a pointer within an area a new object reference.
    
    Parameters:
    
    ref - the object this Pointer points to.
    
    Returns:
    
    this to allow chaining with other Pointer methods.
  - refAssign
```
public Pointer<T> refAssign(byte[] bytes)
```
    assign the underlying (referenced) structure to which this POINTER points the sequence of bytes
    
    Parameters:
    
    bytes - - sequence of bytes representing a Pointer
    
    Returns:
    
    the same pointer
  - handle
```
public Pointer<?> handle()
```
    Return the "handle" to an object of this type T used with this HANDLE or "template" structure associated with this HANDLE or REDEFINED structure. This method is for internal use. Normally, one wants to access the object to which this handle refers and using ref() or assign(Object) is the better way of doing it.
    
    Returns:
    
    the handle (Pointer to an object of a different type other than T to which this pointer refers) without going through the ref() mapping process
    
    Throws:
    
    ERROR - Condition if you are using a model with a regular Pointer and not one that refers to another Pointer as obtained from the ADDR() function (i.e., a handle)
  - model
```
public T model()
```
    Return the "model" or "template" of the class on which this Pointer is based as class "T". Do not modify this object instance in any way.
    
    Returns:
    
    the model in order to see the (usually Group) layout of the actual object instance returned by ref()
    
    Throws:
    
    ERROR - Condition if you are using a model with a regular Pointer and not one that refers to another Pointer as obtained from the ADDR() function (i.e., a handle)
  - free
```
public void free()
```
    Invalidate the object reference. Only when all Pointers have been freed to an object with the Java JVM release storage for it.
    
    Throws:
    
    ERROR - Condition with NULLPOINTER for an unassigned or previously freed pointer.
    
    ERROR - Condition with ADDPOINTERFREE if attempting to free a handle.
  - free
```
public void free(boolean ignore)
```
    Invalidate the object reference, ignoring the ONNULL condition. Only when all Pointers have been freed to an object with the Java JVM release storage for it.
    
    Parameters:
    
    ignore - - ignore any prior freed pointers (free() is a no-op)
    
    Throws:
    
    ERROR - Condition with NULLPOINTER for an unassigned or previously freed pointer.
    
    ERROR - Condition with ADDPOINTERFREE if attempting to free a handle.
  - isNull
```
public boolean isNull()
```
    return true if this Pointer is null
    
    Returns:
    
    true if null, false if Pointer has a pointer or handle value
  - typeof
```
public EPLITYPES typeof()
```
    return the EPLITYPES type of the object pointed to by this pointer or handle
    
    Returns:
    
    if a handle (Pointer to a Pointer), return the EPLITYPE of the inner pointer. If a direct pointer, return its type. An untyped null pointer will return null.
  - toBytes
```
public byte[] toBytes()
```
    turn a Pointer into a sequence of bytes
    
    Returns:
    
    byte array of the Pointer turned into a sequence of bytes
  - fromBytes
```
public Pointer<T> fromBytes(byte[] bytes)
```
    turn a sequence of bytes into a Pointer
    
    Parameters:
    
    bytes - - sequence of bytes representing a Pointer
    
    Returns:
    
    Pointer that was previously Remembered by toBytes()
    
    Throws:
    
    ERROR - Condition if the bytes don't represent a Pointer previously Remembered in this JVM
  - toString
```
public java.lang.String toString()
```
    for debugging info, dump ptr info, put list ptr, etc.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    info about this ptr
  - main
```
public static void main(java.lang.String[] args)
```
    Pointer unit test
  - compareTo
```
public int compareTo(Pointer<T> op2)
```
    compareTo - compare two typed pointers
    
    Specified by:
    
    compareTo in interface java.lang.Comparable<Pointer<T>>
    
    Parameters:
    
    op2 - - the operand to compare to
    
    Returns:
    
    0 if the two are "equal" (contain pointers to the same underlying object); -1 if this pointer is "less than" and +1 if this pointer is "greater than" the operand where hashCode() is used to determine greater or less than
  - equal
```
public boolean equal(java.lang.Object ob2)
```
    equal - compare two typed pointers
    
    Parameters:
    
    ob2 - - the operand to compare to, which should be a Pointer
    
    Returns:
    
    true if the two Pointers refer to the same object or are both NULL, false otherwise

Class Pointer<T>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

BYTES

NULL

ref

model

Constructor Detail

Pointer

Pointer

Pointer

Pointer

Pointer

Method Detail

ref

ref

ref

assign

assign

assign

assign

refAssign

handle

model

free

free

isNull

typeof

toBytes

fromBytes

toString

main

compareTo

equal