Java Project J040602 com.orcmid.LLC.pa.pn ALPHA Organization  Package Projection

com.orcmid> LLC>pa>pn> ALPHA> J040602b> 0.11 2004-10-06-19:30 -0700

Synopsis

The com.orcmid.LLC.pa.pn package structure is projected onto a number of hierarchical structures used in the development of the Peano Numeral package.  These hierarchies are chosen and their components are named so that their intended relationship to com.orcmid.LLC.pa.pn is recognizable.

We speak of this as a projection to capture the following practical matter:

• com.orcmid.LLC.pa.pn identifies an abstract construct in application of the Java programming language.
• The (relatively) material structures that are employed in the expression and execution of corresponding Java compilation units are identified in ways that reflect the abstract structure

It is valuable to notice that this is a practice.  Part of it is a practice and convention established and honored in the community of Java developers, including the developers of Java platforms and hosts.  Additional details are introduced for the specific purpose of providing a harmonious organization of material that is easily recognized as related to com.orcmid.LLC.pa.pn.

For use and adaptation of this material, the key elements to understand are 

• the authoritative use of com.orcmid.LLC.pa.pn (section 2.2), 
• the correct setup of Java Package files for %CLASSPATH%\com\orcmid\LLC\pa\pn (section 3.1), and 
• access to the latest materials using the official web site location <http://orcmid.com/com.orcmid/LLC/pa/pn/> (section 5)

The additional material is provided as demonstration of how additional details might be handled in a chosen development environment.

1. Overview
2. Java Package Hierarchy
     2.1 Basic Rules
     2.2 Authoritative Use of com.orcmid
3. File-System Hierarchies
     3.1 Java Package-Files Access
     3.2 Package-Publication Images
4. Visual SourceSafe Projects
5. HTTP Web Access
6. References

1. Overview

1.1 The package name com.orcmid.LLC.pa.pn is reserved for the Peano Numeral package.  The name was chosen for that purpose and it is our declaration that it shall be so.  The authority by which this claim is made is the fact of ownership of the orcmid.com Internet domain name.

1.2 Having reserved the name, we commence to establish our intention for it, including:

• logistical and storage-organization requirements for access to the compilation units and related material for the package
• access to authoritative definitions of the package and the rules for its use (identified here)
• how to honor the interface contracts for implementation and use of the public types specified in the Peano Numeral package (specified elsewhere)

1.3 Table 1-1 identifies how the Java package structure, com.orcmid.LLC.pa.pn, is projected onto the development and publishing configuration.  This projection is made onto five kinds of hierarchical namings used in the implementation and deployment of package compilation units:

1. Java Package hierarchies
2. File System (\\compagno) hierarchies
3. Visual Source Safe (\\compagno\vss) project hierarchies 
4. HTTP Server hierarchies
5. FTP Server hierarchies

1.4 Other forms of hierarchy, such as one carried internal to a ZIP archive or to a Java Jar (.jar) file, are not employed in the Peano Numeral ALPHA development effort.  We also ignore, at this point, provisions in recent versions of Java software for package versioning, sealing, and other identification of packages at run time.

2. Java Package Hierarchy

2.1 Basic Rules

2.1.1 The interpretation of package names occurring within Java programs is established in the Java Language Specification [1: 6.5.3].  

2.1.2 The specific structure of package names is established in the language specification [1: 6.8.1].  This is where it is established that the first prefix must be a top-level Internet domain name (TLD), such as com.  

2.1.3 The hierarchy of Java packages, and the rules for names that express the hierarchy, are given in the chapter on packages [1: 7].  The decentralized maintenance of unique package names is an important feature of the Java package naming system [1: 7.7]:

• A convention for specifying unique package names is suggested.
• In this convention, it is important to possess (or belong to an organization that possesses) a unique Internet domain name, such as orcmid.com.
• The components of the unique domain name are reversed to create a unique package prefix, such as com.orcmid.
• The assignment of subpackage names and the maintenance of their uniqueness becomes the responsibility of the entity that owns the domain name.

2.1.4 This is a convention.  The package uniqueness convention is widely honored.  The public reliance on a conflicting scheme is likely to be strongly-discouraged in the Java community.

2.2 Authoritative Use of com.orcmid

2.2.1 As the owner of Internet domain orcmid.com, Dennis Hamilton and NuovoDoc assert authority over the Java package hierarchy having prefix com.orcmid.  The following hierarchy of package names is reserved by them for usage relevant to the Numbering Peano project:

com.orcmid
com.orcmid.LLC
com.orcmid.LLC.pa
com.orcmid.LLC.pa.pn

2.2.2 The name com.orcmid.LLC.pa.pn.ALPHA is restricted and is not intended to be used for any purpose.

2.2.3 The Java Language Specification does not require any correspondence between package names and storage at physical locations on the Internet.  There is no requirement that there be a correspondence to an Internet location at all, in the sense of there being a direct association with an authoritative web page or other association with a physical location.  

2.2.4 For packages under the com.orcmid prefix, direct associations are honored by local convention, as illustrated here.

3. File-System Hierarchies

File-System hierarchies are used for the storage of Peano Numeral material in two ways:

1. Java access to the packages for local development, testing, and use of package members in other packages and applications
2. Stored "images" of the package material as part of web site publication, including FTP images

All of the cases illustrated here are implemented privately.  They are described here because any use of compilation units for Peano Numerals will likely need to be similar.

3.1 Java Package-Files Access

3.1.1 The Java System host (Sun Java 2 SE 1.4 on Microsoft Windows) used for Peano Numeral development requires packages to be stored in the Windows file system in accordance with the general rules for storing packages in file systems [1: 7.2].  In this scheme, there must be a file hierarchy that provides the appropriate class path:

%CLASSPATH%\com\orcmid\LLC\pa\pn\

3.1.2 The java compiler and run-time make use of the specified %CLASSPATH% location to resolve references to packages, including package com.orcmid.LLC.pa.pn.

3.1.3 For example, in the ALPHA development work, 

%CLASSPATH% = \\compagno\c\Java2\projects

3.1.4 To use the ALPHA Peano Numeral packages, a similar class path must be provided, with the package files placed in the \pn subdirectory.  The choice of %CLASSPATH% portion is determined by the user of the Java host.  The chosen location must include the com.orcmid.LLC.pa.pn hierarchy in its subpackage structure.  Usage of Java package files and the class path is demonstrated in the examples for compiling ALPHA packages.  (When running locally on host compagno, we use %CLASSPATH% = C:\Java2\projects.)

3.1.5 This structure must be mimicked when using the package on any Java host that uses a file system to store packages.  This is the only "intelligence" that the Java language specification imposes on package names.  It provides a means for access to package materials when the package is named in any compilation unit.  Permitting variable %CLASSPATH% choice allows there to be multiple locations for a package of that name, so long as only one of them is provided in a given execution of the Java compiler or run-time.

3.2 Package-Publication Images

3.2.1 For ALPHA Peano Numeral packages, more file-system hierarchies are used.  They provide images for web-site access to the Numbering Peano materials.

3.2.2 It is not intended that direct Java compiler and run-time access be supported on these web sites.  The projection of com.orcmid.LLC.pa.pn onto these web site file images is for our convenience (Table 1-1):

\\compagno\c\Inetpub\wwwroot\orcmid \com.orcmid\LLC\pa\pn\ALPHA

is the image in the file system of the local IIS 5.1 server that is used for development and updating of the web pages about the Peano Numeral package.
   

\\compagno\c\publicca\bCentral\web\orcmid \com.orcmid\LLC\pa\pn\ALPHA

is the image of the latest material ready for publishing on the web site.  It provides a source for restoration of the web site, if needed.
   

ftp://ftp.nfoCentrale.net/web/orcmid /com.orcmid/LLC/pa/pn/ALPHA

is the image of the current material on the externally-hosted, public web site.

 

3.2.3 This approach is also usable for publishing Numbering Peano on other media.  For example, a CD-ROM collection might use the hierarchic structure

%CD-path%/com /orcmid/LLC/pa/pn/ALPHA

in an authoritative form that might also be used as the target of a %CLASSPATH%.

4. Visual SourceSafe Projects

4.1 On the compagno development system, Microsoft Visual SourceSafe 6.0 is employed for source-code control of all materials as they are developed and published.  The Visual SourceSafe (VSS) database is stored at \\compagno\vss and shared with other local development machines as that networked shared-file location.  There are the following project trees currently defined for com.orcmid.LLC.pa.pn package development:

$/Java2 /com/orcmid/LLC/pa/pn

is the project hierarchy for development of Java compilation units and directly-related materials for com.orcmid.LLC.pa.pn.  The corresponding working directories for check-in and check-out of material are the classpath location \\compagno\c\Java2\projects (see section 3.1).
   

$/OrcmidCompagno /com.orcmid/LLC/pa/pn/ALPHA

is the project hierarchy for the local IIS 5.1 development of web site materials about package com.orcmid.LLC.pa.pn and its ALPHA development.  The corresponding working directories for check-in and check-out of material are the web server file-system locations \\compagno\c\Inetpub\wwwroot\orcmid.  This provides a complete version control of the web pages as they are being developed.
   FrontPage extensions for web page authoring on the IIS 5.1 configuration are configured to automatically coordinate check-in and check-out with this VSS project hierarchy.
   There is some sharing of material between the package development projects into the IIS 5.1 development projects, taking advantage of VSS capabilities for sharing of the same resources between projects.
   

$/nfoCentraleMSbCentralWeb/orcmid /com.orcmid/LLC/pa/pn/ALPHA

is the project hierarchy for the externally-published version of the web-site material at a web hosting service.  This material is normally not checked-in and checked-out under this project.
   The content of these projects is completely shared with the $/OrcmidCompagno sub-projects of the same name.  Any updates to those projects are automatically available under these projects.  (This does not include the FrontPage extension material used on the local IIS 5.1 development site.)
   When the development web site has material that is ready to be published to the external hosted site, VSS is used to update the publication file hierarchy image with those materials that are new or have changed.  FTP transfer is used for bulk-transfer of only those files that have changed or are new since the previous update to the public site.

4.2 The version of com.orcmid.LLC.pa.pn source files is reflected in the Visual SourceSafe labels that are included in the published versions, usually in comments (fig. 4-1).

Fig. 4-1 VSS $Header label in Stubby-0.10.java

/* 0.10 2004-09-18-18:02 create a basic stub that implements the minimal degenerate case (says me). $Header: /Java2/com/orcmid/llc/pa/pn/Stubby-0.10.java 2 04-09-18 18:21 Orcmid $ */

4.3 Likewise, there is version information at the bottom right-hand corner of all of the web pages.  There is also a VSS $Header label in the <head>-element of each these web pages.  For example, this page has the HTML comment

<!--$$Header: /OrcmidCompagno/com.orcmid/LLC/pa/pn/ALPHA/J040602b.htm 8     05-02-11 16:47 Orcmid $-->

in its HTML <head>-element.

4.4 VSS version information provides an additional way to confirm that material originated in the development of the com.orcmid.LLC.pa.pn packages.

5. HTTP Web Access

5.1 There are three web locations used in the development of the current com.orcmid.LLC.pa.pn materials:

http://compagno/orcmid /com.orcmid/LLC/pa/pn/ALPHA

is the web site hierarchy used to view the development materials on the IIS 5.1 web server on the local machine.  This site supports FrontPage extensions and page creation and maintenance is accomplished using Microsoft FrontPage on the local machine and on other computers of the local residential network.  (This network is not open to the Internet.)
   

http://nfoCentrale.net/orcmid /com.orcmid/LLC/pa/pn/ALPHA

is the hierarchy at the web site at which Orcmid's Lair is anchored.  This is a hosting of the nfoCentrale.net domain on a public, hosted site.  This is the site that is updated using FTP transfers from the \\compagno\c\publicca\bCentral\web\orcmid file-system image.
   

http://orcmid.com /com.orcmid/LLC/pa/pn/ALPHA

is the web site hierarchy of the com.orcmid.LLC.pa.pn material at the Orcmid's Lair URL.  This site is implemented by web forwarding of the orcmid.com domain to the subweb of nfoCentrale.net above.
   This is the official public URL.  This URL might be forwarded to a different anchor, or made into an independent site at some future time.  By always using this URL, the material will be found wherever it is currently maintained.

 

 

5.2 The http://compagno/orcmid  URLs refer to a private web site that is not exposed to the public Internet.  It is identified here to complete the picture of how the projection is preserved as material is moved among development and public sites.

6. References

1. Joy, Bill (ed.)., Steele, Guy L.,Jr., Gosling, James., Bracha, Gilad.  Java Language Specification.  2.ed.   Addison-Wesley (Boston: 2000).  ISBN 0-201-31008-2 pbk.  Published on the web at <http://java.sun.com/docs/books/jls/>.

0.11 2004-10-06-18:17 Change to Package Projection, not Mapping

We make this change at the same time as we also talk about situating Peano Numeral, rather than binding it.

0.10 2004-09-27-16:33 Provide complete coverage of the current ALPHA organization

The table and material are completed enough to account for all current organization, including the structure of the local development site that harmonizes with the externally-visible published materials.

0.00 2004-09-26-10:18 Setup for Documenting Hierarchical Organization (orcmid)

Create a tabular presentation that reveals the way that package structure com.orcmid.LLC.pa.pn is projected onto computer hierarchies to ground the material and to provide development and access for authoritative versions.