HOOPS For Java Developers
The HOOPS/Java integration consists of Java wrappers to HOOPS/3DGS, HOOPS/MVO, and HOOPS/Stream. This document describes how to use the HOOPS/Java integration to build a Java application that incorporates the HOOPS/3DF components. Some familiarity with Java, HOOPS/3DGS, and HOOPS/MVO is assumed.
The HOOPS/Java integration is supported under the J2SE Development Kit 6.0 (JDK 6.0), on the Windows 32-bit and 64-bit platforms. It is also supported on Linux platforms.
The following steps are required to compile and run a HOOPS/Java based application:
Compiling: You must place the HOOPS/3DF and HOOPS/Java .jar files in your classpath.
This can either be done via the command line for both compiling and running, or it can be set in the manifest file for your project. The files are:
<ul> <li><span class='filename'>HJ<version>.jar</span></li> <li><span class='filename'>HIJ<version>.jar</span></li> <li><span class='filename'>HJMVO<version>.jar</span></li> <li><span class='filename'>HJSTREAM<version>.jar</span></li> <li><span class='filename'>HJCanvas<version>.jar</span></li> </ul>
Executing: Ensure that the following files are in your application's directory.
- .jar files: (discussed above)
Java wrapper libraries:
- Windows: hjmvo<version>.dll
- Linux: hjmvo<version>.so
- For HOOPS/3DGS:
- Windows: hjstream<version>.dll
- Linux: hjstream<version>.so
- Windows: hoops<version>_vc<MS Visual Studio Version>.dll
- Linux: hoops<version>.so
- Windows: hoops_mvo<version>_vc<MS Visual Studio Version>.dll
- Linux: hoops_mvo<version>.so
- Windows: hoops_stream<version>_vc<MS Visual Studio Version>.dll
- Linux: hoops_stream<version>.so
The above files should all be located in your <hoops>/bin/nt_i386_<Visual Studio Version> directory on Windows, and your <hoops>/bin directory under Linux.
For Linux platforms, prior to execution, you must execute two export commands. Below is a list based on the platform you are using:
For 32-bit Linux (on a 32-bit machine ONLY):
For 64-bit Linux (on a 64-bit machine ONLY):
The routines and classes of the HOOPS/3DGS, HOOPS/MVO and HOOPS/Stream toolkits are all generally accessible via the Java wrappers, with a few exceptions and notes covered below. Developers should refer to the Reference Manual for each component, and can additionally leverage the Intellisense capabilities of the NetBeans IDE to see listings of class members and function/method arguments.
Each HOOPS/3DGS routine name, such as ::Insert_Polyline in your HOOPS program must have a prefix before the name will actually be usable on your computer system. The prefix varies depending on which language you're calling from, and sometimes depending on the brand of the language you're calling from. When calling from Java, all calls to the HOOPS/3GS API are made through the HJ class, such as:
You must call Define_System_Options("multi-threading=full") as your first HOOPS call. This is because Java apps must be thought of as multi-threaded, since the garbage collector will run on a separate thread and may trigger HOOPS calls on a separate thread if it invokes certain destructors.
HOOPS Routines Available in Java
Most functions available under C are available in Java except for:
The largest difference between using HOOPS with Java and C is found when you have a write-back value, i.e. you pass a pointer to a function and it writes a value or values to that location. Because Java does not have pointers, we have to use other means of passing in by reference.
For example, the C HOOPS code that uses a char*:
is replaced in Java by StringBuffer:
NOTE: You must always pass a new or empty StringBuffer, as HJ uses append internally to return the string. You must also call ensureCapacity to guarantee the buffer has a minimum size before anything can be written into it. For example:
The C HOOPS code that uses &[float_value]:
is replaced in Java by single element float arrays:
Arrays can be used in Java in a similar manner as they are used in C. Thus, the C HOOPS code:
is replaced in Java by:
It's important to allocate enough room in the array, lest HOOPS writes into unallocated memory and causes a segfault.
Another difference when using HOOPS with Java is found when dealing with HOOPS keys. In Java, you should use the Java 'long'.
The Java datatypes translate as follows:
|HOOPS||HOOPS (HC) type||Java type|
|'string'||const char *||String|
|'writes string'||char *||StringBuffer|
|'writes bytes'||unsigned char *||byte|
HOOPS Intermediate Mode
The HOOPS Intermediate Mode library provides a means for an application to trap the HOOPS update cycle at certain points in the rendering pipeline through a set of callback classes. When you trap the update cycle at a callback point, you can decide what and how something is drawn, or even abort the process itself. The HOOPS I.M. library also provides a set of functions you can call from your callback class to draw to the display in an "immediate mode" style and to query the graphics database and the device characteristics. In the HOOPS/3dGS Programming Guide, you can learn more about HOOPS I.M. and how to implement and use the callback classes.
Any callback class, which has a virtual function with an array as a parameter, is not available in Java. This is because Java doesn't have any concept of a pointer so functions with array arguments cannot be mapped properly.
The capabilities and limitations of HOOPS/MVO for Java are largely analogous to those of C#. After reviewing this section, you can learn more by clicking here.
Member variables are accessed via helper set/get functions with a capitalized member name appended to the end of set/get. For example:
Note that the first letter after "get" or "set" – in this case, "M" from m_pRelativeOrbitOperator – is capitalized for Java accessor methods.
Methods in the C++ classes which return arrays (as a return type) return the array through a parameter in Java
Array member variables return the array via a get_[variable name] method and are read-only
HFileInputResult and HFileOutputResult
You should use the enum HFileIOResult wherever HFileInputResult or HFileOutputResult are mentioned in our documentation. For example:
The HUtilityPMI classes have several caveats.
PMI::String is PMI_String in Java. For example:PMI_String datum_labels = new PMI_String;datum_labels = new PMI_String("A-B");datum_labels = new PMI_String("C");datum_labels = new PMI_String("D");
PMI Type/SubType enums are placed in Java packages. For example, PMI::DiameterModifier::Type is com.techsoft.hoops.PMI.DiameterModifier.Type
Enum array parameters (in or out) and Enum output params require Java int arrays
Out param example - 1st param in GetDiameterModifierType
class PMI::FeatureControlFrameEntity<br />
int diameter_modifier_type = new int;TextAttributes label_attributes;fcf.GetDiameterModifierType(diameter_modifier_type, text_attributes);
Array param example - 4th param in SetDatumReferences
int datum_modifiers = new int;datum_modifiers = com.techsoft.hoops.PMI.DatumModifier.Type.MaximumMaterialCondition.swigValue();datum_modifiers = com.techsoft.hoops.PMI.DatumModifier.Type.RegardlessOfFeatureSize.swigValue();datum_modifiers = com.techsoft.hoops.PMI.DatumModifier.Type.LeastMaterialCondition.swigValue();// ... declare/populate other variablesfcf.SetDatumReferences(3, datum_labels, datum_label_attributes, datum_modifiers, datum_modifier_attributes);
Casting between PMI enums and Java int
To convert a Java PMI enum to an int value, use [enum value].swigValue(). For example:
int v = com.techsoft.hoops.PMI.DatumModifier.Type.MaximumMaterialCondition.swigValue();
To convert from an int to an enum, use [enum].swigToEnum(). For example:
int tolerance_type = new int;fcf.GetToleranceType(tolerance_type, text_attributes);com.techsoft.hoops.PMI.Tolerance.Type e = com.techsoft.hoops.PMI.Tolerance.Type.swigToEnum(tolerance_type)
Do not use BStreamFileToolkit::PrepareBuffer. Instead, do the following:
- Call HJSTREAM.PrepareBuffer(BStreamFileToolkit tk, byte b, int s) , to setup the buffer.
- Call HJSTREAM.ReleaseBuffer(byte b, int s) to retrieve the next buffer of HSF data from the toolkit. This would be called before processing the buffer of HSF data.