Sun Microsystems Logo

 

 
 

Sun[tm] Java (tm) System Application Server 7 Samples
Creating Your Own Samples Environment

If you are either sharing your application server installation with other users or your system user ID does not have write permissions to the area in which the application server is installed, then it is recommended that you create your own samples environment. The steps involved in creating your own samples environment can consist of:

  » Creating a New Administrative Domain and Application Server Instance
  » Creating a Copy of the Sample Applications

Creating a New Administrative Domain and Application Server Instance

If the application server was installed as part of a Solaris 9 installation, then you must create your own administrative domain and application server instance in order to work with the product. Additionally, if you are using a shared application server installation, you should create your own administrative domain to avoid any conflicts with other users.

If you already created your own samples environment and created an initial administrative domain and an application server instance by following the Getting Started Guide, then go back to the Sample Applications main page and continue reviewing how to work with the samples.

The Sun Java (tm) System Application Server 7 installation that is installed as part of a Solaris 9 installation contains only the necessary libraries, executables and other supporting files required to run an application server. No application server configuration exists upon installation.

To create an initial configuration, you must use the application server's asadmin command line interface (CLI). The create-domain subcommand of the asadmin CLI enables you to create an administrative domain in a location of your choice. Each administrative domain consists of an administrative server and application server instance configurations. When you create an initial administrative domain, you specify the administrative user name, password and port number associated with the administrative server of the domain.

Once you've created an administrative domain, you can create one or more application server instances within the domain. Each application server instance houses an HTTP server, the J2EE[tm] web and EJB containers and other application server facilities.

Create an Administrative Domain

By default, the create-domain subcommand creates the new administrative domain configuration under either /var/appserver/domains/ (in the case of the application server installed as part of a Solaris 9 installation) or /var/opt/SUNWappserver7/domains/ (in the case of an unbundled installation of the application server on Solaris). If you are logged in as a user that does not have write permissions to the default domain configuration area, then you must use the --path option to specify a suitable location for the newly created domain when executing the create-domain subcommand.

To create an administrative domain, follow these steps:

1. If you are not using the root user ID and your user ID does not possess the necessary permissions to create an administrative domain, you will need to either request that the systems administrator create or your domain or request that your user ID be added to the UNIX group that is able to create administrative domains.

User Permissions on UNIX Platforms: If the application server was installed using the root user ID, then special considerations must be taken into account when using a non-root user to work with the application server and the sample applications.

In order for a non-root user to create and delete administrative domains, the user ID must be added to the UNIX group that has write permissions to the domain configuration file. By default, the UNIX group asadmin has write privileges to the domain configuration file.

Alternatively, you can request that the system administrator use the root user ID to create your domain on your behalf by specifying the --sysuser option with your user ID on the create-domain subcommand.

Once an administrative domain is created under your user ID, you may execute asadmin subcommands to create new application server instances and perform a wide variety of administrative operations against the application server instances without the user ID belonging to the UNIX group that has write privileges for the administrative domain configuration file. Membership in the group is required only to create and delete administrative domains.

2. Ensure that either the /usr/sbin directory (in the case of the application server that is installed as part of a Solaris 9 installation) or the <install_dir>/bin directory (in the case of an unbundled install) is included in your environment's path.

3. From the command line, execute the following command to create a new administrative domain named "domain1":

asadmin create-domain --path <domain_config_dir> --adminport 4848 --adminuser admin --adminpassword password domain1

Where <domain_config_dir> specifies the location under which the administrative domain configuration will be created. The --adminport, --adminuser and --adminpassword options specify the initial settings of the new administrative server defined for the domain.

If the root user is executing the create-domain subcommand to create an administrative domain on your behalf, the --sysuser option should be used to specify the system user ID under which the administrative domain files and directories will be created. For example:

asadmin create-domain --sysuser ckamps --path <domain_config_dir> --adminport 4848 --adminuser admin --adminpassword password domain1

Upon execution of the create-domain subcommand, you should see the following message:

Created Domain domain1 successfully

If the name "domain1" has already been used, execute the create-domain subcommand again with another domain name. You can use periods and other characters in your domain names. You could use your login user name as a qualifier to help ensure that your domain name is unique. For example: ckamps.domain1.

When you execute the create-domain subcommand and the following error message is encountered, the message is an indication that your user ID does not have permissions to access the domain configuration files. See the steps above for either adding your user ID to the appropriate UNIX group or requesting that your systems administrator create the administrative domain on your behalf.

Cannot create domain : domain1
problem locking store /etc/appserver/domains.lck (Permission denied)

4. Execute the list-domains subcommand to display a list of all of the domains configured for the application server installation. (Execution of this read only command does not require your user ID to be part of the UNIX group that has write privileges to the domain configuration files).

asadmin list-domains
domain1 [<domain_config_dir>/domain1]

Where the value of <domain_config_dir> represents either the default location for newly created administrative domains or the value specified on the --path option of the create-domain subcommand.

Create an Application Server Instance

Once either the systems administrator has created an administrative domain on your behalf or you created the administrative domain, your next step is to create an application server instance under the newly created administrative domain. Creation of an application server under your own administrative domain does not require that your user ID be part of the UNIX group that has write privileges to the domain configuration files.

Execute the create-instance subcommand to create the application server instance:

asadmin create-instance --domain domain1 --instanceport 80 server1

Where "domain1" is the domain name specified during domain creation, "80" is the HTTP server port number of the application server instance and "server1" is the name of the instance. Specify appropriate values for these options depending on your specific environment. Since port numbers less than 1024 are not accessible to non-root users, you will need to specify a port number greater than 1024 if you are logged in as a non-root user.

As long as you have only a single administrative domain defined on your system, you do not need to specify the target domain name when creating an instance.

Your next step is to make your own copy of the sample applications.

Creating a Copy of the Sample Applications

Making your own copy of the sample applications involves two basic steps: copying the installed samples to your own area and customizing a set of properties used to interact with an application server instance.

Copy Samples Directory

Since the sample applications and the supporting Ant-based build files are contained in a common directory of your application server installation, you can make your own copy of the sample applications by simply copying the following directory to a location in which your user ID has write permissions:

<install_dir>/samples

Customize the common.properties File

Once you make a copy of the samples directory, you must ensure that the samples/common.properties file is configured to match your environment. The common.properties file specifies the environmental information required by the Ant-based build facility that is used to build and deploy the sample applications.

Property Description
admin.host

The name of the host on which the administrative server resides. For example, localhost if the administrative server is on the local machine.

admin.port The port number on which the administrative server is listening. For example, 4848.
admin.user The administrative user defined for the administrative domain. For example, admin.
admin.password

The administrative user's password.

During installation of the application server, this property is not set. You may either choose to set this property or enter the password during each deployment and undeployment operation with the samples.

You may either set this property in the common.properties file or set an environment variable named AS_ADMIN_PASSWORD with the value of the administrative password.

com.sun.aas.installRoot

The application server's installation directory. For example, in the case where the application server is installed as part of a Solaris 9 installation, the value of this property should be set to /usr/appserver.

com.sun.aas.javaRoot The location in which a compatible Java[tm] 2 SDK is installed.
com.sun.aas.pointbaseRoot

The PointBase installation directory. If PointBase was installed as part of the application server, then this property should be set to <install_dir>/pointbase where <install_dir> is the application server's installation directory.

If you are working with the application server that was installed as part of a Solaris 9 installation, then you will install PointBase and set this property in the next section.

com.sun.aas.webServicesLib

Location of the Java web services libraries. For example, <install_dir>/share/lib.

When the application server is installed as part of a Solaris 9 installation, the value of this property should be set to /usr/share/lib.

com.sun.aas.imqLib

Location of the Sun Java (tm) System Message Queue libraries. For example, <install_dir>/imq/lib.

When the application server is installed as part of a Solaris 9 installation, the value of this property should be set to /usr/share/lib/imq.

sunone.instance

The name of the application server instance to which sample applications are to be deployed.

sunone.instance.port The HTTP port number on which the application server instance is listening.

Return to the Sample Applications main page and continue reviewing how to work with the samples.