sigmlinlib

## Class SiGMLInLib

- java.lang.Object
- - sigmlinlib.SiGMLInLib

- All Implemented Interfaces:
    BytesBlockStreamHandler, StringStreamHandler

      public class SiGMLInLib
      extends java.lang.Object
      implements BytesBlockStreamHandler, StringStreamHandler

  SiGML input and translation library: an instance of this (singleton) class is wrapped by the SiGMLSigning package's `JSiGMLInput` ActiveX class.

  The main function is to provide a SiGML input service via TCP/IP sockets. As part of this function, support is provided for translation between various forms of SiGML, notably the conversion of HamNoSys-like `<hns_sign>` elements to the `<hamgestural_sign>` elements, which are accepted as input by the animgen signing animation package. In addition support is also provided for the translation into SiGML of sign sequences in the legacy HNS and HNST text formats.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `ASI_SIGML_ERROR_TEXT` Index in the `acceptSiGML(String[])` parameter array of the error text for the conversion to gestural SiGML.
    `static int` | `ASI_SIGML_GESTURAL` Index in the `acceptSiGML(String[])` parameter array of the converted SiGML document text, in which each `<hns_sign>` element in the original is replaced by the corresponding `<hamgestural_sign>` element.
    `static int` | `ASI_SIGML_IN` Index in the `acceptSiGML(String[])` parameter array of the original SiGML document input text.
    `static int` | `ASI_SIGML_IN_ERR_COUNT` Index in the `acceptSiGML(String[])` parameter array of the error count for the conversion to gestural SiGML.
    `static int` | `HGI_ERROR_TEXT` Index in the `hnsSignToGestural(String)` result array of the error text for the conversion, which will be the empty string in cases where the conversion succeeds.
    `static int` | `HGI_GESTURAL_SIGML` Index in the `hnsSignToGestural(String)` result array of the converted "Gestural" SiGML sign text.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SiGMLInLib()` Constructs a new SiGML input and translation handler.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `acceptBytesBlock(byte[] bb)` Handler method for the input server's "input data acccepted" notification: this method responds by processing the input and in turn invoking the native client's `acceptSiGML(String[])` notification method.
    `void` | `acceptString(java.lang.String s)` Handler method for the input server's "input data acccepted" notification: this method responds by processing the input and in turn invoking the native client's `acceptSiGML(String[])` notification method.
    `void` | `bytesBlockStreamStarted()` Handler method for the input server's "input started" notification: this method in turn invokes the native client's `noteSIServiceStarted()` notification method.
    `void` | `bytesBlockStreamStopped()` Handler method for the input server's "input shut-down" notification: this method in turn invokes the native client's `noteSIServiceStopped()` notification method.
    `HNSSign[]` | `gesturalSiGMLToHNS(java.lang.String gsigml)` Returns a sequence of `HNSSign`s, one for each `<hamgestural_sign>` element in the given SiGML document text.
    `java.lang.String[]` | `hnsSignToGestural(java.lang.String hnssignel)` Converts a single `<hns_sign>` SiGML element to the equivalent `<hamgestural_sign>` element.
    `java.lang.String[]` | `hnsStdSignsToSiGML(java.lang.String hns)` Converts the given "standard" format HNS text (allowing one line per sign containing gloss, HNS manual string and HNST non-manual string) to an equivalent pair of SiGML document texts, one containing `<hns_sign>` elements, and one containing `<hamgestural_sign>` elements.
    `java.lang.String[]` | `hnstSignsToSiGML(java.lang.String hnst)` Converts the given HNST text to an equivalent pair of SiGML document texts, one containing `<hns_sign>` elements, and one containing `<hamgestural_sign>` elements.
    `void` | `setEnabledLogHML(boolean enabled)` Enables or disables logging to the standard error stream of the intermediate HML text for each HNS sign handled by this library's SiGML-to-Gestural-SiGML converter.
    `java.lang.String[]` | `sigmlSignsToGestural(java.lang.String sigml)` Performs HNS-to-Gestural conversion on the given SiGML document text, i.e.
    `java.lang.String[]` | `sigmlSignsToSync(java.lang.String sigml)` Processes a SiGML document with `begin` attributes to Synchronised SiGML.
    `java.lang.String[]` | `sigmlSignsToTimed(java.lang.String sigml, java.lang.String cas)` Processes a SiGML document and a corresponding CAS document so that each `<hns_sign>` and `<hamgestural_sign>` element has an appropriate `duration` attribute.
    `GSiGMLSign[]` | `sigmlToGSiGMLSigns(java.lang.String sigml)` Returns an array of `GSiGMLSign`s for the given SiGML string.
    `GSiGMLSign[]` | `sigmlToGSiGMLSigns(java.lang.String sigml, java.net.URI baseuri)` Returns an array of `GSiGMLSign`s for the given SiGML string, using the specifed base URI.
    `java.lang.String` | `startSiGMLInputService(int informat, int inport, int stopport)` Starts running the TCP/IP socket-based SiGML input service (or UDP-based broadcast input service), as determined by the given input format, accepting input on the specified port, and using the specified port for service termination, returning an error message in case of failure, or the empty string if the service is successfully established.
    `void` | `stopSiGMLInputService()` Stops the currently running SiGML input service, achieved by establishing a connection to the service's termination port.
    `void` | `stringStreamStarted()` Handler method for the broadcast input server's "input started" notification: this method in turn invokes the native client's `noteSIServiceStarted()` notification method.
    `void` | `stringStreamStopped()` Handler method for the broadcast input server's "input shut-down" notification: this method in turn invokes the native client's `noteSIServiceStopped()` notification method.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### HGI_GESTURAL_SIGML

          public static final int HGI_GESTURAL_SIGML

      Index in the `hnsSignToGestural(String)` result array of the converted "Gestural" SiGML sign text.
      See Also:
        Constant Field Values

    - #### HGI_ERROR_TEXT

          public static final int HGI_ERROR_TEXT

      Index in the `hnsSignToGestural(String)` result array of the error text for the conversion, which will be the empty string in cases where the conversion succeeds.
      See Also:
        Constant Field Values

    - #### ASI_SIGML_IN

          public static final int ASI_SIGML_IN

      Index in the `acceptSiGML(String[])` parameter array of the original SiGML document input text.
      See Also:
        Constant Field Values

    - #### ASI_SIGML_GESTURAL

          public static final int ASI_SIGML_GESTURAL

      Index in the `acceptSiGML(String[])` parameter array of the converted SiGML document text, in which each `<hns_sign>` element in the original is replaced by the corresponding `<hamgestural_sign>` element.
      See Also:
        Constant Field Values

    - #### ASI_SIGML_IN_ERR_COUNT

          public static final int ASI_SIGML_IN_ERR_COUNT

      Index in the `acceptSiGML(String[])` parameter array of the error count for the conversion to gestural SiGML.
      See Also:
        Constant Field Values

    - #### ASI_SIGML_ERROR_TEXT

          public static final int ASI_SIGML_ERROR_TEXT

      Index in the `acceptSiGML(String[])` parameter array of the error text for the conversion to gestural SiGML.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### SiGMLInLib

          public SiGMLInLib()

      Constructs a new SiGML input and translation handler.

  - ### Method Detail

    - #### startSiGMLInputService

          public java.lang.String startSiGMLInputService(int informat,
                                                         int inport,
                                                         int stopport)

      Starts running the TCP/IP socket-based SiGML input service (or UDP-based broadcast input service), as determined by the given input format, accepting input on the specified port, and using the specified port for service termination, returning an error message in case of failure, or the empty string if the service is successfully established.

    - #### stopSiGMLInputService

          public void stopSiGMLInputService()

      Stops the currently running SiGML input service, achieved by establishing a connection to the service's termination port.

    - #### hnsSignToGestural

          public java.lang.String[] hnsSignToGestural(java.lang.String hnssignel)

      Converts a single `<hns_sign>` SiGML element to the equivalent `<hamgestural_sign>` element.
      Parameters:
        `hnssignel` - The text of the HNS sign element to be converted.
      Returns:
        The results of the conversion, as an array of two strings, identified by the standard index values:
        - `HGI_GESTURAL_SIGML` (0: converted Gestural SiGML sign element text), and
        - `HGI_ERROR_TEXT` (1: conversion error text).
        If the conversion succeeds the second array element will be the empty string, but if it fails the first will be the empty string.

    - #### hnstSignsToSiGML

          public java.lang.String[] hnstSignsToSiGML(java.lang.String hnst)

      Converts the given HNST text to an equivalent pair of SiGML document texts, one containing `<hns_sign>` elements, and one containing `<hamgestural_sign>` elements. The result is an array of four strings, like that supplied by `acceptSiGML(String[])`.
      Parameters:
        `hnst` - The HNST text to be converted.
      Returns:
        An array of four strings resulting from the conversion process, identified by the standard indices:
        - `ASI_SIGML_IN` (0: SiGML text containing `<hns_sign>` elements),
        - `ASI_SIGML_GESTURAL` (1: SiGML text containing `<hamgestural_sign>`
        elements),
        - `ASI_SIGML_IN_ERR_COUNT` (2: conversion error count), and
        - `ASI_SIGML_ERROR_TEXT` (3: conversion error text).

    - #### hnsStdSignsToSiGML

          public java.lang.String[] hnsStdSignsToSiGML(java.lang.String hns)

      Converts the given "standard" format HNS text (allowing one line per sign containing gloss, HNS manual string and HNST non-manual string) to an equivalent pair of SiGML document texts, one containing `<hns_sign>` elements, and one containing `<hamgestural_sign>` elements. The result is an array of four strings, like that supplied by `acceptSiGML(String[])`.
      Parameters:
        `hns` - The standard format HNS text to be converted.
      Returns:
        An array of four strings resulting from the conversion process, identified by the standard indices:
        - `ASI_SIGML_IN` (0: SiGML text containing `<hns_sign>` elements),
        - `ASI_SIGML_GESTURAL` (1: SiGML text containing `<hamgestural_sign>`
        elements),
        - `ASI_SIGML_IN_ERR_COUNT` (2: conversion error count), and
        - `ASI_SIGML_ERROR_TEXT` (3: conversion error text).

    - #### sigmlSignsToGestural

          public java.lang.String[] sigmlSignsToGestural(java.lang.String sigml)

      Performs HNS-to-Gestural conversion on the given SiGML document text, i.e. converts each `<hns_sign>` element in the original to an equivalent `<hamgestural_sign>` element. The result is an array of four strings, like that supplied by `acceptSiGML(String[])`.
      Parameters:
        `sigml` - The SiGML document text to be converted.
      Returns:
        An array of four strings resulting from the conversion process, identified by the standard indices:
        - `ASI_SIGML_IN` (0: The original SiGML document text),
        - `ASI_SIGML_GESTURAL` (1: the converted SiGML text in which any `<hns_sign>`s have been replaced by `<hamgestural_sign>` elements),
        - `ASI_SIGML_IN_ERR_COUNT` (2: conversion error count), and
        - `ASI_SIGML_ERROR_TEXT` (3: conversion error text).

    - #### sigmlSignsToTimed

          public java.lang.String[] sigmlSignsToTimed(java.lang.String sigml,
                                                      java.lang.String cas)

      Processes a SiGML document and a corresponding CAS document so that each `<hns_sign>` and `<hamgestural_sign>` element has an appropriate `duration` attribute. The result is an array of four strings, like that supplied by `acceptSiGML(String[])`.
      Parameters:
        `sigml` - The SiGML document text to be converted.
      Returns:
        An array of four strings resulting from the conversion process, identified by the standard indices:
        - `ASI_SIGML_IN` (0: The original SiGML document text),
        - `ASI_SIGML_GESTURAL` (1: the converted SiGML text in which any `<hns_sign>`s have been replaced by `<hamgestural_sign>` elements),
        - `ASI_SIGML_IN_ERR_COUNT` (2: conversion error count), and
        - `ASI_SIGML_ERROR_TEXT` (3: conversion error text).

    - #### sigmlSignsToSync

          public java.lang.String[] sigmlSignsToSync(java.lang.String sigml)

      Processes a SiGML document with `begin` attributes to Synchronised SiGML. The synchronised form has additional `<hns_sign/>` elements to pad out signing to honour the `begin` attributes. The result is an array of four strings, like that supplied by `acceptSiGML(String[])`.
      Parameters:
        `sigml` - The SiGML document text to be converted.
      Returns:
        An array of four strings resulting from the conversion process, identified by the standard indices:
        - `ASI_SIGML_IN` (0: The original SiGML document text),
        - `ASI_SIGML_GESTURAL` (1: the converted SiGML text in which any `<hns_sign>`s have been replaced by `<hamgestural_sign>` elements),
        - `ASI_SIGML_IN_ERR_COUNT` (2: conversion error count), and
        - `ASI_SIGML_ERROR_TEXT` (3: conversion error text).

    - #### sigmlToGSiGMLSigns

          public GSiGMLSign[] sigmlToGSiGMLSigns(java.lang.String sigml)

      Returns an array of `GSiGMLSign`s for the given SiGML string. Each item in this array includes the text of a SiGML element containing the sign's `<hamgestural_sign>` representation, i.e. the sign description in the form required for input to animgen.

      [2010-02: In JASigning this is used only by the unused jarpb class sigmlanim.SiGMLReader, i.e. it's effectively UNUSED]

    - #### sigmlToGSiGMLSigns

          public GSiGMLSign[] sigmlToGSiGMLSigns(java.lang.String sigml,
                                                 java.net.URI baseuri)

      Returns an array of `GSiGMLSign`s for the given SiGML string, using the specifed base URI. Each item in this array includes the text of a SiGML element containing the sign's `<hamgestural_sign>` representation, i.e. the sign description in the form required for input to animgen.

      [2010-02: In JASigning this is used only by the unused jarpb class sigmlanim.SiGMLReader, i.e. it's effectively UNUSED]

    - #### gesturalSiGMLToHNS

          public HNSSign[] gesturalSiGMLToHNS(java.lang.String gsigml)
                                       throws GToHNSSignSiGML.GToHNSException

      Returns a sequence of `HNSSign`s, one for each `<hamgestural_sign>` element in the given SiGML document text. (Currently only manual HNS is supported).
      Parameters:
        `gsigml` - The SiGML document text to be converted.
      Returns:
        The sequence of `HNSSign`s produced by converting the given text.
      Throws:
        `GToHNSSignSiGML.GToHNSException` - A conversion exception.

    - #### bytesBlockStreamStarted

          public void bytesBlockStreamStarted()

      Handler method for the input server's "input started" notification: this method in turn invokes the native client's `noteSIServiceStarted()` notification method.
      Specified by:
        `bytesBlockStreamStarted` in interface `BytesBlockStreamHandler`

    - #### bytesBlockStreamStopped

          public void bytesBlockStreamStopped()

      Handler method for the input server's "input shut-down" notification: this method in turn invokes the native client's `noteSIServiceStopped()` notification method.
      Specified by:
        `bytesBlockStreamStopped` in interface `BytesBlockStreamHandler`

    - #### acceptBytesBlock

          public void acceptBytesBlock(byte[] bb)

      Handler method for the input server's "input data acccepted" notification: this method responds by processing the input and in turn invoking the native client's `acceptSiGML(String[])` notification method.
      Specified by:
        `acceptBytesBlock` in interface `BytesBlockStreamHandler`

    - #### stringStreamStarted

          public void stringStreamStarted()

      Handler method for the broadcast input server's "input started" notification: this method in turn invokes the native client's `noteSIServiceStarted()` notification method.
      Specified by:
        `stringStreamStarted` in interface `StringStreamHandler`

    - #### stringStreamStopped

          public void stringStreamStopped()

      Handler method for the broadcast input server's "input shut-down" notification: this method in turn invokes the native client's `noteSIServiceStopped()` notification method.
      Specified by:
        `stringStreamStopped` in interface `StringStreamHandler`

    - #### acceptString

          public void acceptString(java.lang.String s)

      Handler method for the input server's "input data acccepted" notification: this method responds by processing the input and in turn invoking the native client's `acceptSiGML(String[])` notification method.
      Specified by:
        `acceptString` in interface `StringStreamHandler`

    - #### setEnabledLogHML

          public void setEnabledLogHML(boolean enabled)

      Enables or disables logging to the standard error stream of the intermediate HML text for each HNS sign handled by this library's SiGML-to-Gestural-SiGML converter.