com.ibm.jzos.fields
Class StringField

java.lang.Object
  extended by com.ibm.jzos.fields.StringField
All Implemented Interfaces:
Field

public class StringField
extends java.lang.Object
implements Field

A String Field.


Field Summary
static java.lang.String DEFAULT_ENCODING
           
static char HIGH_VALUE
          The Unicode character that translates to EBCDIC 0xFF using Cp1047
 
Constructor Summary
StringField(int offset, int length)
          Construct an instance with trim=true, padLeft=false, and allowTruncation=true.
StringField(int offset, int length, boolean trim)
          Construct an instance with padLeft=false and allowTruncation=true.
StringField(int offset, int length, boolean trim, boolean padLeft)
          Construct an instance with allowTruncation=true.
StringField(int offset, int length, boolean trim, boolean padLeft, boolean allowTruncation)
          Construct an instance.
StringField(int offset, int length, boolean trim, boolean padLeft, boolean allowTruncation, java.lang.String encoding)
          Construct an instance.
 
Method Summary
 boolean equals(java.lang.String aString1, java.lang.String aString2)
          Compare two Strings, possible null, for equality.
 int getByteLength()
          Answer the length of the field described by the receiver
 java.lang.String getEncoding()
          Return the configured (EBCDIC variant) encoding for this field.
 int getOffset()
          Answer the offset of this field into some array of bytes
 java.lang.String getString(byte[] bytes)
          Return a String from the given byte array buffer, at the offset of this field.
 java.lang.String getString(byte[] bytes, int bufOffset)
          Return a String from the given byte array buffer, at the bufOffset + offset of this field.
 boolean isAllowTruncation()
           
 boolean isPadLeft()
           
 boolean isTrim()
           
static java.lang.String makeString(int len, char ch)
          A static helper method which answers a new String of a given size and filled with a given character.
 void putString(java.lang.String string, byte[] bytes)
          Put a String into the given byte array buffer, at the offset of this field.
 void putString(java.lang.String string, byte[] bytes, int bufOffset)
          Put a String into the given byte array buffer, at the bufOffset + offset of this field.
 void setAllowTruncation(boolean allowTruncation)
          Set whether or not to allow truncation of String values larger than the underlying byte length.
 void setByteLength(int len)
          Sets the byte length of the field
 void setEncoding(java.lang.String encoding)
          Set the (EBCDIC variant) encoding for this field.
 void setOffset(int offset)
           
 void setPadLeft(boolean padLeft)
          Set to true if the field will right justify String values that are shorter than the underlying field length.
 void setTrim(boolean trim)
          Set to true if the String value obtained from the underlying byte array are to be blank trimmed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

HIGH_VALUE

public static final char HIGH_VALUE
The Unicode character that translates to EBCDIC 0xFF using Cp1047

See Also:
Constant Field Values

DEFAULT_ENCODING

public static final java.lang.String DEFAULT_ENCODING
See Also:
Constant Field Values
Constructor Detail

StringField

public StringField(int offset,
                   int length)
Construct an instance with trim=true, padLeft=false, and allowTruncation=true.

Parameters:
offset - int the offset in some byte array to the start of this field
length - int the size of the field in bytes

StringField

public StringField(int offset,
                   int length,
                   boolean trim)
Construct an instance with padLeft=false and allowTruncation=true.

Parameters:
offset - int the offset in some byte array to the start of this field
length - int the size of the field in bytes
trim - true if the String returned from the underlying byte array is to be trimmed of leading (padLeft == true) or trailing (padLeft == false) blanks.

StringField

public StringField(int offset,
                   int length,
                   boolean trim,
                   boolean padLeft)
Construct an instance with allowTruncation=true.

Parameters:
offset - int the offset in some byte array to the start of this field
length - int the size of the field in bytes
trim - true if the String returned from the underlying byte array is to be trimmed of leading (padLeft == true) or trailing (padLeft == false) blanks.
padLeft - true if small values are to be left padded with blanks

StringField

public StringField(int offset,
                   int length,
                   boolean trim,
                   boolean padLeft,
                   boolean allowTruncation)
Construct an instance.

Parameters:
offset - int the offset in some byte array to the start of this field
length - int the size of the field in bytes
trim - true if the String returned from the underlying byte array is to be trimmed of leading (padLeft == true) or trailing (padLeft == false) blanks.
padLeft - true if small values are to be left padded with blanks
allowTruncation - true if large Strings are to be right truncated. If false an IllegalArgumentException will be thrown.

StringField

public StringField(int offset,
                   int length,
                   boolean trim,
                   boolean padLeft,
                   boolean allowTruncation,
                   java.lang.String encoding)
Construct an instance.

Parameters:
offset - int the offset in some byte array to the start of this field
length - int the size of the field in bytes
trim - true if the String returned from the underlying byte array is to be trimmed of leading (padLeft == true) or trailing (padLeft == false) blanks.
padLeft - true if small values are to be left padded with blanks
allowTruncation - true if large Strings are to be right truncated. If false an IllegalArgumentException will be thrown.
encoding - the character set encoding. This is assumed to be an EBCDIC variant.
Method Detail

makeString

public static java.lang.String makeString(int len,
                                          char ch)
A static helper method which answers a new String of a given size and filled with a given character.

Parameters:
len - the length of the String to create
ch - the character which will fill the String

getByteLength

public int getByteLength()
Description copied from interface: Field
Answer the length of the field described by the receiver

Specified by:
getByteLength in interface Field
Returns:
int
See Also:
Field.getByteLength()

setByteLength

public void setByteLength(int len)
Sets the byte length of the field


getOffset

public int getOffset()
Description copied from interface: Field
Answer the offset of this field into some array of bytes

Specified by:
getOffset in interface Field
Returns:
int
See Also:
Field.getOffset()

setOffset

public void setOffset(int offset)
Specified by:
setOffset in interface Field
See Also:
Field.setOffset(int)

getString

public java.lang.String getString(byte[] bytes)
Return a String from the given byte array buffer, at the offset of this field.

Parameters:
bytes - the byte array
Returns:
String

getString

public java.lang.String getString(byte[] bytes,
                                  int bufOffset)
Return a String from the given byte array buffer, at the bufOffset + offset of this field.

Parameters:
bytes - the byte array
bufOffset - the additional offset into the byte array
Returns:
String

putString

public void putString(java.lang.String string,
                      byte[] bytes)
Put a String into the given byte array buffer, at the offset of this field.

Parameters:
string - the String value
bytes - the byte array
Throws:
java.lang.IllegalArgumentException - if the String value is too long to fit into the buffer and allowTruncation == false.
java.lang.RuntimeException - if the configured encoding is not supported

putString

public void putString(java.lang.String string,
                      byte[] bytes,
                      int bufOffset)
Put a String into the given byte array buffer, at the bufOffset + offset of this field.

Parameters:
string - the String value
bytes - the byte array
bufOffset - the additional offset into the byte array
Throws:
java.lang.IllegalArgumentException - if the String value is too long to fit into the buffer and allowTruncation == false.
java.lang.RuntimeException - if the configured encoding is not supported

getEncoding

public java.lang.String getEncoding()
Return the configured (EBCDIC variant) encoding for this field. If the field encoding is null, check to see if the jzos.fields.string.encoding property is set. If not, use the default encoding (Cp1047).

Returns:
String encoding

setEncoding

public void setEncoding(java.lang.String encoding)
Set the (EBCDIC variant) encoding for this field.

Parameters:
encoding - the EBCDIC encoding

isAllowTruncation

public boolean isAllowTruncation()
Returns:
true if this field allows truncation of String values larger than the underlying byte length.

setAllowTruncation

public void setAllowTruncation(boolean allowTruncation)
Set whether or not to allow truncation of String values larger than the underlying byte length. If set to false and an oversized String is supplied, an IllegalArgumentException will be thrown. If true, the String will be truncated on the right to fit.

Parameters:
allowTruncation -

isPadLeft

public boolean isPadLeft()
Returns:
true if the field will right justify String values that are shorter than the underlying field length.

setPadLeft

public void setPadLeft(boolean padLeft)
Set to true if the field will right justify String values that are shorter than the underlying field length. If false, short String values are left justfied.


isTrim

public boolean isTrim()
Returns:
true if the String value obtained from the underlying byte array is blank trimmed. The trimming will occur on the left if padLeft == true, otherwise the trimming will occur on the right.

setTrim

public void setTrim(boolean trim)
Set to true if the String value obtained from the underlying byte array are to be blank trimmed. The trimming will occur on the left if padLeft == true, otherwise the trimming will occur on the right.


equals

public boolean equals(java.lang.String aString1,
                      java.lang.String aString2)
Compare two Strings, possible null, for equality.

Parameters:
aString1 -
aString2 -
Returns:
boolean true if equal, false otherwise