You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2006/09/21 16:56:23 UTC
svn commit: r448575 [1/7] - in /incubator/harmony/standard/site:
docs/documentation/ docs/subcomponents/classlibrary/
docs/subcomponents/drlvm/ xdocs/documentation/
xdocs/subcomponents/classlibrary/ xdocs/subcomponents/drlvm/
Author: tellison
Date: Thu Sep 21 07:56:21 2006
New Revision: 448575
URL: http://svn.apache.org/viewvc?view=rev&rev=448575
Log:
Apply final patches in HARMONY-1443 (Maintenance and enhancements of DRLVM documents)
Added:
incubator/harmony/standard/site/docs/subcomponents/classlibrary/asn1_framework.html
incubator/harmony/standard/site/docs/subcomponents/classlibrary/awt.html
incubator/harmony/standard/site/docs/subcomponents/classlibrary/dns_support.html
incubator/harmony/standard/site/docs/subcomponents/classlibrary/java2d.html
incubator/harmony/standard/site/docs/subcomponents/classlibrary/regexp.html
incubator/harmony/standard/site/docs/subcomponents/classlibrary/rmi_proivider.html
incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/ASN1Framework.htm
incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/AWT.html (with props)
incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/DNSsupport.htm
incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/Java2D.html (with props)
incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/RMIprovider.htm
incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/Regexp.htm
incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/asn1_framework.xml (with props)
incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/awt.xml (with props)
incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/dns_support.xml (with props)
incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/java2d.xml (with props)
incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/regexp.xml (with props)
incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/rmi_proivider.xml (with props)
Modified:
incubator/harmony/standard/site/docs/documentation/documentation.html
incubator/harmony/standard/site/docs/subcomponents/classlibrary/index.html
incubator/harmony/standard/site/docs/subcomponents/drlvm/debugging_VM_and_JIT.html
incubator/harmony/standard/site/docs/subcomponents/drlvm/developers_guide.html
incubator/harmony/standard/site/docs/subcomponents/drlvm/getting_started.html
incubator/harmony/standard/site/xdocs/documentation/documentation.xml
incubator/harmony/standard/site/xdocs/subcomponents/classlibrary/index.xml
incubator/harmony/standard/site/xdocs/subcomponents/drlvm/debugging_VM_and_JIT.xml
incubator/harmony/standard/site/xdocs/subcomponents/drlvm/developers_guide.xml
incubator/harmony/standard/site/xdocs/subcomponents/drlvm/getting_started.xml
Modified: incubator/harmony/standard/site/docs/documentation/documentation.html
URL: http://svn.apache.org/viewvc/incubator/harmony/standard/site/docs/documentation/documentation.html?view=diff&rev=448575&r1=448574&r2=448575
==============================================================================
--- incubator/harmony/standard/site/docs/documentation/documentation.html (original)
+++ incubator/harmony/standard/site/docs/documentation/documentation.html Thu Sep 21 07:56:21 2006
@@ -210,7 +210,7 @@
</td></tr>
<tr><td>
<p>
-There is not yet a full manual or similar official documentation. However,
+There is not yet a full manual or similar official documentation. However,
the resources below will help new users and developers get up to speed with
the technology.
</p>
@@ -225,15 +225,20 @@
<ul>
<li>
<a href="build_website.html">Building and Deploying the Apache Harmony Website</a>
+ <br />
+ Instructions on how changes to the website can be made; focuses on textual changes;
+ creating / deleting files is not covered in detail
</li>
<li>
<a href="../subcomponents/classlibrary/index.html">Documentation for the Classlibrary Code</a>
+ <br />
+ Links to available materials on building classlib code, as well as links to module-specific guides
</li>
<li>
- <a href="../externals/security/ASN1Framework.htm">Documentation for Harmony's ASN1 Framework</a>
- </li>
- <li>
- <a href="../externals/regex/Regexp.htm">Documentation for Harmony's Regular Expression Framework</a>
+ <a href="../subcomponents/drlvm/index.html">Documentation for the DRL virtual machine Code</a>
+ <br />
+ Links to available materials on building DRLVM code, as well as links to architecture descriptions,
+ how-to docs, etc
</li>
</ul>
Added: incubator/harmony/standard/site/docs/subcomponents/classlibrary/asn1_framework.html
URL: http://svn.apache.org/viewvc/incubator/harmony/standard/site/docs/subcomponents/classlibrary/asn1_framework.html?view=auto&rev=448575
==============================================================================
--- incubator/harmony/standard/site/docs/subcomponents/classlibrary/asn1_framework.html (added)
+++ incubator/harmony/standard/site/docs/subcomponents/classlibrary/asn1_framework.html Thu Sep 21 07:56:21 2006
@@ -0,0 +1,1679 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+
+<!--
+Copyright 1999-2004 The Apache Software Foundation
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+
+<!-- start the processing -->
+ <!-- ====================================================================== -->
+ <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
+ <!-- Main Page Section -->
+ <!-- ====================================================================== -->
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
+
+ <meta name="author" value="Harmony Documentation Team">
+ <meta name="email" value="harmony-dev@incubator.apache.org">
+
+
+
+
+
+
+
+ <title>Apache Harmony - Apache Harmony</title>
+
+ <link rel="Stylesheet" type="text/css" href="/harmony/site.css"/>
+ </head>
+
+ <body>
+ <table width="100%" cellspacing="0">
+ <!-- TOP IMAGE -->
+ <tr>
+ <td align='LEFT'>
+ <table><tr><td>
+ <td>
+<a href="http://incubator.apache.org/harmony/"><img src="../../images/harmony-logo.png" alt="Apache Harmony" /></a>
+</td>
+</td>
+ </td></tr></table>
+ </td>
+ <td align='RIGHT'>
+ <a href="http://incubator.apache.org/harmony/">
+ <img src="http://incubator.apache.org/harmony/images/apache-incubator-logo.png"
+ alt="Apache Harmony" /></a>
+ </td>
+ </tr>
+ </table>
+ <table width="100%" cellspacing="4">
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+
+ <tr>
+ <!-- LEFT SIDE NAVIGATION -->
+ <td class="menuItem" width="20%" nowrap="true">
+
+ <!-- special ACon Logo - leave here for next time -->
+ <a href="http://www.us.apachecon.com/">
+ <img src="http://www.apache.org/ads/ApacheCon/240x120-2006-us.gif"
+ alt="ApacheCon US 2006" />
+ </a>
+
+ <!-- regular menu -->
+
+
+ <!-- ============================================================ -->
+
+ <p class="menuItem"><strong>General</strong></p>
+ <ul>
+ <li class="menuItem"> <a href="../../index.html">Home</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../license.html">License</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../contribution_policy.html">Contribution Policy</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../guidelines.html">Project Guidelines</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="http://www.apache.org/">ASF</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../downloads.html">Downloads</a>
+</li>
+
+
+
+ </ul>
+ <p class="menuItem"><strong>Community</strong></p>
+ <ul>
+ <li class="menuItem"> <a href="../../get-involved.html">Get Involved</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../contributors.html">Committers</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../mailing.html">Mailing Lists</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../documentation/documentation.html">Documentation</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../faq.html">FAQ</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="http://wiki.apache.org/harmony">Wiki</a>
+</li>
+
+
+
+ </ul>
+ <p class="menuItem"><strong>Development</strong></p>
+ <ul>
+ <li class="menuItem"> <a href="../../status.html">How Are We Doing?</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../roadmap.html">Road Map / TODO</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../svn.html">Source Code</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="http://issues.apache.org/jira/browse/HARMONY">JIRA</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../related.html">Other Projects</a>
+</li>
+
+
+
+ </ul>
+ <p class="menuItem"><strong>Subcomponents</strong></p>
+ <ul>
+ <li class="menuItem"> <a href="../../subcomponents/buildtest/index.html">Build-Test Framework</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../subcomponents/classlibrary/index.html">Class Library</a>
+</li>
+
+
+ <table>
+ <tr><td class="menuItem">
+ <a href="../../subcomponents/classlibrary/status.html">Status</a>
+ </td></tr>
+ </table>
+
+ <li class="menuItem"> <a href="../../subcomponents/drlvm/index.html">DRLVM</a>
+</li>
+
+
+
+ <li class="menuItem"> <a href="../../subcomponents/jchevm/index.html">JCHEVM</a>
+</li>
+
+
+
+ </ul>
+ </td>
+ <td width="80%" valign="top"><a name="top"></a>
+
+ <div>
+<!--
+ Copyright 2005 The Apache Software Foundation or its licensors, as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+<!--
+Author: Nadezhda Morozova, Stepan M. Mishura
+Version: $Revision$
+-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type"
+ content="text/html; charset=windows-1252" />
+ <title>
+ ASN.1 Framework
+ </title>
+ <link rel="Stylesheet" type="text/css" media="all" href="harmony.css" />
+ </head>
+ <body>
+ <h1 style="text-align: center">
+ <a id="Top" name="Top"></a>ASN.1 Framework
+ </h1>
+ <p class="TOCHeading">
+ <a href="#Revision_History">Revision History</a>
+ </p>
+ <p class="TOCHeading">
+ <a href="#Disclaimer">Disclaimer</a>
+ </p>
+ <p class="TOCHeading">
+ <a href="#About_this_document">About this Document</a>
+ </p>
+ <p class="TOC">
+ <a href="#Purpose">Purpose</a>
+ </p>
+ <p class="TOC">
+ <a href="#Intended_Audience">Intended Audience</a>
+ </p>
+ <p class="TOC">
+ <a href="#Documentation_Conventions">Documentation Conventions</a>
+ </p>
+ <p class="TOCHeading">
+ <a href="#Overview">Introduction to ASN.1</a>
+ </p>
+ <p class="TOC">
+ <a href="#About">About</a>
+ </p>
+ <p class="TOC">
+ <a href="#Basic_Types">ASN.1 Basic Types</a>
+ </p>
+ <p class="TOCHeading">
+ <a href="#Implementation">ASN.1 Framework in Harmony</a>
+ </p>
+ <p class="TOC">
+ <a href="#About_ASN_Framework">About</a>
+ </p>
+ <p class="TOC">
+ <a href="#Mapping_ASN_Java">Mapping between ASN.1 and Java Types</a>
+ </p>
+ <p class="TOC">
+ <a href="#Harmony_Classes">Harmony ASN.1 Classes</a>
+ </p>
+ <p class="TOC">
+ <a href="#Encoding_Rules">Encoding Rules</a>
+ </p>
+ <p class="TOC">
+ <a href="#Notations_Implementation">Implementing ASN.1 Notations</a>
+ </p>
+ <p class="TOCHeading">
+ <a href="#Appendix">Appendix: Usage Examples</a>
+ </p>
+ <p class="TOCHeading">
+ <a href="#References">References</a>
+ </p>
+ <h1>
+ <a id="Revision_History" name="Revision_History"></a>Revision History
+ </h1>
+ <table width="100%">
+ <tr>
+ <th class="TableHeading" width="25%">
+ Version
+ </th>
+ <th class="TableHeading" width="50%">
+ Version Information
+ </th>
+ <th class="TableHeading">
+ Date
+ </th>
+ </tr>
+ <tr>
+ <td class="TableCell" width="25%">
+ Initial version
+ </td>
+ <td class="TableCell" width="25%">
+ Nadya Morozova, Stepan Mishura: document created<br />
+ Special thanks to Sergey Dmitriev for assistance
+ </td>
+ <td class="TableCell">
+ November 16, 2005
+ </td>
+ </tr>
+ <tr>
+ <td class="TableCell" width="25%">
+ Formatting update
+ </td>
+ <td class="TableCell" width="25%">
+ Nadya Morozova
+ </td>
+ <td class="TableCell">
+ September 21, 2006
+ </td>
+ </tr>
+ </table>
+ <h1>
+ <a id="Disclaimer" name="Disclaimer"></a>Disclaimer and Legal
+ Information
+ </h1>
+ <p>
+ Copyright 2005 The Apache Software Foundation or its licensors, as
+ applicable.
+ </p>
+ <p>
+ Licensed under the Apache License, Version 2.0 (the "License"); you
+ may not use this file except in compliance with the License. You may
+ obtain a copy of the License at <a
+ href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>.
+ </p>
+ <p>
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied. See the License for the specific language governing
+ permissions and limitations under the License.
+ </p>
+ <h1>
+ <a id="About_this_document" name="About_this_document"></a>About This
+ Document
+ </h1>
+ <h2>
+ <a id="Purpose" name="Purpose"></a>Purpose
+ </h2>
+ <p>
+ This document introduces the ASN.1 (Abstract Syntax Notation)
+ framework delivered as part of the Harmony classlibrary. This document
+ provides an overview of ASN.1 types and encoding rules with focus on
+ the characteristics of the current implementation. The document gives
+ details on the framework design and provides an overall description of
+ the ASN.1 package.
+ </p>
+ <h2>
+ <a id="Intended_Audience" name="Intended_Audience"></a>Intended
+ Audience
+ </h2>
+ <p>
+ The target audience for the document includes a wide community of
+ engineers interested in using ASN.1 and in further work with the
+ product to contribute to its development. The document assumes that
+ readers are familiar with the ASN.1 notation and the Java<a
+ href="#*">*</a> programming language.
+ </p>
+ <h2>
+ <a id="Documentation_Conventions"
+ name="Documentation_Conventions"></a>Documentation Conventions
+ </h2>
+ <p>
+ This document uses the <a href="conventions.htm">unified
+ conventions</a> for the Harmony documentation kit.
+ </p>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h1>
+ <a id="Overview" name="Overview"></a>Introduction to ASN.1
+ </h1>
+ <h2>
+ <a id="About" name="About"></a>About
+ </h2>
+ <p>
+ ASN.1 (Abstract Syntax Notation One) is an international standard of
+ notation used to specify data structures with a high level of
+ abstraction, which is reflected in the ASN.1 specification [<a
+ href="#ASN_SPEC">2</a>]. ASN.1 is fully platform- and
+ language-independent. ASN.1 goes with the <i>encoding rules</i>, which
+ determine how to represent a value of an abstract type as a string of
+ octets [<a href="#RULES_SPEC">3</a>].
+ </p>
+ <p>
+ The Java<a href="#*">*</a> API specification [<a
+ href="#JAVA_API_SPEC">1</a>] employs ASN.1 in the following ways:
+ </p>
+ <ul>
+ <li>
+ <i>Directly</i>: by providing the ASN.1 notation for used data and
+ by specifying its encoding rule
+ </li>
+ <li>
+ <i>Indirectly</i>: by refereeing to another (external)
+ specification that uses the ASN.1 notation
+ </li>
+ </ul>
+ <p>
+ To learn more about ASN.1, you can use online documentation [<a
+ href="#INFO_SITE">4</a>], [<a href="#LAYMAN_GUIDE">5</a>], and
+ publications [<a href="#EBOOK1">6</a>], [<a href="#EBOOK2">7</a>].
+ </p>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h2>
+ <a id="Basic_Types" name="Basic_Types"></a>ASN.1 Basic Types
+ </h2>
+ <p>
+ ASN.1 has the following basic types:
+ </p>
+ <ul>
+ <li>
+ <a href="#String"><i>String</i></a> and <a
+ href="#Primitive"><i>primitive</i></a> types represent raw data.
+ </li>
+ <li>
+ <a href="#Constructed"><i>Constructed</i></a> types serve as
+ containers for a number of type components, which can be optional
+ or can have default values.
+ </li>
+ <li>
+ <a href="#Tagged"><i>Tagged</i></a> types are used to derive one
+ ASN.1 type from another.
+ </li>
+ <li>
+ <a href="#Other"><i>Other</i></a> types are <code>ANY</code> and
+ <code>CHOICE</code>.
+ </li>
+ </ul>
+ <p>
+ These types are used to specify a wide range of other abstract types,
+ as shown in Example 1.
+ </p>
+ <p class="example">
+ <a id="example1" name="example1"></a>Example 1
+ </p>
+ <p class="exampletext">
+ This example is based on RFC 3280 [<a href="#RFC">8</a>].
+ </p>
+ <blockquote>
+<pre>
+Extensions ::= SEQUENCE SIZE (1..MAX) OF Extension
+
+Extension ::= SEQUENCE {
+ extnID OBJECT IDENTIFIER,
+ critical BOOLEAN DEFAULT FALSE,
+ extnValue OCTET STRING
+}
+
+Version ::= INTEGER { v1(0), v2(1), v3(2) }
+</pre>
+ </blockquote>
+ <p>
+ In this example, the basic ASN.1 types <code>SEQUENCE</code>,
+ <code>OBJECT IDENTIFIER</code>, <code>BOOLEAN</code> and <code>OCTET
+ STRING</code> are used to specify a new abstract type
+ <code>Extension</code>. The newly created type is then used with
+ another basic type <code>SEQUENCE OF</code> to describe the
+ <code>Extensions</code> type. The ASN.1 <code>INTEGER</code> type is
+ used to specify the <code>Version</code> abstract type and to provide
+ constraints for this type.
+ </p>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h1>
+ <a id="Implementation" name="Implementation"></a>ASN.1 Framework in
+ Harmony
+ </h1>
+ <p>
+ This section part of the document describes the ASN.1 framework as a
+ whole, defines the mapping principles to establish the correspondence
+ between ASN.1 and Java<a href="#*">*</a> types, and represents the
+ hierarchy of ASN.1 types representation in the current framework.
+ </p>
+ <h2>
+ <a id="About_ASN_Framework" name="About_ASN_Framework"></a>About
+ </h2>
+ <p>
+ The ASN.1 framework provides a common, easy and efficient approach for
+ working with ASN.1 basic types, notations and encoding rules. This
+ framework can be described as a layer between a Java<a href="#*">*</a>
+ object and its ASN.1 encoded form, as shown in Figure 1.
+ </p>
+ <br />
+ <br />
+ <p style="text-align: center">
+ <img src="images/ASN_framework.gif" alt="overview" />
+ </p>
+ <p class="special" style="text-align: center">
+ Figure 1: ASN.1 Framework Layer
+ </p>
+ <p>
+ The Harmony ASN.1 framework is characterized by:
+ </p>
+ <ul>
+ <li>
+ A clear API for decoding and encoding objects
+ </li>
+ <li>
+ Low resource consuming
+ </li>
+ <li>
+ Thread safety
+ </li>
+ </ul>
+ <p>
+ The framework enables the following:
+ </p>
+ <ul>
+ <li>
+ Create a Java<a href="#*">*</a> object instance from its encoded
+ octet string
+ </li>
+ <li>
+ Verify that an octet string is a valid encoded string
+ </li>
+ <li>
+ Generate an encoded octet string for a particular object
+ </li>
+ </ul>
+ <p class="note">
+ Note
+ </p>
+ <p class="notetext">
+ The current ASN.1 framework is a partial implementation of the ASN.1
+ and encoding rules specifications. This framework covers certain ASN.1
+ basic types and basic encoding rules (BER), and provides most
+ restrictions employed by the distinguished encoding rules (DER).
+ </p>
+ <h2>
+ <a id="Mapping_ASN_Java" name="Mapping_ASN_Java"></a>Mapping between
+ ASN.1 and Java<a href="#*">*</a> Types
+ </h2>
+ <p>
+ The framework maps all ASN.1 abstract types and notations to Java<a
+ href="#*">*</a> primitive types or Java<a href="#*">*</a> classes.
+ </p>
+ <p class="example">
+ <a id="example2" name="example2"></a>Example 2
+ </p>
+ <p class="exampletext">
+ The notations in <a href="#example1">Example 1</a> can be represented
+ as the following Java<a href="#*">*</a> classes:
+ </p>
+ <blockquote>
+<pre>
+public class Extension {
+ private String extnID;
+ private boolean critical;
+ private byte extnValue[];
+}
+
+public class Extensions {
+ // contains elements of Extension class
+ private List extensions;
+}
+</pre>
+ </blockquote>
+ <p>
+ The <code>Extension</code> notation corresponds to a Java<a
+ href="#*">*</a> class with three fields, where every field corresponds
+ to one entry in the <code>Extension</code> notation. For example, the
+ <code>critical BOOLEAN DEFAULT FALSE</code> field in the
+ <code>Extension</code> notation corresponds to the <code>boolean
+ critical</code> field in the Java<a href="#*">*</a> class. The
+ <code>Extensions</code> notation equals to a Java<a href="#*">*</a>
+ class with a field that contains an ordered collection of the
+ instances of the <code>Extension</code> class.
+ </p>
+ <p>
+ The table below describes the default mapping ASN.1 types to Java<a
+ href="#*">*</a> types, and indicates the class providing the specified
+ mapping in the current framework.
+ </p>
+ <table cellspacing="0" cellpadding="0" align="center"
+ width="60%">
+ <tr>
+ <th class="TableHeading" colspan="2">
+ ASN.1 Type
+ </th>
+ <th class="TableHeading" style="text-align: center"
+ width="25%">
+ Java<a href="#*">*</a> Type
+ </th>
+ <th class="TableHeading" width="30%">
+ Framework Class
+ </th>
+ </tr>
+ <tr>
+ <th class="TableHeading" rowspan="5" width="11%">
+ <a id="Primitive" name="Primitive">Primitive</a>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>INTEGER</code>
+ </td>
+ <td align="center" width="25%">
+ <code>byte[]</code>
+ </td>
+ <td width="25%">
+ <code><a href="#ASN1Integer">ASN1Integer</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>ENUMERATED</code>
+ </td>
+ <td align="center" width="25%">
+ <code>byte[]</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1Enumerated">ASN1Enumerated</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>OBJECT IDENTIFIER</code>
+ </td>
+ <td align="center" width="25%">
+ <code>int[]</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1Oid">ASN1Oid</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>BOOLEAN</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.Boolean</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1Boolean">ASN1Boolean</a></code>
+ </td>
+ </tr>
+ <tr>
+ <th class="TableHeading" rowspan="12" width="11%">
+ <a id="String" name="String">String</a>
+ </th>
+ <td width="30%">
+ <code>BitString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>asn1.BitString</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1BitString">ASN1BitString</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>OctetString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>byte[]</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1OctetString">ASN1OctetString</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>PrintableString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>T61String</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>IA5String</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>UTF8String</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>BMPString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>GeneralString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>TeletexString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>UniversalString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>UTCTime</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.util.Date</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1UTCTime">ASN1UTCTime</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>GeneralizedTime</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.util.Date</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1UTCTime">ASN1GeneralizedTime</a></code>
+ </td>
+ </tr>
+ <tr>
+ <th rowspan="3" class="TableHeading">
+ <a id="Constructed" name="Constructed">Constructed</a>
+ </th>
+ <td width="30%">
+ <code>SEQUENCE</code>
+ </td>
+ <td align="center" width="25%">
+ <code>Object[]</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1Sequence">ASN1Sequence</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>SEQUENCE OF</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.util.List</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1SequenceOf">ASN1SequenceOf</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>SET OF</code>
+ </td>
+ <td width="25%" align="center">
+ <code>java.util.List</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1SetOf">ASN1SetOf</a></code>
+ </td>
+ </tr>
+ <tr>
+ <th rowspan="2" width="11%" class="TableHeading">
+ <a id="Tagged" name="Tagged">Tagged</a>
+ </th>
+ <td width="30%">
+ <code>EXPLICIT</code>
+ </td>
+ <td width="25%" style="text-align: center">
+ <i>based type</i>
+ </td>
+ <td width="30%">
+ <a href="#ASN1Explicit"><code>ASN1Explicit</code></a>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>IMPLICIT</code>
+ </td>
+ <td align="center" width="25%" style="text-align: center">
+ <i>based type</i>
+ </td>
+ <td width="30%">
+ <a href="#Class_ASNImplicit"><code>ASN1Implicit</code></a>
+ </td>
+ </tr>
+ <tr>
+ <th rowspan="2" width="11%" class="TableHeading">
+ <a id="Other" name="Other">Other</a>
+ </th>
+ <td width="30%">
+ <code>ANY</code>
+ </td>
+ <td align="center" width="25%">
+ <code>byte[]</code>
+ </td>
+ <td width="30%">
+ <code><a href="#Class_ASNAny">ASN1Any</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>CHOICE</code>
+ </td>
+ <td align="center" width="25%" style="text-align: center">
+ <i>one of chosen types</i>
+ </td>
+ <td width="30%">
+ <code><a href="#Class_ASNChoice">ASN1Choice</a></code>
+ </td>
+ </tr>
+ </table>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h2>
+ <a id="Harmony_Classes" name="Harmony_Classes"></a>Harmony ASN.1
+ Classes
+ </h2>
+ <p>
+ Basic ASN.1 types are in the
+ <code>org.apache.harmony.security.asn1</code> package in accordance
+ with the hierarchy shown in Figure 2.
+ </p>
+ <p style="text-align: center">
+ <img src="images/package_content.gif" alt="package" width="469"
+ height="352" />
+ </p>
+ <p class="special">
+ Figure 2: Class Hierarchy
+ </p>
+ <p>
+ The subsequent sections provide as short description of the classes
+ included in the package.
+ </p>
+ <p class="class">
+ <a id="Primitive_Types" name="Primitive_Types"></a>Primitive Types
+ </p>
+ <dl>
+ <dt>
+ <a id="ASN1Integer" name="ASN1Integer"></a>ASN1Integer
+ </dt>
+ <dd>
+ This class represents the ASN.1 <code>INTEGER</code> type that
+ denotes an arbitrary integer with positive, negative, or zero
+ values and any magnitude. Because an integer value is not
+ restricted, it is up to the application class to choose the Java<a
+ href="#*">*</a> type for storing the integer value, for example, an
+ instance of the <code>java.math.BigInteger</code> class. By
+ default, an integer value is stored in an array of bytes.
+ </dd>
+ <dt>
+ <a id="ASN1Enumerated" name="ASN1Enumerated"></a> ASN1Enumerated
+ </dt>
+ <dd>
+ This class represents the ASN.1 <code>ENUMERATED</code> type that
+ denotes a set of integer values. The implementation of this class
+ is similar to that of the <code>ASN1Integer</code> class.
+ </dd>
+ <dt>
+ <a id="ASN1Oid" name="ASN1Oid"></a>ASN1Oid
+ </dt>
+ <dd>
+ This class implements the ASN.1 <code>OBJECT IDENTIFIER</code>
+ type. This type is a sequence of integer components that identifies
+ an entity, such as an organization or an algorithm. Integer
+ components have no negative values. An <code>OBJECT
+ IDENTIFIER</code> value includes at least two components. The
+ corresponding Java<a href="#*">*</a> type is an array of integer
+ values.
+ </dd>
+ <dt>
+ <a id="ASN1Boolean" name="ASN1Boolean"></a> ASN1Boolean
+ </dt>
+ <dd>
+ This class implements the ASN.1 <code>BOOLEAN</code> type, which
+ corresponds to the <code>java.lang.Boolean</code> Java<a
+ href="#*">*</a> class.
+ </dd>
+ </dl>
+ <p class="class">
+ <a id="String_Types" name="String_Types"></a>String Types
+ </p>
+ <dl>
+ <dt>
+ <a id="ASN1StringType" name="ASN1StringType"></a>ASN1StringType
+ </dt>
+ <dd>
+ This is an abstract class that contains common functionality for
+ all ASN.1 string types, and includes the implementation of the
+ following types: <code>BMPString, IA5String, GeneralString,
+ PrintableString, TeletexString, UniversalString,</code> and
+ <code>UTF8String</code>. The class maps all these types to the
+ <code>java.lang.String</code> object.
+ <p class="note">
+ Note
+ </p>
+ <p class="notetext">
+ The current implementation does not verify allowed characters
+ for any of ASN.1 restricted characters types. The class only
+ stores and retrieves contents bytes to and from the
+ <code>String</code> object.
+ </p>
+ </dd>
+ </dl>
+ <dl>
+ <dt>
+ <a id="ASN1BitString" name="ASN1BitString"></a>ASN1BitString
+ </dt>
+ <dd>
+ This class represents the ASN.1 <code>BitString</code> type. The
+ corresponding Java<a href="#*">*</a> class is
+ <code>BitString</code> included in the <code>asn1</code> package.
+ The class provides implementation for decoding or encoding
+ <code>BitString</code> objects.
+ <p class="note">
+ Note
+ </p>
+ <p class="notetext">
+ A special use case for this ASN.1 type exists, when the type is
+ declared as <code>Named BitString</code>. For example:
+ </p>
+ <blockquote>
+ <blockquote>
+<pre>
+ Keys ::= BIT STRING {
+ Key1 (0),
+ Key2 (1),
+ MyKey (2)
+ }
+</pre>
+ </blockquote>
+ </blockquote>
+ <p class="notetext">
+ In this case, the BER specification [<a
+ href="#RULES_SPEC">3</a>] enables adding and removing any number
+ of trailing to and from the basic encoding. To provide a correct
+ type implementation, use the
+ <code>ASN1Bitstring.ASN1NamedBitList</code> class. By default,
+ the class maps the ASN.1 <code>Named BitString</code> type to an
+ array of primitive boolean values.
+ </p>
+ </dd>
+ <dt>
+ <a id="ASN1OctetString" name="ASN1OctetString"></a>ASN1OctetString
+ </dt>
+ <dd>
+ This class implements the ASN.1 <code>OctetString</code> type,
+ which corresponds to the Java<a href="#*">*</a> type of an array of
+ bytes.
+ </dd>
+ </dl>
+ <dl>
+ <dt>
+ <a id="ASN1UTCTime" name="ASN1UTCTime"></a> ASN1UTCTime
+ </dt>
+ <dd>
+ This class represents the ASN.1 <code>UTCTime</code> type. The
+ corresponding Java<a href="#*">*</a> class is
+ <code>java.util.Date</code>.
+ </dd>
+ <dt>
+ <a id="ASN1GeneralizedTime"
+ name="ASN1GeneralizedTime"></a>ASN1GeneralizedTime
+ </dt>
+ <dd>
+ This class represents the ASN.1 <code>GeneralizedTime</code> type.
+ The corresponding Java<a href="#*">*</a> class is
+ <code>java.util.Date</code>.
+ </dd>
+ </dl>
+ <p class="class">
+ <a id="Constructed_Types" name="Constructed_Types"></a>Constructed
+ Types
+ </p>
+ <dl>
+ <dt>
+ <a id="ASN1Sequence" name="ASN1Sequence"></a> ASN1Sequence
+ </dt>
+ <dd>
+ The class represents a ASN.1 type consisting of an ordered
+ collection of more than one type. A type in the collection can be
+ optional or can have default values. If a type in the collection is
+ marked as optional or default, then its value may be absent in the
+ encoding of the sequence type. If a default type is absent, then
+ its default value is used.<br />
+ An instance of the class is initialized with a Java<a
+ href="#*">*</a> array of ASN.1 classes that corresponds to the
+ notation of a sequence type. The order of ASN.1 classes in an
+ initialization array must strictly correspond to the type.<br />
+ For example, if a sequence type has the following types collection:
+ <code>integer</code>, <code>boolean</code>, <code>ANY</code>, then
+ an initialization array must contain three class instances in the
+ same order: <code>ASN1Boolean</code>, <code>ASN1Integer</code>,
+ <code>ASN1Any</code>.
+ </dd>
+ <dt>
+ <a id="ASN1SequenceOf" name="ASN1SequenceOf"></a>ASN1SequenceOf
+ </dt>
+ <dd>
+ The <code>SEQUENCE OF</code> type denotes an ordered collection of
+ one or more values of the selected ASN.1 type. An instance of the
+ class is initialized with an instance of the ASN.1 class according
+ to the type notation. The passed instance is used to decode or
+ encode all values in an collection.
+ </dd>
+ <dt>
+ <a id="ASN1SetOf" name="ASN1SetOf"></a>ASN1SetOf
+ </dt>
+ <dd>
+ The <code>SET OF</code> type denotes an unordered collection of one
+ or more values of the selected ASN.1 type. This class is similar to
+ the <code>ASN1SequenceOf</code> class.
+ </dd>
+ </dl>
+ <p class="class">
+ <a id="Tagged_Types" name="Tagged_Types"></a>Tagged Types
+ </p>
+ <dl>
+ <dt>
+ <a id="ASN1Explicit" name="ASN1Explicit"></a>ASN1Explicit
+ </dt>
+ <dd>
+ The class implements the ASN.1 <code>EXPLICIT</code> type tagging.
+ <em>Explicit tagging</em> denotes a type derived from another type
+ by adding an outer tag to the base type. This type can be
+ represented as a sequence type with only one component, so that the
+ implementation class acts as a container for another ASN.1 type.
+ </dd>
+ <dt>
+ <a id="Class_ASNImplicit" name="Class_ASNImplicit"></a>ASN1Implicit
+ </dt>
+ <dd>
+ The class implements the ASN.1 <code>IMPLICIT</code> type tagging.
+ An <em>implicitly tagged type</em> is a type derived from another
+ type by changing a tag of the base type. The implementation class
+ for this type changes only the tag when decoding or encoding the
+ base type.
+ </dd>
+ </dl>
+ <p class="class">
+ <a id="Other_Types" name="Other_Types"></a>Other Types
+ </p>
+ <dl>
+ <dt>
+ <a id="Class_ASNAny" name="Class_ASNAny"></a>ASN1Any
+ </dt>
+ <dd>
+ The class implements the ASN.1 <code>ANY</code> type. The type
+ denotes any ASN.1 type that can be defined by a value of the
+ <code>OBJECT IDENTIFIER</code> or by an integer index. The class
+ handles only raw data represented as a Java<a href="#*">*</a> byte
+ array. It is up to the application class to select the appropriate
+ decoder or encoder for retrieving or storing the content
+ respectively.
+ </dd>
+ <dt>
+ <a id="Class_ASNChoice" name="Class_ASNChoice"></a>ASN1Choice
+ </dt>
+ <dd>
+ The class implements the ASN.1 <code>CHOICE</code> type. The type
+ represents a list of one more type alternatives with distinct tags.
+ an instance of the class is initialized with the Java<a
+ href="#*">*</a> array of ASN.1 classes, which corresponds to a type
+ notation.<br />
+ For example, if a <code>CHOICE</code> type is specified as a list
+ of <code>boolean</code>, <code>OctetString</code> and
+ <code>UTCTime</code>, then an initialization array contains
+ instances of the <code>ASN1Boolean</code>,
+ <code>ASN1OctetString</code> and <code>ASN1UTCTime</code> classes.
+ During decoding or encoding, a required type alternative is
+ selected.
+ </dd>
+ </dl>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h2>
+ <a id="Encoding_Rules" name="Encoding_Rules"></a>Encoding Rules
+ </h2>
+ <p>
+ Encoding rules specify how to represent an ASN.1 type as a sequence of
+ octets. ASN.1 encoding rules are represented in the
+ <code>org.apache.harmony.security.asn1</code> package, as follows:
+ </p>
+ <ul>
+ <li>
+ <code>BerInputStream</code> and <code>DerInputStream</code> provide
+ decoding and verifying functionality for corresponding notation
+ rules.
+ </li>
+ <li>
+ <code>BerOutputStream</code> and <code>DerOutputStream</code>
+ provide the encoding functionality.
+ </li>
+ </ul>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h3>
+ <a id="Encoding" name="Encoding"></a>Encoding
+ </h3>
+ <p>
+ <em>Encoding</em> an object is the process of extracting all required
+ information from an object and storing it in a sequence of octets
+ according to the specified ASN.1 notation and encoding rules. The
+ common encoding functionality is implemented in the
+ <code>BerOutputStream</code> class. Encoding for DER is represented by
+ the <code>DEROutputStream</code> class.
+ </p>
+ <p>
+ The encoding of data for each ASN.1 type includes:
+ </p>
+ <ul>
+ <li>
+ identifier octets (for example, tag)
+ </li>
+ <li>
+ length octets
+ </li>
+ <li>
+ content octets
+ </li>
+ <li>
+ end-of-content octets
+ </li>
+ </ul>
+ <p class="note">
+ DER Encoding
+ </p>
+ <p class="notetext">
+ In contrast to BER, DER enables using only the definite form of length
+ encoding. That is why, before encoding an ASN.1 type value, the ASN.1
+ framework must obtain the length of the value. This requirement
+ determines the whole process of DER encoding: to calculate the length
+ of a constructed ASN.1 type, the framework calculates lengths of its
+ components, which can also be constructed, and so on. DER encoding
+ goes in the following stages:
+ </p>
+ <ul class="notetext">
+ <li>
+ <em>Collection</em>: Step by step, the DER encoder extracts all
+ data to be encoded, processes the data, calculates an encoding
+ length for each item, and stores all calculations and processed
+ data. Then, the encoder calculates the overall encoding length and
+ allocates required space.
+ </li>
+ <li>
+ <em>Encoding</em>: The DER encoder retrieves stored information,
+ encodes it according to the rules and writes the encoding to the
+ allocated byte array.
+ </li>
+ </ul>
+ <h3>
+ <a id="Decoding" name="Decoding"></a>Decoding
+ </h3>
+ <p>
+ <em>Decoding</em> or verifying the provided encoded form is a
+ sequential process of parsing strings of octets according to the
+ specified ASN.1 notation and encoding rules.
+ </p>
+ <p>
+ An iteration of decoding an ASN.1 type includes decoding its tag,
+ length, and content octets. The class <code>BerInputStream</code>
+ provides a common decoding implementation for all basic ASN.1 types.
+ To provide specific decoding for a basic ASN.1 type, a derived class
+ must override one of the corresponding methods. For example,
+ <code>DerInputStream</code> provides a custom implementation for
+ decoding the <code>ASN.1 Boolean</code> type by overriding the method
+ <code>readBoolean()</code>.
+ </p>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h2>
+ <a id="Notations_Implementation"
+ name="Notations_Implementation"></a>Implementing ASN.1 Notations
+ </h2>
+ <h3>
+ <a id="Basic_Classes" name="Basic_Classes"></a>Basic Classes
+ </h3>
+ <p>
+ In the current framework, the basic classes meet the following
+ requirements:
+ </p>
+ <ul>
+ <li>
+ All basic classes are thread-safe classes.<br />
+ This means that an instance of an ASN.1 class can be used by many
+ threads simultaneously for decoding or encoding a particular class
+ of Java<a href="#*">*</a> objects. An instance of an ASN.1 class
+ does not keep any specific data for a selected object. It only
+ provides a way for a decoder stream to store decoded data in a
+ Java<a href="#*">*</a> object, and a way for an encoder stream to
+ extract a data to be encoded from a Java<a href="#*">*</a> object.
+ </li>
+ <li>
+ All classes for string and primitive ASN.1 types provide access to
+ a reusable class instance via the static <code>getInstance()</code>
+ method.<br />
+ If a separate instance of an ASN.1 class is not required, this
+ method is used instead of a constructor. A constructor is provided
+ for inheritance purposes only.
+ </li>
+ </ul>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h3>
+ <a id="Custom_classes" name="Custom_classes"></a>Custom Classes
+ </h3>
+ <p>
+ Classes from the <code>asn1</code> package that represent ASN.1 basic
+ types are used as building blocks for implementing a <em>custom</em>
+ ASN.1 encoding or decoding class. A custom ASN.1 class provides
+ mapping of an abstract ASN.1 type to a definite Java<a href="#*">*</a>
+ class.
+ </p>
+ <p>
+ Two approaches for implementing custom ASN.1 classes are available.
+ Custom classes can be designed as singleton Java<a href="#*">*</a>
+ classes or not. The choice depends on further use of the class
+ decoder. The singleton approach is not efficient when decoding only
+ one Java<a href="#*">*</a> object. However, for decoding a series of
+ encodings (for example, with an application server), the singleton
+ approach is rather effective because only one reusable decoder
+ instance exists. Creating a new decoder object for each decoded or
+ encoded Java<a href="#*">*</a> object leads to performance penalties.
+ </p>
+ <p>
+ To implement the singleton approach, a custom ASN.1 class must meet
+ the following requirements:
+ </p>
+ <ul>
+ <li>
+ Class has only one reusable instance and provides a way to access
+ it.
+ </li>
+ <li>
+ Class is thread-safe. Thread safety is provided by passing all
+ required data via parameters of methods. All data specific for a
+ Java<a href="#*">*</a> object is stored in the decoding or encoding
+ stream.
+ </li>
+ </ul>
+ <p class="example">
+ Example 3
+ </p>
+ <p class="exampletext">
+ This example illustrates the singleton approach to static instances of
+ ASN.1 custom classes for the <code>Extensions</code> and
+ <code>Extension</code> classes used in <a href="#example2">Example
+ 2</a> . For this, create an instance of a custom ASN.1 class as an
+ instance of an anonymous class as shown below.
+ </p>
+ <blockquote>
+<pre>
+class Extensions {
+ // instance of decoder/encoder
+ public static final ASN1SequenceOf ASN1 =
+ new ASN1SequenceOf(Extension.ASN1);
+
+ private List extensions;
+}
+
+class Extension {
+ // instance of decoder/encoder
+ public static final ASN1Sequence ASN1 =
+ new ASN1Sequence(new ASN1Type[] {
+ ASN1Oid.getInstance(), // extnID
+ ASN1Boolean.getInstance(), // critical
+ ASN1OctetString.getInstance()}) { // extnValue
+ // replace constructor
+ {
+ // set default value for critical field
+ // first parameter - a default value
+ // second parameter - an index of ASN.1 type in a sequence starting with 0
+ setDefault(Boolean.FALSE, 1);
+ }
+ };
+
+ private String extnID;
+ private boolean critical;
+ private byte extnValue[];
+
+}
+</pre>
+ </blockquote>
+ <p>
+ The <code>static final ASN1</code> field instance provides a mapping
+ between the Java<a href="#*">*</a> <code>Extension</code> class and
+ its ASN.1 notation. The field is initialized so that it reflects the
+ ASN.1 notation of the class: it is the instance of the
+ <code>ASN1Sequence</code> class that is initialized with instances of
+ the <code>ASN1Oid</code>, <code>ASN1Boolean</code> and
+ <code>ASN1OctetString</code> classes.
+ </p>
+ <p>
+ The <code>Extensions</code> class has a similar field. The field also
+ reflects the ASN.1 notation: it is the instance of the
+ <code>ASN1SequenceOf</code> class and it is initialized by the
+ <code>ASN1</code> field from the <code>Extension</code> class.
+ </p>
+ <p>
+ Figure 3 displays the correspondence between the application object
+ tree and the object tree of ASN.1 custom classes.
+ </p>
+ <p style="text-align: center">
+ <img src="images/example3.gif" alt="Tree" />
+ </p>
+ <p class="special">
+ Figure 3: Java Object and ASN.1 Custom Class Trees
+ </p>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h1>
+ Appendix: <a id="Appendix" name="Appendix"></a>Usage Examples
+ </h1>
+ <p>
+ This section demonstrates the usage of the ASN.1 framework.
+ </p>
+ <h3>
+ ASN.1 Boolean
+ </h3>
+ <p>
+ An abstract type can be defined as <code>ASN.1 Boolean</code>, for
+ example:
+ </p>
+ <blockquote>
+<pre>
+MyBooleanType ::= BOOLEAN;
+</pre>
+ </blockquote>
+ <p>
+ Then the following code can be used to decode and encode values of
+ this type:
+ </p>
+ <blockquote>
+<pre>
+// represents encoded ASN.1 Boolean type: false value
+byte encoding[] = new byte[] {0x01, 0x01, 0x00};
+
+// get instance of ASN.1 Boolean decoder/encoder
+ASN1Type asn1 = ASN1Boolean.getInstance();
+
+// decoded value is Boolean.FALSE
+Boolean value = (Boolean)asn1.decode(encoding);
+
+// encode Boolean.TRUE value
+
+// an array value equals to {0x01, 0x01, 0xFF}
+byte enc[] = asn1.encode(Boolean.TRUE);
+</pre>
+ </blockquote>
+ <h3>
+ ASN.1 Tagged Types
+ </h3>
+ <p>
+ The following ASN.1 notation can be used to define a tagged type:
+ </p>
+ <blockquote>
+<pre>
+MyTaggedType ::= [APPLICATION 0] EXPLICIT BOOLEAN;
+</pre>
+ </blockquote>
+ <p>
+ By default, a tagged type, <code>MyTaggedType</code>, is mapped to the
+ same Java<a href="#*">*</a> type as a basic type, see ASN.1
+ <code>BOOLEAN</code> above.
+ </p>
+ <p>
+ Then the following code can be used to decode and encode the values of
+ this type:
+ </p>
+ <blockquote>
+<pre>
+// represents encoded explicitly tagged ASN.1 Boolean type: false value
+byte encoding[] = new byte[] {0x60, 0x03, 0x01, 0x01, 0x00};
+
+// create an instance of custom decoder/encoder for tagged type
+ASN1Type asn1 = new ASN1Explicit(
+ ASN1Constants.CLASS_APPLICATION, // tagging class
+ 0, // tag number
+ ASN1Boolean.getInstance() // type to be tagged
+);
+
+// decoded value is Boolean.FALSE
+Boolean value = (Boolean)asn1.decode(encoding);
+
+// encode Boolean.TRUE value as explicitly tagged
+
+// an array value equals to {0x60, 0x03,0x01, 0x01, 0xFF}
+byte enc[] = asn1.encode(Boolean.TRUE);
+</pre>
+ </blockquote>
+ <h3>
+ ASN.1 Sequence Type
+ </h3>
+ <p>
+ A constructed ASN.1 type notation can go as follows.
+ </p>
+ <blockquote>
+<pre>
+MyConstructedType ::= SEQUENCE {
+ classVersion INTEGER,
+ isExtendable BOOLEAN DEFAULT FALSE
+}
+</pre>
+ </blockquote>
+ <p>
+ By default, a sequence type is mapped to an array of objects. In the
+ example, it is an array of two objects: the first object represents
+ <code>classVersion</code> and the second object represents the
+ <code>isExtendable</code> flag.
+ </p>
+ <p>
+ The following code can be used to decode and encode the values of this
+ type:
+ </p>
+ <blockquote>
+<pre>
+// create an instance custom decoder/encoder
+ASN1Type asn1 =
+ new ASN1Sequence(new ASN1Type[] {ASN1Integer.getInstance(), // classVersion
+ ASN1Boolean.getInstance()}) { // isExtendable
+ // replace constructor
+ {
+ // set default value for isExtendable field
+ // first parameter - a default value
+ // second parameter - an index of ASN.1 type in a sequence starting with 0
+ setDefault(Boolean.FALSE, 1);
+ }
+ };
+
+// decoded sequence value is mapped to array of objects
+Object value[] = (Object[])asn1.decode(someEncoding);
+
+// first value (ASN.1 Integer) is mapped by default to an array of bytes
+byte version[] = (byte[])value[0];
+
+// second value (ASN.1 Boolean) is mapped by default to a Boolean object
+Boolean isCritical = (Boolean)value[1];
+</pre>
+ </blockquote>
+ <p>
+ When it is necessary to change the default mapping of an array of
+ objects for the ASN.1 <code>Sequence</code> type to a custom Java<a
+ href="#*">*</a> class, two methods are overridden.
+ </p>
+ <blockquote>
+<pre>
+// class for storing MyConstructedType values
+class A {
+ int version;
+ boolean isExtendable;
+}
+
+// create an instance custom decoder/encoder
+ASN1Type asn1 =
+ new ASN1Sequence(new ASN1Type[] {ASN1Integer.getInstance(), // classVersion
+ ASN1Boolean.getInstance()}) { // isExtendable
+ // replace constructor
+ {
+ // set default value for isExtendable field
+ // first parameter - a default value
+ // second parameter - an index of ASN.1 type in a sequence starting with 0
+ setDefault(Boolean.FALSE, 1);
+ }
+
+ // for decoding
+ public Object getDecodedObject(BerInputStream in) throws IOException {
+ Object values[] = (Object[])in.content;
+
+ A a = new A();
+
+ // array of bytes to primitive int value
+ a.version = (new BigInteger((byte[])value[0])).intValue;
+
+ // Boolean object to primitive boolean
+ a.isExtendable = ((Boolean)value[1]).booleanValue();
+
+ return a;
+ }
+
+ // for encoding
+ public void getValues(Object object, Object values[]) {
+ A a = (A)object;
+
+ // primitive int value to array of bytes
+ values[0] = BigInteger.valueOf(a.version).toByteArray();
+
+ // primitive boolean value to Boolean object
+ values[1] = Boolean.valueOf(a.isCritical);
+ }
+ };
+
+// decoded sequence value is mapped to custom A class
+A a1 = (A)asn1.decode(someEncoding);
+
+// encode an instance of A class
+A a2 = new A();
+a2.version = 5;
+a2.isExtendable = true;
+byte enc[] = asn1.encode(a);
+</pre>
+ </blockquote>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h1>
+ <a id="References" name="References"></a>References
+ </h1>
+ <p>
+ [<a id="JAVA_API_SPEC" name="JAVA_API_SPEC"></a>1] Java API
+ Specification, <a href="http://java.sun.com/j2se/1.5.0/docs/api/"
+ target="_blank">http://java.sun.com/j2se/1.5.0/docs/api/</a>
+ </p>
+ <p>
+ [<a id="ASN_SPEC" name="ASN_SPEC"></a>2] Abstract Syntax Notation One
+ (ASN.1) Specification of Basic Notation ITU-T Rec. X.680 (2002) |
+ ISO/IEC 8824-1:2002
+ </p>
+ <p>
+ [<a id="RULES_SPEC" name="RULES_SPEC"></a>3] Specification of Basic
+ Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished
+ Encoding Rules (DER) ITU-T Rec. X.690 (2002) | ISO/IEC 8825-1:2002
+ </p>
+ <p>
+ [<a id="INFO_SITE" name="INFO_SITE"></a>4] ASN.1 Information Site, <a
+ href="http://asn1.elibel.tm.fr/en/standards/index.htm"
+ target="_blank">http://asn1.elibel.tm.fr/en/standards/index.htm</a>
+ </p>
+ <p>
+ [<a id="LAYMAN_GUIDE" name="LAYMAN_GUIDE"></a>5] <em>A Layman's Guide
+ to a Subset of ASN.1, BER, and DER,</em> <a
+ href="http://luca.ntop.org/Teaching/Appunti/asn1.html"
+ target="_blank">http://luca.ntop.org/Teaching/Appunti/asn1.html</a>
+ </p>
+ <p>
+ [<a id="EBOOK1" name="EBOOK1"></a>6] Olivier Dubuisson, translated by
+ Philippe Fouquart, <em>ASN.1 - Communication between heterogeneous
+ systems</em>, <a href="http://www.oss.com/asn1/dubuisson.html"
+ target="_blank">http://www.oss.com/asn1/dubuisson.html</a>
+ </p>
+ <p>
+ [<a id="EBOOK2" name="EBOOK2"></a>7] Professor John Larmouth,
+ <em>ASN.1 Complete</em>, <a
+ href="http://www.oss.com/asn1/larmouth.html"
+ target="_blank">http://www.oss.com/asn1/larmouth.html</a>
+ </p>
+ <p>
+ [<a id="RFC" name="RFC"></a>8] The Internet Engineering Task Force,
+ Requests for Comments, <a href="http://www.ietf.org/"
+ target="_blank">http://www.ietf.org/</a>
+ </p>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <br />
+ <br />
+ <br />
+ <br />
+ <p>
+ <a id="*" name="*">*</a> Other brands and names are the property of
+ their respective owners.
+ </p>
+ </body>
+</html>
+
+</div>
+ </td>
+ </tr>
+
+ <!-- FOOTER -->
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+ <tr><td colspan="2">
+ <div class="special"><em>
+ Copyright © 2003-2006, The Apache Software Foundation
+ </em></div>
+ </td></tr>
+ </table>
+ </body>
+ </html>
+<!-- end the processing -->
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+