init #contents

Overview

OpenRTM-aist-Java Overview

OpenRTM-aist is an implementation of RT middleware implemented, distributed, and maintained by the Task Intelligence Research Group, Intelligent Systems Research Institute, National Institute of Advanced Industrial Science and Technology. RT middleware and OpenRTM-aist are software platforms that make it possible to build various robot systems by dividing the various functional elements of robots into component units called RT components and freely combining them. They also conform to The Robotic Technology Component Specification, a middleware specification for robots currently being standardized by the OMG (Object Management Group).
OpenRTM-aist-Java is a port of OpenRTM-aist, which has been provided for the C++ language, to the Java language. It has an interface compatible with the C++ version of OpenRTM-aist, and enables interoperability between RT components developed using the Java language and RT components developed using the C++ language.

Target Audience

This document explains how to develop Java-language RT components using OpenRTM-aist-Java. This document assumes that readers already have basic knowledge of the Java language.

Operating Environment

The environment required to run OpenRTM-aist-Java is as follows.

Table 1-1 Operating Environment

Environment	Remarks
Java Development Kit 5.0 (JDK 5) (http://java.sun.com/products/archive/j2se/5.0_14/index.html )	Note: It does not work with Java 1.4.

For details on how to install OpenRTM-aist-Java, refer to the “OpenRTM-aist-Java Installation Manual (UNIX)” or the “OpenRTM-aist-Java Installation Manual (Windows)”. In particular, check the following before proceeding with the work below.

• The version displayed when executing “java -version” matches the JDK above
• The path (base path) to the OpenRTM-aist-Java library is set in the environment variable RTM_JAVA_ROOT

• The library files OpenRTM-aist-0.4.x.jar and commons-cli-1.1.jar exist in the directory “jar” directly under the path set by (to set them as the classpath) **Note**

  Note It is also possible to set your own classpath by referring to this page .

◆Reference:

• JDK 5 installation method (UNIX) , JDK 5 installation method (Windows)
• How to set system environment variables (UNIX), How to set system environment variables (Windows)
• FAQ: Support for FedoraCore when installing Java
• FAQ: How can I set a classpath to any folder and perform an Ant build?
  

&aname(javacomp);

About Developing Java RT Components

Here, we introduce the procedure for developing Java RT components. As a sample, we will use a component with the following specifications.

Table 2-1 Sample Component Specifications

Basic Profile
Component name	sample
Description	SampleComponent
Version	1.0
Vendor	AIST
Category	example
Component type	DataFlowComponent
Activity type	SPORADIC
Maximum number of instances	5
Data InPort
Name	in
Type	TimedLong
Service Provider
IDL path	IDLs/MyService.idl Note
Port name	MySvcPort
Service name	myservice0
Service type	MyService
Configuration Parameter
Name	multiply
Type	int
Default value	1

Note Create the following IDL file, MyService.idl, using an appropriate editor. Also, describe the path to MyService.idl in the “IDL path” in the table above. In Windows, this “IDL path” must be the full path to MyService.idl.

 typedef sequence<string> EchoList;
 typedef sequence<float> ValueList;
 interface MyService
 {
   string echo(in string msg);
   EchoList get_echo_history();
   void set_value(in float value);
   float get_value();
   ValueList get_value_history();
 };

MyService.idl

The above MyService.idl is identical to the one in the “examples/Java/RTMExamples/SimpleService” directory of the samples included with OpenRTM-aist-0.4-Java.

Procedure for Developing RT Components Using the GUI

This section explains the procedure for developing RT components using RtcTemlate, a GUI tool. For details on RtcTemplate, refer to Installing RtcLink and RtcTemplate(No corresponding page available.) and RtcTemplate(No corresponding page available.).

Integration of RtcTemplate and JDT

• Open Eclipse as “New”
  RT components can also be developed from projects in the Eclipse integrated development environment. Specify a new workspace and click the [OK] button. Eclipse starts. (At this time, a “Welcome” screen may be displayed; close it.)
  

Figure 2-2 Specifying a new Workspace

• Creating a Java Project File
  Select [File] > [New] > [Project] from the top menu.
  

Figure 2-3 Creating a build project 1

In the “New Project” wizard, select “Java Project” and click the [Next] button.|

Figure 2-4 Creating a build project 2

In the next step of the “New Project” wizard, enter the “Project name” to be created. Confirm that the setting in the “JDK Compliance” group is “5.0” or higher (or 1.5 or higher), and then click the [Next] button (Figure 2-5). On the other hand, depending on the environment, the “JDK Compliance” frame may be a “JRE” frame, and JDK5 (or JDK1.5) may not be selectable from the pull-down menu (Figure 2-5’). In that case, refer to this page to make it possible to select the JDK.|

Figure 2-5 Creating a build project 3

Figure 2-5' Depending on the environment, the JDK may not be selectable

• Reference:
  • → FAQ: Q. A new Java project cannot be created as JDK5 (1.5) compliant |
    
    
    

In the displayed “New Java Project” screen, configure various settings for the project to be generated and click the [Finish] button.

Figure 2-6 Complete after configuring various project settings

The specified project is generated and displayed in the “Package Explorer View”.

Figure 2-7 Example display in the Package Explorer view

• Disable automatic build
  If [Project] > [Build Automatically] in the Eclipse menu bar is turned on, it is better to clear the check and disable it.
  
  

Note For details about Eclipse, such as options and settings when creating a project, refer to the Eclipse site and other resources.

Generating Skeleton Code Using RtcTemplate

• Starting the GUI RtcTemplate Editor Start the RtcTemplate editor screen.

• Reference:
  • → Starting RtcTemplate directly(No corresponding page available.) Note For information on how to use RtcTemplate, refer to RtcTemplate(No corresponding page available.).
    
    
• Editing settings in the RtcTemplate editor The settings for generating skeleton code for an RT component with the specifications shown in Table 2-1>#javacomp using the GUI version of RtcTemplate are shown below.
  

Figure 2-8 GUI RtcTemplate settings

Note: In Windows, describe the above “Output directory” and “IDL path:” as full paths.

• Generate code with the [Generate] button
  Click the [Generate] button to execute code generation. At this time, be sure to specify the directory of the project generated earlier in the “Output directory” field at the bottom of the RtcTemplate editor (Note In Figure 2-8, it is “temp”).

Figure 2-9 Generating code

• Generated files are added to the project

The following files are generated in the directory specified as “Output directory”.

• Sample.java ………………………….. Component Profile, class defining initialization processing, etc.
• Sampleimpl.java …………………. RT component main class
• SampleComp.java ………………. RT component startup class
• MyServiceSVC_impl.java ……… Service implementation class
• build_Sample.xml ………………. RT component build file
• README.Sample ………………. Read Me file

By specifying the project directory in the “Output directory” field, the generated files are added to the project (automatically).

Figure 2-10 Adding various files

Note Even after code generation is complete, the contents of the generated files may not be reflected in the project’s “Package Explorer”. You can update the information by right-clicking the target project and selecting [Refresh] from the context menu that appears.

Figure 2-11 Updating the project display

Note In the case of an RT component that defines a service port, errors will be displayed with only the files generated by Rtctemplate. This is because the corresponding files use classes that are automatically generated from the IDL file. These classes are automatically generated when the build is executed.

Note If OpenRTM-aist-Java is not installed in a location where the classpath is valid, errors will be displayed. In this case, specify the OpenRTM-aist-Java installation folder (directory) from the project properties.

Figure 2-12 Right-clicking the project

Figure 2-13 Adding the path to OpenRTM-aist-Java

• Adding the IDL file to the “Output directory”
  Manually copy the IDL file specified by “IDL path:” in the RtcTemplate editor to the “Output directory” where the generated Java source code is placed.
  

Building with Eclipse

• Ant build~ You can build the target RT component by right-clicking build_Sample.xml in the Package Explorer and selecting [Run] > [Ant Build] from the displayed context menu. If you need to use your own jar libraries, or if OpenRTM-aist is installed in a different location, refer to this page to build by setting the classpath to any location.
  

Figure 2-14 Building the project

Figure 2-15 Console screen when executing the build

When the build succeeds, class files are generated in the “classes” directory in the project.

• Reference
  • FAQ: Q. How can I set a classpath to any folder and perform an Ant build? |
    
    
    

Executing the Created RT Component

• Creating rtc.conf
  Create a file named rtc.conf with the following contents in “classes” in the project.

 corba.nameservers: localhost
 naming.formats: %n.rtc

rtc.conf

The above rtc.conf is identical to the one in the “examples/Java/RTMExamples/SimpleService” directory of the samples included with OpenRTM-aist-0.4-Java.

• Starting the name server and RtcLink~ Start the name server by double-clicking start-orbd.vbs in the “bin” directory included with OpenRTM-aist-0.4-Java (Windows), or by executing start-orbd.sh (UNIX). Also start RtcLink(No corresponding page available.).
  • Reference:
    • Starting the name server (UNIX) (No corresponding page available.), Starting the name server (Windows) (No corresponding page available.)
    • Starting RtcLink >RtcLink#startRtcLink(No corresponding page available.)
      
      

• Executing the RT component
  Start a command prompt or terminal and make the above-mentioned “classes” directory the current directory.

  • For UNIX systems

 $ java -classpath .:$RTM_JAVA_ROOT/jar/OpenRTM-aist-0.4.1.jar:$RTM_JAVA_ROOT/jar/commons-cli-1.1.jar SampleComp

 あるいは、たとえば bash の場合などは、上記コマンドを分割して、
 
 $ export CLASSPATH=.:$RTM_JAVA_ROOT/jar/OpenRTM-aist-0.4.1.jar:$RTM_JAVA_ROOT/jar/commons-cli-1.1.jar
 $ java SampleComp

• For Windows systems

 > java -classpath ".;%RTM_JAVA_ROOT%\jar\OpenRTM-aist-0.4.1.jar;%RTM_JAVA_ROOT%\jar\commons-cli-1.1.jar" SampleComp
 
 あるいは、上記コマンドを分割して、
 
 > set CLASSPATH=.;%RTM_JAVA_ROOT%\jar\OpenRTM-aist-0.4.1.jar;%RTM_JAVA_ROOT%\jar\commons-cli-1.1.jar
 > java SampleComp

By executing these commands, the RT component appears in RtcLink.

Figure 2-16 RtcLink state when successfully executing the Sample component

Details of Java RT Components

Structure of Java RT Components

Figure 3-1 shows the relationship between the source files of a Java RT component and the outline functions executed in each file. For comparison, the structures of C++ RT components and Java RT components for OpenRTM-aist-0.3 are also shown.

Figure 3-1 Structure of an RT component

When comparing existing C++ RT components and Java RT components, the following points differ.

• Separation of the actual RT component functionality In Java RT components, due to startup processing and other factors, the actual RT component functionality has been moved to the XXXImpl class (Impl.java in Figure 3-1). Accordingly, in the original RT component class (.java in Figure 3-1), only the Component Profile definition and various component generation processing remain.
  
• Conversion of callback functions into interfaces The parts defined as callback functions in C++ RT components have been converted into interfaces in Java RT components.
  
  • ModuleInitProc: Interface for starting the component startup class
  • RtcNewFunc: Interface for generating RT components
  • RtcDeleteFunc: Interface for destroying RT components

With this modification, the component startup class must implement the above interfaces.

Differences Between Java RT Components and C++ Components

Data Ports

OpenRTM-aist-Java adds a holder class (DataRef class) to pass data. Therefore, the definition and usage of data ports have been changed as follows.

For how to use data ports, refer to the “SeqIO” and “SimpleIO” samples.

Service Ports

OpenRTM-aist-Java adds an auxiliary variable (/Base) for using service ports. Therefore, the definition and usage of service ports have been changed as follows. For details, see the "SimpleService" sample.

Configuration

As with data ports, when using configuration, holder classes are used for passing data. Therefore, the definition and usage of configuration data have been changed as follows.

For how to use configuration data, refer to the “ConfigSample” sample.
Table 3-1 shows the relationship between the types of holder classes prepared by OpenRTM-aist-Java for configuration data holders and data types.

Table 3-1 Correspondence of Configuration Data Holder Types

Data type	Holder class
short	jp.go.aist.rtm.RTC.util.ShortHolder
int	jp.go.aist.rtm.RTC.util.IntegerHolder
long	jp.go.aist.rtm.RTC.util.LongHolder
float	jp.go.aist.rtm.RTC.util.FloatHolder
double	jp.go.aist.rtm.RTC.util.DoubleHolder
byte	jp.go.aist.rtm.RTC.util.ByteHolder
String	jp.go.aist.rtm.RTC.util.StringHolder

As with the C++ version of OpenRTM-aist, OpenRTM-aist-Java also allows users to create configuration data holders for any user-defined type.
When implementing a holder for configuration data, you must implement the stringFrom method of jp.go.aist.rtm.RTC.util.ValueHolder and add the Serializable interface to the implements clause.
The stringFrom method of jp.go.aist.rtm.RTC.util.ValueHolder is a method for converting a string passed as an argument into the target data type.
For configuration data holders, refer to the VectorHolder class in the “ConfigSample” sample.

Startup Behavior of Java RT Components

The startup behavior of C++ RT components is shown below. The behavior at component startup is basically the same for Java RT components, but because the actual RT component functionality has been separated into the XXXImpl class, the message destination during component generation and component initialization has been changed to the XXX class.

Correspondence Between IDL Data Types and Java Language Data Types

Table 3-2 shows the correspondence between CORBA IDL data types and Java language data types.

Table 3-2 Data Type Correspondence

CORBA IDL	Java language
short	short
long	int
float	float
double	double
long long	long
long double	double
char	char
wchar	char
octet	byte
unsigned short	short
unsigned long	int
unsigned long long	long
boolean	boolean
string	String
wstring	String
any	org.omg.CORBA.Any
void	void

Other

Tips

How to Configure Automatic Startup of Eclipse

• For Windows
  • 1. Select the “.project” file from within the Eclipse project directory and right-click it. Select [Properties] from the context menu that appears.~
• The Eclipse project to select can be any project.

Select the ".project" file

• 1. In the “General” tab of the displayed “Properties” screen, click the [Change] button on the right side of the “Program” row in the middle.

Changing the application association

• 1. Click the [Browse] button at the bottom of the displayed “Open With” screen.

Select Eclipse

• 1. A file selection screen appears. Select “eclipse.exe” from the directory where the Eclipse to be started automatically is installed.
• 1. Close the “Open With” screen and “Properties” by clicking the [OK] button.
     By making the above settings, it becomes possible to automatically start the specified Eclipse by double-clicking the “.project” file.
     
     Note If multiple Eclipses are installed, note that the double-click operation will always start the version of Eclipse specified in the above operation.
     Note If the project you double-clicked is not included in the workspace set for the target Eclipse to be started, it will not be displayed in the Package Explorer of the started Eclipse. In this case, import the target project into the workspace or change the workspace settings.
     
     
• For Linux
  • It is possible to start Eclipse by specifying the workspace with the data option.

     > eclipse -data /home/devel/OpenRTM/workspace
    

    Specify the workspace that contains the target project.
    
    

Acknowledgments

OpenRTM-aist-Java was developed using the following libraries. We thank those involved in the development and design of these projects.

• Apache Commons CLI 1.1
  

This product includes software developed by The Apache Software Foundation (http://www.apache.org/ ).