%
% $Id: tools.tex,v 1.13 2008-11-21 10:04:57 nick.cross Exp $
%

In this chapter we  briefly explain the executables that come
with JacORB. These include the IDL-compiler, a utility to decode IORs
and print their components, the JacORB name server, a utility to test
a remote object's liveness, etc.

\section{idl}

The IDL compiler parses IDL files and maps type definitions to Java
classes as specified by the OMG IDL/Java language mapping. For
example, IDL interfaces are translated into Java interfaces, and
typedefs, structs, const declarations etc.  are mapped onto
corresponding Java classes. Additionally, stubs and skeletons for all
interface types in the IDL specification are generated.

(The  IDL  parser  was   generated  with  Scott  Hudson's  CUP  parser
generator.  The  LALR grammar for  the CORBA IDL  is in the  file {\tt
org/jacorb/idl/parser.cup}.)

\subsection*{Compiler Options}

\begin{tabbing}
XX \= XXXXXXXXXXXXX \= XX \kill
\>  -h $|$ help \>  print help on compiler options\\
\>  -v $|$ version \> print compiler version information\\
\>  -d dir \> root of directory tree for output (default: current directory)\\
\>  -syntax \> syntax check only, no code generation\\
\>  -Dx \>  define preprocessor symbol x with value 1\\
\>  -Dx=y  \>  define preprocessor symbol x with value y\\
\>  -Idir  \>  set include path for idl files\\
\>  -Usymbol \> undefine preprocessor symbol\\
\>  -W [1..4] \> debug output level (default is 1)\\
\>  -all  \> generate code for all IDL files, even included ones
(default is off)\\
\> \> If you want to make sure that for a given IDL no code will\\
\> \>  be generated even if this option is set, use the (proprietary)
preprocessor \\
\> \> directive {\tt \#pragma   inhibit\_code\_generation}.\\
\>  -forceOverwrite \> generate Java code even if the IDL files have
not \\
\> \> changed since the last compiler run (default is off)\\
\>  -ami\_callback  \> generate AMI reply handlers and sendc methods
(default is off). See chapter \ref{ch:AMI}\\
\>  -ami\_polling  \>  generate AMI poller and sendp methods (default
is off). See chapter \ref{ch:AMI}\\
\>  -backend classname \>  use classname as compiler (code generator)
backend.  The default code generator \\
\> \>class is {\tt org.jacorb.idl.javamapping.JavaMappingGeneratingVisitor}\\
\> \>  (c.f. API documentation). Custom generators must implement the
interface\\
\> \> {\tt org.jacorb.idl.IDLTreeVisitor}\\
\> -i2jpackage x:a.b.c \>  replace IDL package name x by a.b.c in
generated Java code \\
\> \> (e.g. CORBA:org.omg.CORBA)\\
\> -i2jpackagefile filename \> replace IDL package names using list
from <filename>. \\
\> \> Format as above.\\
\> -ir \> generate extra information required by the JacORB Interface
Repository \\
\> \> (One extra file for each IDL module, and another additional file per IDL interface.)\\
\> \> (default is off)\\
\> -cldc10 \>Generate J2ME/CLDC1.0 compliant stubs\\
\> -genEnhanced \>Generate stubs with toString/equals (only StructType)\\
\> -nofinal  \> generated Java code will contain no final class
definitions, which\\
\> \> is the default to allow for compiler optimizations.\\
\> -unchecked\_narrow  \>  use unchecked\_narrow in generated code for IOR parameters in
 operations \\
\> \> (default is off). Generated helper classes contain marshalling code which, by
default,\\
\> \>  will try to narrow any object references to statically known interface type. This \\
\> \> may involve remote invocations to test a remote object's type, thus incurring \\
\> \> runtime overhead to achieve static type safety. The -unchecked\_narrow option\\
\> \> generates code that will not by statically type safe, but avoids
remote tests \\
\> \>  of an object's type. If the type is not as expected, clients will experience \\
\> \> CORBA.BAD\_OPERATION exceptions at invocation time.\\
\> -noskel \>disables generation of POA skeletons (e.g., for
client-side use)\\
\> -nostub \>disables generation of client stubs (for server-side use)\\
\> -diistub \>generate DII-based client stubs \\
\> \> (default is off)\\
\> -sloppy\_forward \> allow forward declarations without later
definitions\\
\> \> (useful only for separate compilation).\\
\> -sloppy\_names \> less strict checking of module name scoping
(default: off)\\
\> \> CORBA IDL has a number of  name resolution rules that are
stricter than\\
\> \> necessary for Java (e.g., a struct member's name identifier must
not \\
\> \> equal the type name). The -sloppy\_names option relaxes checking of
these \\
\> \>  rules. Note that IDL accepted with this option will be rejected
by other, conformant  \\
\> \> IDL compilers!\\
\> -permissive\_rmic  \>  tolerate dubious and buggy IDL generated by
JDK's rmic stub generator\\
\> \> (e.g., incorrectly empty inheritance clauses), includes -sloppy\_names.\\
\> -generate\_helper \emph{compatibilty} \\
\> \> controls the compatibilty level of the generated helper code. Valid values are: \\
\> \> {\bf deprecated} uses CORBA 2.3 API. this API version is part of the JDK.\\
\> \> {\bf portable} uses CORBA 2.4 API. the usage of this option mandates the use \\
\> \> of the JacORB provided \emph{org.omg.*} classes on the bootclasspath. This is the default. \\
\> \> {\bf jacorb} uses JacORB API. The generated helper code will contain references \\
\> \> to JacORB classes. The helpers will use the CORBA 2.4 API but won't be portable \\
\> \> anymore. There's no need to put the \emph{org.omg.*} classes provided by JacORB \\
\> \> on the bootclasspath.
\end{tabbing}

\subsection*{i2jpackage}
The {\tt -i2jpackage} switch can be used to flexibly redirect
generated Java classes into packages. Using this option, any IDL scope
x can be replaced by one (or more) Java packages y. Specifying {\tt
  -i2jpackage X:a.b.c} will thus cause code generated for IDL
definitions within a scope x to end up in a Java package {\tt a.b.c},
e.g. an IDL identifier {\tt X::Y::ident} will be mapped to {\tt
  a.b.c.y.ident} in Java. It is also possible to specify a file
containing these mappings using the {\tt -i2jpackagefile} switch.

\subsubsection{Example 1}

given the following IDL definition
\begin{verbatim}
struct MyStruct
{
    long value;
};
\end{verbatim}
Invoking idl without the i2jpackage option will generate (along with other
files) the java file MyStruct.java
\begin{verbatim}

/**
 * Generated from IDL struct "MyStruct".
 *
 * @author JacORB IDL compiler V 2.3, 18-Aug-2006
 * @version generated at 07.12.2006 11:46:28
 */

public final class MyStruct
        implements org.omg.CORBA.portable.IDLEntity
{
    [...]
}
\end{verbatim}

Note that the class does not contain a package definition.

The option -i2jpackage :com.acme will place any identifier without scope into
the java package com.acme. Thus we get:
\begin{verbatim}
package com.acme;

/**
 * Generated from IDL struct "MyStruct".
 *
 * @author JacORB IDL compiler V 2.3, 18-Aug-2006
 * @version generated at 07.12.2006 11:46:28
 */

public final class MyStruct
        implements org.omg.CORBA.portable.IDLEntity
{
    [...]
}
\end{verbatim}

\subsubsection{Example 2}

\begin{verbatim}
module outer
{
    struct OuterStruct
    {
        long value;
    };

    module inner
    {
        struct InnerStruct
        {
            long value;
        };
    };
};
\end{verbatim}

If you're not using the i2jpackage option, the IDL compiler will generate
the classes \emph{outer.OuterStruct} and \emph{outer.inner.InnerStruct}.

Again using the i2jpackage it's possible to map IDL modules to different java
packages.
\cmdline{idl -i2jpackage outer:com.acme.outer} will generate the classes
\emph{com.acme.outer.OuterStruct} and \emph{com.acme.outer.inner.InnerStruct}.

\cmdline{idl -idjpackage inner:com.acme.inner} will generate the classes
\emph{outer.OuterStruct} and \emph{outer.com.acme.inner.InnerStruct}.

Note: See Section \ref{sec:ifr_pragma_i2jpackage} if you intend to use the
i2jpackage option in conjunction with the JacORB IfR and are using \#pragma
prefix statements in your IDL.


\subsection*{Compiler Options}
If one is building from Ant it is possible to invoke the compiler directly
using the supplied Ant task, JacIDL. To add the taskdef add the following
to the ant script:
\small{
\begin{verbatim}
<taskdef name="jacidl" classname="org.jacorb.idl.JacIDL"/>
\end{verbatim}
}
The task supports all of the options of the IDL compiler.

\begin{small}
\begin{longtable}{|p{4cm}|p{8.5cm}|p{2cm}|p{2cm}|}
\caption{JacIDL Configuration}\\
\hline
~ \hfill \textbf {Attribute} \hfill ~ & ~ \hfill \textbf {Description} \hfill ~ & ~ \hfill \textbf{Required} \hfill ~ & ~ \hfill \textbf {Default} \hfill ~ \endhead
\hline
\verb"srcdir" & Location of the IDL files & Yes & \\
\hline
\verb"destdir" & Location of the generated java files & Yes & \\
\hline
\verb"includes" & Comma-separated list of patterns of files that must be included; all files are included when omitted. & No & \\
\hline
\verb"includesfile" & The name of a file that contains include patterns. & No & \\
\hline
\verb"excludes" & Comma-separated list of patterns of files that must be excluded; files are excluded when omitted. & No & \\
\hline
\verb"excludesfile" & The name of a file that contains include patterns. & No & \\
\hline
\verb"defaultexcludes" & Indicates whether default excludes should be used (yes | no); default
excludes are used when omitted. & No & \\
\hline
\verb"includepath" & The path the idl compiler will use to search for included files. & No & \\
\hline
\verb"parseonly" & Only perform syntax check without generating code. & No & False\\
\hline
\verb"noskel" & Disables generation of POA skeletons & No & False\\
\hline
\verb"nostub" & Disables generation of client stubs & No & False\\
\hline
\verb"diistub" & Generate DII-based client stubs & No & False\\
\hline
\verb"sloppyforward" & Allow forward declarations without later definitions & No & False\\
\hline
\verb"sloppynames" & Less strict checking of names for backward compatibility & No & False\\
\hline
\verb"generateir" & Generate information required by the Interface Repository & No & False\\
\hline
\verb"all" & Generate code for all IDL files, even included ones & No & False\\
\hline
\verb"nofinal" & Generate class definitions that are not final & No & False\\
\hline
\verb"forceoverwrite" & Generate code even if IDL has not changed. & No & False\\
\hline
\verb"uncheckedNarrow" & Use unchecked\_narrow in generated code for IOR parameters in operations. & No & False\\
\hline
\verb"ami" & Generate ami callbacks. & No & False\\
\hline
\verb"debuglevel" & Set the debug level from 0 to 4. & No & 0\\
\hline
\verb"helpercompat" & control the portability of the generated helper code. & No & portable \\
\hline
\end{longtable}
\end{small}

\subsection*{Nested Elements}

Several elements may be specified as nested elements. These are {\tt <define>}, {\tt <undefine>}, {\tt <include>}, {\tt <exclude>}, {\tt <patternset>} and {\tt <i2jpackage>}. The format of {\tt <i2jpackage>} is {\tt <i2jpackage names="x:y">}


\subsection*{Examples}

The task command
\small{\begin{verbatim}
    <jacidl destdir="${generate}"
            srcdir="${idl}"
    />
\end{verbatim}
}

compiles all *.idl files under the \${idl} directory and stores the .java files in the \${generate} directory.

\small{\begin{verbatim}
    <jacidl destdir="${generate}" srcdir="${idl}">
       <define key="GIOP_1_1" value="1"/>
    </jacidl>
\end{verbatim}
}

like above, but additionaly defines the symbol GIOP\_1\_1 and sets its (optional) value to 1.

\small{\begin{verbatim}
    <jacidl destdir="${generate}"
            srcdir="${idl}"
            excludes="**/*foo.idl"
    />
\end{verbatim}
}

like the first example, but exclude all files which end with foo.idl.

\section{ns}

JacORB provides a service for mapping names to network references. The
name server itself is written in Java like the rest of the package and
is a  straightforward implementation  of the CORBA  ``Naming Service''
from  Common  Object Services  Spec.,  Vol.1  \cite{OMG1997}. The  IDL
interfaces are mapped to Java according to our Java mapping.

\subsection*{Usage}

\cmdline{ns <filename>  [<timeout>]}

or

\cmdline{jaco jacorb.Naming.NameServer <filename>  [<timeout>]}

\subsection*{Example}

\cmdline{ns \~/public\_html/NS\_Ref}

The name server does {\it not}  use a well known port for its service.
Since clients  cannot (and  need not) know  in advance where  the name
service will  be provided, we use  a bootstrap file in  which the name
server records  an object reference to itself  (its {\it Interoperable
Object Reference} or  IOR). The name of this bootstrap  file has to be
given as an argument to the  {\tt ns} command. This bootstrap file has
to  be available  to clients  network-wide, so  we demand  that  it be
reachable  via a  URL  --- that  is,  there must  be an  appropriately
configured HTTP server in your network domain which allows read access
to the bootstrap  file over a HTTP connection.  (This implies that the
file must have its read  permissions set appropriately. If the binding
to the name service fails, please  check that this is the case.) After
locating the name service through this mechanism, clients will connect
to the name server directly, so the only HTTP overhead is in the first
lookup of the server.

The name bindings in the server's database are stored in and retrieved
from a file that is found in the current directory unless the property
{\tt jacorb.naming.db\_dir} is set to a different directory name. When
the server  starts up, it tries  to read this file's  contents. If the
file  is  empty or  corrupt,  it will  be  ignored  (but overridden  on
exit). The name server can only save its state when it goes down after
a specified timeout. If the server is interrupted (with {\tt CTRL-C}),
state information  is lost  and the file  will not contain  any usable
data.

If no timeout is specified, the name server will simply stay up until
it is killed. Timeouts are specified in milliseconds.

\section{nmg}

The JacORB  NameManager, a  GUI for the  name service, can  be started
using the {\tt nmg} command.  The NameManager then tries to connect to
an existing name service.

\subsection*{Usage}

\cmdline{nmg}

\section{lsns}

This utility  lists the contents  of the default naming  context. Only
currently active servers that have registered are listed. The {\tt -r}
option recursively lists the  contents of naming contexts contained in
the root  context. If  the graph of  naming contexts  contains cycles,
trying to list the entire contents recursively will not return...

\subsection*{Usage}


\cmdline{lsns [-r] }

\subsection*{Example}

\cmdline{lsns \\
\ /grid.service}

when only the server for the grid example is running and registered
with the name server.


\section{dior}

JacORB comes with a simple utility to decode an interoperable object reference
(IOR) in string form into a more readable representation.

\subsection*{Usage}

\cmdline{dior -i <IOR-string> | -f <filename>}

\subsection*{Example}

In the following example we use it to print out the contents of the
IOR that the JacORB name server writes to its file:

\cmdline{dior -f \~/public\_html/NS\_Ref}
\small{\begin{verbatim}
------IOR components-----
TypeId  :       IDL:omg.org/CosNaming/NamingContextExt:1.0
Profile Id   :  TAG_INTERNET_IOP
IIOP Version :  1.0
Host    :       160.45.110.41
Port    :       49435
Object key :    0x52 6F 6F 74 50 4F 41 3A 3A 30 D7 D1 91 E1 70 95 04
\end{verbatim}
}

\section{pingo}

``Ping'' an object using its stringified IOR. Pingo will call {\tt
  \_non\_existent()} on the object's reference to determine whether
  the object is alive or not.

\subsection*{Usage}

\cmdline{pingo -i <IOR-string> | -f <filename> }

\section{ir}

This command starts the JacORB Interface Repository, which is explained in
chapter \ref{ch:interface_repository}.

\subsection*{Usage}

\cmdline{ir <reppository class path> <IOR filename> }

\section{qir}

This command queries the JacORB Interface Repository and prints out
re--generated IDL for the repository item denoted by the argument
repository ID.

\subsection*{Usage}

\cmdline{qir <reppository Id> }

\section{ks}

This command starts the JacORB KeyStoreManager, which is explained in
chapter \ref{ch:SSL}

\subsection*{Usage}

\cmdline{ks}

\section{fixior}

This command patches host and port information into an IOR file.

\subsection*{Usage}

\cmdline{fixior <host> <port> <ior\_file> }


%%% Local Variables:
%%% mode: latex
%%% TeX-master: "../ProgrammingGuide"
%%% End:
