Package com.isode.dsapi.syntax.mhs

Class ORAddress

java.lang.Object
com.isode.dsapi.syntax.mhs.ORAddress
public class ORAddress extends Object
Class representation of an O/R address.

This class uses the MTA.ORAddress class to encode/decode an ORAddress. The ASN definition has: 

ORAddress ::= SEQUENCE {
    standard-attributes StandardAttributes,
    domain-defined-attributes DomainDefinedAttributes OPTIONAL,
    extension-attributes ExtensionAttributes OPTIONAL }
An ORAddress object (as represented by this class) may contain a value that is not a complete and legal ORAddress. This is to allow applications to construct an empty object and then add fields to it without requiring that a valid representation exist at all times (which is typically done e.g. by UIs that may be manipulating an ORAddress).

For compatibility reasons with earlier implementations, the toString() method of this class return an empty String ("") for objects which do not represent valid ORAddress values. Use getString() or isValid() to detect error conditions.

An ORAddress object can be constructed either to be empty (e.g. using new ORAddress()) or using an AttributeValue or String value.

For any ORAddress which contains a valid combination of components, the getAttributeValue() method can be used to return an AttributeValue containing the ORAddress.

The set(int,String) method may be used to set individual fields in an ORAddress, but note that doing this can result in an "invalid" ORAddress. For example, it is not legal to have an ORAddress that contains a generation-qualifier unless it also contains a surname. Since it may be useful to set fields in an arbitrary order, the set(int,String) method may result in an "invalid" ORAddress, in which case getAttributeValue() will throw an exception. The isValid() method may be used to determine whether an ORAddress contains a valid value.

Note that this class does not handle teletex or universal string values (with the one exception of teletex common-name). Any teletex or universal values are passed through but cannot be read or written. Only printable-string values are accessible.

  • Field Details

    • avType

      public static final String avType
      The name of the attribute type expected to be in the schema for this syntax.
      See Also:

    • avName

      public static final String avName
      The name of the attribute expected to be present in the schema for this syntax.
      See Also:

  • Constructor Details

    • ORAddress

      public ORAddress(MTA.ORAddress val)
      Create a new ORAddress object from an existing ASN value.
      Parameters:
      val - an ASN value, which must not be null. The contents of this object will be copied.
      Since:
      14.4

    • ORAddress

      public ORAddress(String str) throws BadValueException, BadSyntaxException
      Create a new ORAddress object from a string representation.
      Parameters:
      str - String representation. A null value, or blank String ("") creates an empty object.
      Throws:
      BadValueException - if str is not a valid ORAddress.
      BadSyntaxException - if the schema does not know about ORAddress.

    • ORAddress

      public ORAddress(AttributeValue av) throws BadValueException, BadSyntaxException
      Create a new ORAddress object from a suitable AttributeValue.
      Parameters:
      av - AttributeValue. Must not be null, and must be of a type that permits ORAddress values
      Throws:
      BadValueException - if av is not a valid ORAddress
      BadSyntaxException - if the schema does not know about ORAddress.

    • ORAddress

      public ORAddress(byte[] ber) throws BadValueException
      Construct a new object based on a byte array containing the BER representation of an ORAddress.
      Parameters:
      ber - BER representation of an ORAddress value
      Throws:
      BadValueException - if ber doesn't hold a valid ORAddress value
      Since:
      14.4

    • ORAddress

      public ORAddress()
      Create an empty object. This will not be a valid ORAddress, but can become one as fields are set appropriately.

  • Method Details

    • parseADORAddress

      public static ORAddress parseADORAddress(String str) throws BadValueException
      Create an ORAddress from an Active Directory-format O/R Address. Throws an exception if there are any problems decoding the value.

      Note that we make no attempt to handle any characters outside of the printable-string set. AD normally doesn't permit non-printable-string characters to be entered. If any other UTF-8 characters occur in the data, then constructing an attribute from the ORAddress will give an exception.

      Returns:
      ORAddress
      Throws:
      BadValueException - Bad value
      Since:
      14.5

    • getADString

      public String getADString()
      Return the Active Directory-format O/R address represented by this ORAddress structure. Note that this only sees the printable-string values in the ORAddress. If there are any teletex or universal strings, they are ignored.
      Since:
      14.5

    • getString

      public String getString() throws BadValueException, BadSyntaxException
      Return the O/R address string value (in Isode/RFC-2156 format)
      Returns:
      String representation of O/R address
      Throws:
      BadValueException
      BadSyntaxException
      Since:
      14.5
      See Also:

    • toString

      public String toString()
      Return the O/R address string value.
      Overrides:
      toString in class Object
      Returns:
      String representation of O/R address, or the empty string ("") if not set or invalid. (Use getString() if failures aren't to be silently ignored).
      See Also:

    • getCountryName

      public String getCountryName()
      Return the country name component as a String
      Returns:
      country name, or null if none is set.

    • getADMD

      public String getADMD()
      Return the ADMD as a String
      Returns:
      the ADMD, or null if none is set

    • getPRMD

      public String getPRMD()
      Return the PRMD as a String
      Returns:
      the PRMD, or null if none is set

    • getOrganizationName

      public String getOrganizationName()
      Return the organization name as a String
      Returns:
      the organization name, or null if none is set

    • getNetworkAddress

      public String getNetworkAddress()
      Return the network address as a String
      Returns:
      the network address, or null if none is set

    • getTerminalID

      public String getTerminalID()
      Return the terminal id as a String
      Returns:
      the terminal id, or null if none is set

    • getNumericUserID

      public String getNumericUserID()
      Return the numeric user id as a String
      Returns:
      the numeric user id, or null if none is set

    • getSurname

      public String getSurname()
      Return the surname as a String
      Returns:
      the surname, or null if none is set

    • getGivenName

      public String getGivenName()
      Return the given name as a String
      Returns:
      the given name, or null if none is set

    • getInitials

      public String getInitials()
      Return the initials as a String
      Returns:
      the initials, or null if none is set

    • getGenerationQualifier

      public String getGenerationQualifier()
      Return the generation qualifier as a String
      Returns:
      the generation qualifier, or null if none is set

    • getOU

      public String getOU(int index)
      Return an OU as a String
      Parameters:
      index - the index of the OU to return (starting at 0)
      Returns:
      the specified OU, or null if none matches

    • getCommonName

      public String getCommonName()
      Return the common name, if set
      Returns:
      common name as a String, or null if none set

    • getTeletexCommonName

      public String getTeletexCommonName()
      Return teletex-common-name, if set
      Returns:
      the teletex-common-name as a String, or null if none set

    • getCommonNameAsAttributeValue

      public Attribute getCommonNameAsAttributeValue()
      Fetches the Printable String version of the Common Name attribute as an AttributeValue.
      Returns:
      AttributeValue or null

    • getTeletexCommonNameAsAttributeValue

      public Attribute getTeletexCommonNameAsAttributeValue()
      Fetches the Teletex version of the Common Name attribute as an AttributeValue.
      Returns:
      Attribute or null

    • getCommonNameAsAttributValueWrapper

      public Attribute getCommonNameAsAttributValueWrapper()
      Attempts to return CN Teletex string first, then if that fails attempts to return CN as Printable String. In both cases, still encoded as an AttributeValue
      Returns:
      AttributeValue or null

    • getASN

      public MTA.ORAddress getASN()
      Return the ASN structure corresponding to the ORAddress
      Returns:
      an ASN object containing the ORAddress

    • setCountryName

      public void setCountryName(String newval)
      Set the country name
      Parameters:
      newval - new country name, or null for no value

    • setADMD

      public void setADMD(String newval)
      Set the ADMD
      Parameters:
      newval - new ADMD, or null for no value

    • setPRMD

      public void setPRMD(String newval)
      Set the PRMD
      Parameters:
      newval - new PRMD, or null for no value

    • setOrganizationName

      public void setOrganizationName(String newval)
      Set the organization name
      Parameters:
      newval - new organization name, or null for no value

    • setTeletexOrganizationName

      public void setTeletexOrganizationName(String newval)
      Set teletex-common-name
      Parameters:
      newval - new teletex-common-name, or null for no value

    • setNetworkAddress

      public void setNetworkAddress(String newval)
      Set the network address
      Parameters:
      newval - new network address name, or null for no value

    • setTerminalID

      public void setTerminalID(String newval)
      Set the terminal id
      Parameters:
      newval - new terminal id, or null for no value

    • setNumericUserID

      public void setNumericUserID(String newval)
      Set the user id
      Parameters:
      newval - new user id, or null for no value

    • setSurname

      public void setSurname(String newval)
      Set the surname.
      Parameters:
      newval - new surname, or null for no value.

    • setGivenName

      public void setGivenName(String newval)
      Set the given name.
      Parameters:
      newval - new given name, or null for no value.

    • setInitials

      public void setInitials(String newval)
      Set the initials
      Parameters:
      newval - new initials, or null for no value.

    • setGenerationQualifier

      public void setGenerationQualifier(String newval)
      Set the generation qualifier
      Parameters:
      newval - new generation qualifier, or null for no value.

    • setOU

      public void setOU(String newval, int index)
      Set a specific OU. By setting a value to null, that value and all those after it are removed.
      Parameters:
      newval - new OU, or null for no value.
      index - index of OU to add (starting at 0)

    • setCommonName

      public void setCommonName(String newval)
      Set common name
      Parameters:
      newval - new common name, or null for no value

    • setTeletexCommonName

      public void setTeletexCommonName(String newval)
      Set teletex-common-name
      Parameters:
      newval - new teletex-common-name, or null for no value

    • set

      public void set(String str) throws BadValueException, BadSyntaxException
      Set value from string.

      If an error is detected with the specified value, an exception will be thrown, and the object retains its original value.

      Parameters:
      str - String representation. A null String, or an empty String ("") results in an empty ORAddress. *
      Throws:
      BadValueException - if str is not a valid ORAddress
      BadSyntaxException - if the schema does not know about ORAddress.

    • getDDACount

      public int getDDACount()
      Determine how many DDA components are present in this ORAddress
      Returns:
      the number of type/value pairs of domain defined attributes in this object

    • getDDAType

      public String getDDAType(int index)
      Return the string representing the type of the DDA at a certain position (starting at zero)
      Parameters:
      index - a value that must be in the range returned by getDDACount()
      Returns:
      a string representing the type of the DDA at the specified point, or null if index is out of range.

    • getDDAValue

      public String getDDAValue(int index)
      Return the string representing the value of the DDA at a certain position (starting at zero)
      Parameters:
      index - a value that must be in the range returned by getDDACount()
      Returns:
      a string representing the value of the DDA at the specified point, or null if index is out of range.

    • addDDA

      public void addDDA(String type, String value)
      Add a new DDA type/value to this ORAddress.
      Parameters:
      type - a String containing the type field of this DDA
      value - a String containing the value of this DDA

    • removeDDA

      public void removeDDA(int index)
      Remove a DDA type/value from this ORAddress.
      Parameters:
      index - a value that should be in the range returned by getDDACount(), otherwise the method does nothing.

    • removeAllDDAs

      public void removeAllDDAs()
      Remove all DDA type/value from this ORAddress.

    • getAttributeValue

      public AttributeValue getAttributeValue(AttributeType at) throws BadAttributeTypeException, BadValueException, BadSyntaxException
      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 = rts.getAttributeValue(new AttributeType("MHSORAddress"));
      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:
      BadAttributeTypeException - if at is not an AttributeType which has ORAddress syntax.
      BadValueException - if it is not possible to create an AttributeValue representation of this object.
      BadSyntaxException - if the schema does not know about ORAddress.
      Since:
      14.4

    • get

      public String get(int type)
      Get an O/R address component value.
      Parameters:
      type - Address component type as defined in class OR.
      Returns:
      String value, null if no corresponding value present.

    • set

      public void set(int type, String value)
      Set an O/R address component value.
      Parameters:
      type - Address component type as defined in class OR.
      value - String encoded value.

    • getAttributeValue

      public AttributeValue getAttributeValue(String attributeName) throws BadValueException, BadAttributeTypeException, BadSyntaxException
      Returns a new AttributeValue with the specified attribute name containing this ORAddress
      Parameters:
      attributeName - the name of the attribute (which must have the syntax ORAddress).
      Returns:
      an AttributeValue with the syntax ORAddress that contains the contents of the current object
      Throws:
      BadAttributeTypeException - if attributeName is not an attribute of ORAddress syntax
      BadSyntaxException - if the schema does not know about ORAddress.
      BadValueException - if this object is empty.

    • isValid

      public boolean isValid()
      Does this object represent a valid ORAddress?
      Returns:
      true if this is a valid ORAddress, false otherwise.

    • isValidOrBlank

      public boolean isValidOrBlank()
      Does this object represent a valid or blank ORAddress?
      Returns:
      true if this is a valid or blank ORAddress, false otherwise.
      Since:
      14.6

    • isValidOrBlankWithException

      public void isValidOrBlankWithException() throws BadValueException
      Does this object represent a valid or blank ORAddress? returns if the OR Address is blank, or valid. Otherwise throws an exception.
      Throws:
      BadValueException

    • isBlank

      public boolean isBlank()

    • reset

      public void reset()
      Clear all fields in the object. The object will not be a valid ORAddress, but may become one if fields inside it are set appropriately.

    • equals

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

      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 ORAddress
      Returns:
      true if other is a valid ORAddress which the ORAddress syntax-handler regards as having the same value as this object, false otherwise.
      Since:
      14.4

    • 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.
      Since:
      14.4

    • getTeletexOrganizationName

      public String getTeletexOrganizationName()
      Return teletex-organization-name, if set
      Returns:
      the teletex-organization-name as a String, or null if none set