Using External JAR Files

Contents

Maven Repository Locations
External JAR Options
Using a Run Configuration
Using the mvn Command
Determining External JAR Parameters
Rebuild the Repository Index

Certain adapters and operators require access to implementing JAR files provided by vendors of software external to TIBCO StreamBase® and TIBCO® Live Datamart. Examples of external JAR files include the JARs that implement TIBCO Enterprise Message Service™ or a third-party JAR file from a database vendor that implements JDBC access to that vendor's database system.

External JAR files may include proprietary technology from their vendors and are made available only to valid license-holders of those products. Other external JAR files are made publicly available, either from a vendor's download site or from a public Maven repository such as Maven Central.

You can also use the instructions on this page to install a WAR file, such as the one that implements TIBCO LiveView™ Web functionality, or other file types similar to JARs.

Maven Repository Locations

Whatever their source, external JAR files must be obtained from their vendor and integrated into a Maven repository accessible to your EventFlow or LiveView fragment project. Projects generally do not pass StreamBase typechecking until all required external JAR files are identified as accessible to the Maven build system.

Maven repositories can be located in several layers:

  • A public repository, such as Maven Central. EventFlow and LiveView fragment projects have access to Maven Central by default.

  • A vendor-provided public repository specific to that vendor's products. For example, Oracle Corporation provides an Oracle-specific repository.

  • A site-specific network repository for your organization or department. In general, a site-specific central repository offers the most flexibility for the installation of required external JAR files and for the deployment of Maven artifacts.

  • A read-only on-disk repository installed by a software package. TIBCO StreamBase and TIBCO Live Datamart installs a read-only on-disk Maven repository as part of its installation. Your projects pull StreamBase-provided artifacts from this repository, but you cannot add external JAR files to it.

  • A machine-specific local repository. This is usually the ~/.m2/repository folder of the current user's home directory on your local machine. Using the local machine's repository provides convenience, but any JAR file installed locally for one machine must be installed locally again for every developer and for any QA and deployment machines.

External JAR Options

You must install required external JAR files to the Maven system for your EventFlow or LiveView fragment project in one of several ways. The following ways are listed here in preference order.

  • If your JAR file is made available by its vendor in a public repository such as Maven Central, then you only need to specify the artifact's name and the version you wish to include, using the Maven → Add Dependency option. The JDBC driver for the MySQL database is an example of a JAR file in this category.

  • If your JAR file is not available from a public repository, but is downloadable under license from its vendor, you can add such downloaded JAR files to your local machine's Maven repository, or to a site-specific network repository. In Maven terminology, this is known as installing a file.

    You can run a Maven Install operation with a Studio Run Configuration, or with command-line mvn install command. Using command-line Maven requires a separate installation of Maven as described in Installing Command Line Maven.

    The Maven Install options are described in the next sections. To use either method, you must obtain the external JAR file from its vendor, and obtain, as far as possible, its exact groupId, artifactId, and version number.

  • It is possible for you to run a Maven Install that specifies a JAR dependency based on a local system path. In this case, you specify an absolute path to the JAR file on your local system, or a path relative to your project folder. This method is not recommended because it is not portable. Your system path on a development system is likely not the same as the path to the same JAR file on a QA or deployment system. This method is not described on this page.

  • For short-term testing ONLY, you can place an implementing JAR file in your project's src/main/resources folder. However, you must remove such JAR files before creating the archive for your EventFlow fragment or LiveView fragment project. Otherwise, you could end up distributing another company's proprietary JAR files as part of your EventFlow fragment, possibly without a license to do so. This is especially important to remember for JAR files that implement proprietary interfaces.

Using a Run Configuration

Using a Run Configuration in StreamBase Studio is the preferred method to run a Maven Install operation if you do not have a command-line Maven installation, or prefer not to install one.

This simple procedure is described on Editing Maven Install Configurations.

Using the mvn Command

To add a third-party JAR file to your local Maven repository, you can use a mvn install command at the StreamBase Command Prompt (Windows) or in a StreamBase-configured shell (macOS and Linux). You may need to install the mvn command for your system, as described in Installing Command Line Maven.

You can install the JAR file to the local Maven repository, which is specific to the current user on the current machine. By default, this is the .m2 directory of the current user's home directory. Use command syntax like the following. (This command is shown on multiple lines, but must be entered as one long command.) 

mvn install:install-file 
  -Dfile=<path-to-file> 
  -DgroupId=<group-id> 
  -DartifactId=<artifact-id> 
  -Dversion=<version> 
  -Dpackaging=jar
  -DgeneratePom=true

Fill in the groupId, artifactId, and version information as obtained from the vendor when you downloaded the JAR file. If unavailable, use reasonable values that honor the vendor origin of the file, as described in the next section.

The following example shows the command to install the JAR file that implements the JDBC driver for access to the Microsoft SQL Server database. This example presumes that the downloaded JDBC JAR file, sqljdbc4.jar, is in the current directory. (Again, this command is shown on multiple lines, but must be entered as one long command.) 

mvn install:install-file 
  -Dfile=sqljdbc4.jar 
  -DgroupId=com.microsoft 
  -DartifactId=sqlserver-driver 
  -Dversion=4.0 
  -Dpackaging=jar 
  -DgeneratePom=true

If your site has a central Maven repository, you can also add the -DLocalRepositoryPath= parameter to install the JAR file in your site's shared repository. Consult your local Maven administrators for the value to use at your site.

Determining External JAR Parameters

It is not always obvious what values to fill in for the groupId, artifactId, and version fields for a vendor-provided external JAR file. Many vendors assume their JAR files will be used with simple references to the file, and do not provide Maven-compatible information.

Try the following ways to determine the best values to use with Maven Install, whether in a Run Configuration or on the command line.

  • In all cases, use reasonable values that honor the origin vendor's trade names. Do not invent arbitrary names and version numbers, and do not provide values that match the StreamBase artifact you are building, instead of matching the vendor of origin.

  • If you obtain a JAR file from a public repository such as Maven Central, then by definition, the JAR file contains Maven-compatible information. This will be loaded automatically as Maven adds the dependency for the file from the public repository.

  • You can almost always provide the exact version number for an external JAR file. The vendor's web site from which you download the external JAR file generally allows you to choose among several versions. You thus know the version number of the file you chose to download.

  • If you have a Java JRE or JDK on your search PATH, you also have the jar command. You can use the jar command to look inside a downloaded JAR file for the values to use. Use a command like the following to view the JAR file's table of contents: 

    jar tf filename.jar

    JAR files are archived with a Zip-compatible compression method, so you can also use an unzip utility or app, if your system has one.

    • First, look for the presence of a META-INF/maven folder in the JAR. If that is present, and contains a pom.xml file, then you need not look farther. In your Maven Install Run Configuration, you only need to specify the file parameter, and the other values are filled in at install time from the JAR's internal pom.xml file.

      However, if you are using command line Maven, you must still specify all values as arguments on the mvn install:install-file command line. In this case, you can extract the JAR file's pom.xml to see what values to enter. For example: 

      jar xf jms-2.0.jar META-INF/maven/javax.jms/jms/pom.xml

    • If there is no maven folder in your JAR file, then extract the META-INF/MANIFEST.MF file. For example, use the following command on the tibjms.jar file shipped with TIBCO Enterprise Message Service™ 8.2: 

      jar xf tibjms.jar META-INF/MANIFEST.MF

      Opening the MANIFEST.MF file shows the following contents: 

      Manifest-Version: 1.0
Implementation-Vendor: Cloud Software Group, Inc.
Implementation-Title: com/tibco/tibjms
Implementation-Version: 8.2.1
Specification-Vendor: Cloud Software Group, Inc.
Created-By: 1.7.0_04 (Oracle Corporation)
Specification-Title: TIBCO Enterprise Message Service
Specification-Version: 8.2.1
Main-Class: com.tibco.tibjms.version

      From this information, you can now provide the following values for your Maven Install configuration or command:

      Parameter Name Value
      file /path/on/your/system/to/tibjms.jar
      groupId com.tibco.tibjms
      artifactId ems
      version 8.2.1
      packaging jar
      generatePom true

    • The JAR file's MANIFEST.MF file may not contain as much Maven-compatible information as the previous example. It will almost always provide you with at least a version number.

      In this case, provide a reasonable groupId value that is the reverse URL for the vendor, and an artifactId that reflects the intended use for the file. You can use the basename of the JAR file as the artifactId. For example:

      Parameter Name Value
      file /path/on/your/system/to/silent.jar
      groupId com.example
      artifactId silent
      version n.m.p
      packaging jar
      generatePom true

Rebuild the Repository Index

When you install a JAR file into a local machine repository or a site-specific network repository, the installed file may not immediately appear in response to a search in the Maven → Add Dependency dialog.

To get the file to appear, you must rebuild Studio's index of the files contained in that repository. Use the following method for the local machine's .m2 repository. (Ask your site's Maven administrators for the version of this procedure that applies to a site-specific network repository.)

  1. In Studio, open the Maven Repositories view:

    1. Invoke Window → Show View → Other.

    2. In the search field, enter maven. This restricts the list of views to those with Maven in their names.

    3. Select Maven Repositories.

  2. In the Maven Repositories view:

    1. Open Local Repositories.

    2. Select Local Repository.

    3. Right-click and select Rebuild Index from the context menu.

    4. Click OK.

  3. Watch for status messages in Studio's status bar in the lower right. This command sometimes does not start a rebuild on first invocation. If the command returns very quickly with no status messages, re-run the Rebuild Index command.

    Watch for Studio status bar messages. The command should take 5 to 15 seconds with many status messages and possibly a dialog box or two.

  4. On macOS, the newly added JAR file should now appear in response to a search in the Maven → Add Dependency dialog, and should now be selectable from the results view of that dialog.

    On Windows, the newly added JAR file may still not appear in the Maven → Add Dependency dialog even after a successful index rebuild. In this case, if you saw a BUILD SUCCESS message when you installed the file, then it is safely installed. You can fill in the Group Id, Artifact Id, and Version fields manually in the Add Dependency dialog.