JAVA COMPONENT DEVELOPMENT GUIDE PIPELINE PILOT INTEGRATION COLLECTION 2017 Copyright Notice
Total Page:16
File Type:pdf, Size:1020Kb
JAVA COMPONENT DEVELOPMENT GUIDE PIPELINE PILOT INTEGRATION COLLECTION 2017 Copyright Notice ©2016 Dassault Systèmes. All rights reserved. 3DEXPERIENCE, the Compass icon and the 3DS logo, CATIA, SOLIDWORKS, ENOVIA, DELMIA, SIMULIA, GEOVIA, EXALEAD, 3D VIA, BIOVIA and NETVIBES are commercial trademarks or registered trademarks of Dassault Systèmes or its subsidiaries in the U.S. and/or other countries. All other trademarks are owned by their respective owners. Use of any Dassault Systèmes or its subsidiaries trademarks is subject to their express written approval. Acknowledgments and References To print photographs or files of computational results (figures and/or data) obtained using BIOVIA software, acknowledge the source in an appropriate format. For example: "Computational results obtained using software programs from Dassault Systèmes BIOVIA. The ab initio calculations were performed with the DMol3 program, and graphical displays generated with Pipeline Pilot." BIOVIA may grant permission to republish or reprint its copyrighted materials. Requests should be submitted to BIOVIA Support, either through electronic mail to [email protected], or in writing to: BIOVIA Support 5005 Wateridge Vista Drive, San Diego, CA 92121 USA Contents Chapter 1: Java Component Development Appendix D: Memory Management 30 Overview 1 Appendix E: Testing 31 Who Should Read this Guide 1 Requirements 1 Getting Started with Java Component Development 1 Java Component API 1 Component Interface 2 Supported Objects 2 Additional Information 2 Chapter 2: Creating Java Components 3 Application Package 3 Anatomy of a Java Component 3 Development Requirements 4 Creating a Java Component with Eclipse 4 Creating a Package 4 Creating a Java Project in Eclipse 5 Creating a Project Named "pilotcomponent" 5 Adding the External jar reference to the Build Path 9 Creating a Pilot Component Class 9 Using the Java API to Implement the Component Interface 10 Component Interface 11 Component Categories 11 Saving the Java Code 12 Activating the Package 12 Chapter 3: Testing a Java Component in Pipeline Pilot Client 14 Chapter 4: Adding New Java Components to a Package 16 Saving Components in Package Destinations 16 Chapter 5: Distributing the Package 18 Chapter 6: Debugging a Java Component 19 Writing Additional Properties to the Output 19 Printing Debug Messages 21 Debugging with Eclipse IDE 22 Notes on Debugging 24 Appendices 26 Appendix A: Java VM Environment 26 Appendix B: Using JNI within a Java Component 26 Appendix C: Hash Table Values 26 Creation from a Java Map 27 Values as Java Maps 28 Comment on null values 30 Chapter 1: Java Component Development Overview The Pipeline Pilot Integration collection includes tools for developing components in the Java programming language for use with protocols. Java is a powerful environment for experienced programmers who need to develop and deliver high-performance capabilities. Java is known for its speed and ability to integrate the capabilities of a pre-existing Java library. If speed is not an issue, it may be easier to use a scripting language such as Perl, Python, or VB. Who Should Read this Guide This guide provides information about how to use the Java component application programming interface (API) to access and modify data objects for developing your own components. It offers the necessary architectural background and technical instructions for creating, testing, and deploying your customized Java components. Requirements To develop components in Java, you need the following: Experience writing code in Java A Java-integrated development environment (IDE), such as Eclipse 3.1 You should also have a basic understanding of how to use Pipeline Pilot Client to design and run protocols Note: This document assumes you are familiar with the Protocol Development Quick Start guide, which explains Component Lifetime Management. Getting Started with Java Component Development The tools available for developing components in Java include: Java-based components, such as Java (on Server) Java API and accompanying API documentation API examples that demonstrate how to design Java components that access the Pipeline Pilot data model to carry out a variety of tasks. A set of template Java Classes to use as a starting point for creating different types of Java components that call the API, such as calculators, manipulators, filters, readers, and writers. This guide includes instructions that walk you through the steps of creating a new component using the Java API, based on the Java (on Server) component that acts as a common "empty vessel" for all Java components. Java Component API The Java Component API provides a convenient way to access and modify the data structures, including the data records that flow through the components, the various parameter settings, and the global properties of the enclosing protocol. Java Component Development Overview | Page 1 The API is implemented in an object-oriented fashion that reflects the natural syntax and features of the Java programming language. For the API definition, refer to the published Javadocs. Component Interface The Java component interface is com.scitegic.pilot.Component. Every Java component implements the following methods, which are detailed in this guide: Component.onInitialize: Executed once before processing the first data record. Component.onProcess: Executed for each data record passed as input or generated by the component. Component.onFinalize: Executed after processing the last data record. The support of this interface is what allows the Java component to plug and play in protocol. Supported Objects The objects implemented by the Java API include: com.scitegic.pilot.DataRecord: The data upon which the component operates to implement its function. com.scitegic.pilot.Node: An element of the data record and global data hierarchies. com.scitegic.pilot.PropertyCollection: An ordered set of name/value pairs used to hold the properties assigned to each node and to represent parameter settings. com.scitegic.pilot.Property: One of the name/value pairs in a property collection. com.scitegic.pilot.Value: A generic value object used to define name/value pairs in a property collection. com.scitegic.pilot.Context: Passed to the Component interface methods above, to allow access to component parameters and global properties. Additional Information For more information about the Pipeline Pilot Integration collection and other BIOVIA software products, visit https://community.3dsbiovia.com. Page 2 | Pipeline Pilot • Java Component Development Guide Chapter 2: Creating Java Components The following topics are covered: Application Package Anatomy of a Java Component Development Requirements Creating a Java Component with Eclipse Activating the Package Application Package To deploy and run a Java component, you need to work within a named package. A package is a directory structure that holds all files required to deploy an application—binaries, component XML, example protocols, example data files, and documentation. All components in Pipeline Pilot are deployed in packages, representing licensed modules. The package approach is particularly important for components that include a separately compiled binary content, such as Java components. IMPORTANT! We recommend that you become familiar with the packaging concept described in the Application Packaging Guide. The "package.conf" file at the top of the package directory structure provides details about how everything is organized in this package and other configuration information. To make a Java component accessible to Pipeline Pilot, define CLASSPATH within java directive in "package.conf", pointing to the location of your classes. <java> CLASSPATH$(package)/…/classes </java> or .jar <java> CLASSPATH$(package)/…/jars/your_component.jar </java> Anatomy of a Java Component When completed, a Java component consists of two parts that reside within a package file structure: A Java class that implements the interface com.scitegic.pilot.Component. The jar file (included in the Integration collection) required to build such classes is "<install_ root>/apps/scitegic/integration/bin/lang/java/jars/pilot.jar" An instance of the Java (on Server) component with its JavaClass and Use Package parameters set to refer to the appropriate class and package. This is the XML definition of the interface that is exposed to a protocol designer in the Pipeline Pilot Client. It defines the component parameters, default parameter values, the component icon, and configuration of input and output ports. Creating Java Components | Page 3 Development Requirements To implement Java components, be sure you have the following resources available: Develop the Java components on a server and write the compiled class files on the same server for testing. We recommend using a dedicated server for developing and debugging Java components. Creating a Java Component with Eclipse This example provides step-by-step instructions on how to create a Java component using Eclipse 3.1 as the Java development environment. IMPORTANT! Before you start, ensure that Eclipse is configured to use Java 5.0 features. From Eclipse, select Window > Preferences > Java > Compiler. Set the Compiler compliance level to "5.0", and enable the flag for Use default compliance settings. To work with this example, use a command window on your server. The example includes the following steps: Creating a package Creating a Java project in Eclipse that implements the Pipeline Pilot component