Referenced Files

The component descriptor can name other files in the library that are dependencies for this component (e.g., this component requires additional files that are not included in the component JAR file). Referenced files are files that have been published to the library and may contain native (non-Java) code, Java code, static data files, etc.

Overview of Referenced Files

This feature is useful when a component uses third-party tools that are not included directly in the component JAR file. If the referenced file is Java code, the system will automatically deploy the referenced file and add it to the classpath so that it can be used freely by the component. If two components use different versions of the same third-party tool, there is no conflict because each component will be loaded in its own classloader with its own version of dependent (referenced) tools.

If a referenced file contains native (non-Java) code, the system will automatically deploy the native code file into a directory on the system PATH of the JVM. Deployment of the native code file allows the native code to be loaded using the System.loadLibrary() call without the native code knowing the full system-dependent path name of the file at compile time. The use of native code in a component imposes certain restrictions and limitations on the component. For more information, see Non-Java Code Considerations.

The deployment descriptor tags to define a referenced file are

<Requires>
   <Reference 
      name="library_name_of_file" 
      version="library_version_of_file" 
      type="file_type" 
      libname="native_file_name"
      platforms="platform_list"
      sharedloader="true|false"
      id="any_id"/>
</Requires>

The tags are as follows:

  • name. The full name of the referenced file as published in the library. The name can contain the platforms substitution if the reference is platform dependent (see details below).

  • version. The version of the referenced file as published in the library. The version can contain wildcards to select the latest version (e.g.,2.*.* will select the latest version that has 2 as the major version).

  • type. Defines the type of referenced file. The allowed values are:

  • metamodel. The referenced file is a MetaModel (Java JAR file with a MetaModel XML file).
  • jar. The referenced file is a Java JAR file containing Java code.
  • library. The referenced file is a native code library (non-Java code).
  • program. The referenced file is a native executable program (non-Java code).
  • data. The referenced file is a component-specific arbitrary data file. The component can read the content of this file but cannot update it.

  • libname. If the type=library, libname defines the name to be used in a System.loadLibrary() call to load this native code library into the JVM process. Do not specify a file extension. The file extension, which is system dependent, will be defined when the file is published to the library.

  • platforms. An optional comma-delimited list of platforms that this reference supports. If the component is loaded on a platform not in the list, this reference will be ignored. The current possible platform specifications are

    • Win32

    • Linux

    • Irix

    • OSF1

    This list does not imply platform support.

  • sharedloader. If specified, the value of this tag must be either true or false. The default value is false. This tag applies only to references with type=jar. If a component has a shared loader reference, the referenced JAR file will be loaded using the single system-wide shared class loader. In general, this tag should be used only for Java library files that load native (non-Java) code. For more information about native code, see Non-Java Code Considerations.

  • id. This optional tag can contain any valid string value. The component can locate this referenced file by using the id in the MetaModel.getReference() method. Use of this tag allows the component to discover the physical location of the deployed file as well as various additional information. For more information, refer to the MMReference object description in the SDK documentation.

The name tag can contain the string {platform} if there are different versions of the file for different native platforms. For example, native code files are typically built for each platform, and the system must deploy the file that is correct for the platform on which the system is running. The {platform} string will be substituted at the time the component is loaded with one of the following values:

  • win32

  • win64

  • Linux

  • Linux_x64

  • Irix

  • OSF1

Likewise, if different versions of the file exist for different languages, the string {language} can be embedded in the name and will be resolved with an underscore followed by a 2-letter language identifier (e.g,. _en for US English, _ja for Japanese, etc.)

Native Code Example

<Requires>
<Reference id="mylib" 
name="com.mycompany.mycomponent.my_c_code.{platform}" 
version="1.0.*" type="library" libname="myccode"
platforms="Windows,Linux"/>
</Requires>

In this example, multiple copies of the file are published to the library, one for each supported platform (Windows and Linux). The library names will be:

com.mycompany.mycomponent.my_c_code.win32
com.mycompany.mycomponent.my_c_code.Linux

When the component is loaded into a model, the appropriate file is taken from the library and written to disk with a file name such as myccode.dll on Windows or libmyccode.50 on Linux. The file is placed in the JVM native code path, so that it can be loaded by the component by calling System.loadLibrary("myccode"). For more information about using native code, see Non-Java Code Considerations.

Data File Example

<Requires>
<Reference id="mydata" 
name="com.mycompany.mycomponent.mydata" 
version="1.0.*" type="data" />
</Requires>

This file will be read from the library and written to local disk when the component is loaded. The component can find this file by using the ID tag to locate it from the component’s MetaModel:

MMReference ref = getMetaModel().getReference("mydata");
File myFile = ref.getLocalFile();

The File object can then be used to load the file content. Writing the file will update only the local deployed copy and may have undesirable side effects when the component is used in a parallel model or in the SIMULIA Execution Engine distributed shared environment. In general, components should not write to referenced files and should consider them read-only.