• Where to put html files?
  
  
  Put all your html, jsp or other files you want the server to serve in the htdocs/ directory.

• Why my configed servlet not shown in the unload servlets dialog box Please note the UI is only intended to show the servlets been used, not the all the servlets that are configed and mapped. To unmap a servlet, use cofnig servlet (http://localhost/srvConfig/) instead.

• How to use the config servlet?
  
  
  Start the server and connect to http://localhost/, click on the first link, 'Config the Server'. Enter admin for both username and password. After login click on the 'Edit user list' link and change the pass word for admin.
  If you don't want to use the config servlet anymore, you can disable it by remove the srvConfig.war file from wars/ directory, then either restart the server or click on the Reload Wars button on the UI.

• How to run server as NT service?
  First, run jvmInvoker.exe -i to install the service. Then use NT control services applet to start the "Bajie Http Web Server" service.
  NOTE: You must either copy the jvm.dll (found at your jdk bin/hotspot directory) to the directory where jvmInvoker is installed, or your JDK must be installed instead of just copied (so the registory values can be found). The code for getting the registry values is copied from KC Multimedia, and the source is available at service.cpp and jvmInvoker.cpp jvmInvoker.exe is included in the server package.

• I want to edit the extracted war files in defaultTmp/htdocs/bajieWarDir directly, how do I prevent the server override the files?
  set WAREXCATOVERRIDE to false in config/jzHttpSrv.properties. WARNING: this will prevent the server from overriding any WARs and autoreload on WARs will not working in this mode.

• How to add servlets?
  
  First, drop your servlet in the server's classpath (you can set it from config servlet or by edit the config/jzHttpSrv.properties file).
  By default htdocs/WEB-INF/classes and servlets/ directory are in classpath. (You can find the directory where you extract the server). So drop your servlet class files in those directory. If your servlet is a jar, you can drop it in either lib/ or htdocs/WEB-INF/lib directory, where all *.jar file will be automaticaly added in server classpath. Or you can add it to server classpath (to change server classpath, you can either manuly edit htodcs/WEB-INF/web.xml file and restart the server, or use config servlet http://localhost/srvConfig and click on edit webapp config link and edit it there).
  If you have parameters for your servlet, put them in a files named servletClassName.params.properties. For example, if you wrote a servlet counter.class, then put your servlet params as key=val in counter.params.properties, in the same place as counter.class.
  Now use your browser go to http://localhost/servlet/ServletClassName and your servlet will be in action (example, if your servlet is counter.class, then use http://localhost/servlet/counter and your servlet will be invoked).
  If you wish to map your servlet to a different url, then use the following step:
  Use your browser and connect to:
  http://localhost/srvConfig/ , this will open the config servlet.
  Click Edit Servlets , which is on the top of the screen. It will show you a list of servlet alias. To automatically find and add new servlets, click on the Show auto alias action button, this will go to a screen show all the servlets in the servlets/ directory. Select the servlets you want to add by check the check box on the left and change the alias name if you want to, then click on the submit button.
  The servlet can be invoke by: http://localhost/servlet/servletAliasName. You can also change the servlet mapping so the servlet request url can be anything by either use the config servlet or edit the WEB-INF/web.xml file (just as webapp).
  
  With the server class path feature, you can also add specical path for special classes. For example, you can add filters/ directory in your classpath and only put filter classes in that directory.
  
  To edit the server classpath, use config servlet http://localhost/srvConfig/ , login using admin/admin and click on the "Edit WebApp Config" button on top right corner of the screen, and append/delete classpath in the "Set Server Class Path" box.
  
  Note: If you jar your servlet, and you wish to use classname.params.properties file to provide parameters, then you need to jar the file with your classes.

• How to add .war files?
  
  There are 2 ways to add .war files.
  
  • Put your .war files in wars/ directory, and start the server. If the server is already started, click on the 'Reload Wars' button. The .war file will be listed with war context name same as the .war file name. For example, if your .war file is named tagTest.war, you can access it via http://localhost/tagTest/......
    
  • If you want to give your war context other name then the .war file name, then put the .war file in any directory under the install root, and edit the config/war.properties file and add /yourContext/=path/yourWarFileName.war
    you can use tagtest.war in wap.properties as an example.

• How to prevent server automatically map servlet alias to /servlet/ServletAlias?
  This feature is in versions 0.94z+. I don't have time to update the documents yet, another config option is available to set if the server automatically map servlets to URL mapping (if servlet will be mapped to /servlet/serveltAlias). It is AUTOADDSERVLETMAPPING=true/false in config/jzHttpSrv.properties.
  
  
  Historic note ;-) Long long time ago, the server automatically pick up servlets classes in servlets/ directory. People can drop their classes in there and access their servlet via http://host/servlet/ServletName directly without any config. However later on for speed and expandablity, web.xml file is used to map url and servlet, and config servlet is used to automatically give servlet a name and map it to a url. To ensure a smooth transition, any servlet that is given a alias is automatically mapped to /servlet/servletAlias. You can now disable it by set the propertie.

• How was the .tld file for jsp located?
  
  The search order for .tld files are:
  • If the .jsp file request the tld is in a war, then the WAR's web.xml file is searched for a matching for the uri. If match found, use the value as the uri.
    If no match found, the engine will try to find the uri with in the WAR file, related to the root of the WAR. (So if the tld is in WEB-INF/tlds/test.tld, the request uri should be WEB-INF/tlds/test.tld, with or with our a leading '/').
    If the uri ends with ".jar" extension, the engine will search for META-INF/taglib.tld as the tld file. For example, if the request uri is /WEB-INF/lib/tag.jar, then the engine will search for META-INF/taglib.tld in /WEB-INF/lib/tag.jar.
    If the above method failed, then the engine will try to locate the tld as if the jsp is not in a WAR (see step below).
  • If the .jsp file is not in a war, the engine will try to find the matching in the common web.xml file (htdocs/WEB-INF/web.xml). If match found, then the engine will try to open it as a file, related to webroot (related to htdocs directory). If no match found, and the uri starts with http:// or file://, then the engine will open a URL to it. Otherwise the engine will test if the request uri is a file. If the request uri is a file with path related to the htdocs/ directory, the engine will open it. If all the above failed, the engine will search for htdocs/WEB-INF/classes directory for the file and look into all .jar files in htdocs/WEB-INF/lib directory for the file. For example, if the request uri is test/test.tld, and htdocs/WEB-INF/lib/test.jar contains test/test.tld, the engine will find it and use it.
  • Note: I think the best way to store and use a .tld file is, jar the .tld file with other beans, tags that used by the jsp file in one jar (name the tld file /META-INF/taglib.tld in the jar). And put it in WEB-INF/lib directory. In the jsp or in the web.xml taglib mapping, set the value to /WEB-INF/lib/yourlibjar.jar. (yourlibjar.jar is the jar with all the related classes). This way deploy jsps and the taglib is very easy, just 2 simple drop of file and everything will be in place.

• Where to put .jsp files? Where do I put bean classes for jsp files?
  
  • Put .jsp files anywhere under the htdocs/ directory except the WEB-INF/ directory.
  • put bean classes in WEB-INF/classes directory, and if beans is jared, put in WEB-INF/lib directory. It is the same for .war files and taglib files.
    If you jar your taglib, you can either put the .tld file in WEB-INF/classes directory or jar it with your taglib. However if you jar them, make sure they got different names or different pathes.

How to set autoreload for servlets and .war files?

Open your browser and connect to: http://localhost/srvConfig/, and edit your current server. Servlet autoreload and other server properties can be set there. Make sure you save server properties before exit. The server will compare to see if servlet class file's date is newer before treating a request that access the servlet. If it is newer the server will unload the servlet and load the new version.
NOTE: if the classes is not in a jar file, autoreload can be slow because the server checks all loaded classes files in the classes' path to see if they are out of date.
NOTE: If you change from not autoreload to autoreload without restart, use 'Reload classpath' button to ensure the server get all the class files registered. Othewise auto reload may not work.

CGI support

The default CGI directory is .\cgi\bin\ , changed the PERLEXECLOC property in config/jzHttpSrv.properties to set the perl interperter. If that property is not set, all CGI are supposed to be executables.
A request of form http://hostname/cgi/bin/XXXX will execute the XXXX cgi script. The server checks to make sure XXXX exists in cgi\bin\ directory before execute it.

HTTPS support

jzHttpSrv has build in support for sun's JSSE. For legal reasons, the jar files are not included. If you want, go to java.sun.com to download JSSE (as long as you are in US, you can do this) , and add the jars in the classpath. Once you downloaded the zip file, unzip it and find the 3 jar files, jsse.jar, jcert.jar and jssl.jar. put them in the same directory with jzHttpSrv.jar, then go to that directory and type: java -cp jsse.jar;jcert.jar;jssl.jar;jzHttpSrv.jar jzHttpSrv
You can put the jars in the JDKPATH/jre/lib/ext directory so you can start the server the normal way.

With version 0.95h, you can start server with the 'servers' menu. After the server list dialog popup, click on 'add server' button. Check the 'ssl' check box, and select the testkeys file (which is supplied by sun. If you have a key, use your key instead). The password for testkeys is 'passphrase'.

Customized logging is REMOVED!! (Added since version 0.30c, removed after version 0.94z. Use filters for customized logging.)

Customizable error page
You can specify which html page, jsp page or servlet to involve when a error is encountered. Use the config servlet, click on Edit WebApp Config button, and at the bottom of the new page, you can map specific error code or exception to the html, jsp or servlet. If you wish to use a servlet, you must use put its url mapping to the Error Page Location box.
The message is passed to the jsp or servlet via: request Attribute "javax.servlet.error.message" -> exception message. See htdocs/errorReport.jsp for example.

Browsers with no cookie support
• For simple GET or POST operation: If browser do not support cookies, you must embedded the sessionid in forms or URL. The name must be "jsessionid" (according sun spec) or classpath. The server will pick it up automatically. See servlets/test/NoCookieSession.java for example
• For POST with multipart/form-data com.BajieSoft.HttpSrv.gzHttpServletRequest is the under line implemention of HttpServletRequest. Usually you don't need to use setSessionID() function. But when you are doing POST with multipart/form-data and need to deal with browsers with no cookie support, you need to embedded the server id as above, and make sure it is the first item in the form. After parse it out, cast your HttpServletRequest to com.BajieSoft.HttpSrv.gzHttpServletRequest and use the setSessionID function to set the session id. When compile make sure add jzHttpSrv.jar to classpath.

How to set auto servlet reload on or off?

Auto servlet reload is by default on. With auto servlet reload on, the server automatically reload updated servlet, war or jsp files when needed without your attension. It is ideal in development mode because you can fix a bug in your servlet and recompile, or for war recompile and jar it, then just use the browser the connect the it as if nothing happened, the server will automatically load the new one.
However, the auto reload make the server run slow, espically for servlets, it is very slow. To turn it off, connect to http://localhost/srvConfig (you may need to specify the port if you use a non-default port). Login in with admin/admin. Click on "Edit common server properties" on top left of the screen, Set "Set Auto Servlet reload " to off and make sure click on the "Save" button.

Config Servlet Help (srcConfig)

• Common server properties Screen
  • Set Auto Servlet reload This setting decides if .war, servlet and .jsp files should be automatically reloaded if source changed. Turn it on in development mode is a very good idea since you don't need to restart the server every time you modified your servlet, war or jsp. Turn it off can make the server a little faster.
  • Set dir processing mode The three modes are:
    • Off. Never list the content of a directory.
    • Process if no default file found. Only show the content of the directory if no welcome file is found in the directory.
    • Always list the content of the directory no matter the condition.
  • Set Error Report Servlet class Set the servlet for error processing. Please see Customizable error page
  • Set Dir Processing Servlet Class Set the servlet for directory listing. This allows you to do customized directory listing instead of the one provided by the server. The path will be given in pathinfo.
  • Set Maxium allowable threadsMaxium number of threads it will keep for future use.
  • Set Initial threadsThreads that are useable from the start.
  • Set Maxium cache size in bytes Set the maxium cachable page buffer in bytes. Cached files will be stored in memory so next they got requested by user they don't need to be fetched form disk.
  • Set Cache Reorg time Time in seconds how long the caches need to be looked into (unload some not used files to make cache more effecient).
  • Reload classpath (this is on top of the screen) Reload all the classpath (the main propose is to reload the *.jar files in WEB-INF/lib directory, because there is no other way to know new jar files are dropped there). Use this option if you dropped new jar files to the WEB-INF/lib directory.
  • Unload all servlets (this is on top of the screen) Unload all the servlets.
  • Debug Mode Turn on debug mode to see debug messages.
  • User DataBase class Specify the name of the class the server will use to load and identify user information. The default class will load config/users.properties file. If you have a lot of users, it is best to implement your own class and use a database instead.
    You own class must implement the com.BajieSoft.HttpSrv.srvDB.IServerUserDB interface. Make sure your class is in the classpath and use the config Servlet to set the user database class to your class. This url shows a sample source sample source for user Database and here is the ServerUser Interface for storing a user and IServerUserDB interface for server user database
    ServerUser, the interface for the object that needs to be returned to the server. ServerUserImpl.java, a implemention of ServerUser.
  • The mode Extract war files is no longer supported.
  • Set perl interpreter location Set where perl interpreter is. You need to set it before can use cgi scriptes.
  • Use existing jsp compiled classes on restart Leave it on (reuse class). This way after server is restarted, it will not recompile the jsp files if it is already compiled.
  • Set HTTP Request Doc rootSet the root directory where html files will be served. Default is htdocs. Can be a absolute path or relative to where the server is installed.
  • JSP compile string The string to compile .java files generated from .jsp files. If javac is not in the path, you need to specify the full path to javac.
  • JSP temp dir Temp dir to put .java files generated by .jsp. This is also the directory where the compiled .class files will be stored.
  • Set Servlet LoggerSet the class name used for logging servlet logs.
  
  

  ---

  
  
• Edit Webapp Config button
  • Set Server Class Path Set the classpath where beans and classes should be loaded. The style is just like the CLASSPATH for ordinary java classes (can be jars, pathes and seperated by : on unix or ; on windows. Note that even though htdocs/WEB-INF/lib directory is a special case, even if it is not in classpath, all *.jar file in that directory will be loaded as if they are in classpath.
  
  

  ---

  
  
• Edit Virtual Path Section (located with common server properties)
  Virtual path maps url patern to a directory on the file system.
  • URL Mapping. The url patern. Note: if url is of form /path/, /path will not mapp to virtual path. But if url is of form /path, then both /path and /path/ will be mapped. And url is always starts with /.
  • Path. Path is the directory on file system. It could be in any format. If it is relative, then it is relative to the location of jzHttpSrv.jar.
  
  

  ---

  
  
  

  ---

  
  
• Edit CGI mappings (located with common server properties)
  CGI mapping maps a url to the cgi directory.
  • CGI Mapping. The url patern. every thing after the pattern will be passed to perl handler (usually perl.exe).
  • Path. Path is the directory on file system. It could be in any format. If it is relative, then it is relative to the location of jzHttpSrv.jar (example, cgi/bin directory).
  
  

  ---

  
  
• Initial Context Params (located with common server properties)
  Initial Context Params is set so servlets can get it by ServletContext.getInitParameter().
  
  

  ---

  
  
• Edit Servlets Screen
  • Add New Servlet Alias Add a new servlet alias.
  • Show&Add Servlet alias This is the prefered way to add servlets since the computer will ensure the classname and path are correct, and you will have a chance to decide which servlet you want given a alias to and change the alias name before submit. It will only add servlets that has not been given a alias.
  • Add all servlets Same as above except that it will make all check boxes selected.
  • DeleteDelete the alias
  • EditEdit the alias settings and add back. If the alias name is changed, a new alias is created.
  
  

  ---

  
  
• Add New Servlets Screen
  It is best to use 'Auto add all servlets' to add new servlets, unless you want to add a jsp servlet. The following method is for manual add servlet. Don't put in both class name and jsp file name.
  After add the new servlet, make sure to use Edit Servlet Mapping button, located on top right of the screen to map a url to the servelt so it can be used.
  • Servlet Alias Name Name of the alias. It should not contain any space, '?', ':', '\' or '/' chars.
  • Servlet Class Name The Full Name of the servlet class.
  • Jsp File Name name of the jsp file that is used as a servlet. The name shoulbe be the same as request from browser, without the http://hostname.
    Example, if the jsp is accessable via http://host/jsp/test.jsp, the jsp name should be /jsp/test.jsp
  
  

  ---

  
  
• Error Code Mapping
  • enter integer code , currently the code supported are:
    403 -- Forbidden, user try to access below the root (../../request) or with bad chars
    404 -- File not found
    500 -- Internal server error
  
  

  ---

  
  
• Edit Servlet Mapping
  Edit servlet mapping allows you to add or delete url->servlet alias mappings.
  • URL Mapping. The url that is mapped to servlet. If the url ends with a /, then The server will not find the servlet if you specifi a url without the trailing '/'. But if the url doesn't end with a '/', both 'url' or 'url/' will be mapped to the servelt.
  • All aliased servlet will appear in a select box for you to select.
  
  

  ---

  
  
• Extension mappings
  Extension mapping is to let the server know if you wish to use a servlet to treate a special file. One example will be map *.jsp to JspServlet.
  
  

  ---

  
  
• Welcome File List
  Welcome files are a list of files server need to search for if a user requested a directory from the web browser. The server will try to find if any of the files in the welcome file exists before decide if it need to list the current directory. One example will be request on http://localhost/ returns http://localhost/index.html if index.html is in the welcome file list.
  Set by click on Edit WebApp Config button.
  
  

  ---

  
  
• Set Session Timeout time Set the session timeout in seconds.
  Session timeout can be set by click on Edit WebApp Config button.
  
  

  ---

  
  
• Server Properties
  • Clear all sessions Clear all the sessions .
  • Reload all wars Reload all the .war files. Use this button if you added new .war files in the wars/ directory, or removed .war files from that directory.
  
  

  ---

  
  
• Server List
  You can see the server list by click on the 'Show & Edit servers' link.
  This will show you all the servers running. If you didn't start any server, there will be a default web server on port 80. Click on the 'Edit server' button will let you edit all the server properties include Servlets, mime types and etc.
  
  

  ---

  
  
• Start a new server
  • The port the server will be on The port the server is running on. For http, the default is 80 and for https, the default is 443. If you start a http server on port 85, then use http://localhost:85/ to access it.
  • give a server name Optional. Can be any name you want.
  • Check this box if it is ssl server Click on the box if the server is a https server ( uses securities socket layer, used by most commerical servers). Make sure sun's jsse jars are in the class path. For detailed instructions, please see SSL setup.
  • The ip address of the serverThe server will detect all the ip addresses available on the local machine, you just need to select one of them for the server to bind on. If you don't care, just select "All Local addresses" and you can access the server via all the ip addresses the machine got.
  • SSL cert file name This is for ssl only. You only need to do it if you want to start ssl and have your own cert file. If you want to start SSL but don't have your own cert file, you can use the default one come with the server. The default one is provided with sun's jsse package, so if you connect to the server with a browser, it will warning that the cert doesn't match.
  • SSL cert password The password for the cert file. Again leave it as is if you don't have your own cert file. If you want your won cert file, you need to generate one with jdk1.3's key tool and apply for a cert from versign or other cert providers.
  
  

  ---

  
  
• Use database to provide user login info
  Version 0.95zun provide a build in class to provide server buildin user login feature. To use this feature:
  • change config/jzHttpSrv.properties line
    USERDATABASECLASS=com.BajieSoft.HttpSrv.srvDB.simpleUserDB
    to
    USERDATABASECLASS=com.BajieSoft.HttpSrv.srvDB.simpleDbUserDB
    
  • Modify config/jndiConfig.xml to set jdbc class and connection string for your database.
  • download jdbc2_0-stdext.jar if you don't have jdk1.4. Put it in lib/ directory. This file provides DataSource classes.
  • setup your database so it has one database, 'httpusers'. Setup 2 tables, 'users' and 'roles' table users needs to have 2 fields, 'username' 'password' table roles needs to have 2 fields, 'username' 'role' auth.sql is for setup a simple database for SQL servers (MySQL, MS SQL, Oracle etc).
    users.mdb is a simpel access file, you can use it through JDBC-ODBC (not recommanded, access is slow when there are more then 3 concurrent users).
  • If needed, you can write your own implemention, see here for source code.

How to enable chinese/japanese char input on English version of windows?
The input will be correct on Chinese/Japanese version of windows because the pre-set locale. However, for english version of windows, the double byte char will be read in as single byte chars.
To avoid this, you can set the UseEncoding to your encoding, such as GB2312 for chinese and Shift_JIS for japanese. You can either put the line UseEncoding=encoding in to jzHttpSrv.properties yourself, or you can change it in real time (and let server verify the encoding exists) via config servlet. Just logon to http://localhost/srvConfig, click on 'Edit Common Properties' link on top left, then set the 'Default Encoding' to your encoding and make sure click save.
This will let the next request parameter to be parsed as the encoding you set.