• Using the Java command
• Using Java Webstart (JNLP)

java -jar jdlgS.jar

Notes:

• If the jdlgS.jar file is not located in the current directory, the full path must be specified. For example:

  java -jar /path/to/jdlgS.jar
  

• The -D command line option may be used to specify JDLG configuration properties. For example, to specify a JDLG configuration file, a command line like below could be used:

  java -Deloquence.config=/path/to/jdlg.cfg -jar jdlgS.jar
  

  Note: Any -D command line option must be specified before the -jar option on the command line.

• To use the JDLG drag & drop functionality with Java 9 or newer, access to the javax.swing and javax.swing.plaf.basic Java packages must be allowed.

  To do this, specify the two --add-opens options below before the -jar option on the command line:

  --add-opens=java.desktop/javax.swing=ALL-UNNAMED --add-opens=java.desktop/javax.swing.plaf.basic=ALL-UNNAMED
  

  Java 9 also supports the --permit-illegal-access command line option which may be used as an alternative to the --add-opens options above. Please note that this option has been replaced with --illegal-access=permit in newer Java versions.

  For example:

  java --permit-illegal-access -jar jdlgS.jar
  java --illegal-access=permit -jar jdlgS.jar
  

• By default, Java limits the allocated memory, i.e., the heap size, to 64 MB for the 32-bit virtual machine and 84 MB for the 64-bit virtual machine. This may be insufficient for complex applications. The -Xmx command line option may be used to increase the Java heap size limit. For example, the command line below specifies a maximum heap size of 128 MB:

  java -Xmx128M -jar jdlgS.jar
  

  Notes:

  • The -Xmx command line option must be specified before the -jar option on the command line.

  • If the 64-bit virtual machine is used, JDLG is expected to use at least 30% more memory than if the 32-bit virtual machine is used.

• On the Windows platform, the java command opens a console window where any Java or JDLG error messages would be output. To avoid that a console window is opened, the javaw command may be used instead, for example:

  javaw -jar C:\path\to\jdlgS.jar
  

  Note: When using the javaw command, it is recommended to configure an error log file, otherwise any Java or JDLG error messages would not be reported.

• JDLG requires Java version 5 or newer.

Note: Java Webstart is no longer included in Oracle^™ Java since version 11. We provide the EQWS utility as a simple and lightweight alternative.

To use JDLG with Java Webstart or EQWS, a JNLP file like below should be configured:

<?xml version="1.0"?>
<jnlp spec="1.0+" codebase="http://intranet/jdlg" href="jdlg.jnlp">

  <information>
    <title>Eloquence JDLG</title>
    <vendor>Marxmeier Software AG</vendor>
    <homepage href="http://eloquence.marxmeier.com/doc/jdlg/" />
    <description>Eloquence JDLG</description>
    <description kind="short">JDLG</description>
    <icon href="eq-logo.gif" />
  </information>

  <security>
    <all-permissions />
  </security>

  <resources>
    <j2se version="1.5+" />
    <jar href="jdlgS.jar" main="true" />
    <property name="jnlp.eloquence.config"
              value="conf/jdlg.cfg" />
  </resources>

  <application-desc />

</jnlp>

In the example above, the underlined items may require further explanation:

The codebase attribute of the <jnlp ...> tag specifies the JNLP codebase directory, for example located on a web server in the network (here: http://intranet/jdlg), where the JDLG files are stored. These files are:

• jdlg.jnlp : This is the JNLP file shown above.

• eq-logo.gif : Specifies a logo image which is used by Java Webstart as the JDLG logo. This file may be downloaded from the Eloquence web site at: https://eloquence.marxmeier.com/images/eq-logo.gif

• jdlgS.jar : This is the JDLG jar file, available for download at: https://eloquence.marxmeier.com/download/jdlg/2.0/

• jdlg.cfg : The example above demonstrates how a JDLG configuration property may be specified. Here, the jnlp.eloquence.config property is configured so that the jdlg.cfg file is loaded from the conf subdirectory relative to the JNLP codebase directory.

  Multiple JDLG configuration properties may be specified by configuring multiple <property ... /> tags in the <resources> section.

The "1.5+" version specification of the <j2se ... /> tag in the <resources> section above requests a Java version 5 or newer. Java 5 (internal version number: 1.5) is the minimum version required to run JDLG.

In the example above, the URL of the JNLP file is: http://intranet/jdlg/jdlg.jnlp

• Invoking the JNLP file with Java Webstart:

  Loading this URL in a browser will pass the JNLP file to Java Webstart. In turn, Java Webstart then checks whether JDLG is already installed on the system. If not, or if the installed JDLG version is older than the jdlgS.jar file on the web server, the jdlgS.jar file is loaded from the web server and installed on the system. After that, JDLG is started, using the configuration specified in the JNLP file.

  Note: Java Webstart requires that the web server is configured to associate the .jnlp file extension with the application/x-java-jnlp-file mime type.

  As an alternative, the javaws command may be used with an URL or a local JNLP file. For example:

  javaws http://intranet/jdlg/jdlg.jnlp
  javaws /path/to/jdlg.jnlp
  

• Invoking the JNLP file with EQWS:

  The example below assumes that EQWS is installed in the local C:\Util directory. EQWS expects an URL as argument. For example:

  java -jar C:\Util\eqws.jar http://intranet/jdlg/jdlg.jnlp
  

  EQWS checks whether JDLG is already installed on the system. If not, or if the installed JDLG version is older than the jdlgS.jar file on the web server, the jdlgS.jar file is loaded from the web server and installed on the system. After that, JDLG is started, using the configuration specified in the JNLP file.

  Please refer to the EQWS documentation for further details.

Notes:

• To use the JDLG drag & drop functionality with Java 9 or newer, access to the javax.swing and javax.swing.plaf.basic Java packages must be allowed.

  To do this, add the java-vm-args attribute to the <j2se ... /> tag, as shown below:

  <j2se version="1.5+"
        java-vm-args="--add-opens=java.desktop/javax.swing=ALL-UNNAMED --add-opens=java.desktop/javax.swing.plaf.basic=ALL-UNNAMED" />
  

• By default, Java limits the allocated memory, i.e., the heap size, to 64 MB for the 32-bit virtual machine and 84 MB for the 64-bit virtual machine. This may be insufficient for complex applications. The max-heap-size attribute of the <j2se .../> tag may be used to increase the Java heap size limit. For example, the <j2se .../> tag below specifies a maximum heap size of 128 MB:

  <j2se version="1.5+" max-heap-size="128m"/>
  

  Note: If the 64-bit virtual machine is used, JDLG is expected to use at least 30% more memory than if the 32-bit virtual machine is used.

Notes (JDLG version 1.6.3 or newer):

• Starting with Oracle^™ Java version 7u45, Java Webstart requires that JDLG properties are prefixed with "jnlp.", otherwise they are ignored.

• If no configuration file is specified in a JNLP file, JDLG loads the default jdlg.cfg file if present in the JNLP codebase directory.

Note (JDLG version 1.7.0 or newer):

• Relative URLs in JDLG configuration properties are resolved relative to the JNLP codebase directory.

  This simplifies JDLG configuration and allows to move JNLP files along with the related resources from one directory to another without requiring to edit the configured URLs besides the JNLP code base.

  A relative URL may be specified for each of the configuration properties below:

  • eloquence.config
    (or: jnlp.eloquence.config)

  • eloquence.config.sessions
    (or: jnlp.eloquence.config.sessions)

  • eloquence.config.logoicon
    (or: jnlp.eloquence.config.logoicon)

  • eloquence.config.baseurl
    (or: jnlp.eloquence.config.baseurl)

  • eloquence.config.helpbaseurl
    (or: jnlp.eloquence.config.helpbaseurl)

  • icon attribute in an application configuration file

  When specified, a relative URL is considered relative to the JNLP codebase directory. For example, if the JNLP header specifies ...

  <jnlp spec="1.0+" codebase="http://intranet/jdlg" href="jdlg.jnlp">
  

  ... and the jnlp.eloquence.config property is defined as ...

  <property name="jnlp.eloquence.config"
            value="conf/jdlg.cfg" />
  

  ... the configuration is read from the resulting URL: http://intranet/jdlg/conf/jdlg.cfg

Note (JDLG versions before 1.7.0):

• URLs in JDLG configuration properties must be absolute. In the example above, the following must be configured:

  <property name="jnlp.eloquence.config.url"
            value="http://intranet/jdlg/jdlg.cfg" />