GlueGen v2.6.0-rc-20250712
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
36public 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 */
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 */
134}
135
136
boolean useToolGetProcAdressFirst(String funcName)
long toolGetProcAddress(long toolGetProcAddressHandle, String funcName)
May implement the lookup function using the Tools facility.
List< List< String > > getToolLibNames()
If a SecurityManager is installed, user needs link permissions for the named libraries.
boolean searchToolLibInSystemPath()
Returns true if tool libraries shall be searched in the system path (default), otherwise false.
boolean shallLookupGlobal()
If method returns true and if a SecurityManager is installed, user needs link permissions for all lib...
List< String > getSymbolForToolLibPath()
Returns optional list of optional symbol names per getToolLibNames() in same order for an OS which re...
List< String > getGlueLibNames()
If a SecurityManager is installed, user needs link permissions for the named libraries.
RunnableExecutor getLibLoaderExecutor()
Returns a suitable RunnableExecutor implementation, which is being used to load the tool and glue nat...
List< String > getToolGetProcAddressFuncNameList()
May return the native libraries.
boolean searchToolLibSystemPathFirst()
Returns true if system path shall be searched first (default), rather than searching it last.