Chapter 2　Config kangaroo-egg

Kangaroo-egg server has a “conf” folder under it installed folder.

Under “conf” folder there has a “webconfig.xml” file and a “webfile” folder, first we look “webconfig.xml”, it’s a standard XML file, you can set kangaroo-egg use this file, but must reboot kangaroo-egg after change configuration.

webconfig.xml top element is “<kangaroo-egg>”, it’s include these elements:

Picture 2-0-1

2.1　systemSet element

You can modify “systemSet” element to change kangaroo-egg server setting.

Picture 2-1-1

1. systemPsw

You can set server password use this element. Some operate need use server password, for example the operate at 10.6 need use server password. He password default set to 123456, so change it at first please.

2. regionSet

You can set server region use this element. Server information, language, data encoding will different by your set. Now support “cn” and “us” region.

3. urlEnc

Http request URL can attach datum, but no ascii data will encode, so server need decode those datum.

For example Chinese “小明” encode with UTF-8 character set will change to “%E5%B0%8F%E6%98%8E”. But it encode with GBK character set will change to “%D0%A1%C3%F7”.

  So not encode URL is http://127.0.0.1/run.dqm?name=小明

  Encode with UTF-8 URL is http://127.0.0.1/run.dqm?name=%E5%B0%8F%E6%98%8E

Encode with GBK URL is http://127.0.0.1/run.dqm?name=%D0%A1%C3%F7

So server need decode datum by different character set.

“%D0%A1%C3%F7” can decode to “小明” by use GBK character set. It can’t decode to “小明” by use UTF character set.
  So you can set decode character use this element. You can use “default” value to set it, that means if you “regionSet” set to “cn” then this element will set to “GBK” automatically, and if you “regionSet” set to “us” then this element will set to “US-ASCII” automatically. Of course you can set this element use explicit value also, example GBK, BIG5…
<urlEnc>BIG5</urlEnc>

4. dataEnc

Chinese browser will encode post datum use GBK character default, Japanese browser will encode post datum use Shift_JIS character default. So you can set decode character use this element. You can use “default” value to set it, that means if you “regionSet” set to “cn” then this element will set to “GBK” automatically, and if you “regionSet” set to “us” then this element will set to “US-ASCII” automatically. Of course you can set this element use explicit value also, example GBK, BIG5…

<dataEnc>BIG5</dataEnc>

5. bufferSize

You can set server buffer size use this element. For example if this element’s value set to 16, that means server buffer size is 16K. We set this element’s value to 16 default.

6. threadPriority

You can set server thread priority use this element. Highest level is 10, lowest level is 1. We set this element’s value to 5. Under some OS this is a uselessel element maybe.

7. clearTimeoutSession

Session will be expired, so need clear expired sessions to release memory periodically. (About session refer to Chapter 8 please.) You can set how long to clear time out sessions. We set this element’s value to 60 default, that means server will clear time out sessions every 60 minutes.

  If this value set too big then many expired sessions can’t be cleared in time, so memory maybe will overflow.

  If this value set too small then system will continually clear expired sessions, so server will become busy.

8. clearDhtmlInstance

DQM container like servlet container, first server translate from dynamic web page into java file, and compile java file into class file. If need execute class file, server will initialize class file to instance first, and save instance into DQM container. If another want to visit this page then server can get instance from DQM container direct, and execute instance.

The benefit of to do this is not initialize class when user visit it every time. This flow can improve server performance. But there are defects in this flow. If many instane save into DQM container then memory will overflow maybe. Other defect is if dynamic web page was deleted, but DQM container can’t delete already exist instance automatically. So you can use this element clear all instances of DQM container periodically.

If “enable” attribute of this element set be “true”, then this function enabled, else this fuction disable. You can define how many days to clear instances use “clearTime” attribute of this element. Default it set to “7”, that means server will clear all instances every 7 days. The “clearTime” attribute can be avail when “enable” set to “true” only.

9. saveLogs

You can set visit logs save to file use this element. The element have 3 attributes:

1.       The “enable” attribute’s value equal “true” then visit logs will save to file, else not save.

2.       Server will save logs to buffer first, when buffer full then save all logs that in buffer to file. The “bufSize” attributes can set buffer size, if you set it to “256” that means buffer size is 256K.

3.       You can set logs file maximum size use “logFileMaxSize” attributes. If you set it to “204800” that means logs file maximum size is 204800K (200M).

The “logFileMaxSize” attribute can be avail when “enable” attribute set to “true” only. If disable “saveLogs” function then visit logs will not save to buffer too. Please refer to section 10.6 to know how to view buffer logs.

Kangaroo-egg server use CLF format to record visit log. A entry of log file represent a HTTP request. Some request informations contained in every entry, use “|” flag to split it, it represent:

1.       The thread of process current HTTP request.

2.       Start time of process current HTTP request.

3.       The remote IP address of current HTTP request.

4.       The request method, request URI and request protocol of current HTTP request.

5.       Server response code of current HTTP request, for example 200, 503.

6.       Server response content length, if it equals -1 then mean content length unknown., for example if transmitted content use chunked code then can’t know content length.

7.       End time of process current HTTP request.

8.       If current web enable password protect then visit some page need enter username and password, if username ok then server will record it at current flag. About password protect please refer to section 2.3.

2.2　connectors element

You can modify “connectors” element to change kangaroo-egg server connection pool.

Picture 2-2-1

1. coreConnectionNumber

You can set server core connection pool size use this element. Connection will consume system memory. Core connection can’t died never.

2. maxConnectionNumber

You can set server maximum connection pool size use this element. This value must larger than or equel coreConnectionNumber’s value. The number of coreConnectionNumber larger than maxConnectionNumber are non-coreConnectionNumber connection pool size. See picture 2-2-1 that coreConnectionNumber’s value is “40” and maxConnectionNumber’s value is “200”, so non-coreConnectionNumber’s value is 160. But what is non-core ConnectionNumber connection pool? Non-core connection will died automatically when it’s no activate and exceeded time limit. This element’s “timeOut” attribute can set non-core connection time out value. For example in picture 2-2-1 that “timeOut” attribute is “20”, that means non-core connection will died automatically when it’s no activate and exceeded 20 minutes.

Server will use core connection first, if all of core connection used up then will use non-core connection. If non-core connection used up too then response 503 error.

If coreConnectionNumber’s value equals maxonnectionNumber’s value, then non-core connection pool can’t be used. In this status all of the request will use core connection, if core connection used up then response 503 error.

No-core connection can be of use to the time of many requests, it’s can offer more connectons for this status. Sever will automatically release time out non-core conntion when accept less requests.

Please notice if you set many connections then need many memory. You must assign more memory to kangaroo-egg server. For example I set “maxConnectionNumber” to 800, so I want to assign 512M memory to kangaroo-egg server, What can I do? Very easy modify run.bat :

Picture 2-2-2

run.sh：

Picture 2-2-3

3. maxServerUnavailableNumber

You can set server unavailable connection pool size use this element. If all of the connections used up then server will use unavailable connection response 503. If unavailable connection used up then closed client’s request. Suggest set this element to a small value.

4. maxPersistentConnectionsNumber

　　You can set persistent connections maximum number use this element. For example if this value is ten that means client can connect ten number in a same connection. If set this element to “1” that means close function of persistent connections. About persistent connections please refer to rfc2616 document.

5. connectionTimeout

You can set time out of persistent connections use this element. Sets the length of time in seconds before the server disconnects an inactive user. This ensures that all connections are closed if the HTTP protocol fails to close a connection. For example in picture 2-2-1 that “connectionTimeout” element’s value is “50”, that means alive persistent connection will closed automatically when it’s no activate and exceeded 50 seconds.

6. HTTP

You can enable HTTP service use this element. The element have 3 attributes:

1．  The “enable” attribute’s value equal “true” then enable HTTP service, else is disable HTTP service.

2．  You can set HTTP listened port use “port” attribute. We default set it to “8080”.

7. HTTPS

You can enable HTTP service use this element. The element have 7 attributes:

1.       The “enable” attribute’s value equal “true” then enable HTTPS service, else is disable HTTPS service.

2.       You can set HTTPS listened port use “port” attribute. We default set it to “8443”.

3.       You can set certificate file of HTTPS use “keystoreFile” attribute. Please refer to addendum 6 to know how to create certificate file.

4.       You can set type of certificate file use “keystoreType” attribute. If use JDK keytool to The certificate file that use JDK keytool created is “jks” type.

5.       You can set certificate file‘s save password use “keystorePass” attribute.

6.       You can set certificate file‘s password use “keyPass” attribute.

7.       You can set server validate client certificate file use “needClientAuth” attribute. If this attribute set be “true”, then need validate client certificate file, else not need validate.

All attributes can be avail when “enable” set to “true” only.

2.3　mainHost element

You can modify “mainHost” element to config kangaroo-egg webserver main host.

Picture 2-3-1

1. webPath

You can set the location of main host home directory use this element.

2. defaultHttpFile

You can set main host default document use this element.

3. dhtmlExtName

You can set main host dynamic web page's extended name use this element. The kangaroo-egg webserver can define the dynamic web page's extended name in yourself. We default set it to “dqm”, so the file that extended name is “dqm” can be executed.

4. maxPostLen

Use this element you can set the datum size of main host allowed accept. The dynamic web page can accept data from client, for instance browser uplod file. Kangaroo-egg server will save accept data to temporary memory, so if client uploaded larger datum server maybe overflow. This element can solve this problem. For example if this element’s value set to 16, that means server only can accept 16K upload datum, if upload datum size over 16K then server will prompt error information or close connection.

5. session

You can config main host session use this element. About session refer to Chapter 8 please. This element has two attributes.

1.       You can set the length of session timeout use “timeOut” attribute. For example set this attribute to “20” that mean session will overdue automatically when it’s no activate and exceeded 20 minutes.

2.       The session must need memory, so if server maintain large number sessions at same time then it maybe overflow memory. You can set session maximal number use “allowedMaxNumber” attribute. Sever will check current number of session before create a new session, if it exceeded session maximal numbe of your set then server will clear all existed sessions before create a new session. If this attribute set a negative then server session unlimited.

6. listFile

Use this element you can set allow the user to see a hypertext listing of the files and subdirectories in this host directory. If this element set be “true”, then allow list files, else not allow.

7. needPassword

You can enable your Web server's Basic authentication use this element. If this element set be “true” that means enable web server’s authentication, else disable it. The browser will prompt the user input user name and the password when user visit host that enabled authenticate (to see picture 2-3-2).

Picture 2-3-2

This element has 5 sub-elements:

1.       You can set web server’s authentication application use “className” element. See picture 2-3-1 that we set this element to “default”, it’s mean use kangaroo-egg’s default authentication application. We will introduce how to use custom authentication application later.

2.       The “parameter” element has a “comment” attribute, it function is to remark, for example if you have many parameters then you can use this attribute to remark them. The “comment” attribute is not must need. See picture 2-3-1 the first “parameter” element’s “comment” attribute value is “title”. You maybe already guess the function of this element, it can set dialog box title (to see picture 2-3-2 red mark ).

3.       See picture 2-3-1 the next “parameter” element’s “comment” attribute value is “userName”. It’s function is set authentication application’s username.

4.       See picture 2-3-1 the next “parameter” element’s “comment” attribute value is “userName”. It’s function is set authentication application’s username.

5.       See picture 2-3-1 the next “parameter” element’s “comment” attribute value is “securityPath”. It’s function is set authentication area, for example if you want to protect all web site you can set this element to “/”, but if you want to protect resource that under “security” folder so you must set the element to “/security/”.

Use the default authentication application has a defect, that everyone can use a pair of username/password only. So you can use custom authentication application, for example use database to validate identity(Inquires the user name and the password from the database).

Kangaroo-egg has a interface that name is “com.kangaroo_egg.webserver.CheckServerPSW”, custom authentication class must need implement it. This interface is very simpleness, has two methods:

First method:

public String getPswTitle()

Kangaroo-egg server can get dialog box title (to see picture 2-3-2 red mark ) from this method.

Second method:

public boolean checkPSW(String username, String password, String requestPath, String queryData)

Kangaroo-egg server use this method to validate identity. The parameter’s value of “username” and “password” is user inputed when jump dialog box(to see picture 2-3-2). The “requestPath” parameter’s value is path of user visited, but notice this path not encoded (please refer to section 2.1). The “queryData” parameter’s value is characters of URL attached, if user request URL not attach any characters then is’t value is null. And this method will return a boolean value, if it return true then successfully validate identity. If it return false then unsuccessfully validate identity.

Custom authentication application must implement this interface and it’s two methods, then change “className” parameter’s value to your authentication application’s class name(must need full class name). Of course, custom authentication application’s class maybe has constructor with parameters, so you can use “parameter” element to set constructor’s parameters (if constructor not have parameters then user can not set “parameter” element). For example a custom authentication application class has two String type parameters, so you can define two “parameter” elements. The “parameter” element’s value is constructor’s parameter. The “parameter” element has a “comment” attribute, it function is to remark, for example if you have many parameters then you can use this attribute to remark them.

Ok, now let us research default authentication application, it’s class full name is “com.kangaroo_egg.webserver.DefaultCheckServerPSW”, so server has same function when “className” parameter’s value set by “default” or “com.kangaroo_egg.webserver.DefaultCheckServerPSW”. Because default class name too long, so server add this “default” value.

Now we see default authentication application source code, first this class implement “com.kangaroo_egg.webserver. CheckServerPSW” interface.

public class DefaultCheckServerPSW implements CheckServerPSW

Secondly this class constructor has four string type parameters, so need four “parameter” elements. (Four “parameter” elements see picture 2-3-1 please)

This class constructor has four string type parameters, the “ipswtitle” parameter’s value is dialog box title (to see picture 2-3-2 red mark ) that user use “parameter” element defined. (Source code line: 3)

The “iusername” parameter’s value is username that user use “parameter” element defined. (Source code line: 4)

The “ipassword” parameter’s value is password that user use “parameter” element defined. (Source code line: 5)

The “irequestPath” parameter’s value is authentication area that user use “parameter” element defined. (Source code line: 6)

Next we look default authentication application how to implement “getPswTitle()” method.

It’s return “pswtitle” variable’s value (source code line: 2). The “pswtitle” variable is initialized by constructor.

Last we look default authentication application how to implement “checkPSW” method.

First program check current visit area whether does need to protect, if does not need to protect then directly returns “true”, it’s express passed. (Source code line: 2 to 4)

If visits area needs to protected, then program will compare username and password that user inputed(iusername, ipassword) with the validated username and password which assigns (username, password). (Source code line: 5 to 7). If result identically then return “true” express passed confirmation, otherwise returns “false” express confirmation defeat. (Source code line: 8)

This default authentication application has not certainly used “iqueryData” parameter, of course you can use this parameter in your authentication application.

Above may see the custom authentication application also is so, you must element constructor, “getPswTitle” and “checkPSW” method.

8. needRedirect

  You can enable URL inexplicit redirect function use this element, but only can redirect to same host. For example, if a document name has been changed, but users still want to use the old address to access it, it can be to use this feature (let old address to redirect new address). And if website has a cumbersome URL then we can use this function to redirect it to a short URL.

  If this element set be “true” that means enable redirect, else disable it. Next we introduce elements and attributes of “needRedirect”:

1. You can set redirect application use “className” element (must need full class name). We will introduce how to code redirect application later.
2. Of course, redirect application’s class maybe has constructor with parameters, so you can use “parameter” element to set constructor’s parameters. For example a user application class has two String type parameters, so you can define two “parameter” elements. The “parameter” element’s value is constructor’s parameter. But if constructor not have parameters then user can not set “parameter” element
3. The “parameter” element has a “comment” attribute, it function is to remark, for example if you have many parameters then you can use this attribute to remark them.

  But how to code redirect application? Kangaroo-egg has a interface that name is “com.kangaroo_egg.webserver.RequestRedirect”, redirect class must need implement it. This interface is very simpleness, only has one method:

  public URL redirectURL(URL oriUrl)

  We can use this method to redirect URL of user request, the “oriUrl” is user original request URL, the URL of this method returned is redirect URL, but if this method returns null then 400 errors will be reported.

  Next we give an example, if we maintaining our website now, we hope that user visit any web address always see maintenance information. We can use redirect function to do it. First we create a static web page “maintenance.htm”, its source code:

  Next we create redirect application, it’s name is “example.MaintenanceRedirect”, it’s source code:

  Next we config the “needRedirect” element:

     <needRedirect enable="true">

       <className>example.MaintenanceRedirect</className>

       <parameter comment="redirect url">/maintenance.htm</parameter>

     </needRedirect>

  We enable redirect function and set “MaintenanceRedirect” to redirect application, and this redirect application need a String parameter (source code line: 11 to 13), so we use “parameter” element to provide it. Now user visit any web address always will redirect to maintenance web page (source code line: 17), this maintenance web page defined by “parameter” element. But system maybe will throw exception when we construct URL instance, so if system throw exception then we return original request URL (source code line: 18 to 20).

  public URL redirectURL(URL oriUrl)

  This method parameter is Java URL class, so we need to introduce it. Usually URL have 5 parts: protocol, host, port, path and query.

  For example a URL: http://www.kangaroo-egg.com:80/a.dqm?key=value

  It’s protocol part is: http

  It’s host part is: www.kangaroo-egg.com

  It’s port part is: 80

  It’s path part is: /a.dqm

  It’s query part is: key=value

  Please notice use this function only can redirect to same host, so system will ignore redirect URL’s protocol, host and port. System actually use redirect URL’s path and query. For example, we can revise “example.MaintenanceRedirect” source code as below:

  The final result has not change, system will not redirect to “sun” website’s maintenance.htm, it still will redirect to current host’s maintenance.htm.

8. needCompress

You can enable compress web content use this element. Server can compress dynamic web content before it output, like this can improve performance of network bandwidth (but need use cpu resource).

Kangaroo-egg support the most mainstreams compression format (for example gzip), can fit  the most browser. If client can’t support receive compressed datum then kangaroo-egg will automatically disable compress function. If this value set be “true” then enable the function of compress, else disable it.

9. autoCompile

You can enable automatically compile function use this element. We alread introduced that first server translate from dynamic web page into java file, next compile java file into class file. Only class file can be executed. But sometimes need re-compile, like dynamic web page modified. It’s reasonable in the development time, because dynamic web page will often modified. But dynamic web page nearly dosen’t modified in productive phase, so not need to consume the resources that monitor dynamic web page is changed.

If value of this element set be “true” then server will automatically compile dynamic web page if it modified. Other value then not automatically compile. (About automatically compile flow please refer to section F1.3)

10. userApps

You can setup own java program use this element, because this element has more content, so use section 2.4 to introduce this element. This element is not must need.

2.4　userApps element

You can modify “userApps” element to add user Java applications. For example you can add database connection pool application use this element. What are user Java applications? Very easy user Java applications will initialized when server starting.

The “userApps” element can contain zero or more “userApp” elements. A “userApp” element represent a user application. Ok let me introduce all elements and attributes of “userApp”.

1.       The “userApp” element has two attributes, “enable” and “number”. The “enable” attribute’s value equal “true” then enable current user application, else is disable it. The “number” attribute is not must need, it function is to remark, for example if you have many user applications then you can use this attribute to remark them.

2.       You can set user application’s class use “className” element. This element must need full class name, server will initialize this class when server started.

3.       Of course, user application’s class maybe has constructor with parameters, so you can use “parameter” element to set constructor’s parameters. For example a user application class has two String type parameters, so you can define two “parameter” elements. The “parameter” element’s value is constructor’s parameter. But if constructor not have parameters then user can not set “parameter” element

4.       The “parameter” element has a “comment” attribute, it function is to remark, for example if you have many parameters then you can use this attribute to remark them.

Ok now give a demo. “example.StartupTime” is a class, it can print current time when initialized, source code is below this.

So you can config userApps element to:

<userApps>

<userApp enable="true" number="1">

          <className>example.StartupTime</className>

          <parameter comment="prompt_info">Startup time=</parameter>

</userApp>

</userApps>

The “example.StartupTime” will be initialized when server started. Look the source code, this class has two constructors, a constructor need a String type parameter(soure code line:2-4). Ok we add a “parameter” element, it’s value is “Startup time=”, so when start server then console will print “Startup time=Fri Jan 06 16:10:04 GMT+08:00 2006”, but notice that information of “Startup time=” is our input via “parameter” element. And the time “Fri Jan 06 16:10:04 GMT+08:00 2006” will change to your current time.

But this class has another constructor that without any parameters(soure code line:6-8), so how to use this constructor? Very easy not add “parameter” element at webconfig.xml, like below:

<userApps>

<userApp enable="true" number="1">

          <className>example.StartupTime</className>

</userApp>

</userApps>

The console will print “Fri Jan 06 16:10:04 GMT+08:00 2006” when server started. You can see that printed current time only.

Next we add second user application, it will regular print current time. It’s obvious what the class need use thread. The class name is “example.PrintTime”, source code is below this.

So you need add a new “userApp” element in “userApps”:

<userApps>

<userApp enable="true" number="1">

          <className>example.StartupTime</className>

          <parameter comment="prompt_info">Startup time=</parameter>

</userApp>

<userApp enable="true" number="2">

          <className>example. PrintTime</className>

          <parameter comment="sleepTime(minute)">10</parameter>

</userApp>

</userApps>

Application use a new thread to regular print current time(to see source code line: 5), at soure code line 8 to 18 is thread main body. The constructor’s parameter can decide how long to print current time(to see source code line: 4 and 11). So like above config that user application will print current every 10 minutes.

2.5　vHost element

You can modify “vHost” element to config kangaroo-egg webserver virtual host. You can add more virtual host, only turns to increase “vHost” element. The “number” attribute of “vHost” element is not must need, it function is to remark number of current virtual host. Of course, you can change it to better understanding of the content, but still recommends using numeral. If you not config exactly this element then server will prompt number of that virtual host has error. (most of the top is No.1, from top to bottom, the increase).

The content of “vHost” element very like the content of “mainHost” element:

Picture 2-5-1

Seen from picture 2-5-1 that we distribute two virtual hosts on kangaroo-egg server, the second virtual host’s elements same with first, only different point is element’s value. We use second virtual host as example, please see picture 2-5-2. Please noctice that first virtual host not config “userApps” and “needRedirect” element, this means that no user application and disable redirect function.

Picture 2-5-2

1. hostName

The “mainHost” element not include this sub-element. You can set virtual host’s name(domain name, host head) use this element. Of course, a virtual server can set multi-hostname(use “|” flag to split values), see picture 2-5-2 that the second virtual host set two host name: “www.kangaroo-egg.com” and “kangaroo-egg.com”.

For example, if our server IP address is “210.52.216.34”. Meanwhile “www.kangaroo-egg.com” and “kangaroo-egg.com” two domain names are at this IP address. If user visit those two domain name then will see No.2 virtual host’s resource. See picture 2-5-1 that No.1 virtual host name is “download.kangaroo-egg.com”, and this domain name is at our server IP address, so user visit this domain name will see No.1 virtual host’s resource. So another question that user directly visit IP address will see main host’s resource. Why? Because if host name(domain name) of user visited was not defined in all “vHost” elements then server will automatically reset to main host. This is the reason that why “mainHost” element not include “hostName” sub-element.

2. webPath

You can set the location of virtual host home directory use this element.

3. defaultHttpFile

You can set main host default document use this element.

4. dhtmlExtName

You can set main host dynamic web page's extended name use this element. The function of this element please refer to section 2.3.

5. maxPostLen

Use this element you can set the datum size of main host allowed accept. The function of this element please refer to section 2.3.

6. session

You can config main host session use this element. The function of this element please refer to section 2.3.

7. listFile

Use this element you can set allow the user to see a hypertext listing of the files and subdirectories in this host directory. The function of this element please refer to section 2.3.

8. needPassword

You can enable your Web server's Basic authentication use this element. The function of this element please refer to section 2.3.

9. needRedirect

You can enable redirect function use this element. The function of this element please refer to section 2.3.

10. needCompress

You can enable compress web content use this element. The function of this element please refer to section 2.3.

11. autoCompile

You can enable automatically compile function use this element. The function of this element please refer to section 2.3.

12. userApps

You can setup own java program use this element. The function of this element please refer to section 2.3.

2.6　webfile folder

That has a webfile folder under the conf folder, all HTTP message files are saved at this filder. For example, a user visited a inexistent document then kangaroo-egg will output message file of code is 404 from this directory. You can customize the user message file to replace the default file. But notice message file must follow this norms: file extended name must be “html”, file main name must use underscore flag and region name, for example region of United States then message main file name is end by “_us”.