Chapter 10　Built-in object : command

This chapter is going to introduce last built-in object “command”, other built-in objects are directed at the web procedure, but this chapter must introduce the object is directed at server's.

10.1　Introduce command object

The “command” is a special built-in object, only DQM container has this object. User can get or change server’s current information through this object, use this object you can apply new value to server, but not to need restart server.

10.2　Use command to process session and application

1.       public int getSessionCount()

Get the the quantity of current host’s sessions, including not expired and already expired(but had not cleared, refer to section 8.4) sessions.

Return: the current session quantity

2.       public void clearAllSession()

Delete current host’s all sessions. All sessions will be cleared from memory, including not expired and already expired(but had not cleared) sessions.

For example, the dqm file “commandSession.dqm”, source code:

When visiting this dqm file, it will show current host’s sessions quantity (source code line 4), next we clear current host’s sessions (source code line 5 to 10), then you can try visit this dqm file again, you will find current host only has one session (That only session is you are using now).

3.       public int getApplicationCount()

Return: how many items in current host’s application.

4.       public void clearAllApplication()

Removes all items from current host’s application.

For example:

The dqm file “commandApplication1.dqm” can add five items into current host’s application, source code:

The dqm file “commandApplication2.dqm” can get the quantity of current application’s items and clear all application’s items, source code:

First visit “commandApplication1.dqm” for add 5 items into current application (commandApplication1.dqm source code line 3 to 5). Next visit “commandApplication2.dqm” you will see current application has 5 items (if there are other programs also add item into application, then the quantity of application’s items will bigger than 5, commandApplication2.dqm source code line 4). You can clear current application’s items (commandApplication2.dqm source code line 5 to 10), then you can try visit this dqm file again, you will find current application has zero item.

5.       public String getDhtmlExtName()

Returns: dynamic web page's extended name of current host. If you set dynamic web page's extended name to “dqm” then will return “.dqm”, how to set dynamic web page's extended name please refer to section 2.3 and 2.5.

10.3　Use command to process Dqm Instance Buffer Pool

DQM container has a pool to store instance of dqm file (please refer to addendum 1), this section we will introduce use command how to process “dqm instance buffer pool”.

1.       public int getDhtmlInstanceCount()

Return: the quantity of current dqm instance buffer pool’s instances

2.       public void clearAllDhtmlInstance()

Remove all instances from current “dqm instance buffer pool”.

3.       public boolean clearDhtmlInstance(String http_file)

Remove the specified dqm file instance from current “dqm instance buffer pool” if it is present.

Parameters: http_file - dqm file instance to be removed from current “dqm instance buffer pool”, if present. For instance, if need to remove instance of “http://youname/chat/main.dqm”, then “http_file” value should be: “/chat/main.dqm”.

Returns: true if current “dqm instance buffer pool” contained the specified dqm file instance

We have to give an example, “testDhtmlInstancePool.dqm” can prove that dqm file instance is stored in the “dqm instance buffer pool”, its source code:

If using statement <%!%> that means all declaration will become class member. Here we declare a private static class member variable: “ct”, it’s type is integer. This variable uses in recording the times of visits this dqm file. But if re-new this dqm file then “ct” will become zero. In fact when you visit this dqm file you will see how many times this dqm file by visited. This proves that the dqm file only initialize single instance, and put the instance into “dqm instance buffer pool”.

The dqm file “clearDhtmlInstance.dqm” can check and delete dqm file instance from current “dqm instance buffer pool”, it’s source code:

This program’s interface:

Picture 10-3-1

This program has three functions, user can use three buttons to choose the three functions, but must first input the correct operation password. In here password is “123456”, it’s defined by “password” variable (source code line 3), if you want to change password please change this variable’s value.

We introduce the first function (source code line: 29 to 32), it can get the quantity of current dqm instance buffer pool's instances, this function was used “getDhtmlInstanceCount()” method. If restart the server to ensure that “dqm instance buffer pool” does not contain any instanes, then visit “testDhtmlInstancePool.dqm” file, next visit “clearDhtmlInstance.dqm” file and use current function to check quantity of instance, you will see current has 2 dqm instance. Why it has 2 instances? First we visited “testDhtmlInstancePool.dqm” file, so put this dqm file’s instance into the “dqm instance buffer pool”. But what is another instance? Do not forget that we get instance quantity through “clearDhtmlInstance.dqm” file, so pool has 2 instances: “testDhtmlInstancePool.dqm” and “clearDhtmlInstance.dqm”.

Ok next we introduce the second function (source code line: 34 to 38) it can remove all instances from current “dqm instance buffer pool”, this function was used “clearAllDhtmlInstance()” method. We can try to visit many dqm files, then use first function to get current instance quantity, next we use current function to remove all dqm instances, next if we use first function to get current instance quantity again, we will find current dqm instance pool only has one instance (it’s your current visiting dqm file: “clearDhtmlInstance.dqm”).

  Sometimes we just want to remove the specified dqm file instance from current “dqm instance buffer pool”, not need to remove all instances, this time we can use “clearDhtmlInstance” method. The third function can remove the specified dqm file instance (source code line: 40 to 48). We can try to visit many dqm files (include “testDhtmlInstancePool.dqm”), then use first function to get current instance quantity, next we try ro remove instance of “testDhtmlInstancePool.dqm”, only input “/testDhtmlInstancePool.dqm” into “Specified dqm file” item, because this dqm file under root folder. Ok now we use first function to get current instance quantity again, will find a instance was removed.

10.4　Use command to process Class Buffer Pool

In section 3.4 we introduced main host or virtual host has “/WEB-INF/classes” and “/WEB-INF/lib” folder, you can put jar and class files into these two folders, if the dqm file need to use the jar and class files then system will automatically load it from the two folders. In order to improve performance, class loader installed a “class buffer pool”. First class loader will check “class buffer pool” when need to load a class, if the pool alread has the class then load it from pool.  If the pool does not has the class then load it into pool, later if other dqm file need to use the same class then can load it from “class buffer pool”.

However, there is a question that “class buffer pool” can’t check whether the jar or class file was updated, Why not check, because the jar or class files usually do not update, even if the jar or class files were updated, we still can manually reload new class file to “class buffer pool” without restart server (Use the following method).

1.       public boolean clearAllLoadedClass()

Removes all classes from current “class buffer pool”.

Return: true if remove successfully, else return false.

For example, first we create a java class, it’s full name is “test.Test”, it’s source code:

Please compile above java file and put it’s class file into “/WEB-INF/classes” folder (notice the file’s package name, full class path is “/WEB-INF/classes/test/Test.class”), next create a “testClassPool.dqm”, this dqm file will use “test.Test”, source code:

Visit abovedqm file, you will find it will read information from “test.Test” class, the result is: The content of "Test" class: one。

Next we change method return value, it source code:

You can seen the value of returned was changed to “two”, and overwrite original class file after re-compile it, next visit “testClassPool.dqm” again (don’t restart server), you will find that the results still show "one". At begin of this section we already introduced, because “class buffer pool” does not detect the jar or class file has been updated, so class loader will still get old class from “class buffer pool”, and use it, therefore the results still showed "one".

So we can use “clearAllLoadedClass” method to remove all classes from current “class buffer pool”. Using this method does not need to restart the server, and “class buffer pool” not include “test.Test” class so it will reload this class again. Notice that to the "class buffer pool" no method can remove the specified class.

The dqm file “clearClassPool.dqm” can removes all classes from current “class buffer pool”, it’s source code:

This program’s interface:

Picture 10-4-1

You will find this program very like “clearDhtmlInstance.dqm”(at section 10.3), but this program only has one function: removes all classes from current “class buffer pool”. Similarly if want to execute this function you must first input the correct operation password. In here password is “123456”, it’s defined by “password” variable (source code line 3), if you want to change password please change this variable’s value.

Removes all classes from current “class buffer pool”, this function was used “clearAllLoadedClass ()” method (source code line 26).

Next use this program we can continue to the previous example, input operation password and execute function of remove classes (if execute not successful please try again). After remove all classes from current "class buffer pool" we visit “testClassPool.dqm” again, but you will find the execution result was still display “one”. Why? Old classes was alread removed from pool, but don’t forget “dqm instance buffer pool”, so we must remove instance of “testClassPool.dqm” from "dqm instance buffer pool" too (use clearDhtmlInstance.dqm at section 10.3). Now visit “testClassPool.dqm” again, the results finally display "two."

10.5　Soft restart the server

The command object has a method can soft restart kangaroo-egg server.

public void resetHost()

This methiod can restore condition that current host to server starting time condition. This method only can effect current host, equal to restart server, but not need to shutdown server. In fact this method equal to execute “clearAllApplication”, “clearAllDhtmlInstance”, “clearAllLoadedClass”, “clearAllSession” and “clearAllStaticPage” these five methods at same time. About “clearAllStaticPage” method we will introduce in section 12.2.

10.6　Log operation

At section 2.1, we introduced “saveLogs” element, you can save visit logs to file use this element. But server will save logs to buffer first, when buffer full then save all logs that in buffer to file. So below method of command object can get logs buffer’s content. Please notice that if disable “saveLogs” function then visit logs will not save to buffer too.

public String getLogBuf(String psw)

Read the log records from server log buffer,

Parameters: psw - Because the the log records is based on the whole server, so need to provide the password to get logs. About password set up please refer to “systemPsw” of section 2.1.

Returns: If provide the correct password then returns buffer’s log record, else return null.

10.7　Password protection

At section 2.3 and 2.5 we introduced “needPassword” item, use it can enable web server’s authentication, but user must input correct username and password before visit resource. But sometimes we need to get username which already logon, so Command has this method:

public String getAuthUser()

Get the username which already logon current host.

Returns: If enable web authentication and successful login then return the logon name, else return null.

Why needs to have this method? If we do not want to use dqm languages to code authentication program, then can use server authentication (refer to “needPassword” element at section 2.3 and 2.5). If use server authentication then you can use this method to get logon name, for example you can get logon name and put it into session, maybe other dqm program need to use logon name.