public final class JCOBridge extends JCHandler
This class manages the full lifecycle of the CLR runtime hosted inside the JVM process: initialization, assembly loading, type resolution, object instantiation, and global object registration. It also provides factory methods for AWT UI integration and diagnostic logging.
Typical usage from a JVM-hosted application:
Initialize(String[]) (or Initialize()) to load the native bridge
and start the CLR runtime.CreateNew() to obtain a JCOBridge instance.AddReference(java.lang.String), GetType(java.lang.String), NewObject(java.lang.String, java.lang.Object...),
etc.) to interact with CLR assemblies and types.Configuration can be provided in three ways, evaluated in this order of precedence:
setNativePath(java.lang.String), setLicensePath(java.lang.String), etc.).Initialize(String[]).JCOBRIDGE_NativePath, JCOBRIDGE_LicensePath).See also: JCOReflector for usage examples.
| Modifier and Type | Method and Description |
|---|---|
void |
AddPath(String path)
Adds a directory to the CLR assembly search path.
|
JCAssembly |
AddReference(String assemblyName)
Loads a CLR assembly by name and returns a handle to it.
|
static IJCGraphicContainer |
CreateContainer(Component comp)
Creates an
IJCGraphicContainer wrapping the given AWT component, enabling it to
be embedded in a CLR UI host (e.g. |
static IJCGraphicContainer |
CreateContainer(String className)
Creates an
IJCGraphicContainer from a class name. |
static JCOBridge |
CreateNew()
Creates and returns a new
JCOBridge instance backed by a fresh CLR context. |
static Object |
GetCLRGlobal(String key)
Retrieves a previously registered CLR global object by key.
|
static String |
getCLRRID()
Returns the .NET Runtime Identifier (RID) override used to select the correct
CoreCLR host activator library.
|
JCControl |
GetControl(String type)
Returns a
JCControl handle to a graphical CLR object, suitable for embedding
CLR controls (WinForms, WPF) into an AWT/Swing host. |
static Boolean |
getCoreCLREnableDesktop()
Returns
true if Microsoft.WindowsDesktop.App hosting is enabled. |
static String |
getCoreCLRVersion()
Returns the target .NET major version used to select the hosting framework.
|
JCEnum |
GetEnum(String type)
Resolves a CLR enum type by its fully qualified name and returns a handle to it.
|
static String[] |
getFilteredArgs()
Returns the command-line arguments that were not consumed by JCOBridge during
Initialize(String[]). |
static boolean |
getGlobalize()
Returns whether the hosted .NET Core instance will be globalized.
|
JCJControl |
GetJControl(String type)
Returns a
JCJControl handle to a graphical CLR object, suitable for embedding
CLR controls into a Swing host via a dedicated Swing-aware wrapper. |
static Object |
GetJVMGlobal(String key)
Retrieves a previously registered JVM global object by key.
|
static String |
getLicensePath()
Returns the path where the JCOBridge license file is located.
|
static String |
getNativePath()
Returns the path from which the JCOBridge native library is loaded.
|
static String |
getScopedOn()
Returns the scoped-on value used for license validation.
|
static String |
getScopedOnVersion()
Returns the scoped-on version used for license validation.
|
JCType |
GetType(String type)
Resolves a CLR type by its fully qualified name and returns a handle to it.
|
static void |
Initialize()
Initializes the JCOBridge runtime with default parameters.
|
static void |
Initialize(String[] args)
Initializes the JCOBridge runtime, consuming JCOBridge-specific arguments from
args and storing the remainder in filteredArgs. |
static void |
InitializeFromRemote(String J2CBridgeCanonicalPath,
String licencePath,
String scopedOn,
String scopedOnVersion,
boolean globalize)
Initializes the JCOBridge native bridge from a CLR-hosted process.
|
static Boolean |
isCLRHostingProcess()
Returns
true if the hosting process is a CLR (i.e. |
static Boolean |
isNET10HostingProcess()
Returns whether the hosting CLR is .NET 10.
|
static Boolean |
isNET6HostingProcess()
Returns whether the hosting CLR is .NET 6.
|
static Boolean |
isNET8HostingProcess()
Returns whether the hosting CLR is .NET 8.
|
static Boolean |
isNET9HostingProcess()
Returns whether the hosting CLR is .NET 9.
|
static Boolean |
isNETFrameworkHostingProcess()
Returns whether the hosting CLR is .NET Framework.
|
static Boolean |
isNETHostingProcess(Integer netVersion)
Returns whether the hosting CLR is the specified major .NET version.
|
static void |
Load()
Loads the CLR/JVM wrapper library for Windows (
J2CBridge_x64.dll or
J2CBridge_x86.dll), resolved relative to the JCOBridge JAR location. |
static void |
LoadWrapper(String libraryName)
Loads the CLR/JVM wrapper library from the given absolute path.
|
Object |
NewObject(JCType type,
Object... params)
Creates a new instance of the CLR type represented by the given
JCType handle,
passing optional constructor arguments. |
Object |
NewObject(String type,
Object... params)
Creates a new instance of the specified CLR type, passing optional constructor arguments.
|
void |
RegisterEventLog(IJCEventLog logger)
Registers a diagnostic logger with the CLR context.
|
static void |
RegisterJVMGlobal(String key,
Object obj)
Registers a JVM object in the global shared map, making it accessible from the CLR side
by key.
|
static void |
setCLRRID(String rid)
Sets the .NET Runtime Identifier (RID) override.
|
static void |
setCoreCLREnableDesktop(Boolean value)
Enables or disables
Microsoft.WindowsDesktop.App hosting. |
static void |
setCoreCLRVersion(String clrApp)
Sets the target .NET major version.
|
static void |
setGlobalize(boolean globalize)
Controls whether the hosted .NET Core instance will be globalized.
|
static void |
setLicensePath(String path)
Sets the path where the JCOBridge license file is located.
|
static void |
setNativePath(String path)
Sets the path from which the JCOBridge native library is loaded.
|
static void |
setScopedOn(String value)
Sets the scoped-on value for license validation.
|
static void |
setScopedOnVersion(String value)
Sets the scoped-on version for license validation.
|
static void |
SetWrapperPath(String path)
Sets the path to the CLR/JVM wrapper library.
|
static void |
UnregisterJVMGlobal(String key)
Unregisters a JVM object from the global shared map, removing it from both the native
registry and
registeredObjectsMap, allowing it to be collected by the GC. |
getReferencepublic static String[] getFilteredArgs()
Initialize(String[]). These are the arguments that should be forwarded
to the application.null if Initialize(String[])
has not been called yet.public static String getNativePath()
JCOBridge.jar, overridable via
setNativePath(java.lang.String) or the JCOBRIDGE_NativePath environment variable.public static void setNativePath(String path)
IllegalArgumentException otherwise.
Must be called before Initialize().path - the directory path containing the native bridge libraries.IllegalArgumentException - if path does not refer to an existing directory.public static String getLicensePath()
setLicensePath(java.lang.String) or
the JCOBRIDGE_LicensePath environment variable.
HTTP/HTTPS URLs are also accepted.public static void setLicensePath(String path)
IllegalArgumentException otherwise.
Must be called before Initialize().path - the directory path containing the license file.IllegalArgumentException - if path does not refer to an existing directory.public static String getCLRRID()
public static void setCLRRID(String rid)
Initialize().rid - the RID string (e.g. "linux-x64", "win-x64").public static String getCoreCLRVersion()
"8" (default), "9", and "10".public static void setCoreCLRVersion(String clrApp)
"8", "9",
and "10". Throws IllegalArgumentException for any other value.
Must be called before Initialize().clrApp - the .NET major version string.IllegalArgumentException - if clrApp is not a recognized version.public static Boolean getCoreCLREnableDesktop()
true if Microsoft.WindowsDesktop.App hosting is enabled.
This option is only valid on Windows — attempting to initialize with it on Linux
or macOS will throw a JCException.true if desktop hosting is requested.public static void setCoreCLREnableDesktop(Boolean value)
Microsoft.WindowsDesktop.App hosting.
Must be called before Initialize(). Only valid on Windows.value - true to enable desktop features.public static String getScopedOn()
public static void setScopedOn(String value)
Initialize().value - the scoped-on value.public static String getScopedOnVersion()
public static void setScopedOnVersion(String value)
Initialize().value - the scoped-on version.public static boolean getGlobalize()
true.true if the CLR instance will be globalized.public static void setGlobalize(boolean globalize)
false to run in invariant globalization mode, which reduces
resource usage and startup time but disables culture-sensitive operations.
Must be called before Initialize().globalize - false to disable globalization.public static Boolean isCLRHostingProcess()
true if the hosting process is a CLR (i.e. JCOBridge was started
from .NET rather than from a JVM main). Detected via the jcobridge.started.from.clr
system property set by the native bridge at startup.true if the current process was started by a CLR host.public static Boolean isNETFrameworkHostingProcess()
null if the host is a JVM; true if the host is .NET Framework;
false if the host is .NET (Core).public static Boolean isNETHostingProcess(Integer netVersion)
jcobridge.started.from.clr
system property starts with the given version number string.netVersion - the major .NET version to check (e.g. 8, 10).null if the host is a JVM; true if the host is the specified
.NET version; false otherwise.public static Boolean isNET6HostingProcess()
null if the host is a JVM; true if .NET 6; false otherwise.public static Boolean isNET8HostingProcess()
null if the host is a JVM; true if .NET 8; false otherwise.public static Boolean isNET9HostingProcess()
null if the host is a JVM; true if .NET 9; false otherwise.public static Boolean isNET10HostingProcess()
null if the host is a JVM; true if .NET 10; false otherwise.public static void SetWrapperPath(String path)
Internal use only. Called by the JCOBridge infrastructure before
CreateNew() to point the instance constructor at the correct wrapper.
path - the absolute or relative path to the wrapper library.public static void Load()
throws IOException
J2CBridge_x64.dll or
J2CBridge_x86.dll), resolved relative to the JCOBridge JAR location.
Internal use only. Called by the CLR host when JCOBridge is started from .NET Framework.
IOException - if the library path cannot be resolved or the library cannot be loaded.public static void LoadWrapper(String libraryName) throws IOException
Internal use only. Called by the CLR host when the library path is known at the point of invocation (e.g. when JCOBridge is started from .NET Core).
libraryName - the absolute path to the native wrapper library.IOException - if the library cannot be loaded.public static void Initialize()
throws JCNativeException,
JCException,
IOException
Settings are read from the JCOBRIDGE_JVM_SETTINGS environment variable
(if present) and from the static fields set via the programmatic setters.
Each setting in the environment variable must be separated by &&:
JCOBRIDGE_JVM_SETTINGS=--NativePath:/opt/jcobridge&&--LicensePath:/opt/license
JCNativeException - if something happens within the CLR context.JCException - if initialization fails at the library level.IOException - if a required file or directory cannot be accessed.public static void Initialize(String[] args) throws IOException, JCException
args and storing the remainder in filteredArgs.
Arguments from the JCOBRIDGE_JVM_SETTINGS environment variable (if present)
are merged with args before processing. Each environment variable entry must
be separated by &&.
args - the full argument array from main(String[] args).IOException - if a required file or directory cannot be accessed.JCException - if initialization fails at the library level.public static void InitializeFromRemote(String J2CBridgeCanonicalPath, String licencePath, String scopedOn, String scopedOnVersion, boolean globalize) throws JCNativeException, IOException
Do not call directly. Invoked by the CLR host when the JVM is started from .NET rather than the other way around.
J2CBridgeCanonicalPath - the canonical path to the loaded native bridge library.licencePath - the license file path or URL.scopedOn - the scoped-on value for license validation.scopedOnVersion - the scoped-on version for license validation.globalize - false to run in invariant globalization mode.JCNativeException - if the native initialization fails.IOException - if a required file cannot be accessed.public static JCOBridge CreateNew() throws JCNativeException
JCOBridge instance backed by a fresh CLR context.
Initialize() must have been called before invoking this method.JCOBridge instance.JCNativeException - if the CLR context cannot be created.public static void RegisterJVMGlobal(String key, Object obj) throws JCNativeException
registeredObjectsMap to prevent premature
GC collection while it is registered.key - the key to identify the registered object.obj - the object to register.JCNativeException - if the native registration fails.public static void UnregisterJVMGlobal(String key) throws JCNativeException
registeredObjectsMap, allowing it to be collected by the GC.key - the key of the object to unregister.JCNativeException - if the native unregistration fails.public static Object GetJVMGlobal(String key) throws JCNativeException
key - the registration key.JCNativeException - if the native lookup fails or the key is not found.public static Object GetCLRGlobal(String key) throws JCNativeException
key - the registration key.JCNativeException - if the native lookup fails or the key is not found.public static IJCGraphicContainer CreateContainer(Component comp)
IJCGraphicContainer wrapping the given AWT component, enabling it to
be embedded in a CLR UI host (e.g. a WinForms or WPF panel).comp - the AWT Component to embed.IJCGraphicContainer wrapping comp.public static IJCGraphicContainer CreateContainer(String className) throws InstantiationException, IllegalAccessException, ClassNotFoundException, JCException
IJCGraphicContainer from a class name. The class must either implement
IJCGraphicContainer directly or extend Component (in which case
it is wrapped automatically).className - the fully qualified class name to instantiate.IJCGraphicContainer instance.IllegalAccessException - if the class or its nullary constructor is not accessible.InstantiationException - if the class is abstract, an interface, an array, a primitive,
or void; or has no nullary constructor.ClassNotFoundException - if the class cannot be located.JCException - if the instantiated class is neither an IJCGraphicContainer
nor a Component.public void RegisterEventLog(IJCEventLog logger) throws JCNativeException
logger via the IJCEventLog interface.logger - the IJCEventLog instance to register.JCNativeException - if the registration fails within the CLR context.public void AddPath(String path) throws JCNativeException
AddReference(java.lang.String) calls.path - the directory path to add to the CLR assembly search path.JCNativeException - if the operation fails within the CLR context.public JCAssembly AddReference(String assemblyName) throws JCNativeException
assemblyName - the name or path of the CLR assembly to load.JCAssembly handle to the loaded assembly.JCNativeException - if the assembly cannot be found or loaded.public JCType GetType(String type) throws JCNativeException
type - the fully qualified CLR type name (e.g. "System.Collections.ArrayList").JCType handle to the resolved type.JCNativeException - if the type cannot be found.public JCEnum GetEnum(String type) throws JCNativeException
type - the fully qualified CLR enum type name.JCEnum handle to the resolved enum type.JCNativeException - if the enum type cannot be found.public JCControl GetControl(String type) throws JCNativeException
JCControl handle to a graphical CLR object, suitable for embedding
CLR controls (WinForms, WPF) into an AWT/Swing host.type - the fully qualified CLR type name of the graphical object.JCControl handle.JCNativeException - if the type cannot be found or instantiated.public JCJControl GetJControl(String type) throws JCNativeException
JCJControl handle to a graphical CLR object, suitable for embedding
CLR controls into a Swing host via a dedicated Swing-aware wrapper.type - the fully qualified CLR type name of the graphical object.JCJControl handle.JCNativeException - if the type cannot be found or instantiated.public Object NewObject(String type, Object... params) throws JCNativeException
bool, float, String, etc.) are returned as
their Java equivalents; all other types are returned as JCObject.type - the fully qualified CLR type name to instantiate.params - optional constructor arguments.JCObject.JCNativeException - if the type cannot be found or the constructor fails.public Object NewObject(JCType type, Object... params) throws JCNativeException
JCType handle,
passing optional constructor arguments.type - the JCType handle of the CLR type to instantiate.params - optional constructor arguments.JCObject.JCNativeException - if the constructor fails.