type=page
status=published
title=Developing Java Clients
next=connectors.html
prev=container_managed-persistence.html
~~~~~~
Developing Java Clients
=======================

[[GSDVG00012]][[beakt]]


[[developing-java-clients]]
10 Developing Java Clients
--------------------------

This chapter describes how to develop, assemble, and deploy Java
clients.

The following topics are addressed here:

* link:#beaku[Introducing the Application Client Container]
* link:#beakv[Developing Clients Using the ACC]
* link:#gkusn[Developing Clients Without the ACC]


[NOTE]
=======================================================================

The Web Profile of the OracleGlassFish Server supports the EJB 3.1 Lite
specification, which allows enterprise beans within web applications,
among other features. The full GlassFish Server supports the entire EJB
3.1 specification. For details, see
http://jcp.org/en/jsr/detail?id=318[JSR 318]
(`http://jcp.org/en/jsr/detail?id=318`).

Accordingly, the Application Client Container is supported only in the
full GlassFish Server, not in the Web Profile.

JMS resources are supported only in the full GlassFish Server, not in
the Web Profile. See link:jms.html#beaob[Using the Java Message Service].

=======================================================================


[[beaku]][[GSDVG00159]][[introducing-the-application-client-container]]

Introducing the Application Client Container
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Application Client Container (ACC) includes a set of Java classes,
libraries, and other files that are required for and distributed with
Java client programs that execute in their own Java Virtual Machine
(JVM). The ACC manages the execution of Java EE application client
components (application clients), which are used to access a variety of
Java EE services (such as JMS resources, EJB components, web services,
security, and so on.) from a JVM outside the Oracle GlassFish Server.

The ACC communicates with the GlassFish Server using RMI-IIOP protocol
and manages the details of RMI-IIOP communication using the client ORB
that is bundled with it. Compared to other Java EE containers, the ACC
is lightweight.

For information about debugging application clients, see
link:debugging-apps.html#gekvq[Application Client Debugging].


[NOTE]
=======================================================================

Interoperability between application clients and GlassFish Servers
running under different major versions is not supported.

=======================================================================


[[fvymq]][[GSDVG00459]][[acc-security]]

ACC Security
^^^^^^^^^^^^

The ACC determines when authentication is needed. This typically occurs
when the client refers to an EJB component that requires authorization
or when annotations in the client's `main` class trigger injection
which, in turn, requires contact with the GlassFish Server's naming
service. To authenticate the end user, the ACC prompts for any required
information, such as a username and password. The ACC itself provides a
very simple dialog box to prompt for and read these values.

The ACC integrates with the GlassFish Server's authentication system. It
also supports SSL (Secure Socket Layer)/IIOP if configured and when
necessary; see link:#gckgn[Using RMI/IIOP Over SSL].

You can provide an alternate implementation to gather authentication
information, tailored to the needs of the application client. To do so,
include the class to perform these duties in the application client and
identify the fully-qualified name of this class in the
`callback-handler` element of the `application-client.xml` descriptor
for the client. The ACC uses this class instead of its default class for
asking for and reading the authentication information. The class must
implement the javax.security.auth.callback.CallbackHandler interface.
See the Java EE specification, section 9.2, Application Clients:
Security, for more details.

Application clients can use link:securing-apps.html#beacm[Programmatic
Login Using the ProgrammaticLogin Class].

[[fvymv]][[GSDVG00460]][[acc-naming]]

ACC Naming
^^^^^^^^^^

The client container enables the application clients to use the Java
Naming and Directory Interface (JNDI) to look up Java EE services (such
as JMS resources, EJB components, web services, security, and so on.)
and to reference configurable parameters set at the time of deployment.

[[gbgfe]][[GSDVG00461]][[application-client-annotation]]

Application Client Annotation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Annotation is supported for the main class and the optional callback
handler class in application clients. For more information, see
"link:../application-deployment-guide/overview.html#GSDPG00320[Deployment Descriptors and Annotations]" in GlassFish
Server Open Source Edition Application Deployment Guide.

[[gavkg]][[GSDVG00462]][[java-web-start]]

Java Web Start
^^^^^^^^^^^^^^

Java Web Start allows your application client to be easily launched and
automatically downloaded and updated. It is enabled for all application
clients by default. For more information, see link:#gavmf[Using Java Web
Start].

[[gipjj]][[GSDVG00463]][[application-client-jar-file]]

Application Client JAR File
^^^^^^^^^^^^^^^^^^^^^^^^^^^

In GlassFish Server 5.0, the downloaded appclient JAR file is smaller
than in previous releases, with dependent classes in separate JAR files.
When copying the downloaded appclient to another location, make sure to
include the JAR files containing the dependent classes as well. You can
also use the `asadmin get-client-stubs` command to retrieve the
appclient and all associated application JAR files and place them in
another location.

[[beakv]][[GSDVG00160]][[developing-clients-using-the-acc]]

Developing Clients Using the ACC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section describes the procedure to develop, assemble, and deploy
client applications using the ACC.

The following topics are addressed here:

* link:#beakw[To Access an EJB Component From an Application Client]
* link:#beakx[To Access a JMS Resource From an Application Client]
* link:#gavmf[Using Java Web Start]
* link:#gipkt[Using the Embeddable ACC]
* link:#beaky[Running an Application Client Using the `appclient`
Script]
* link:#beakz[Using the `package-appclient` Script]
* link:#fvymy[The `client.policy` File]
* link:#gckgn[Using RMI/IIOP Over SSL]
* link:#ghbpc[Connecting to a Remote EJB Module Through a Firewall]
* link:#gipkj[Specifying a Splash Screen]
* link:#gjiec[Setting Login Retries]
* link:#gjpjt[Using Libraries with Application Clients]

[[beakw]][[GSDVG00072]][[to-access-an-ejb-component-from-an-application-client]]

To Access an EJB Component From an Application Client
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1.  In your client code, reference the EJB component by using an `@EJB`
annotation or by looking up the JNDI name as defined in the
`ejb-jar.xml` file. +
For more information about naming and lookups, see
link:jndi.html#beans[Accessing the Naming Context]. +
If load balancing is enabled as in Step link:#accejb8[7] and the EJB
components being accessed are in a different cluster, the endpoint list
must be included in the lookup, as follows: +
[source,oac_no_warn]
----
corbaname:host1:port1,host2:port2,.../NameService#ejb/jndi-name
----
2.  Define the `@EJB` annotations or the `ejb-ref` elements in the
`application-client.xml` file. Define the corresponding `ejb-ref`
elements in the `glassfish-application-client.xml` file. +
For more information on the `glassfish-application-client.xml` file, see
"link:../application-deployment-guide/dd-files.html#GSDPG00081[The glassfish-application-client.xml file]" in
GlassFish Server Open Source Edition Application Deployment Guide. For a
general explanation of how to map JNDI names using reference elements,
see link:jndi.html#beaoa[Mapping References].
3.  Deploy the application client and EJB component together in an
application. +
For more information on deployment, see the link:../application-deployment-guide/toc.html#GSDPG[GlassFish Server
Open Source Edition Application Deployment Guide]. To get the client JAR
file, use the `--retrieve` option of the `asadmin deploy` command. +
To retrieve the stubs and ties generated during deployment, use the
`asadmin get-client-stubs` command. For details, see the
link:../reference-manual/toc.html#GSRFM[GlassFish Server Open Source Edition Reference Manual].
4.  Ensure that the client JAR file includes the following files:
* A Java class to access the bean.
* `application-client.xml` - (optional) Java EE application client
deployment descriptor.
* `glassfish-application-client.xml` - (optional) GlassFish Server
specific client deployment descriptor. For information on the
`glassfish-application-client.xml` file, see "link:../application-deployment-guide/dd-files.html#GSDPG00081[The
glassfish-application-client.xml file]" in GlassFish Server Open Source
Edition Application Deployment Guide.
* The `MANIFEST.MF` file. This file contains a reference to the `main`
class, which states the complete package prefix and class name of the
Java client.
5.  Prepare the client machine. +
This step is not needed for Java Web Start. This step is not needed if
the client and server machines are the same. +
If you are using the `appclient` script, package the GlassFish Server
system files required to launch application clients on remote systems
using the `package-appclient` script, then retrieve the application
client itself using the `asadmin get-client-stubs` command. +
For more information, see link:#beakz[Using the `package-appclient`
Script] and the link:../reference-manual/toc.html#GSRFM[GlassFish Server Open Source Edition
Reference Manual].
6.  To access EJB components that are residing in a remote system, make
the following changes to the `sun-acc.xml` file or the `appclient`
script. This step is not needed for Java Web Start.
* Define the `target-server` element's `address` and `port` attributes
to reference the remote server machine and its ORB port. See
"link:../application-deployment-guide/dd-elements.html#GSDPG00284[target-server]" in GlassFish Server Open Source
Edition Application Deployment Guide.
* Use the `-targetserver` option of the appclient script to reference
the remote server machine and its ORB port. For more information, see
link:#beaky[Running an Application Client Using the `appclient` Script]. +
To determine the ORB port on the remote server, use the `asadmin get`
command. For example: +
[source,oac_no_warn]
----
asadmin --host rmtsrv get server-config.iiop-service.iiop-listener.iiop-listener1.port
----
For more information about the `asadmin get` command, see the
link:../reference-manual/toc.html#GSRFM[GlassFish Server Open Source Edition Reference Manual].
7.  [[accejb8]] +
To set up load balancing and failover of remote EJB references, define
at least two `target-server` elements in the `sun-acc.xml` file or the
`appclient` script. This step is not needed for Java Web Start. +
If the GlassFish Server instance on which the application client is
deployed participates in a cluster, the ACC finds all currently active
IIOP endpoints in the cluster automatically. However, a client should
have at least two endpoints specified for bootstrapping purposes, in
case one of the endpoints has failed. +
The `target-server` elements in the `sun-acc.xml` file specify one or
more IIOP endpoints used for load balancing. The `address` attribute is
an IPv4 address or host name, and the `port` attribute specifies the
port number. See "link:../application-deployment-guide/dd-elements.html#GSDPG00111[client-container]" in GlassFish
Server Open Source Edition Application Deployment Guide. +
The `--targetserver` option of the appclient script specifies one or
more IIOP endpoints used for load balancing. For more information, see
link:#beaky[Running an Application Client Using the `appclient` Script].

[[GSDVG555]]

Next Steps

* For instructions on running the application client, see
link:#gavmf[Using Java Web Start] or link:#beaky[Running an Application
Client Using the `appclient` Script].
* For more information about RMI-IIOP load balancing and failover, see
"link:../ha-administration-guide/rmi-iiop.html#GSHAG00013[RMI-IIOP Load Balancing and Failover]" in GlassFish
Server Open Source Edition High Availability Administration Guide.

[[beakx]][[GSDVG00073]][[to-access-a-jms-resource-from-an-application-client]]

To Access a JMS Resource From an Application Client
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1.  Create a JMS client. +
For detailed instructions on developing a JMS client, see
"https://javaee.github.io/tutorial/jms-examples.html[Java Message
Service Examples]" in The Java EE 8 Tutorial.
2.  Next, configure a JMS resource on the GlassFish Server. +
For information on configuring JMS resources, see
"link:../administration-guide/jms.html#GSADG00598[Administering JMS Connection Factories and
Destinations]" in GlassFish Server Open Source Edition Administration
Guide.
3.  Define the `@Resource` or `@Resources` annotations or the
`resource-ref` elements in the `application-client.xml` file. Define the
corresponding `resource-ref` elements in the
`glassfish-application-client.xml` file. +
For more information on the `glassfish-application-client.xml` file, see
"link:../application-deployment-guide/dd-files.html#GSDPG00081[The glassfish-application-client.xml file]" in
GlassFish Server Open Source Edition Application Deployment Guide. For a
general explanation of how to map JNDI names using reference elements,
see link:jndi.html#beaoa[Mapping References].
4.  Ensure that the client JAR file includes the following files:
* A Java class to access the resource.
* `application-client.xml` - (optional) Java EE application client
deployment descriptor.
* `glassfish-application-client.xml` - (optional) GlassFish Server
specific client deployment descriptor. For information on the
`glassfish-application-client.xml` file, see "link:../application-deployment-guide/dd-files.html#GSDPG00081[The
glassfish-application-client.xml file]" in GlassFish Server Open Source
Edition Application Deployment Guide.
* The `MANIFEST.MF` file. This file contains a reference to the `main`
class, which states the complete package prefix and class name of the
Java client.
5.  Prepare the client machine. +
This step is not needed for Java Web Start. This step is not needed if
the client and server machines are the same. +
If you are using the `appclient` script, package the GlassFish Server
system files required to launch application clients on remote systems
using the `package-appclient` script, then retrieve the application
client itself using the `asadmin get-client-stubs` command. +
For more information, see link:#beakz[Using the `package-appclient`
Script] and the link:../reference-manual/toc.html#GSRFM[GlassFish Server Open Source Edition
Reference Manual].
6.  Run the application client. +
See link:#gavmf[Using Java Web Start] or link:#beaky[Running an
Application Client Using the `appclient` Script].

[[gavmf]][[GSDVG00464]][[using-java-web-start]]

Using Java Web Start
^^^^^^^^^^^^^^^^^^^^

Java Web Start allows your application client to be easily launched and
automatically downloaded and updated. General information about Java Web
Start is available at
`http://www.oracle.com/technetwork/java/javase/tech/index-jsp-136112.html`.

The following topics are addressed here:

* link:#gavqb[Enabling and Disabling Java Web Start]
* link:#gavmk[Downloading and Launching an Application Client]
* link:#gavor[The Application Client URL]
* link:#gcjlg[Signing JAR Files Used in Java Web Start]
* link:#geqxg[Error Handling]
* link:#geqwd[Vendor Icon, Splash Screen, and Text]
* link:#gkmbs[Creating a Custom JNLP File]

[[gavqb]][[GSDVG00312]][[enabling-and-disabling-java-web-start]]

Enabling and Disabling Java Web Start
+++++++++++++++++++++++++++++++++++++

Java Web Start is enabled for all application clients by default.

The application developer or deployer can specify that Java Web Start is
always disabled for an application client by setting the value of the
`eligible` element to `false` in the `glassfish-application-client.xml`
file. See the link:../application-deployment-guide/toc.html#GSDPG[GlassFish Server Open Source Edition
Application Deployment Guide].

The GlassFish Server administrator can disable Java Web Start for a
previously deployed eligible application client using the `asadmin set`
command.

To disable Java Web Start for all eligible application clients in an
application, use the following command:

[source,oac_no_warn]
----
asadmin set applications.application.app-name.property.java-web-start-enabled="false"
----

To disable Java Web Start for a stand-alone eligible application client,
use the following command:

[source,oac_no_warn]
----
asadmin set applications.application.module-name.property.java-web-start-enabled="false"
----

Setting `java-web-start-enabled="true"` re-enables Java Web Start for an
eligible application client. For more information about the
`asadmin set` command, see the link:../reference-manual/toc.html#GSRFM[GlassFish Server Open Source
Edition Reference Manual].

[[gavmk]][[GSDVG00313]][[downloading-and-launching-an-application-client]]

Downloading and Launching an Application Client
+++++++++++++++++++++++++++++++++++++++++++++++

If Java Web Start is enabled for your deployed application client, you
can launch it for testing. Simply click on the Launch button next to the
application client or application's listing on the App Client Modules
page in the Administration Console.

On other machines, you can download and launch the application client
using Java Web Start in the following ways:

* Using a web browser, directly enter the URL for the application
client. See link:#gavor[The Application Client URL].
* Click on a link to the application client from a web page.
* Use the Java Web Start command `javaws`, specifying the URL of the
application client as a command line argument.
* If the application has previously been downloaded using Java Web
Start, you have additional alternatives.

** Use the desktop icon that Java Web Start created for the application
client. When Java Web Start downloads an application client for the
first time it asks you if such an icon should be created.

** Use the Java Web Start control panel to launch the application
client.

When you launch an application client, Java Web Start contacts the
server to see if a newer client version is available. This means you can
redeploy an application client without having to worry about whether
client machines have the latest version.

[[gavor]][[GSDVG00314]][[the-application-client-url]]

The Application Client URL
++++++++++++++++++++++++++

The default URL for an application or module generally is as follows:

[source,oac_no_warn]
----
http://host:port/context-root
----

The default URL for a stand-alone application client module is as
follows:

[source,oac_no_warn]
----
http://host:port/appclient-module-id
----

The default URL for an application client module embedded within an
application is as follows. Note that the relative path to the
application client JAR file is included.

[source,oac_no_warn]
----
http://host:port/application-id/appclient-path
----

If the context-root, appclient-module-id, or application-id is not
specified during deployment, the name of the JAR or EAR file without the
extension is used. If the application client module or application is
not in JAR or EAR file format, an appclient-module-id or application-id
is generated.

Regardless of how the context-root or id is determined, it is written to
the server log when you deploy the application. For details about
naming, see "link:../application-deployment-guide/overview.html#GSDPG00323[Naming Standards]" in GlassFish Server
Open Source Edition Application Deployment Guide.

To set a different URL for an application client, use the `context-root`
subelement of the `java-web-start-access` element in the
`glassfish-application-client.xml` file. This overrides the
appclient-module-id or application-id. See the link:../application-deployment-guide/toc.html#GSDPG[GlassFish
Server Open Source Edition Application Deployment Guide].

You can also pass arguments to the ACC or to the application client's
`main` method as query parameters in the URL. If multiple application
client arguments are specified, they are passed in the order specified.

A question mark separates the context root from the arguments.
Ampersands (`&`) separate the arguments and their values. Each argument
and each value must begin with `arg=`. Here is an example URL with a
`-color` argument for a stand-alone application client. The `-color`
argument is passed to the application client's `main` method.

[source,oac_no_warn]
----
http://localhost:8080/testClient?arg=-color&arg=red
----


[NOTE]
=======================================================================

If you are using the `javaws` URL command to launch Java Web Start with
a URL that contains arguments, enclose the URL in double quotes (`"`) to
avoid breaking the URL at the ampersand (`&`) symbol.

=======================================================================


Ideally, you should build your production application clients with
user-friendly interfaces that collect information which might otherwise
be gathered as command-line arguments. This minimizes the degree to
which users must customize the URLs that launch application clients
using Java Web Start. Command-line argument support is useful in a
development environment and for existing application clients that depend
on it.

[[gcjlg]][[GSDVG00315]][[signing-jar-files-used-in-java-web-start]]

Signing JAR Files Used in Java Web Start
++++++++++++++++++++++++++++++++++++++++

Java Web Start enforces a security sandbox. By default it grants any
application, including application clients, only minimal privileges.
Because Java Web Start applications can be so easily downloaded, Java
Web Start provides protection from potentially harmful programs that
might be accessible over the network. If an application requires a
higher privilege level than the sandbox permits, the code that needs
privileges must be in a JAR file that was signed.

When Java Web Start downloads such a signed JAR file, it displays
information about the certificate that was used to sign the JAR if that
certificate is not trusted. It then asks you whether you want to trust
that signed code. If you agree, the code receives elevated permissions
and runs. If you reject the signed code, Java Web Start does not start
the downloaded application.

Your first Java Web Start launch of an application client is likely to
involve this prompting because by default GlassFish Server uses a
self-signed certificate that is not linked to a trusted authority.

The GlassFish Server serves two types of signed JAR files in response to
Java Web Start requests. One type is a JAR file installed as part of the
GlassFish Server, which starts an application client during a Java Web
Start launch: as-install`/lib/gf-client.jar`.

The other type is a generated application client JAR file. As part of
deployment, the GlassFish Server generates a new application client JAR
file that contains classes, resources, and descriptors needed to run the
application client on end-user systems. When you deploy an application
with the `asadmin deploy` command's `--retrieve` option, use the
`asadmin get-client-stubs` command, or select the Generate RMIStubs
option from the EJB Modules deployment page in the Administration
Console, this is one of the JAR files retrieved to your system. Because
application clients need access beyond the minimal sandbox permissions
to work in the Java Web Start environment, the generated application
client JAR file must be signed before it can be downloaded to and
executed on an end-user system.

A JAR file can be signed automatically or manually.

The following topics are addressed here:

* link:#gcjmd[Automatically Signing JAR Files]
* link:#gcjlr[Using the `jar-signing-alias` Deployment Property]

[[gcjmd]][[GSDVG00038]][[automatically-signing-jar-files]]

Automatically Signing JAR Files

The GlassFish Server automatically creates a signed version of the
required JAR file if none exists. When a Java Web Start request for the
`gf-client.jar` file arrives, the GlassFish Server looks for
domain-dir`/java-web-start/gf-client.jar`. When a request for an
application's generated application client JAR file arrives, the
GlassFish Server looks in the directory
domain-dir`/java-web-start/`app-name for a file with the same name as
the generated JAR file created during deployment.

In either case, if the requested signed JAR file is absent or older than
its unsigned counterpart, the GlassFish Server creates a signed version
of the JAR file automatically and deposits it in the relevant directory.
Whether the GlassFish Server just signed the JAR file or not, it serves
the file from the domain-dir`/java-web-start` directory tree in response
to the Java Web Start request.

To sign these JAR files, by default the GlassFish Server uses its
self-signed certificate. When you create a new domain, either by
installing the GlassFish Server or by using the `asadmin create-domain`
command, the GlassFish Server creates a self-signed certificate and adds
it to the domain's key store.

A self-signed certificate is generally untrustworthy because no
certification authority vouches for its authenticity. The automatic
signing feature uses the same certificate to create all required signed
JAR files.

Starting with Java SE 7 Update 21, stricter security is enforced for
applications launched using Java Web Start. Application users will see
various security messages, depending on their Java security settings. If
Java security is set to Very High on their systems, users will not be
able to launch application clients signed using the GlassFish Server
self-signed certificate.

To minimize impacts to application users, all Java Web Start
applications should be signed with a trusted certificate instead of the
GlassFish Server self-signed certificate. If you use the GlassFish
Server Java Web Start feature or deploy applications that provide their
own Java Web Start applications, perform the following steps:

1.  Obtain a trusted certificate from a certification authority if your
organization does not already have one.
2.  Stop GlassFish Server.
3.  Replace the GlassFish Server self-signed certificate with the
trusted certificate by importing the trusted certificate into the
GlassFish Server keystore using the `s1as` alias. By default, the
keystore is located at domain-dir`/config/keystore.jks`. +
For more information about importing a trusted certificate into the
domain keystore, see "link:../security-guide/system-security.html#GSSCG00147[Administering JSSE Certificates]"
in GlassFish Server Open Source Edition Security Guide.
4.  Delete any signed JARs already generated by GlassFish Server:
1.  At the command prompt, type: +
`rm -rf` domain-dir`/java_web_start`
2.  For each application that contains an application client launched
using Java Web Start, type: +
`rm -rf` domain-dir`/generated/xml/`app-name`/signed`
3.  Restart GlassFish Server.
5.  Ensure that the Java security setting on user systems is set to Very
High.

After you perform these steps, the first time a user launches an
application client on their system, Java Web Start detects that the
server's signed JARs are newer than those cached on the user's system
and downloads them again. This happens on the first launch only,
regardless of the client. Even though the application client is now
signed using a trusted certificate, users will again be asked whether to
trust the downloaded application and can choose to skip that prompt for
future launches.

[[gcjlr]][[GSDVG00039]][[using-the-jar-signing-alias-deployment-property]]

Using the `jar-signing-alias` Deployment Property

The `asadmin deploy` command property `jar-signing-alias` specifies the
alias for the security certificate with which the application client
container JAR file is signed.

Java Web Start won't execute code requiring elevated permissions unless
it resides in a JAR file signed with a certificate that the user's
system trusts. For your convenience, GlassFish Server signs the JAR file
automatically using the self-signed certificate from the domain, `s1as`.
Java Web Start then asks the user whether to trust the code and displays
the GlassFish Server certificate information.

To sign this JAR file with a different certificate, first add the
certificate to the domain keystore. You can use a certificate from a
trusted authority, which avoids the Java Web Start prompt. To add a
certificate to the domain keystore, see "link:../security-guide/system-security.html#GSSCG00147[Administering
JSSE Certificates]" in GlassFish Server Open Source Edition Security
Guide.

Next, deploy your application using the `jar-signing-alias` property.
For example:

[source,oac_no_warn]
----
asadmin deploy --property jar-signing-alias=MyAlias MyApp.ear
----

For more information about the `asadmin deploy` command, see the
link:../reference-manual/toc.html#GSRFM[GlassFish Server Open Source Edition Reference Manual].

[[geqxg]][[GSDVG00316]][[error-handling]]

Error Handling
++++++++++++++

When an application client is launched using Java Web Start, any error
that the application client logic does not catch and handle is written
to `System.err` and displayed in a dialog box. This display appears if
an error occurs even before the application client logic receives
control. It also appears if the application client code does not catch
and handle errors itself.

[[geqwd]][[GSDVG00317]][[vendor-icon-splash-screen-and-text]]

Vendor Icon, Splash Screen, and Text
++++++++++++++++++++++++++++++++++++

To specify a vendor-specific icon, splash screen, text string, or a
combination of these for Java Web Start download and launch screens, use
the `vendor` element in the `glassfish-application-client.xml` file. The
complete format of this element's data is as follows:

[source,oac_no_warn]
----
<vendor>icon-image-URI::splash-screen-image-URI::vendor-text</vendor>
----

The following example vendor element contains an icon, a splash screen,
and a text string:

[source,oac_no_warn]
----
<vendor>images/icon.jpg::otherDir/splash.jpg::MyCorp, Inc.</vendor>
----

The following example vendor element contains an icon and a text string:

[source,oac_no_warn]
----
<vendor>images/icon.jpg::MyCorp, Inc.</vendor>
----

The following example vendor element contains a splash screen and a text
string; note the initial double colon:

[source,oac_no_warn]
----
<vendor>::otherDir/splash.jpg::MyCorp, Inc.</vendor>
----

The following example vendor element contains only a text string:

[source,oac_no_warn]
----
<vendor>MyCorp, Inc.</vendor>
----

The default value is the text string `Application Client`.

For more information about the `glassfish-application-client.xml` file,
see the link:../application-deployment-guide/toc.html#GSDPG[GlassFish Server Open Source Edition Application
Deployment Guide].

You can also specify a vendor-specific icon, splash screen, text string,
or a combination by using a custom JNLP file; see link:#gkmbs[Creating a
Custom JNLP File].

[[gkmbs]][[GSDVG00318]][[creating-a-custom-jnlp-file]]

Creating a Custom JNLP File
+++++++++++++++++++++++++++

You can partially customize the Java Network Launching Protocol (JNLP)
file that GlassFish Server uses for Java Web Start.

The following topics are addressed here:

* link:#gkmco[Specifying the JNLP File in the Deployment Descriptor]
* link:#gkmbq[Referring to JAR Files from the JNLP File]
* link:#gkmbt[Referring to Other JNLP Files]
* link:#gkmbr[Combining Custom and Automatically Generated Content]

For more information about JNLP, see the
http://java.sun.com/javase/technologies/desktop/javawebstart/download-spec.html[Java
Web Start Architecture JNLP Specification and API Documentation]
(`http://java.sun.com/javase/technologies/desktop/javawebstart/download-spec.html`).

[[gkmco]][[GSDVG00040]][[specifying-the-jnlp-file-in-the-deployment-descriptor]]

Specifying the JNLP File in the Deployment Descriptor

To specify a custom JNLP file for Java Web Start, use the `jnlp-doc`
element in the `glassfish-application-client.xml` file. If none is
specified, a default JNLP file is generated.

The value of the `jnlp-doc` element is a relative path with the
following format:

[source,oac_no_warn]
----
[path-to-JAR-in-EAR!]path-to-JNLP-in-JAR
----

The default path-to-JAR-in-EAR is the current application client JAR
file. For example, if the JNLP file is in the application client JAR
file at `custom/myInfo.jnlp`, the element value would look like this:

[source,oac_no_warn]
----
<java-web-start-access>
   <jnlp-doc>custom/myInfo.jnlp</jnlp-doc>
</java-web-start-access>
----

If the application client is inside an EAR file, you can place the
custom JNLP file inside another JAR file in the EAR. For example, if the
JNLP file is in a JAR file at `other/myLib.jar`, the element value would
look like this, with an exclamation point (`!`) separating the path to
the JAR from the path in the JAR:

[source,oac_no_warn]
----
<java-web-start-access>
   <jnlp-doc>other/myLib.jar!custom/myInfo.jnlp</jnlp-doc>
</java-web-start-access>
----

For more information about the `glassfish-application-client.xml` file,
see the GlassFish Server Open Source Edition Application Deployment
Guide.

[[gkmbq]][[GSDVG00041]][[referring-to-jar-files-from-the-jnlp-file]]

Referring to JAR Files from the JNLP File

As with any JNLP document, the custom JNLP file can refer to JAR files
the application client requires.

Do not specify every JAR on which the client depends. GlassFish Server
automatically handles JAR files that the Java EE specification requires
to be available to the application client. This includes JAR files
listed in the application client JAR file's manifest `Class-Path` and
JAR files in the EAR file's library directory (if any) and their
transitive closures. The custom JNLP file should specify only those JAR
files the client needs that GlassFish Server would not otherwise
include.

Package these JAR files in the EAR file, as with any JAR file required
by an application client. Use relative URIs in the `<jar href="...">`
and `<nativelib href="...">` elements to point to the JAR files. The
codebase that GlassFish Server assigns for the final client JNLP file
corresponds to the top level of the EAR file. Therefore, relative `href`
references correspond directly to the relative path to the JAR files
within the EAR file.

Neither the Java EE specification nor GlassFish Server supports
packaging JAR files inside the application client JAR file itself.
Nothing prevents this, but GlassFish Server does no special processing
of such JAR files. They do not appear in the runtime class path and they
cannot be referenced from the custom JNLP file.

[[gkmbt]][[GSDVG00042]][[referring-to-other-jnlp-files]]

Referring to Other JNLP Files

The JNLP file can also refer to other custom JNLP files using
`<extension href="..."/>` elements. To be consistent with relative
`href` references to JAR files, the relative `href` references to JNLP
files are resolved within the EAR file. You can place these JNLP files
directly in the EAR file or inside JAR files that the EAR file contains.
Use one of these formats for these `href` references:

[source,oac_no_warn]
----
[path-to-JAR-in-EAR!]path-to-JNLP-in-JAR

path-to-JNLP-in-EAR
----

Note that these formats are not equivalent to the format of the
`jnlp-doc` element in the `glassfish-application-client.xml` file.

These formats follow the standard entry-within-a-JAR URI syntax and
semantics. Support for this syntax comes from the automated Java Web
Start support in GlassFish Server. This is not a feature of Java Web
Start or the JNLP standard.

[[gkmbr]][[GSDVG00043]][[combining-custom-and-automatically-generated-content]]

Combining Custom and Automatically Generated Content

GlassFish Server recognizes these types of content in the JNLP file:

* Owned — GlassFish Server owns the content and ignores any custom
content
* Merged — Automatically generated content and custom content are merged
* Defaulted — Custom content is used if present, otherwise default
content is provided

You can compose a complete JNLP file and package it with the application
client. GlassFish Server then combines it with its automatically
generated JNLP file. You can also provide content that only adds to or
replaces what GlassFish Server generates. The custom content must
conform to the general structure of the JNLP format so that GlassFish
Server can properly place it in the final JNLP file.

For example, to specify a single native library to be included only for
Windows systems, the new element to add might be as follows:

[source,oac_no_warn]
----
<nativelib href="windows/myLib.jar"/>
----

However, you must indicate where in the overall document this element
belongs. The actual custom JNLP file should look like this:

[source,oac_no_warn]
----
<jnlp>
   <resources os="Windows">
      <nativelib href="windows/myLib.jar"/>
   </resources>
</jnlp>
----

GlassFish Server provides default `<information>` and `<resources>`
elements, without specifying attributes such as `os`, `arch`,
`platform`, or `locale`. GlassFish Server merges its own content within
those elements with custom content under those elements. Further, you
can provide your own `<information>` and `<resources>` elements (and
fragments within them) that specify at least one of these attributes.

In general, you can perform the following customizations:

* Override the GlassFish Server defaults for the child elements of
`<information>` elements that have no attribute settings for `os`,
`arch`, `platform`, and `locale`. Among these child elements are
`<title>`, `<vendor>`, `<description>`, `<icon>`, and so on.
* Add `<information>` elements with `os`, `arch`, `platform`, or
`locale` settings. You can also add child elements.
* Add child elements of `<resources>` elements that have no attribute
settings for `os`, `arch`, or `locale`. Among these child elements are
`<jar>`, `<property>`, `<nativelib>`, and so on. You can also customize
attributes of the `<java>` child element.
* Add `<resources>` elements that specify at least one of `os`, `arch`,
or `locale`. You can also add child elements.

This flexibility allows you to add JAR files to the application
(including platform-specific native libraries) and set properties to
control the behavior of your application clients.

The following tables provide more detail about what parts of the JNLP
file you can add to and modify.

[[GSDVG556]][[sthref24]][[gkmbk]]


Table 10-1 Owned JNLP File Content

[width="100%",cols="32%,68%",options="header",]
|=======================================================================
|JNLP File Fragment |Description
a|
[source,oac_no_warn]
----
<jnlp codebase="xxx" ...>
----

 |GlassFish Server controls this content for application clients
packaged in EAR files. The developer controls this content for
application clients packaged in WAR files.

a|
[source,oac_no_warn]
----
<jnlp href="xxx" ...>
----

 |GlassFish Server controls this content for application clients
packaged in EAR files. The developer controls this content for
application clients packaged in WAR files.

a|
[source,oac_no_warn]
----
<jnlp>
  <security>
----

 |GlassFish Server must control the permissions requested for each JNLP
file. All permissions are needed for the main file, which launches the
ACC. The permissions requested for other JNLP documents depend on
whether the JAR files referenced in those documents are signed.

a|
[source,oac_no_warn]
----
<jnlp>
  <application-desc>
    <argument> ...
----

 |GlassFish Server sets the `main-class` and the arguments to be passed
to the client.
|=======================================================================


[[GSDVG557]][[sthref25]][[gkmci]]


Table 10-2 Defaulted JNLP File Content

[width="100%",cols="39%,61%",options="header",]
|=======================================================================
|JNLP File Fragment |Description
a|
[source,oac_no_warn]
----
<jnlp spec="xxx" ...>
----

 |Specifies the JNLP specification version.

a|
[source,oac_no_warn]
----
<jnlp>
  <information [no-attributes]>
----

 |Specifies the application title, vendor, home page, various
description text values, icon images, and whether offline execution is
allowed.

a|
[source,oac_no_warn]
----
<jnlp>
  <resources [no-attributes]>
    <java version="xxx" 
        java-vm-args="yyy" ...>
----

 |Specifies the Java SE version or selected VM parameter settings.
|=======================================================================


[[GSDVG558]][[sthref26]][[gkmcc]]


Table 10-3 Merged JNLP File Content

[width="100%",cols="37%,63%",options="header",]
|=======================================================================
|JNLP File Fragment |Description
a|
[source,oac_no_warn]
----
<jnlp>
  <information [attributes]>
----

 |You can specify one or more of the `os`, `arch`, `platform`, and
`locale` attributes for the `<information>` element. You can also
specify child elements; GlassFish Server provides no default children.

a|
[source,oac_no_warn]
----
<jnlp>
  <resources [attributes]>
----

 |You can specify one or more of the `os`, `arch`, `platform`, and
`locale` attributes for the `<resources>` element. You can also specify
child elements; GlassFish Server provides no default children.

a|
[source,oac_no_warn]
----
<jnlp>
  <resources [no-attributes]>
    <jar ...>
----

 |Adds JAR files to be included in the application to the JAR files
provided by GlassFish Server.

a|
[source,oac_no_warn]
----
<jnlp>
  <resources [no-attributes]>
    <nativelib ...>
----

 |Adds native libraries to be included in the application. Each entry in
a JAR listed in a `<nativelib>` element must be a native library for the
correct platform. The full syntax of the `<nativelib>` element lets the
developer specify the platform for that native library.

a|
[source,oac_no_warn]
----
<jnlp>
  <resources [no-attributes]>
    <property ...>
----

 |Adds system properties to be included in the application to the system
properties defined by GlassFish Server.

a|
[source,oac_no_warn]
----
<jnlp>
  <resources [no-attributes]>
    <extension ...>
----

 |Specifies another custom JNLP file.

a|
[source,oac_no_warn]
----
<jnlp>
  <component-desc ...>
----

 |Includes another custom JNLP file that specifies a component
extension.

a|
[source,oac_no_warn]
----
<jnlp>
  <installer-desc ...>
----

 |Includes another custom JNLP file that specifies an installer
extension.
|=======================================================================


[[gipkt]][[GSDVG00465]][[using-the-embeddable-acc]]

Using the Embeddable ACC
^^^^^^^^^^^^^^^^^^^^^^^^

You can embed the ACC into your application client. If you place the
as-install`/lib/gf-client.jar` file in your runtime classpath, your
application creates the ACC after your application code has started,
then requests that the ACC start the application client portion. The
basic model for coding is as follows:

1.  Create a builder object.
2.  Operate on the builder to configure the ACC.
3.  Obtain a new ACC instance from the builder.
4.  Present a client archive or class to the ACC instance.
5.  Start the client running within the newly created ACC instance.

Your code should follow this general pattern:

[source,oac_no_warn]
----
// one TargetServer for each ORB endpoint for bootstrapping
TargetServer[] servers = ...;

// Get a builder to set up the ACC
AppClientContainer.Builder builder = AppClientContainer.newBuilder(servers);

// Fine-tune the ACC's configuration. Note ability to "chain" invocations.
builder.callbackHandler("com.acme.MyHandler").authRealm("myRealm"); // Modify config

// Get a container for a client.
URI clientURI = ...; // URI to the client JAR
AppClientContainer acc = builder.newContainer(clientURI);

or

Class mainClass = ...;
AppClientContainer acc = builder.newContainer(mainClass);

// In either case, start the client running.
String[] appArgs = ...;
acc.startClient(appArgs); // Start the client

...

acc.close(); // close the ACC(optional)
----

The ACC loads the application client's `main` class, performs any
required injection, and transfers control to the `static main` method.
The ACC's `run` method returns to the calling application as soon as the
client's `main` method returns to the ACC.

If the application client's `main` method starts any asynchronous
activity, that work continues after the ACC returns. The ACC has no
knowledge of whether the client's `main` method triggers asynchronous
work. Therefore, if the client causes work on threads other than the
calling thread, and if the embedding application needs to know when the
client's asynchronous work completes, the embedding application and the
client must agree on how this happens.

The ACC's shutdown handling is invoked from the ACC's `close` method.
The calling application can invoke `acc.close()` to close down any
services started by the ACC. If the application client code started any
asynchronous activity that might still depend on ACC services, invoking
`close` before that asynchronous activity completes could cause
unpredictable and undesirable results. The shutdown handling is also run
automatically at VM shutdown if the code has not invoked `close` before
then.

The ACC does not prevent the calling application from creating or
running more than one ACC instance during a single execution of the
application either serially or concurrently. However, other services
used by the ACC (transaction manager, security, ORB, and so on) might or
might not support such serial or concurrent reuse.

[[beaky]][[GSDVG00466]][[running-an-application-client-using-the-appclient-script]]

Running an Application Client Using the `appclient` Script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To run an application client, you can launch the ACC using the
`appclient` script, whether or not Java Web Start is enabled. This is
optional. This script is located in the as-install`/bin` directory. For
details, see the link:../reference-manual/toc.html#GSRFM[GlassFish Server Open Source Edition
Reference Manual].

[[beakz]][[GSDVG00467]][[using-the-package-appclient-script]]

Using the `package-appclient` Script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can package the GlassFish Server system files required to launch
application clients on remote systems into a single JAR file using the
`package-appclient` script. This is optional. This script is located in
the as-install`/bin` directory. For details, see the
link:../reference-manual/toc.html#GSRFM[GlassFish Server Open Source Edition Reference Manual].

[[fvymy]][[GSDVG00468]][[the-client.policy-file]]

The `client.policy` File
^^^^^^^^^^^^^^^^^^^^^^^^

The `client.policy` file is the J2SE policy file used by the application
client. Each application client has a `client.policy` file. The default
policy file limits the permissions of Java EE deployed application
clients to the minimal set of permissions required for these
applications to operate correctly. If an application client requires
more than this default set of permissions, edit the `client.policy` file
to add the custom permissions that your application client needs. Use
the J2SE standard policy tool or any text editor to edit this file.

For more information on using the J2SE policy tool, see
`http://docs.oracle.com/javase/tutorial/security/tour2/index.html`.

For more information about the permissions you can set in the
`client.policy` file, see
`http://docs.oracle.com/javase/7/docs/technotes/guides/security/permissions.html`.

[[gckgn]][[GSDVG00469]][[using-rmiiiop-over-ssl]]

Using RMI/IIOP Over SSL
^^^^^^^^^^^^^^^^^^^^^^^

You can configure RMI/IIOP over SSL in two ways: using a username and
password, or using a client certificate.

To use a username and password, configure the `ior-security-config`
element in the `glassfish-ejb-jar.xml` file. The following configuration
establishes SSL between an application client and an EJB component using
a username and password. The user has to login to the ACC using either
the `sun-acc.xml` mechanism or the
link:securing-apps.html#beacm[Programmatic Login Using the
ProgrammaticLogin Class] mechanism.

[source,oac_no_warn]
----
<ior-security-config>
  <transport-config>
    <integrity>required</integrity>
    <confidentiality>required</confidentiality>
    <establish-trust-in-target>supported</establish-trust-in-target>
    <establish-trust-in-client>none</establish-trust-in-client>
  </transport-config>
  <as-context>
    <auth-method>username_password</auth-method>
    <realm>default</realm>
    <required>true</required>
  </as-context>
 <sas-context>
    <caller-propagation>none</caller-propagation>
 </sas-context>
</ior-security-config>
----

For more information about the `glassfish-ejb-jar.xml` and `sun-acc.xml`
files, see the link:../application-deployment-guide/toc.html#GSDPG[GlassFish Server Open Source Edition
Application Deployment Guide].

To use a client certificate, configure the `ior-security-config` element
in the `glassfish-ejb-jar.xml` file. The following configuration
establishes SSL between an application client and an EJB component using
a client certificate.

[source,oac_no_warn]
----
<ior-security-config>
  <transport-config>
    <integrity>required</integrity>
    <confidentiality>required</confidentiality>
    <establish-trust-in-target>supported</establish-trust-in-target>
    <establish-trust-in-client>required</establish-trust-in-client>
  </transport-config>
  <as-context>
    <auth-method>none</auth-method>
    <realm>default</realm>
    <required>false</required>
  </as-context>
  <sas-context>
    <caller-propagation>none</caller-propagation>
  </sas-context>
</ior-security-config>
----

To use a client certificate, you must also specify the system properties
for the keystore and truststore to be used in establishing SSL. To use
SSL with the Application Client Container (ACC), you need to set these
system properties in one of the following ways:

* Use the new syntax of the `appclient` script and specify the system
properties as JVM options. See link:#beaky[Running an Application Client
Using the `appclient` Script].
* Set the environment variable `VMARGS` in the shell. For example, in
the `ksh` or `bash` shell, the command to set this environment variable
would be as follows: +
[source,oac_no_warn]
----
export VMARGS="-Djavax.net.ssl.keyStore=${keystore.db.file} 
-Djavax.net.ssl.trustStore=${truststore.db.file} 
-Djavax.net.ssl.keyStorePass word=${ssl.password} 
-Djavax.net.ssl.trustStorePassword=${ssl.password}"
----
* Optionally, you can set the `env` element using Ant. For example: +
[source,oac_no_warn]
----
<target name="runclient">
  <exec executable="${S1AS_HOME}/bin/appclient">
    <env key="VMARGS" value=" -Djavax.net.ssl.keyStore=${keystore.db.file} 
      -Djavax.net.ssl.trustStore=${truststore.db.file} 
      -Djavax.net.ssl.keyStorePasword=${ssl.password} 
      -Djavax.net.ssl.trustStorePassword=${ssl.password}"/>
    <arg value="-client"/>
    <arg value="${appClient.jar}"/>
  </exec>
</target>
----

[[ghbpc]][[GSDVG00470]][[connecting-to-a-remote-ejb-module-through-a-firewall]]

Connecting to a Remote EJB Module Through a Firewall
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To deploy and run an application client that connects to an EJB module
on a GlassFish Server instance that is behind a firewall, you must set
ORB Virtual Address Agent Implementation (ORBVAA) options. Use the
`asadmin create-jvm-options` command as follows:

[source,oac_no_warn]
----
asadmin create-jvm-options -Dcom.sun.corba.ee.ORBVAAHost=public-IP-adress
asadmin create-jvm-options -Dcom.sun.corba.ee.ORBVAAPort=public-port
asadmin create-jvm-options 
-Dcom.sun.corba.ee.ORBUserConfigurators.com.sun.corba.ee.impl.plugin.hwlb.VirtualAddressAgentImpl=x
----

Set the `ORBVAAHost` and `ORBVAAPort` options to the host and port of
the public address. The `ORBUserConfigurators` option tells the ORB to
create an instance of the `VirtualAddressAgentImpl` class and invoke the
`configure` method on the resulting object, which must implement the
com.sun.corba.ee.spi.orb.ORBConfigurator interface. The
`ORBUserConfigurators` value doesn't matter. Together, these options
create an ORB that in turn creates `Object` references (the underlying
implementation of remote EJB references) containing the public address,
while the ORB listens on the private address specified for the IIOP port
in the GlassFish Server configuration.

[[gipkj]][[GSDVG00471]][[specifying-a-splash-screen]]

Specifying a Splash Screen
^^^^^^^^^^^^^^^^^^^^^^^^^^

Java SE 6 offers splash screen support, either through a Java
command-line option or a manifest entry in the application's JAR file.
To take advantage of this Java SE feature in your application client,
you can do one of the following:

* Create the appclient JAR file so that its manifest contains a
`SplashScreen-Image` entry that specifies the path to the image in the
client. The `java` command displays the splash screen before starting
the ACC or your client, just as with any Java application.
* Use the new `appclient ... -jar` launch format, using the `-splash`
command-line option at runtime or the `SplashScreen-Image` manifest
entry at development time. See link:#beaky[Running an Application Client
Using the `appclient` Script].
* In the environment that runs the `appclient` script, set the `VMOPTS`
environment variable to include the `-splash` option before invoking the
`appclient` script to launch the client.
* Build an application client that uses the embeddable ACC feature and
specify the splash screen image using one of the following:

** The `-splash` option of the `java` command

** `SplashScreen-Image` in the manifest for your program (not the
manifest for the application client) +
See link:#gipkt[Using the Embeddable ACC].

During application (EAR file) deployment, the GlassFish Server generates
façade JAR files, one for the application and one for each application
client in the application. During application client module deployment,
the GlassFish Server generates a single facade JAR for the application
client. The `appclient` script supports splash screens inside the
application client JAR only if you launch an application client facade
or appclient client JAR. If you launch the facade for an application or
the undeployed application itself, the `appclient` script cannot take
advantage of the Java SE 6 splash screen feature.

[[gjiec]][[GSDVG00472]][[setting-login-retries]]

Setting Login Retries
^^^^^^^^^^^^^^^^^^^^^

You can set a JVM option using the `appclient` script that determines
the number of login retries allowed. This option is
`-Dorg.glassfish.appclient.acc.maxLoginRetries=`n where n is a positive
integer. The default number of retries is 3.

This retry loop happens when the ACC attempts to perform injection if
you annotated the client's `main` class (for example, using
`@Resource`). If instead of annotations your client uses the
`InitialContext` explicitly to look up remote resources, the retry loop
does not apply. In this case, you could write logic to catch an
exception around the lookup and retry explicitly.

For details about the `appclient` script syntax, see the
link:../reference-manual/toc.html#GSRFM[GlassFish Server Open Source Edition Reference Manual].

[[gjpjt]][[GSDVG00473]][[using-libraries-with-application-clients]]

Using Libraries with Application Clients
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Libraries field in the Administration Console's deployment page and
the `--libraries` option of the `asadmin deploy` command do not apply to
application clients. Neither do the as-install`/lib`, domain-dir`/lib`,
and domain-dir`/lib/classes` directories comprising the Common Class
Loader. These apply only to applications and modules deployed to the
server. For more information, see link:class-loaders.html#beade[Class
Loaders].

To use libraries with an application client, package the application
client in an application (EAR file). Then, either place the libraries in
the `/lib` directory of the EAR file or specify their location in the
application client JAR file's manifest `Class-Path`.

[[gkusn]][[GSDVG00161]][[developing-clients-without-the-acc]]

Developing Clients Without the ACC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section describes the procedure to create, assemble, and deploy a
Java-based client that is not packaged using the Application Client
Container (ACC).

The following topics are addressed here:

* link:#gkusp[To access an EJB component from a stand-alone client]
* link:#gkutw[To access an EJB component from a server-side module]
* link:#gkuqa[To access a JMS resource from a stand-alone client]

For information about using the ACC, see link:#beakv[Developing Clients
Using the ACC].

[[gkusp]][[GSDVG00074]][[to-access-an-ejb-component-from-a-stand-alone-client]]

To access an EJB component from a stand-alone client
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1.  In your client code, instantiate the `InitialContext`: +
[source,oac_no_warn]
----
InitialContext ctx = new InitialContext();
----
It is not necessary to explicitly instantiate a naming context that
points to the CosNaming service.
2.  In the client code, look up the home object by specifying the JNDI
name of the home object. +
Here is an EJB 2.x example: +
[source,oac_no_warn]
----
Object ref = ctx.lookup("jndi-name");
BeanAHome = (BeanAHome)PortableRemoteObject.narrow(ref,BeanAHome.class);
----
Here is an EJB 3.x example: +
[source,oac_no_warn]
----
BeanRemoteBusiness bean =(BeanRemoteBusiness) ctx.lookup("com.acme.BeanRemoteBusiness");
----
If load balancing is enabled as in Step link:#CIHJADHD[6] and the EJB
components being accessed are in a different cluster, the endpoint list
must be included in the lookup, as follows: +
[source,oac_no_warn]
----
corbaname:host1:port1,host2:port2,.../NameService#ejb/jndi-name
----
For more information about naming and lookups, see
link:jndi.html#beans[Accessing the Naming Context].
3.  Deploy the EJB component to be accessed. +
For more information on deployment, see "link:../application-deployment-guide/overview.html#GSDPG00063[About
Deployment Tools]" in GlassFish Server Open Source Edition Application
Deployment Guide.
4.  Copy the as-install`/lib/gf-client.jar` file to the client machine
and include it in the classpath on the client side. +
The `gf-client.jar` file references GlassFish Server JAR files in its
`MANIFEST.MF` file. If there is no GlassFish Server installation on the
client machine, you must also copy the as-install`/modules` directory to
the client machine and maintain its directory structure relative to the
as-install`/lib/gf-client.jar` file. Or you can use the
`package-appclient` script; see link:#beakz[Using the
`package-appclient` Script].
5.  To access EJB components that are residing in a remote system, set
the following system properties for the Java Virtual Machine startup
options: +
[source,oac_no_warn]
----
-Dorg.omg.CORBA.ORBInitialHost=${ORBhost}
-Dorg.omg.CORBA.ORBInitialPort=${ORBport}
----
Here ORBhost is the GlassFish Server hostname and ORBport is the ORB
port number (default is `3700` for the default server instance, named
`server`). +
You can use the `asadmin get` command to get the IIOP port numbers. For
example: +
[source,oac_no_warn]
----
asadmin get "configs.config.server-config.iiop-service.iiop-listener.orb-listener-1.*"
----
6.  [[CIHJADHD]] +
To set up load balancing and remote EJB reference failover, define the
`endpoints` property as follows: +
[source,oac_no_warn]
----
-Dcom.sun.appserv.iiop.endpoints=host1:port1,host2:port2,...
----
The `endpoints` property specifies a comma-separated list of one or more
IIOP endpoints used for load balancing. An IIOP endpoint is in the form
host`:`port, where the host is an IPv4 address or host name, and the
port specifies the port number. +
If the `endpoints` list is changed dynamically in the code, the new list
is used only if a new `InitialContext` is created.
7.  Make sure the `etc/hosts` file on the client machine maps the
GlassFish Server hostname and external IP address.
8.  Run the stand-alone client. +
As long as the client environment is set appropriately and the JVM is
compatible, you merely need to run the `main` class.

[[gkutw]][[GSDVG00075]][[to-access-an-ejb-component-from-a-server-side-module]]

To access an EJB component from a server-side module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A server-side module can be a servlet, another EJB component, or another
type of module.

1.  [[CIHFIJDC]] +
In your module code, instantiate the `InitialContext`: +
[source,oac_no_warn]
----
InitialContext ctx = new InitialContext();
----
It is not necessary to explicitly instantiate a naming context that
points to the CosNaming service. +
To set up load balancing and remote EJB reference failover, define the
`endpoints` property as follows: +
[source,oac_no_warn]
----
Hashtable env = new Hashtable();
env.put("com.sun.appserv.iiop.endpoints","host1:port1,host2:port2,...");
InitialContext ctx = new InitialConext(env);
----
The `endpoints` property specifies a comma-separated list of one or more
IIOP endpoints used for load balancing. An IIOP endpoint is in the form
host`:`port, where the host is an IPv4 address or host name, and the
port specifies the port number. +
You can use the `asadmin get` command to get the IIOP port numbers. For
example: +
[source,oac_no_warn]
----
asadmin get "configs.config.server-config.iiop-service.iiop-listener.orb-listener-1.*"
----
If the `endpoints` list is changed dynamically in the code, the new list
is used only if a new `InitialContext` is created.
2.  In the module code, look up the home object by specifying the JNDI
name of the home object. +
Here is an EJB 2.x example: +
[source,oac_no_warn]
----
Object ref = ctx.lookup("jndi-name");
BeanAHome = (BeanAHome)PortableRemoteObject.narrow(ref,BeanAHome.class);
----
Here is an EJB 3.x example: +
[source,oac_no_warn]
----
BeanRemoteBusiness bean =(BeanRemoteBusiness) ctx.lookup("com.acme.BeanRemoteBusiness");
----
If load balancing is enabled as in Step link:#CIHFIJDC[1] and the EJB
components being accessed are in a different cluster, the endpoint list
must be included in the lookup, as follows: +
[source,oac_no_warn]
----
corbaname:host1:port1,host2:port2,.../NameService#ejb/jndi-name
----
For more information about naming and lookups, see
link:jndi.html#beans[Accessing the Naming Context].
3.  Deploy the EJB component to be accessed. +
For more information on deployment, see "link:../application-deployment-guide/overview.html#GSDPG00063[About
Deployment Tools]" in GlassFish Server Open Source Edition Application
Deployment Guide.
4.  To access EJB components that are residing in a remote system, set
the following system properties for the Java Virtual Machine startup
options: +
[source,oac_no_warn]
----
-Dorg.omg.CORBA.ORBInitialHost=${ORBhost}
-Dorg.omg.CORBA.ORBInitialPort=${ORBport}
----
Here ORBhost is the Application Server hostname and ORBport is the ORB
port number (default is `3700` for the default server instance, named
`server`).
5.  Deploy the module. +
For more information on deployment, see "link:../application-deployment-guide/overview.html#GSDPG00063[About
Deployment Tools]" in GlassFish Server Open Source Edition Application
Deployment Guide.

[[gkuqa]][[GSDVG00076]][[to-access-a-jms-resource-from-a-stand-alone-client]]

To access a JMS resource from a stand-alone client
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1.  Create a JMS client. +
For detailed instructions on developing a JMS client, see
"https://javaee.github.io/tutorial/jms-examples.html[Java Message
Service Examples]" in The Java EE 8 Tutorial.
2.  Configure a JMS resource on GlassFish Server. +
For information on configuring JMS resources, see
"link:../administration-guide/jms.html#GSADG00598[Administering JMS Connection Factories and
Destinations]" in GlassFish Server Open Source Edition Administration
Guide.
3.  Copy the following JAR files to the client machine and include them
in the classpath on the client side:
* `gf-client.jar` - available at as-install`/lib`
* `imqjmsra.jar` - available at
as-install`/lib/install/aplications/jmsra` +
The `gf-client.jar` file references GlassFish Server JAR files in its
`MANIFEST.MF` file. If there is no GlassFish Server installation on the
client machine, you must also copy the as-install`/modules` directory to
the client machine and maintain its directory structure relative to the
as-install`/lib/gf-client.jar` file. Or you can use the
`package-appclient` script; see link:#beakz[Using the
`package-appclient` Script].
4.  To access EJB components that are residing in a remote system, set
the following system properties for the Java Virtual Machine startup
options: +
[source,oac_no_warn]
----
-Dorg.omg.CORBA.ORBInitialHost=${ORBhost}
-Dorg.omg.CORBA.ORBInitialPort=${ORBport}
----
Here ORBhost is the Application Server hostname and ORBport is the ORB
port number (default is `3700` for the default server instance, named
`server`). +
You can use the `asadmin get` command to get the IIOP port numbers. For
example: +
[source,oac_no_warn]
----
asadmin get "configs.config.server-config.iiop-service.iiop-listener.orb-listener-1.*"
----
5.  Run the stand-alone client. +
As long as the client environment is set appropriately and the JVM is
compatible, you merely need to run the `main` class.