Package com.oss.asn1

Class Coder

java.lang.Object
com.oss.asn1.Coder
Direct Known Subclasses:
BERCoder, CERCoder, COERCoder, CPERAlignedCoder, CPERUnalignedCoder, CXERCoder, DERCoder, EncodingRuleConvertor, EXERCoder, JSONCoder, OERCoder, PERAlignedCoder, PERUnalignedCoder, XERCoder
public abstract class Coder extends Object
This class defines public methods which allow access to the Coding Services of the OSS ASN.1/Java Tools.
Since:
ASN.1/Java 1.0-beta A

  • Method Details

    • encode

      public final void encode(AbstractData source, OutputStream sink) throws EncodeNotSupportedException, EncodeFailedException
      Encode the source PDU into an OutputStream.
      Parameters:
      source - the PDU to encode.
      sink - the stream the encoded data will be written to.
      Throws:
      EncodeNotSupportedException - thrown if source is not a legal PDU.
      EncodeFailedException - thrown if the encode operation fails.

    • decode

      public final <T extends AbstractData> T decode(InputStream source, T sink) throws DecodeNotSupportedException, DecodeFailedException
      Decode the encoded data in the InputStream and populate a PDU instance.
      Type Parameters:
      T - type of decoded value.
      Parameters:
      source - a stream containing encoded data.
      sink - the PDU instance that will receive the decoded data.
      Returns:
      the decoded data.
      Throws:
      DecodeNotSupportedException - thrown if source is not a legal PDU.
      DecodeFailedException - thrown if the decode operation fails.

    • encode

      public final ByteBuffer encode(AbstractData source, ByteBuffer sink) throws EncodeNotSupportedException, EncodeFailedException
      Encode the source PDU into a ByteBuffer.
      Parameters:
      source - the PDU to encode.
      sink - the byte buffer the encoded data will be written to.
      Returns:
      the ByteBuffer object containing encoded data.
      Throws:
      EncodeNotSupportedException - thrown if source is not a legal PDU.
      EncodeFailedException - thrown if the encode operation fails.

    • encode

      public final ByteBuffer encode(AbstractData source) throws EncodeNotSupportedException, EncodeFailedException
      Encode the source PDU into a ByteBuffer.
      Parameters:
      source - the PDU to encode.
      Returns:
      the ByteBuffer object containing encoded data.
      Throws:
      EncodeNotSupportedException - thrown if source is not a legal PDU.
      EncodeFailedException - thrown if the encode operation fails.

    • decode

      public final <T extends AbstractData> T decode(ByteBuffer source, T sink) throws DecodeNotSupportedException, DecodeFailedException
      Decode the encoded data in the ByteBuffer and populate a PDU instance.
      Type Parameters:
      T - type of decoded value.
      Parameters:
      source - a byte buffer containing encoded data.
      sink - the PDU instance that will receive the decoded data.
      Returns:
      the decoded data.
      Throws:
      DecodeNotSupportedException - thrown if source is not a legal PDU.
      DecodeFailedException - thrown if the decode operation fails.

    • decodeWithPositions

      public final AbstractDataWithPositions decodeWithPositions(InputStream source, AbstractData sink) throws DecodeNotSupportedException, DecodeFailedException
      Decode the encoded data in the InputStream and populate a PDU instance. In addition to the decoded value, offset/size information is returned from decoder.
      Parameters:
      source - a stream containing encoded data.
      sink - the PDU instance that will receive the decoded data.
      Returns:
      the decoded data with position information.
      Throws:
      DecodeNotSupportedException - thrown if source is not a legal PDU.
      DecodeFailedException - thrown if the decode operation fails.

    • validate

      @Deprecated public final int validate(AbstractData pdu) throws ValidateNotSupportedException, ValidateFailedException
      Deprecated.
      Validate a PDU by checking its constraints. This method is deprecated. Use the isValid method of AbstractData class instead.
      Parameters:
      pdu - the PDU object to validate.
      Returns:
      an int value describing the result. 0 means the PDU value is valid, and nonzero means a constraint violation occurred.
      Throws:
      ValidateNotSupportedException - thrown if pdu is not a legal PDU.
      ValidateFailedException - thrown if the validate operation fails.

    • enableEncoderDebugging

      public void enableEncoderDebugging()
      Turn debugging on during encode.

    • disableEncoderDebugging

      public void disableEncoderDebugging()
      Turn debugging off during encode.

    • enableDecoderDebugging

      public void enableDecoderDebugging()
      Turn debugging on during decode.

    • disableDecoderDebugging

      public void disableDecoderDebugging()
      Turn debugging off during decode.

    • enableRichDecoderExceptions

      public void enableRichDecoderExceptions()
      Enable Rich decoder exceptions to return partially decoded data.

    • disableRichDecoderExceptions

      public void disableRichDecoderExceptions()
      Disable Rich decoder exceptions.

    • getEncoderDebugOut

      public PrintWriter getEncoderDebugOut()
      Get the character-output stream that is the destination for the encoder's debug output.
      Returns:
      the character-output stream where the diagnostic output from the encoder will be written.

    • getDecoderDebugOut

      public PrintWriter getDecoderDebugOut()
      Get the character-output stream that is the destination for the decoder's debug output.
      Returns:
      the character-output stream where the diagnostic output from the decoder will be written.

    • setEncoderDebugOut

      public void setEncoderDebugOut(PrintWriter out)
      Redirect the encoder's diagnostic output to a character-output stream.
      Parameters:
      out - the character-output stream.

    • setDecoderDebugOut

      public void setDecoderDebugOut(PrintWriter out)
      Redirect the decoder's diagnostic output to a character-output stream.
      Parameters:
      out - the character-output stream.

    • getEncoderDebugProperties

      public Properties getEncoderDebugProperties()
      Get current settings of the encoder's debugger.
      Returns:
      the settings that specify the format of the diagnostic output.

    • getDecoderDebugProperties

      public Properties getDecoderDebugProperties()
      Get current settings of the decoder's debugger.
      Returns:
      the settings that specify the format of the diagnostic output.

    • setEncoderDebugProperties

      public void setEncoderDebugProperties(Properties params)
      Specify settings of the encoder's debugger. Currently, the following properties are recognized:
      • oss.tracer.TruncationLimit=number - specifies how the lengthy content trace data is truncated. When the value is set to zero the truncation is disabled.
      • oss.tracer.IndentWidth=number - for better readability, some lines in the diagnostic output are indented to the right. Say, in BER diagnostic output indentation is used to reflect the nested TLV structure. This property specifies the number of print positions in one indentation level.
      • oss.tracer.ExceptionTrace=on|off - setting this property to "on" causes the exception stack trace to be included in the diagnostic output.
      Parameters:
      params - the settings that specify the format of the diagnostic output.

    • setDecoderDebugProperties

      public void setDecoderDebugProperties(Properties params)
      Specify settings of the decoder's debugger. Currently, the following properties are recognized:
      • oss.tracer.TruncationLimit=number - specifies how the lengthy content trace data is truncated. When the value is set to zero the truncation is disabled.
      • oss.tracer.IndentWidth=number - for better readability, some lines in the diagnostic output are indented to the right. Say, in BER diagnostic output indentation is used to reflect the nested TLV structure. This property specifies the number of print positions in one indentation level.
      • oss.tracer.ExceptionTrace=on|off - setting this property to "on" causes the exception stack trace to be included in the diagnostic output.
      Parameters:
      params - the settings that specify the format of the diagnostic output.

    • enableEncoderConstraints

      public void enableEncoderConstraints()
      Enforce constraints during encode.

    • disableEncoderConstraints

      public void disableEncoderConstraints()
      Do not enforce constraints during encode. This can help improve performance.

    • enableDecoderConstraints

      public void enableDecoderConstraints()
      Enforce constraints during decode.

    • disableDecoderConstraints

      public void disableDecoderConstraints()
      Do not enforce constraints during decode. This can help improve performance.

    • enableAutomaticEncoding

      public void enableAutomaticEncoding()
      Turn on automatic encoding of OpenTypes. The coder can then automatically encode the OpenType which has a component relation constraint or a type constraint applied.

    • disableAutomaticEncoding

      public void disableAutomaticEncoding()
      Turn off automatic encoding of the OpenType.

    • isPDUDetectionAvailable

      public boolean isPDUDetectionAvailable()
      Indicates if the coder is capable of automatically detecting the type of the incoming PDU.
      Returns:
      true if PDU detection is available.

    • enableAutomaticDecoding

      public void enableAutomaticDecoding()
      Turn on automatic decoding of OpenTypes. The coder will automatically decode the OpenType with a component relation constraint or a type constraint applied.

    • disableAutomaticDecoding

      public void disableAutomaticDecoding()
      Turn off automatic decoding of OpenTypes.

    • disableDeferredDecoding

      public void disableDeferredDecoding()
      Turn off deferred decoding of components marked with the DeferDecoding directive. The coder will ignore the directive and fully decode appropriate components.

    • enableDeferredDecoding

      public void enableDeferredDecoding()
      Turn on deferred decoding of components marked with the DeferDecoding directive.

    • enableContainedValueEncoding

      public void enableContainedValueEncoding()
      Turn on automatic encoding of the value, that is contained in a BIT STRING or in an OCTET STRING with the contents constraint imposed.

    • disableContainedValueEncoding

      public void disableContainedValueEncoding()
      Turn off automatic encoding of the value, that is contained in a BIT STRING or in an OCTET STRING with the contents constraint imposed.

    • enableContainedValueDecoding

      public void enableContainedValueDecoding()
      Turn on automatic decoding of the value, that is contained in a BIT STRING or in an OCTET STRING with the contents constraint imposed.

    • enableContainedValueDecoding

      public void enableContainedValueDecoding(boolean preserveEncoding)
      Turn on automatic decoding of the value, that is contained in a BIT STRING or in OCTET STRING with the contents constraint imposed.
      Parameters:
      preserveEncoding - setting this parameter to true instructs the decoder to preserve the encoded form after the automatic decoding. By default, the encoded form is erased on successful automatic decoding of the contained value.

    • disableContainedValueDecoding

      public void disableContainedValueDecoding()
      Turn off automatic decoding of the value, that is contained in a BIT STRING or in an OCTET STRING with the contents constraint imposed.

    • enableRelaxedDecoding

      public void enableRelaxedDecoding()
      Turn on relaxed decoding mode. In the relaxed mode the coder ignores non-severe decoding errors.

    • disableRelaxedDecoding

      public void disableRelaxedDecoding()
      Turn off relaxed decoding mode. In the relaxed mode the coder ignores non-severe decoding errors.

    • enableStrictDecoding

      public void enableStrictDecoding()
      Turn on Strict decoding mode. In the Strict mode the coder will generate additional exception for some non-severe decoding errors, that are otherwise ignored.

    • disableStrictDecoding

      public void disableStrictDecoding()
      Turn off Strict decoding mode. In the strict mode the coder will generate additional exceptions for some non-severe decoding errors, that are otherwise ignored.

    • enableXERCoderInterface

      public void enableXERCoderInterface()
      Enable user defined XER encodings which are generated by user classes which implement XERCoderInterface (XER and E-XER only).

    • disableXERCoderInterface

      public void disableXERCoderInterface()
      Disable user defined XER encodings which are generated by user classes which implement XERCoderInterface (XER and E-XER only).

    • enableCompact

      public void enableCompact()
      Do not generate whitespace into the XML document (XER and E-XER only). In the compact mode the encoding is written without any whitespace as a single line of text. If the compact mode is disabled newlines are inserted as necessary and the indentation is applied.

    • disableCompact

      public void disableCompact()
      Add whitespace as necessary to improve readability of XML document (XER and E-XER only). In the compact mode the encoding is written without any whitespace as a single line of text. If the compact mode is disabled newlines are inserted as necessary and the indentation is applied.

    • includeXMLDeclaration

      public void includeXMLDeclaration()
      Make the XML document contain the initial XML declaration (XER and E-XER only).

    • excludeXMLDeclaration

      public void excludeXMLDeclaration()
      Initial XML declaration is excluded from the XML document (XER and E-XER only).

    • setIndentWidth

      public void setIndentWidth(int width)
      Set indentation width for generating whitespace (XER and E-XER only).
      Parameters:
      width - number of spaces for indenting

    • getIndentWidth

      public int getIndentWidth()
      Get the number of spaces allocated for indenting (XER and E-XER only).
      Returns:
      indentation width setting

    • useDefiniteLengthEncoding

      public void useDefiniteLengthEncoding()
      Use Definite Length Encoding when encoding with the Basic Encoding Rules (BER ONLY).

    • useIndefiniteLengthEncoding

      public void useIndefiniteLengthEncoding()
      Use Indefinite Length Encoding when encoding with the Basic Encoding Rules (BER ONLY).

    • usingDefiniteLengthEncoding

      public boolean usingDefiniteLengthEncoding()
      Determine whether DEFINITE length encoding is in effect (BER, DER and CER Only).
      Returns:
      true if DEFINITE length encoding is in effect.

    • enableTruncatedZeroSecondsInGeneralizedTime

      public void enableTruncatedZeroSecondsInGeneralizedTime()
      Kept for compatibility with Native Java, but has no effect.

    • disableTruncatedZeroSecondsInGeneralizedTime

      public void disableTruncatedZeroSecondsInGeneralizedTime()
      Kept for compatibility with Native Java, but has no effect.

    • enableTruncatedZeroSecondsInUTCTime

      public void enableTruncatedZeroSecondsInUTCTime()
      Kept for compatibility with Native Java, but has no effect.

    • disableTruncatedZeroSecondsInUTCTime

      public void disableTruncatedZeroSecondsInUTCTime()
      Kept for compatibility with Native Java, but has no effect.

    • disableEncodingOfAbsentComponents

      public void disableEncodingOfAbsentComponents()
      Do not encode absent optional components (JSON only).

    • enableEncodingOfAbsentComponents

      public void enableEncodingOfAbsentComponents()
      Do encode absent optional components as properties with the value 'null' (JSON only).

    • disableEncodinOfImpliedValues

      public void disableEncodinOfImpliedValues()
      Do not encode absent components with DEFAULT (JSON only).

    • enableEncodingOfImpliedValues

      public void enableEncodingOfImpliedValues()
      Do encode absent components with DEFAULT as present with the default value (JSON only).

    • enableJSONCoderInterface

      public void enableJSONCoderInterface()
      Enable user defined JSON encodings which are generated by user classes which implement JSONCoderInterface (JSON only).

    • disableJSONCoderInterface

      public void disableJSONCoderInterface()
      Disable user defined JSON encodings which are generated by user classes which implement JSONCoderInterface (JSON only).

    • toString

      public String toString()
      Return the name of this implementation of the Coder.
      Overrides:
      toString in class Object

    • getNumberOfPaddingBits

      public int getNumberOfPaddingBits()
      The method returns number of padding bits produced by previous call to encode. BER and DER coders always return 0. PER coder returns true number of padding bits which were added to produce complete PER encoding.
      Returns:
      number of padding bits produced by the last encode

    • getStorageManager

      public StorageManager getStorageManager()
      Get current setting of the StorageManager.
      Returns:
      an instance of the StorageManager to allocate the external storage.

    • setStorageManager

      public void setStorageManager(StorageManager storageManager)
      Set the StorageManager, that will allocate the storage for the huge values.
      Parameters:
      storageManager - the instance of the class, that implements the StorageManager interface.

    • getTransferSyntax

      public abstract TransferSyntax getTransferSyntax()
      Returns:
      identifier of this coder encoding rules.

    • isUnknownExtensionFound

      public boolean isUnknownExtensionFound()
      Returns:
      true if an unknown extension was found by the last invocation of the decode() method.