com.jogamp.gluegen

Class JavaConfiguration

java.lang.Object

com.jogamp.gluegen.JavaConfiguration

Direct Known Subclasses:

ProcAddressConfiguration

public class JavaConfiguration
extends Object

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

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	DEBUG_IGNORES
static boolean	DEBUG_RENAMES
protected static Logger	LOG
static String	NEWLINE

Constructor Summary

Constructors

Constructor and Description
JavaConfiguration()

Method Summary

Methods

Modifier and Type	Method and Description
JavaEmitter.MethodAccess	accessControl(String methodName) Returns the access control for the emitted Java method.
protected void	addClassJavadoc(String className, String code)
protected void	addCustomJavaCode(String className, String code)
protected void	addJavaPrologueOrEpilogue(String methodName, String code, boolean prologue)
void	addJavaSymbolRename(String origName, String newName) Programmatically adds a rename directive for the given symbol.
protected void	addMethodJavadoc(String methodName, String code)
protected void	addTypeInfo(TypeInfo info)
void	addUseNIODirectOnly(String fname)
void	addUseNIOOnly(String fname)
boolean	allStatic() Returns true if the emission style is AllStatic.
String	className() Returns the class name parsed from the configuration file.
List<String>	customCCode() Returns, as a List of Strings, the custom C code to be emitted along with the glue code for the main class.
List<String>	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)
void	dumpIgnores()
void	dumpIgnoresOnce()
void	dumpRenames()
void	dumpRenamesOnce()
JavaEmitter.EmissionStyle	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<String>	extendedInterfaces(String interfaceName) Returns a List of Strings indicating the interfaces the passed interface should declare it extends.
String	extendedParentClass(String className) Returns a List of Strings indicating the interfaces the passed class should declare it implements.
List<String>	forcedStructs() Returns, as a List of Strings, the structs for which glue code emission should be forced.
String	getJavaSymbolRename(String origName) Returns a replacement name for this function or definition which should be used as the Java name for the bound method or constant.
Set<String>	getRenamedJavaSymbols(String aliasedName) Returns a set of replaced names to the given aliasedName.
String	gluegenRuntimePackage() Returns the package in which the generated glue code expects to find its run-time helper classes (Buffers, Platform, StructAccessor).
String	implClassName() Returns the implementation class name parsed from the configuration file.
List<String>	implementedInterfaces(String className) Returns a List of Strings indicating the interfaces the passed class should declare it implements.
String	implPackageName() Returns the implementation package name parsed from the configuration file.
List<String>	imports() Returns the list of imports that should be emitted at the top of each .java file.
boolean	isForceUsingNIOOnly4All()
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.
List<String>	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.
List<String>	javadocForMethod(String methodName)
List<String>	javaEpilogueForMethod(MethodBinding binding, boolean forImplementingMethodCall, boolean eraseBufferAndArrayTypes) Returns a list of Strings which should be emitted as an epilogue to the body for the Java-side glue code for the given method.
String	javaOutputDir() Returns the Java code output directory parsed from the configuration file.
List<String>	javaPrologueForMethod(MethodBinding binding, boolean forImplementingMethodCall, boolean eraseBufferAndArrayTypes) Returns a list of Strings which should be emitted as a prologue to the body for the Java-side glue code for the given method.
boolean	manuallyImplement(String functionName) Returns true if the glue code for the given function will be manually implemented by the end user.
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.
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	readAccessControl(StringTokenizer tok, String filename, int lineNo)
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	readExtendedIntfImplSymbols(StringTokenizer tok, String filename, int lineNo, boolean forInterface, boolean forImplementation, boolean onlyList)
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	readJavaPrologueOrEpilogue(StringTokenizer tok, String filename, int lineNo, boolean prologue)
protected void	readManuallyImplement(StringTokenizer tok, String filename, int lineNo)
protected void	readMethodJavadoc(StringTokenizer tok, String filename, int lineNo)
protected void	readOpaque(StringTokenizer tok, String filename, int lineNo)
protected void	readParentClass(StringTokenizer tok, String filename, int lineNo)
protected void	readRangeCheck(StringTokenizer tok, String filename, int lineNo, boolean inBytes)
protected void	readRenameJavaSymbol(StringTokenizer tok, String filename, int lineNo)
protected void	readRenameJavaType(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 void	readReturnValueCapacity(StringTokenizer tok, String filename, int lineNo)
protected void	readReturnValueLength(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	readUnignore(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	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	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	runtimeExceptionType() Returns the kind of exception to raise if run-time checks fail in the generated code.
void	setOutputRootDir(String s)
boolean	shouldIgnoreInImpl(String symbol)
boolean	shouldIgnoreInInterface(String symbol) Returns true if this #define, function, struct, or field within a struct should be ignored during glue code generation.
protected static boolean	startsWithDescriptor(String s)
List<Integer>	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)
boolean	structsOnly()
boolean	tagNativeBinding() Returns whether the comment of a native method binding should include a @native tag.
List<String>	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<String>	temporaryCVariableDeclarations(String functionName) Returns a List of Strings of expressions declaring temporary C variables in the glue code for the specified function.
TypeInfo	typeInfo(Type type, TypeDictionary typedefDictionary) If this type should be considered opaque, returns the TypeInfo describing the replacement type.
String	unsupportedExceptionType() Returns the kind of exception to raise if run-time checks fail in the generated code.
boolean	useNIODirectOnly(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	useNIOOnly(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.

Methods inherited from class java.lang.Object

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

Field Detail

DEBUG_IGNORES

public static final boolean DEBUG_IGNORES

DEBUG_RENAMES

public static final boolean DEBUG_RENAMES

LOG

protected static final Logger LOG

NEWLINE

public static String NEWLINE

Constructor Detail

JavaConfiguration

public JavaConfiguration()

Method Detail

read

public final void read(String filename)
                throws IOException

Reads the configuration file.

Parameters:

filename - path to file that should be read

Throws:

IOException

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.

Throws:

IOException

setOutputRootDir

public void setOutputRootDir(String s)

packageName

public String packageName()

Returns the package name parsed from the configuration file.

implPackageName

public String implPackageName()

Returns the implementation package name parsed from the configuration file.

className

public String className()

Returns the class name parsed from the configuration file.

implClassName

public String implClassName()

Returns the implementation class name parsed from the configuration file.

structsOnly

public boolean structsOnly()

javaOutputDir

public String javaOutputDir()

Returns the Java code output directory parsed from the configuration file.

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.

tagNativeBinding

public boolean tagNativeBinding()

Returns whether the comment of a native method binding should include a @native tag.

emissionStyle

public JavaEmitter.EmissionStyle emissionStyle()

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

accessControl

public JavaEmitter.MethodAccess accessControl(String methodName)

Returns the access control for the emitted Java method. Returns one of JavaEmitter.ACC_PUBLIC, JavaEmitter.ACC_PROTECTED, JavaEmitter.ACC_PRIVATE, or JavaEmitter.ACC_PACKAGE_PRIVATE.

gluegenRuntimePackage

public String gluegenRuntimePackage()

Returns the package in which the generated glue code expects to find its run-time helper classes (Buffers, Platform, StructAccessor). Defaults to "com.jogamp.gluegen.runtime".

runtimeExceptionType

public String runtimeExceptionType()

Returns the kind of exception to raise if run-time checks fail in the generated code.

unsupportedExceptionType

public String unsupportedExceptionType()

Returns the kind of exception to raise if run-time checks fail in the generated code.

imports

public List<String> imports()

Returns the list of imports that should be emitted at the top of each .java file.

typeInfo

public TypeInfo typeInfo(Type type,
                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.

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.

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.

stringArguments

public List<Integer> 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.

isForceUsingNIOOnly4All

public boolean isForceUsingNIOOnly4All()

addUseNIOOnly

public void addUseNIOOnly(String fname)

useNIOOnly

public boolean useNIOOnly(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. NIO only still allows usage of array backed not direct Buffers.

addUseNIODirectOnly

public void addUseNIODirectOnly(String fname)

useNIODirectOnly

public boolean useNIODirectOnly(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. NIO direct only does only allow direct Buffers. Implies useNIOOnly !

manuallyImplement

public boolean manuallyImplement(String functionName)

Returns true if the glue code for the given function will be manually implemented by the end user.

customJavaCodeForClass

public List<String> 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.

javadocForMethod

public List<String> javadocForMethod(String methodName)

javadocForClass

public List<String> 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.

packageForStruct

public String packageForStruct(String structName)

Returns the package into which to place the glue code for accessing the specified struct. Defaults to emitting into the regular package (i.e., the result of packageName).

customCCode

public List<String> customCCode()

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

forcedStructs

public List<String> forcedStructs()

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

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.

temporaryCVariableDeclarations

public List<String> temporaryCVariableDeclarations(String functionName)

Returns a List of Strings of expressions declaring temporary C variables in the glue code for the specified function.

temporaryCVariableAssignments

public List<String> temporaryCVariableAssignments(String functionName)

Returns a List of Strings of expressions containing assignments to temporary C variables in the glue code for the specified function.

extendedInterfaces

public List<String> 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.

implementedInterfaces

public List<String> 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.

extendedParentClass

public String extendedParentClass(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.

dumpIgnoresOnce

public void dumpIgnoresOnce()

dumpIgnores

public void dumpIgnores()

dumpRenamesOnce

public void dumpRenamesOnce()

dumpRenames

public void dumpRenames()

shouldIgnoreInInterface

public boolean shouldIgnoreInInterface(String symbol)

Returns true if this #define, function, struct, or field within a struct should be ignored during glue code generation.

shouldIgnoreInImpl

public boolean shouldIgnoreInImpl(String symbol)

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.

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.

getJavaSymbolRename

public String getJavaSymbolRename(String origName)

Returns a replacement name for this function or definition which should be used as the Java name for the bound method or constant. If a function, it still calls the originally-named C function under the hood. Returns null if this symbol has not been explicitly renamed.

getRenamedJavaSymbols

public Set<String> getRenamedJavaSymbols(String aliasedName)

Returns a set of replaced names to the given aliasedName.

addJavaSymbolRename

public void addJavaSymbolRename(String origName,
                       String newName)

Programmatically adds a rename directive for the given symbol.

allStatic

public boolean allStatic()

Returns true if the emission style is AllStatic.

emitInterface

public boolean emitInterface()

Returns true if an interface should be emitted during glue code generation.

emitImpl

public boolean emitImpl()

Returns true if an implementing class should be emitted during glue code generation.

javaPrologueForMethod

public List<String> javaPrologueForMethod(MethodBinding binding,
                                 boolean forImplementingMethodCall,
                                 boolean eraseBufferAndArrayTypes)

Returns a list of Strings which should be emitted as a prologue to the body for the Java-side glue code for the given method. Returns null if no prologue was specified.

javaEpilogueForMethod

public List<String> javaEpilogueForMethod(MethodBinding binding,
                                 boolean forImplementingMethodCall,
                                 boolean eraseBufferAndArrayTypes)

Returns a list of Strings which should be emitted as an epilogue to the body for the Java-side glue code for the given method. Returns null if no epilogue was specified.

dispatch

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

Throws:

IOException

readString

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

readBoolean

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

stringToPrimitiveType

protected Class<?> stringToPrimitiveType(String type)
                                  throws ClassNotFoundException

Throws:

ClassNotFoundException

readAccessControl

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

readOpaque

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

readReturnsString

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

readReturnedArrayLength

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

readExtendedIntfImplSymbols

protected void readExtendedIntfImplSymbols(StringTokenizer tok,
                               String filename,
                               int lineNo,
                               boolean forInterface,
                               boolean forImplementation,
                               boolean onlyList)

readIgnore

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

readUnignore

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

readIgnoreNot

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

readUnimplemented

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

readIgnoreField

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

readManuallyImplement

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

readCustomJavaCode

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

addCustomJavaCode

protected void addCustomJavaCode(String className,
                     String code)

readCustomCCode

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

readMethodJavadoc

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

addMethodJavadoc

protected void addMethodJavadoc(String methodName,
                    String code)

readClassJavadoc

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

addClassJavadoc

protected void addClassJavadoc(String className,
                   String code)

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);
 

readStructPackage

protected void readStructPackage(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)

readTemporaryCVariableDeclaration

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

readTemporaryCVariableAssignment

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

doInclude

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

Throws:

IOException

doIncludeAs

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

Throws:

IOException

readExtend

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

readImplements

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

readParentClass

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

readRenameJavaType

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

readRenameJavaSymbol

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

readJavaPrologueOrEpilogue

protected void readJavaPrologueOrEpilogue(StringTokenizer tok,
                              String filename,
                              int lineNo,
                              boolean prologue)

addJavaPrologueOrEpilogue

protected void addJavaPrologueOrEpilogue(String methodName,
                             String code,
                             boolean prologue)

readRangeCheck

protected void readRangeCheck(StringTokenizer tok,
                  String filename,
                  int lineNo,
                  boolean inBytes)

parseTypeInfo

protected static TypeInfo parseTypeInfo(String cType,
                     JavaType javaType)

addTypeInfo

protected void addTypeInfo(TypeInfo info)

startsWithDescriptor

protected static boolean startsWithDescriptor(String s)