From 14d710e449ea10d3b33e9e65c0cad1b3a5dad784 Mon Sep 17 00:00:00 2001 From: nmorozov Date: Thu, 21 Sep 2006 13:26:29 +0400 Subject: [PATCH] adding classlib docs to website from classlib module --- xdocs/subcomponents/classlibrary/ASN1Framework.htm | 1434 +++++++++++++++++++ xdocs/subcomponents/classlibrary/AWT.html | 1509 ++++++++++++++++++++ xdocs/subcomponents/classlibrary/DNSsupport.htm | 669 +++++++++ xdocs/subcomponents/classlibrary/Java2D.html | 501 +++++++ xdocs/subcomponents/classlibrary/Regexp.htm | 577 ++++++++ .../subcomponents/classlibrary/asn1_framework.xml | 30 xdocs/subcomponents/classlibrary/awt.xml | 30 xdocs/subcomponents/classlibrary/dns_support.xml | 30 xdocs/subcomponents/classlibrary/java2d.xml | 30 xdocs/subcomponents/classlibrary/regexp.xml | 30 10 files changed, 4840 insertions(+), 0 deletions(-) diff --git a/xdocs/subcomponents/classlibrary/ASN1Framework.htm b/xdocs/subcomponents/classlibrary/ASN1Framework.htm new file mode 100755 index 0000000..871fed1 --- /dev/null +++ b/xdocs/subcomponents/classlibrary/ASN1Framework.htm @@ -0,0 +1,1434 @@ + + + + + + + + ASN.1 Framework + + + + +

+ ASN.1 Framework +

+

+ Revision History +

+

+ Disclaimer +

+

+ About this Document +

+

+ Purpose +

+

+ Intended Audience +

+

+ Documentation Conventions +

+

+ Introduction to ASN.1 +

+

+ About +

+

+ ASN.1 Basic Types +

+

+ ASN.1 Framework in Harmony +

+

+ About +

+

+ Mapping between ASN.1 and Java Types +

+

+ Harmony ASN.1 Classes +

+

+ Encoding Rules +

+

+ Implementing ASN.1 Notations +

+

+ Appendix: Usage Examples +

+

+ References +

+

+ Revision History +

+ + + + + + + + + + + + + + + + +
+ Version + + Version Information + + Date +
+ Initial version + + Nadya Morozova, Stepan Mishura: document created
+ Special thanks to Sergey Dmitriev for assistance + 		+ November 16, 2005 +
+ Formatting update + + Nadya Morozova + + September 21, 2006 +
+

+ Disclaimer and Legal + Information +

+

+ 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. +

+

+ About This + Document +

+

+ Purpose +

+

+ 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. +

+

+ Intended + Audience +

+

+ 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* programming language. +

+

+ Documentation Conventions +

+

+ This document uses the unified + conventions for the Harmony documentation kit. +

+

+ Back to Top +

+

+ Introduction to ASN.1 +

+

+ About +

+

+ 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 [2]. ASN.1 is fully platform- and + language-independent. ASN.1 goes with the encoding rules, which + determine how to represent a value of an abstract type as a string of + octets [3]. +

+

+ The Java* API specification [1] employs ASN.1 in the following ways: +

+ +

+ To learn more about ASN.1, you can use online documentation [4], [5], and + publications [6], [7]. +

+

+ Back to Top +

+

+ ASN.1 Basic Types +

+

+ ASN.1 has the following basic types: +

+ +

+ These types are used to specify a wide range of other abstract types, + as shown in Example 1. +

+

+ Example 1 +

+

+ This example is based on RFC 3280 [8]. +

+
+
+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) }
+
+
+

+ In this example, the basic ASN.1 types SEQUENCE, + OBJECT IDENTIFIER, BOOLEAN and OCTET + STRING are used to specify a new abstract type + Extension. The newly created type is then used with + another basic type SEQUENCE OF to describe the + Extensions type. The ASN.1 INTEGER type is + used to specify the Version abstract type and to provide + constraints for this type. +

+

+ Back to Top +

+

+ ASN.1 Framework in + Harmony +

+

+ 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* types, and represents the + hierarchy of ASN.1 types representation in the current framework. +

+

+ About +

+

+ 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* + object and its ASN.1 encoded form, as shown in Figure 1. +

+
+
+

+ overview +

+

+ Figure 1: ASN.1 Framework Layer +

+

+ The Harmony ASN.1 framework is characterized by: +

+ +

+ The framework enables the following: +

+ +

+ Note +

+

+ 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). +

+

+ Mapping between + ASN.1 and Java* Types +

+

+ The framework maps all ASN.1 abstract types and notations to Java* primitive types or Java* classes. +

+

+ Example 2 +

+

+ The notations in Example 1 can be represented + as the following Java* classes: +

+
+
+public class Extension {
+    private String extnID;
+    private boolean critical;
+    private byte extnValue[];
+}
+
+public class Extensions {
+    // contains elements of Extension class
+    private List extensions;
+}
+
+
+

+ The Extension notation corresponds to a Java* class with three fields, where every field corresponds + to one entry in the Extension notation. For example, the + critical BOOLEAN DEFAULT FALSE field in the + Extension notation corresponds to the boolean + critical field in the Java* class. The + Extensions notation equals to a Java* + class with a field that contains an ordered collection of the + instances of the Extension class. +

+

+ The table below describes the default mapping ASN.1 types to Java* types, and indicates the class providing the specified + mapping in the current framework. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ ASN.1 Type + + Java* Type + + Framework Class +
+ Primitive + +
+ INTEGER + + byte[] + + ASN1Integer +
+ ENUMERATED + + byte[] + + ASN1Enumerated +
+ OBJECT IDENTIFIER + + int[] + + ASN1Oid +
+ BOOLEAN + + java.lang.Boolean + + ASN1Boolean +
+ String + + BitString + + asn1.BitString + + ASN1BitString +
+ OctetString + + byte[] + + ASN1OctetString +
+ PrintableString + + java.lang.String + + ASN1StringType +
+ T61String + + java.lang.String + + ASN1StringType +
+ IA5String + + java.lang.String + + ASN1StringType +
+ UTF8String + + java.lang.String + + ASN1StringType +
+ BMPString + + java.lang.String + + ASN1StringType +
+ GeneralString + + java.lang.String + + ASN1StringType +
+ TeletexString + + java.lang.String + + ASN1StringType +
+ UniversalString + + java.lang.String + + ASN1StringType +
+ UTCTime + + java.util.Date + + ASN1UTCTime +
+ GeneralizedTime + + java.util.Date + + ASN1GeneralizedTime +
+ Constructed + + SEQUENCE + + Object[] + + ASN1Sequence +
+ SEQUENCE OF + + java.util.List + + ASN1SequenceOf +
+ SET OF + + java.util.List + + ASN1SetOf +
+ Tagged + + EXPLICIT + + based type + + ASN1Explicit +
+ IMPLICIT + + based type + + ASN1Implicit +
+ Other + + ANY + + byte[] + + ASN1Any +
+ CHOICE + + one of chosen types + + ASN1Choice +
+

+ Back to Top +

+

+ Harmony ASN.1 + Classes +

+

+ Basic ASN.1 types are in the + org.apache.harmony.security.asn1 package in accordance + with the hierarchy shown in Figure 2. +

+

+ package +

+

+ Figure 2: Class Hierarchy +

+

+ The subsequent sections provide as short description of the classes + included in the package. +

+

+ Primitive Types +

+
+
+ ASN1Integer +
+
+ This class represents the ASN.1 INTEGER 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* type for storing the integer value, for example, an + instance of the java.math.BigInteger class. By + default, an integer value is stored in an array of bytes. +
+
+ ASN1Enumerated +
+
+ This class represents the ASN.1 ENUMERATED type that + denotes a set of integer values. The implementation of this class + is similar to that of the ASN1Integer class. +
+
+ ASN1Oid +
+
+ This class implements the ASN.1 OBJECT IDENTIFIER + 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 OBJECT + IDENTIFIER value includes at least two components. The + corresponding Java* type is an array of integer + values. +
+
+ ASN1Boolean +
+
+ This class implements the ASN.1 BOOLEAN type, which + corresponds to the java.lang.Boolean Java* class. +
+
+

+ String Types +

+
+
+ ASN1StringType +
+
+ This is an abstract class that contains common functionality for + all ASN.1 string types, and includes the implementation of the + following types: BMPString, IA5String, GeneralString, + PrintableString, TeletexString, UniversalString, and + UTF8String. The class maps all these types to the + java.lang.String object. +

+ Note +

+

+ 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 + String object. +

+
+
+
+
+ ASN1BitString +
+
+ This class represents the ASN.1 BitString type. The + corresponding Java* class is + BitString included in the asn1 package. + The class provides implementation for decoding or encoding + BitString objects. +

+ Note +

+

+ A special use case for this ASN.1 type exists, when the type is + declared as Named BitString. For example: +

+
+
+
+    Keys ::= BIT STRING {
+        Key1 (0),
+        Key2 (1),
+        MyKey (2)
+    }
+
+
+
+

+ In this case, the BER specification [3] enables adding and removing any number + of trailing to and from the basic encoding. To provide a correct + type implementation, use the + ASN1Bitstring.ASN1NamedBitList class. By default, + the class maps the ASN.1 Named BitString type to an + array of primitive boolean values. +

+
+
+ ASN1OctetString +
+
+ This class implements the ASN.1 OctetString type, + which corresponds to the Java* type of an array of + bytes. +
+
+
+
+ ASN1UTCTime +
+
+ This class represents the ASN.1 UTCTime type. The + corresponding Java* class is + java.util.Date. +
+
+ ASN1GeneralizedTime +
+
+ This class represents the ASN.1 GeneralizedTime type. + The corresponding Java* class is + java.util.Date. +
+
+

+ Constructed + Types +

+
+
+ ASN1Sequence +
+
+ 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.
+ An instance of the class is initialized with a Java* 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.
+ For example, if a sequence type has the following types collection: + integer, boolean, ANY, then + an initialization array must contain three class instances in the + same order: ASN1Boolean, ASN1Integer, + ASN1Any. +
+
+ ASN1SequenceOf +
+
+ The SEQUENCE OF 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. +
+
+ ASN1SetOf +
+
+ The SET OF type denotes an unordered collection of one + or more values of the selected ASN.1 type. This class is similar to + the ASN1SequenceOf class. +
+
+

+ Tagged Types +

+
+
+ ASN1Explicit +
+
+ The class implements the ASN.1 EXPLICIT type tagging. + Explicit tagging 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. +
+
+ ASN1Implicit +
+
+ The class implements the ASN.1 IMPLICIT type tagging. + An implicitly tagged type 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. +
+
+

+ Other Types +

+
+
+ ASN1Any +
+
+ The class implements the ASN.1 ANY type. The type + denotes any ASN.1 type that can be defined by a value of the + OBJECT IDENTIFIER or by an integer index. The class + handles only raw data represented as a Java* byte + array. It is up to the application class to select the appropriate + decoder or encoder for retrieving or storing the content + respectively. +
+
+ ASN1Choice +
+
+ The class implements the ASN.1 CHOICE type. The type + represents a list of one more type alternatives with distinct tags. + an instance of the class is initialized with the Java* array of ASN.1 classes, which corresponds to a type + notation.
+ For example, if a CHOICE type is specified as a list + of boolean, OctetString and + UTCTime, then an initialization array contains + instances of the ASN1Boolean, + ASN1OctetString and ASN1UTCTime classes. + During decoding or encoding, a required type alternative is + selected. +
+
+

+ Back to Top +

+

+ Encoding Rules +

+

+ Encoding rules specify how to represent an ASN.1 type as a sequence of + octets. ASN.1 encoding rules are represented in the + org.apache.harmony.security.asn1 package, as follows: +

+ +

+ Back to Top +

+

+ Encoding +

+

+ Encoding 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 + BerOutputStream class. Encoding for DER is represented by + the DEROutputStream class. +

+

+ The encoding of data for each ASN.1 type includes: +

+ +

+ DER Encoding +

+

+ 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: +

+ +

+ Decoding +

+

+ Decoding 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. +

+

+ An iteration of decoding an ASN.1 type includes decoding its tag, + length, and content octets. The class BerInputStream + 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, + DerInputStream provides a custom implementation for + decoding the ASN.1 Boolean type by overriding the method + readBoolean(). +

+

+ Back to Top +

+

+ Implementing ASN.1 Notations +

+

+ Basic Classes +

+

+ In the current framework, the basic classes meet the following + requirements: +

+ +

+ Back to Top +

+

+ Custom Classes +

+

+ Classes from the asn1 package that represent ASN.1 basic + types are used as building blocks for implementing a custom + ASN.1 encoding or decoding class. A custom ASN.1 class provides + mapping of an abstract ASN.1 type to a definite Java* + class. +

+

+ Two approaches for implementing custom ASN.1 classes are available. + Custom classes can be designed as singleton Java* + classes or not. The choice depends on further use of the class + decoder. The singleton approach is not efficient when decoding only + one Java* 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* object leads to performance penalties. +

+

+ To implement the singleton approach, a custom ASN.1 class must meet + the following requirements: +

+ +

+ Example 3 +

+

+ This example illustrates the singleton approach to static instances of + ASN.1 custom classes for the Extensions and + Extension classes used in Example + 2 . For this, create an instance of a custom ASN.1 class as an + instance of an anonymous class as shown below. +

+
+
+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[];
+
+}
+
+
+

+ The static final ASN1 field instance provides a mapping + between the Java* Extension 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 + ASN1Sequence class that is initialized with instances of + the ASN1Oid, ASN1Boolean and + ASN1OctetString classes. +

+

+ The Extensions class has a similar field. The field also + reflects the ASN.1 notation: it is the instance of the + ASN1SequenceOf class and it is initialized by the + ASN1 field from the Extension class. +

+

+ Figure 3 displays the correspondence between the application object + tree and the object tree of ASN.1 custom classes. +

+

+ Tree +

+

+ Figure 3: Java Object and ASN.1 Custom Class Trees +

+

+ Back to Top +

+

+ Appendix: Usage Examples +

+

+ This section demonstrates the usage of the ASN.1 framework. +

+

+ ASN.1 Boolean +

+

+ An abstract type can be defined as ASN.1 Boolean, for + example: +

+
+
+MyBooleanType ::= BOOLEAN;
+
+
+

+ Then the following code can be used to decode and encode values of + this type: +

+
+
+// 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);
+
+
+

+ ASN.1 Tagged Types +

+

+ The following ASN.1 notation can be used to define a tagged type: +

+
+
+MyTaggedType ::= [APPLICATION 0] EXPLICIT BOOLEAN;
+
+
+

+ By default, a tagged type, MyTaggedType, is mapped to the + same Java* type as a basic type, see ASN.1 + BOOLEAN above. +

+

+ Then the following code can be used to decode and encode the values of + this type: +

+
+
+// 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);
+
+
+

+ ASN.1 Sequence Type +

+

+ A constructed ASN.1 type notation can go as follows. +

+
+
+MyConstructedType ::= SEQUENCE {
+    classVersion INTEGER,
+    isExtendable BOOLEAN DEFAULT FALSE
+}
+
+
+

+ 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 + classVersion and the second object represents the + isExtendable flag. +

+

+ The following code can be used to decode and encode the values of this + type: +

+
+
+// 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]; 
+
+
+

+ When it is necessary to change the default mapping of an array of + objects for the ASN.1 Sequence type to a custom Java* class, two methods are overridden. +

+
+
+// 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);
+
+
+

+ Back to Top +

+

+ References +

+

+ [1] Java API + Specification, http://java.sun.com/j2se/1.5.0/docs/api/ +

+

+ [2] Abstract Syntax Notation One + (ASN.1) Specification of Basic Notation ITU-T Rec. X.680 (2002) | + ISO/IEC 8824-1:2002 +

+

+ [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 +

+

+ [4] ASN.1 Information Site, http://asn1.elibel.tm.fr/en/standards/index.htm +

+

+ [5] A Layman's Guide + to a Subset of ASN.1, BER, and DER, http://luca.ntop.org/Teaching/Appunti/asn1.html +

+

+ [6] Olivier Dubuisson, translated by + Philippe Fouquart, ASN.1 - Communication between heterogeneous + systems, http://www.oss.com/asn1/dubuisson.html +

+

+ [7] Professor John Larmouth, + ASN.1 Complete, http://www.oss.com/asn1/larmouth.html +

+

+ [8] The Internet Engineering Task Force, + Requests for Comments, http://www.ietf.org/ +

+

+ Back to Top +

+
+
+
+
+

+ * Other brands and names are the property of + their respective owners. +

+ + + diff --git a/xdocs/subcomponents/classlibrary/AWT.html b/xdocs/subcomponents/classlibrary/AWT.html new file mode 100755 index 0000000..57560ff --- /dev/null +++ b/xdocs/subcomponents/classlibrary/AWT.html @@ -0,0 +1,1509 @@ + + + + + + Abstract Windowing Toolkit + + + + +

+ Abstract Window Toolkit Framework +

+

+ Revision History +

+

+ Disclaimer and Legal + Information +

+

+ About this Document +

+

+ Purpose +

+

+ Intended Audience +

+

+ Documentation Conventions +

+

+ Introduction to AWT +

+

+ AWT in DRL +

+

+ Event Handling +

+
+

+ Native and AWT Events +

+

+ Event Dispatch Thread +

+

+ Native and AWT Events Priority +

+

+ Native Events Handling +

+

+ Native and AWT + Event Handlers Cooperation +

+
+

+ Focus Subsystem +

+
+

+ Focus Dispatcher +

+

+ AWT Level +

+

+ DRL Focus + Implementation Specifics +

+
+

+ Visual Themes in AWT +

+
+

+ Default Theme +

+

+ Derived Themes +

+

+ Implementation Specifics +

+

+ Using + State Interfaces in a Standard Component +

+

+ Windows* Theme +

+
+

+ Multi-threading Support +

+
+

+ Why Synchronize +

+

+ How to Synchronize +

+

+ When to Synchronize +

+

+ Synchronizer +

+
+

+ References +

+

+ Revision History +

+ + + + + + + + + + + + + + + + +
+ Version + + Version Information + + Date +
+ Initial version + + Nadya Morozova, Pavel Dolgov: document created. + + May 10, 2006 +
+ Formatting update + + Nadya Morozova + + September 21, 2006 +
+

+ Disclaimer and Legal + Information +

+

+ Copyright 2005-2006 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. +

+

+ About This + Document +

+

+ Purpose +

+

+ This document introduces the AWT (Abstract Window Toolkit) framework + delivered as part of the DRL (Dynamic Run-time Layer) initiative. This + document focuses on the characteristics of the current AWT + implementation. +

+

+ Intended + Audience +

+

+ The target audience for the document includes a wide community of + engineers interested in further work with AWT to contribute to its + development. The document assumes that readers are familiar with AWT + and the Java* programming language. +

+

+ Documentation Conventions +

+

+ This document uses the unified conventions for the DRL documentation kit. +

+

+ Back to Top +

+

+ Introduction to AWT +

+

+ As indicated in the specification [1], the + Abstract Window Toolkit (AWT) is a part of the Java* + Foundation Classes (JFC). AWT provides basic facilities to develop + graphical user interfaces (GUI) and to draw simple graphics for + platform-independent applets and applications. +

+

+ In AWT, GUI consists of components, such as buttons, menus, + and top-level windows. One of the main AWT features is that all its + built-in components are heavy-weight, that is, every Java* component has a native GUI object behind it. The Swing + library [2] is built on the basis of AWT and + uses light-weight components, which do not have the 1:1 mapping with + native resources. +

+

+ AWT in DRL +

+

+ This document describes major design features and internal specifics + of the DRL AWT implementation. Further in this document, AWT denotes + the DRL implementation for convenience.
+ To summarize, DRL AWT has the following key features: +

+ +

+ Back to Top +

+

+ Event Handling +

+

+ AWT helps applications react to user's actions and traces the system + state and the AWT internal state by means of events. Subsequent + sections describe the AWT event handling implementation in DRL with + focus on the interaction between AWT and the native system, + specifically, the GUI subsystem of OS. For information on application + events handling, consult the AWT specification [1]. +

+

+ Native and + AWT Events +

+

+ The DRL AWT framework deals with the following types of events: +

+ +

+ Event Dispatch Thread +

+

+ AWT has the event dispatch thread (EDT) at its basis, + represented by the class java.awt.EventDispatchThread. + This thread handles all generated types of events by going over the + loop shown in Figure 1. EDT starts on AWT Toolkit creation and stops + on application termination. +

+

+ AWT and native event handling order +

+

+ Figure 1: Native and AWT Events Handling +

+

+ In more detail, EDT performs the following event loop: +

+
    +
  1. + Wait for and get the native event from operating system. +
    2. +
  2. + Decode the native event into an AWT event. +
    3. +
  3. + Dispatch the AWT event: find the target AWT component for this + event and pass it to this component through + the java.awt.Dispatcher class. +
    4. +
  4. + Push the AWT event to the event queue represented by + the java.awt.EventQueue class. +
    5. +
  5. + Pop all AWT events from the event queue. +
    6. +
  6. + Pass the given AWT events to the appropriate AWT component by using + the java.awt.Component.processXYZEvent() methods. +
    7. +
  7. + Call the appropriate AWT component’s event listeners of + the EventListener interface. Applications should + implement appropriate listeners' interfaces to react to specific + events. +
    8. +
+

+ Native and AWT Events + Priority +

+ +

+ Back to Top +

+

+ Native Events Handling +

+

+ This section defines native events types and the way AWT handles these + events based on their type. +

+

+ Native Events Classification +

+

+ Figure 3 below demonstrates how native events can be classified by + their role in the AWT framework. +

+

+ Native events: 4 subtypes +

+

+ Figure 3: Native Events Classification +

+ +

+ Abstracting the Native Platform +

+

+ Native events handling goes in two stages: the first stage depends on + the native platform, and the second stage is the same on all supported + platforms. Platform-dependent functionality comprises the Window + Toolkit, WTK, in the org.apache.harmony.awt.wtk + package. The platform-dependent and platform-independent levels + cooperate via three main interfaces of this + package: NativeEventListener, NativeEvent, + and NativeEventQueue, as shown in Figure 2. Classes + implementing the NativeEvent + and NativeEventQueue interfaces are platform-specific. + For example, the NativeEvent interface is implemented by + the classes LinuxEvent and WinEvent for the + Linux* and Windows* systems + respectively. +

+

+ Interfaces depending and not depending on the underlying platform +

+

+ Figure 2: Interfaces for Abstracting the Native Platform +

+

+   +

+

+ Classes of the NativeEvent interface convert information + about native events to a platform-independent format. + The NativeEventQueue interface fetches native events, and + the NativeEventListener interface of the Java* EDT thread handles native events. In the DRL AWT + implementation, native and AWT events are handled by the single EDT + thread. See the Multi-threading + Support section for more information. +

+

+ Back to Top +

+

+ Native Event Dispatching +

+

+ The method onEvent() in the + platform-dependent NativeEventListener interface + processes native events. Platform-dependent classes + implementing NativeEventQueue call this method to handle + a relevant native event, see Figure 4. +

+

+ AWT handles relevant native events by following these steps: +

+
    +
  1. + The platform-specific implementation of + the NativeEvent interface translates the event to a + unified format described by the interface NativeEvent. +
    2. +
  2. + The platform-specific implementation + of NativeEventQueue calls the EDT + method onEvent() and passes the decoded event as a + parameter. +
    3. +
  3. + EDT passes the event to the java.awt.Dispatcher class + identifying the type of event. +
    4. +
  4. + Depending on the event type, the dispatcher can handle the event or + transmit it to a specific sub-dispatcher. For + example, java.awt.MouseDispatcher works with mouse + events, java.awt.Dispatcher.KeyDispatcher processes + keyboard events. +
    5. +
+

+ The result of native event dispatching depends on the event type: + state event, signal or invisible. Signal native events are translated + to AWT events explicitly (Figure 4, second column). For state and + invisible events, the AWT framework updates the state of the AWT + object corresponding to the native object that sent the event. For + state events, this implicitly generates an AWT event signaling an AWT + object state change (Figure 4, third column). For invisible events, + the AWT object state gets updated silently (Figure 4, fourth column). +

+

+ Native events handling by the 4 subtypes +

+

+ Figure 4: Native Events Handling by Type +

+

+ Back to Top +

+

+ Native and AWT + Event Handlers Cooperation +

+

+ Native events often result in new AWT events that need to be handled. + This section describes when and how AWT event handlers are called for + this purpose. +

+

+ The Windows* OS generates synchronous and + asynchronous native events, so that AWT must be ready to handle nested + calls to the event handler. In this case, AWT makes an additional + effort to handle AWT events one by one. DRL AWT uses + the WindowProc event handler inside WTK for interaction + with Windows*. The OS calls this handler for handling + any native event in AWT. +

+

+ The Linux* event handling mechanism is different with + its own method for handling native events. In this OS, all native + events are asynchronous and no nesting happens. +

+

+ Handling a single event +

+

+ Figure 5 is an example of mouse click event handling in AWT. In the + given case, the AWT listener does not co-operate with the underlying + native system, and, consequently, no other native events are produced + during the listener's operation. The example demonstrates handling an + event on Windows*. +

+

+ Native events handling by the 4 subtypes +

+

+ Figure 5: Mouse Click Event Handling +

+

+ Numbers in the figure above correspond to the following steps in the + event handling flow: +

+
    +
  1. + The OS calls WindowProc to handle the native event. + The type of event is determined, information about this event is + gathered and passed to the onEvent() method + of NativeEventListener. +
    2. +
  2. + The java.awt.Dispatcher class finds the appropriate + target for this event and posts an AWT event to the AWT event + queue. In this example, it is MouseEvent. +
    3. +
  3. + The method onEventNestingEnd() is called to handle all + accumulated AWT events. MouseEvent is fetched from the + event queue and finally dispatched. Listeners of the event's target + are called at this point. +
    4. +
  4. +  WindowProc returns. +
    5. +
+

+ Back to Top +

+

+ Handling nested events +

+

+ Figure 6 is an example of mouse click event handling with the event + listener requests keyboard focus on the clicked component. +

+

+ Nested Event handling +

+

+ Figure 6: Mouse Click Event Handling with a Nested Event +

+

+ Numbers in the figure above correspond to the following steps in the + event handling flow: +

+
    +
  1. + The OS calls WindowProc, the native event is + transformed into an AWT event and stored in the event queue. +
    2. +
  2. + The event listener calls requestFocus(), which + indirectly results in a native API call. +
    3. +
  3. + The OS calls WindowProc to report the focus change + event. Because the previous call to WindowProc is not + complete yet, the new call is recognized as nested. +
    4. +
  4. + The dispatcher adds another AWT event, FocusEvent, to + the event queue. +
    5. +
  5. +  WindowProc returns without handling AWT events + because it is a nested native event handler. +
    6. +
  6. + The method onEventNestingEnd() is still working in the + first-level WindowProc handler. This method fetches + and dispatches the FocusEvent added at step 4. +
    7. +
  7. + When the AWT event queue is empty, WindowProc returns. +
    8. +
+

+ This technique guarantees that AWT event handlers are called + sequentially. The nested native event handler does not attempt to + handle pending AWT events. Instead, these events are collected in the + event queue to be handled later. The first-level native event handler + dispatches all the AWT events waiting in the queue. +

+

+ Back to Top +

+

+ Focus Subsystem +

+

+ The AWT focus subsystem is a set of classes for managing keyboard + input focus responsible for: +

+ +

+ In the DRL implementation, the focus subsystem functionality is + distributed among several internal layers: +

+ +

+ The interaction between user code and these levels of the focus + subsystem is shown on Figure 7 below. +

+

+ Detailed event handling schema +

+

+ Figure 7. Focus Event Data Flow +

+

+ The following code entities perform the major focus subsystem tasks: +

+ +

+ Subsequent sections describe the levels of focus management in more + detail and give specifics of the DRL implementation compared to the + focus specification [3]. +

+

+ Back to Top +

+

+ Focus Dispatcher +

+

+ The focus dispatcher responds to native focus events and, for those + relevant to AWT, sends an internal focus change event to the higher + AWT level. The dispatcher skips redundant native events and handles + event proxying supported on certain native platforms. The focus + dispatcher in DRL is characterized by the features listed below. +

+
+
+ Platform independence +
+
+ This component is platform-independent and handles native events in + a unified way. For example, when set to skip a false event, the + focus dispatcher does not change its behavior on platforms where + this type of event never occurs. +
+
+ Internal operation only: no interaction with user code +
+
+ The dispatcher does not generate AWT events and never calls client + code directly, synchronously. Instead, WTK passes event information + to the upper AWT level, which includes the flag indicating whether + the focus is lost or gained, the source and opposite components, + and the focused window. +
+
+ Focus Proxying +
+
+ When the focus is on an inactive window, focus proxies are used. A + focus proxy is a child of an active window that has the + native focus, whereas focus and key events are redirected to the + Java* focused window. This way, the native + decorations indicating the active state of the window are on the + active window. At the same time, keyboard input and focus AWT + events go to the focused window, whereas the native focused window + is the focus proxy. The focus dispatcher transfers the native focus + to the focus proxy and back when necessary. Events are redirected + by the keyboard focus manager. +

+ Events and Output in Event Proxying +

+

+ Figure 8. Focus Proxy +

+

+ If the active window is the focused window, no proxying occurs. + In this case, the nearest heavyweight ancestor of the focus + owner or the focus owner native window itself (if focus owner is + a heavy-weight component) has native focus. +

+
+
+

+ Back to Top +

+

+ AWT Level +

+

+ The higher level of the focus subsystem generates and posts all + necessary AWT events to the event queue. This level keeps track of the + following focus states: +

+ +

+ The AWT level of the focus subsystem handles focus requests + synchronously on every successful focus change request. When the + method requestFocus() is called, the keyboard focus + manager posts all necessary AWT events in the required order + irrespective of the success or failure of the native focus request. In + other words, the AWT subsystem does not wait until the native focus + request gets confirmed and the corresponding native events are + received. +

+

+ After receiving a notification from the native system, WTK requests + the AWT level to update the focus state via an internal request. For + example, if the native system reports an unsuccessful focus change, a + component might lose focus. +

+

+ Note +

+

+ Only certain native focus-related events cause a Java* focus state update. For example: +

+ +

+ Back to Top +

+

+ DRL Focus Implementation + Specifics +

+

+ Below, the specific features of DRL implementation are listed compared + to the focus specification grouped by their function. +

+
+
+ Replacing the + DefaultKeyboardFocusManager class +
+
+ The keyboard focus manager handles all events in the required order + and never synthesizes window activation events. Instead, the focus + manager skips the events that do not correspond to the current + focus state. Such events can be generated by the private API of + this class in response to native events. For example, the keyboard + focus manager ignores events sent to the window that has failed to + become the focused window because the corresponding AWT event was + dispatched and vetoed.
+ When handling the WINDOW_GAINED_FOCUS event, private + methods in the keyboard focus manager set focus on the appropriate + child component of the window. +
+
+ + Programmatic Traversal +
+
+ Disabling any ancestor of the focus owner, both light-weight and + heavy-weight, automatically initiates a focus traversal. +
+
+

+ Back to Top +

+

+ Visual + Themes in AWT +

+

+ This document describes the mechanism of drawing standard AWT + components with platform-independent Java* means or + platform-specific native API or using both approaches. +

+

+ Default theme +

+

+ You can paint standard components in many ways, including drawing the + component parts (text, background, shadows and all other elements) by + the means of class java.awt.Graphics. Note that the + framework must not paint standard components by the + method java.awt.Component.paint() because it could be + overridden. Instead, when processing a painting event, the framework + calls the package-private + method java.awt.Component.prepaint() just before calling + the method paint(). The prepaint() method + does the actual painting for all standard components by delegating the + painting task to the theme. This approach might not seem optimal, but + it works on all supported platforms without any changes. +

+

+ The org.apache.harmony.awt.Theme class implements the + default theme. Methods of this class do the following: +

+ +

+ The default theme class is platform-independent, non-abstract and + fully functional, and it usually works when the native theme is + disabled or not available, or when the native theme re-uses + functionality of the standard theme. +

+

+ Back to Top +

+

+ Derived themes +

+

+ You can create a custom theme that inherits from the default theme and + contains specific features. The current implementation contains + the WinTheme class that extends the default theme as + shown in Figure 9. +

+

+ To use the native API in your theme, extend the default theme + overriding its painting methods. In the derived theme, you can use the + additional features of specific implementation of + the Graphics class, and explicitly call native API + functions via wrappers, see org.apache.harmony.misc + package for details. Figure 9 below demonstrates theme-related classes + hierarchy with methods related to the Button component as + an example. A block of code for extending + the drawButton() method is shown in Example 1 below. +

+

+ OS specific themes as subclasses to the major theme +

+

+ Figure 9: Hierarchy of Theme Classes +

+

+   +

+

+ After creating a derived theme, turn it on by using the + property awt.theme. This property contains the name of a + subclass of default theme class used as the theme by all components. + If the property points to a non-existent class or if the required + native library is missing, or any other error occurs, the default + theme is used. If the property is not set, the native theme of the + current OS is used if it exists. If no OS theme exists, the default + theme is used. +

+

+ To force the default theme, set the command-line + option -Dawt.theme=0. As long as zero is an invalid class + name, this does the job. +

+

+ Back to Top +

+

+ Implementation details +

+

+ Painting standard components requires access to their internal state, + such as the pressed state, the focused state, the background color, + and the contained text. Because not all these attributes are visible + through the public API, the DRL AWT module provides a set of + interfaces to allow the theme to access private and public data. The + package org.apache.harmony.awt.state contains these + interfaces, such + as, TextState, CheckboxState, + and ButtonState. Each standard component class has an + inner class that implements the appropriate interface and has the + state field of that class declared. + The java.awt.Component class stores all functionality + common for all types of standard components. Specifically, + the java.awt.Component class has an inner + class ComponentState that implements + the org.apache.harmony.awt.state.State interface. This + inner class enables implementing the state of a specific component by + overriding only a few methods. +

+

+ Standard components delegate the painting and size calculation to the + currently active theme and pass their state field value as a parameter + to every method of the theme. +

+

+ Platform-specific and component-specific code is concentrated in + separate helper classes, such as DefaultButton, the + helper to the default theme, and WinCheckbox, the helper + to the Windows* theme. The theme class contains only + simple methods. +

+

+ Example 1 +

+

+ This is an example with the Button component. +

+
+public void drawButton(Graphics g, ButtonState s) { 
+    drawButtonBackground(g, s); 
+    drawButtonText(g, s); 
+} 
+protected void drawButtonBackground(Graphics g, ButtonState s) { 
+    DefaultButton.drawBackground(g, s); 
+} 
+protected void drawButtonText(Graphics g, ButtonState s) { 
+    DefaultButton.drawText(g, s); 
+}
+
+

+ When designing a custom theme, you may need to override some of these + protected methods. +

+

+ Figure 10 shows an example of component classes relation, inner states + and the inheritance hierarchy of component state interfaces. The + figure contains short names for convenience, for example, +  Component actually means +  java.awt.Component. +

+

+ Methods and classes related to state change operations +

+

+ Figure 10: Inheritance and Composition for Components' State +

+

+ Back to Top +

+

+ Using State + Interfaces in a Standard Component +

+

+ This section illustrates how the state interfaces are used in + the Button component. In DRL AWT, all standard components + follow the same model. +

+

+ This is a part of the java.awt.Button code that + illustrates how to use visual themes in standard components. +

+
+class State extends Component.ComponentState implements ButtonState { … } 
+final transient State state = new State(); 
+    
+void prepaint(Graphics g) { 
+    toolkit.theme.drawButton(g, state); 
+}
+
+

+ The framework calls the prepaint() method, which paints + standard components. The painting itself is done by the theme class, + and all the information it requires is contained in the state + variable. +

+

+ Back to Top +

+

+ Windows* theme +

+

+ In DRL, the Windows* theme is implemented by the + class org.apache.harmony.awt.theme.windows.WinTheme, + which inherits from the + class org.apache.harmony.awt.Theme. +

+

+ The WinTheme class paints components using the Windows* API function DrawFrameControl() in the + classic mode and DrawThemeBackground() in the XP mode, + and basic Windows* API painting functions. +

+

+ The implementation also includes several helper classes: +

+ +

+ Note +

+

+ If the Windows* theme does not support the + combination of components attributes, it delegates painting to the + default theme by calling the super class. For example, the default + theme can be used when the background color of a push button differs + from the theme setting. +

+

+ Back to Top +

+

+ Multi-Threading support +

+

+ Complying to the specification [1], DRL AWT can + work within multi-threaded applications. This implementation ensures + consistency of AWT framework data when accessed by multiple threads. + For that, AWT synchronizes its key classes. +

+

+ Why synchronize +

+

+ The main purpose of synchronization is keeping the component hierarchy + consistent when component properties are queried and/or modified, so + that it potentially affects other components. This includes the + parent-child relationships, the child component order, inherited + properties, such as the font and the background color, the size and + position related properties, as well as visibility, focusable state + and other conditions relevant for message handling. Concurrent + modifications of these properties can make the AWT framework state + inconsistent. +

+

+ For example, if a thread adds a component to a list of child + components for a container without updating this component’s + field parent, another thread working with the same + component gets the wrong value of the parent field. + Moreover, the second thread may remove this component from the + container children list, which makes the behavior of the first thread + unpredictable. Synchronization helps avoid such problems. +

+

+ Back to Top +

+

+ How to synchronize +

+

+ When a method or a block of code deals with the data that must not be + modified concurrently, a synchronized section is used. The DRL + implementation uses a special monitor AWT lock more powerful + than built-in Java* synchronized blocks and methods. + The AWT lock is similar to the synchronization tools provided by + the java.util.concurrent package. The synchronized + section using the AWT lock has its own specifics, as demonstrated by + the example below. +

+

+ Example 2 +

+

+ This example provides an excerpt of code from + the Component class demonstrating a typical synchronized + section in the AWT code. The methods lockAWT() + and unlockAWT() are the boundaries of the critical + section. The code between them is synchronized by the AWT lock. +

+
+final transient Toolkit toolkit = Toolkit.getDefaultToolkit();
+…
+public Color getBackground() {
+    toolkit.lockAWT();
+    try {
+        if ((backColor == null) && (parent != null)) {
+            return parent.getBackground();
+        }
+        return backColor;
+    } finally {
+        toolkit.unlockAWT();
+    }
+}
+
+

+ From the syntactical standpoint, this is a try-finally structure, + which guarantees that the unlockAWT() method is always + called after doing the useful work in the body of try block. + Logically, it is used as an ordinary synchronized block, except when + using AWT lock extended functionality. +

+

+ Back to Top +

+

+ When to synchronize +

+

+ AWT synchronization covers the following classes: +

+ +

+ The total number of synchronized classes nears 40. +

+

+ Simple data structures, for example, Rectangle + or Point, are not protected from concurrent modifications + for performance reasons. +

+

+ General rules on how to use synchronized sections +

+ +

+ Exceptions +

+ +

+ Note +

+

+ In platform-specific event handling code, the event listener uses this + lock by calling methods onEventBegin() + and onEventEnd(). These methods + call lockAWT() and unlockAWT() respectively. + This is done to ensure that the dispatcher can find the event target + and that the data is not modified by another thread. +

+

+ Back to Top +

+

+ Synchronizer +

+

+ The org.apache.harmony.awt.wtk.Synchronizer class + implements the AWT lock. The Toolkit class holds the + reference to the synchronizer instance. In a standalone + application, Toolkit and Synchronizer are + singleton classes. In the multi-context mode, AWT provides + independent Toolkit and Synchronizer + instances per each context. +

+

+ Figure 11 shows the inheritance relationship of synchronizer classes. + The Linux* and Windows* operating + systems have their own classes. +

+

+ Windows and Linux synchronizers are subclasses of Synchronizer +

+

+ Figure 11: Synchronizer Classes +

+

+ The base class Synchronizer represents a mutex with a + high-priority event dispatch thread. All + user threads are served in the FIFO (first in first out) order, + whereas EDT has higher priority and is served in the LIFO (last in + first out) order. +

+

+ Back to Top +

+

+ Synchronizer for Linux* +

+

+ AWT uses the Xlib library to access native window resources on Linux*. The Xlib library is thread-safe and all user and EDT + threads can freely access the native system through the AWT interface, + as shown in Figure 12. As a result, the + class org.apache.harmony.awt.wtk.linux.LinuxSynchronizer + contains no extensions to java.awt.Synchronizer. +

+

+ user threads access native resources independently of the EDT thread +

+

+ Figure 12: Access to the Native System on Linux* +

+

+ Back to Top +

+

+ Synchronizer for Windows* +

+

+ Synchronization on Windows* is different due to + Windows* libraries specifics. Firstly, changing the + state of a native window usually produces a synchronous event that + reports this change. Secondly, only the thread that created a window + receives native events related to that window. +

+

+ In DRL AWT, the event dispatch thread + handles all native events and, consequently, is the only thread that + can create windows. EDT also changes the window’s state to + simplify the native events handling scheme. Non-EDT threads can create + and manipulate native windows by giving tasks to EDT. User and EDT + threads cooperation is shown in Figure 13. +

+

+ user threads access native resources via of the EDT thread +

+

+ Figure 13: Access to the Native System on Windows* + with EDT +

+

+ The org.apache.harmony.awt.wtk.windows.WinSynchronizer + class, the extension of Synchronizer, implements the + interface NativeServer, which enables user threads to + query EDT for access to native resources. +

+

+ However, delegating access to native resources to EDT requires a more + complicated synchronization mechanism. Using + the Synchronizer logic as is results in a potential + deadlock while handling native Windows* events. + Figure 14 shows the scenario of the deadlock. +

+

+ thread execution flows with deadlock illustrated +

+

+ Figure 14: Deadlock with the user thread and EDT +

+

+ t1: The user thread starts. +

+

+ t2: EDT starts. +

+

+ t3: The user thread obtains the AWT lock. +

+

+ t4: EDT tries to obtain the AWT lock and gets blocked. +

+

+ t5: The user thread requests a service from EDT via + the NativeServer interface and gets blocked forever + because EDT is blocked too. +

+

+ The WinSynchronizer class resolves the deadlock issue by + combining the synchronizer’s protocol and the native server + protocol. For that, EDT switches between handling events and providing + access to native resources for other running threads, as shown in + Figure 15. +

+

+ EDT modes +

+

+ Figure 15. EDT Operation +

+

+ This algorithm enables detecting a potential deadlock and resolving + it. When EDT is requested to provide access to native resources while + it is waiting to obtain the AWT lock, EDT awakes, serves the request + and resumes waiting. Serving the native resource request is + transparent for the event-handling side of EDT because this operation + is performed while EDT is inside of lockAWT() method. The + deadlock is resolved, as shown in Figure 16. +

+

+ Thread execution flow with no deadlock +

+

+ Figure 16: Deadlock Resolution by WinSynchronizer +

+

+ t1: The user thread starts. +

+

+ t2: EDT starts. +

+

+ t3: The user thread obtains the AWT lock. +

+

+ t4: EDT tries to obtain the AWT lock and gets blocked. +

+

+ t5: The user thread requests EDT service and also gets + blocked. EDT starts processing the request. +

+

+ t6: EDT finishes processing request. The user thread resumes. +

+

+ t7: The user thread releases the AWT lock, EDT obtains it. +

+

+ t8: The user thread may continue its work or exit. +

+

+ t9: EDT releases the AWT lock. +

+

+ t10: EDT continues operation. +

+

+ Back to Top +

+

+ References +

+

+ [1] AWT spec, http://java.sun.com/j2se/1.5.0/docs/guide/awt/index.html +

+

+ [2] Swing Library Description, http://java.sun.com/j2se/1.5.0/docs/guide/swing/index.html +

+

+ [3] AWT Focus Subsystem + specification, http://java.sun.com/j2se/1.5.0/docs/api/java/awt/doc-files/FocusSpec.html +

+

+   +

+

+ Back to Top +

+

+ (C) Copyright 2005-2006 Intel Corporation +

+

+ * Other brands and names are the property of + their respective owners. +

+ + + diff --git a/xdocs/subcomponents/classlibrary/DNSsupport.htm b/xdocs/subcomponents/classlibrary/DNSsupport.htm new file mode 100755 index 0000000..cb29029 --- /dev/null +++ b/xdocs/subcomponents/classlibrary/DNSsupport.htm @@ -0,0 +1,669 @@ + + + + + + DNS Service Provider + + + + +

+ DNS Service Provider +

+

+ Revision History +

+

+ Disclaimer and Legal Information +

+

+ About This Document +

+

+ Purpose +

+

+ Intended Audience +

+

+ Documentation Conventions +

+

+ Introduction to DNS Provider +

+

+ DNS Provider in DRL +

+

+ About +

+

+ DNS URL Syntax +

+

+ Attribute Identifiers +

+

+ API Mapping +

+

+ Environment Properties +

+

+ DNS Resolver +

+

+ Federation +

+

+ Appendix: Usage Examples +

+

+ References +

+

+ Revision History +

+ + + + + + + + + + + + + + + + + + +
+ Version + + Version Information + + Date +
+ Initial version + + Alexei Zakharov, Nadya Morozova: document created. + +   March 23, 2006 +
+ Formatting update + + Nadya Morozova + +   September 21, 2006 +
+

+ Disclaimer and Legal Information +

+

+ Copyright 2005-2006 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. +

+

+ About This + Document +

+

+ Purpose +

+

+ This document introduces the DRL implementation of the DNS service + provider for JNDI, the Java* Naming Directory + Interface. The document gives details on the DNS provider design, + includes an overall description of the package, and includes helpful + usage examples. The description documents the first version of the DRL + DNS service provider deployed in March 2006. +

+

+ Intended + Audience +

+

+ The target audience for the document includes a wide community of + engineers interested in using the DNS service provider for JNDI and in + further work with the product to contribute to its development. The + document assumes that readers are familiar with the Java* programming language, the Java* + Naming Directory Interface, and common concepts of the DNS protocol. +

+

+ Documentation Conventions +

+

+ This document uses the unified + conventions for the DRL documentation kit. +

+

+ Back to Top +

+

+ Introduction to DNS Provider +

+

+ The DNS service provider enables Java* applications + to access information stored in the Domain Name System database by + means of the Java* Naming and Directory Interface [1]. The provider presents the DNS namespace as a tree + of JNDI directory contexts, and DNS resource records as JNDI + attributes. +

+

+ Back to Top +

+

+ DNS + Provider in DRL +

+

+ This part of the document describes the DRL implementation of the DNS + provider as a whole and defines the API mapping, environment + properties usage, and other specific aspects. +

+

+ About +

+

+ This + is an independent implementation of the DNS service provider for JNDI. + More detailed information on JNDI and JNDI service providers can be + found at [1]. +

+

+ In DRL, the DNS service provider is a directory context associated + with a domain name. This way, DNS resource records correspond to JNDI + attributes. The DNS support functionality is mainly represented by the + following classes of the + org.apache.harmony.jndi.provider.dns package: +

+ +

+ DNS URL Syntax +

+

+ The DNS URL, or DNS Pseudo URL, passes the initial information + to the DNS context as a value for the + java.naming.provider.url property or as an argument to a + method of the initial context via the DNS URL provider. The DNS URL is + defined in the following format: +

+
+dns:[//host[:port]][/domain]

+
+

+ A given combination of host and port + indicates the DNS server to be used for serving requests about a given + domain. Given partial data, the following values are used instead of + missing parameters: +

+ +

+ Back to Top +

+

+ Attribute Identifiers +

+

+ Because this provider presents DNS resource records in the form of + JNDI attributes, the exact format of attribute identifiers must be + defined. These identifiers are accepted by different methods of the + DNS provider. An identifier consists of the following combination of + DNS class and type information: +

+
+[CLASS_IDENTIFIER] TYPE_IDENTIFIER

+
+

+ Currently supported class identifiers: +

+ +

+ Currently supported type identifiers: +

+ +

+ If the class identifier is missing, the provider assumes the + IN class identifier. For an unsupported attribute type, + calling getAttributes() returns a numerical value rather + than its type ID. The symbol "" indicates + ANY type or class, so that an empty string stands for any + type in any class. +

+

+ For more details about DNS resource record classes and types, see RFC + 1035 [2]. +

+

+ Back to Top +

+

+ API Mapping +

+

+ The DNSContext class, the main class of the DRL DNS + provider, implements the DirContext interface. Because + DNS allows a read-only service, DNSContext provides only + a part of the overall DirContext functionality. +

+

+ Below is the list of supported DirContext methods grouped + by functionality. All other methods throw + javax.naming.OperationNotSupportedException. +

+

+ Environment operations +

+

+ addToEnvironment()
+ getEnvironent()
+ removeFromEnvironment() +

+

+ Operations with DNS names +

+

+ composeName()
+ getNameInNamespace()
+ getNameParser() +

+

+ Querying attribute values +

+

+ getAttributes() +

+

+ This method queries the attribute values from the remote DNS server or + the local provider's cache. +

+

+ Lookup operations +

+

+ lookup()
+ lookupLink() +

+

+ The lookup algorithm works as follows: +

+
    +
  1. + Determines the attribute identifier (ID) contained in the + org.apache.harmony.jndi.provider.dns.lookup.attr + property. If the property value contains no attribute identifier, + the TXT attribute is used. +
    2. +
  2. + Calls getAttributes() to retrieve the values of + attributes with the identifier determined at step 1 for the + requested domain name. +
    3. +
  3. + Calls DriverManager.getObjectInstance() to obtain the + object instance for the requested domain name and the retrieved + attribute value(s). +
    4. +
  4. + Returns the object instance to the user application. +
    5. +
+

+ Note +

+

+ The user object factory must be able to create object instances for an + object of the + org.apache.harmony.jndi.provider.dns.DNSContext class [1]. If no object factories have been specified, the + lookup methods return an instance of DNSContext. +

+

+ List operations +

+

+ list()
+ listBindings() +

+

+ These methods list the entire content of the DNS zone via DNS zone + transfer mechanism. +

+

+ Releasing all resources +

+

+ close() +

+

+ Note +

+

+ Currently, this method does nothing because it has nothing to + release.
+

+

+
+ Back to Top +

+

+ Environment Properties +

+

+ The DNS service provider accepts a number of environment properties as + shown in the table below. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Property Name + + Function +
+ java.naming.authoritative + + Sets the authoritative bit [2] for all + outgoing messages when TRUE. +
+ org.apache.harmony.jndi.provider.dns.lookup.attr + + + Specifies the attribute identifier to be used in the lookup algorithm. +
+ org.apache.harmony.jndi.provider.dns.recursion + + Sets the recursion bit for outgoing messages when + TRUE. +
+ org.apache.harmony.jndi.provider.dns.timeout.initial + + + Indicates the initial timeout. +

+ When accessing remote data, the DNS client tries to query + all possible remote servers with this value taken as a + timeout. If this fails, the client increases the initial + timeout value by two times. If this also fails, a value 4 + times greater than the initial timeout is taken and so on + (x8, x16, ... ) until the maximum number of timeout + retries is reached, see the description of property + org.apache.harmony.jndi.provider.dns.timeout.retries. +

+
+ org.apache.harmony.jndi.provider.dns.timeout.retries + + + Sets the number of timeout retries, that is, the maximum + number of retries that can be performed when accessing a + remote DNS server. +

+ If all attempts fail and the maximum number of retries is + reached, the user gets an error message, see the + description of property + org.apache.harmony.jndi.provider.dns.timeout.initial. +

+
+ org.apache.harmony.jndi.providers.dns.threads.max + + + Determines the maximum number of threads that can be started + by a single instance of the DNS context. The default value is + 7. +
+ java.naming.provider.url + + Enumerates the initial DNS URLs. +

+ Multiple URLs must go in a space-separated list, see DNS URL Syntax. During + instantiation, the DNS provider fills its internal tables + with the given DNS server and controlled domain pairs. The + domain part of all URLs must be identical. The newly + created DNS context is associated with this domain name. +

+
+

+ Back to Top +

+

+ DNS Resolver +

+

+ The DRL DNS provider includes an independent fully-functional DNS + resolver with its own SLIST table and local cache. The SLIST table and + the cache are singleton classes shared among all instances of the + resolver. The resolver conforms with RFC 1034 on general principles + and algorithms used by the resolver, and with RFC 1035 on respective + records and message formats. The standards RFC 1123, 2181, and 2782 + are also relevant [2]. +

+

+ Back to Top +

+

+ Federation +

+

+ The DLR DNS provider has built-in federation support. Implicit next + naming system is determined dynamically. If the DNS context encounters + the border of the DNS namespace, it calls the + DirectoryManager.getContinuationContext( + ) method and forwards the call to the obtained next naming + system context. +

+

+ Unsupported methods, such as bind() and + rename(), also perform the initial check. The user gets + javax.naming.OperationNotSupportedException for these + methods only if the requested name is entirely inside the DNS + namespace. +

+

+ Back to Top +

+

+ Appendix: Usage Examples +

+

+ Below is an example of using the provider as the initial context. In + the example, the DNSContextFactory class is specified as + the default factory for producing initial contexts. +

+
+Hashtable env = new Hashtable();

+DirectoryContext ctx;

+Attributes attrs;

+

+env.put(Context.INITIAL_CONTEXT_FACTORY,

+        "org.apache.harmony.jndi.provider.dns.DNSContextFactory");

+env.put(Context.PROVIDER_URL,

+        "dns://dns01.example.com/subdomain.example.com");

+ctx = new InitialDirContext(env);

+

+// Obtain A and CNAME records for server1.subdomain.example.com

+attrs = ctx.getAttributes("server1", new String[] {"A", "CNAME"});

+
+

+ The provider can also be accessed by passing a DNS URL to any initial + context method that accepts string arguments. For that, set the + following property before calling a method of the initial context: +

+
+env.put(Context.URL_PKG_PREFIXES, "org.apache.harmony.jndi.provider.dns");

+ctx = new InitialDirContext(env);

+

+// Add server with IP address 192.168.1.111 to SLIST as a server

+// responsible for serving requests about host11.subdomain.example.com

+// Retrieve A and HINFO records for host11.subdomin.example.com

+attrs = ctx.getAttributes("dns://192.168.1.111/host11.subdomain.example.com",

+                          new String[] {"A", "HINFO"});

+
+

+ The class dnsURLContext actually serves requests of this + type. +

+

+ Back to Top +

+

+ References +

+

+ [1] Java* Naming And + Directory Interface, http://java.sun.com/j2se/1.5.0/docs/guide/jndi/index.html +

+

+ [2] Internet Engineering Task Force, + Requests for Comments, http://www.ietf.org/ +

+

+   +

+

+ Back to Top +

+

+ (C) Copyright 2005-2006 Intel Corporation +

+

+ * Other brands and names are the property of + their respective owners. +

+ + + diff --git a/xdocs/subcomponents/classlibrary/Java2D.html b/xdocs/subcomponents/classlibrary/Java2D.html new file mode 100755 index 0000000..4eaf4b8 --- /dev/null +++ b/xdocs/subcomponents/classlibrary/Java2D.html @@ -0,0 +1,501 @@ + + + + + + DRL Java 2D* + + + + +

+ DRL Java 2D* +

+

+ Revision History +

+

+ Disclaimer and Legal Information +

+

+ About This Document +

+

+ Purpose +

+

+ Intended Audience +

+

+ Documentation Conventions +

+

+ Introduction to Java 2D* +

+

+ Java 2D* in DRL +

+

+ About +

+

+ Architecture Overview +

+

+ Class Relationship +

+

+ CommonGraphics2D Class + Internals +

+

+ Platform + Specifics in DRL Java 2D* Graphics +

+

+ Java 2D* Portability +

+

+ References +

+

+ Revision History +

+ + + + + + + + + + + + + + + + +
+ Version + + Version Information + + Date +
+ Initial version + + Alexey Petrenko, Svetlana Konovalova: document created. + + May 18, 2006 +
+ Formatting update + + Nadya Morozova + +   September 21, 2006 +
+

+ Disclaimer and Legal Information +

+

+ Copyright 2005-2006 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. +

+

+ Portions, Copyright (C) 1991-2005 Unicode, Inc. The following applies + to Unicode +

+

+ COPYRIGHT AND PERMISSION NOTICE. +

+

+ Copyright (C) 1991-2005 Unicode, Inc. All rights reserved. Distributed + under the Terms of Use in http://www.unicode.org/copyright.html. + Permission is hereby granted, free of charge, to any person obtaining + a copy of the Unicode data files and any associated documentation (the + "Data Files") or Unicode software and any associated documentation + (the "Software") to deal in the Data Files or Software without + restriction, including without limitation the rights to use, copy, + modify, merge, publish, distribute, and/or sell copies of the Data + Files or Software, and to permit persons to whom the Data Files or + Software are furnished to do so, provided that (a) the above copyright + notice(s) and this permission notice appear with all copies of the + Data Files or Software, (b) both the above copyright notice(s) and + this permission notice appear in associated documentation, and (c) + there is clear notice in each modified Data File or in the Software as + well as in the documentation associated with the Data File(s) or + Software that the data or software has been modified. +

+

+ THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF + ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT + HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR + ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT + OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA FILES OR + SOFTWARE. +

+

+ Except as contained in this notice, the name of a copyright holder + shall not be used in advertising or otherwise to promote the sale, use + or other dealings in these Data Files or Software without prior + written authorization of the copyright holder. +

+

+ Additional Terms From the Database: +

+

+ Copyright (C) 1995-1999 Unicode, Inc. All Rights reserved. +

+

+ Disclaimer: +

+

+ The Unicode Character Database is provided as is by Unicode, Inc. No + claims are made as to fitness for any particular purpose. No + warranties of any kind are expressed or implied. The recipient agrees + to determine applicability of information provided. If this file has + been purchased on magnetic or optical media from Unicode, Inc., the + sole remedy for any claim will be exchange of defective media within + 90 days of receipt. This disclaimer is applicable for all other data + files accompanying the Unicode Character Database, some of which have + been compiled by the Unicode Consortium, and some of which have been + supplied by other sources. +

+

+ Limitations on Rights to Redistribute This Data: +

+

+ Recipient is granted the right to make copies in any form for internal + distribution and to freely use the information supplied in the + creation of products supporting the UnicodeTM Standard. The files in + the Unicode Character Database can be redistributed to third parties + or other organizations (whether for profit or not) as long as this + notice and the disclaimer notice are retained. Information can be + extracted from these files and used in documentation or programs, as + long as there is an accompanying notice indicating the source. +

+

+ About This + Document +

+

+ Purpose +

+

+ This document introduces the Java 2D* [1] implementation, supplied as part of the + DRL (Dynamic Runtime Layer) initiative, and gives details on its + design. +

+

+ Intended + Audience +

+

+ The target audience for the document includes a wide community of + engineers interested in using Java 2D* and in further + work with the product to contribute to its development. The document + assumes that readers are familiar with the Java 2D* + technology and the Java* programming language. +

+

+ Documentation Conventions +

+

+ This document uses the unified conventions for the DRL documentation kit. +

+

+ Back to Top +

+

+ Introduction to Java 2D* +

+

+ The Java 2D* implementation is the collection of + classes for a high-performance two-dimensional (2D) graphics and image + processing. The package includes line and shape drawing, text and + image rendering. +

+

+ Back to Top +

+

+ Java 2D* in DRL +

+

+ About +

+

+ DRL Java 2D* is a fast and easily portable + implementation of the Java 2D* technology, consisting + of a number of classes for advanced graphics and image processing. +

+

+ Back to Top +

+

+ Architecture Overview +

+

+ DRL Java 2D* supports the Windows* + and Linux* operating systems for the IA-32 + architecture. The Windows* version mostly uses the + GDI+ (Graphics Device Interface plus) library, but can also use the + GDI library for better performance. For example, Java 2D* can use GDI instead of GDI+ to speed up image + processing. The Linux* version uses Xlib and xft + libraries. +

+

+ DRL Java 2D* has portability in its design, so that + you can easily port it to other operating systems and hardware + architectures. For details and how to port Java 2D* + on other platforms see Java 2D* + Portability. +

+

+ Back to Top +

+

+ Class + Relationship +

+

+ Figure 1 below shows the Java 2D* structure, + demonstrating the inheritance relationship of the + Graphics2D classes: +

+

+ Class Hierarchy diagram +

+

+ Figure 1: Inheritance Relationship of the Graphics2D + Classes +

+ +

+ For more information on the classes see Platform Specifics + in DRL Java 2D* Graphics. +

+

+ Back to Top +

+

+ CommonGraphics2D + Class Internals +

+

+ The section specifies the CommonGraphics2D class internal + areas and gives description on their tools. +

+

+ Line and Shape Rasterizers +

+

+ The CommonGraphics2D class splits all shapes into a set + of rectangles to unify the drawing process for different operating + systems and architectures. For this purpose Java 2D* + uses the JavaShapeRasterizer and the + JavaLineRasterizer classes from the + org.apache.harmony.awt.gl.render package. The + JavaShapeRasterizer class splits an object implementing a + Shape interface into a set of rectangles and produces a MultiRectArea + object. The JavaLineRasterizer class makes line drawing + more accurate and processes lines with strokes, which are instances of + the BasicStroke class. +

+

+ To port the shape drawing to another platform you just need to + override rectangle-drawing methods. However, if your operating system + has functions to draw particular shapes, you can optimize your + subclass of the CommonGraphics2D class by using this + functionality in overridden methods. +

+

+ Blitters +

+

+ Blitter classes draw images on the display or buffered images. All + blitters inherit the + org.apache.harmony.awt.gl.render.Blitter interface. +

+

+ Blitters are divided into: +

+ +

+ DRL Java 2D* also uses blitters to fill the shapes + and the user-defined subclasses of the java.awt.Paint + class with paints, which the system does not support. +

+

+ Text Renderers +

+

+ Text renderers draw strings and glyph vectors. All text renderers are + subclasses of the org.apache.harmony.awt.gl.TextRenderer + class. +

+

+ Java 2D* does not have its own font rendering engine + and uses native libraries instead: the GDI library on the Windows* OS and the Xft, FontConfig and FreeType libraries on + the Linux* OS. The + java.awt.font.NumericShaper class uses data from the + Unicode Character Database [2] for retrieving character + properties. +

+

+ Back to Top +

+

+ Platform + Specifics in DRL Java 2D* Graphics +

+

+ The Windows* implementation - the + WinGDIPGraphics2D class - for the most part is based on + the GDI+ library, which has the routines for drawing all types of + shapes filling them with a solid color brush and a linear gradient + brush, but it does not support an acyclic gradient brush. The Java + 2D* package doesn't use the native library texture + paint option, resorting to Blitters instead. + However, the major part of the shape drawing and filling routines is + native in this class. +

+

+ As for the Linux* implementation - the + XGraphics2D class - the Xlib library has no methods to + draw and fill free-form shapes. So, the corresponding + XGraphics2D methods use Rasterizers, inherited from the + CommonGraphics2D class. +

+

+ Back to Top +

+

+ Java 2D* Portability +

+

+ The actions to port the DRL Java 2D* package to + another architecture or operating system, or to use it with another + library depend on the particular platform. The main steps are the + following: +

+ +

+ Back to Top +

+

+ References +

+

+ [1] Java 2D* Technology + http://java.sun.com/j2se/1.5.0/docs/guide/2d/index.html +

+

+ [2] Unicode Character Database http://www.unicode.org/ucd/ +

+

+ Back to Top +

+

+ (C) Copyright 2005-2006 Intel Corporation +

+

+ * Other brands and names are the property of + their respective owners. +

+ + + diff --git a/xdocs/subcomponents/classlibrary/Regexp.htm b/xdocs/subcomponents/classlibrary/Regexp.htm new file mode 100755 index 0000000..f1626ee --- /dev/null +++ b/xdocs/subcomponents/classlibrary/Regexp.htm @@ -0,0 +1,577 @@ + + + + + + + Design of the regex processing framework + + + +

+ Regex Processing Framework +

+

+ Revision History +

+

+ Disclaimer +

+

+ About this Document +

+

+ Purpose +

+

+ Intended Audience +

+

+ Documentation Conventions +

+

+ Introduction to Pattern Matching +

+

+ AbstractSet Interface +

+

+ Characteristics +

+

+ Methods Used +

+

+ Class Hierarchy +

+

+ Optimizations +

+

+ Usage Examples +

+

+ References +

+

+ Revision History +

+ + + + + + + + + + + + + + + + +
+ Version + + Version Information + + Date +
+ Initial version + + Nadya Morozova, Nikolay Kuznetsov: document created. + + December 16, 2005 +
+ Formatting update + + Nadya Morozova + +   September 21, 2006 +
+

+ Disclaimer and Legal + Information +

+

+ 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. +

+

+ About This + Document +

+

+ Purpose +

+

+ This document describes the java.util.regex package + delivered as part of the Harmony classlibrary project. This document + provides an overview of the overall architecture with focus on the + aspects improving performance. +

+

+ Intended + Audience +

+

+ The target audience for the document includes a wide community of + engineers interested in using regular expression package and in + further work with the product to contribute to its development. The + document assumes that readers are familiar with Regular expressions + [1, 2, 3], finite automata theory [4], + basic compiler techniques [4] and the Java* programming language [5]. +

+

+ Documentation Conventions +

+

+ This document uses the unified + conventions for the Harmony documentation kit. +

+

+ Back to Top +

+

+ Introduction to Pattern + Matching +

+

+ To analyze text in search of sequences matching preset patterns, you + can choose from a variety of techniques, such as the wide-spread + regular expressions (RE) [1], exact + string matching, for example, the Boyer-Moore algorithm (BM) [6], and others. However, the RE engine is rather + complex, and significantly impacts performance, whereas the exact + string matching techniques have a limited application. +

+

+ For example, the regular expression .*world is used to + find the last instance of world in a sentence. The BM string + searching algorithm is more appropriate for solving the task than the + RE technique, and is more effective from the performance perspective. + To optimize using pattern matching techniques with different tasks, + Harmony provides a unified interface that applies to any part of a + regular expression, including the whole expression. +

+

+ In terms of the Finite Automata theory, which is the basis of regular + expression processing, a part of regular expression is a node. + The Harmony regex framework treats every distinctive part of a regular + expression and the whole expression as a node. Each node implements + the unified interface adjusted for a specific technique. For instance, + for the regular expression in the example, the Harmony framework + includes a special class SequenceSet, which has a unified interface + called AbstractSet, and implements the Boyer-Moore + algorithm in searching for a word. +

+

+ Back to Top +

+

+ AbstractSet + Interface +

+

+ The key feature of the Harmony regex framework the single super + interface, AbstractSet, shared by all types of nodes. + Individual nodes are independent, so that every node of the automaton + incorporates its own find-match algorithm optimized for a specific + type of nodes. You can use methods implemented in the + AbstractSet interface subclasses or override these + methods to use your own more efficient algorithm. +

+

+ Characteristics +

+

+ The AbstractSet interface has the following key + characteristics: +

+ +

+ Back to Top +

+

+ Methods Used +

+

+ The AbstractSet interface defines the matching and + finding methods, and the service methods supporting them, as follows. +

+

+ Service Methods +

+
+
+ accept() +
+
+ Checks whether the current node matches the current string + symbol(s) to ensure that the automaton can proceed with the current + state. The method returns the number of accepted symbols. This + method is designed for nodes representing tokens, which mostly use + the default match procedure. To optimize the match procedure for a + specific type of token, you only need to override the + accept() method, see Example + 1. +
+
+ first() +
+
+ Checks whether the first symbol of the current node intersects with + previous one. If not, then the previous node is quantified + possessively without backtrack (the option of restarting the + search from the previous position). +
+
+ next() +
+
+ Returns the next node of the automaton. +
+
+

+ Matching and Finding Methods +

+
+
+ matches() +
+
+ Runs the match procedure starting from the current state. This is + the only method you need to override in order to introduce new + functionality. By default, the matches() method does + the following when working with terms (see Class Hierarchy): +
    +
  1. + Calls the accept() method and proceeds if the + method returns a positive value. +
    2. +
  2. + Calls the match of the next node with the shift obtained from + the accept() method. +
    3. +
  3. + Returns TRUE in case of a successful match. +
    4. +
+
+
+ find() +
+
+ Checks whether the pattern can match any part of the string in the + following way: +
    +
  1. + Finds the next position in the input string, for which the + accept() method returns a positive value. If no + matches are found, the method terminates and returns a + negative value. +
    2. +
  2. + From this position, runs the matches() method. +
    3. +
+
+
+ findBack() +
+
+ Does the same as the find() method but starts from the + end of the string or from the nearest new-line symbol. This method + optimizes the find procedure when the current node of the pattern + fits the rest of the string. In such cases, it is necessary to find + the last occurrence of the pattern represented by the next node, as + in the case of the .*world pattern. +
+
+

+ Back to Top +

+

+ Class Hierarchy +

+

+ Figure 1 shows the class hierarchy based on the + AbstractSet interface. As mentioned in its description, the whole hierarchy is based + on this interface. The other classes of the framework are divided into + the following categories: +

+ +

+ Hierarchy of classes in regexp framework +

+

+ Figure 1. Class Hierarchy +

+

+ Figure 1 displays only the basics of the regex framework. This + framework also includes other nodes responsible for different + optimizations. For more details, see the comments inlined in code. +

+

+ Back to Top +

+

+ Optimizations +

+

+ In the current implementation, most optimizations are based on the + node representation to improve efficiency of the framework. It is + noteworthy that an optimal finite automaton is built during compile + time, so that the constructed automaton does not spend additional time + on decision-making overhead during match time. The regex framework + optimizations improve different aspects, such as: +

+ +

+ Back to Top +

+

+ Usage Examples +

+

+ This part on the document illustrates usage of the Harmony regex + framework. +

+

+ Example 1 +

+

+ This example illustrates using the CharSet class, which + includes all nodes accepting characters to create a new type of + tokens. For that, the class uses the LeafSet class, which + is the basic class for tokens. This example shows that the only method + you need to override in order to present a new type of tokens is the + accept() method. +

+
+class CharSet extends LeafSet {
+    ...
+    public int accept(int strIndex, CharSequence testString) {
+        // checks that the current symbol of the input string is the one this 
+        // instance represents and returns 1 (the number of
+        // accepted symbols) or -1 if accept fails:
+        return (this.ch == testString.charAt(strIndex)) ? 1 : -1;
+    }
+    ...
+}
+
+

+ Example 2 +

+

+ The following example demonstrates independent implementation of the + find() method for SequenceSet. +

+

+ Note +

+

+ This changes the find procedure for nodes representing character + sequences and at the same time does not affect the find-match + algorithms of other types of nodes. +

+
+class SequenceSet extends LeafSet {
+    ...
+    protected int indexOf(CharSequence str, int from) {
+        // Boyer-Moore algorithm 
+        ...
+    }
+    
+    public int find(int strIndex, CharSequence testString,
+            MatchResultImpl matchResult) {
+        ...
+        while (strIndex <= strLength) {
+            // call the fast search method instead of default implementation
+            strIndex = indexOf(testStr, strIndex);
+            if (strIndex < 0) {
+                return -1;
+            }
+            if (next.matches(strIndex + charCount, testString, matchResult) >= 0) {
+                return strIndex;
+            }
+            strIndex++;
+        }
+        return -1;
+    }
+    ...
+}
+
+

+ Example 3 +

+

+ This example illustrates how to turn the match procedure of the + .* patterns into the find procedure, which is potentially + faster. +

+
+class DotQuantifierSet extends LeafQuantifierSet {
+    ...     
+    public int matches(int stringIndex, CharSequence testString,
+            MatchResultImpl matchResult) {
+        ...
+        // find line terminator, since .* represented by this node accepts all characters
+        // except line terminators 
+        int startSearch = findLineTerminator(stringIndex, strLength, testString);
+        ...
+        // run findBack method of the next node, because the previous 
+        // part of the string is accepted by .* and no matter where
+        // the next part of pattern is found, the procedure works OK.  
+        return next.findBack(stringIndex, startSearch, testString, matchResult);
+    }
+}
+
+

+ Back to Top +

+

+ References +

+

+ [1] Jeffrey E. F. Friedl., + Mastering regular expressions, 2nd Edition., July 2002, + O'Reilly, ISBN 0-596-00289-0 +

+

+ [2] McNaughton, R. and Yamada, H. + Regular Expressions and State Graphs for Automata, IRA Trans. + on Electronic Computers, Vol. EC-9, No. 1, Mar. 1960, pp 39-47. +

+

+ [3] Thompson, K., Regular + Expression search Algorithm, Communication ACM 11:6 (1968), pp. + 419-422. +

+

+ [4] Alfred V. Aho, Ravi Sethi, Jeffrey + D. Ullman, Compilers, Principles Techniques and Tools, + Addison-Wesley Publishing Company, Inc., 1985, ISBN 0-201-10088-6 +

+

+ [5] Java Technology site, http://java.sun.com +

+

+ [6] R. Boyer and S. Moore. A fast string + searching algorithm. C. ACM, 20:762-772, 1977. +

+

+ [7] D.E. Knuth, .I. Morris, and V. + Pratt. Fast pattern matching in strings. SIAM J on Computing, + 6:323-350, 1977. +

+

+ Back to Top +

+

+   +

+

+ * Other brands and names are the property of + their respective owners. +

+ + + diff --git a/xdocs/subcomponents/classlibrary/asn1_framework.xml b/xdocs/subcomponents/classlibrary/asn1_framework.xml new file mode 100755 index 0000000..197c245 --- /dev/null +++ b/xdocs/subcomponents/classlibrary/asn1_framework.xml @@ -0,0 +1,30 @@ + + + + + + + + Apache Harmony + Harmony Documentation Team + + + + + + diff --git a/xdocs/subcomponents/classlibrary/awt.xml b/xdocs/subcomponents/classlibrary/awt.xml new file mode 100755 index 0000000..12e16c8 --- /dev/null +++ b/xdocs/subcomponents/classlibrary/awt.xml @@ -0,0 +1,30 @@ + + + + + + + + Apache Harmony + Harmony Documentation Team + + + + + + diff --git a/xdocs/subcomponents/classlibrary/dns_support.xml b/xdocs/subcomponents/classlibrary/dns_support.xml new file mode 100755 index 0000000..2acb615 --- /dev/null +++ b/xdocs/subcomponents/classlibrary/dns_support.xml @@ -0,0 +1,30 @@ + + + + + + + + Apache Harmony + Harmony Documentation Team + + + + + + diff --git a/xdocs/subcomponents/classlibrary/java2d.xml b/xdocs/subcomponents/classlibrary/java2d.xml new file mode 100755 index 0000000..0669796 --- /dev/null +++ b/xdocs/subcomponents/classlibrary/java2d.xml @@ -0,0 +1,30 @@ + + + + + + + + Apache Harmony + Harmony Documentation Team + + + + + + diff --git a/xdocs/subcomponents/classlibrary/regexp.xml b/xdocs/subcomponents/classlibrary/regexp.xml new file mode 100755 index 0000000..8223bf9 --- /dev/null +++ b/xdocs/subcomponents/classlibrary/regexp.xml @@ -0,0 +1,30 @@ + + + + + + + + Apache Harmony + Harmony Documentation Team + + + + + + -- 1.4.1