com.javonet

Class Javonet

java.lang.Object

com.javonet.Javonet

public class Javonet
extends java.lang.Object

This is main class of Javonet solution. Javonet exposes methods for:

• initializing javonet
• activating javonet
• loading references to .NET assemblies
• retrieving .NET types
• creating .NET classes instances

Use this class as starting point for most Javonet operations.

Activating Javonet

Before you perform any operation with Javonet first you must activate your Javonet license. You can do it either by calling activate(String, String, JavonetFramework) method or specifying your license details in Javonet XML configuration file.

Usage Sample

Example below shows all what you need to do to activate Javonet and use .NET Random class to generate random number and retrieve result as JAVA integer:

 
	Javonet.activate("your@mail.com", "your-javonet-license-key");
 
	NObject objRandom = Javonet.New("System.Random");
	Integer value = objRandom.invoke("Next",10,20);
		
	System.out.println(value);
 
 

Version:

1.0

Constructor Summary

Constructors

Constructor and Description
Javonet()

Method Summary

Modifier and Type	Method and Description
static boolean	activate(java.lang.String oemLicenceKey, JavonetFramework framework) Activates Javonet copy with OEM license details.
static boolean	activate(java.lang.String email, java.lang.String licenceKey, JavonetFramework framework) Activates Javonet copy with your license details.
static boolean	activate(java.lang.String email, java.lang.String licenceKey, java.lang.String proxyHost, JavonetFramework framework) Activates Javonet copy with your license details.
static boolean	activate(java.lang.String email, java.lang.String licenceKey, java.lang.String proxyHost, java.lang.String proxyUsername, java.lang.String proxyPassword, JavonetFramework framework) Activates Javonet copy with your license details.
static boolean	activate(java.lang.String email, java.lang.String licenceKey, java.lang.String proxyHost, java.lang.String proxyUsername, java.lang.String proxyPassword, java.lang.String proxyDomain, JavonetFramework framework, java.lang.String relay) Activates Javonet copy with your license details.
static void	addReference(java.lang.String... pathOrName) Loads .NET library or libraries into memory on .NET side.
static void	addReference(java.lang.String name, byte[] dotNetAssemblyByteArray) Loads .NET library from byte array into memory on .NET side.
static void	addReference(java.lang.String name, java.lang.Byte[] dotNetAssemblyByteArray) Loads .NET library from byte array into memory on .NET side.
static NObject	create(java.lang.String typeName) Creates new instance of .NET class using parameter-less constructor specified by provided type name and located in any of the loaded assemblies.
static NObject	create(java.lang.String typeName, java.lang.Object... parameters) Creates new instance of .NET class using constructor with parameters specified by provided type name and located in any of the loaded assemblies.
static void	Dispose() Disposes Javonet session.
static JavonetFramework	getFramework() Returns current .NET Framework version that is being used by Javonet.
static com.javonet.internal.IGateway	getGateway() Returns current gateway session object.
static NType	getType(java.lang.String typeName) Loads specified type on .NET side and returns new instance of NType class connected to this type.
static NType	getType(java.lang.String typeName, java.lang.Object... genericTypes) Loads specified generic type on .NET side and returns new instance of NType class connected to this type.
static boolean	getUseLegacyExceptions() Returns if Javonet is working in legacy exceptions mode or new NException mode.
static boolean	getUsePrivateHandleField() Returns information if Javonet is using the private handles field mode for strongly typed wrappers.
static boolean	isActivated() Returns true or false indicating if Javonet engine has been activated and configured in the current process.
static NObject	New(java.lang.String typeName) Creates new instance of .NET class using parameter-less constructor specified by provided type name and located in any of the loaded assemblies.
static NObject	New(java.lang.String typeName, java.lang.Object... parameters) Creates new instance of .NET class using constructor with parameters specified by provided type name and located in any of the loaded assemblies.
static NAssembly	reference(java.lang.String pathOrName) Loads .NET library and returns instance of associated NAssembly object.
static void	setActivationRelay(java.lang.String relayUrl, java.lang.String relaySignature) Sets the custom URL that will be used for processing activation requests.
static void	setApartmentState(JavonetApartmentState apartmentState) Sets apartment state for .NET process main thread.
static void	setDependencyPath(java.lang.String name, java.lang.String path) Defines fixed path for dependent DLL which is being dynamically loading by .NET code.
static void	setLicenseDirectory(java.lang.String licenseDirectory) Sets the absolute path where the Javonet license files should be stored.
static void	setUseHardwareKey(boolean useHardwareKey) Sets if the Javonet should use hardware key as a source of machine ID for license verification.
static void	setUseLegacyExceptions(boolean value) Sets if Javonet is working in legacy exceptions mode or new NException mode.
static void	setUsePrivateHandleField(boolean value) Sets if Javonet should use the private handles field mode for strongly typed wrappers.
static void	showWelcomeMessage() Prints on console Javonet Welcome message.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Javonet

public Javonet()

Method Detail

activate

public static boolean activate(java.lang.String oemLicenceKey,
                               JavonetFramework framework)
                        throws JavonetException

Activates Javonet copy with OEM license details.

Parameters:

oemLicenceKey - Your OEM license key

framework - .NET Framework version to be used read more at JavonetFramework

Returns:

Activation result true for success and false for failure

Throws:

JavonetException - If exception occurs during activation

activate

public static boolean activate(java.lang.String email,
                               java.lang.String licenceKey,
                               JavonetFramework framework)
                        throws JavonetException

Activates Javonet copy with your license details. Activation can be also performed automatically by providing your license details in Javonet XML configuration file.

Parameters:

email - Your license key email address

licenceKey - Your license key

framework - .NET Framework version to be used read more at JavonetFramework

Returns:

Activation result true for success and false for failure

Throws:

JavonetException - If exception occurs during activation

activate

public static boolean activate(java.lang.String email,
                               java.lang.String licenceKey,
                               java.lang.String proxyHost,
                               JavonetFramework framework)
                        throws JavonetException

Activates Javonet copy with your license details. Activation can be also performed automatically by providing your license details in Javonet XML configuration file. With this method optional proxy settings can be provided which should be used to access Internet from enterprise network. These settings will be used for performing activation.

Parameters:

email - Your license key email address

licenceKey - Your license key

proxyHost - Proxy host name in format HOST:PORT or IP:PORT

framework - .NET Framework version to be used read more at JavonetFramework

Returns:

Activation result true for success and false for failure

Throws:

JavonetException - If exception occurs during activation

activate

public static boolean activate(java.lang.String email,
                               java.lang.String licenceKey,
                               java.lang.String proxyHost,
                               java.lang.String proxyUsername,
                               java.lang.String proxyPassword,
                               JavonetFramework framework)
                        throws JavonetException

Activates Javonet copy with your license details. Activation can be also performed automatically by providing your license details in Javonet XML configuration file. With this method optional proxy settings can be provided which should be used to access Internet from enterprise network. These settings will be used for performing activation.

Parameters:

email - Your license key email address

licenceKey - Your license key

proxyHost - Proxy host name in format HOST:PORT or IP:PORT

proxyUsername - Username to be used for proxy authentication

proxyPassword - Password to be used for proxy authentication

framework - .NET Framework version to be used read more at JavonetFramework

Returns:

Activation result true for success and false for failure

Throws:

JavonetException - If exception occurs during activation

activate

public static boolean activate(java.lang.String email,
                               java.lang.String licenceKey,
                               java.lang.String proxyHost,
                               java.lang.String proxyUsername,
                               java.lang.String proxyPassword,
                               java.lang.String proxyDomain,
                               JavonetFramework framework,
                               java.lang.String relay)
                        throws JavonetException

Activates Javonet copy with your license details. Activation can be also performed automatically by providing your license details in Javonet XML configuration file.

With this method optional proxy settings can be provided which should be used to access Internet from enterprise network. These settings will be used for performing activation.

Parameters:

email - Your license key email address

licenceKey - Your license key

proxyHost - Proxy host name in format HOST:PORT or IP:PORT

proxyUsername - Username to be used for proxy authentication

proxyPassword - Password to be used for proxy authentication

proxyDomain - User domain to be used for proxy authentication

framework - .NET Framework version to be used read more at JavonetFramework

Returns:

Activation result true for success and false for failure

Throws:

JavonetException - If exception occurs during activation

addReference

public static void addReference(java.lang.String... pathOrName)
                         throws JavonetException

Loads .NET library or libraries into memory on .NET side.

Loaded libraries are automatically used for all look-ups on further Javonet calls to .NET types or classes.

Assembly can be located anywhere on the hard drive in local directory or in GAC.

You can specify full assembly path or full assembly name for GAC assemblies.

You can provide more then one assembly name in seperate string arguments.

Parameters:

pathOrName - List of .NET assemblies paths or full assembly names to be loaded

Throws:

JavonetException - If .NET exception occurs during while loading assembly

addReference

public static void addReference(java.lang.String name,
                                byte[] dotNetAssemblyByteArray)
                         throws JavonetException

Loads .NET library from byte array into memory on .NET side.

Loaded libraries are automatically used for all look-ups on further Javonet calls to .NET types or classes.

You can load the assembly bytes from disk or memory stream extracted from your application jar file.

This method will automatically box the provided bytes array byte[] into Byte[]. For higher performance use the addReference(String, Byte[]).

Parameters:

name - Name of the library provided in second argument.

dotNetAssemblyByteArray - Byte Array of an assembly to be loaded.

Throws:

JavonetException - If .NET exception occurs during while loading assembly

addReference

public static void addReference(java.lang.String name,
                                java.lang.Byte[] dotNetAssemblyByteArray)
                         throws JavonetException

Loads .NET library from byte array into memory on .NET side.

Loaded libraries are automatically used for all look-ups on further Javonet calls to .NET types or classes.

You can load the assembly bytes from disk or memory stream extracted from your application jar file.

Parameters:

name - Name of the library provided in second argument.

dotNetAssemblyByteArray - Byte Array of an assembly to be loaded.

Throws:

JavonetException - If .NET exception occurs during while loading assembly

create

public static NObject create(java.lang.String typeName)
                      throws JavonetException

Creates new instance of .NET class using parameter-less constructor specified by provided type name and located in any of the loaded assemblies.

Parameters:

typeName - Name of the type for which new instance should be created

Returns:

New instance of NObject associated to new instance of created object on .NET side

Throws:

JavonetException - If .NET exception occurs during initialization of .NET object

create

public static NObject create(java.lang.String typeName,
                             java.lang.Object... parameters)
                      throws JavonetException

Creates new instance of .NET class using constructor with parameters specified by provided type name and located in any of the loaded assemblies.

Constructor is being matched by parameters count and type.

Parameters can be specified as JAVA primitive types (string, integer, float..) or instances of NObject class for reference-type parameters.

This method returns new instance of NObject class associated to newly created object on .NET side.

Parameters:

typeName - Name of the type for which new instance should be created

parameters - Parameters to be passed to constructor during creation of new instance of associated .NET type

Returns:

New instance of NObject associated to new instance of created object on .NET side

Throws:

JavonetException - If .NET exception occurs during initialization of .NET object

Dispose

public static void Dispose()

Disposes Javonet session. All objects and connections are closed. Existing NObject, NType and NAssemblies objects cannot be used anymore.

getFramework

public static JavonetFramework getFramework()

Returns current .NET Framework version that is being used by Javonet.

Framework version can be set either by calling activate(String, String, JavonetFramework) method or setting "framework" property in "settings" section of javonet.xml configuration file.

Returns:

current .NET Framework version selected

getGateway

public static com.javonet.internal.IGateway getGateway()
                                                throws JavonetException

Returns current gateway session object. If gateway is not yet initialized it will be initialized automatically.

Returns:

Current gateway session object

Throws:

JavonetException - If exception occurs during gateway initialization

getType

public static NType getType(java.lang.String typeName)
                     throws JavonetException

Loads specified type on .NET side and returns new instance of NType class connected to this type.

Parameters:

typeName - Name of the type to be loaded

Returns:

New instance of NType associated to loaded .NET type

Throws:

JavonetException - If .NET exception occurs during .NET type loading

getType

public static NType getType(java.lang.String typeName,
                            java.lang.Object... genericTypes)
                     throws JavonetException

Loads specified generic type on .NET side and returns new instance of NType class connected to this type.

Parameters:

typeName - Name of the type to be loaded

genericTypes - List of generic types used to parameterize this generic type instance

Returns:

New instance of NType associated to loaded .NET type

Throws:

JavonetException - If .NET exception occurs during .NET type loading

getUseLegacyExceptions

public static boolean getUseLegacyExceptions()

Returns if Javonet is working in legacy exceptions mode or new NException mode.

Legacy exceptions is standard way how exceptions were handled before version 1.5 all .NET and Javonet exceptions where thrown as JavonetException. For .NET exceptions the message contained entire .NET exception converted to string.

New exception mode distinguishes between JavonetExceptions and exceptions coming from users .NET code. For .NET exceptions the NException extension of JavonetException is thrown. This class contains real .NET message, merges Java and .NET stacktrace and provides access to internal exceptions. Additionally all other properties from .NET exception are copied to Java side for further processing including the access to the .NET exception type.

It is recommended to work with new exceptions mode which will be further extended in next releases. Legacy mode should be used only for backward compatibility in existing projects.

Returns:

Returns true or false indicating if Javonet is working using old exceptions mode.

Since:

1.5

getUsePrivateHandleField

public static boolean getUsePrivateHandleField()

Returns information if Javonet is using the private handles field mode for strongly typed wrappers.

In private handles mode, when regular Java class is passed to Javonet methods as argument, new value for a field, part of array etc... to be processed on .NET side, Javonet looks if this object contains private field of NObject type and name "handle". If yes the object associated with that NObject instance is used for further processing.

This is used to simplify strongly typed wrappers creation and make them more natural for end-users. Read more about creating strongly typed wrappers on Javonet Guides for Java Developers. https://www.javonet.com/java-devs/guides/

Returns:

Returns true or false indicating if Javonet is looking for private handles.

Since:

1.5

isActivated

public static boolean isActivated()

Returns true or false indicating if Javonet engine has been activated and configured in the current process. If Javonet has been activate the "activate" method should not be called. This method can be used in distributed and mulit-threaded environments to avoid multiple Javonet activation calls.

Returns:

Boolean value indicating if Javonet activation has been performed

New

public static NObject New(java.lang.String typeName)
                   throws JavonetException

Creates new instance of .NET class using parameter-less constructor specified by provided type name and located in any of the loaded assemblies.

This method works the same way as create(String) and was created to provide more semantically meaningful usage.

Parameters:

typeName - Name of the type for which new instance should be created

Returns:

New instance of NObject associated to new instance of created object on .NET side

Throws:

JavonetException - If .NET exception occurs during initialization of .NET object

New

public static NObject New(java.lang.String typeName,
                          java.lang.Object... parameters)
                   throws JavonetException

Creates new instance of .NET class using constructor with parameters specified by provided type name and located in any of the loaded assemblies.

This method works the same way as create(String, Object...) and was created to provide more semantically meaningful usage.

Constructor is being matched by parameters count and type.

Parameters can be specified as JAVA primitive types (string, integer, float..) or instances of NObject class for reference-type parameters.

This method returns new instance of NObject class associated to newly created object on .NET side.

Parameters:

typeName - Name of the type for which new instance should be created

parameters - Parameters to be passed to constructor during creation of new instance of associated .NET type

Returns:

New instance of NObject associated to new instance of created object on .NET side

Throws:

JavonetException - If .NET exception occurs during initialization of .NET object

reference

public static NAssembly reference(java.lang.String pathOrName)
                           throws JavonetException

Loads .NET library and returns instance of associated NAssembly object.

Loaded libraries are automatically used for all look-ups on further Javonet calls to .NET types or classes.

Assembly can be located anywhere on the hard drive in local directory or in GAC.

You can specify full assembly path or full assembly name for GAC assemblies.

Parameters:

pathOrName - Full path or full assembly name

Returns:

New instance of associated NAssembly object

Throws:

JavonetException - If .NET exception occurs during while loading assembly

setActivationRelay

public static void setActivationRelay(java.lang.String relayUrl,
                                      java.lang.String relaySignature)

Sets the custom URL that will be used for processing activation requests.

Usage of activation relay servers is allowed for enterprise license only in order to customize the url that will need to be white-listed for activation requests.

The customized activation url must be provided with valid signature generated using Javonet private RSA key by Javonet support. Otherwise the server will not be authorized for processing activation requests.

Parameters:

relayUrl - Target url for activation processing i.e. https://ads.sdncenter.pl

relaySignature - Url signature in base64 format

Since:

1.5

setApartmentState

public static void setApartmentState(JavonetApartmentState apartmentState)
                              throws JavonetException

Sets apartment state for .NET process main thread. This method must be called before any other operation on Javonet is executed.

Apartment state can be also set automatically by specifying it in Javonet XML configuration file.

Javonet during initialization creates .NET process connected to JAVA process of your application. The .NET process main thread can be in Multi-Threaded Apartment state (MTA) or Single-Threaded Apartment state (STA). This value is very important for implementations where WinForms or WPF interface is supposed to be used for JAVA application.

In case when you plan to create WinForms or WPF interface you must use STA apartment thread.

Parameters:

apartmentState - Apartment state to be set

Throws:

JavonetException - If exception occurs while setting apartment state

setDependencyPath

public static void setDependencyPath(java.lang.String name,
                                     java.lang.String path)
                              throws JavonetException

Defines fixed path for dependent DLL which is being dynamically loading by .NET code. This method should be used only if there is a problem with automated resolution of particular DLL location. Method applies only for the library specified, resolution of *.resources libraries will not be affected.

Parameters:

name - Name of the library for which the path will be specified. In example MyProject.Commons.

path - Path to the DLL file that will be set as fixed location for library specified.

Throws:

JavonetException - If .NET exception occurs while specifying fixed registration

setLicenseDirectory

public static void setLicenseDirectory(java.lang.String licenseDirectory)

Sets the absolute path where the Javonet license files should be stored.

Parameters:

licenseDirectory - path for Javonet license files

setUseHardwareKey

public static void setUseHardwareKey(boolean useHardwareKey)
                              throws JavonetException

Sets if the Javonet should use hardware key as a source of machine ID for license verification. If set to "true" the hardware dongle key must be plugged in order to properly activate Javonet.

Setting this value to true to will cause the creation of javonet_hk.lic file in the root directory of Java application.

Parameters:

useHardwareKey - flag if hardware dongle key should be used as source of machine id.

Throws:

JavonetException - thrown if method is called after activate method

setUseLegacyExceptions

public static void setUseLegacyExceptions(boolean value)

Sets if Javonet is working in legacy exceptions mode or new NException mode.

By default Javonet works in NException mode.

Legacy exceptions is standard way how exceptions were handled before version 1.5 all .NET and Javonet exceptions where thrown as JavonetException. For .NET exceptions the message contained entire .NET exception converted to string.

New exception mode distinguishes between JavonetExceptions and exceptions coming from users .NET code. For .NET exceptions the NException extension of JavonetException is thrown. This class contains real .NET message, merges Java and .NET stacktrace and provides access to internal exceptions. Additionally all other properties from .NET exception are copied to Java side for further processing including the access to the .NET exception type.

It is recommended to work with new exceptions mode which will be further extended in next releases. Legacy mode should be used only for backward compatibility in existing projects.

Parameters:

value - true or false indicating if legacy exceptions should be used.

Since:

1.5

setUsePrivateHandleField

public static void setUsePrivateHandleField(boolean value)

Sets if Javonet should use the private handles field mode for strongly typed wrappers.

In private handles mode, when regular Java class is passed to Javonet methods as argument, new value for a field, part of array etc... to be processed on .NET side, Javonet looks if this object contains private field of NObject type and name "handle". If yes the object associated with that NObject instance is used for further processing.

This is used to simplify strongly typed wrappers creation and make them more natural for end-users. Read more about creating strongly typed wrappers on Javonet Guides for Java Developers. https://www.javonet.com/java-devs/guides/

Parameters:

value - true or false indicating if private handles fields mode should be used.

Since:

1.5

showWelcomeMessage

public static void showWelcomeMessage()

Prints on console Javonet Welcome message. This method could be used for debugging and logging purposes.

Welcome message includes details about Javonet version, .NET and C++ runtime loaded and configuration detected.