@node    Moving a class into a package
@section Moving a class into a package

@cindex Packages, moving a class into a package

Consider a typical CLASS:

m4_define([COMM],@i{$*})

@example
NI()TT(CLASS A
BEGIN
PD PROPERTY int data;

PD CLASSVAR int data2 = 666;

PD CONSTRUCTOR A(int d)
PD BEGIN
PD PD data = d;
PD END

PD METHOD VOID meth1()
PD BEGIN
PD PD System.out.println("meth1:" + data);
PD END

PD METHOD VOID meth2()
PD BEGIN
PD PD System.out.println("meth2:" + data);
PD END

PD FUNCTION VOID func()
PD BEGIN
PD PD System.out.println("func:" + data2);
PD END

PD BEGINMAIN
PD PD VAR A a1 = NEW A(123);
PD PD a1.meth1();) COMM(// prints out "meth1:123")
TT(PD PD VAR A a2 = NEW A(456);
PD PD a2.meth2();) COMM(// prints out "meth2:456")
TT(PD PD A.func();) COMM(// prints out "func:666")
TT(PD ENDMAIN
END)
@end example

To move this CLASS into a PACKAGE called (for argument's sake)
TT(pkg), you need to set the CLASS's visibility status from none
(i.e. PACKAGE visibility) to POBLIC.  Also each package visible
(i.e. no PRIVATE or POBLIC or PROTECTED specification) CLASS variable,
FUNCTION, METHOD and PROPERTY needs to have its visibility status
changed from package to POBLIC if you want to be able to access these
items from outside of the package.  If you have more than one class in
the same file, they will have to be separated into separate files as
you can only have one POBLIC CLASS per file.  Also the name of the
package must be declared via a PACKAGE specification like so
TT(PACKAGE pkg;) at the top of the file before any actual CLASS or
INTERFACE definitions.  Here is the same source file, ready to be put
into a package:

@example
PACKAGE pkg;

POBLIC CLASS A
BEGIN
PD POBLIC PROPERTY int data;

PD POBLIC CLASSVAR int data2 = 666;

PD POBLIC CONSTRUCTOR A(INT d)
PD BEGIN
PD PD data = d;
PD END

PD POBLIC METHOD VOID meth1()
PD BEGIN
PD PD System.out.println("meth1:" + data);
PD END

PD POBLIC METHOD VOID meth2()
PD BEGIN
PD PD System.out.println("meth2:" + data);
PD END

PD POBLIC FUNCTION VOID func()
PD BEGIN
PD PD System.out.println("func:" + data2);
PD END

PD BEGINMAIN
PD PD VAR A a1 = NEW A(123);
PD PD a1.meth1(); COMM(// prints out "meth1:123")
PD PD VAR A a2 = NEW A(456);
PD PD a2.meth2(); COMM(// prints out "meth2:456")
PD PD A.func(); COMM(// prints out "func:666")
PD ENDMAIN
END
@end example

Also the source file for the class needs to be moved into the
folder TT(TILDE()/jtw-tutorials/pkg).  To run the class, you will need to
invoke the TT(Makefile) command:

@center TT(make clean pkg/A.run)

@node Moving a class into a sub-package
@section Moving a class into a sub-package

Suppose you want to move a class TT(A) from no package (the folder
TT(~/jtw-tutorials)) to a package called for argument's sake
TT(pkg.inner), the steps from @ref{Moving a class into a package}
needs to be followed, the only difference being that the PACKAGE spec
needs to be changed to TT(PACKAGE pkg.inner;) and the file needs to be
moved into the folder TT(pkg/inner).  To run the CLASS file you need
to invoke the following Make command:

@center TT(make clean pkg/inner/A.run).

Here is the class definition for the file
TT(~/jtw-tutorials/pkg/inner/A.jtw):

@example
PACKAGE pkg.inner;

POBLIC CLASS A
BEGIN
PD POBLIC PROPERTY INT data;

PD POBLIC CLASSVAR INT data2 = 666;

PD POBLIC CONSTRUCTOR A(INT d)
PD BEGIN
PD PD data = d;
PD END

PD POBLIC METHOD VOID meth1()
PD BEGIN
PD PD System.out.println("meth1:" + data);
PD END

PD POBLIC METHOD VOID meth2()
PD BEGIN
PD PD System.out.println("meth2:" + data);
PD END

PD POBLIC FUNCTION VOID func()
PD BEGIN
PD PD System.out.println("func:" + data2);
PD END

PD BEGINMAIN
PD PD VAR A a1 = NEW A(123);
PD PD a1.meth1(); COMM(// prints out "meth1:123")
PD PD VAR A a2 = NEW A(456);
PD PD a2.meth2(); COMM(// prints out "meth2:456")
PD PD A.func(); COMM(// prints out "func:666")
PD ENDMAIN
END
@end example

@node Importing a package
@section Importing a package

@cindex Packages, importing

When referring to a CLASS or INTERFACE in a PACKAGE you need to
specify the PACKAGE name in front of every CLASS name and INTERFACE
name in the PACKAGE you want to access, like so, in the MAIN folder
TT(~/jtw-tutorials) (outside of any package):

@example
CLASS B
BEGIN
PD BEGINMAIN
PD PD VAR pkg.A a1 = NEW pkg.A(123);
PD PD a1.meth1(); COMM(// prints out "meth1:123")
PD PD VAR pkg.A a2 = NEW pkg.A(456);
PD PD a2.meth2(); COMM(// prints out "meth2:456")
PD PD pkg.A.func(); COMM(// prints out "func:666")
PD ENDMAIN
END
@end example

To avoid having to qualify each class name and interface name with
it's package, you need to use the IMPORT directive like so before the
definition of the class like so:

@example
IMPORT pkg.*;

CLASS B
BEGIN
PD BEGINMAIN
PD PD VAR A a1 = NEW A(123);
PD PD a1.meth1(); COMM(// prints out "meth1:123")
PD PD VAR A a2 = NEW A(456);
PD PD a2.meth2(); COMM(// prints out "meth2:456")
PD PD A.func(); COMM(// prints out "func:666")
PD ENDMAIN
END
@end example

@node Importing a package from another package
@section Importing a package from another package

When referring to a class or interface in a package you need to
specify the package name in front of every CLASS name or INTERFACE
name in the package you want to access, like so, in the folder
TT(~/jtw-tutorials/pkg) (i.e.\ in the TT(pkg) package).

@example
PACKAGE pkg;

POBLIC CLASS C
BEGIN
PD BEGINMAIN
PD PD VAR pkg.inner.A a1 = NEW pkg.inner.A(123);
PD PD a1.meth1(); COMM(// prints out "meth1:123")
PD PD VAR pkg.inner.A a2 = NEW pkg.inner.A(456);
PD PD a2.meth2(); COMM(// prints out "meth2:456")
PD PD pkg.inner.A.func(); COMM(// prints out "func:666")
PD ENDMAIN
END
@end example

To avoid having to qualify each class name or interface name with it's
package, you need to use the IMPORT directive like so after the
PACKAGE declaration but before the definition of the CLASS or
INTERFACE like so:

@example
PACKAGE pkg;

IMPORT pkg.inner.*;

POBLIC CLASS C
BEGIN
PD BEGINMAIN
PD PD VAR A a1 = NEW A(123);
PD PD a1.meth1(); COMM(// prints out "meth1:123")
PD PD VAR A a2 = NEW A(456);
PD PD a2.meth2(); COMM(// prints out "meth2:456")
PD PD A.func(); COMM(// prints out "func:666")
PD ENDMAIN
END
@end example

@node How to build a collection of class files or an entire package
@section How to build a collection of class files or an entire package

@cindex Building code that uses a PACKAGE
@cindex Building a collection of classes
@cindex Packages, building
@cindex Collection of classes, building

When your class CLSS(X) uses another class CLSS(Y) in a different file
then you need to add to the TT(build) target of your TT(Makefile)
which is initially like so:

@center TT(FUNC(build:) clean)

to what follows:

@center TT(FUNC(build:) clean BO(Y.java))

If your class CLSS(Y) is in another PACKAGE such as the CLASS
GRY(~/jtw-tutorials/path/to/dir/Y.class) i.e. in the PACKAGE
TT(path.to.dir) then you need to add to the build target of your
TT(Makefile) like so:

@center TT(FUNC(build:) clean BO(path/to/dir/Y.java))

This process should be repeated for every CLASS that is called,
directly or indirectly from your MAIN CLASS CLSS(X).  By applying this
process to every file in your package, you can build an entire
package, simply by invoking the TT(Makefile) command TT(make build).
To actually compile and run the CLSS(X) CLASS, let
GRY(~/jtw-tutorials/path2/to/dir/X.class) be the location of the
CLSS(X) CLASS.  Then you need to invoke the following TT(Makefile)
target:

@center TT(make build GRN(path2/to/dir/X.run))

The build target calls the "TT(BO(clean))" target which deletes all
TT(BO(*.java)) and GRY(*.class) files directly or indirectly in the
folder TT(~/jtw-tutorials).  If you don't do this then TT(BO(java))
might run an old version of GRY(*.class) files despite earlier errors
in the build process. This is because the use of pipes in building and
executing GRY(*.class) files hides the return values of the programs
TT(BO(javac)) and TT(BO(java)).

@node How to invoke javadoc on a package
@section How to invoke javadoc on a package

NI()To invoke TT(javadoc), you first need to issue the following
command from the folder TT(~/jtw-tutorials):

@center TT(make build)

NI()See the @ref{How to build a collection of class files or an entire
package} for more information about setting up the TT(build) target.
Then you need to issue the following command from the folder
TT(~/jtw-tutorials):

@center TT(javadoc path3/to/pkg -d /path4/to/dir)

where TT(path3.to.pkg) is the name of the package that you want to
build and TT(/path4/to/dir) is the desired location for your
documentation files in TT(*.html) format.

