Package com.isode.dsapi.syntax

Class IsodeSyntax<ASNSYNTAX extends BERCodable>

java.lang.Object
com.isode.dsapi.syntax.IsodeSyntax<ASNSYNTAX>
Direct Known Subclasses:
AddressSynonym, DLSubmitPermission, FailoverContext, GlobalDomainIdentifier, IdentifiedDN, MASAP, MTAInfo, PresentationAddress, Redirect, RedirectFilter, RoutingFilter, RTSCredentials
public abstract class IsodeSyntax<ASNSYNTAX extends BERCodable> extends Object
This is an abstract class used to help deal with syntaxes for which an ASN definition is available in isode-asn. The classes use a combination of functionality from the isode-asn classes (which allow getting/setting individual "fields" in a complex value) and the appropriate Isode syntax handler (if available) which allow parsing/printing of string values.

Many of the common functions required by such classes are implemented in this abstract class, although there are some things that it is not possible to do, due to limitations with the generics mechanism.

Validity

The idea of these classes is that they provide an easy way to construct and manipulate values. In the course of manipulating values, it is possible for an object to contain an "illegal" value (for example, you've set the value for one non-optional field, but haven't set the other yet, or you set a "country" field to a value containing ten characters). Individual "set" methods do not throw exceptions for these situations.

The idea of validity is subject to some ambiguity as a result of the way that certain syntax handlers are implemented. For example, the syntax handler for GlobalDomainIdentifier, when parsing string values, disallows ten character country names. But the same syntax handler will not reject a BER encoded value which contains a ten character country name.

Since the DSA stores values in encoded form, a value with a ten character country name is one which could be stored in the DSA (and might be returned when you read an entry). But the string representation of such a value would be considered invalid by the syntax handler's string parsing function (even though the string might have been generated by the same syntax handler's print function).

The getAttributeValue(AttributeType) and getAttributeValue(String) methods may return values whose validity is "ambiguous". While such values will be ones that can be stored in the DSA (and so may be useful to callers), there is no guarantee that they have a string representation that the syntax handler would consider to be legal. The isValid() imposes the strictest form of checking, by putting the value through the syntax handler's decode(), print() and parse() functions, and so should be used by callers who wish to be certain that a given value is valid.

To implement a new syntax handling class, extend this class, and add code as follows:

Define a static variable that contains information about the syntax you're supporting, and then implement a getSyntaxInfo() method which returns a reference to it.

For functionality which relies on the Isode syntax handlers, this class requires that getSyntaxInfo() is returning a valid value (i.e. that the loaded schema has support for the syntax). In cases where no support is available then functionality will be constrained, or BadSyntaxException may be thrown.

Certain of the abstract methods in this class can be implemented in a boiler-plate style (see comments for the methods).

Since:
14.6

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected static class 
    IsodeSyntax.SyntaxInfo
    A SyntaxInfo keeps track of various information that the IsodeSyntax class uses to process string representations of the values.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected ASNSYNTAX
    asnVal
    This member holds the asn representation of the current value
    protected static final com.isode.util.Logger
    logger
     

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    IsodeSyntax()
    Create a new object, and call the subclass reset() method.
    protected
    IsodeSyntax(byte[] ber)
    Construct a new object based on a byte array containing the BER representation of an object.
    protected
    IsodeSyntax(ASNSYNTAX val)
    Create a new object from an existing ASN representation.
    protected
    IsodeSyntax(AttributeValue av)
    Create a new object from a suitable AttributeValue.
    protected
    IsodeSyntax(String val)
    Create a new object from a string representation.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Object other)
    Performs equality testing using the syntax handler for the relevant attribute type.
    ASNSYNTAX
    getAsnVal()
    Return a reference to the underlying asn representation of this object
    AttributeValue
    getAttributeValue(AttributeType at)
    Derive an AttributeValue from the object.
    AttributeValue
    getAttributeValue(String attributeName)
    Returns a new AttributeValue with the specified attribute name containing this object.
    String
    getStringRepresentation()
    Return the printable string value as produced by the syntax handler, if available.
    protected abstract IsodeSyntax.SyntaxInfo
    getSyntaxInfo()
    Subclasses must implement a method which returns a SyntaxInfo object that can be used by the IsodeSyntax class.
    int
    hashCode()
    Returns a hashcode suitable for use by the Collection classes
    static boolean
    isNumeric(String str)
    Check for a numeric string.
    boolean
    isValid()
    Determine whether the object represents a valid value.
    protected boolean
    isValidStringValue(String value, AttributeType at)
    Determine whether a given String is a valid value for this type of attribute
    protected abstract void
    parse(byte[] berRepresentation)
    Set the object to contain a value based on the specified BER representation.
    abstract void
    reset()
    Clear all fields in the object.
    void
    set(String str)
    Set the current value by parsing a string representation.
    String
    toString()
    Return a String representation of this value, for debugging.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • logger

      protected static final com.isode.util.Logger logger

    • asnVal

      protected ASNSYNTAX extends BERCodable asnVal
      This member holds the asn representation of the current value

  • Constructor Details

    • IsodeSyntax

      protected IsodeSyntax()
      Create a new object, and call the subclass reset() method. This is useful for subclass constructors which are creating a value based on a series of values that will be used to for fields.

    • IsodeSyntax

      protected IsodeSyntax(ASNSYNTAX val)
      Create a new object from an existing ASN representation.
      Parameters:
      val - an ASN value, which must not be null. The contents of this object will be copied.

    • IsodeSyntax

      protected IsodeSyntax(String val) throws BadValueException, BadSyntaxException
      Create a new object from a string representation.

      Typically, a subclass provides a corresponding constructor which looks like this 

       public MySyntax(String s) throws BadValueException, BadSyntaxException {
    super(s);
 }
      Parameters:
      val - String representation. Must not be null.
      Throws:
      BadValueException - if str is not a valid String value for this type of attribute
      BadSyntaxException - it is not possible to parse this type of value

    • IsodeSyntax

      protected IsodeSyntax(AttributeValue av) throws BadValueException, BadSyntaxException
      Create a new object from a suitable AttributeValue.

      Typically, a subclass provides a corresponding constructor which looks like this 

       public MySyntax(AttributeValue av) throws BadValueException {
    super(av);
 }
      Parameters:
      av - AttributeValue. Must not be null.
      Throws:
      BadValueException - if av is not a valid GlobalDomainIdentifier
      BadSyntaxException - it is not possible to parse this type of value

    • IsodeSyntax

      protected IsodeSyntax(byte[] ber) throws BadValueException
      Construct a new object based on a byte array containing the BER representation of an object.

      Typically, a subclass provides a corresponding constructor which looks like this 

       public MySyntax(byte[] ber) throws BadValueException {
    super(ber);
 }
      Parameters:
      ber - BER representation of a value
      Throws:
      BadValueException - if ber doesn't hold a valid value for this attribute type

  • Method Details

    • getSyntaxInfo

      protected abstract IsodeSyntax.SyntaxInfo getSyntaxInfo() throws BadSyntaxException
      Subclasses must implement a method which returns a SyntaxInfo object that can be used by the IsodeSyntax class.
      Returns:
      a SyntaxInfo describing the syntax represented by the subclass.
      Throws:
      BadSyntaxException - if no SyntaxInfo is available for this syntax.

    • parse

      protected abstract void parse(byte[] berRepresentation) throws BadValueException
      Set the object to contain a value based on the specified BER representation. If the BER is not valid, and exception will be thrown and the object will retain its previous value.

      Subclasses must implement a suitable syntax-specific method, which will contain code like this: 

       protected void parse(byte[] berRepresentation) throws BadValueException  {
    com.isode.asn.modules.MHSR.GlobalDomainIdentifie savedVal = asnVal;
    try {
       asnVal = ASNConv.decode(
             berRepresentation,
             com.isode.asn.modules.MHSR.GlobalDomainIdentifier.class);
    } catch (BadValueException e) {
       asnVal = savedVal;
       throw e;
    }
 }
      (Replace the second parameter to the decode() method with a reference to the appropriate class).
      Parameters:
      berRepresentation - putative value in BER
      Throws:
      BadValueException

    • reset

      public abstract void reset()
      Clear all fields in the object. Following this operation, the object may not be a valid value, so may need to have fields set in it to become one.

      Subclasses should implement a method which clears all the asn fields, e.g. 

         asnVal = new MHSR.GlobalDomainIdentifier();
   asnVal.setAdministration_domain_name(new AdministrationDomainName());
   asnVal.setCountry_name(new CountryName());
      Note that this method is called by the IsodeSyntax() constructor.

    • set

      public void set(String str) throws BadValueException, BadSyntaxException
      Set the current value by parsing a string representation. If an error occurs, then the value remains unchanged.
      Parameters:
      str - a String representation of a value for this type of attribute
      Throws:
      BadValueException - str is null, or if it does not represent a valid value for this type. The object's value is left unchanged.
      BadSyntaxException - it is not possible to parse strings for this type of attribute. The object's original value is left unchanged.

    • isNumeric

      public static boolean isNumeric(String str)
      Check for a numeric string. Can be useful when setting fields which are a CHOICE of numeric or printable
      Parameters:
      str - String to check.
      Returns:
      true if string is numeric, false otherwise.

    • getAttributeValue

      public AttributeValue getAttributeValue(AttributeType at) throws BadSyntaxException, BadValueException
      Derive an AttributeValue from the object. To do this, callers must provide a suitable AttributeType object (which is required in order to construct a new AttributeValue). For example: 
         AttributeValue av = obj.getAttributeValue(new AttributeType("cn"));

      See notes above validity.

      Parameters:
      at - an AttributeType which should be used to create the new AttributeValue
      Returns:
      an AttributeValue, whose type will be determined by at and whose value is derived from this object
      Throws:
      BadSyntaxException - if at is not an AttributeType which has the right syntax, or if no syntax handlers are available for this type of attribute.
      BadValueException - if an error occurs when attempting to encode the value

    • getAttributeValue

      public AttributeValue getAttributeValue(String attributeName) throws BadAttributeTypeException, BadValueException, BadSyntaxException
      Returns a new AttributeValue with the specified attribute name containing this object.

      See notes above validity.

      Parameters:
      attributeName - the name of the attribute (which must have the correct syntax).
      Returns:
      an AttributeValue with the appropriate syntax that contains the contents of the current object
      Throws:
      BadAttributeTypeException - if attributeName is not an attribute of the correct syntax
      BadSyntaxException - if the schema does not know about this syntax.
      BadValueException - if the current object does not contain a legal value for this attribute type.
      See Also:

    • isValidStringValue

      protected boolean isValidStringValue(String value, AttributeType at)
      Determine whether a given String is a valid value for this type of attribute
      Parameters:
      value - string to be tested
      Returns:
      true if it appears to be legal, false otherwise

    • isValid

      public boolean isValid()
      Determine whether the object represents a valid value. This method is intended to allow UI applications to let the user know whether a given value is legal, and so tries to be as strict as possible, using the syntax handler's decode(), parse() and print() routines where possible.

      Note that if this method returns false, that does not necessarily mean that the value would be rejected by the DSA (see comments in the code for more detailed information). A return value of true does mean that the DSA will accept this value though.

      See notes above validity.

      Returns:
      true if this is a valid value according to the syntax handler, false if it's not, or if validity cannot be determined because there is no syntax handler.

    • getAsnVal

      public ASNSYNTAX getAsnVal()
      Return a reference to the underlying asn representation of this object
      Returns:
      the asn value (which will be a BERCodable object).

    • equals

      public boolean equals(Object other)
      Performs equality testing using the syntax handler for the relevant attribute type.

      Note that this method uses JNI to constructs AttributeValues and then call the syntax handler's comparison function, so it may not be ideal for use in resource-constrained situations (e.g. calling it loads of times in a loop)

      Overrides:
      equals in class Object
      Parameters:
      other - another object of the same attribute type
      Returns:
      true if other is the same object, or one which has a valid value that matches this object's value so far as the syntax handler is concerned. A value of false means that object contains a different value, or that it is not possible to compare the values because no suitable syntax handler is available.

    • hashCode

      public int hashCode()
      Returns a hashcode suitable for use by the Collection classes
      Overrides:
      hashCode in class Object
      Returns:
      a hash code value for this object.

    • getStringRepresentation

      public String getStringRepresentation() throws BadValueException
      Return the printable string value as produced by the syntax handler, if available.
      Returns:
      String representation of the value from syntax handler. This will be null if the attribute type has no string representation, or if there's no syntax handler available.
      Throws:
      BadValueException - if the value is not valid for this syntax.
      See Also:

    • toString

      public String toString()
      Return a String representation of this value, for debugging.

      If the value is valid and printable, then its printable string value will be returned. Otherwise a value derived from the underlying ASN value will be returned. For an empty value, the string "" will be returned.

      Overrides:
      toString in class Object
      Returns:
      a String representation of the value, or the empty string in the case of a null value
      See Also: