Creating a Java JAR file from the command line

If your Synergy source files are not on Windows, or if you don’t use Workbench, follow the instructions in this topic to create the Java class wrappers, Javadoc, and JAR file using command line utilities. To create a Java JAR file from the command line, you’ll need to do the following:

1. Create an XML file with the genxml utility. See Creating an XML file with genxml.
2. Use the XML file and the genjava utility to generate Java classes. See Generating Java classes with genjava.
3. (optional) Edit the Java source files. See Editing the Java source files.
4. Run the batch file to compile the classes, create the JAR file, and (optionally) create the Javadoc HTML files. See Building a JAR file from the command line.

Creating an XML file with genxml

The genxml utility creates an XML file from SMC method definitions and repository structure definitions. This is an intermediate step in creating Java class wrappers.

Note

The genxml utility checks structure sizes in the SMC against the corresponding structures in the repository and reports a warning if there are discrepancies. Although the XML file is generated anyway, you should use the MDU’s Verify Catalog utility to update the structure sizes in the SMC. (See Verifying repository structure sizes and enumerations.) Failure to do so can cause errors at runtime because the structure information in the component, which was pulled from the repository, will differ from that in the SMC.

The genxml utility is installed in the DBLDIR directory. It runs on all supported Synergy/DE platforms.

dbr genxml ‑f xmlFilename ‑i intName [‑a altIntName] [‑d targetDir] 
[‑s smcDir] [‑m rpsMain ‑t rpsText] [‑n] [‑v msgLevel] [‑?]

Arguments

‑f xmlFilename

The name to use for the XML file. This name will also be used for the JAR file. You can include the complete path if desired. The extension “.xml” will be appended to this filename if you don’t specify an extension.

‑i intName

Name of the interface from the SMC to include in the XML file. You may pass multiple interface names; each must be preceded with the ‑i option. A Java class will be created for each interface specified. Remember, the interface name is case sensitive.

‑a altIntName

(optional) Alternate interface name. Use this name for the interface previously specified with the ‑i option. Genxml uses the associated ‑i interface to pull methods from the SMC; the alternate name is included in the XML file and is used as the class name when genjava is run. If you pass multiple interface names, each may have an alternate name. Each alternate name must be preceded with the ‑a option. See Examples.

Important

When using alternate names, sequence matters. The ‑a option must follow the ‑i option that it applies to. You may specify multiple interface names, and each may have an associated alternate name immediately following it.

‑d targetDir

(optional) The target directory for the XML file. If not passed, the XML file is created in the directory specified with the ‑f option. If no directory is specified with ‑f, the file is created in the current directory.

‑s smcDir

(optional) Directory where the SMC files (cdt.is? and cmpdt.is?) are located. If not passed, DBLDIR is used.

‑m rpsMain

(optional) Full path to the repository main file that contains the structures referenced in the SMC. Use with ‑t. This option is used if you are passing structures as parameters. If not passed, genxml uses the environment variable RPSMFIL to determine the name of the repository main file; if that is not set, it uses RPSDAT:rpsmain.ism. If RPSDAT isn’t set, genxml looks in the current directory for rpsmain.ism.

‑t rpsText

(optional) Full path to the repository text file that contains the structures referenced in the SMC. Use with ‑m. This option is used if you are passing structures as parameters. If not passed, genxml use the environment variable RPSTFIL to determine the name of the repository text file; if that is not set, it uses RPSDAT:rpstext.ism. If RPSDAT isn’t set, genxml looks in the current directory for rpstext.ism.

‑n

(optional) Indicates that you want to use the value in the Repository Alternate name field instead of the value in the Name field. This option pertains only when you are passing structures as parameters. If not set, the field name in the structure becomes the property name in the class. If passed, the value in the Alternate name field is used if it exists; else, the value in the Name field is used.

‑v msgLevel

(optional) Level of verbosity in messages:

0 = no messages

1 = error messages and warnings

2 = everything included in level 1, plus success messages (default)

3 = everything included in level 2, plus return codes and the location of the SMC and repository files

‑?

(optional) Displays a list of options and the version number for genxml.

Examples

This example creates an XML file named ConsultIt.xml, which will also be the name of the JAR file. The XML file will include information about two interfaces, AppLogin and Consultant. The target directory for the XML file is c:\work, which is also where the SMC files are located.

dbr DBLDIR:genxml ‑f ConsultIt ‑i AppLogin ‑i Consultant ‑d c:\work ‑s c:\work 

This example uses alternate interface names. Instead of classes named AppLogin and Consultant, the JAR file will have classes named Login and Consult.

dbr DBLDIR:genxml ‑f ConsultIt ‑i AppLogin ‑a Login ‑i Consultant ‑a Consult ‑d c:\work ‑s c:\work 

On OpenVMS, you’ll need to define genxml as a foreign command and then execute it. In the example below, we have quoted the XML filename and the interface names to preserve the case.

$ GENXML:==$DBLDIR:GENXML
$ GENXML ‑F "ConsultIt" ‑I "AppLogin" ‑I "Consultant" ‑ 
  ‑D SYS$WORK: ‑S SYS$WORK:  

Generating Java classes with genjava

The genjava utility is a Java program that uses the Synergy XML file created by genxml and outputs the following:

The genjava utility is installed in the xfNLJava directory.

java genjava ‑f xmlFilename [‑p packageName] [‑d targetDir] [‑j] 
[‑c version] [‑t version] [‑ro] [‑v msgLevel] [‑?]

Arguments

‑f xmlFilename

The full name and path of the XML file generated with genxml. If you do not specify the file extension, “.xml” will be appended to the end of the filename.

‑p packageName

(optional) The name of the package that the generated classes will belong to. Use dot notation to indicate multiple levels. The maximum length for package name is 101 characters.

If passed, a directory structure corresponding to the package name will be created within targetDir (or the current directory; see below), and the generated class files will be placed in the lowest level directory in the structure. For example, the package name com.CompanyName.ProductName would result in the directory structure com\CompanyName\ProductName, and the generated classes would be placed in ProductName.

If not passed, the XML filename is used as the package name, and so the subdirectory for the generated class files is named with the XML filename.

‑d targetDir

(optional) Specifies the directory in which the batch file, the manifest file, and, later, the JAR file will be created. If not passed, the files are created in the current working directory.

‑j

(optional) Indicates that you want to create Javadoc files. This option adds a command to create Javadoc to the batch file. (See Generating Javadoc.)

‑c version

(optional) Indicates the Java compatibility desired for the generated classes. Valid values for version are 1.2 and 1.5. If you specify 1.2, the classes will be generated as they were in xfNetLink Java version 9.5.1 and earlier, and they will be compatible with JRE 1.2 through 1.4. If you specify 1.5, the generated classes will be compatible with JRE 1.5 and higher, and various new xfNetLink Java features (introduced in version 9.5.1a and later) will be available. These include encryption, enumerations, type coercion, and support for Boolean and binary structure fields. In addition, when you specify 1.5, default type mappings change (see Appendix B: Data Type Mapping for xfNetLink Java) and ArrayLists use generics. If ‑c is not specified, the default is 1.5.

‑t version

(optional) Indicates the version of the JRE that the JAR file should be built to target. (This option adds the ‑target option to the command line in the batch file.) Valid values for version are 1.5, 1.6, and 1.7. If ‑t is not specified, the default is the version of Java installed on the machine where the JAR file is built.

‑ro

(optional) Indicates that you want fields flagged as read‑only in Repository to be generated as read‑only properties in the structure classes. These properties will have a “get” method but no “set” method. If you are planning to use the classes in your JAR file as JavaBeans, note that JavaBeans require that properties be accessible with both get and set methods.

‑v msgLevel

(optional) Level of verbosity in messages.

0 = no messages

1 = error messages

2 = error messages and informational messages (default)

‑?

(optional) Displays a list of options for the utility.

Examples

The example below creates .java files from ConsultIt.xml. The .bat (.com on OpenVMS), .mf, and .dat files will be created in the c:\work directory. The directory structure com\ABCComputers\ConsultPro will be created within c:\work, with the generated .java files placed in the ConsultPro directory.

java genjava ‑f c:\work\ConsultIt.xml ‑p com.ABCComputers.ConsultPro ‑d c:\work ‑j ‑c 1.5 ‑t 1.5 

Building a JAR file from the command line

If you need to edit the .java source files, do so before building the JAR file See Editing the Java source files.

Important

If you are using Java 1.7 and targeting an earlier version of Java (1.5 or 1.6), you must set the XFBOOTCLASSPATH and XFEXTDIRS environment variables before running the batch file. If either is missing or not set to a valid location, the compile will fail.

Set XFBOOTCLASSPATH to the complete path of the rt.jar file, usually java.home\lib\rt.jar. (For example, c:\Program Files\Java\jdk1.6.0_23\jre\ lib\rt.jar.)

Set XFEXTDIRS to the directory that contains the other classes and jar files that are required by your application, usually java.home/lib. (For example, usr/Java/jdk1.6.0_23/jre/lib.)

The genjava utility created a batch file (.bat for Windows and UNIX; .com for OpenVMS) named with the XML filename and placed it in the directory specified with the ‑d option. The batch file includes commands to compile the Java classes, create the JAR file, and—if you included the ‑j option when running genjava—generate Javadoc HTML files.

Run the batch file. For example, to continue with our previous scenario:

c:\work\ConsultIt

The JAR file will be placed in the ‑d directory. If you created Javadoc, the HTML files will be placed in the package directory and in a subdirectory within that. See Generating Javadoc and Setting up your environment for development for more information about these files.