net.java.games.gluegen

Class JavaConfiguration


public class JavaConfiguration
extends java.lang.Object

Parses and provides access to the contents of .cfg files for the JavaEmitter.

Field Summary

static int
NIO_MODE_ALL_POINTERS
See nioMode
static int
NIO_MODE_VOID_ONLY
See nioMode

Method Summary

protected void
addClassJavadoc(String className, String code)
protected void
addCustomJavaCode(String className, String code)
protected void
addTypeInfo(TypeInfo info)
boolean
allStatic()
Returns true if the emission style is AllStatic.
String
className()
Returns the class name parsed from the configuration file.
List
customCCode()
Returns, as a List of Strings, the custom C code to be emitted along with the glue code for the main class.
List
customJavaCodeForClass(String className)
Returns a list of Strings containing user-implemented code for the given Java type name (not fully-qualified, only the class name); returns either null or an empty list if there is no custom code for the class.
protected void
dispatch(String cmd, StringTokenizer tok, File file, String filename, int lineNo)
protected void
doInclude(StringTokenizer tok, File file, String filename, int lineNo)
protected void
doIncludeAs(StringTokenizer tok, File file, String filename, int lineNo)
int
emissionStyle()
Returns the code emission style (constants in JavaEmitter) parsed from the configuration file.
boolean
emitImpl()
Returns true if an implementing class should be emitted during glue code generation.
boolean
emitInterface()
Returns true if an interface should be emitted during glue code generation.
List
extendedInterfaces(String interfaceName)
Returns a List of Strings indicating the interfaces the passed interface should declare it extends.
boolean
flattenNIOVariants()
Returns true if, for the plethora of java.nio variants generated for primitive C pointer types, the emitter should flatten the output down to two variants: one taking only Java primitive arrays as arguments, and one taking only java.nio.Buffers as arguments.
boolean
forcedNio(String functionName)
Returns true if the user requested that the given function should create a java.nio variant for the given function's void* and other C primitive pointers, overriding the NIO mode default.
List
forcedStructs()
Returns, as a List of Strings, the structs for which glue code emission should be forced.
String
implClassName()
Returns the implementation class name parsed from the configuration file.
String
implPackageName()
Returns the implementation package name parsed from the configuration file.
List
implementedInterfaces(String className)
Returns a List of Strings indicating the interfaces the passed class should declare it implements.
List
imports()
Returns the list of imports that should be emitted at the top of each .java file.
boolean
isUnimplemented(String symbol)
Returns true if this function should be given a body which throws a run-time exception with an "unimplemented" message during glue code generation.
String
javaOutputDir()
Returns the Java code output directory parsed from the configuration file.
List
javadocForClass(String className)
Returns a list of Strings containing Javadoc documentation for the given Java type name (not fully-qualified, only the class name); returns either null or an empty list if there is no Javadoc documentation for the class.
boolean
manuallyImplement(String functionName)
Returns true if the glue code for the given function will be manually implemented by the end user.
List
mirroredArgs(String functionName)
Returns a List of Integers indicating the indices of arguments in this function that should be expanded to the same type when binding functions with multiple void* arguments.
String
nativeOutputDir()
Returns the native code output directory parsed from the configuration file.
boolean
nativeOutputUsesJavaHierarchy()
Returns whether the native code directory structure mirrors the Java hierarchy.
int
nioMode()
Returns the default NIO generation mode for C primitive pointer arguments.
boolean
nioOnly(String functionName)
Returns true if the given function should only create a java.nio variant, and no array variants, for void* and other C primitive pointers.
boolean
noNio(String functionName)
Returns true if the user requested that the given function should only create array variants, and no java.nio variant, for void* and other C primitive pointers, overriding the NIO mode default.
String
packageForStruct(String structName)
Returns the package into which to place the glue code for accessing the specified struct.
String
packageName()
Returns the package name parsed from the configuration file.
protected static TypeInfo
parseTypeInfo(String cType, JavaType javaType)
void
read(String filename)
Reads the configuration file.
protected void
read(String filename, String linePrefix)
Reads the specified file, treating each line as if it started with the specified string.
protected void
readArgumentIsString(StringTokenizer tok, String filename, int lineNo)
When const char* arguments in the C function prototypes are encountered, the emitter will normally convert them to byte[] arguments.
protected Boolean
readBoolean(String cmd, StringTokenizer tok, String filename, int lineNo)
protected void
readClassJavadoc(StringTokenizer tok, String filename, int lineNo)
protected void
readCustomCCode(StringTokenizer tok, String filename, int lineNo)
protected void
readCustomJavaCode(StringTokenizer tok, String filename, int lineNo)
protected void
readExtend(StringTokenizer tok, String filename, int lineNo)
protected void
readIgnore(StringTokenizer tok, String filename, int lineNo)
protected void
readIgnoreField(StringTokenizer tok, String filename, int lineNo)
protected void
readIgnoreNot(StringTokenizer tok, String filename, int lineNo)
protected void
readImplements(StringTokenizer tok, String filename, int lineNo)
protected void
readManuallyImplement(StringTokenizer tok, String filename, int lineNo)
protected void
readMirrorExpandedBindingArgs(StringTokenizer tok, String filename, int lineNo)
When void* arguments in the C function prototypes are encountered, the emitter will try to expand the binding and create Java entry points for all possible array types.
protected void
readNioMode(StringTokenizer tok, String filename, int lineNo)
Sets the default NIO generation mode for C primitive pointers.
protected void
readOpaque(StringTokenizer tok, String filename, int lineNo)
protected void
readRenameJavaType(StringTokenizer tok, String filename, int lineNo)
protected void
readReturnValueCapacity(StringTokenizer tok, String filename, int lineNo)
protected void
readReturnValueLength(StringTokenizer tok, String filename, int lineNo)
protected void
readReturnedArrayLength(StringTokenizer tok, String filename, int lineNo)
protected void
readReturnsString(StringTokenizer tok, String filename, int lineNo)
protected String
readString(String cmd, StringTokenizer tok, String filename, int lineNo)
protected void
readStructPackage(StringTokenizer tok, String filename, int lineNo)
protected void
readTemporaryCVariableAssignment(StringTokenizer tok, String filename, int lineNo)
protected void
readTemporaryCVariableDeclaration(StringTokenizer tok, String filename, int lineNo)
protected void
readUnimplemented(StringTokenizer tok, String filename, int lineNo)
String
renameJavaType(String javaTypeName)
Returns a replacement name for this type, which should be the name of a Java wrapper class for a C struct, or the name unchanged if no RenameJavaType directive was specified for this type.
String
returnValueCapacity(String functionName)
Returns a MessageFormat string of the C expression calculating the capacity of the java.nio.ByteBuffer being returned from a native method, or null if no expression has been specified.
String
returnValueLength(String functionName)
Returns a MessageFormat string of the C expression calculating the length of the array being returned from a native method, or null if no expression has been specified.
String
returnedArrayLength(String functionName)
Provides a Java MessageFormat expression indicating the number of elements in the returned array from the specified function name.
boolean
returnsString(String functionName)
Indicates whether the given function (which returns a char* in C) should be translated as returning a java.lang.String.
String
runtimeExceptionType()
Returns the kind of exception to raise if run-time checks fail in the generated code.
boolean
shouldIgnore(String symbol)
Returns true if this #define, function, struct, or field within a struct should be ignored during glue code generation.
List
stringArguments(String functionName)
Returns a list of Integers which are the indices of const char* arguments that should be converted to Strings.
protected Class
stringToPrimitiveType(String type)
List
temporaryCVariableAssignments(String functionName)
Returns a List of Strings of expressions containing assignments to temporary C variables in the glue code for the specified function.
List
temporaryCVariableDeclarations(String functionName)
Returns a List of Strings of expressions declaring temporary C variables in the glue code for the specified function.
TypeInfo
typeInfo(net.java.games.gluegen.cgram.types.Type type, net.java.games.gluegen.cgram.types.TypeDictionary typedefDictionary)
If this type should be considered opaque, returns the TypeInfo describing the replacement type.

Field Details

NIO_MODE_ALL_POINTERS

public static final int NIO_MODE_ALL_POINTERS
Field Value:
2

NIO_MODE_VOID_ONLY

public static final int NIO_MODE_VOID_ONLY
Field Value:
1

Method Details

addClassJavadoc

protected void addClassJavadoc(String className,
                               String code)

addCustomJavaCode

protected void addCustomJavaCode(String className,
                                 String code)

addTypeInfo

protected void addTypeInfo(TypeInfo info)

allStatic

public boolean allStatic()
Returns true if the emission style is AllStatic.

className

public String className()
Returns the class name parsed from the configuration file.

customCCode

public List customCCode()
Returns, as a List of Strings, the custom C code to be emitted along with the glue code for the main class.

customJavaCodeForClass

public List customJavaCodeForClass(String className)
Returns a list of Strings containing user-implemented code for the given Java type name (not fully-qualified, only the class name); returns either null or an empty list if there is no custom code for the class.

dispatch

protected void dispatch(String cmd,
                        StringTokenizer tok,
                        File file,
                        String filename,
                        int lineNo)
            throws IOException

doInclude

protected void doInclude(StringTokenizer tok,
                         File file,
                         String filename,
                         int lineNo)
            throws IOException

doIncludeAs

protected void doIncludeAs(StringTokenizer tok,
                           File file,
                           String filename,
                           int lineNo)
            throws IOException

emissionStyle

public int emissionStyle()
Returns the code emission style (constants in JavaEmitter) parsed from the configuration file.

emitImpl

public boolean emitImpl()
Returns true if an implementing class should be emitted during glue code generation.

emitInterface

public boolean emitInterface()
Returns true if an interface should be emitted during glue code generation.

extendedInterfaces

public List extendedInterfaces(String interfaceName)
Returns a List of Strings indicating the interfaces the passed interface should declare it extends. May return null or a list of zero length if there are none.

flattenNIOVariants

public boolean flattenNIOVariants()
Returns true if, for the plethora of java.nio variants generated for primitive C pointer types, the emitter should flatten the output down to two variants: one taking only Java primitive arrays as arguments, and one taking only java.nio.Buffers as arguments.

forcedNio

public boolean forcedNio(String functionName)
Returns true if the user requested that the given function should create a java.nio variant for the given function's void* and other C primitive pointers, overriding the NIO mode default.

forcedStructs

public List forcedStructs()
Returns, as a List of Strings, the structs for which glue code emission should be forced.

implClassName

public String implClassName()
Returns the implementation class name parsed from the configuration file.

implPackageName

public String implPackageName()
Returns the implementation package name parsed from the configuration file.

implementedInterfaces

public List implementedInterfaces(String className)
Returns a List of Strings indicating the interfaces the passed class should declare it implements. May return null or a list of zero length if there are none.

imports

public List imports()
Returns the list of imports that should be emitted at the top of each .java file.

isUnimplemented

public boolean isUnimplemented(String symbol)
Returns true if this function should be given a body which throws a run-time exception with an "unimplemented" message during glue code generation.

javaOutputDir

public String javaOutputDir()
Returns the Java code output directory parsed from the configuration file.

javadocForClass

public List javadocForClass(String className)
Returns a list of Strings containing Javadoc documentation for the given Java type name (not fully-qualified, only the class name); returns either null or an empty list if there is no Javadoc documentation for the class.

manuallyImplement

public boolean manuallyImplement(String functionName)
Returns true if the glue code for the given function will be manually implemented by the end user.

mirroredArgs

public List mirroredArgs(String functionName)
Returns a List of Integers indicating the indices of arguments in this function that should be expanded to the same type when binding functions with multiple void* arguments. Returns null if no such indices were specified.

nativeOutputDir

public String nativeOutputDir()
Returns the native code output directory parsed from the configuration file.

nativeOutputUsesJavaHierarchy

public boolean nativeOutputUsesJavaHierarchy()
Returns whether the native code directory structure mirrors the Java hierarchy.

nioMode

public int nioMode()
Returns the default NIO generation mode for C primitive pointer arguments. NIO_MODE_VOID_ONLY is the default and specifies that only void* arguments will have java.nio variants generated for them. NIO_MODE_ALL_POINTERS specifies that all C primitive arguments will have java.nio variants generated.

nioOnly

public boolean nioOnly(String functionName)
Returns true if the given function should only create a java.nio variant, and no array variants, for void* and other C primitive pointers.

noNio

public boolean noNio(String functionName)
Returns true if the user requested that the given function should only create array variants, and no java.nio variant, for void* and other C primitive pointers, overriding the NIO mode default.

packageForStruct

public String packageForStruct(String structName)

packageName

public String packageName()
Returns the package name parsed from the configuration file.

parseTypeInfo

protected static TypeInfo parseTypeInfo(String cType,
                                        JavaType javaType)

read

public final void read(String filename)
            throws IOException
Reads the configuration file.
Parameters:
filename - path to file that should be read

read

protected final void read(String filename,
                          String linePrefix)
            throws IOException
Reads the specified file, treating each line as if it started with the specified string.
Parameters:
filename - path to file that should be read
linePrefix - if not null, treat each line read as if it were prefixed with the specified string.

readArgumentIsString

protected void readArgumentIsString(StringTokenizer tok,
                                    String filename,
                                    int lineNo)
When const char* arguments in the C function prototypes are encountered, the emitter will normally convert them to byte[] arguments. This directive lets you specify which of those arguments should be converted to String arguments instead of byte[] .

For example, given the C prototype:

 void FuncName(const char* ugh, int bar, const char *foo, const char* goop);
 
The emitter will normally emit:
 public abstract void FuncName(byte[] ugh, int bar, byte[] foo, byte[] goop);
 
However, if you supplied the following directive:
 ArgumentIsString FuncName 0 2
 
The emitter will instead emit:
 public abstract void FuncName(String ugh, int bar, String foo, byte[] goop);
 

readBoolean

protected Boolean readBoolean(String cmd,
                              StringTokenizer tok,
                              String filename,
                              int lineNo)

readClassJavadoc

protected void readClassJavadoc(StringTokenizer tok,
                                String filename,
                                int lineNo)

readCustomCCode

protected void readCustomCCode(StringTokenizer tok,
                               String filename,
                               int lineNo)

readCustomJavaCode

protected void readCustomJavaCode(StringTokenizer tok,
                                  String filename,
                                  int lineNo)

readExtend

protected void readExtend(StringTokenizer tok,
                          String filename,
                          int lineNo)

readIgnore

protected void readIgnore(StringTokenizer tok,
                          String filename,
                          int lineNo)

readIgnoreField

protected void readIgnoreField(StringTokenizer tok,
                               String filename,
                               int lineNo)

readIgnoreNot

protected void readIgnoreNot(StringTokenizer tok,
                             String filename,
                             int lineNo)

readImplements

protected void readImplements(StringTokenizer tok,
                              String filename,
                              int lineNo)

readManuallyImplement

protected void readManuallyImplement(StringTokenizer tok,
                                     String filename,
                                     int lineNo)

readMirrorExpandedBindingArgs

protected void readMirrorExpandedBindingArgs(StringTokenizer tok,
                                             String filename,
                                             int lineNo)
When void* arguments in the C function prototypes are encountered, the emitter will try to expand the binding and create Java entry points for all possible array types. If there are 2 or more void* arguments in the C prototype, this directive lets you specify which of those arguments should always be expanded to the same type.

For example, given the C prototype:

 void FuncName(void *foo, void *bar);
 
The emitter will normally emit multiple Java entry points:
 public abstract void FuncName(boolean[] foo, java.nio.Buffer bar);
 public abstract void FuncName(boolean[] foo, boolean[] bar);
 public abstract void FuncName(boolean[] foo, byte[] bar);
 public abstract void FuncName(boolean[] foo, char[] bar);
 public abstract void FuncName(boolean[] foo, short[] bar);
 public abstract void FuncName(boolean[] foo, int[] bar);
 public abstract void FuncName(boolean[] foo, long[] bar);
 public abstract void FuncName(boolean[] foo, float[] bar);
 public abstract void FuncName(boolean[] foo, double[] bar);
 
 public abstract void FuncName(byte[] foo, java.nio.Buffer bar);
 public abstract void FuncName(byte[] foo, boolean[] bar);
 public abstract void FuncName(byte[] foo, byte[] bar);
 <...etc for all variants on the second parameter...>
 
 public abstract void FuncName(char[] foo, java.nio.Buffer bar);
 public abstract void FuncName(char[] foo, boolean[] bar);
 public abstract void FuncName(char[] foo, byte[] bar);
 <...etc for all variants on the second parameter...>
 <...and so on for all remaining variants on the first parameter...>
 
This directive lets you specify that arguments at a particular index should always be expanded to the same type. For example, the directive:
 MirrorExpandedBindingArgs FuncName 0 1
 
will force the first and second arguments in function FuncName to be expanded identically. This would result in the emission of the following entry points only:
 public abstract void FuncName(java.nio.Buffer[] foo, java.nio.Buffer bar);
 public abstract void FuncName(boolean[] foo, boolean[] bar);
 public abstract void FuncName(byte[] foo, byte[] bar);
 public abstract void FuncName(char[] foo, char[] bar);
 public abstract void FuncName(short[] foo, short[] bar);
 public abstract void FuncName(int[] foo, int[] bar);
 public abstract void FuncName(long[] foo, long[] bar);
 public abstract void FuncName(float[] foo, float[] bar);
 public abstract void FuncName(double[] foo, double[] bar);
 

readNioMode

protected void readNioMode(StringTokenizer tok,
                           String filename,
                           int lineNo)
Sets the default NIO generation mode for C primitive pointers. Options are VOID_ONLY or ALL_POINTERS. When the mode is set to VOID_ONLY, java.nio variants of methods are only generated for C primitive pointers of type void*. All other pointers are translated by default into Java primitive arrays. When the mode is set to ALL_POINTERS, C primitive pointers of other types (i.e., int*) will have java.nio variants generated for them (i.e., IntBuffer as opposed to merely int[]). This default mode can be overridden with the NioOnly and NoNio directives. The default for this mode is currently VOID_ONLY.

readOpaque

protected void readOpaque(StringTokenizer tok,
                          String filename,
                          int lineNo)

readRenameJavaType

protected void readRenameJavaType(StringTokenizer tok,
                                  String filename,
                                  int lineNo)

readReturnValueCapacity

protected void readReturnValueCapacity(StringTokenizer tok,
                                       String filename,
                                       int lineNo)

readReturnValueLength

protected void readReturnValueLength(StringTokenizer tok,
                                     String filename,
                                     int lineNo)

readReturnedArrayLength

protected void readReturnedArrayLength(StringTokenizer tok,
                                       String filename,
                                       int lineNo)

readReturnsString

protected void readReturnsString(StringTokenizer tok,
                                 String filename,
                                 int lineNo)

readString

protected String readString(String cmd,
                            StringTokenizer tok,
                            String filename,
                            int lineNo)

readStructPackage

protected void readStructPackage(StringTokenizer tok,
                                 String filename,
                                 int lineNo)

readTemporaryCVariableAssignment

protected void readTemporaryCVariableAssignment(StringTokenizer tok,
                                                String filename,
                                                int lineNo)

readTemporaryCVariableDeclaration

protected void readTemporaryCVariableDeclaration(StringTokenizer tok,
                                                 String filename,
                                                 int lineNo)

readUnimplemented

protected void readUnimplemented(StringTokenizer tok,
                                 String filename,
                                 int lineNo)

renameJavaType

public String renameJavaType(String javaTypeName)
Returns a replacement name for this type, which should be the name of a Java wrapper class for a C struct, or the name unchanged if no RenameJavaType directive was specified for this type.

returnValueCapacity

public String returnValueCapacity(String functionName)
Returns a MessageFormat string of the C expression calculating the capacity of the java.nio.ByteBuffer being returned from a native method, or null if no expression has been specified.

returnValueLength

public String returnValueLength(String functionName)
Returns a MessageFormat string of the C expression calculating the length of the array being returned from a native method, or null if no expression has been specified.

returnedArrayLength

public String returnedArrayLength(String functionName)
Provides a Java MessageFormat expression indicating the number of elements in the returned array from the specified function name. Indicates that the given return value, which must be a pointer to a CompoundType, is actually an array of the CompoundType rather than a pointer to a single object.

returnsString

public boolean returnsString(String functionName)
Indicates whether the given function (which returns a char* in C) should be translated as returning a java.lang.String.

runtimeExceptionType

public String runtimeExceptionType()
Returns the kind of exception to raise if run-time checks fail in the generated code.

shouldIgnore

public boolean shouldIgnore(String symbol)
Returns true if this #define, function, struct, or field within a struct should be ignored during glue code generation.

stringArguments

public List stringArguments(String functionName)
Returns a list of Integers which are the indices of const char* arguments that should be converted to Strings. Returns null if there are no such hints for the given function name.

stringToPrimitiveType

protected Class stringToPrimitiveType(String type)
            throws ClassNotFoundException

temporaryCVariableAssignments

public List temporaryCVariableAssignments(String functionName)
Returns a List of Strings of expressions containing assignments to temporary C variables in the glue code for the specified function.

temporaryCVariableDeclarations

public List temporaryCVariableDeclarations(String functionName)
Returns a List of Strings of expressions declaring temporary C variables in the glue code for the specified function.

typeInfo

public TypeInfo typeInfo(net.java.games.gluegen.cgram.types.Type type,
                         net.java.games.gluegen.cgram.types.TypeDictionary typedefDictionary)
If this type should be considered opaque, returns the TypeInfo describing the replacement type. Returns null if this type should not be considered opaque.