docs/reference-manual/src/main/asciidoc/appclient.adoc - glassfish - Git at Google

 type=page
 status=published
 title=appclient
 next=asadmin.html
 prev=manvol1m.html
 ~~~~~~

 = appclient

 [[appclient-1m]][[GSRFM00262]][[appclient]]

 == appclient

 Launches the Application Client Container and invokes the client
 application typically packaged in the application JAR file

 [[sthref2357]]

 === Synopsis

 [source]
 ----
 appclient [client_application_classfile | -client client_application_jar]
 [-mainclass main_class_name | -name display_name]
 [-xml sun-acc.xml file] [-textauth]
 [-targetserver host[:port][,host[:port]...]]
 [-user username] [-passwordfile password_file]
 [application-options]

 appclient [jvm-options]
 [-mainclass main_class_name | -name display_name]
 [-xml client_config_xml_file] [-textauth]
 [-targetserver host[:port][,host[:port]...]]
 [-user username] [-passwordfile password_file]
 class-selector [application-options]
 ----

 [[sthref2358]]

 === Description

 Use the `appclient` command to launch the Application Client Container
 and invoke a client application that is typically packaged in an
 application JAR file. The application client JAR file is specified and
 created during deployment by the Administration Console or the
 `asadmin deploy` command with the `--retrieve` option. You can also
 retrieve the client JAR file using the `asadmin get-client-stubs`
 command.

 The Application Client Container is a set of Java classes, libraries,
 and other files that are required to execute a first-tier application
 client program on a Virtual Machine for the Java platform (JVM machine).
 The Application Client Container communicates with the server using
 RMI-IIOP.

 The client JAR file that is retrieved after deploying an application
 should be passed with the `-client` or `-jar` option when running the
 `appclient` utility. The client JAR file name is of the form
 app-name`Client.jar`. For multiple application clients in an EAR file,
 you must use the `-mainclass` or `-name` option to specify which client
 to invoke.

 If the application client is a stand-alone module or the only client in
 an EAR file, the Application Client Container can find the client
 without using the `-mainclass` or `-name` options. If you provide a
 `-mainclass` or `-name` value that does not match what is in the client,
 the Application Client Container launches the client anyway but issues a
 warning that the selection did not match the information in the client.
 The warning also displays what the actual main class and name values are
 for the client.

 [[sthref2359]]

 === Options

 jvm-options::
   optional; you can set JVM options for the client application. These
   can be any valid `java` command options except `-client` or `-jar`.
   JVM options can be intermixed with other `appclient` command options
   as long as both types of options appear before the class-selector.
 client_application_classfile::
   optional; the file system pathname of the client application `.class`
   file. A relative pathname must be relative to the current directory.
   This class file must contain the `main()` method to be invoked by the
   Application Client Container. +
   If you use client_application_classfile and the class is dependent on
   other user classes, you must also set the classpath. You can either
   use the `-classpath` JVM option in the `appclient` command or set the
   `CLASSPATH` environment variable. For more information about setting a
   classpath, see Setting the Class Path, Oracle Solaris Version
   (`http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/classpath.html`)
   or Setting the Class Path, Windows Version
   (`http://docs.oracle.com/javase/6/docs/technotes/tools/windows/classpath.html`).
 `-client`::
   optional; the name and location for the client JAR file.
 `-mainclass`::
   optional; the full classname of the main client application as
   specified in the `Main-Class` entry in the `MANIFEST.MF` file. Used
   for a multiple client applications. By default, uses the class
   specified in the `client jar`. For example,
   `com.example.test.AppClient`.
 `-name`::
   optional; the display name for the client application. Used for
   multiple client applications. By default, the display name is
   specified in the client jar `application-client.xml` file which is
   identified by the `display-name` attribute.
 `-xml`::
   optional if using the default domain, instance, and name
   (`sun-acc.xml`), otherwise it is required; identifies the name and
   location of the client configuration XML file. If not specified,
   defaults to the `sun-acc.xml` file in the domain-dir``/config``
   directory.
 `-textauth`::
   optional; used to specify using text format authentication when
   authentication is needed.
 `-targetserver`::
   optional; a comma-separated list of one or more server specifications
   for ORB endpoints. Each server specification must include at least the
   host. Optionally, a server specification can include the port as well.
   If the port is omitted from a server specification, the default value,
   `3700`, is used for that host.
 `-user`::
   optional; the application user who is authorized to have access to
   particular guarded components in the application, such as EJB
   components.
 `-passwordfile`::
   optional; specifies the name, including the full path, of a file that
   contains the password for application clients in the following format:
 +
 [source]
 ----
 PASSWORD=appclient-password
 ----
   If this option is omitted, the password is specified interactively at
   the command prompt.
 +
 [CAUTION]
 ====
 Avoid specifying a password interactively at the command prompt. Such
 a password can be seen by users who can run commands to display
 running processes and the commands to start them, such as `ps`.
 ====
 +
 For security reasons, a password that is specified as an environment
 variable is not read by the `appclient` utility.
 class-selector::
   required; you must specify the client application class using one of
   the following class selectors.

   `-jar` jar-file;;
     the name and location of the client JAR file. The application client
     JAR file is specified and created during deployment by the
     `asadmin deploy` command. If specified, the `-classpath` setting is
     ignored in deference to the `Class-Path` setting in the client JAR
     file's manifest.
   class-name;;
     the fully qualified name of the application client's main class. The
     Application Client Container invokes the `main` method of this class
     to start the client. For example, `com.example.test.AppClient`. +
     If you use class-name as the class selector, you must also set the
     classpath. You can either use the `-classpath` JVM option in the
     `appclient` command or set the `CLASSPATH` environment variable. For
     more information about setting a classpath, see Setting the Class
     Path, Oracle Solaris Version
     (`http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/classpath.html`)
     or Setting the Class Path, Windows Version
     (`http://docs.oracle.com/javase/6/docs/technotes/tools/windows/classpath.html`).

 application-options::
   optional; you can set client application arguments.

 [[sthref2360]]

 === Examples

 [[GSRFM804]][[sthref2361]]

 ==== Example 1   Using the `appclient` command

 [source]
 ----
 appclient -xml sun-acc.xml -jar myclientapp.jar scott sample
 ----

 Where: `sun-acc.xml` is the name of the client configuration XML file,
 `myclientapp.jar` is the client application `.jar` file, and `scott` and
 `sample` are arguments to pass to the application. If `sun-acc.xml` and
 `myclientapp.jar` are not in the current directory, you must give the
 absolute path locations; otherwise the relative paths are used. The
 relative path is relative to the directory where the command is being
 executed.

 [[sthref2362]]

 === Attributes

 See
 http://www.oracle.com/pls/topic/lookup?ctx=E18752&id=REFMAN5attributes-5[`attributes`(5)]
 for descriptions of the following attributes:

 [width="100%",cols="50%,50%",options="header",]
 |===
 |ATTRIBUTE TYPE |ATTRIBUTE VALUE
 |Interface Stability |Unstable
 |===


 [[sthref2363]]

 === See Also

 link:asadmin.html#asadmin-1m[`asadmin`(1M)]

 link:get-client-stubs.html#get-client-stubs-1[`get-client-stubs`(1)],
 link:package-appclient.html#package-appclient-1m[`package-appclient`(1M)]
	type=page
	status=published
	title=appclient
	next=asadmin.html
	prev=manvol1m.html
	~~~~~~

	= appclient

	[[appclient-1m]][[GSRFM00262]][[appclient]]

	== appclient

	Launches the Application Client Container and invokes the client
	application typically packaged in the application JAR file

	[[sthref2357]]

	=== Synopsis

	[source]
	----
	appclient [client_application_classfile \| -client client_application_jar]
	[-mainclass main_class_name \| -name display_name]
	[-xml sun-acc.xml file] [-textauth]
	[-targetserver host[:port][,host[:port]...]]
	[-user username] [-passwordfile password_file]
	[application-options]

	appclient [jvm-options]
	[-mainclass main_class_name \| -name display_name]
	[-xml client_config_xml_file] [-textauth]
	[-targetserver host[:port][,host[:port]...]]
	[-user username] [-passwordfile password_file]
	class-selector [application-options]
	----

	[[sthref2358]]

	=== Description

	Use the `appclient` command to launch the Application Client Container
	and invoke a client application that is typically packaged in an
	application JAR file. The application client JAR file is specified and
	created during deployment by the Administration Console or the
	`asadmin deploy` command with the `--retrieve` option. You can also
	retrieve the client JAR file using the `asadmin get-client-stubs`
	command.

	The Application Client Container is a set of Java classes, libraries,
	and other files that are required to execute a first-tier application
	client program on a Virtual Machine for the Java platform (JVM machine).
	The Application Client Container communicates with the server using
	RMI-IIOP.

	The client JAR file that is retrieved after deploying an application
	should be passed with the `-client` or `-jar` option when running the
	`appclient` utility. The client JAR file name is of the form
	app-name`Client.jar`. For multiple application clients in an EAR file,
	you must use the `-mainclass` or `-name` option to specify which client
	to invoke.

	If the application client is a stand-alone module or the only client in
	an EAR file, the Application Client Container can find the client
	without using the `-mainclass` or `-name` options. If you provide a
	`-mainclass` or `-name` value that does not match what is in the client,
	the Application Client Container launches the client anyway but issues a
	warning that the selection did not match the information in the client.
	The warning also displays what the actual main class and name values are
	for the client.

	[[sthref2359]]

	=== Options

	jvm-options::
	optional; you can set JVM options for the client application. These
	can be any valid `java` command options except `-client` or `-jar`.
	JVM options can be intermixed with other `appclient` command options
	as long as both types of options appear before the class-selector.
	client_application_classfile::
	optional; the file system pathname of the client application `.class`
	file. A relative pathname must be relative to the current directory.
	This class file must contain the `main()` method to be invoked by the
	Application Client Container. +
	If you use client_application_classfile and the class is dependent on
	other user classes, you must also set the classpath. You can either
	use the `-classpath` JVM option in the `appclient` command or set the
	`CLASSPATH` environment variable. For more information about setting a
	classpath, see Setting the Class Path, Oracle Solaris Version
	(`http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/classpath.html`)
	or Setting the Class Path, Windows Version
	(`http://docs.oracle.com/javase/6/docs/technotes/tools/windows/classpath.html`).
	`-client`::
	optional; the name and location for the client JAR file.
	`-mainclass`::
	optional; the full classname of the main client application as
	specified in the `Main-Class` entry in the `MANIFEST.MF` file. Used
	for a multiple client applications. By default, uses the class
	specified in the `client jar`. For example,
	`com.example.test.AppClient`.
	`-name`::
	optional; the display name for the client application. Used for
	multiple client applications. By default, the display name is
	specified in the client jar `application-client.xml` file which is
	identified by the `display-name` attribute.
	`-xml`::
	optional if using the default domain, instance, and name
	(`sun-acc.xml`), otherwise it is required; identifies the name and
	location of the client configuration XML file. If not specified,
	defaults to the `sun-acc.xml` file in the domain-dir``/config``
	directory.
	`-textauth`::
	optional; used to specify using text format authentication when
	authentication is needed.
	`-targetserver`::
	optional; a comma-separated list of one or more server specifications
	for ORB endpoints. Each server specification must include at least the
	host. Optionally, a server specification can include the port as well.
	If the port is omitted from a server specification, the default value,
	`3700`, is used for that host.
	`-user`::
	optional; the application user who is authorized to have access to
	particular guarded components in the application, such as EJB
	components.
	`-passwordfile`::
	optional; specifies the name, including the full path, of a file that
	contains the password for application clients in the following format:
	+
	[source]
	----
	PASSWORD=appclient-password
	----
	If this option is omitted, the password is specified interactively at
	the command prompt.
	+
	[CAUTION]
	====
	Avoid specifying a password interactively at the command prompt. Such
	a password can be seen by users who can run commands to display
	running processes and the commands to start them, such as `ps`.
	====
	+
	For security reasons, a password that is specified as an environment
	variable is not read by the `appclient` utility.
	class-selector::
	required; you must specify the client application class using one of
	the following class selectors.

	`-jar` jar-file;;
	the name and location of the client JAR file. The application client
	JAR file is specified and created during deployment by the
	`asadmin deploy` command. If specified, the `-classpath` setting is
	ignored in deference to the `Class-Path` setting in the client JAR
	file's manifest.
	class-name;;
	the fully qualified name of the application client's main class. The
	Application Client Container invokes the `main` method of this class
	to start the client. For example, `com.example.test.AppClient`. +
	If you use class-name as the class selector, you must also set the
	classpath. You can either use the `-classpath` JVM option in the
	`appclient` command or set the `CLASSPATH` environment variable. For
	more information about setting a classpath, see Setting the Class
	Path, Oracle Solaris Version
	(`http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/classpath.html`)
	or Setting the Class Path, Windows Version
	(`http://docs.oracle.com/javase/6/docs/technotes/tools/windows/classpath.html`).

	application-options::
	optional; you can set client application arguments.

	[[sthref2360]]

	=== Examples

	[[GSRFM804]][[sthref2361]]

	==== Example 1 Using the `appclient` command

	[source]
	----
	appclient -xml sun-acc.xml -jar myclientapp.jar scott sample
	----

	Where: `sun-acc.xml` is the name of the client configuration XML file,
	`myclientapp.jar` is the client application `.jar` file, and `scott` and
	`sample` are arguments to pass to the application. If `sun-acc.xml` and
	`myclientapp.jar` are not in the current directory, you must give the
	absolute path locations; otherwise the relative paths are used. The
	relative path is relative to the directory where the command is being
	executed.

	[[sthref2362]]

	=== Attributes

	See
	http://www.oracle.com/pls/topic/lookup?ctx=E18752&id=REFMAN5attributes-5[`attributes`(5)]
	for descriptions of the following attributes:

	[width="100%",cols="50%,50%",options="header",]
	\|===
	\|ATTRIBUTE TYPE \|ATTRIBUTE VALUE
	\|Interface Stability \|Unstable
	\|===


	[[sthref2363]]

	=== See Also

	link:asadmin.html#asadmin-1m[`asadmin`(1M)]

	link:get-client-stubs.html#get-client-stubs-1[`get-client-stubs`(1)],
	link:package-appclient.html#package-appclient-1m[`package-appclient`(1M)]