Using Servlets at Metawerx
This section contains information on using servlets, including updating servlets in real-time, configuration and debugging.
This information is important to read if you are developing with servlets on a live internet server.
FAQ Contents:
The JavaSoft website contains links to download the Java Servlet Development Kit API (JSDK)
The Free Scripts/Servlets option under the Resources section in SiteWinder contains a series of useful servlets that are already installed as part of your site. Configuring and using these servlets is a good way to get started and to get some ideas of what is possible using servlet technology.
It is also very useful to start with the servlet examples available in the JSDK (Java Servlet Development Kit). If you are new to servlets, try to modify and compile these servlets first, then run them on your metawerx site.
Apart from developing your own servlets, many useful servlets can be downloaded from sources on the internet.
Check the Servlet Resources link for further information.
If you are having problems with your servlets, the place to start looking for answers is the Servlet Master Log.
This log contains exceptions that your servlets haven't caught, and other errors that are logged by the system, as well as messages output with System.out.println(). The ServletExec Master Log can be viewed by any user, so not all messages in there will be caused by your own servlets.
The Servlet Master Log (ServletExec.log) is located in the SiteWinder Tools menu under Servlet Logs, and can also be accessed from within ServletExec's Administration Panel. Your login details for SiteWinder and ServletExec are in the email that is sent to you containing your site information.
The other logs are your personal servlet logs, which can be written to using the log() function from your servlets. This function is available in all HttpServlet-derived classes and writes to the Servlet.log file, cached in chunks of 40k. This caching amount can be configured within ServletExec. This logging is faster, and messages cannot be seen by any other users on the server.
Other log files listed are older versions of the servlet logs. When the server is reset, or the master log is full, it is renamed to ServletExec.log.1. The Servlets.log files do the same thing, and there may be up to 9 servlet logs files kept, with Servlet.log.9 being the oldest.
Using files with your Servlets
When reading from and writing to files from your servlets, it is important to remember that you are working in a secure environment.
For this reason, you will experience Security Exceptions if you simply try to write to a file such as "myfile.txt".
There are two ways to discover the correct location for data files.
If you still experience Security Exceptions, please contact us for assistance at support@metawerx.net
Catching all Exceptions and Errors inside your own servlets
You can catch all errors that occur in your service(), doGet() and doPost() methods by using try/catch blocks around the entire sections of code you want to trace. This will allow all exceptions to be written to your Servlet Logs instead of the Servlet Master Log.
For example:
Change your service/doPost/doGet method as follows:
Old:
public void service(HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException {
// ...
// your servlet code
// ...
}
New:
public void service(HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException {
try {
// ...
// your servlet code
// ...
} catch (Exception e) {
log("[MyServletName] The following Exception occurred: "+e);
e.printStackTrace();
} catch (Error e) {
log("[MyServletName] The following Error occurred: "+e);
e.printStackTrace();
}
}
Using this method, all Errors and Exceptions thrown by your code will be caught by your new Exception Handler and logged to your private log files.
Remember that logs written with log() are cached for up to 40k for faster performance, so modify this setting under the Logs option in ServletExec if you want less caching (for example, if you are debugging in real-time).
The e.printStackTrace() function dumps your exception details to the Master Log however, so if you also want to catch the full text of the stack trace, you can develop a function to send this to an output stream using e.printStackTrace(YourOutputStream)
You may also send the logs to a different location, such as to the user over the web, by checking if res.getOutputStream() is still valid.
JavaSoft The JavaSoft website contains links to many Java resources as well as the complete Java API. Most Java features are available from within servlets.
Servlet Specifications and API This link contains information on the official specification for Servlets and links to download the JSDK (Java Servlet Development Kit) API.
JSP Specifications and API This link contains information on the official specification for JSP (Java Server Pages).
Tomcat The Tomcat main page contains links to download Tomcat, links to the tomcat newsgroup mailing-lists
ServletExec The ServletExec main page contains links to download a version of ServletExec you can use at home for development use, as well as many other resources for servlet programmers including a good booklist.
Servlet Newsgroups Three of the most valuable sources of information available are the Servlets newsgroup (available at JavaSoft), the ServletExec newsgroup (available at New Atlanta) and the Tomcat Newsgroup (available at the Tomcat Main Page).
CoolServlets contains some good free servlets and links to more servlet resources.
Configuring Servlets in ServletExec's Administration Panel
Configuring your servlets helps you to reload them whenever necessary. This is a big help in servlet development if you are uploading new versions to the server during development and want quick refreshes.
To access ServletExec, go to http://yoursitename/servlet/admin. ServletExec Administration can also be accessed from the SiteWinder Tools menu.
Next, find the blank entry form at the top of the page. You will notice their are a series of forms, one for each servlet that is configured. Servlets can be configured one at a time, by filling out the blank subform that appears at the top of the page, then clicking Submit.
For the most basic configuration (that just adds your servlet to the list), enter the details as follows:
* do not enter the servlet class as YourServletClass.class, as the .class extension is added automatically by ServletExec
Then click Submit.
The page will refresh, and you will now be able to unload the servlet whenever you need to by using the unload-feature. To unload a servlet, simply access ServletExec's Administration Panel, find the servlet you want to unload, and remove the checkmark from the [x] Loaded box, then click Submit.
Note: ServletExec quick-help provides extra information not listed here. See the end of every page in the ServletExec Administration Panel for help on what each field does and how to use it.
Manually Unloading Servlets using ServletExec's Administration Panel
To access ServletExec, go to http://yoursitename/servlet/admin. ServletExec Administration can also be accessed from the SiteWinder Tools menu.
To unload a servlet, simply access ServletExec's Administration Panel, find the servlet you want to unload, and remove the checkmark from the [x] Loaded box, then click Submit.
Removing Servlets from ServletExec's Administration Panel
If you are not using a particular servlet any more, and want to remove it's configuration from ServletExec's Administration Panel, follow these steps:
- Access ServletExec's Administration Panel using SiteWinder or http://yoursitename/servlet/admin
- Find the servlet you want to remove
- Clear all fields in the subform
- Click Submit
The page will reload and the servlet will no longer be listed.
Adding Initialization Arguments for your servlets
You can use settings with your servlets, by using initialisation arguments.
This allows your servlets to read settings as they start up, to prevent hardcoding certain information into the servlet such as JDBC driver names and configuration file locations.
You will find this is a very useful feature of servlets, as it allows the same servlet to access different configuration information in your local-environment, and the server environment.
Initialization arguments can be set using the ServletExec Administration panel.
To access ServletExec, go to http://yoursitename/servlet/admin. ServletExec Administration can also be accessed from the SiteWinder Tools menu.
The example below sets up two arguments, "datafile" and "emailAddress". For the purpose of the example, we will assume that your servlet uses these two arguments to access data from a configuration file and sends it to your email address.
Next, find the entry for the servlet you want to add arguments to, or add the servlet if it is not already added. (see the topic titled Configuring Servlets in ServletExec's Administration Panel).
Enter the following example arguments in the Initilization Arguments field. datafile=d:/httpd/users/myconfig.data,emailAddress=info@yourdomain.com
* use your own email address of course
Then click Submit.
In your servlet, you can now access this information by using the following calls:
If you are using ServletExec at home, you may configure your servlets to use a different location for their datafile, for example:
Now when your servlet runs on the metawerx server, it will use the d:/httpd/users/myconfig.data datafile, but when running at home, it will use c:/inetpub/wwwroot/myservlet/myconfig.data.
Forcing Servlet Class Files to reload, when the servlets already been loaded by the VM
To force the server to refresh a servlet that has already been loaded by the VM, there are two things you can do. Note that deleting the class files or servlets will not cause them to be unloaded from the VM.
1. The first method is to upload the servlet again, then access it using the browser. This usually forces the VM to reload the servlet, and it's dependant class files, if the uploaded servlet is newer than the one already loaded in memory.
2. The second method is to configure your servlets using ServletExec (the Servlet Administration tool accessable from SiteWinder), which enables you to manually unload a particular servlet whenever you need to by unchecking the box marked [x] Loaded and then clicking Submit. This is the preferred method, and ensures the class is unloaded correctly. Note that you can configure a servlet even after it has been loaded without configuration (for example, you uploaded it, tried it, and now want the server to reload a new version). The easiest way to do this is to add the entry using the name of the class. For example, if your class name is SiteWinder.class, just enter the Servlet Name as SiteWinder and the Servlet Class as SiteWinder and leave the other fields blank. This will usually cause the servlet engine to reload a new instance as soon as you access the servlet again.
Hint: do not enter your class using the .class extension in the Servlet Class field, as the .class extension is added automatically by SiteWinder.
Forcing Class Files to reload, when the classes have already been loaded by the VM
If your classes have been uploaded to the /servlets folder (as opposed to the /classes folder), and those classes have already been loaded by the VM, they may or may not refresh automatically. There are two methods that can be used to force the classes to refresh. Note that deleting the class files or servlets will not cause them to be unloaded from the VM.
1. The first method is to re-upload the servlet that accesses the class files, and the re-upload the class files using FTP, then access the servlet using the browser. This usually forces the VM to reload the servlet and it's dependant class files because the uploaded servlet is newer than the one already loaded in memory.
2. The second method is to configure your servlets using ServletExec (the Servlet Administration tool accessable from SiteWinder) then you can manually unload a particular servlet whenever you need to by unchecking the box marked [x] Loaded and then clicking Submit. This is the preferred method, and ensures the class is unloaded correctly.
| SiteWinder WebSite Administration Server v1.15, © MetaWerx 1997-2015. All rights reserved. |