com.heirloomcomputing.epli.runtime

Class Group

java.lang.Object

com.heirloomcomputing.epli.runtime.Group

Direct Known Subclasses:

Dfhaid, Dfheiblk

public class Group
extends java.lang.Object

Elastic PL/I base class for all Variable Groups (structures). Groups in EPLI are represented by classes which inherit this class

Author:

Heirloom Computing, Inc.

Constructor Summary

Constructors

Constructor and Description
Group() Constructor super of inherited Group classes
Group(java.lang.Object from) Constructor to create a group from something that wasn't originally intended to be a group, such as a String, Integer, etc.

Method Summary

Modifier and Type	Method and Description
Group	assign(java.lang.Object fromObj) Distribute a value along each element of a structure on a byte-by-byte basis.
Group	assignByField(Group from) assign on a field-by-field basis the given Group parameter to this Group.
Group	assignByName(Group from) assign on a field-by-field basis the given Group parameter to this Group only where structure names match.
int	compareTo(Group anotherGroup) Compare two structures (Group), this and anotherGroup.
int	compareTo(java.lang.String op2) Compare a structure (Group) when represented as a String to another String.
boolean	equals(Group anotherGroup) Return if two groups are equal, same as this.compareTo(anotherGroup)==0
java.lang.Object[]	findElement(java.lang.String fullName) Find an element by name within this group using reflection taking into account that the class structure may be embedded within program classes (e.g., MyProg$1MyGroup$2MySubGroup$3MyElement)
void	fromBytes(byte[] bytes) Use reflection to assign each Group's field from byte array segment
int	getSize() same as length
Group	init(java.lang.Object value) Initialize each element of a structure to a value, often seen in A = '' or A(*) = '' where A is a structure or an array of structures
int	length() Use reflection to determine each Group's field size and return it
static void	main(java.lang.String[] args) unit test
void	setElement(java.lang.Object field, java.lang.Object element, java.lang.Object value) setElement - for a previously found element via findElement(name), set the value of that field
byte[]	toByteArray() toByteArray - synonym for toBytes()
byte[]	toBytes() Use reflection to convert each Group's field into a byte array
java.lang.String	toString() Use reflection to convert each Group's field into a string
static Group	valueOf(java.lang.Object from) static factory method creating a group

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Group

public Group()

Constructor super of inherited Group classes

Group

public Group(java.lang.Object from)

Constructor to create a group from something that wasn't originally intended to be a group, such as a String, Integer, etc. Used in RECORD FILE operations

Method Detail

valueOf

public static Group valueOf(java.lang.Object from)

static factory method creating a group

compareTo

public int compareTo(Group anotherGroup)

Compare two structures (Group), this and anotherGroup.

Parameters:

anotherGroup - - a group to compare with this one

Returns:

0 if the two groups' contents have identical values; a value less than 0 if this Group's contents are numerically less than the argument Group's corresponding field; and a value greater than 0 if this Group's contents are numerically greater than the argument Group. Note that if the group contain different numbers of fields, a value of greater than 0 is returned if this Group has more fields; a value of less than 0 is returned if this Group has fewer numbers of fields if the two groups' values are equivalent up to the lower number of fields

compareTo

public int compareTo(java.lang.String op2)

Compare a structure (Group) when represented as a String to another String.

Parameters:

op2 - - a String to compare with this Group

Returns:

0 if the group-as-a-string and the string have an identical value; a value less than 0 if this Group's contents are numerically less than the argument string's corresponding field; and a value greater than 0 if this Group's contents are numerically greater than the argument string.

findElement

public java.lang.Object[] findElement(java.lang.String fullName)

Find an element by name within this group using reflection taking into account that the class structure may be embedded within program classes (e.g., MyProg$1MyGroup$2MySubGroup$3MyElement)

Parameters:

fullName - - the name to find, which might include array indexes and other subgroups, but does not include the top level variable or class name

Returns:

an Object array with exactly 3 objects, index 0 is the element object (value), index 1 the Field corresponding, index 2 the group the field is in (this or a sub-Group within this). this Object[] is intended to be used in setEelement() if the value is to be changed

Throws:

NAME - Condition if name could not be found

setElement

public void setElement(java.lang.Object field,
                       java.lang.Object element,
                       java.lang.Object value)

setElement - for a previously found element via findElement(name), set the value of that field

Parameters:

field - - the Field object of an element within this Group

element - - the element to set (only used to verify old and new values are of the same type)

value - - the value to set

equals

public boolean equals(Group anotherGroup)

Return if two groups are equal, same as this.compareTo(anotherGroup)==0

Parameters:

anotherGroup - - the source group (this group is destination)

Returns:

this - to allow easier chaining

toString

public java.lang.String toString()

Use reflection to convert each Group's field into a string

Overrides:

toString in class java.lang.Object

Returns:

an unmarshalled String of each field concatenated

toBytes

public byte[] toBytes()

Use reflection to convert each Group's field into a byte array

Returns:

byte array of each field concatenated with one another

toByteArray

public byte[] toByteArray()

toByteArray - synonym for toBytes()

length

public int length()

Use reflection to determine each Group's field size and return it

Returns:

total length of the Group if returned as toBytes()

getSize

public int getSize()

same as length

Returns:

the length if converted to a byte array

fromBytes

public void fromBytes(byte[] bytes)

Use reflection to assign each Group's field from byte array segment

Parameters:

bytes - - the input buffer or null if we're meant to ignore this operation

assignByField

public Group assignByField(Group from)

assign on a field-by-field basis the given Group parameter to this Group. The two groups are expected to have the same field structure, although the field names may differ. The result will be the from Group and this Group sharing the object instances of each file.

 DCL 1 G1,
     2 G2,
       3 G2F1 FIXED BIN(15) INIT(3),
       3 G2F2 FLOAT DEC(10,5) DIM(10) init(7.0),
     2 G1F3 CHAR(10) INIT('is g1f3');
 DCL 1 G3,
     2 G4,
       3 G4F4 FIXED BIN(15),
       3 G4F5 FLOAT DEC(10,5) DIM(10),
     2 G3F6;
 G3 = G1, BY STRUCTURE     // assign field objects using assignByField()
 //G3 = G1;                // copy values by bytes using assign()
 //G3 = G1, BY NAME;       // assign field objects by field names using assignByName()
 as Java
    public class G1 {
       public class G2 {
          public Short G2F1 = Short.value((Short)3);
          public Array G2F2 = new Array("G2F2", 7.0);
       }
       public G2 g2 = new G2();
       public @CHAR(10) String g1f3 = new String("is g1f3");
    };
    public class G3 {
       public class G4 {
          public Short G4F4 = Short.value((Short)3);
          public Array G4F5 = new Array("G2F2", 7.0);
       }
       public G4 g4 = new G4();
       public @CHAR(10) String g3f6 = new String("");
    };
    G1 g1 = new G1();
    G3 g3 = (new G3()).assignByField(g1);
    assert (g1.g2.g2f1 == g3.g4.g4f4) && (g1.g2.g2f2.get(5) == g3.g4.g4f5.get(5)) &&
           (g1.g2f3 == g3.g3f6);
 

Parameters:

from - - the Group superclass from which content is to be copied into this Group

Returns:

this - for ease of chaining

Throws:

Condition - CONDITION.CONVERSION - if the structures of the two Group's subclasses do not line up on number of fields, field type or field size

assign

public Group assign(java.lang.Object fromObj)

Distribute a value along each element of a structure on a byte-by-byte basis. this Group structure need not match the fromObj structure, if it is a group or even can be a non-group. copying continues through the shorter of this and fromObj.

Parameters:

fromObj - - the object from which to copy into this structure

Returns:

this for ease of chaining Group methods see example above.

    G1 g1 = new G1();
    G3 g3 = (new G3()).assign(g1);
    assert (g1.g2.g2f1.shortValue() == g3.g4.g4f4.shortValue()) &&
           (g1.g2.g2f2.get(5).doubleValue() == g3.g4.g4f5.get(5).doubleValue()) &&
           (g1.g2f3.equals(g3.g3f6));
 

assignByName

public Group assignByName(Group from)

assign on a field-by-field basis the given Group parameter to this Group only where structure names match. The result will be the from Group and this Group sharing the object instances of each file. note: compiling with "-out:style ENCAPSULATION" and using a copy constuctor is better when the two structures are exactly the same type see example above

    G1 g1 = new G1();
    G1 g11= (new G1()).assignByName(g1);
    assert (g1.g2.g2f1 == g11.g2.g2f1) && (g1.g2.g2f2.get(5) == g11.g2.g2f2.get(5)) &&
           (g1.g2f3 == g11.g2f3);
 or, if compiled with "-out:style ENCAPSULATION" which creates getters/setters and a copy constructor
    G1 g1 = new G1();
    G1 g11 = new G1(g1);
 

Parameters:

from - - the Group superclass from which content is to be copied into this Group

Throws:

Condition.CONDITION.CONVERSION - - conversion between like-named but type-differing fields can't be converted

init

public Group init(java.lang.Object value)

Initialize each element of a structure to a value, often seen in A = '' or A(*) = '' where A is a structure or an array of structures

Parameters:

value - - the scalar value to assign each element of a structure or an array of structures

Returns:

this for ease of chaining Group methods

Note: difference between init() and assign() is that init() will assign each element of the structure the same value (converted to the type of that element) while assign() will distribute portions of the value (based on the byte size of the element) to elements in the structure, resulting in different values being set for each element.

main

public static void main(java.lang.String[] args)

unit test