com.sun.tools.corba.se.idl

Class Compile

java.lang.Object

com.sun.tools.corba.se.idl.Compile

Direct Known Subclasses:

Compile

public class Compile
extends Object

Compiler usage:

java com.sun.tools.corba.se.idl.toJava.compile [options]

where <idl file> is the name of a file containing IDL definitions, and [options] is any combination of the options listed below. The options and the idl file name can appear in any order.

Options:

-i <include path>

By default, the current directory is scanned for included files. This option adds another directory. See also Note 1 below.

-d <symbol>

This is equivalent to the following line in an IDL file: #define <symbol>

-emitAll

Emit all types, including those found in #included files.

-v

Verbose mode.

Note 1: If you have an include path or paths that you will always be using, it can get tedious putting these on the command with the -i option all the time. Instead, these can be placed into a config file called idl.config. This file must be in the CLASSPATH. The format of the includes line is:

 includes=;;...;
 

Note that the path separator character, here shown as a semicolon, is machine dependent. For instance, on Windows 95 this character is a semicolon, on UNIX it is a colon.

Note 2: If you are directly invoking the main method on this class (not a subclass), then it will only check that the IDL file is syntactically correct. It does not generate any files. Only extensions to this framework generate files, therefore an extension must be invoked if you want files to be generated.

To Extend the compiler:

You only need to extend the compiler if you want it to generate something other than what it currently generates.

Step 1 - Implement the generator interfaces:

Each generator interface defines one method: generate (Hashtable, XXXEntry, PrintWriter);
- The Hashtable is the symbol table; each element is a SymtabEntry (or a subclass of SymtabEntry) and is keyed by its fully qualified name;
- XXXEntry is the appropriate entry for the type to be generated. For example: AttributeGen defines generate (Hashtable, AttributeEntry, PrintWriter); ConstGen defines generate (Hashtable, ConstEntry, PrintWriter); etc.
- The PrintWriter is a stream to the file being generated. For the generators called by the compiler framework, this will be null. The generator is responsible for creating and opening files. But for generators that are called by other generators - for instance, MethodGen.generate will most likely be called by InterfaceGen.generate - this parameter is provided so that the proper file can be written to.

Step 2 - Implement the GenFactory interface:

All of the generators implemented in Step 1 must be created somehow. There is an interface for a factory, GenFactory, which must be implemented. The name of this factory must be set in the extension to the Compile class (see Step 3, below).

Step 3 - Extend com.sun.tools.corba.se.idl.Factories:

Extend com.sun.tools.corba.se.idl.Factories and override the method genFactory. This method must return an instance of the factory which you implemented in step 2. Your extension of this class may also do more, this is only the minimum. See com.sun.tools.corba.se.idl.Factories for more information.

Step 4 - Extend com.sun.tools.corba.se.idl.Compile:

Your extension of com.sun.tools.corba.se.idl.Compile should contain a minimum of two methods:

protected com.sun.tools.corba.se.idl.Factories ()

This method overrides com.sun.tools.corba.se.idl.Compile.factories and returns your extension from Step 3.

public static void main (String[] args)

This main method must instantiate this class and call its start method.

Given that the extension of Factories is MyFactories, the extension of Compile could be:

 public class MyCompile extends com.sun.tools.corba.se.idl.Compile
 {
   protected com.sun.tools.corba.se.idl.Factories factories ()
   {
     return new MyFactories ();
   }
   public static void main (String[] args)
   {
     MyCompile compile = new MyCompile ();
     compile.start (args);
   }
 }
 

If you would like a bit more control over the processing of the framework, you can replace compile.start with what it calls. But then you also have to handle the exceptions which start handles for you:

 public class MyCompile extends com.sun.tools.corba.se.idl.Compile
 {
   ...

   public static void main (String[] args)
   {
     MyCompile compile = new MyCompile ();
     try
     {
       compile.init (args);
       java.util.Enumeration emitList = compile.parse ();
       compile.generate ();
     }
     catch (com.sun.tools.corba.se.idl.InvalidArgument e)
     {
       System.err.println (e);
     }
     catch (java.io.IOException e)
     {
       System.err.println (e);
     }
   }
 }
 

Note that compile.parse returns an enumeration. This enumerates the SymtabEntry's which should be generated. If the parse method detects errors, it returns null. Note that you do not have to check that `emitList' is valid before calling generate (that's done internally), but if you do any processing between parse and generate, emitList should be checked before executing that code.

Field Summary

Fields

Modifier and Type	Field and Description
Arguments	arguments This is the repository of emitter arguments.
protected Vector	includeEntries This is a vector of IncludeEntry's.
protected Vector	includes This is a vector of strings of the form "IDLfile" or .
protected Hashtable	overrideNames This hashtable contains pairs.
protected Hashtable	symbolTable This is the symbol table.

Constructor Summary

Constructors

Constructor and Description
Compile()

Method Summary

Modifier and Type	Method and Description
protected void	displayVersion() Write the version number of this compiler to standard out.
protected Factories	factories()
protected void	generate() Invoke the generators.
protected void	init(String[] args) Initialize the framework.
static void	main(String[] args)
protected Enumeration	parse() Parse the IDL file and return an enumeration of the symbols to be generated.
protected void	registerPragma(PragmaHandler handler)
void	start(String[] args) Start the parse/code generation process.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

arguments

public Arguments arguments

This is the repository of emitter arguments.

overrideNames

protected Hashtable overrideNames

This hashtable contains pairs. It is filled in by extenders in cases where they wish to override an IDL type name with some other name. For instance, when mapping to Java, there could be an overrideNames entry of <"TRUE", "true">. NOTE: Do NOT change this variable to a new Hash table. Just add elements to it.

symbolTable

protected Hashtable symbolTable

This is the symbol table. It will be empty until the parse method executes. If errors are encountered, the state of the symbol table is undefined.

includes

protected Vector includes

This is a vector of strings of the form "IDLfile" or . It is a list of the files included in the given IDL file. It will be empty until the parse method executes. If errors are encountered, the state of this vector is undefined.

includeEntries

protected Vector includeEntries

This is a vector of IncludeEntry's. It is a list of the files included in the given IDL file. It mirrors the includes vector. It will be empty until the parse method executes. If errors are encountered, the state of this vector is undefined.

Constructor Detail

Compile

public Compile()

Method Detail

main

public static void main(String[] args)

factories

protected Factories factories()

registerPragma

protected void registerPragma(PragmaHandler handler)

init

protected void init(String[] args)
             throws InvalidArgument

Initialize the framework.

Throws:

InvalidArgument

parse

protected Enumeration parse()
                     throws IOException

Parse the IDL file and return an enumeration of the symbols to be generated. All elements of the Enumeration will be extensions of SymtabEntry. If any errors were encountered during parsing, null will be returned.

Throws:

IOException

generate

protected void generate()
                 throws IOException

Invoke the generators.

Throws:

IOException

start

public void start(String[] args)

Start the parse/code generation process. This method calls init, parse, generate. If more control is desired, rather than call start, those three methods could be called explicitly.

displayVersion

protected void displayVersion()

Write the version number of this compiler to standard out.