This section covers the most common problems you may encounter when using the Application Server:
Port Conflicts Debugging Multiple Instances on the Same Server
Application Generates Error persistence.support.JDODataStoreException
Cannot Undeploy Or Redeploy Application With Open Streams to Jar Files (Windows Only)
Cannot Reinstall Application Server After Manual Deletion of Directories
Bundled ANT throws java.lang.NoClassDefFoundError in main Thread
Changing Exploded Application Files Does Not Update /generated/xml Directory
If the .asadmintruststore file does not exist in the server administrator's home directory, you may experience serious bugs when upgrading certain applications hosted on the server.
If possible, the asadmin start-domain domain1 command should be run by user who installed the server.
If it is not run by that user, the .asadmintruststore file should be moved or copied from the home directory of installing user to the home directory of the running user.
Note that if the file is moved (not copied) from the installing user's home directory to the running user's home directory, you might experience application upgrade problems, as described in bugs 6315957, 6309079, 6310428 and 6312869, because the upgrade/install user (normally root in Java ES) will no longer have the .asadminstruststore file in his or her home directory.
There may be instances when the .asadminstrustore file for a domain has been has been deleted. In such cases, you can create a new .asadminstrustore file.
Use the asadmin start-domain command to start the domain you want to manage.
Note that this is a local asadmin command, and as such it does not require an ~/.asadmintruststore file to start the domain.
Run any remote asadmin command.
A remote asadmin command is one that requires ---user, ---passwordfile (--password), ---host and ---port options to be specified on the command line, and needs the target domain to be running. A typical remote asadmin command is asadmin list.
Accept the new Domain Certificate by pressing “y” when prompted.
The command asadmin start-domain fails with one of the following errors:
When issued with no arguments, the command asadmin start-domain fails with the error:
CLI143 There is more than one domain in C:\\Sun\\AppServer\\domains. Please use operand to specify the domain. CLI156 Could not start the domain null.
This error occurs when there is more than one domain in the domains directory, none of them is named domain1, and no domain is specified with the start-domain command.
Specify the domain when issuing the start-domain command:
asadmin start-domain domain1
This message comes from Application Server 8. The full message looks like either:
Could not start the domain. There are no domains.
or
Could not start the domain. No default domain. Need to enter a domain.
This error occurs when Application Server 8 is installed on the same system, and its asadmin command (at /usr/sbin) is found on the PATH before the asadmin command for Application Server 8 at install_dir/bin. The situation is especially likely to occur on Solaris/Linux systems when . is not specified as part of the PATH variable. Without . in the PATH, the asadmin command in /usr/sbin is found first, even when the current directory is install_dir/bin.
Make sure install_dir/bin is in the PATH ahead of /usr/sbin, or that . is in the PATH ahead of /usr/sbin if you access asadmin by changing directories to install_dir/bin. Alternatively, if you do change to install_dir/bin to run asadmin, be sure to include./ in the command name; for example:
cd install_dir/bin ./asadmin |
If your domain or node agent is stopped unexpectedly (for example, if you need to restart your machine), you can configure your system to automatically restart the domain or node agent on reboot.
To restart your domain on a UNIX platform, add a line containing the appropriate asadmin start-domain command to your /etc/inittab file. If you use /etc/rc.local, or your system’s equivalent, place a the desired asadmin command in /etc/rc.local.
For example, to restart domain1 for an Application Server installed in the /opt/SUNWappserver directory, using a password file called password.txt, add the following line to /etc/inittab or /etc/rc.local:
das:3:respawn:/opt/SUNWappserver/bin/asadmin start-domain --user admin --passwordfile /opt/SUNWappserver/password.txt domain1
Be sure to put the text on one line. The first three letters are a unique designator for the process and can be altered.
To restart a node agent, the syntax is similar. For example, to restart agent1 for an Application Server installed in the /opt/SUNWappserver directory using a password file called password.txt, add the following line to /etc/inittab or /etc/rc.local:
das:3:respawn:/opt/SUNWappserver/bin/asadmin start-node-agent --user admin --passwordfile /opt/SUNWappserver/password.txt agent1
To restart automatically on Microsoft Windows, create a Windows Service. Use the appservService.exe and appserverAgentService.exe executables shipped with Sun Java System Application Server in conjunction with the Service Control command (sc.exe) provided by Microsoft.
The sc.exe command comes with Windows XP and is either located in the C:\\windows\\system32 directory or C:\\winnt\\system32 directory.
As of this writing, the Windows 2000 sc.exe is available for download at: ftp://ftp.microsoft.com/reskit/win2000/sc.zip. For more information on using sc.exe, see:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dndllpro/html/msdn_scmslite.asp.
Use appservService.exe and appservAgentService.exe as follows:
C:\\winnt\\system32\\sc.exe create service_name binPath= \\"fully_qualified_ path_to_appservService.exe \\"fully_qualified_path_to_asadmin.bat start_command\\" \\"fully_qualified_path_to_asadmin.bat stop_command\\"" start= auto DisplayName= "display_name" |
To create a service called SunJavaSystemAppServer DOMAIN1 that starts and stops domain1 using password file C:\\Sun\\AppServer\\password.txt, run the following command:
C:\\windows\\system32\\sc.exe create domain1 binPath= "C:\\Sun\\AppServer\\ lib\\appservService.exe \\"C:\\Sun\\AppServer\\bin\\asadmin.bat start-domain --user admin --passwordfile C:\\Sun\\AppServer\\password.txt domain1\\" \\"C:\\Sun\\AppServer\\bin\\asadmin.bat stop-domain domain1\\"" start=auto DisplayName= "SunJavaSystemAppServer DOMAIN1" |
To create a service that starts and stops the node agent agent1, run the following command:
C:\\windows\\system32\\sc.exe create agent1 binPath= "C:\\Sun\\AppServer\\ lib\\appservAgentService.exe \\"C:\\Sun\\AppServer\\bin\\asadmin.bat start-node-agent --user admin --passwordfile C:\\Sun\\AppServer\\ password.txt agent1\\" \\"C:\\Sun\\AppServer\\bin\\asadmin.bat stop-node-agent agent1\\"" start=auto DisplayName="SJESAS_SE8.1 AGENT1" |
The start and stop commands entered as part of the binPath= parameter must have the correct syntax. To test, run the commands from the command prompt. If the commands do not properly start or stop the domain or node agent, the service will not work correctly.
Also, do not use a mixture of asadmin start and stop commands and service start and stops. Mixing the two can cause the server status to be out of sync. For example, the service might not show that the component has started even though the component is not running. To avoid this situation, always use the sc.exe command to start and stop the component when using services.
Handle the password and master password required when starting in one of the following ways:
On Microsoft Windows, configure the service to ask the user for the password.
In the Services Control Panel, double-click the service you created.
In the Properties window, click the Log On tab.
Check “Allow service to interact with desktop” to prompt for the required passwords when starting the component.
You have to log in to see the prompts, and entries are not echoed back as you type them. This method is the most secure way to use the services option, but user interaction is required before the service becomes available.
If the “interact with desktop” option is not set, the service stays in a “start-pending” state and appears to hang. Kill the service process to recover from this state.
On Windows or UNIX, create a domain using the --savemasterpassword=true option and create a password file to store the admin password. When starting the component, use the --passwordfile option to point to the file that contains the password. The admin password can also be added by using the --password option with the asadmin start command. Be aware that this method is less secure because the admin password is stored in clear text.
For example:
Create a domain with a saved master password. Using this syntax, you are prompted for the admin password and master password:
asadmin create-domain --adminport 4848 --adminuser admin --savemasterpassword=true --instanceport 8080 domain1 |
On Windows, create a service using a password file to populate the admin password:
C:\\windows\\system32\\sc.exe create domain1 binPath= "C:\\Sun\\AppServer\\lib\\appservService.exe \\"C:\\Sun\\AppServer\\bin\\asadmin.bat start-domain --user admin --passwordfile C:\\Sun\\AppServer\\password.txt domain1\\" \\"C:\\Sun\\AppServer\\bin\\asadmin.bat stop-domain domain1\\"" start= auto DisplayName= "SJESAS_PE8.1 DOMAIN1" |
The path to the password file password.txt is C:\\Sun\\AppServer\\password.txt. It contains the password in the following format:
AS_ADMIN_password=password |
For example, for a password adminadmin:
AS_ADMIN_password=adminadmin |
On UNIX, use the --passwordfile option in the line you add to the inittab file:
das:3:respawn:/opt/SUNWappserver/bin/asadmin start-domain --user admin --passwordfile /opt/SUNWappserver/password.txt domain1 |
The path to the password file password.txt is /opt/SUNWappserver/password.txt. It contains the password in the following format:
AS_ADMIN_password=password |
For example, for a password adminadmin:
AS_ADMIN_password=adminadmin |
Creating a service using a password that is populated from a command line option:
C:\\windows\\system32\\sc.exe create domain1 binPath= "C:\\Sun\\AppServer\\ lib\\appservService.exe \\"C:\\Sun\\AppServer\\bin\\asadmin.bat start-domain --user admin --password adminadmin domain1\\" \\"C:\\Sun\\AppServer\\bin\\ asadmin.bat stop-domain domain1\\"" start=auto DisplayName="SJESAS_PE8.1 DOMAIN1" |
The following Application Server logs are useful for troubleshooting installation problems:
Server log file — For troubleshooting server configuration and deployment problems
HTTP server access logs — For troubleshooting HTTP server problems, and for tracing the activity of HTTP requests entering the Application Server instances
Both the installation and uninstallation programs create log files and log all installation and uninstallation events to these files. The primary purpose of these log files is to provide troubleshooting information.
In addition to installation program messages and log files, operating system utilities such as pkginfo and showrev on Solaris and rpm on Linux can be used to gather system information.
Log file entries include information about the attempted action, the outcome of the action, and, if applicable, the cause of failure. The log files contain the followingtypes of message entries:
INFO — These messages mark normal completion of a particular installation tasks.
WARNING — These messages mark non-critical failures. Warning messages generally contain information about the cause and the nature of the failure, and also provide possible remedies.
ERROR — These messages mark critical failures that cause installation or uninstallation status to be reported as Failed. Error messages generally provide detailed information about the nature and the cause of the problem that occurred.
The domain-specific logs are located in install_dir/domains/domain1/logs/. Log files for the server installation in general are located as follows:
Solaris, root user installation/uninstallation:
/var/sadm/install/logs
Solaris, non-root installation/uninstallation:
/var/tmp
Linux installation/uninstallation:
/var/tmp
Windows installation/uninstallation:
%TEMP%
Log file names are different for each product distribution, but are platform independent:
Enterprise Edition, both SDK and Application Server distributions, main installation/uninstallation log files:
Install_Application_Server_8PE_<timestamp\>.log Uninstall_Application_Server_8PE_<timestamp\>.log
Enterprise Edition, Application Server only distribution, low-level installation/uninstallation log files:
Sun_Java_System_Application_Server_Platform_Edition_install.B<timestamp\> Sun_Java_System_Application_Server_Platform_Edition_uninstall.B<timestamp\>
Enterprise Edition, SDK distribution, low-level installation/uninstallation log files:
Java_2_Platform__Enterprise_Edition_1.4_SDK_install.B<timestamp\> Java_2_Platform__Enterprise_Edition_1.4_SDK_uninstall.B<timestamp\>
Enterprise Edition, main installation/uninstallation log files:
Install_Application_Server_8EE_<timestamp\>.log Uninstall_Application_Server_8EE_<timestamp\>.log
Enterprise Edition, low-level installation/uninstallation log files:
Sun_Java_System_Application_Server_Enterprise_Edition_ install.B<timestamp\> Sun_Java_System_Application_Server_Enterprise_Edition_ uninstall.B<timestamp\>
Things to check for this error include the following:
If the console window is still open, the expected message is:
Domain domain Started
where domain is the name of the default domain. This indicates that the default domain was started successfully.
If the console window is already closed, check for messages in the log file:
install_dir/domains/domain1/logs/server.log
If startup was successful, the expected message is similar to that on the console, and appears at the end of the log file:
[INFO][...][..][date&time][Application server startup complete .]
The server might be running at a different port number than expected, either because it was intentionally installed there, or because another server was already running on the default port when the server was installed.
Examine the server's configuration file:
install_dir/domains/domain1/config/domain.xml |
Find the http-listener element.
Inspect the value of the port attribute.
Be sure to enter the correct port number when invoking the server.
The server's default port number is 8080, however, there are a number of ways in which the expected value can change:
A different port number was specified during installation.
A previous installation exists.
If the specified port number is already taken by another application when the server is started, the port number rolls forward to the next available number. For example, if a server is already running on the default 8080 port, the new Application Server instance uses port number 8081. If two servers are running, the port number rolls to 8082, and so on.
When attempting to open the start page of the Application Server, the initial screen does not appear.
Things to check include the following:
If the server cannot be accessed from the web, but it is running locally, then the server is actually running.
Verify that the server is running locally.
Log on to the machine where the server is running.
Go to the local web page. For example, if 8080 is the default port, go to:
http://localhost:8080/ |
If the start page does appear, there is a problem with the web connection that prevents accessing the server remotely. If the start page does not appear, see Did the Server Start?
The server should be accessible directly from the host on which it is running (localhost); for example, using the default port, 8080:
http://localhost:8080/
A server instance running on localhost may not be accessible if the server host machine is connected to the web through a proxy. To solve this problem, do one of the following:
Set the browser to bypass the proxy server when accessing localhost. Refer to the browser's help system for information on how to do this.
Use the fully-qualified host name or IP address of your system; for example:
http://myhost.mydomain.com:8080/ |
To find the host name and domain for the localhost machine:
On Microsoft Windows — On the desktop, right-click My Computer and select Properties from the pop-up menu. A System Properties dialog is displayed. Click Network Identification to see the computer name.
On Solaris or Linux — Type hostname at the command prompt.
The Administration Console provides an interface for administrative functions. If the Administration Console is not accessible, it might be for one of several reasons.
The server must be running before the Administration Console can be accessed.
Review the information in Did the Server Start? to determine if the server is running.
The default port number for the EE and SE Administration Console is 4849; for the PE Administration Console it is 4848. Also note that the URL for the EE and SE console requires secure HTTP (https://servername:4849.), whereas the PE console uses standard HTTP (http://servername:4848). However, it could be running on a different port number than expected, either because it was intentionally installed there, or because that port was taken when the server was started.
Refer to Was the Server Started at the Expected Port? for guidelines on verifying the port on which the Administration Console is running, and be sure to enter the correct port number and HTTP protocol when invoking the Administration Console.
According to the J2EE 1.4 Specification, the Security Manager is not optional; it must be enabled in the Application Server. Since there is no configuration interface in the Application Server for disabling the Security Manager, it can only be disabled by directly modifying the domain.xml configuration file in such a way that the following line is removed:
<jvm-option\>-Djava.security.policy=yourPolicy</jvm-option\>
The -Djava.security.policy=yourPolicy option must be present in the domain.xml file to access the Administration Console.
If a particular application cannot be accessed through the Application Server, some things to check include the following:
If the Application Server is not running, applications will not be accessible.
Review the information in Did the Server Start? to determine if the server is running. The server must be running before a server application can be accessed.
An application must be successfully deployed before it can be accessed.
Check the server's log file:
install_dir/domains/domain1/server.log
You are getting the error, Invalid user or password, but you installed the system with the Don't Prompt option, so the password should be supplied automatically.
The correct password may not have been specified during installation, or it may not be passed when the domain is started.
Check the password in the .asadminprefs file. On UNIX/Linux systems, it is in the home directory for the user under which the server was installed. On Windows, it is in C:\\Documents and Settings\\username. The contents look something like this:
AS_ADMIN_USER=admin AS_ADMIN_PASSWORD=administrator
If you have forgotten the administrator user name, you can find it by inspecting the .adminprefs file, as described in the section above, or by inspecting the install_dir/domains/domain1/config/keyfile, where domain1 is the default domain. For a different domain, substitute its name in the path.
If you have forgotten the administrator password, you will need to create a new user name-password pair by removing the user name and password, creating new ones, and restarting the server. (You will not be able to read the password, because it is encrypted in the keyfile.)
Stop the server, if it is currently running.
Change to the appropriate WEB-INF directory; for example:
install_dir/lib/install/applications/adminapp/adminapp_war/WEB-INF |
Comment out the entire <security-constraint\> element in the web.xml file.
Do not delete the element, as you will be reenabling it later. This action disables security for command-line operations.
The commands will still expect a value for --username (or -u) and --password (or -w). But these can be dummy values, since the server side does not impose any security.
Start the server.
At this point, the server does not have command-line security.
Run the following command:
asadmin create-file-user --user <dummy\> --password <dummy\> --userpassword <new_secret\> --groups asadmin <new_user_id\> |
This command creates the following new entry:
<install_dir\>/domains/domain1/config/keyfile |
Uncomment the <security-constraint\> element in web.xml file.
Restart the server for the new user name-password to take effect.
When the server is started, any remote command-line operations will need new_user_id and new_secret as user name and password.
If a message similar to the following is displayed when starting the Application Server on Microsoft Windows, a server port conflict has occurred:
Address already in use
This error occurs when another application is running on the Application Server port (default 8080), or because a previous instance of the Application Server did not shut down cleanly.
Other things to check include the following:
If another application is using the server's port, stop the other application, then restart the Application Server.
The installer attempts to avoid port conflicts by choosing the next available port when the default port is in use—but that only works if application using the default port was running when the Application Server was installed.
Use the asadmin stop-domain command to stop the server, or explicitly kill the Java process and then restart the Application Server.
Port conflict errors can occur when debugging multiple instances on the same server that are part of the same cluster.
Modify the domain.xml file to remove the address attribute from the -Xrunjdwp option in the java-config element for the cluster. This results in the JVM choosing a random debug port for the instance. The port number chosen for the instance is displayed in the server log when it is started; for example:
Before:
debug-options="-Xdebug -Xrunjdwp:transport=dt_socket,server=y, suspend=n,address=9009"
After:
debug-options="-Xdebug -Xrunjdwp:transport=dt_socket,server=y, suspend=n"
This problem only occurs on Windows 2000/XP systems with the Application Server Enterprise Edition (not Platform Edition) software, and is due to a known Windows security flaw rather than a problem with the Application Server itself.
The problem occurs when two or more instances of the Application Server are created using the same port number for the instanceport option; for example:
asadmin create-domain -adminport 5001 <options\> -instanceport 6001 <domain\ asadmin create-domain -adminport 5002 <options\> -instanceport 6001 <domain\>
When the two domains are started on a UNIX/Linux system, a port conflict error is thrown and the second instance fails to start. However, when the two domains are started on Windows 2000/XP, no error is thrown, both server instances start, but only the first instance is accessible at the specified port. When that first server instance is subsequently shut down, the second instance then becomes accessible. Moreover, when both instance are running, the Windows netstat command shows the duplicate listeners as active, but only the first listener can respond to requests.
Be sure to use unique port numbers for all server instances on Windows systems.
This error message occurs when attempting to start the server after deleting the J2SE directory that was specified during installation. This situation generally occurs after being informed during the install that the J2SE platform needs an upgrade, and the upgrade takes place after the Application Server installation.
To use the new J2SE for all domains, change the AS_JAVA variable in asenv.conf (Solaris/Linux), or asenv.bat (Windows).
The J2SE version can be changed on a per-domain basis by modifying the java-home attribute for the java-config element in the domain’s domain.xml file.
<java-config ... java-home="path" ...\>
A more time-intensive solution is to uninstall and then reinstall the server.
A com.sun.jdo.api.persistence.support.JDODataStoreException is generated by an application, with a nested java.sql.SQLException indicating a duplicate primary key.
Even if the application is checking for a CreateException, it does not see one. The Enterprise JavaBeans specification requires a CreateException to be thrown only if two beans with the same primary key are created in the same transaction, so a CreateException is not thrown on transaction rollback if two entity beans with duplicate primary keys are created.
If an application creates an entity bean with a duplicate primary key, check to see if the primary key exists by calling findByPrimaryKey before calling create.
Unexpected results are returned when setting variables in a command, such as:
asadmin set name={$a-b}
In this case, name is set to b, not {$a-b} because the shell syntax ${a=b} is interpreted as “if the variable a is unset, substitute the value b, otherwise substitute the value of a.” This is standard shell behavior. For example, consider the following:
asadmin set default-config.http-service.http-listener.http-listener-1.port= ${http-listener-1-port}
In this case, default-config.http-service.http-listener.http-listener-1.port is set to listener-1-port, which is invalid.
On Windows systems, after running an application, subsequent attempts to undeploy it or redeploy it throw exceptions about the server being unable to delete a file or rename a directory.
On Windows systems, an application may use getClass().getResource or getResourceAsStream methods to locate a resource inside the application, particularly in jar files that are in the application or accessible to it. If the streams remain open, subsequent attempts to redeploy or undeploy the application can fail. In addition, the Java runtime by default caches streams to jar files for performance reasons.
Be sure to close streams opened by your applications. Also, if an application needs to be redeployed or undeployed repeatedly, and also needs to obtain a resource from a jar file using getResource or getResourceAsStream, consider using getClass().getResource which returns a URL object, then invoke the url.setUseCaches method to turn off caching for that jar file, and then use url.getInputStream() to obtain the stream.
Although turning off caching for accesses to the jar file can slow down performance, this approach does allow the application to be undeployed or redeployed. Note also that if the getClass().getResourceAsStream method is used instead, then the jar file in which the resource is located will be cached (this is the default Java runtime setting) and remain open until the server is stopped.
If the Application Server directories are deleted manually rather than by means of the included uninstall the program, subsequent attempts to reinstall the Application Server in the same directory fail. This is because the installation directory information stored in /tmp/productregistry file remains even though the program directories have been removed.
Remove Application Server directory information from the <location\> property entries in the /tmp/productregistry file; for example, change:
<location\>/opt/SUNWappserver/jdk</location\>
to
<location\></location\>
Reinstall the Application Server in a different directory.
If the Application Server crashes, the server dumps a core file and, by default, restarts with the -Xrs flag, which prevents the dump of a JVM thread dump.
Comment out the -Xrs flag in the server.xml file for the Application Server.
Kill the server process (kill -3 on UNIX; Ctrl+Break on Windows).
When using the bundled Ant distribution for activities outside of Application Server, a java.lang.NoClassDefFoundError: org/apache/tools/ant/launch/Launcher may be thrown in the main thread.
Using the bundled ANT for activities outside the Application Server environment is not recommended.
The JES Service Registry (SR) deploys into Application Server 8.2 Enterprise Edition as part of the JES 5 release. The SR uses client certificate authentication to authenticate registered users. The SR has an option to generate a x509 certificate signed by the RegistryOperator certificate contained in the Application Server's truststore.
The problem is this client certificate authentication method depends on the location of the generated sun-web.xml file in the /generated/xml directory. When a deployed application is exploded and redeployed, the SR no longer know where to find the sun-web.xml file.
Modifying deployment descriptors after deployment is not recommended. If modifying a deployment descriptor after deployment is necessary, use the .reload functionality to force the application to reload. In the case of the Service Registry product, you will also need to modify the domain's web.xml file to include some login information. If you are having login issues, please double check to make sure their application is indeed reloaded by checking the server.log.