GlueGen: src/java/com/jogamp/common/os/DynamicLibraryBundleInfo.java Source File

GlueGen v2.6.0 GlueGen, Native Binding Generator for Java™ (public API).

DynamicLibraryBundleInfo.java
Go to the documentation of this file.
1/**
2 * Copyright 2010-2023 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28
29package com.jogamp.common.os;
30
31import java.util.List;
32
33import com.jogamp.common.util.RunnableExecutor;
34
35
36 public interface DynamicLibraryBundleInfo {
37 public static final boolean DEBUG = DynamicLibraryBundle.DEBUG;
38
39 /**
40 * Returns {@code true} if tool libraries shall be searched in the system path <i>(default)</i>, otherwise {@code false}.
41 * @since 2.4.0
42 */
43 public boolean searchToolLibInSystemPath();
44
45 /**
46 * Returns {@code true} if system path shall be searched <i>first</i> <i>(default)</i>, rather than searching it last.
47 * <p>
48 * If {@link #searchToolLibInSystemPath()} is {@code false} the return value is ignored.
49 * </p>
50 * @since 2.4.0
51 */
52 public boolean searchToolLibSystemPathFirst();
53
54 /**
55 * If a {@link SecurityManager} is installed, user needs link permissions
56 * for the named libraries.
57 *
58 * @return a list of Tool library names or alternative library name lists.<br>
59 * <ul>
60 * <li>GL/GLU example Unix: [ [ "libGL.so.1", "libGL.so", "GL" ], [ "libGLU.so", "GLU" ] ] </li>
61 * <li>GL/GLU example Windows: [ "OpenGL32", "GLU32" ] </li>
62 * <li>Cg/CgGL example: [ [ "libCg.so", "Cg" ], [ "libCgGL.so", "CgGL" ] ] </li>
63 * </pre>
64 */
65 public List<List<String>> getToolLibNames();
66
67 /**
68 * Returns optional list of optional symbol names per {@link #getToolLibNames()} in same order for an OS which requires the symbol's address to retrieve the path of the containing library.
69 */
70 public List<String> getSymbolForToolLibPath();
71
72 /**
73 * If a {@link SecurityManager} is installed, user needs link permissions
74 * for the named libraries.
75 *
76 * @return a list of Glue library names.<br>
77 * <ul>
78 * <li>GL: [ "nativewindow_x11", "jogl_gl2es12", "jogl_desktop" ] </li>
79 * <li>NEWT: [ "nativewindow_x11", "newt" ] </li>
80 * <li>Cg: [ "nativewindow_x11", "jogl_cg" ] </li>
81 * </ul><br>
82 * Only the last entry is crucial, ie all other are optional preload dependencies and may generate errors,
83 * which are ignored.
84 */
85 public List<String> getGlueLibNames();
86
87 /**
88 * May return the native libraries <pre>GetProcAddressFunc</pre> names, the first found function is being used.<br>
89 * This could be eg: <pre> glXGetProcAddressARB, glXGetProcAddressARB </pre>.<br>
90 * If your Tool does not has this facility, just return null.
91 * @see #toolGetProcAddress(long, String)
92 */
93 public List<String> getToolGetProcAddressFuncNameList() ;
94
95 /**
96 * May implement the lookup function using the Tools facility.<br>
97 * The actual function pointer is provided to allow proper bootstrapping of the ProcAddressTable,
98 * using one of the provided function names by {@link #getToolGetProcAddressFuncNameList()}.<br>
99 */
100 public long toolGetProcAddress(long toolGetProcAddressHandle, String funcName);
101
102 /**
103 * @param funcName
104 * @return true if {@link #toolGetProcAddress(long, String)} shall be tried before
105 * the system loader for the given function lookup. Otherwise false.
106 * Default is <b>true</b>.
107 */
108 public boolean useToolGetProcAdressFirst(String funcName);
109
110 /** @return true if the native library symbols shall be made available for symbol resolution of subsequently loaded libraries. */
111 public boolean shallLinkGlobal();
112
113 /**
114 * If method returns <code>true</code> <i>and</i> if a {@link SecurityManager} is installed, user needs link permissions
115 * for <b>all</b> libraries, i.e. for <code>new RuntimePermission("loadLibrary.*");</code>!
116 *
117 * @return true if the dynamic symbol lookup shall happen system wide, over all loaded libraries.
118 * Otherwise only the loaded native libraries are used for lookup, which shall be the default.
119 */
120 public boolean shallLookupGlobal();
121
122 /**
123 * Returns a suitable {@link RunnableExecutor} implementation, which is being used
124 * to load the <code>tool</code> and <code>glue</code> native libraries.
125 * <p>
126 * This allows the generic {@link DynamicLibraryBundle} implementation to
127 * load the native libraries on a designated thread.
128 * </p>
129 * <p>
130 * An implementation may return {@link DynamicLibraryBundle#getDefaultRunnableExecutor()}.
131 * </p>
132 */
133 public RunnableExecutor getLibLoaderExecutor();
134}
135
136
com.jogamp.common.os.DynamicLibraryBundle
Provides bundling of:
Definition: DynamicLibraryBundle.java:61
com.jogamp.common.os.DynamicLibraryBundleInfo
Definition: DynamicLibraryBundleInfo.java:36
com.jogamp.common.os.DynamicLibraryBundleInfo.useToolGetProcAdressFirst
boolean useToolGetProcAdressFirst(String funcName)
com.jogamp.common.os.DynamicLibraryBundleInfo.toolGetProcAddress
long toolGetProcAddress(long toolGetProcAddressHandle, String funcName)
May implement the lookup function using the Tools facility.
com.jogamp.common.os.DynamicLibraryBundleInfo.getToolLibNames
List< List< String > > getToolLibNames()
If a SecurityManager is installed, user needs link permissions for the named libraries.
com.jogamp.common.os.DynamicLibraryBundleInfo.searchToolLibInSystemPath
boolean searchToolLibInSystemPath()
Returns true if tool libraries shall be searched in the system path (default), otherwise false.
com.jogamp.common.os.DynamicLibraryBundleInfo.shallLookupGlobal
boolean shallLookupGlobal()
If method returns true and if a SecurityManager is installed, user needs link permissions for all lib...
com.jogamp.common.os.DynamicLibraryBundleInfo.getSymbolForToolLibPath
List< String > getSymbolForToolLibPath()
Returns optional list of optional symbol names per getToolLibNames() in same order for an OS which re...
com.jogamp.common.os.DynamicLibraryBundleInfo.getGlueLibNames
List< String > getGlueLibNames()
If a SecurityManager is installed, user needs link permissions for the named libraries.
com.jogamp.common.os.DynamicLibraryBundleInfo.getLibLoaderExecutor
RunnableExecutor getLibLoaderExecutor()
Returns a suitable RunnableExecutor implementation, which is being used to load the tool and glue nat...
com.jogamp.common.os.DynamicLibraryBundleInfo.DEBUG
static final boolean DEBUG
Definition: DynamicLibraryBundleInfo.java:37
com.jogamp.common.os.DynamicLibraryBundleInfo.shallLinkGlobal
boolean shallLinkGlobal()
com.jogamp.common.os.DynamicLibraryBundleInfo.getToolGetProcAddressFuncNameList
List< String > getToolGetProcAddressFuncNameList()
May return the native libraries.
com.jogamp.common.os.DynamicLibraryBundleInfo.searchToolLibSystemPathFirst
boolean searchToolLibSystemPathFirst()
Returns true if system path shall be searched first (default), rather than searching it last.
com.jogamp.common.os.DynamicLookupHelper.DEBUG
static final boolean DEBUG
Definition: DynamicLookupHelper.java:50
com.jogamp.common.util.RunnableExecutor
Definition: RunnableExecutor.java:30