Java Project J040603
com.orcmid.LLC.pa.pn ALPHA Compiling

 Compiling Num.java 0.1x

com.orcmid>
LLC>pa>pn>
ALPHA>


J040603c>

0.10 2008-08-28-17:25 -0700


Here we develop the the interface definition that we intend to use as the reference for all further development in files Num-0.1x.java.  These will continue to be used until we have to expand the methods (likely) and/or introduce JavaDoc (probably later).

The 0.1x versions are used to

The files employed in this experiment are archived in J040603c.zip (WinZip file).  File J040603c.txt is the manifest carried in the current WinZip archive.

Here's how we are establishing the next, basic reference level for Num-0.1x.java and the com.orcmid.LLC.pa.pn ALPHA material:

1. Basics
2. The Reference Interface
     2.1 Num-0.10.java
     2.2 Num-0.10.class Compilation
3. Verifying Package-Internal Access 
     3.1 Stubby-0.10.java
     3.2 Stubby.class Compilation
     3.3 StubbyRun Demonstration
4. com.orcmid.LLC.pa.pn.Num: What's In A Name?
     4.1 Binding Considerations
     4.2 To Version 0.11 and Beyond
5. Compilation Environment

 

1. Basics

1.1 We are going to define a simple interface.  It's full name is com.orcmid.LLC.pa.pn.Num.  

1.2 If there is some Java object, SumO, that implements this interface, then we can establish access to that interface by a statement like

com.orcmid.LLC.pa.pn.Num N = SumO;

1.3 If we have a reference to a com.orcmid.LLC.pa.pn.Num interface (such as N, above), then these expressions

N.aum()
N.dim()
N.aum().aum().aum().aum()
N.aum().aum().dim().dim()

all return com.orcmid.LLC.pa.pn.Num interfaces (if they return anything).  

1.4 These additional expressions return boolean values (if they return anything):

N.allo()
N.aum().allo()
N.dim().allo()
N.dim().dim().dim().allo()
( N.allo() ? N.aum().allo() : N.dim().allo() )
( N.allo() ? N.aum() : N.dim() ).allo()

whatever all that means.  

1.5 Throwing an exception from a method is considered equivalent to not returning anything.  Simply disappearing into the ether also counts as not returning anything.  We consider throwing an exception superior to simply disappearing, never to return, never to return.

1.6 The key point is that all we know, with the interface declaration that we make in the next section, is

1.7 If this is all that matters (because it is really all that is known) to the Java processor, it should be clear that there is not much to tell us when an implementation of the interface is "correct" or honors some Java-recognized interface "contract."   

1.8 The next steps, after completing some housekeeping, will be to set the stage for seeing how we can 

  1. Know what the intended behavior is for interface com.orcmid.LLC.pa.pn.Num 
  2. Recognize when assertion that some class implements the interface is valid
  3. Identify the authoritative source in the matter

2. The Reference Interface

see also:
J040603b: Compiling Num.java 0.01
A040601i: Assuming Contexts and Meanings (Miser Project)

After kicking around the earlier 0.01 efforts and knowing I wanted to use a fully-object-oriented manifestation of Peano Numerals, I contrived a simple three-method interface that is similar to earlier trials.  There is also improvement of the package name to fit with the narrative that is envisioned for this exploration.  The method names are also replaced by ones chosen to avoid suggesting much, leaving the readers to recognize that one should not read much into the nomenclature (at least, not until it becomes familiar from discussion and usage).

2.1 Num-0.10.java

2.1.1 Num-0.10.java provides minimal specification of com.orcmid.LLC.pa.pn.Num in terms that have any impact on Java processors.  The intention is to demonstrate  how little meaning is inherent in the compilation unit for the interface.

Fig. 2-1 Num-0.10.java source
/* Num-0.10.java */

package com.orcmid.LLC.pa.pn;

interface Num
{

    public Num aum();

    public Num dim();

    public boolean allo();
}

/* 0.10 2004-09-18-14:35 create basic package with minimal suggestive namings and
        demonstration of what the compiler makes of it.
   $Header: /Java2/com/orcmid/LLC/pa/pn/Num-0.10.java 2     04-09-18 14:36 Orcmid $
   */

2.1.2 This is the minimalist source program.   As far as the Java language is concerned, there is no more conveyed here than in earlier versions.   This is the one we will take as the basic reference for as long as we stick to three simple methods.

2.2 Num-0.10.class Compilation

2.2.1 Compilation of Num-0.10.java will produce a single Num.class file.  This file incorporates enough information for the Java compiler and virtual-machine to implement the interface and provide access to implementations of it.

Fig. 2-2 Num-0.10.class Compilation (Console Session)
[dh:2004-09-18-14:36] C:\...\pn> javac Num-0.10.java

[dh:2004-09-18-14:37] C:\...\pn> list /X Num.class
 Num.class    ¦ F1 Help ¦ Commands: BFGHINPWX ¦     Col 0    Line 1          0% 
0000 0000 CA FE BA BE 00 00 00 2E  00 0C 07 00 0A 07 00 0B   Êþº¾..........   
0000 0010 01 00 03 61 75 6D 01 00  1C 28 29 4C 63 6F 6D 2F   .aum.()Lcom/   
0000 0020 6F 72 63 6D 69 64 2F 4C  4C 43 2F 70 61 2F 70 6E   orcmid/LLC/pa/pn   
0000 0030 2F 4E 75 6D 3B 01 00 03  64 69 6D 01 00 04 61 6C   /Num;.dim.al   
0000 0040 6C 6F 01 00 03 28 29 5A  01 00 0A 53 6F 75 72 63   lo.()Z..Sourc   
0000 0050 65 46 69 6C 65 01 00 0D  4E 75 6D 2D 30 2E 31 30   eFile..Num-0.10   
0000 0060 2E 6A 61 76 61 01 00 18  63 6F 6D 2F 6F 72 63 6D   .java.com/orcm   
0000 0070 69 64 2F 4C 4C 43 2F 70  61 2F 70 6E 2F 4E 75 6D   id/LLC/pa/pn/Num   
0000 0080 01 00 10 6A 61 76 61 2F  6C 61 6E 67 2F 4F 62 6A   .java/lang/Obj   
0000 0090 65 63 74 06 00 00 01 00  02 00 00 00 00 00 03 04   ect........   
0000 00A0 01 00 03 00 04 00 00 04  01 00 05 00 04 00 00 04   ........   
0000 00B0 01 00 06 00 07 00 00 00  01 00 08 00 00 00 02 00   ..........   
0000 00C0 09                                                 .                  
                                                                                

[dh:2004-09-18-14:50] C:\...\pn> rename Num.class Num-0.10.class
C:\java2\projects\com\orcmid\LLC\pa\pn\Num.class -> C:\java2\projects\com\orcmid
\LLC\pa\pn\Num-0.10.class
     1 file renamed

[dh:2004-09-18-14:50] C:\...\pn>

2.2.2 The class file is renamed to Num-0.10.class for preservation and future comparison with other Num.class compilations.  The name must be Num.class in order to access the compilation unit properly.

3. Verifying Package-Internal Access

3.1 Stubby-0.10.java

see also:
J040603b: Compiling Num.java 0.01, Section 3

3.1.1 Num-0.10.java is written so that com.orcmid.LLC.pa.pn.Num is accessible only from other compilation units of the same com.orcmid.LLC.pa.pn package.  We're going to verify how that is done with a simple class that asserts implementation of the interface.  The source file is Stubby-0.10.java:

Fig. 3-1 Stubby-0.10.java source
/* Stubby-0.10.java */

package com.orcmid.LLC.pa.pn;

class Stubby implements com.orcmid.LLC.pa.pn.Num
{

    public com.orcmid.LLC.pa.pn.Num aum()
    {   throw new java.lang.ArithmeticException("No such Stubby Numeral");
        }

    public com.orcmid.LLC.pa.pn.Num dim()
    {   return this; }

    public boolean allo()
    {   return true; }
}

/* 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 $
   */

3.1.2 Observations:

  1. The class Stubby is defined as package-internal, just as the interface com.orcmid.LLC.pa.pn.Num is.
  2. In Stubby, all type names are written out in full so that identifications are as unambiguous as I can make them within the provisions of the Java language.  I will do the same in the next version of Num-0.1x.java.
  3. The Java compiler will require that Stubby offer at least public methods matching the names and signatures of the  methods declared as part of interface com.orcmid.LLC.pa.pn.Num.
  4. In Stubby, the aum() method has no defined result and an unchecked exception is thrown.  Although the Java language and API define unchecked exceptions as always allowed, I will modify the next version of Num-0.1x.java to specify that aum() throws this exception.  That is important-to-document technical information.  The requirements for implementation of the com.orcmid.LLC.pa.pn.Num interface will also reflect that this is the only method exception that is allowed to be thrown intentionally.
  5. In demonstrating successful package access, it is unimportant whether Stubby satisfies any requirements for the interface beyond what is conveyed in Java language.  At this point, I am still making up the behavioral requirements as I go along.  Nevertheless, Stubby is likely to be a valid implementation, albeit for a degenerate case.

3.2 Stubby.class Compilation

3.2.1 Compiling Stubby confirms what I thought might be a difficulty.  Although you can produce a package-internal compilation unit anywhere, you can only find one at a proper classpath location.  Operating in the same directory where a Num.class is already compiled, I obtain this result:

Fig. 3-2 Stubby-0.10.java Compilation (Console Session)

[dh:2004-09-18-18:11] C:\...\pn> javac Stubby-0.10.java
Stubby-0.10.java:5: cannot resolve symbol
symbol  : class Num
location: package pn
class Stubby implements com.orcmid.LLC.pa.pn.Num
                                            ^
Stubby-0.10.java:8: cannot resolve symbol
symbol  : class Num
location: package pn
    public com.orcmid.LLC.pa.pn.Num aum()
                               ^
Stubby-0.10.java:12: cannot resolve symbol
symbol  : class Num
location: package pn
    public com.orcmid.LLC.pa.pn.Num dim()
                               ^
3 errors

[dh:2004-09-18-18:13] C:\...\pn> javac -classpath .;C:\java2\projects Stubby-0.1
0.java

[dh:2004-09-18-18:14] C:\...\pn> cd
C:\java2\projects\com\orcmid\LLC\pa\pn

3.2.2 However, the working directory is beneath a point in the computer directory hierarchy that works as the proper class path, and everything compiles properly when that class path is set.

3.2.3 Clueless Moment:  At first I thought that I could get away with something and not have to provide a properly-structured class path for the path-internal usages.  My initial compilations were done with jEdit's JCompiler plug-in and Stubby seemed to compile just fine without my doing anything about class paths.  Au contraire, the JCompiler plug-in is configured to discover the class path for the package of the current source file and it was able to do that.  In fact, I figured out how to write my own command line, above, from the JCompiler log:

> compile
Compiling C:\java2\projects\com\orcmid\LLC\pa\pn\Stubby-0.10.java...

Command line:
javac -classpath .;C:\java2\projects -g C:\java2\projects\com\orcmid\LLC\pa\pn\Stubby-0.10.java

JCompiler done.

 

3.3 StubbyRun Demonstration

3.3.1 Having come this far, we can also demonstrate how package-internal classes can be used as part of a package-internal (and public) application class.  StubbyRun.java is the simplest demonstration I could think of without input-output.  The program must fail with a java.lang.ArithmeticException.  The only question is, which one?

Fig. 3-3 StubbyRun.java 0.10 source
/* StubbyRun.java */

package com.orcmid.LLC.pa.pn;

public class StubbyRun
{
    public static void main(java.lang.String[] arg)
    {   com.orcmid.LLC.pa.pn.Num N = new com.orcmid.LLC.pa.pn.Stubby();
        if (N.dim().allo()) 
            N = N.aum();
        else throw new java.lang.ArithmeticException("Stubby Failed");
        } // main(string[])

    } // StubbyRun

/* 0.10 2004-09-18-20:17 create a Java application that simply lets Stubby do
        its degenerate thing.  All this application does is blow up.
   $Header: /Java2/com/orcmid/LLC/pa/pn/StubbyRun.java 1     04-09-18 20:30 Orcmid $
   */

 3.3.2 And here is what we get for our efforts:

Fig. 3-4 StubbyRun Execution (Console Session)

[dh:2004-09-18-21:10] C:\...\pn> javac -classpath .;C:\java2\projects StubbyRun.
java

[dh:2004-09-18-21:11] C:\...\pn> java -cp .;C:\java2\projects com.orcmid.LLC.pa.
pn.StubbyRun
Exception in thread "main" java.lang.ArithmeticException: No such Stubby Numeral

        at com.orcmid.LLC.pa.pn.Stubby.aum(Stubby-0.10.java:9)
        at com.orcmid.LLC.pa.pn.StubbyRun.main(StubbyRun.java:10)

[dh:2004-09-18-21:11] C:\...\pn>

which is exactly what I was looking for (after figuring out how to write the java command properly).  

3.3.3 Here we can see that 

4. com.orcmid.LLC.pa.pn.Num: What's In A Name?

We have established workable compilation techniques for package com.orcmid.LLC.pa.pn elements.  We now have enough experience with what actually happens to tidy up a little.  At the same time, we want to begin looking at what can be identified.  Given enough identifiers, we want to build up assurance that a person can find authoritative information about an interface and appropriate implementations of it (and how one can tell that).

4.1 Binding Considerations

see also:
J040602: Peano Numerals ALPHA Organization
J040602c: Situating Peano Numeral
where these ideas are elaborated and demonstrated further.

We're ready to establish the scaffolding and framework on which we can build more.  

4.1.1 We are not going to offer more "meaning" for interface com.orcmid.LLC.pa.pn.Num here.   Rather, we want to provide a place where someone can find whatever authoritative information there is, as it is progressively built-up.  

4.1.2 We consider the following ways that someone could want to know what the package com.orcmid.LLC.pa.pn is all about (among others discussed under the organization topic):

  1. Source code from the package is encountered.  Links to authoritative locations about the code can be provided in each file.  This is particularly important for ALPHA and other material that are not part of a stable release.  Preserving links to authoritative material is also important in case the code has been repackaged in such a way that the package name isn't sufficient to suggest a primary source. Links are also one way to locate licensing information,  documentation, and support status that might not accompany the source code. 
  2. One of the ZIP archives is available  Archives, such as J040603c.zip, the one for these experiments, include the source code files.  In addition there is sufficient descriptive information to consult without accessing the web.  All of that material also leads to authoritative sources.   A valuable feature of detached information,  is the presence of links to the authoritative material and determine whether there are known defects in the material being used and whether there is more recent material.  It might also be important to learn that the material is obsolete or revoked in some fashion.  
    1. One direct feature would be to specify a link to where a source element is archived.  
    2. The manifest or other special element in the archive itself should link to the location of the authoritative version as a means to finding recent history and status.

4.2 To Version 0.11 and Beyond

It is now time to put all of this talking around the changes to be made to the material and to change something.  This will happen in another page.  We will preserve the version 0.10 material (except for notes concerning its obsolescence) and build a new ZIP archive.  Instead of describing all of this again, however, we streamline the presentation of differences by incorporating more about what's up in the files and the archives.

5. Compilation Environment

5.1 The computer used for these compilations is Compagno, a Dell Inspiron 7000 with Intel Pentium II and Windows XP (Build 2600) SP1

5.2 The Java 2 platform used is Java 2 Platform, Standard Edition v 1.4.1 SDK (1.4.1_02) for Microsoft Windows.  Important Note 2004-12-02: This version of the J2SE Platform and some of its successors have security defects in their Java Virtual Machine (JVM).  This will require an upgrade.  It is recommended that you use a later version of the J2SE SDK that does not have any security defects recorded against it.  At the moment, version 1.4.2_06 is the oldest secure release.

5.3 I used jEdit version 4.1 final as a programmer's editor.  The jEdit colorizations are used in the source-code illustrations on this page.  JCompiler plug-in 1.50 is used for launching compiles and matching error messages to source code (with support from other prerequisite plug-ins).  SourceControl plug-in 0.52 is used for integration of jEdit with Visual Source Safe 6.0c (Build 9447).

5.4 The command line interface used is  JP Software 4NT Command Processor version 5.00 (Build 101). At the time of the compilation exhibited here, the following settings were in effect.  There is a change in the command-line prompt from the Num-0.01.java work.  Now the prompt provides a dateline and abbreviates the working-directory path.

Fig. 5-1 4NT Console-Session Environment

[dh:2004-09-18-14:21] C:\...\pn> ver

4NT  5.00U   Windows XP 5.1

[dh:2004-09-18-14:23] C:\...\pn> path
Path=C:\JAVA2\SDK1.4.1.02\BIN;C:\WINDOWS\SYSTEM32;C:\WINDOWS;C:\WINDOWS\SYSTEM32
\WBEM;C:\COMANDO\TOOLS

[dh:2004-09-18-14:23] C:\...\pn> set
ALLUSERSPROFILE=C:\Documents and Settings\All Users
APPDATA=C:\Documents and Settings\Dennis E. Hamilton\Application Data
CLASSPATH=.
CommonProgramFiles=C:\Program Files\Common Files
COMPUTERNAME=COMPAGNO
ComSpec=C:\comando\4NT\4nt.exe
HOMEDRIVE=C:
HOMEPATH=\Documents and Settings\Dennis E. Hamilton
LOGONSERVER=\\COMPAGNO
NUMBER_OF_PROCESSORS=1
OS=Windows_NT
Path=C:\JAVA2\SDK1.4.1.02\BIN;C:\WINDOWS\SYSTEM32;C:\WINDOWS;C:\WINDOWS\SYSTEM32
\WBEM;C:\COMANDO\TOOLS
PATHEXT=.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH
PROCESSOR_ARCHITECTURE=x86
PROCESSOR_IDENTIFIER=x86 Family 6 Model 5 Stepping 2, GenuineIntel
PROCESSOR_LEVEL=6
PROCESSOR_REVISION=0502
ProgramFiles=C:\Program Files
PROMPT=[dh:$j-$m]$s$W$g$s
SESSIONNAME=Console
SystemDrive=C:
SystemRoot=C:\WINDOWS
TEMP=C:\DOCUME~1\DENNIS~1.HAM\LOCALS~1\Temp
TMP=C:\DOCUME~1\DENNIS~1.HAM\LOCALS~1\Temp
USERDOMAIN=COMPAGNO
USERNAME=orcmid
USERPROFILE=C:\Documents and Settings\Dennis E. Hamilton
windir=C:\WINDOWS

[dh:2004-09-18-14:23] C:\...\pn>
C:\java2\projects\com\orcmid\LLC\pa\pn

 


0.10 2004-09-19-15:07 Complete the coverage of all 0.10-level cases
All of the 0.10 material is completed before undertaking an 0.11 reference definition and test case.
0.00 2004-09-18-13:57 Setup for Documenting Compiles and Package Structure (orcmid)
Confirm that the revised interface compiles and then determine how it is referenced from another compilation unit of the same package.

Construction Zone (Hard Hat Area)

You are navigating Orcmid's Lair

created 2004-06-12-14:09 -0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 08-08-28 17:27 $
$$Revision: 23 $

Home