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.

      • returnedArrayLength

        public String returnedArrayLength​(String functionName)
        Returns a MessageFormat string of the Java expression calculating the number of elements in the returned array from the specified function name. The literal 1 indicates a 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)!

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

      • manualStaticInitCall

        public boolean manualStaticInitCall​(String clazzName)
        Returns true if the static initialization java code calling initializeImpl() for the given class will be manually implemented by the end user as requested via configuration directive ManualStaticInitCall 'class-name'.

      • forceStaticInitCode

        public boolean forceStaticInitCode​(String clazzName)
        Returns true if the static initialization java code implementing initializeImpl() and the native code implementing: 
           static jobject JVMUtil_NewDirectByteBufferCopy(JNIEnv *env, void * source_address, jlong capacity);
        for the given class will be included in the generated code, always, as requested via configuration directive ForceStaticInitCode 'class-name'.

        If case above code has been generated, static class initialization is generated to call initializeImpl(), see manualStaticInitCall(String).

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

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

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

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

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

      • readManualStaticInitCall

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

      • readForceStaticInitCode

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

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