Index: xdocs/downloads.xml =================================================================== --- xdocs/downloads.xml (revision 517120) +++ xdocs/downloads.xml (working copy) @@ -57,17 +57,17 @@

Note

- These are snapshot builds - untested builds provided for your convenience. They + These are snapshot builds - untested builds provided for your convenience. They have not been tested, and are not official releases of the Apache Harmony project or the Apache Software Foundation.

- Java Development Kit (JDK) +

Java Development Kit (JDK)

- The JDK lets you build and run your Java programs. It include javac and other standard JDK tools. - Note that it's safest to set JAVA_HOME to the root directory - of the distribution, and put the bin/ directory on your PATH. + The JDK lets you build and run your Java programs. It include javac and other standard JDK tools. + Note that it's safest to set JAVA_HOME to the root directory + of the distribution, and put the bin/ directory on your PATH.

- Java Runtime Environment (JRE) +

Java Runtime Environment (JRE)

- The JRE lets you run your Java programs. Note that it's safest to set JAVA_HOME to the root directory - of the distribution, and put the bin/ directory on your PATH. + The JRE lets you run your Java programs. Note that it's safest to set JAVA_HOME to the root directory + of the distribution, and put the bin/ directory on your PATH.

- Harmony Development Kit (HDK) +

Harmony Development Kit (HDK)

- The HDK is targetted at Harmony developers. It includes the pre-built class library and VM binaries, + The HDK is targetted at Harmony developers. It includes the pre-built class library and VM binaries, necessary include files, test cases, and dependencies. It is not a replacement for the common JDK.

@@ -140,7 +140,7 @@

These are not official releases of the Apache Software Foundation, nor are they - complete or compatible with the Java specification. They are snapshots provided + complete or compatible with the Java specification. They are snapshots provided to make testing and experimentation easier.

Index: xdocs/faq.xml =================================================================== --- xdocs/faq.xml (revision 517120) +++ xdocs/faq.xml (working copy) @@ -1,12 +1,11 @@ - + - - Frequently Asked Questions - Harmony Documentation Team - + + Frequently Asked Questions + Harmony Documentation Team + - -
+ +
-
    -
  1. - How do I subscribe to the mail list? -
    - You can subscribe by sending an email to dev-subscribe@harmony.apache.org - you will receive a confirmation request that you must respond to. - After that, you can post to the dev list dev@harmony.apache.org. - Please see our mailing list page for - more information. -
  2. -
-
- -
- -
    -
  1. - When building the classlibrary, ant crashes with a compiler error, a - heap error, or a reflection error. -
    - These problems are all symptomatic of running out of java heap for ant. The - solution is to set the ANT_OPTS environment variable to something bigger than - the default. At the time of this writing, best practice is to set -
    - set ANT_OPTS="-Xmx256M" -
    -
  2. -
-
- - -
-
    -
  1. - Why are you doing this? -
    - We believe that there is broad community interest in coming together to create and use an open source, - compatible implementation of J2SE 5, the latest version of the Java 2 Standard Edition specification. -
  2. -
  3. - What version of Java will you be implementing? -
    - We are starting with Java SE 5, as that is the first version of Java SE for which the - licensing allows an open source implementation, but we'll continue with Java SE 6 and - any subsequent versions that follow. -
  4. -
  5. - Why haven't you done this before? -
    - While the Java Community Process has allowed open source implementations of JSRs for a few years now, - Java 5 is the first of the J2SE specs that we are able to do due to licensing reasons. -
  6. -
  7. - Are you doing this to attack Sun? -
    - No, of course we aren't. Apache doesn't support projects that attack any entity, corporate or otherwise. -
    - Sun has been a long-time supporter of Apache and Apache projects, and Apache has a wide variety of projects - that are implementations of Java specifications, such as Apache Geronimo, Apache Tomcat, Pluto, taglibs, etc. -
    - This project is open to every interested member of the Java community, and every interested member is welcome - to participate in whatever manner they choose. -
  8. -
  9. - Are you doing this because Sun refuses to release their source for J2SE under an open source license? -
    - Not really. We would welcome Sun doing that (as well as anyone else w/ a J2SE implementation!) as it would save us a - lot of time, and we wholeheartedly encourage them to do so ;) but Sun has the right to do what it chooses with it's intellectual property. - Since we started the project, Sun has announced that they will be open sourcing their implementation, and they've - started the process. Of course, we'll continue to develop Apache Harmony - multiple independent implelentations - of Java SE is good for the Java ecosystem. -
  10. -
  11. - Will your implementation be compatible with the specification? -
    - Yes -
  12. -
  13. - How will you know? -
    - We are going to test it with the TCK from Sun. -
  14. -
  15. - How will you license the TCK from Sun. Isn't it expensive? -
    - Sun offers scholarships to qualified non-profits, academics and individuals. - Apache is a qualified non-profit, and has benefitted from this scholarship before, - with the J2EE 1.4 TCK license and support for the Apache Geronimo project, among others. -
    - We will apply for the scholarship, and hope that Sun will grant us the license and support needed for us to do a good job. -
  16. -
  17. - How long will it take? -
    - It will be done when it's done :) This will take a long time, but we hope that contributions from around the community will help us along the way. -
  18. -
  19. - Do you have any code to start? -
    - No, we don't. We didn't want to "bless" any given implementation that might be donated - (if such a thing could happen) but would rather let the community decide how it will create and develop the platform. -
  20. -
  21. - Will you accept SWT if IBM offers it? -
    - Apache is always grateful for contributions from wherever they come, and IBM has a record of contributions - to open source, but it would up to the project community to decide whether any particular contribution was used in the project. -
  22. -
  23. - Why are you going to have an architecture thread? -
    - We wanted a way that we could bring together people from all over the Java community, - even other open-source projects that are related. We welcome everyone to the discussion, - no matter what license they choose to implement under, be it a free software license, - an open source license or a proprietary license. We are here to open discussion and learning, - and to design a great architecture for J2SE platforms. -
    - At Apache, we think that a strong, diverse, meritocratic community is what makes a good open source project, - and we want to be sure that everyone can participate in some way. -
  24. -
  25. - Does this compete with Kaffe and Classpath? -
    - People from Kaffe and Classpath are helping start this project! - Their experience in the open source VM and class library is invaluable, - and they bring problems that the larger architecture community discussion can help solve. -
    - We will have an implementation under the Apache License, but we think of this as complementary rather than competitive. - And when we solve a few small license interoperability issues, we expect we'll be able to complement each other even more. -
  26. -
  27. - How will you ensure that the intellectual property of Sun and others is respected? -
    - Good question - this is a very important issue for us. There are several ways, but this will be a topic - for the community to work on at the beginning. So far we've thought of : -
      -
    1. We shall ask any person that would be a committer to declare what kind of non-open-source class library - or VM source code they have been exposed to, and allow us to keep them from participating in the related parts - of the codebase where they may inadvertently violate the IP rights of someone else. -
    2. -
    3. We shall require that any code contribution that isn't a new, original work of authorship created expressly - for the Apache Harmony project be subject to the standard Apache process for provenance and licensing to ensure - that we have an accurate record of every contribution that wasn't created expressly inside the Apache Harmony project. -
    4. -
    5. We would like to perform continuous "surveillance" on the codebase we are building, and compare to class library - and VMs from elsewhere, like Sun, IBM, BEA, Kaffe, etc to ensure that no code from those efforts become part of Apache Harmony - without our knowledge. We do this to protect ourselves, our users, and of course those other efforts. - We don't know yet how to do this, but are exploring ideas such as having a third party such as Black Duck or - an existing licensee (or Sun!) do this for us. This, like all the topics herein, are open for discussion an change by the community. -
    6. -
    7. Anything anyone can think of! -
    8. -
    -
  28. -
  29. - Won't this lead to fragmentation in the Java community? -
    - We don't think so. Our intent is to bring people together, let us share what we know, - solve common problems, and collaborate on things where we can. A diverse Java community is a healthy Java community. - Multiple implementations of the Java specifications show the value of Java - that we do have a specification, - that anyone is free to make a compatible implementation, and that users of Java have the opportunity to run - their Java code in more places, on more platforms. This is the central promise of Java, and we think that our efforts support this. -
  30. -
  31. - How can I get involved and help influence and shape this proposal? Or is it too late? -
    - Join the community and participate! It's never too late! We're just getting started, and everything is open - to discussion - the community will change what the community wants to change. What we do in this project is decided - by those participating in the project. This is the Apache Software Foundation - collaborative, meritocratic, and community-based. -
  32. -
+
    +
  1. +

    + How do I subscribe to the mail list? +

    +

    + You can subscribe by sending an email to + dev-subscribe@harmony.apache.org. + You will receive a confirmation request that you must respond to. + After that, you can post to the dev list + dev@harmony.apache.org. + Please see our mailing list page for + more information. +

    +
  2. +
+
-
+
- +
    +
  1. +

    + + When building the classlibrary, ant crashes with a compiler error, a + heap error, or a reflection error. + +

    +

    + These problems are all symptomatic of running out of java heap for ant. The + solution is to set the ANT_OPTS environment variable to something bigger than + the default. At the time of this writing, best practice is to set: +

    +
    set ANT_OPTS="-Xmx256M"
    +
  2. +
+
+
+
    +
  1. +

    + Why are you doing this? +

    +

    + We believe that there is broad community interest in coming together to create + and use an open source, compatible implementation of J2SE 5, the latest version + of the Java 2 Standard Edition specification. +

    +
  2. +
  3. +

    + What version of Java will you be implementing? +

    +

    + We are starting with Java SE 5, as that is the first version of Java SE for which the + licensing allows an open source implementation, but we'll continue with Java SE 6 and + any subsequent versions that follow. +

    +
  4. +
  5. +

    + Why haven't you done this before? +

    +

    + While the Java Community Process has allowed open source implementations of JSRs + for a few years now, Java 5 is the first of the J2SE specs that we are able to do + due to licensing reasons. +

    +
  6. +
  7. +

    + Are you doing this to attack Sun? +

    +

    + No, of course we aren't. Apache doesn't support projects that attack any entity, + corporate or otherwise. Sun has been a long-time supporter of Apache and Apache projects, + and Apache has a wide variety of projects that are implementations of Java specifications, + such as Apache Geronimo, Apache Tomcat, Pluto, taglibs, etc. +

    +

    + This project is open to every interested member of the Java community, and every + interested member is welcome to participate in whatever manner they choose. +

    +
  8. +
  9. +

    + + Are you doing this because Sun refuses to release their source for J2SE + under an open source license? + +

    +

    + Not really. We would welcome Sun doing that (as well as anyone else w/ a J2SE implementation!) + as it would save us a lot of time, and we wholeheartedly encourage them to do so ;) but Sun + has the right to do what it chooses with it's intellectual property. + Since we started the project, Sun has announced that they will be open sourcing their implementation, and they've + started the process. Of course, we'll continue to develop Apache Harmony - multiple independent implelentations + of Java SE is good for the Java ecosystem. +

    +
  10. +
  11. +

    + Will your implementation be compatible with the specification? +

    +

    + Yes +

    +
  12. +
  13. +

    + How will you know? +

    +

    + We are going to test it with the TCK from Sun. +

    +
  14. +
  15. +

    + How will you license the TCK from Sun. Isn't it expensive? +

    +

    + Sun offers scholarships to qualified non-profits, academics and individuals. + Apache is a qualified non-profit, and has benefitted from this scholarship before, + with the J2EE 1.4 TCK license and support for the Apache Geronimo project, among others. +

    +

    + We will apply for the scholarship, and hope that Sun will grant us the license + and support needed for us to do a good job. +

    +
  16. +
  17. +

    + How long will it take? +

    +

    + It will be done when it's done :) This will take a long time, but we hope that + contributions from around the community will help us along the way. +

    +
  18. +
  19. +

    + Do you have any code to start? +

    +

    + No, we don't. We didn't want to "bless" any given implementation that might be donated + (if such a thing could happen) but would rather let the community decide how it will + create and develop the platform. +

    +
  20. +
  21. +

    + Will you accept SWT if IBM offers it? +

    +

    + Apache is always grateful for contributions from wherever they come, and IBM has a record + of contributions to open source, but it would up to the project community to + decide whether any particular contribution was used in the project. +

    +
  22. +
  23. +

    + Why are you going to have an architecture thread? +

    +

    + We wanted a way that we could bring together people from all over the Java community, + even other open-source projects that are related. We welcome everyone to the discussion, + no matter what license they choose to implement under, be it a free software license, + an open source license or a proprietary license. We are here to open discussion and learning, + and to design a great architecture for J2SE platforms. +

    +

    + At Apache, we think that a strong, diverse, meritocratic community is what makes a good + open source project, and we want to be sure that everyone can participate in some way. +

    +
  24. +
  25. +

    + Does this compete with Kaffe and Classpath? +

    +

    + People from Kaffe and Classpath are helping start this project! + Their experience in the open source VM and class library is invaluable, + and they bring problems that the larger architecture community discussion can help solve. +

    +

    + We will have an implementation under the Apache License, but we think of this as + complementary rather than competitive. And when we solve a few small license + interoperability issues, we expect we'll be able to complement each other even more. +

    +
  26. +
  27. +

    + How will you ensure that the intellectual property of Sun and others is respected? +

    +

    + Good question - this is a very important issue for us. There are several ways, but this + will be a topic for the community to work on at the beginning. So far we've thought of: +

    +
      +
    • + We shall ask any person that would be a committer to declare what kind of + non-open-source class library or VM source code they have been exposed to, + and allow us to keep them from participating in the related parts + of the codebase where they may inadvertently violate the IP rights of someone else. +
    • +
    • + We shall require that any code contribution that isn't a new, original work of + authorship created expressly for the Apache Harmony project be subject to the + standard Apache process for provenance and licensing to ensure that we have + an accurate record of every contribution that wasn't created expressly inside + the Apache Harmony project. +
    • +
    • + We would like to perform continuous "surveillance" on the codebase we are building, + and compare to class library and VMs from elsewhere, like Sun, IBM, BEA, Kaffe, + etc to ensure that no code from those efforts become part of Apache Harmony + without our knowledge. We do this to protect ourselves, our users, and of course + those other efforts. We don't know yet how to do this, but are exploring ideas + such as having a third party such as Black Duck or an existing licensee (or Sun!) + do this for us. This, like all the topics herein, are open for discussion an change + by the community. +
    • +
    • + Anything anyone can think of! +
    • +
    +
  28. +
  29. +

    + Won't this lead to fragmentation in the Java community? +

    +

    + We don't think so. Our intent is to bring people together, let us share what we know, + solve common problems, and collaborate on things where we can. A diverse Java community + is a healthy Java community. Multiple implementations of the Java specifications show + the value of Java - that we do have a specification, that anyone is free to make + a compatible implementation, and that users of Java have the opportunity to run their Java + code in more places, on more platforms. This is the central promise of Java, and we + think that our efforts support this. +

    +
  30. +
  31. +

    + + How can I get involved and help influence and shape this proposal? + Or is it too late? + +

    +

    + Join the community and participate! It's never too late! We're just getting started, + and everything is open to discussion - the community will change what the + community wants to change. What we do in this project is decided by those participating + in the project. This is the Apache Software Foundation - collaborative, meritocratic, + and community-based. +

    +
  32. +
+ +
+ +
- + Index: xdocs/hdk.xml =================================================================== --- xdocs/hdk.xml (revision 517120) +++ xdocs/hdk.xml (working copy) @@ -1,13 +1,11 @@ - - Older Harmony News Harmony Documentation Team + +
+
+
New JRE and HDK Snapshots Posted
+
+

+ Our latest snapshots have + lots of new fixes and features. The VM has a new GC, + almost complete JVMTI, and now can co-exist with + the IBM VME in + the Harmony JRE structure. Our classlibrary continues to grow with new + classes, notably CORBA, thanks to + Apache Yoko. + Also, the classlibrary includes many new fixes and updates. + Choose the JRE to test your favorite applications, and + give us feedback on how + we are doing, or use the HDK to enable faster development of the Harmony classlibrary. + (2006-09-28) +

+
- +
Can Apache Harmony Help Sun Open Java?
+
+

+ We're happy to help + (2006-08-16) +

+
-
-

- New JRE and HDK Snapshots Posted -

- Our latest snapshots have - lots of new fixes and features. The VM has a new GC, - almost complete JVMTI, and now can co-exist with - the IBM VME in - the Harmony JRE structure. Our classlibrary continues to grow with new - classes, notably CORBA, thanks to - Apache Yoko. Also, the classlibrary includes many new fixes and updates. - Choose the JRE to test your favorite applications, and - give us feedback on how - we are doing, or use the HDK to enable faster development of the Harmony classlibrary. - (2006-09-28) -
-

-

- Can Apache Harmony Help Sun Open Java? -

- We're happy to help - (2006-08-16) -
-

-

- New Snapshot Posted -

- Lots of fixes and additions in the latest snapshot. - (2006-08-16) -
-

-

- DRLVM Documentation Update -

- Check our new documentation on - DRLVM - including guides for building, using, debugging, - GC architecture and execution manager - architecture. - (2006-08-05) -
-

-

- New HDK and JRE Snapshots Available -

- New - snapshots - of the HDK and JRE are now available with lots of bugfixes. - (2006-08-04) -
-

-

- HDK and JRE Snapshots Available -

- Harmony now - offers a snapshot - of it's JRE and HDK builds. - The JRE snapshot is our in-progress Java Runtime Environment, - including both the virtual machine and classlibrary. Note that - this isn't stable, complete or compatible software. However, - you can use this to run your favorite Java applications and - help the project find and fix bugs, and help direct our efforts - to complete the most popular parts of the classlibrary first. The HDK - snapshot is a developers build, complete with classlibrary jars and - native libraries, header files, and build scripts. - (2006-07-22) -
-

-

- New class library snapshot build available -

- A new stable snapshot of the class libraries code is available - for download from the - Harmony downloads page. - These are made available for people to evaluate and experiment - with the code. This snapshot contains the recently integrated - Swing, AWT, and Java2D code. As always, please report bugs - (and successes!) to the - Harmony developers mailing list. - (2006-06-30) -
-

-

- AWT, Java2D and Swing Code Contribution -

- On May 30th, 2006 the Apache Harmony project received a - substantial - contribution of class library code into the project. The code for - AWT, Java2D, and Swing implementation has been contributed by Alexey - Petrenko on behalf of Intel corp. The full announcement can be found - on the - Harmony developers mailing list. Thanks to - Alexey and his colleagues in the Intel Middleware Products Division! - (2006-05-31) -
-

- -

- New class library snapshot build available -

- A new stable snapshot of the class libraries code is available - for download from the - Harmony downloads page. - There are source and binary downloads available for people to - evaluate and experiment with the code. As always, please report bugs - (and successes!) to the - Harmony developers mailing list. - (2006-05-12) -
-

- -

- DRL Virtual Machine Contribution -

- On May 3rd, 2006 the Apache Harmony project received a - substantial - contribution of virtual machine (VM) code into the project, containing - a JIT, core VM, GC, bytecode verifier, etc. This was contributed by - Andrey Chernyshev on behalf of Intel Corp. The full announcement can - be found on the - Harmony developers mailing list. - (2006-05-03) -
-

- -

- Java Security Code Contribution -

- On December 30th, 2005 the Apache Harmony project accepted additional - class library code into the project. The code had been contributed by - Mikhail Loenko on behalf of Intel corp. The new class library code - includes security, cryptography, javax.net and unit tests. Thanks to - Mikhail and his collegues in the Intel Managed Runtime Division! - (2006-01-16) -
-

- -

- VM Interface and Core Classes Contribution -

- IBM has offered the Apache Harmony project a set of core - Java classes and an implementation of a VM/class library - interface. Tim Ellison wrote : - -
I'm delighted to be able to make a code contribution to the - Harmony project on behalf of IBM. The code comprises a concrete implementation - of the interface between virtual machine and class library that we have - been discussing recently, together with a set of core Java classes. -
- This contribution is sufficient to run Ant and the Eclipse Java - compiler, to provide a basic self-hosting environment. IBM also - made a version of their J9 VM - - available for use by the project in evaluating this contribution. - Thanks Tim and IBM :) - (2005-11-08) -
-

- -

- "Bootstrap JVM" Contributed to Apache Harmony -

- Daniel Lydickto the Harmony project of a basic Java - Virtual Machine entitled the "Apache Harmony Bootstrap JVM." - Dan offered the VM with the following goals in mind : -
    -
  • Basic platform for learning about VMs
  • -
  • Boostrap and runtime framework for our eventual 'production' VM
  • -
  • Help spur architectural discussion about core - component designs
  • -
- Thanks Dan! - (2005-09-30) -
-

- -

- Source for JCVM Contributed to Apache Harmony -

- Archie Cobbs has offered for contribution to the Apache Harmony project - a copy of the JCVM - codebase. Come and help us build on this interesting - VM. Thanks Archie! - (2005-09-25) -
-

-

- Project accepted by Apache Incubator -

- The Apache Harmony project was accepted formally accepted for - inubation by the Apache Incubator PMC. - (2005-05-18) -
-

+
New Snapshot Posted
+
+

+ Lots of fixes and additions in the latest snapshot. (2006-08-16) +

+
-
+
DRLVM Documentation Update
+
+

+ Check our new documentation on DRLVM + including guides for building, using, debugging, GC architecture and execution manager + architecture. (2006-08-05) +

+
- +
New HDK and JRE Snapshots Available
+
+

+ New snapshots + of the HDK and JRE are now available with lots of bugfixes. (2006-08-04) +

+
+
HDK and JRE Snapshots Available
+
+

+ Harmony now offers a snapshot + of it's JRE and HDK builds. + The JRE snapshot is our in-progress Java Runtime Environment, + including both the virtual machine and classlibrary. Note that + this isn't stable, complete or compatible software. However, + you can use this to run your favorite Java applications and + help the project find and fix bugs, and help direct our efforts + to complete the most popular parts of the classlibrary first. The HDK + snapshot is a developers build, complete with classlibrary jars and + native libraries, header files, and build scripts. (2006-07-22) +

+
+ +
New class library snapshot build available
+
+

+ A new stable snapshot of the class libraries code is available + for download from the Harmony downloads page. + These are made available for people to evaluate and experiment + with the code. This snapshot contains the recently integrated + Swing, AWT, and Java2D code. As always, please report bugs + (and successes!) to the Harmony developers mailing list. + (2006-06-30) +

+
+ +
AWT, Java2D and Swing Code Contribution
+
+

+ On May 30th, 2006 the Apache Harmony project received a + + substantial contribution of class library code into the project. + The code for AWT, Java2D, and Swing implementation has been contributed by Alexey + Petrenko on behalf of Intel corp. The full announcement can be found + on the Harmony developers mailing list. Thanks to + Alexey and his colleagues in the Intel Middleware Products Division! + (2006-05-31) +

+
+ +
New class library snapshot build available
+
+

+ A new stable snapshot of the class libraries code is available + for download from the Harmony downloads page. + There are source and binary downloads available for people to + evaluate and experiment with the code. As always, please report bugs + (and successes!) to the Harmony developers mailing list. + (2006-05-12) +

+
+ +
DRL Virtual Machine Contribution
+
+

+ On May 3rd, 2006 the Apache Harmony project received a + + substantial contribution of virtual machine (VM) code into the project, + containing a JIT, core VM, GC, bytecode verifier, etc. This was contributed by + Andrey Chernyshev on behalf of Intel Corp. The full announcement can + be found on the Harmony developers mailing list. + (2006-05-03) +

+
+ +
Java Security Code Contribution
+
+

+ On December 30th, 2005 the Apache Harmony project accepted additional + class library code into the project. The code had been contributed by + Mikhail Loenko on behalf of Intel corp. The new class library code + includes security, cryptography, javax.net and unit tests. Thanks to + Mikhail and his collegues in the Intel Managed Runtime Division! + (2006-01-16) +

+
+ +
VM Interface and Core Classes Contribution
+
+

+ IBM has offered the Apache Harmony project a set of core + Java classes and an implementation of a VM/class library + interface. Tim Ellison wrote: +

+

+ + I'm delighted to be able to make a code contribution to the + Harmony project on behalf of IBM. The code comprises a concrete implementation + of the interface between virtual machine and class library that we have + been discussing recently, together with a set of core Java classes. + +

+

+ This contribution is sufficient to run Ant and the Eclipse Java + compiler, to provide a basic self-hosting environment. IBM also + made a version of their J9 VM + + available for use by the project in evaluating this contribution. + Thanks Tim and IBM :) (2005-11-08) +

+
+ +
"Bootstrap JVM" Contributed to Apache Harmony
+
+

+ Daniel Lydickto the Harmony project of a basic Java Virtual Machine entitled + the "Apache Harmony Bootstrap JVM." Dan offered the VM with the following goals in mind: +

    +
  • Basic platform for learning about VMs
  • +
  • Boostrap and runtime framework for our eventual 'production' VM
  • +
  • Help spur architectural discussion about core component designs
  • +
+ Thanks Dan! (2005-09-30) +

+
+ +
Source for JCVM Contributed to Apache Harmony
+
+

+ Archie Cobbs has offered for contribution to the Apache Harmony project + a copy of the JCVM codebase. Come and + help us build on this interesting VM. Thanks Archie! (2005-09-25) +

+
+ +
Project accepted by Apache Incubator
+
+

+ The Apache Harmony project was accepted formally accepted for + inubation by the Apache Incubator PMC. (2005-05-18) +

+
+
+
+
Index: xdocs/roadmap.xml =================================================================== --- xdocs/roadmap.xml (revision 517120) +++ xdocs/roadmap.xml (working copy) @@ -47,7 +47,6 @@ It's a major task being done by a community of volunteers. Thus, the following is an approximate roadmap for what the project hopes to achieve in the next year.

- - -

Another motivation of the Harmony project is to provide a @@ -415,9 +412,7 @@

- -

As we now have a fairly usable class library and virtual machine, we wish to make it easy for the broad Java user community to help us ensure that Index: xdocs/subcomponents/classlibrary/ASN1Framework.html =================================================================== --- xdocs/subcomponents/classlibrary/ASN1Framework.html (revision 517120) +++ xdocs/subcomponents/classlibrary/ASN1Framework.html (working copy) @@ -18,218 +18,193 @@ - - - - ASN.1 Framework - - - - -

- ASN.1 Framework -

-

- Revision History -

- -

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

- - + + + ASN.1 Framework + + + +

+ ASN.1 Framework +

+

+ Revision History +

+

+ 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 - Version Information + Version Information - Date + Date
- Initial version + Initial version - Nadya Morozova, Stepan Mishura: document created
+ Nadya Morozova, Stepan Mishura: document created
Special thanks to Sergey Dmitriev for assistance
- November 16, 2005 + November 16, 2005
- Formatting update + Formatting update - Nadya Morozova + Nadya Morozova - September 21, 2006 + September 21, 2006
- -

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

-
-
+        
+    
+    

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

+
    +
  • Directly: by providing the ASN.1 notation for used data and by specifying + its encoding rule
  • +
  • Indirectly: by refereeing to another (external) specification that uses the + ASN.1 notation
  • +
+

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

+
    +
  • String and primitive + types represent raw data.
  • +
  • Constructed types serve as containers for a number + of type components, which can be optional or can have default values.
  • +
  • Tagged types are used to derive one ASN.1 type from + another.
  • +
  • Other types are ANY and CHOICE. +
  • +
+

+ 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 {
@@ -240,102 +215,84 @@
 
 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: -

-
-
+    

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

+
    +
  • A clear API for decoding and encoding objects
  • +
  • Low resource consuming
  • +
  • Thread safety
  • +
+

+ The framework enables the following: +

+
    +
  • Create a Java* object instance from its encoded octet string
  • +
  • Verify that an octet string is a valid encoded string
  • +
  • Generate an encoded octet string for a particular object
  • +
+

+ 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;
@@ -347,753 +304,640 @@
     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 +

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

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

- A special use case for this ASN.1 type exists, when the type is - declared as Named BitString. For example: + 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. + 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, +
+
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 +
+
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. -

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

+
    +
  • BerInputStream and DerInputStream provide decoding and + verifying functionality for corresponding notation rules.
  • +
  • BerOutputStream and DerOutputStream provide the encoding + functionality.
  • +
+

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

+
    +
  • identifier octets (for example, tag)
  • +
  • length octets
  • +
  • content octets
  • +
  • end-of-content octets
  • +
+

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

+
    +
  • Collection: Step by step, the DER encoder extracts all data to be encoded, + processes the data, calculates an encoding length for each item, and stores all + calculations and processed data. Then, the encoder calculates the overall encoding + length and allocates required space.
  • +
  • Encoding: The DER encoder retrieves stored information, encodes it according + to the rules and writes the encoding to the allocated byte array.
  • +
+

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

+
    +
  • All basic classes are thread-safe classes.
    + This means that an instance of an ASN.1 class can be used by many threads simultaneously + for decoding or encoding a particular class of Java* objects. An + instance of an ASN.1 class does not keep any specific data for a selected object. + It only provides a way for a decoder stream to store decoded data in a Java* + object, and a way for an encoder stream to extract a data to be encoded from a Java* object.
  • +
  • All classes for string and primitive ASN.1 types provide access to a reusable class + instance via the static getInstance() method.
    + If a separate instance of an ASN.1 class is not required, this method is used instead + of a constructor. A constructor is provided for inheritance purposes only.
  • +
+

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

+
    +
  • Class has only one reusable instance and provides a way to access it.
  • +
  • Class is thread-safe. Thread safety is provided by passing all required data via + parameters of methods. All data specific for a Java* object is + stored in the decoding or encoding stream.
  • +
+

+ 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 =
@@ -1124,59 +968,52 @@
 
 }
 
-
-

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

-
-
+    

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

-
-
+    

+ 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};
 
@@ -1191,29 +1028,23 @@
 // 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: -

-
-
+    

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

-
-
+    

+ 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};
  
@@ -1232,33 +1063,27 @@
 // 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. -

-
-
+    

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

-
-
+    

+ 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
@@ -1281,14 +1106,12 @@
 // 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. -

-
-
+    

+ 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;
@@ -1343,67 +1166,53 @@
 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. -

- +

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

+ - - - - Index: xdocs/subcomponents/classlibrary/compat.xml =================================================================== --- xdocs/subcomponents/classlibrary/compat.xml (revision 517120) +++ xdocs/subcomponents/classlibrary/compat.xml (working copy) @@ -3,11 +3,11 @@ - - + - - Debugging DRL Virtual Machine and JIT Compiler - - - -

- Debugging the DRL Virtual Machine and the - JIT Compiler -

-

- This document gives practical instructions on how to debug - the DRL virtual machine and its baseline just-in-time - compiler Jitrino.JET. For a definition of components and - details on their internal structure, consult the DRL - Virtual Machine Developer’s Guide supplied with - the DRLVM image. -

-

- The document includes two groups of debugging tips, one for - VM tips, and the other for JIT compiler tips, as shown - below. -

- -

- Debugging the Virtual Machine -

-
-

+ Debugging DRL Virtual Machine and JIT Compiler + + +

+ Debugging the DRL Virtual Machine and the JIT Compiler +

+

+ This document gives practical instructions on how to debug the DRL virtual machine + and its baseline just-in-time compiler Jitrino.JET. For a definition of components + and details on their internal structure, consult the + DRL Virtual Machine Developer’s Guide supplied with the DRLVM image. +

+

+ The document includes two groups of debugging tips, one for VM tips, and the other + for JIT compiler tips, as shown below. +

+

+ Debugging the Virtual Machine +

+
+

How to debug the VM? -

-

- How to get more of your - debugging? -

-
-

- Debugging the Jitrino.JET Baseline - Compiler -

-
-

- How to enable tracing in - Jitrino.JET? -

-

- How to configure trace - logging? -

-

- How to get more of your - tracing? -

-
- -

- Back to top -

-

- Debugging the Virtual Machine -

-

- This section gives an insight into debugging the DRL virtual - machine version 1.0 and provides tips on resolving - non-standard debugging issues. -

-

- How to debug the VM? -

-

- This section gives instructions on different scenarios of - debugging the VM source code. -

-

- Basic Debugging Steps -

-

- For ordinary tests, start the ij executable with the - debugger enabled, as follows: -

-

- On Windows* -

-
    -
  1. - Start Microsoft Visual Studio* and open - the solution file vm\build\vm.sln. -
  2. -
  3. - Open the source code that you need to debug, set - breakpoints and perform all other preliminary steps. -
  4. -
  5. - Select the vmcore project and open its properties to - specify the location of the ij executable. - Select the Debugging tab and specify the - command and command arguments. -
  6. -
  7. - Copy the ZLib tool library zlib1.dll to the - location of the VM executable. -
  8. -
  9. - Start debugging via the menu Debug > - Start, click NO in the - popup dialog offering to build the project. -
  10. -
-

- On Linux* -

-
    -
  1. - Set up the LD_LIBRARY_PATH to point to the - deploy/jre/bin directory. Change the working - directory to the location of the VM executable and run: -
    +        

    +

    + How to get more of your debugging? +

    +
+

+ Debugging the Jitrino.JET Baseline Compiler +

+
+

+ How to enable tracing in Jitrino.JET? +

+

+ How to configure trace logging? +

+

+ How to get more of your tracing? +

+
+

+ Back to top +

+

+ Debugging the Virtual Machine +

+

+ This section gives an insight into debugging the DRL virtual machine version 1.0 + and provides tips on resolving non-standard debugging issues. +

+

+ How to debug the VM? +

+

+ This section gives instructions on different scenarios of debugging the VM source + code. +

+

+ Basic Debugging Steps +

+

+ For ordinary tests, start the ij executable with the debugger enabled, as follows: +

+

+ On Windows*

+
    +
  1. Start Microsoft Visual Studio* and open the solution file + vm\build\vm.sln.
  2. +
  3. Open the source code that you need to debug, set breakpoints and perform all other + preliminary steps.
  4. +
  5. Select the vmcore project and open its properties to specify the location of the + ij executable. Select the Debugging tab and specify + the command and command arguments.
  6. +
  7. Copy the ZLib tool library zlib1.dll to the location of the VM executable. +
  8. +
  9. Start debugging via the menu Debug > Start, + click NO in the popup dialog offering to build the project.
  10. +
+

+ On Linux*

+
    +
  1. Set up the LD_LIBRARY_PATH to point to the deploy/jre/bin + directory. Change the working directory to the location of the VM executable and + run: +
     gdb ij
     
    -
  2. -
  3. - Set breakpoints and perform all other preliminary steps. -
  4. -
  5. - On the command line, specify debugging parameters by - typing: -
    +        
  6. +
  7. Set breakpoints and perform all other preliminary steps.
  8. +
  9. On the command line, specify debugging parameters by typing: +
     run <your_params>
     
    -
  10. -
-

- Back to top -

-

- Attaching the Debugger to the Live Process -

-

- To attach to the running VM process, do the following: -

-

- On Windows* -

-
    -
  1. - Start Visual Studio* . -
  2. -
  3. - Go Debug > - Processes. -
  4. -
  5. - Select the VM process and click - Attach.
    - If you built the VM in the debug mode, the - Microsoft Debug Runtime window appears. - Click the Debug button to go to the - crash point. -
  6. -
-

- On Linux* -

-

- Run: -

-
+        
+    
+    

+ Back to top +

+

+ Attaching the Debugger to the Live Process +

+

+ To attach to the running VM process, do the following: +

+

+ On Windows*

+
    +
  1. Start Visual Studio* .
  2. +
  3. Go Debug > Processes.
  4. +
  5. Select the VM process and click Attach.
    + If you built the VM in the debug mode, the Microsoft Debug Runtime + window appears. Click the Debug button to go to the crash point. +
  6. +
+

+ On Linux*

+

+ Run: +

+
 gdb –p <PID of ij>
 
-

- If the VM crashed during execution, use the core dump to - analyze the crash: -

-
+    

+ If the VM crashed during execution, use the core dump to analyze the crash: +

+
 gdb ij core
 
-

- Back to top -

-

- How to get more from your - debugging? -

-

- This section includes some tips on optimizing the debug - process and getting more debug information. -

-

- Configuration of tracing -

-

- Consult the Getting Started guide delivered with - DRLVM bundle for information on VM standard and non-standard - configuration options. Tracing-related options might be - useful for debugging purposes. -

-

- Native stack examination -

-

- The debugger might draw the stack incorrectly when the JIT - or native stubs are involved. To avoid this, set esp as the - memory location and 4-byte integer values as the output - format. As a result, you can examine the stack word by word - and look into the code for each number 0x00… by using - the Disassembly window. -

-
-

- When the VM has crashed -

-

- A very specific case on Windows*: the VM - has crashed and you only see the stack frame in the call - stack 0x00000000. This means that the - program has jumped or called to a null pointer. -

-

- You might still get the stack trace. For that, do the - following: -

-
    -
  1. - Open the Disassembly window. -
  2. -
  3. - Find any ret instruction with no parameters in the - memory space.
    - Open any source file, open the context menu, and - select Go to - Disassembly to find any - ret instruction. -
  4. -
  5. - When found, select the ret instruction and click - Set Next Statement in the context - menu. -
  6. -
  7. - Type F11 to go a single instruction.
    - You may see several instructions near the current - point of execution. If you see a call instruction, you - have found an appropriate call site and you can see - the call stack in the Call Stack - window. If you have found a wrong call site, repeat - the instruction from step 2. -
  8. -
-
-

- Back to top -

-

- Java* stack examination -

-

- On Windows* -

-

- Running the VM in the interpreter mode, you can get Java* methods stack trace almost at any point of - execution. For that, break the execution of the VM and - select the Interpreter frame in the Visual - Studio* Call Stack window. - Then, in the watch window, add the watch - stack_dump(). The stack dump appears in VM - output window. Running the VM in the JIT mode, use the - st_print() function for the same purpose. -

-

- On Linux* -

-

- Use the gdb command print and specify the - stack_dump or st_print in the - interpreter or the JIT compiler mode respectively. -

-

- Setting smart breakpoints -

-

- On Windows* / IA-32 -

-

- Place breakpoints in source code by inserting calls to the - _CrtDbgBreak() function. Placing the call inside a condition - calls the function only for the specified case you need to - debug. Analogously, you can use the Windows* API function DebugBreak() or print INT 3. -

-

-     Note
-     This requires recompiling the VM. -

-

- On Linux* -

-

- Run the following: -

-
+    

+ Back to top +

+

+ How to get more from your debugging? +

+

+ This section includes some tips on optimizing the debug process and getting more + debug information. +

+

+ Configuration of tracing +

+

+ Consult the Getting Started + guide delivered with DRLVM bundle for information on VM standard and non-standard + configuration options. Tracing-related options might be useful for debugging purposes. +

+

+ Native stack examination +

+

+ The debugger might draw the stack incorrectly when the JIT or native stubs are involved. + To avoid this, set esp as the memory location and 4-byte integer values as the output + format. As a result, you can examine the stack word by word and look into the code + for each number 0x00… by using the Disassembly window. +

+

+ When the VM has crashed +

+

+ A very specific case on Windows*: the VM has crashed and you only + see the stack frame in the call stack 0x00000000. This means that the + program has jumped or called to a null pointer. +

+

+ You might still get the stack trace. For that, do the following: +

+
    +
  1. Open the Disassembly window.
  2. +
  3. Find any ret instruction with no parameters in the memory space.
    + Open any source file, open the context menu, and select Go to + Disassembly to find any ret instruction.
  4. +
  5. When found, select the ret instruction and click Set Next Statement + in the context menu.
  6. +
  7. Type F11 to go a single instruction.
    + You may see several instructions near the current point of execution. If you see + a call instruction, you have found an appropriate call site and you can see the + call stack in the Call Stack window. If you have found a wrong + call site, repeat the instruction from step 2.
  8. +
+

+ Back to top +

+

+ Java* stack examination +

+

+ On Windows*

+

+ Running the VM in the interpreter mode, you can get Java* methods + stack trace almost at any point of execution. For that, break the execution of the + VM and select the Interpreter frame in the Visual Studio* + Call Stack window. Then, in the watch window, add the watch stack_dump(). + The stack dump appears in VM output window. Running the VM in the JIT mode, use + the st_print() function for the same purpose. +

+

+ On Linux*

+

+ Use the gdb command print and specify the stack_dump or + st_print in the interpreter or the JIT compiler mode respectively. +

+

+ Setting smart breakpoints +

+

+ On Windows* / IA-32

+

+ Place breakpoints in source code by inserting calls to the _CrtDbgBreak() + function. Placing the call inside a condition calls the function only for the specified + case you need to debug. Analogously, you can use the Windows* API + function DebugBreak() or print INT 3. +

+

+ Note

+

+ This requires recompiling the VM.

+

+ On Linux*

+

+ Run the following: +

+
 __asm {int 3}
 
-

- Back to top -

-

- Handling Java* threads as native threads -

-

- DRL VM has 1:1 mapping between native threads visible in the - debugger and Java* threads.
- To work with Java* threads individually, - freeze the threads you do not need with the help of the - debugger, and continue execution of other threads. -

-

- Debugging deadlocks with the CriticalSection synchronization - primitive -

-

- The CriticalSection primitive is a common cause - of deadlocks. If the code has stopped at a critical section, - you can try to find the thread that owns this primitive. -

-

- On Windows* -

-

- The file WinNT.H located in <PlatformSDK>\Include - contains the definition for the structure - _RTL_CRITICAL_SECTION, which contains the description of the - CriticalSection primitive. You can get the owning thread for - the CriticalSection primitive in a number of ways, as - indicated below. -

-
-

- Lookup in Memory -

-

- On Windows* -

-

- While debugging the code in Visual Studio, do the - following: -

-
    -
  1. - Go Debug > - Windows > Memory - 1. -
  2. -
  3. - In the address line, enter the address of the critical - section. -
  4. -
  5. - Open the context menu and select 4-byte Integers. This - sets the fourth DWORD from the beginning of the - critical section as the owning thread ID in - hexadecimal representation. -
  6. -
-

-     Note
-     Visual Studio* displays thread IDs - in decimal representation. -

-
-
- In the watch window -

- In the watch window of Visual Studio*, - insert the following: -

-
+    

+ Back to top +

+

+ Handling Java* threads as native threads +

+

+ DRL VM has 1:1 mapping between native threads visible in the debugger and Java* threads.
+ To work with Java* threads individually, freeze the threads you + do not need with the help of the debugger, and continue execution of other threads. +

+

+ Debugging deadlocks with the CriticalSection synchronization primitive +

+

+ The CriticalSection primitive is a common cause of deadlocks. If the + code has stopped at a critical section, you can try to find the thread that owns + this primitive. +

+

+ On Windows*

+

+ The file WinNT.H located in <PlatformSDK>\Include + contains the definition for the structure _RTL_CRITICAL_SECTION, which + contains the description of the CriticalSection primitive. You can get the owning + thread for the CriticalSection primitive in a number of ways, as indicated below. +

+

+ Lookup in Memory

+

+ While debugging the code in Visual Studio, do the following: +

+
    +
  1. Go Debug > Windows > Memory 1. +
  2. +
  3. In the address line, enter the address of the critical section.
  4. +
  5. Open the context menu and select 4-byte Integers. This sets the fourth DWORD from + the beginning of the critical section as the owning thread ID in hexadecimal representation. +
  6. +
+

+ Note

+

+ Visual Studio* displays thread IDs in decimal representation.

+

+ In the watch window

+

+ In the watch window of Visual Studio*, insert the following: +

+
 * ((int* )<cs-ptr>+3)
 
-

- Where <cs-ptr> is the address of your - critical section -

-
-

- On Linux* -

-

- The file /usr/include/bits/pthreadtypes.h - contains the description of the pthread_mutex_t - type. To get the ID of the thread owning the - CriticalSection primitive, in gdb execute: -

-
+    

+ Where <cs-ptr> is the address of your critical section +

+

+ On Linux*

+

+ The file /usr/include/bits/pthreadtypes.h contains the description + of the pthread_mutex_t type. To get the ID of the thread owning the + CriticalSection primitive, in gdb execute: +

+
 x/4w <address of your mutex primitive>
 
-

- The third word in the output contains the owning thread - descriptor you are looking for. -

-

- Getting a class name for an object -

-

- You can often need to find out the class name for a Java* object used in VM code. For example, you may - need to get the class name for an object of the type - ManagedObject * (which is a direct pointer to - the heap). For that, insert the following expression into - the watch window in Visual Studio on Windows* or print the command of gdb on - Linux* : -

- ((VTable*)(*((int - *)obj)))->clss->name->bytes -

- Variables of the types jobject and - Object_Handle are references to - ManagedObject * types. These structures contain - a single element, a pointer to ManagedObject * - type object. To use the expression above, de-reference the - variable, for example, substituting obj in the - expression above with a cast to (ManagedObject - *)(*(int *)obj). -

-

- Back to top -

-

- Debugging the Jitrino.JET - Baseline Compiler -

-

- To use debugging and tracing in Jitrino.JET, use the debug - build or the release build with the JET_PROTO - macro defined. See the file jdefs.h for a - definition of the available flags. -

-

- How to enable tracing in - Jitrino.JET? -

-

- Currently, Jitrino.JET provides no interface or command line - to control tracing options. To enable tracing, set the - compile_flags variable at the entry point to - the method Compiler::compile(). At that point, - the global variable Compiler::g_methodsSeen - contains the ID of the method being compiled, and the - instance variable m_fname contains its fully - qualified name with no signature. Obtain these options - through a call to - Compiler::m_infoBlock.get_flags(). -

-

- How to configure trace - logging? -

-

- Tracing flags control compilation results output and trace - run-time execution, as described below. Tracing results are - created in each run in the directory where the - ij executable starts: compilation results are - in jet.log, and run-time output is in - jet.rt.log. -

-

- Group 1: Compilation Results Tracing -

-

- The following flags control tracing compilation of a method: -

-
    -
  • - DBG_TRACE_SUMM prints a - short summary about the compiled method: the compilation - status (success or failure), the name, signature, - bytecode size, the start and end addresses of the - generated code, and the compilation ID (the sequential - number of the method compiled by Jitrino.JET). -
  • -
  • - DBG_DUMP_BBS dumps the - bytecode and marks up basic blocks boundaries. -
  • -
  • - DBG_TRACE_CG prints - information about each compiled bytecode instruction: the - state of the Java* operand stack before - the instruction, the known state of local variables at - the given point, and the native code generated for the - instruction. The order instructions appear in the log - file is the depth-first order, the same as when - processing instructions during compilation. See the file - trace.cpp, function toStr2() for the legend - of the operand stack items print-out. -
  • -
  • - DBG_TRACE_LAYOUT prints the - results of the code layout, mostly, the address ranges - for the basic blocks. -
  • -
  • - DBG_DUMP_CODE dumps - generated code for the given method, the method’s - actual addresses, intermixed with appropriate bytecode - instructions. -

    -     Note
    -     For DBG_DUMP_CODE and - DBG_TRACE_CG, Jitrino.JET can print - disassembled code in addition to raw hexadecimal - dumps. For that, the compiler requires an external - disassembler. Currently, Jitrino.JET is configured to - use the external library - lwdis.dll/liblwdis.so that must be - located in the same directory as - jitrino.dll/libjitrino.so. The name lwdis - stands for light weight disassembler. The library must - export the function disasm(). Refer to - the file trace.cpp, the DISFUNC - definition for details on calling convention and - signature. +

    + The third word in the output contains the owning thread descriptor you are looking + for. +

    +

    + Getting a class name for an object +

    +

    + You can often need to find out the class name for a Java* object + used in VM code. For example, you may need to get the class name for an object of + the type ManagedObject * (which is a direct pointer to the heap). For + that, insert the following expression into the watch window in Visual Studio on + Windows* or print the command of gdb on Linux* + : +

    +
    ((VTable*)(*((int*)obj)))->clss->name->bytes
    +

    + Variables of the types jobject and Object_Handle are references to + ManagedObject * types. These structures contain a single element, a + pointer to ManagedObject * type object. To use the expression above, + de-reference the variable, for example, substituting obj in the expression + above with a cast to (ManagedObject *)(*(int *)obj). +

    +

    + Back to top +

    +

    + Debugging the Jitrino.JET Baseline Compiler +

    +

    + To use debugging and tracing in Jitrino.JET, use the debug build or the release + build with the JET_PROTO macro defined. See the file jdefs.h + for a definition of the available flags. +

    +

    + How to enable tracing in Jitrino.JET? +

    +

    + Currently, Jitrino.JET provides no interface or command line to control tracing + options. To enable tracing, set the compile_flags variable at the entry + point to the method Compiler::compile(). At that point, the global + variable Compiler::g_methodsSeen contains the ID of the method being + compiled, and the instance variable m_fname contains its fully qualified + name with no signature. Obtain these options through a call to Compiler::m_infoBlock.get_flags(). +

    +

    + How to configure trace logging? +

    +

    + Tracing flags control compilation results output and trace run-time execution, as + described below. Tracing results are created in each run in the directory where + the ij executable starts: compilation results are in jet.log, + and run-time output is in jet.rt.log. +

    +

    + Group 1: Compilation Results Tracing +

    +

    + The following flags control tracing compilation of a method: +

    +
      +
    • DBG_TRACE_SUMM prints a short summary about the compiled + method: the compilation status (success or failure), the name, signature, bytecode + size, the start and end addresses of the generated code, and the compilation ID + (the sequential number of the method compiled by Jitrino.JET).
    • +
    • DBG_DUMP_BBS dumps the bytecode and marks up basic + blocks boundaries.
    • +
    • DBG_TRACE_CG prints information about each compiled + bytecode instruction: the state of the Java* operand stack before + the instruction, the known state of local variables at the given point, and the + native code generated for the instruction. The order instructions appear in the + log file is the depth-first order, the same as when processing instructions during + compilation. See the file trace.cpp, function toStr2() for the legend + of the operand stack items print-out.
    • +
    • DBG_TRACE_LAYOUT prints the results of the code layout, + mostly, the address ranges for the basic blocks.
    • +
    • DBG_DUMP_CODE dumps generated code for the given method, + the method’s actual addresses, intermixed with appropriate bytecode instructions. +

      + Note

      +

      + For DBG_DUMP_CODE and DBG_TRACE_CG, Jitrino.JET can print + disassembled code in addition to raw hexadecimal dumps. For that, the compiler requires + an external disassembler. Currently, Jitrino.JET is configured to use the external + library lwdis.dll/liblwdis.so that must be located in the same directory + as jitrino.dll/libjitrino.so. The name lwdis stands for light weight + disassembler. The library must export the function disasm(). Refer + to the file trace.cpp, the DISFUNC definition for details on calling + convention and signature.

      -
    • -
    • - DBG_CHECK_STACK prints - nothing but instruments code to check stack integrity. - The methods compiled by Jitrino.JET use EBP-based frames. - These frames can mask errors, for example, wrong - convention usage with a VM helper call. Using this option - performs run-time checks and INT3 raised in case the - stack integrity broken. -
    • -
    • - DBG_BRK inserts INT3 at the - method entry point, so it can be stopped in the debugger. - -

      -     Note
      -     An instance variable of class - Compiler, dbg_break_pc can - be used to insert INT3 at the specified - program counter of a method. +

    • +
    • DBG_CHECK_STACK prints nothing but instruments code + to check stack integrity. The methods compiled by Jitrino.JET use EBP-based frames. + These frames can mask errors, for example, wrong convention usage with a VM helper + call. Using this option performs run-time checks and INT3 raised in case the stack + integrity broken.
    • +
    • DBG_BRK inserts INT3 at the method entry point, so + it can be stopped in the debugger. +

      + Note

      +

      + An instance variable of class Compiler, dbg_break_pc can + be used to insert INT3 at the specified program counter of a method.

      -
    • -
    -

    - Back to top -

    -

    - Group 2: Run-time Execution tracing -

    -

    - The following flags trace run-time life of the method: -

    -
      -
    • - DBG_TRACE_EE prints - entering: <method-name> and exiting: - <method-name> at the method entrance - and exit points.
      +
    • +
    +

    + Back to top +

    +

    + Group 2: Run-time Execution tracing +

    +

    + The following flags trace run-time life of the method: +

    +
      +
    • DBG_TRACE_EE prints entering: <method-name> + and exiting: <method-name> at the method entrance and exit points.

      -
    • -
    • - DBG_TRACE_BC traces - execution of every bytecode instruction by printing a - string of the following format before executing the - instruction: <method-name> @ - PC=<pc>
      +
    • +
    • DBG_TRACE_BC traces execution of every bytecode instruction + by printing a string of the following format before executing the instruction: + <method-name> @ PC=<pc>

      -
    • -
    -

    -     Notes -

    -

    -     The output string for DBG_TRACE_EE and - DBG_TRACE_BC uses a specific format: before the - string, an estimated call depth is printed and the string - gets indentation based on the call depth. After the string, - the string ID is printed. The estimated call depth may help - to identify where a method was called from. The string ID - can be helpful for setting a conditional breakpoint in the - debugger for a complex scenario. For that, set a condition - for the static variable cnt in the function - rt_dbg, file trace.cpp. -

    -

    -     Turning on the option DBG_TRACE_BC may slow - down execution extremely and may result to a gigantic file - jet.rt.log. -

    -
      -
    • - DBG_TRACE_RT traces - run-time support calls, for example, getting address of - ‘this’, support for root set enumeration and - stack unwinding.
      +
    • +
    +

    + Notes

    +

    + The output string for DBG_TRACE_EE and DBG_TRACE_BC uses + a specific format: before the string, an estimated call depth is printed and the + string gets indentation based on the call depth. After the string, the string ID + is printed. The estimated call depth may help to identify where a method was called + from. The string ID can be helpful for setting a conditional breakpoint in the debugger + for a complex scenario. For that, set a condition for the static variable cnt in + the function rt_dbg, file trace.cpp.
    + Turning on the option DBG_TRACE_BC may slow down execution extremely + and may result to a gigantic file jet.rt.log. +

    +
      +
    • DBG_TRACE_RT traces run-time support calls, for example, + getting address of ‘this’, support for root set enumeration and stack + unwinding.

      -
    • -
    -

    -     Note
    -     The output goes to jet.log, with the address (both - native and PC) where the event happens, and some other info. -

    -

    - Back to top -

    -

    - How to get more from your - tracing? -

    -

    - To identify one or more problematic methods with another - stable JIT compiler, use the execution manager. With this - technique, some methods are compiled by the stable JIT, and - the rest goes to the JIT being debugged. With a simple - binary search, you can find the problematic method rather - quickly. -

    -

    -     Note
    -     Try turning off parallel compilation when using this - technique (refer to VM’s - -Xno_parallel_jit option). -

    -

    - To get details in case of a crash with no adequate - stack trace or IP location available, turn on the option - DBG_TRACE_EE to see, in which method the crash happens. As - the second step, turn on DBG_TRACE_BC for this particular - method to find the exact bytecode instruction. Often, this - cuts the code to analyze down to 5-10 native instructions. -

    -

    - To set a breakpoint and stop execution at a specific - point, use trace.cpp:rt_dbg to break execution at the - specified bytecode instruction or at the entry point of the - specified method. -

    -

    - Back to top -

    -

    - Tracing Example -

    -

    - This is an example of code that turns on various tracing - scenarios. The code must be placed in the method - Compiler::compile(). -

    -

    - #if defined(_DEBUG) || defined(JET_PROTO) -

    -

    -     // - Turns on a short summary of all methods -

    -

    -     compile_flags |= DBG_TRACE_SUMM; -

    -

    -     // A - handy constant -

    -

    -     static const unsigned TRACE_CG = DBG_DUMP_BBS | DBG_TRACE_CG | -

    -

    -                                      DBG_TRACE_LAYOUT - | DBG_TRACE_SUMM | -

    -

    -                                      DBG_DUMP_CODE; -

    -

    -     // For - methods in the range (1000;15000), print out the complete - code generator dumps -

    -

    -     if (g_methodsSeen>1000 && g_methodsSeen<15000) { -

    -

    -     compile_flags |= TRACE_CG; -

    -

    -     } -

    -

    -     // For - methods getSomeValue() and for all methods in class - MyClass, -

    -

    -     // - trace enter and exit -

    -

    -     if (NULL != strstr(m_fname, "::getSomeValue") || -

    -

    -         NULL != strstr(m_fname, "MyClass::") ) { -

    -

    -         compile_flags |=     DBG_TRACE_EE; -

    -

    -     } -

    -

    -     // For - the method crashes_some_times() in class MyClass trace - every -

    -

    -     // - bytecode execution: the last bytecode in the log is the most - probable -

    -

    -     // - cause of the failure -

    -

    -     if (!strcmp(m_fname, - "MyClass::crashes_some_times")) { -

    -

    -         compile_flags |= DBG_TRACE_EE|DBG_TRACE_BC; -

    -

    -     } -

    -

    -     // - Break into debugger (INT3) at the entry of the - stop_at_entry() method -

    -

    -     if (!strcmp(m_fname, "MyClass::stop_at_entry")) - { -

    -

    -         compile_flags |= DBG_BRK; -

    -

    -     } -

    -

    -     // - Break into debugger (INT3) inside the method -

    -

    -     if (!strcmp(m_fname, - "MyClass::stop_somewhere_in_the_middle")) { -

    -

    -         dbg_break_pc = 50; -

    -

    -     } -

    -

    -     // - Trace run-time support calls: unwind, getting the address of - 'this', root -

    -

    -     // set - enumeration -

    -

    -     if (!strcmp(m_fname, - "MyClass::something_wrong_with_unwind_here")) { -

    -

    -         compile_flags |= DBG_TRACE_RT; -

    -

    -     } -

    -

    -     // - By-pass run-time tracing for java/* classes -

    -

    -     if (m_fname == strstr(m_fname, "java/")) { -

    -

    -         compile_flags &= ~(DBG_TRACE_EE|DBG_TRACE_BC); -

    -

    -     } -

    -

    - #endif -

    - -

    - Back to top -

    -

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

    - +
  • +
+

+ Note

+

+ The output goes to jet.log, with the address (both native and PC) where the event + happens, and some other info. +

+

+ Back to top +

+

+ How to get more from your tracing? +

+

+ To identify one or more problematic methods with another stable JIT compiler, use + the execution manager. With this technique, some methods are compiled by the stable + JIT, and the rest goes to the JIT being debugged. With a simple binary search, you + can find the problematic method rather quickly. +

+

+ Note

+

+ Try turning off parallel compilation when using this technique (refer to VM’s + -Xno_parallel_jit option). +

+

+ To get details in case of a crash with no adequate stack trace or IP location + available, turn on the option DBG_TRACE_EE to see, in which method + the crash happens. As the second step, turn on DBG_TRACE_BC for this + particular method to find the exact bytecode instruction. Often, this cuts the code + to analyze down to 5-10 native instructions. +

+

+ To set a breakpoint and stop execution at a specific point, use trace.cpp:rt_dbg + to break execution at the specified bytecode instruction or at the entry point of + the specified method. +

+

+ Back to top +

+

+ Tracing Example +

+

+ This is an example of code that turns on various tracing scenarios. The code must + be placed in the method Compiler::compile(). +

+

+ #if + + defined(_DEBUG) || + defined(JET_PROTO) +

+

+ + // Turns on a short summary of all methods +

+

+ + compile_flags |= DBG_TRACE_SUMM; +

+

+ + // A handy constant +

+

+ + static const unsigned + TRACE_CG = DBG_DUMP_BBS + | DBG_TRACE_CG | +

+

+ + DBG_TRACE_LAYOUT | DBG_TRACE_SUMM | +

+

+ + DBG_DUMP_CODE; +

+

+ + // For methods in the range (1000;15000), print out the complete code generator + dumps +

+

+ + if (g_methodsSeen>1000 && + g_methodsSeen<15000) { +

+

+ + compile_flags |= TRACE_CG; +

+

+ } +

+

+ + // For methods getSomeValue() and for all methods in class MyClass, +

+

+ + // trace enter and exit +

+

+ + if (NULL != + strstr(m_fname, "::getSomeValue") + || +

+

+ + NULL != strstr(m_fname, + "MyClass::") ) { +

+

+ + compile_flags |= DBG_TRACE_EE; +

+

+ } +

+

+ + // For the method crashes_some_times() in class MyClass trace every +

+

+ + // bytecode execution: the last bytecode in the log is the most probable +

+

+ + // cause of the failure +

+

+ + if (!strcmp(m_fname, + "MyClass::crashes_some_times")) { +

+

+ + compile_flags |= DBG_TRACE_EE|DBG_TRACE_BC; +

+

+ } +

+

+ + // Break into debugger (INT3) at the entry of the stop_at_entry() method +

+

+ + if (!strcmp(m_fname, + "MyClass::stop_at_entry")) { +

+

+ + compile_flags |= DBG_BRK; +

+

+ } +

+

+ + // Break into debugger (INT3) inside the method +

+

+ + if (!strcmp(m_fname, + "MyClass::stop_somewhere_in_the_middle")) { +

+

+ + dbg_break_pc = 50; +

+

+ } +

+

+ + // Trace run-time support calls: unwind, getting the address of 'this', root +

+

+ + // set enumeration +

+

+ + if (!strcmp(m_fname, + "MyClass::something_wrong_with_unwind_here")) { +

+

+ + compile_flags |= DBG_TRACE_RT; +

+

+ } +

+

+ + // By-pass run-time tracing for java/* classes +

+

+ + if (m_fname == + strstr(m_fname, "java/")) { +

+

+ + compile_flags &= ~(DBG_TRACE_EE|DBG_TRACE_BC); +

+

+ } +

+

+ #endif +

+

+ Back to top +

+

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

+ - Index: xdocs/subcomponents/drlvm/GettingStarted.html =================================================================== --- xdocs/subcomponents/drlvm/GettingStarted.html (revision 517120) +++ xdocs/subcomponents/drlvm/GettingStarted.html (working copy) @@ -1,10 +1,10 @@ - - - Apache Harmony Source Code - Harmony Documentation Team - + + Apache Harmony Source Code + Harmony Documentation Team + + - +
+

+ The Harmony project uses the + Subversion version control + system. If you're new to Subversion, you can check out the + online book about Subversion. + Note that we are currently using Subversion 1.1.x (there are separate + versions of the book covering 1.0 and 1.1). +

-
+ +

+ If you just want to browse the source code, you can use the + + ViewCVS + web interface + to Subversion. This is current at all times. +

+
-

-The Harmony project uses the -Subversion version control -system. If you're new to Subversion, you can check out the -online book about Subversion. -Note that we are currently using Subversion 1.1.x (there are separate -versions of the book covering 1.0 and 1.1). -

+ +

+ Anyone can check code out of Subversion. You only need to specify a + username and password in order to update the Subversion repository, and only + Harmony committers have the permissions to do that. We run Subversion + over standard HTTPS, so hopefully you won't have problems with intervening + firewalls. +

- +

Check out from Subversion

+

Again, anyone can do this. Use a command like:

+
svn checkout https://svn.apache.org/repos/asf/harmony
-

-If you just want to browse the source code, you can use the -ViewCVS -web interface to Subversion. This is current at all times. -

- -
- - - -

Anyone can check code out of Subversion. You only need to specify a -username and password in order to update the Subversion repository, and only -Harmony committers have the permissions to do that. We run Subversion -over standard HTTPS, so hopefully you won't have problems with intervening -firewalls.

- -Check out from Subversion -

Again, anyone can do this. Use a command like:

-
svn checkout https://svn.apache.org/repos/asf/harmony
- -Commit Changes to Subversion - -

-Any Harmony committer should have a shell account on -svn.apache.org. Before you can commit, you'll need to set a -Subversion password for yourself. To do that, log in to -svn.apache.org and run the command svnpasswd. -

- -

-Once your password is set, you can use a command like this to commit: -

- -
svn commit
- -

If Subversion can't figure out your username, you can tell it -explicitly:

-
svn --username you commit
-

Subversion will prompt you for a password, and once you enter it once, it -will remember it for you. Note this is the password you configured with -svnpasswd, not your shell or other password.

- -
-
- +

Commit Changes to Subversion

+

+ Any Harmony committer should have a shell account on + svn.apache.org. Before you can commit, you'll need to set a + Subversion password for yourself. To do that, log in to + svn.apache.org and run the command svnpasswd. +

+

Once your password is set, you can use a command like this to commit:

+
svn commit
+

+ If Subversion can't figure out your username, you can tell it + explicitly: +

+
svn --username you commit
+

+ Subversion will prompt you for a password, and once you enter it once, it + will remember it for you. Note this is the password you configured with + svnpasswd, not your shell or other password. +

+ +
+