Package com.jogamp.gluegen

Class JavaConfiguration

  • Direct Known Subclasses:
    ProcAddressConfiguration
    public class JavaConfiguration
extends Object
    Parses and provides access to the contents of .cfg files for the JavaEmitter.

    • 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.

      • relaxedEqualSemanticsTest

        public boolean relaxedEqualSemanticsTest()
        Returns whether TypeConfig.SemanticEqualityOp#equalSemantics(TypeConfig.SemanticEqualityOp) shall attempt to perform a relaxed semantic equality test, e.g. skip the const and volatile qualifier - or not.

      • emissionStyle

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

      • accessControl

        public JavaEmitter.MethodAccess accessControl​(String name)
        Returns the access control for the given method-name or fully qualified class-name.

      • 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.

      • canonicalNameOpaque

        public TypeInfo canonicalNameOpaque​(String canonicalName)
        If the given canonicalName should be considered opaque, returns the TypeInfo describing the replacement type.

        Returns null if this type should not be considered opaque.

        If symbol references a struct fields, see canonicalStructFieldSymbol(String, String), it describes field's array-length or element-count referenced by a pointer.

      • typeInfo

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

      • returnsString

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

      • returnsStringOnly

        public boolean returnsStringOnly​(String functionName)
        Indicates whether the given function (which returns a char* in C) should be translated as returning a java.lang.String only. Excluding other variants for struct field access.

      • returnedArrayLength

        public String returnedArrayLength​(String symbol)
        Returns a MessageFormat string of the Java expression calculating the number of elements in the returned array from the specified function name or struct-field array-size. The literal 1 indicates a constant single object.

        If symbol references a struct fields, see canonicalStructFieldSymbol(String, String), it describes field's array-length or element-count referenced by a pointer.

        In case of struct fields, this array length will also be used for the native C function, i.e. multiplied w/ sizeof(C-Type) and passed down to native code, if not overriden by either returnValueCapacity(String) or returnValueLength(String)!

      • maxOneElement

        public boolean maxOneElement​(String symbol)
        Indicates whether the given symbol covers no or one single object. This is useful for struct-field pointer, indicating a null value holding no object or at most referincing memory for one single object.

      • stringArguments

        public List<Integer> stringArguments​(AliasedSymbol symbol)
        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 alias symbol.

      • pascalStringArgument

        public List<JavaConfiguration.PascalStringIdx> pascalStringArgument​(AliasedSymbol symbol)
        Returns a list of PascalStringIdx which are tuples of indices of int len, const char* arguments that should be converted to Strings. Returns null if there are no such hints for the given function alias symbol.

      • pascalStringLengthIndex

        public int pascalStringLengthIndex​(AliasedSymbol symbol,
                                   int valueIndex)

      • 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 !

      • 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.

      • customJNICodeForClass

        public List<String> customJNICodeForClass​(String className)
        Returns a list of Strings containing user-implemented JNI 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.

      • returnStructMachineDataInfoIndex

        public String returnStructMachineDataInfoIndex​(String structName)
        Returns a MessageFormat string of the Java code defining mdIdx, i.e. the index of the static MachineDescriptor index for structs.

        If undefined, code generation uses the default expression: 

             private static final int mdIdx = MachineDataInfoRuntime.getStatic().ordinal();

      • 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.

        If symbol references a struct fields, see canonicalStructFieldSymbol(String, String), it describes field's array-length or element-count referenced by a pointer.

      • returnValueLength

        public String returnValueLength​(String symbol)
        Returns a MessageFormat string of the C expression calculating the length of the array being returned from a native method.

        If symbol references a struct fields, see canonicalStructFieldSymbol(String, String), it describes field's array-length or element-count referenced by a pointer.

      • 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.

      • logIgnoresOnce

        public void logIgnoresOnce()

      • logIgnores

        public void logIgnores()

      • logRenamesOnce

        public void logRenamesOnce()

      • logRenames

        public void logRenames()

      • oneInMap

        public static <K,​V> V oneInMap​(Map<K,​V> map,
                                     Set<K> symbols)

      • oneInSet

        public static <K> boolean oneInSet​(Set<K> set1,
                                   Set<K> set2)

      • canonicalStructFieldSymbol

        public static String canonicalStructFieldSymbol​(String structName,
                                                String fieldName)
        Returns the canonical configuration name for a struct field name, i.e. 'struct-name'.'field-name'

      • immutableAccess

        public final boolean immutableAccess​(AliasedSymbol symbol)
        Returns true if the glue code for the given aliased symbol shall produce code for immutable access only.

        This is implemented for whole struct-type symbols or struct-field names, where no setter methods will be produced if marked immutable.

      • immutableAccess

        public final boolean immutableAccess​(String symbol)
        Returns true if the glue code for the given symbol shall produce code for immutable access only.

        This is implemented for whole struct-type symbols or struct-field names, where no setter methods will be produced if marked immutable.

      • getDelegatedImplementation

        public String getDelegatedImplementation​(AliasedSymbol symbol)
        Returns the RENAMED-IMPL-SYMBOL if the implementation of the glue code of the given function shall be manually delegated by the end user.

        DelegateImplementation <ORIG-SYMBOL> <RENAMED-IMPL-SYMBOL>

        The interface is emitted unchanged.

        The Java and native-code implementation is renamed to RENAMED-IMPL-SYMBOL. The user's manual implementation of ORIG-SYMBOL may delegate to RENAMED-IMPL-SYMBOL.

        If symbol references a struct field or method, see canonicalStructFieldSymbol(String, String), it describes field's array-length or element-count referenced by a pointer.

      • getOpaqueReturnType

        public JavaType getOpaqueReturnType​(AliasedSymbol symbol)
        Returns the opaque JavaType for the given function AliasedSymbol or null if not opaque.

        ReturnsOpaque <Primitive Java Type> <Function Name>

      • shouldIgnoreInInterface

        public boolean shouldIgnoreInInterface​(AliasedSymbol symbol)
        Returns true if this aliased symbol should be ignored during glue code generation of interfaces and implementation.

        Both, the current-name and all aliases shall be considered.

        Implementation calls shouldIgnoreInInterface_Int(AliasedSymbol) and overriding implementations shall ensure its being called as well!

        Parameters:
        symbol - the symbolic aliased name to check for exclusion

      • shouldIgnoreInInterface_Int

        protected final boolean shouldIgnoreInInterface_Int​(AliasedSymbol symbol)

      • shouldIgnoreInImpl

        public boolean shouldIgnoreInImpl​(AliasedSymbol symbol)
        Returns true if this aliased symbol should be ignored during glue code generation of implementation only.

        Both, the current-name and all aliases shall be considered.

        Implementation calls shouldIgnoreInImpl_Int(AliasedSymbol) and overriding implementations shall ensure its being called as well!

        Parameters:
        symbol - the symbolic aliased name to check for exclusion

      • shouldIgnoreInImpl_Int

        protected final boolean shouldIgnoreInImpl_Int​(AliasedSymbol symbol)

      • isUnimplemented

        public boolean isUnimplemented​(AliasedSymbol 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.

      • getAliasedDocNames

        public Set<String> getAliasedDocNames​(AliasedSymbol symbol)
        Return a set of aliased-name for comment in docs.

        This is usually AliasedSymbol.addAliasedName(String), however an implementation may choose otherwise.

        Parameters:
        symbol - the aliased symbol to retrieve the aliases
        Returns:
        set of aliased-names or null.

      • 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.

      • addDelegateImplementation

        public void addDelegateImplementation​(String origName,
                                      String renamedImpl)
        Programmatically adds a delegate implementation 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.

      • readAccessControl

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

      • readReturnsOpaque

        protected void readReturnsOpaque​(StringTokenizer tok,
                                 String filename,
                                 int lineNo)

      • readReturnsString

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

      • readReturnsStringOnly

        protected void readReturnsStringOnly​(StringTokenizer tok,
                                     String filename,
                                     int lineNo)

      • readReturnedArrayLength

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

      • readMaxOneElement

        protected void readMaxOneElement​(StringTokenizer tok,
                                 String filename,
                                 int lineNo)

      • readJavaCallbackDef

        protected void readJavaCallbackDef​(StringTokenizer tok,
                                   String filename,
                                   int lineNo)

      • readJavaCallbackKey

        protected void readJavaCallbackKey​(StringTokenizer tok,
                                   String filename,
                                   int lineNo)

      • readExtendedIntfImplSymbols

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

      • readUnimplemented

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

      • readIgnoreField

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

      • readImmutableAccess

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

      • readCustomJNICode

        protected void readCustomJNICode​(StringTokenizer tok,
                                 String filename,
                                 int lineNo)

      • addCustomJNICode

        protected void addCustomJNICode​(String className,
                                String code)

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

      • readArgumentIsPascalString

        protected void readArgumentIsPascalString​(StringTokenizer tok,
                                          String filename,
                                          int lineNo)

      • readStructPackage

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

      • readStructMachineDataInfoIndex

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

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

      • readDelegateImplementation

        public void readDelegateImplementation​(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)

      • addTypeInfo

        protected void addTypeInfo​(TypeInfo info)

      • startsWithDescriptor

        protected static boolean startsWithDescriptor​(String s)