| Sun ONE Application Server 7 Developer's Guide to Clients |
Chapter 2
Using the Application Client ContainerThis 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.
This chapter contains the following sections:
Introducing the Application Client ContainerThe 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 Sun ONE 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 JavaTM 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 Applications Using the ACCThis section describes the procedure to develop, assemble, and deploy client applications using the ACC. This section describes the following topics:
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
Use Java Naming and Directory InterfaceTM (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”);
Object objref = myEnv.lookup(“ejb/RMIConverter”);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 rmiConverter.
Object objref = initial.lookup("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.
Converter currencyConverter = home.create();
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:
BigDecimal param = new BigDecimal ("100.00");
BigDecimal amount = currencyConverter.dollarToYen(param);
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.
To call an EJB module from an application client, perform the following steps:
- Define the element <ejb-ref> in the sun-application-client.xml file.
For more information on the sun-application-client.xml file, see "Sun ONE 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 ONE Application Server Administrator’s 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:
- 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 ONE 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.
This information can be obtained from the server.xml file on the remote system.
For more information on server.xml file, see the Sun ONE Application Server Administrator’s Configuration File Reference.
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:
The following steps describe the procedure to create a client:
- Define the main class as shown in the code illustration below:
public static(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("java.naming.factory.initial", "com.sun.jndi.cosnaming.CNCtxFactory");
env.put("java.naming.provider.url", url);
initial = new InitialContext(env);
objref = initial.lookup(jndiname);
- Run the client from the command line.
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;}
- 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.
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);- 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:
- Assemble the application client. See "Packaging an Application Client Using the ACC".
Sample Code
The sample code of ClinetLoginPasswordModule is given below:
package com.sun.enterprise.security.auth.login;
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.*;
public class ClientPasswordLoginModule implements LoginModule {
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);// initial state
private Subject subject;
private CallbackHandler callbackHandler;
private Map sharedState;
private Map options;private boolean debug = com.iplanet.ias.util.logging.Debug.enabled;
// the authentication status
private boolean succeeded = false;
private boolean commitSucceeded = false;// username and password
private String username;
private char[] password;private final PasswordCredential passwordCredential=null;
// testUser’s PrincipalImpl
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;// initialize any configured options
debug = "true".equalsIgnoreCase((String)options.get("debug"));
}
/* 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.*/
public boolean login() throws LoginException {
// prompt for a username and password
if (callbackHandler == null){
String failure = localStrings.getLocalString("login.nocallback","Error: no CallbackHandler available to garner authentication information from the user");
throw new LoginException(failure);
}String uname = System.getProperty (LOGIN_NAME);
String pswd;if (uname != null) {
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);
}char[] tmpPassword = ((PasswordCallback)callbacks[1]).getPassword();
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());}
}
// print debugging information
if (debug) {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.getPrivate Credentials().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;
}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;
}}
Note
Sun ONE Application Server does not support authentication of Clients on the RMI/IIOP path that do not use the ACC.
Packaging an Application Client Using the ACC
After installing Sun ONE 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
Modify the environment variables in asenv.conf file located in the default-config_dir directory as shown below:
Editing the appclient Script
Modify the appclient script file as follows:
UNIX:
Change $CONFIG_HOME/asenv.conf to your_ACC_dir/config/asenv.conf.
Windows:
Change %CONFIG_HOME%\config\asenv.bat to your_ACC_dir\config\asenv.bat
Editing the sun-acc.xml File
Modify sun-acc.xml file to set the following attributes:
- 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>
For more information on the sun-acc.xml file, see "Application Client Container Configuration File".
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".
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE client-container SYSTEM
"file:////export3/sun/appserver7/appserv/lib/dtds/sun-applicatio n-client-container_1_0.dtd">
<client-container>
<target-server name="qasol-e1" address="qasol-e1" port="3700">
<security>
<ssl cert-nickname="cts" ssl2-enabled="false" ssl2-ciphers="-rc4,-rc4export,-rc2,-rc2export,-des,-desede3"
ssl3-enabled="true"
ssl3-tls-ciphers="+rsa_rc4_128_md5,-rsa_rc4_40_md5,+rsa3_des_sha ,+rsa_des_sha,-rsa_rc2_40_md5,-rsa_null_md5,-rsa_des_56_sha,-rsa _rc4_56_sha"
tls-enabled="true" tls-rollback-enabled="true"/>
<cert-db path="/export3/ctsdata/ctscertdb" password="changeit"/>
</security>
</target-server>
<client-credential user-name="j2ee" password="j2ee"/>
<log-service file="" level="WARNING"/>
</client-container>
Using the package-appclient Script
The following steps describe the procedure to use the package-appclient script that is bundled with Sun ONE 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.
- 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:
http://java.sun.com/docs/books/tutorial/security1.2/tour2/ index.html
For more information about the permissions you can set in the client.policy file, visit the following URL:
http://java.sun.com/j2se/1.4/docs/guide/security/permissions.html
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.
- -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:
appclient -client rmi-simpleClient.jar
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:
install_dir/samples/rmi-iiop/simple
Application Client Deployment DescriptorsDeployment descriptors are the XML files used to configure the runtime properties of a module or application. The J2EE Specification defines the format of these descriptors. You can view and edit the deployment descriptors using a text editor at any time during the development process.
Sun ONE Application Server application clients require three deployment descriptors files:
- A J2EE standard file (application.client.xml), described in the J2EE Specification.
- An optional Sun ONE Application Server specific client deployment descriptor file (sun-application-client.xml), described in this section.
- An optional Sun ONE Application Server specific Application Client Container Configuration file (sun-acc.xml), described in this section.
This section presents the following topics:
Format of Deployment Descriptors
A deployment descriptor file defines the elements that an XML file can contain and the subelements and attributes these elements can have. The sun-application-client-1_3-0.dtd file defines the format of the sun-application-client.xml file. The sun-application-client-container-1_0.dtd file defines the format of sun-acc.xml file. These DTD files are located in the install_dir/lib/dtds directory.
Note
Do not edit the DTD files. Their contents change only with new versions of Sun ONE Application Server.
For general information about DTD files and XML, see the XML specification at:
Each element defined in a DTD file (which may be present in the corresponding XML file) can contain the following:
Subelements
An element can contain other elements. For example, the following code defines the client-container element.
<!ELEMENT client-container(target-server,auth-realm?,client-credential?, log-service?,property*))>
The ELEMENT tag specifies that a client-container element can contain target-server, auth-realm, client-credential, log-service, property subelements.
The following table shows how optional suffix characters of subelements determine the requirement rules, or number of allowed occurrences, for the subelements. The left column lists the subelement ending character, and the right column lists the corresponding requirement rule:
If an element cannot contain other elements, you see EMPTY or (#PCDATA) instead of a list of element names in parentheses.
Data
Some elements contain data instead of subelements. These elements have definitions of the following format:
<!ELEMENT element-name (#PCDATA)>
For example:
<!ELEMENT credential (#PCDATA)>
Attributes
Elements that have ATTLIST tags contain attributes (name-value pairs). Attributes have definitions of the following format:
<!ATTLIST element attribute type default attribute type default ...>
For example:
<!ATTLIST client-container user-name CDATA #REQUIRED
password CDATA #REQUIRED
realm CDATA #IMPLIED>
A client-container element can contain user-name, password, and realm attributes.
The #REQUIRED label means that a value must be supplied.
The #IMPLIED label means that the attribute is optional, and that Sun ONE Application Server generates a default value. Wherever possible, explicit defaults for optional attributes (such as "true") are listed.
Attribute declarations specify the type of the attribute. For example, CDATA means character data, and %boolean is a predefined enumeration.
J2EE Application Client Deployment Descriptor
Application clients are packaged in JAR format files with a .jar extension and include a deployment descriptor similar to other J2EE application components. The deployment descriptor describes the enterprise beans and external resources referenced by the application. As with other J2EE application components, you need to configure access to resources at the time of deployment, assign names for enterprise beans and resources, etc.The deployment descriptor is standardized by the J2EE 1.3 specification.
Sun ONE Application Client Deployment Descriptor
The sun-application-client.xml is the deployment descriptor for the application clients. The easiest way to create a sun-application-client.xml file is to deploy the application client. For more information on deploying a client using the Administration interface, see the Sun ONE Application Server Developer’s Guide.
Elements in sun-application-client.xml file
Elements in the sun-application-client.xml file are as follows:
Attributes
Elements can contain attributes (name, value pairs). Attributes are defined in attributes lists using the ATTLIST tag.
None of the elements in the sun-application-client.xml file contain attributes.
sun-application-client
This is the root element describing all the runtime bindings of a single application client.
Subelements
The following table describes subelements for the sun-application-client element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
resource-ref
Maps the absolute JNDI name to the resource-ref element in the corresponding J2EE XML file.
Subelements
The following table describes subelements for the resource-ref element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
res-ref-name
Specifies the res-ref-name in the corresponding J2EE application-client.xml file resource-ref entry.
Subelements
none
default-resource-principal
Specifies the default principal (user) that the container uses to access a resource.
If this element is used in conjunction with a JMS Connection Factory resource, the name and password subelements must be valid entries in Sun ONE Message Queue’s broker user repository. See the “Security Management” chapter in the Sun ONE Message Queue Administrator’s Guide for details.
Subelements
The following table describes subelements for the default-resource-principal element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-4 default-resource-principal subelements
Element
Required
Description
only one
Specifies the name of the principal.
only one
Specifies the password for the principal.
name
Contains data that specifies the name of the principal.
Subelement
none
password
Contains data that specifies the password for the principal.
Subelement
none
ejb-ref
Maps the ejb-ref-name in the corresponding J2EE ejb-jar.xml file ejb-ref entry to the absolute jndi-name of a resource.
Subelements
The following table describes subelements for the ejb-ref element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
ejb-ref-name
Specifies the ejb-ref-name in the corresponding J2EE ejb-ref.xml file ejb-ref entry. This element locates the name of the ejb reference in the application.
Subelement
none
resource-env-ref
Specifies the name of a resource env reference.
Subelements
The following table describes subelements for the resource-env-ref element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
resource-env-ref-name
Specifies the res-ref-name in the corresponding J2EE application-client.xml file resource-env-ref entry.
Subelements
none
jndi-name
Contains data that specifies the absolute jndi-name of a URL resource or a resource in the application-client.xml file.
Subelement
none
Application Client Container Configuration File
The sun-acc.xml file tracks changes in Sun ONE Application Client Container configuration.
Elements in the sun-acc.xml File
Elements in the sun-acc.xml file are as follows:
client-container
Defines Sun ONE Application Server specific configuration for the ACC. This is the root element; there can only be one client-container element in a sun-acc.xml file.
Subelements
The following table describes subelements for the client-container element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Attributes
The following table describes attributes for the client-container element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
target-server
Defines the IIOP listener configuration of the target server.
Subelements
The following table describes subelements for the target-server element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Attributes
The following table describes attributes for the target-server element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
description
Contains data that specifies a text description of the containing element.
Subelement
none
Attributes
none
client-credential
Default client credentials that will be sent to the server. If this element is present, then it will be automatically sent to the server, without prompting the user for username and password on the client side.
Subelements
The following table describes subelements for the client-credential element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-11 client-credential subelement
Element
Required
Description
zero or more
Specifies a property which has a name and a value.
Attributes
The following table describes attributes for the client-credential element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
log-service
Specifies configuration settings for the log file.
Subelements
The following table describes subelements for the log-service element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-13 log-service subelement
Element
Required
Description
zero or more
Specifies a property which has a name and a value.
Attributes
The following table describes attributes for the log-service element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
security
Defines SSL security configuration for IIOP/SSL communication with the target server.
Subelements
The following table describes subelements for the security element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Attributes
none
ssl
Defines SSL processing parameters.
Subelements
none
Attributes
The following table describes attributes for the SSL element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
If both SSL2 and SSL3 are enabled, the server tries SSL3 encryption first. If that fails, the server tries SSL2 encryption. If both SSL2 and SSL3 are enabled for a virtual server, the server tries SSL3 encryption first. If that fails, the server tries SSL2 encryption.
cert-db
Location and password to read the certificate database. SunONE Application Server provides utilities with which a certificate database can be created. certutil, distributed as part of NSS can also be used to create certificate database.
Subelement
none
Attributes
The following table describes attributes for the cert-db element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
auth-realm
JAAS is available on the ACC. Defines the optional configuration for JAAS authentication realm.
Authentication realms require provider-specific properties, which vary depending on what a particular implementation needs.
For more information about how to define realms, see the Sun ONE Application Server Developer’s Guide.
Here is an example of the default file realm:
<auth-realm name="file"
classname="com.iplanet.ias.security.auth.realm.file.FileRealm">
<property name="file" value="instance_dir/config/keyfile"/>
<property name="jaas-context" value="fileRealm"/>
</auth-realm>
Which properties an auth-realm element uses depends on the value of the auth-realm element’s name attribute. The file realm uses file and jaas-context properties. Other realms use different properties.
Subelements
The following table describes subelements for the auth-realm element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-18 auth-realm subelement
Element
Required
Description
zero or more
Specifies a property which has a name and a value.
Attributes
The following table describes attributes for the auth-realm element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-19 auth-realm attributes
Attribute
Default Value
Description
auth-realm-name
none
Defines the name of this realm.
classname
none
Defines the Java class which implements this realm.
property
Specifies a property, which has a name and a value.
Subelement
none
Attributes
The following table describes attributes for the property element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 2-20 property attributes
Attribute
Default Value
Description
name
none
Specifies the name of the property.
value
none
Specifies the value of the property.
