Chapter 2 Using the Application Client Container

This chapter describes how to access the application server using RMI/IIOP protocol, and how to use the Application Client Container (ACC) to develop and package application clients.

Introducing the Application Client Container

Developing Application Clients

Introducing the Application Client Container

The Application Client Container (ACC) includes a set of Java classes, libraries, and other files that are required and distributed along with Java client programs that execute on their own Java Virtual Machine. It manages the execution of the application client components. The ACC provides system services that enable a Java client program to execute. It communicates with Application Server using RMI/IIOP and manages the details of RMI/IIOP communication using the client ORB that is bundled with it. The ACC is specific to the EJB container and is often provided by the same vendor. Compared to other J2EE containers that reside on the server, this container is lightweight.

Application Client Container Features

Security

The ACC is responsible for collecting authentication data such as the username and password from the user. Sends the collected data over RMI/IIOP to the server. The server then processes the authentication data using the configured Java^TM Authentication and Authorization Service (JAAS) module. See Authenticating an Application Client Using the JAAS Module.

Authentication techniques are provided by the client container, and are not under the control of the application client. The container integrates with the platform’s authentication system. When you execute a client application, it displays a login window and collects authentication data from the user. It also support SSL (Secure Socket Layer)/IIOP if configured and when it is necessary.

Naming

The client container enables the application clients to use Java Naming and Directory Interface (JNDI) to look up EJB components and to reference configurable parameters set at the time of deployment.

Developing Application Clients

This section describes the procedure to develop, assemble, and deploy client applications, how to use the ACC to package such applications and deploy them to the server. This section describes the following topics:

Creating an Application Client

Creating an ACC Client With Load Balancing and Failover Support (Enterprise Edition)

Using an Application Client to Invoke an EJB Module

Using an Application Client to Access JMS Resources

Invoking an RMI/IIOP-based Client Without Using the ACC

Authenticating an Application Client Using the JAAS Module

Packaging an Application Client Using the ACC

Running an Application Client Using the ACC

Creating an Application Client

A J2EE application client is a program written in the Java programming language. At runtime, the client program executes in a different virtual machine than the J2EE server.

Code examples from the Converter sample application illustrate the following steps involved in the development of an application client:

Locating the Home Interface

Creating an Enterprise Bean Instance

Invoking a Business Method

Locating the Home Interface

Use the Java Naming and Directory Interface^TM (JNDI) to lookup and locate an EJB component’s home interface. The following steps describe the procedure to locate an EJB component’s home interface.

Create an initial naming context.

Context initial = new InitialContext();
Context myEnv = (Context)initial.lookup(“java:comp/env”);

The context interface is part of JNDI. An initial context object, which implements the Context interface, provides the starting point for the resolution of names. All naming operations are relative to a context.

Retrieve the object bound to the name RMCConverter.

Object objref = myEnv.lookup(“ejb/RMIConverter”);

The RMIConverter name is bound to an enterprise bean reference, a logical name for the home of an enterprise bean component. In this case, the RMIConverter name refers to the ConverterHome object. The names of enterprise bean components should reside in the java:com/env/ejb subcontext.

Narrow the reference to a ConverterHome object.

ConverterHome home =(ConverterHome) PortableRemoteObject.narrow(objref, ConverterHome.class);

Creating an Enterprise Bean Instance

To create the bean instance, the client invokes the create method on the ConverterHome object. The create method returns an object whose type is Converter. The remote converter interface defines the business methods of the bean that the client may call and the EJB container instantiates the bean and then invokes the ConverterBean.ejbCreate method.

Invoking a Business Method

To invoke a business method, you first need to invoke a method on the Converter object. The EJB container will invoke the corresponding method on the ConverterEJB instance that is running on the server. The client invokes the dollarToYen business method in the following lines of code:

Creating an ACC Client With Load Balancing and Failover Support (Enterprise Edition)

Sun Java System Application Server, Enterprise Edition provides a highly available J2EE application through the use of load balancing and a sophisticated failover mechanism on the RMI/IIOP path.

Load balancing of requests from client applications on the RMI/IIOP path

High availability of remote references for RMI/IIOP invocations from stand-alone clients and ACC clients.

High availability of J2EE application means that, if between method invocations, the server instance to the EJB object becomes unavailable, then subsequent invocations are redirected to an alternate available server instance in the cluster.

For more information on High Availability, see the Sun Java System Application Server Administration Guide.

Introducing the Properties that Support LB/FO for ACC Clients

In order to enable load balancing capabilities in your ACC client, Sun Java System Application Server supports the following two properties:

com.sun.appserv.iiop.endpoints

com.sun.appserv.iiop.loadbalancingpolicy

Configuration Changes

Define the load balancing properties in the sun-acc.xml file to provide a highly available ACC client. The properties are defined as property elements in the sun-acc.xml file.

To failover an ACC client on the RMI/IIOP path, information about all the endpoints in a cluster to which the RMI/ IIOP requests can be failed over must be available. You must have defined the IIOP endpoints in the server.xml file. The iiop-cluster element under the availability-service element defines the IIOP endpoints.

Using an Application Client to Invoke an EJB Module

This section describes how an application client can be used to call a stand-alone EJB module, or an EJB module residing in another J2EE application client.


Note	The endpoints are categorized as those configured for non-SSL and those configured for SSL. Only endpoints configured for non-SSL are supported. For more information on defining IIOP endpoints, see the Sun Java System Application Server Administration Guide.

Define the element <ejb-ref> in the application-client.xml file. The deployer provides the JNDI name for the <ejb-ref> in the corresponding sun-application-client.xml file.

For more information on the sun-application-client.xml file, see Sun Java System Application Client Deployment Descriptor.

Make sure that the JNDI name matches with the JNDI name defined in the EJB module.

Deploy the EJB module using the Administration interface. For more information on deploying an EJB module using the Administration Interface, see the Sun Java System Application Server Administration Guide.

The client JAR file is created at the following location:
/application/j2ee-modules/ejbmodulename/appclient.jar

Distribute your appclient.jar file to the location that the client JVM can access.

Ensure that the appclient.jar file includes the following files:

a Java class to access the bean

application-client.xml

sun-application-client-.xml

The MANIFEST.MF file. This file contains the main class, which states the complete package prefix and classname of the Java client.

Run the application client to access the EJB component. The following line of code illustrates how to invoke an EJB component using the ACC:

appclient -client jarpath -mainclass client application main class|-name name -xml config_xml_file app-args

-client is required and specifies the name and location of the application client jar file.

-mainclass is optional and specifies the class name, that is located within the appclient.jar file whose main() method is to be invoked. By default, the class specified in the client jars Main-class attribute of the MANIFEST file is used.

-name is optional and specifies the display name that is located within the appclient.jar. By default, the display name is specified in the client jar application-client.xml file as display-name attribute.

-xml, which specifies the name and location of the ACC configuration xml file, is required if you are not using the default domain and instance. By default, the ACC uses instance_dir/config/sun-acc.xml for clients running on the application server, or install_dir//lib/appclient/sun-acc.xml for clients that are packaged using the package-applclient script.

app-args are optional and they represent the arguments passed to the client’s main() method.

To deploy the application client, assemble the application client to create a standard J2EE .ear file and then deploy the application client to Sun Java System Application Server.

Making a Remote Call on the EJB

If you need to access the EJB components that are residing in a remote system other than the system where the application client is being developed, make the following changes into the sun-acc.xml fie.

Define the <target-server> address attribute to reference the remote server machine.

Define the <target-server> port attribute to reference the ORB port on the remote server.

This information can be obtained from the server.xml file on the remote system. For more information on server.xml file, see the Sun Java System Application Server Administrator’s Configuration File Reference.

Using an Application Client to Access JMS Resources

This section describes the procedure to develop an application client that can access JMS resources to send a JMS message to a destination. The following two scenarios are discussed:

Application Client Accessing JMS Resources Without Using the ACC

Application Client Packaged in an Application Client Container Accessing JMS Resources

Before creating the client application, you must create JMS resources on the server. For information on creating JMS resources, see the Sun Java System Application Server Developer’s Guide to J2EE Services and APIs.

Application Client Accessing JMS Resources Without Using the ACC

A stand-alone client uses the RMI/IIOP standard to communicate with Sun Java System Application Server. The J2EE 1.3 specification requires that a stand-alone client operate within the ACC context. However, Sun Java System Application Server allows Java platform clients to directly access the resources residing on the server. This section describes how you can develop a stand-alone client that can access the JMS resources directly without using the ACC path.

The sample application SimpleQueueClient.java is used here to describe the steps involved in developing a stand-alone client that looks up the JMS resources outside ACC and also send and receive messages to a queue on Sun Java System Application Server.

Import the JMS packages.

import javax.jms.*;
import javax.naming.*;

Create an initial context.

Context initialContext = new InitialContext();

Do not pass any environment properties to the InitialContext constructor. Instead, obtain the ORBhost name and port number through the command line options.

Look up the Queue by its JNDI name. Use the jms/sampleQCF string to lookup the JMS destination.

private static final String LOOKUP_STRING_FACTORY = "jms/sampleQCF";

private static final String LOOKUP_STRING_QUEUE = "jms/sampleQ";

factory = (QueueConnectionFactory) initialContext.lookup(LOOKUP_STRING_FACTORY);

queue = (Queue) initialContext.lookup(LOOKUP_STRING_QUEUE);

InitialContext method is used to retrieve administered objects.

To send and receive messages, you must follow the procedure to create a JMS client:

Create a QueueConnection to the message service. The connection provides access to the underlying transport of the message, and is also used to create sessions. Use the CreateQueueConnection() method on the factory object to create a connection.

Start the connection. Unless the connection is started, MessageConsumers associated with the messages cannot receive any messages.

Create a QueueSession. Sessions provide context for producing and consuming messages. Sessions are used to create message producers and message consumers, as well as build message themselves.

Create message producers. Use the session and destination to create a message producer. In this example, a QueueSender is created.

Create message consumers. Use the session and destination to create message consumer. In this example, a QueueReceiver is created.

Build a message. Use session to create an empty message and add the data.

Send the message. The message is passed to the send method on the QueueSender.

Receive the message. Use the QueueReceiver method to receive the message.

Retrieve the message contents. Call the receive method with a timeout argument (in milliseconds) greater than 0.

Close all JMS resources.

For detailed instructions on developing a JMS client, see the Sun Java System Application Server Developer's Guide to J2EE Services and APIs.

Next, configure JMS resources on Sun Java System Application Server. You can either use the Administration Interface or the command line options to configure the resources.

You need to configure the following general properties:

jmshost - Application Server host name

adminusr - Admin instance user name

adminpwd - Admin instance password

adminport - Admin instance port number

Configure the following Connection Factory and Destination resource.

Connection Factory:

JNDI Name: jms/sampleQCF

Resource Type: javax.jms.QueueConnectionFactory

Destination Resource:

JNDI Name: jms/sampleQ

Resource Type: javax.jms/Queue

For information on configuring JMS resources, see the Sun Java System Application Server Administration Guide.



Note	You do not have to deploy this application on an ACC or Sun Java System Application Server as it is a stand-alone client.

Run the client.

Set the environment variable LD_LIBRARY_PATH. This variable should point to the Application Server, the Sun Java System MQ jar files and shared libraries:

LD_LIBRARY_PATH=/usr/lib/mps:/opt/SUNWappserver7/lib:/usr/lib

If the Application Server is on a different system, copy all the jar files and shared libraries from the /opt/SUNWappserver7/lib, /usr/share/lib/imq and /usr/lib/mps directories to the target system.

Before running the client, set the values for the Java Virtual Machine startup options:

jvmarg value = “-Dorg.omg.CORBA.ORBInitialHost=${ORBhost}”
jvmarg value = “-Dorg.omg.CORBA.ORBInitialPort=${ORBport}”

Here ORBhost is the Application Server hostname and ORBport is the ORB port number (default 3700 for server1 instance).

Run the client.

import javax.jms.*;
import javax.naming.*;
import java.io.IOException;
import java.util.*;

private static final String LOOKUP_STRING_FACTORY = "jms/sampleQCF";
private static final String LOOKUP_STRING_QUEUE = "jms/sampleQ";

out("Looking up the queue connection factory from JNDI :"+LOOKUP_STRING_FACTORY);

// look up the connection factory from the object store
factory = (QueueConnectionFactory)
initialContext.lookup(LOOKUP_STRING_FACTORY);
out(LOOKUP_STRING_FACTORY + ": " + factory);

  // look up queue from the object store
  out("Looking up the queue from JNDI");
  queue = (Queue) initialContext.lookup(LOOKUP_STRING_QUEUE);
  out(LOOKUP_STRING_QUEUE + ": " + queue);

String msg = "An error was encountered trying to lookup an object from JNDI";
out(msg);
e.printStackTrace();

final String messageBody = "This is a sample message. It was " + "sent at " + new Date();

  QueueSession        session       =null;
  QueueConnection         connection       =null;
  QueueSender         queueSender       = null;
  QueueReceiver         queueReceiver       = null;
  String         successText       ="SUCCESSFUL";
  TextMessage         msgReceived       =null;

  connection = factory.createQueueConnection();
     out("Starting the Connection");
     connection.start();

session = connection.createQueueSession(false,Session.AUTO_ACKNOWLEDGE);
out("Creating a QueueSender");
queueSender = session.createSender(queue);
out("Creating a QueueReceiver");
queueReceiver = session.createReceiver(queue);

    out("Building a message" );
    TextMessage msgSent = session.createTextMessage();
    msgSent.setText(messageBody);

    out("Sending message to " + queue.getQueueName() );
    queueSender.send(msgSent);
    out( "Waiting for the return message" );

/* comment the following line to leave the message on the queue. then use the message queue product's admin tools to verify that the message was placed on the queue.
*/

// Retrieving the next message that arrives within the timeout interval of 2000 miliseconds

    if (msgReceived == null) {
    out("An error has occurred. The return message was not received.");
  successText = "UNSUCCESSFUL";

//Retreive the contents of the message.
if (msgReceived instanceof TextMessage) {

  out("An unexpected exception occurred: " + e);
  Exception linkedException = e.getLinkedException();
  if (linkedException != null) {
    out("The linked exception is: " + linkedException);
  }

    try {
   out("Closing QueueReceiver");
   queueReceiver.close();
   } catch (JMSException e) {
   out("There was an error closing the receiver");
   e.printStackTrace();

  if (queueSender != null) {
    try {
   out("Closing QueueSender");
   queueSender.close();
   } catch (JMSException e) {
   out("There was an error closing the sender");
   e.printStackTrace();

     try {
      out("Closing session");
      session.close();
      } catch (JMSException e) {
   out("There was an error closing the session");
   e.printStackTrace()
   }
  }

  if (connection != null) {
    try {
      out("Closing connection");
      connection.close();
      } catch (JMSException e) {
      out("There was an error closing the connection");
      e.printStackTrace();

Application Client Packaged in an Application Client Container Accessing JMS Resources

When the application client is packaged in an application client container, make the following changes to the code. In the sample application SimpleQueueClient.java, make the following changes:

A J2EE application can be packaged using the Application Client Container. Use the java:comp/env/jms/ string to lookup the JMS resources. This is the J2EE application namespace.

private static final String LOOKUP_STRING_FACTORY = "java:comp/env/jms/sampleQCF";

private static final String LOOKUP_STRING_QUEUE = "java:comp/env/jms/sampleQ";

The Application Client Container gets the ORB hostname and port number from the ACC configuration file sun-acc.xml.

The <name> entry in this file will be the Application Server hostname and the port is the ORB port number (default 3700 for server1 instance).

Assemble the application client to create a jar file. Include the two configuration files in the client jar file.

sun-application-client.xml - Sun Java System Application Server specific J2EE client application

For information on sun-application-client.xml file, see Sun Java System Application Client Deployment Descriptor.

The contents of the sun-application-client.xml is as follows:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE sun-application-client PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7 Application Client 1.3//EN'

'http://www.sun.com/software/appserver/dtds/sun-application-client_1_3-0.dtd'>

<sun-application-client>

<resource-ref>

<res-ref-name>jms/sampleQ</res-ref-name>
<jndi-name>jms/sampleQ</jndi-name>

</resource-ref>

<resource-ref>

<res-ref-name>jms/sampleQCF</res-ref-name>
<jndi-name>jms/sampleQCF</jndi-name>

<resource-ref>
<sun-application-client>

application-client.xml - J2EE 1.3 application client deployment descriptor

The contents of the application-client.xml is as follows:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE application-client PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application Client 1.3//EN' 'http://java.sun.com/dtd/application-client_1_3.dtd'>

<application-client>

<display-name>SimpleQueue</display-name>

<resource-ref>

<res-ref-name>jms/sampleQ</res-ref-name>

<res-type>javax.jms.Queue</res-type>

<res-auth>Container</res-auth>

</resource-ref>

<resource-ref>

<res-ref-name>jms/sampleQCF</res-ref-name>

<res-type>javax.jms.QueueConnectionFactory</res-type>

<res-auth>Container</res-auth>

</resource-ref>

</application-client>

These deployment descriptors describe the external JMS resources (administered objects) referenced by the sample application.

Package the application client using the appclient script. See Packaging an Application Client Using the ACC.

package-appclient script also creates a MANIFEST file that contains the main class, which states the complete package prefix and classname of the Java platform client.

Run the application client using the ACC. For instructions, see Running an Application Client Using the ACC.

Authenticating an Application Client Using the JAAS Module

Using the JAAS module, you can provide security in your application client code. Create a LoginModule that describes the interface implemented by authentication technology providers. LoginModules are plugged in under applications to provide a particular type of authentication.The following steps are involved in creating a LoginModule:

Write the LoginModule interface.

public class ClientPasswordLoginModule implements LoginModule{

private static Logger _logger=null;

static{

_logger=LogDomains.getLogger(LogDomains.SECURITY_LOGGER);

}

private Subject subject;
private CallbackHandler callbackHandler;
private Map sharedState;
private Map options;

The standard JAAS package required by this class is javax.security. The code line below illustrates how you can import the package in your client application:

import javax.security.*;

Initialize the LoginModule interface that you just created.

public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options) {

this.subject = subject;
this.callbackHandler = callbackHandler;
this.sharedState = sharedState;
this.options = options;

}

The parameter subject, is the subject to be authenticated.

callbackHandler, for communicating with the end user which prompts for the username and password.

sharedState, is the shared LoginModule state.

options, the options specified in the configuration file of the LoginModule.

Use login() method to fetch the login information from the client application and authenticate the user.

public boolean login() throws LoginException {

if (uname != null) {
username = new String (uname);
pswd = System.getProperty (LOGIN_PASSWORD);

}

The login information is fetched using the CallBackHandler.

Callback[] callbacks = new Callback[2];

callbacks[0] = new NameCallback(localStrings.getLocalString("login.username", "ClientPasswordModule username: "));

callbacks[1] = new PasswordCallback(localStrings.getLocalString("login.password", "ClientPasswordModule password: "), false);

username = ((NameCallback)callbacks[0]).getName();

char[] tmpPassword = ((PasswordCallback)callbacks[1]).getPassword();

The login() method tries to connect to the server using the login information that is fetched. If the connection is established, the method returns the value true.

Use commit() method to set the subject in the session to the username that is verified by the login method. If the commit method returns a value true, then this method associates PrincipalImpl with the subject located in the LoginModule. If this LoginModule’s own authentication attempt is failed, then this method removes any state that was originally saved.

Use logout() method to remove the privilege settings associated with the roles of the subject.

public boolean logout() throws LoginException {

subject.getPrincipals().remove(userPrincipal);
succeeded = false;
succeeded = commitSucceeded;
username = null;
if (password != null) {
  for (int i = 0; i < password.length; i++)
    password[i] = ’ ’;
    password = null;
}
userPrincipal = null;
return true;
}

Edit the sun-acc.xml deployment descriptor to configure JAAS authentication for the client. See auth-realm.

Integrate the LoginModule with the application server.

Edit the deployment descriptor to make the following changes:

Configure the server with a realm that uses a specific LoginModule for security authentication.

Map the application realm and roles to the realm and roles defined by the LoginModule.

Assemble the application client. See Packaging an Application Client Using the ACC.

Sample Code

import java.util.*;
import java.io.IOException;
import javax.security.auth.*;
import javax.security.auth.callback.*;
import javax.security.auth.login.*;
import javax.security.auth.spi.*;
import com.sun.enterprise.security.auth.login.PasswordCredential;
import com.sun.enterprise.security.PrincipalImpl;
import com.sun.enterprise.security.auth.LoginContextDriver;
import com.sun.enterprise.util.LocalStringManagerImpl;
import java.util.logging.*;
import com.sun.logging.*;

private static Logger _logger=null;
  static{
    _logger=LogDomains.getLogger(LogDomains.SECURITY_LOGGER);
  }

private static final String DEFAULT_REALMNAME = "default";
private static LocalStringManagerImpl localStrings =
new LocalStringManagerImpl(ClientPasswordLoginModule.class);

private Subject subject;
private CallbackHandler callbackHandler;
private Map sharedState;
private Map options;

private PrincipalImpl userPrincipal;
public static String LOGIN_NAME = "j2eelogin.name";
public static String LOGIN_PASSWORD = "j2eelogin.password";

public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options) {

    this.subject = subject;
    this.callbackHandler = callbackHandler;
    this.sharedState = sharedState;
    this.options = options;

/* Authenticate the user by prompting for a username and password. @return true in all cases since this <code>LoginModule</code> should not be ignored.*/

/* @exception FailedLoginException if the authentication fails. @exception LoginException if this <code>LoginModule</code> is unable to perform the authentication.*/

String failure = localStrings.getLocalString("login.nocallback","Error: no CallbackHandler available to garner authentication information from the user");

  username = new String (uname);
  pswd = System.getProperty (LOGIN_PASSWORD);
  char[] dest;
  if (pswd == null){
    dest = new char[0];
    password = new char[0];
  } else {
    int length = pswd.length();
    dest = new char[length];
    pswd.getChars(0, length, dest, 0 );
    password = new char[length];
  }
  System.arraycopy (dest, 0, password, 0, dest.length);
  } else{
    Callback[] callbacks = new Callback[2];
    callbacks[0] = new NameCallback(localStrings.getLocalString("login.username", "ClientPasswordModule username: "));
    callbacks[1] = new PasswordCallback(localStrings.getLocalString("login.password", "ClientPasswordModule password: "), false);

  try {
    callbackHandler.handle(callbacks);
    username = ((NameCallback)callbacks[0]).getName();
    if(username == null){
      String fail = localStrings.getLocalString("login.nousername", "No user specified");
      throw new LoginException(fail);
    }

    if (tmpPassword == null) {
  // treat a NULL password as an empty password
    tmpPassword = new char[0];
    }
    password = new char[tmpPassword.length];
    System.arraycopy(tmpPassword, 0,
    password, 0, tmpPassword.length);
    ((PasswordCallback)callbacks[1]).clearPassword();
    } catch (java.io.IOException ioe) {
    throw new LoginException(ioe.toString());
    } catch (UnsupportedCallbackException uce) {
String nocallback = localStrings.getLocalString("login.callback","Error: Callback not available to garner authentication information from user(CallbackName):" );
throw new LoginException(nocallback + uce.getCallback().toString());

for (int i = 0; i < password.length; i++){
//System.out.print(password[i]);
}
//System.out.println();
}

// by default - the client side login module will always say
// that the login successful. The actual login will take place
// on the server side.
if (debug)

{
_logger.log(Level.FINE," [ClientPasswordLoginModule] " +"authentication succeeded");
succeeded = true;
return true;

public boolean commit() throws LoginException {
if (succeeded == false) {
  return false;
  } else {
  // add a Principal (authenticated identity)to the Subject
  // assume the user we authenticated is the PrincipalImpl
    userPrincipal = new PrincipalImpl(username);
    if (!subject.getPrincipals().contains(userPrincipal))
      subject.getPrincipals().add(userPrincipal);
      if (debug) {
      _logger.log(Level.FINE,"    [ClientPasswordLoginModule] " +"added PrincipalImpl to Subject");
  }

PasswordCredential pc = new PasswordCredential(username, new String(password), realm);
if(!subject.getPrivateCredentials().contains(pc))subject.getPrivateCredent ials().add(pc);

username = null;
for (int i = 0; i < password.length; i++){
password[i] = ’ ’;
password = null;
commitSucceeded = true;
return true;
}
}

public boolean abort() throws LoginException {
if (succeeded == false) {
return false;
} else if (succeeded == true && commitSucceeded == false) {
// login succeeded but overall authentication failed
  succeeded = false;
  username = null;
  if (password != null) {
    for (int i = 0; i < password.length; i++)
      password[i] = ’ ’;
      password = en das ull;
    }
    userPrincipal = null;
    } else {

    // overall authentication succeeded and commit succeeded,
    // but someone else’s commit failed
    logout();
    }
    return true;
    }

Invoking an RMI/IIOP-based Client Without Using the ACC

You can invoke a J2EE client without using the ACC. When you are creating an application client that does not use the ACC, you need to setup your development environment as follows:


Note	Sun Java System Application Server does not support authentication of RMI/IIOP Clients that do not use the ACC (non-ACC clients).

Include the following non-java libraries in the client’s classpath.

Windows:

The following libraries can be found at install_dir/bin:

cis.dll

libnspr4.dll

libplc4.dll

nss3.dll

ssl3.dll

Solaris:

The following libraries can be found at install_dir/lib:

libcis.so

libnspr4.so

libplc4.so

libnss3.so

libssl3.so

In addition to the non-java libraries, copy the following jar files to the client system and add them to the classpath:

appserv-ext.jar

appserv-rt.jar

fscontext.jar

imq.jar

imqadmin.jar

imqutil.jar

Define the main class as shown in the code illustration below:

public static void main(String[] args) {

String url = null;

String jndiname = null;

boolean acc = true;

}

If the code sees the url and jndiname passed in, the acc flag is set to false and does the EJB lookup differently than it does if this client code is called by the application client utility without any arguments.

if (args.length == 2 ) {

  url = args[0];
  jndiname = args[1];
  acc = false;
  System.out.println("url = "+url);

}

Obtain the naming initial context and perform the JNDI look up.

Properties env = new Properties();

env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.cosnaming.CNCtxFactory");

env.put(Context.PROVIDER_URL, url);

initial = new InitialContext(env);

objref = initial.lookup(jndiname);

Run the client from the command line.

Packaging an Application Client Using the ACC

After installing Sun Java System Application Server, the ACC can be run by executing the appclient script located+ in the install_dir/bin directory. The script package-appclient that is located in the same directory, is used to package a client application into a single appclient.jar file. Packaging an application client involves the following main steps:

Editing the Configuration File

Editing the appclient Script

Editing the sun-acc.xml File

Setting Security Options

Using the package-appclient Script

Editing the Configuration File

Modify the environment variables in asenv.conf file located in the default-config_dir directory as shown below:

$AS_INSTALL to reference the location where the package was un-jared plus /appclient. For example: $AS_INSTALL=/install_dir/appclient.

$AS_NSS to reference the location of the nss libs.

$AS_JAVA to reference the location where you have installed the JDK.

$AS_ACC_CONFIG to reference the configuration xml (sun-acc.xml). The sun-acc.xml is located at install_dir/config.

$AS_IMQ_LIB to reference the imq home. It should be: instance_dir/imq/lib.

Editing the appclient Script

Editing the sun-acc.xml File

Ensure that the DOCTYPE references %%%SERVER_ROOT%%%/lib/dtds to your_ACC_dir/lib/dtds.

Ensure that the <target-server> address attribute references the remote server machine.

Ensure that the <target-server> port attribute references the ORB port on the remote server.

If you want to log the messages in a file, specify a file name for the <log-service> file attribute. You can also set the log level.

For example,

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE client-container SYSTEM "file:{Your installed server root}/lib/dtds/sun-application-client-container_1_0.dtd ">

<client-container>

<target-server name="qasol-e1" address="qasol-e1" port="3700">

<log-service file=" " level="WARNING"/>
</client-container>

If you want to enable load balancing and failover capabilities for the ACC client, follow the steps described in the section Creating an ACC Client With Load Balancing and Failover Support (Enterprise Edition).

Setting Security Options

You can run the application client using SSL with certificate authentication. In order to set the security options, modify the sun-acc.xml file as shown in the code illustration below. For more information on the sun-acc.xml file, see the Application Client Container Configuration File.

"file:////export3/sun/appserver7/appserv/lib/dtds/sun-application-clien t-container_1_0.dtd">

<ssl cert-nickname="cts" ssl2-enabled="false" ssl2-ciphers="-rc4,-rc4export,-rc2,-rc2export,-des,-desede3"

ssl3-tls-ciphers="+rsa_rc4_128_md5,-rsa_rc4_40_md5,+rsa3_des_sha,+rsa_d es_sha,-rsa_rc2_40_md5,-rsa_null_md5,-rsa_des_56_sha,-rsa_rc4_56_sha"

Using the package-appclient Script

The following steps describe the procedure to use the package-appclient script that is bundled with Sun Java System Application Server:

Under install_dir/bin directory, run the package-appclient script. This creates an appclient.jar file and stores it under install_dir/lib/appclient/ directory.



Note	The appclient.jar file provides an application client container package targeted at remote hosts and does not contain a server installation. You can run this file from a remote machine with the same operating system as where it is created. That is, appclient.jar created on a Solaris platform will not function on Windows.

Copy the install_dir/lib/appclient/appclient.jar file to the desired location. The appclient.jar file contains the following files:

appclient/bin - contains the appclient script which you use to launch the ACC.

appclient/lib - contains the JAR and runtime shared library files.

appclient/lib/appclient - contains the following files:

sun-acc.xml - the ACC configuration file.

client.policy file- the security manager policy file for the ACC.

appclientlogin.conf file - the login configuration file.

client.jar file - is created during the deployment of the client application.

appclient/lib/dtds - contains sun-application_client-contianer_1_3-0.dtd which is the DTD corresponding to sun-acc.xml.

client.policy

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 J2EE deployed application clients to the minimal set of permissions required for these applications to operate correctly. If you develop an application client that requires more than this default set of permissions, you can edit the client.policy file to add the custom permissions that your applications need. You can use the J2SE standard policy tool or any text editor to edit this file. For more information on using the J2SE policy tool, visit the following URL:

Running an Application Client Using the ACC

To run a client application that is packaged in an application jar file, you first need to launch the ACC. You can launch the application client container using appclient script.

appclient -client client_application_jar [-mainclass client_application_main_class_name|-name display_name][-xml sun-acc.xml] [-textauth] [-user user_name] [-password password]

-client: Specifies the name and location of the client application jar file. This is a required parameter.

-mainclass: Specifies the class name that is located within the client jar whose main() method is to be invoked. By default, uses the class specified in the client jar. This is optional.



Note	The class name must be the full name. For example, com.sun.test.AppClient

-name: Specifies the display name that is located in the application client jar file. By default, the display name is specified in the client jar application-client.xml file which is identified by the display-name attribute. This is optional.



Note	-mainclass, -name are optional for a single client application. For multiple client applications use either the -classname option or the -name option.

-xml: is used to specify the name and location of the client configuration xml file. If you do not specify this option, ACC will use the default one from appclient script identified by $AS_ACC_CONFIG that references to the default instance. For Solaris bundle, this option is required.

-textauth: is optional for user to specify authentication using the text format.

The following example shows how to run the sample application client, rmiConverter:

Sample Client Application

You can find the sample client application that demonstrates the working of an RMI/IIOP client that uses an application client container at the following location:

Previous Contents Index Next
Sun Java System Application Server 7 2004Q2 Developer's Guide to Clients