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.
|
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] | -all [-d targetDir] [-s smcDir] [-m rpsMain -t rpsText] [-n] [-v msgLevel] [-?]
Options
-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.
|
|
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. |
-all
Export all methods from the SMC. This option is an alternative to listing individual interfaces with the -i option. A Java class will be created for each interface in the SMC. If both -i and -all are included on the command line, -all takes precedence.
|
The -all option may not be suitable for some SMCs because it exports all methods, even those that are not included in an interface. An XML file that contains methods that are not in an interface will cause the error “Missing interface name in XML file. No Java class will be generated” when you run genjava. You may have such methods in your SMC if it contains the xfServerPlus API routines or the xfNetLink Java pooling support methods. |
-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.
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. (The DCL interface on OpenVMS uppercases names. If names are not uppercase in the SMC, you’ll need to put them in double quotes on the genxml command line, or genxml will generate an error. You will likely also want to put quotes around the XML filename, since it becomes the name of the Synergy component.)
$ 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:
- Java source files (.java files). There will be one file for each interface you specified when running genxml, as well as a file for each structure, group, and enumeration in those interfaces. The source files are created as a Java package, named with the name you specify with the -p option.
- A manifest file (named with the XML filename), which will be used when creating the JAR file.
- A batch file (also named with the XML filename), which will be used to compile the classes, create the JAR file, and generate Javadoc.
- Files named filename_srclist.dat and filename_clslist.dat (where filename is the name of the XML file), which are used in conjunction with the batch file to create the JAR file.
The genjava utility is installed in the xfNLJava directory.
java genjava -f xmlFilename [-p packageName] [-d targetDir] [-j] [-t version] [-ro] [-v msgLevel] [-?]
Options
-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.)
-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 8, 9, 10, 11, 12, and 17. 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
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.
|
|
If you are targeting an earlier version of Java than you are using (e.g., if you are using Java 11 and targeting Java 10), 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 (x86)\Java\jdk\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/jdk/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.
