Class Layout

java.lang.Object
cl.obcom.desktopfx.layout.Layout
All Implemented Interfaces:
Serializable
public final class Layout extends Object implements Serializable
Collection of fields whose values can be edited with a LayoutMessage.

After creating a layout, its name must be defined using the setName method. Then, the addField method must be called for each field. Finally, the complete method must be called to complete the definition of the layout.

See Also:

  • Constructor Details

    • Layout

      public Layout()
      Creates a new Layout instance for the default JVM locale. Once the layout isComplete, the locale can be changed using setLocale.

    • Layout

      public Layout(Locale locale)
      Creates a new Layout instance for the given locale. If supplied locale is null, the default JVM locale is used. Once the layout isComplete, the locale can be changed using setLocale.
      Parameters:
      locale - the initial locale of the layout (can be null).

  • Method Details

    • getName

      public String getName()
      Returns the name of this layout. It returns null if this layout is not complete.
      Returns:
      the name of this layout or null.

    • setName

      public void setName(String name)
      Changes the name of this layout. This method cannot be used if the layout is complete.
      Parameters:
      name - the name of this layout.
      Throws:
      NullPointerException - if name is null.
      IllegalStateException - if the layout definition is complete.

    • getLength

      public int getLength()
      Returns the sum of the sizes of all the fields of this layout. It returns 0 if this layout is not complete.
      Returns:
      the total field size of this layout.

    • getSignature

      public String getSignature()
      Returns the signature (or checksum) of this layout. It returns null if this layout is not complete.
      Returns:
      the signature (or checksum) of this layout.

    • getLocale

      public Locale getLocale()
      Returns the locale of this layout. This locale is used by fields that are locale-sensitive (such as numeric fields) when they are converted to/from strings. Initially, a layout uses the default JVM locale.
      Returns:
      the locale of this layout or null for default locale.

    • setLocale

      public void setLocale(Locale locale)
      Changes the locale of this layout and all of it's fields. This locale is used by fields that are locale-sensitive (such as numeric fields) when they are converted to/from strings. If supplied locale is null, the default JVM locale is used.
      Parameters:
      locale - the locale of the layout (can be null).
      Throws:
      IllegalStateException - if the layout is not complete.

    • getField

      public LayoutField getField(String name)
      Returns the layout field indexed by the supplied name. Returns null if the field is not defined in the layout, or if the layout is not complete.
      Parameters:
      name - the name of the required field.
      Returns:
      the field indexed by name or null.
      Throws:
      NullPointerException - if name is null.

    • exists

      public boolean exists(String name)
      Returns true if the layout field indexed by the supplied name exists in this layout. It returns false if this layout is not complete.
      Parameters:
      name - the name of the layout field.
      Returns:
      true if the field is defined in this layout.
      Throws:
      NullPointerException - if name is null.

    • fields

      public Collection<LayoutField> fields()
      Returns an unmodifiable collection with the fields contained in this layout. These fields are returned in the order they were added to the layout using the addField method. It returns an empty collection if this layout is not complete.
      Returns:
      an unmodifiable collection of the fields contained in this layout.

    • addField

      public LayoutField addField(FieldType type, String name, int length, int scale, String defval)
      Appends a new field to the collection of fields of this layout. The properties of the new field are specified by the supplied arguments, whose legal values and restrictions are all explained in LayoutField.

      Certain calls to this method must be made in pairs. In particular, if a field of type LIST is added, then this list must be closed (or terminated) adding a field of type LISTEND. This last call does not actually add a LayoutField; it just completes the definition of the list field.

      Parameters:
      type - type of the new field.
      name - name of the new field.
      length - total length of the new field.
      scale - numeric scale of the new field.
      defval - default value of the new field.
      Returns:
      the newly added field or null if type is LISTEND.
      Throws:
      NullPointerException - if an argument is null.
      IllegalArgumentException - if an argument is invalid.
      IllegalStateException - if the layout definition is complete.

    • createField

      public static LayoutField createField(FieldType type, String name, int length, int scale, String defval, int offset, int occurs)
      Creates a new field without a layout. The properties of the new field are specified by the supplied arguments, whose legal values and restrictions are all explained in LayoutField. Fields created with this method can only be used to retrieve/store values in messages. The returned field uses the default JVM locale.
      Parameters:
      type - type of the new field.
      name - name of the new field.
      length - total length of the new field.
      scale - numeric scale of the new field.
      defval - default value of the new field.
      offset - the offset position of the field.
      occurs - the occurrences of the field.
      Returns:
      a new field without a layout.
      Throws:
      NullPointerException - if an argument is null.
      IllegalArgumentException - if type is invalid.

    • createField

      public static LayoutField createField(FieldType type, String name, int length, int scale, String defval, int offset, int occurs, Locale locale)
      Creates a new field without a layout. The properties of the new field are specified by the supplied arguments, whose legal values and restrictions are all explained in LayoutField. Fields created with this method can only be used to retrieve/store values in messages. If supplied locale is null, the default JVM locale is used.
      Parameters:
      type - type of the new field.
      name - name of the new field.
      length - total length of the new field.
      scale - numeric scale of the new field.
      defval - default value of the new field.
      offset - the offset position of the field.
      occurs - the occurrences of the field.
      locale - the locale of the field (can be null).
      Returns:
      a new field without a layout.
      Throws:
      NullPointerException - if an argument is null.
      IllegalArgumentException - if type is invalid.

    • isComplete

      public boolean isComplete()
      Returns true if this layout is complete. A layout is complete when it's name, fields and signature have all been defined. A complete layout is immutable, so none of its properties can be changed.
      Returns:
      true if this layout is complete.

    • complete

      public void complete(String signature)
      Completes the definition of the collection of fields of this layout. The supplied signature is stored so it can later be retrieved using the getSignature() method. Once this method is called, no other calls to the addField method are allowed. In other words, this layout becomes immutable after this method is used.
      Parameters:
      signature - the signature of this layout (can be null).
      Throws:
      IllegalStateException - if the layout definition is complete.

    • toString

      public String toString()
      Creates and returns a string serialization of this layout. The serialization consists of a sequence of three or more text lines. The first line is called the version and starts with the sequence " VR:". The last line is called the checksum and starts with the sequence "CS:". The lines between the version and the checksum lines represent layout fields in the following format: 
      type:length[.scale]:name[:default]
      Overrides:
      toString in class Object
      Returns:
      the serialization of this layout.
      Throws:
      IllegalStateException - if the layout is not complete.

    • normalizeName

      public static String normalizeName(String name)
      Converts supplied name to upper case and replaces "-" by "_".
      Parameters:
      name - the name to be normalized (can be null).
      Returns:
      the normalized version of supplied name.

    • compile

      public static Layout compile(String specification, boolean verifySignature)
      Compiles the given specification into a layout. The first line of the specification provides the name of the layout, and the last line provides it's signature. The lines between the first and the last define the fields of the layout. The following is a sample layout specification: 
      VR:1.0:FMPRA_ING:2021-08-01:18:22:50
N:5:CODIGO
X:1:TIPO:M
N:11.2:VALOR
X:1:ESTADO:A
D:8:FECHAING:*
X:30:DESCRIP
D:8:FECACT:*
CS:64:FMPRA_ING:ONHP2hI8ptNvgfYJSErLqa
      Parameters:
      specification - the specification of the layout.
      verifySignature - if true verify the layout signature.
      Returns:
      the Layout compiled from the supplied specification.
      Throws:
      NullPointerException - if specification is null.
      IllegalArgumentException - if specification is invalid.