Chapter 4　Built-in object : out

Earlier chapters introduced that dqm technology has six build-in objects. At this chapter we will go through these built-in objects, first introduced “out” object.

The “out” object can control sent to the client content.

4.1　Methof of print and println

The “out” object has two important methods: “print” and “println”. It’s function to transmit character data to client.

1.       public void print(String content, String charsetName) throws IOException

Output character using the specified charset.

Parameters: content - character that need to output

charsetName - the name of a supported charset, for example BIG-5, UTF-8, GBK…

Throws: If happen problem when output then this method will throws IOExeption.

2.       public void print(String content) throws IOException

Output character using default charset. The default charset is set by “webconfig.xml->systemSet->dataEnc”, please refer to section 2.1.

Parameters: content - character that need to output

Throws: If happen problem when output then this method will throws IOExeption.

3.       public void print(boolean content) throws IOException

Output a value that type is Boolean.

Parameters: content – boolean type value that need to output

Throws: If happen problem when output then this method will throws IOExeption.

4.       public void print(char content) throws IOException

Output a character.

Parameters: content – a character that need to output

Throws: If happen problem when output then this method will throws IOExeption.

5.       public void print(char[] content) throws IOException

Output character array.

Parameters: content – character array that need to output

Throws: If happen problem when output then this method will throws IOExeption.

6.       public void print(double content) throws IOException

Output a value that type is double.

Parameters: content – double type value that need to output

Throws: If happen problem when output then this method will throws IOExeption.

7.       public void print(float content) throws IOException

Output a value that type is float.

Parameters: content – float type value that need to output

Throws: If happen problem when output then this method will throws IOExeption.

8.       public void print(int content) throws IOException

Output a value that type is int.

Parameters: content – int type value that need to output

Throws: If happen problem when output then this method will throws IOExeption.

9.       public void print(long content) throws IOException

Output a value that type is long.

Parameters: content – long type value that need to output

Throws: If happen problem when output then this method will throws IOExeption.

10.   public void print(Object content) throws IOException

Output a object.

Parameters: content – object that need to output

Throws: If happen problem when output then this method will throws IOExeption.

The above method has a simple syntax.

<%=content%> it’s equals <%out.print(content);%>

　And “println” method is output value and then terminate the line.

For example a dqm file: print_test.dqm, source code:

Output result:

4.2　Method of write

You can use “write” method to transmit binary data to client. For example we can use this method to output binary data(picture) of save in database.

1.       public void write(byte[] b, int off, int len) throws IOException

Writes len bytes from the specified byte array starting at offset off to this output stream(client). The general contract for write(b, off, len) is that some of the bytes in the array b are written to the output stream in order; element b[off] is the first byte written and b[off+len-1] is the last byte written by this operation.

Parameters: b - the data.

off - the start offset in the data.

len - the number of bytes to write.

Throws: If happen problem when output then this method will throws IOExeption.

2.       public void write(byte[] b) throws IOException

Writes b.length bytes from the specified byte array to this output stream(client). The general contract for write(b) is that it should have exactly the same effect as the call write(b, 0, b.length).

Parameters: b - the data.

Throws: If happen problem when output then this method will throws IOExeption.

4.3　Method of compress web content

Earlier chapters introduced that main host or virtual host can use “needCompress” element to enable or disable compress web content function(Refer to section 2.3 or 2.5), but it only can control compress function of all dqm file. In section 3.2 we known that can use “compress” attribute of “page” directive to set single dqm file’s compress funtion. But maybe you will think that use directive to control compress function is not agility too. Ok, kangaroo-egg provide method to contrl single dqm file’s compress funtion.

1.       public boolean setEnableCompress(boolean vaule)

Enable/disable compress output content of current dqm file. If not use this method in the dqm file, then kangaroo-egg will use current host “needCompress” element’s value to decide enable or disable compress funtion. About “needCompress” element please refer to section 2.3 and 2.5. If use this method many times then the last set is available. Only enable buffer function then can use this method. About buffer function refer to section 3.2 please. If disable buffer function then only can use “needCompress” element or “compress” attribute of “page” directive to control compress function. The current method can decide need to compress on real-time. For example you can enable compress function when a lot of content need to output. You can disable compress function when less content need to output. You can use “getBufSize” method to acquire output content size (“getBufSize” method can refer to section 4.4).

Parameters: value - a boolean indicating whether enable compress function.

Returns: If return true that mean is really enable compress function. Really enable? Yes, because in some cases such as the browser does not support decompression, then even you enable compress function but the fact is can not be compressed (This status will return false).

2.       public boolean getIsEnableCompress()

Check really status of compress function. This method return value same as “setEnableCompress” method return value. Use this method can easy to check compression status at any time.

Return: If return true that mean is really enable compress function, else not.

3.       public String getCompressName()

Get compression format. For example if the browser can support “gzip” format, the server can support “gzip” format, then return “gzip”. If the browser only can support “zip” format, the server can support “gzip” and “deflate”, then return “no”. Sometimes the browser and server can support many compression formats, then server will use default format. Now kangaroo-egg only support “gzip” and “deflate” formats, default is use “gzip”. So if browser can support “gzip” and “deflate” then kangaroo-egg will use “gzip” also. And notice the value of this method returned is unaffected by enable compress function.

Return: Compression format of client and server all can support.

For example “compress.dqm”, source code:

If your browser support “gzip” compression format then result:

Program will enable compress function at source code line 7, next program check whether really enable compress function(at source code line 9). Because we visit this dqm file by IE(IE browser support compress function), so result shown the compress function was really enabled(result line: 3).

At last program will disable compress function(source code line: 14), and check whether really disable compress function(at source code line 16). You can seen from result line 8 that was eally disabled.

You can seen from result line 4 and 9, that client support gzip compression format. Because we use IE browser and it unaffected by enable compress function.

The results maybe not same under different environments, because some browsers do not support compression format, even if it may not have support gzip compression format.

4.4　Method of buffer

In section 4.3 we again referred to the buffer, if you want to use method of “setEnableCompress” then must enable buffer function. But what is buffer function? Program will simultaneous execute and output when disable buffer function. If enable buffer function then first server will save all result to buffer until executive over, next output all results that in buffer to client.The benefits of buffer function is you can can modify the contents of the output when executing program, because result will first save in buffer. But the buffer needs temporarily to use the memory. Other if the program need long time to executed, then client get result need wait a long time too unit process of implementation complete.

  Next we introduce two methods of operate buffer.

1.       public int getBufSize()

Get current dqm file buffer size.

Return: If disable buffer function then return -1, else return the current dqm file buffer size.

2.       public void clear()

Clear all of the current dqm file buffer data. If the buffer function disabled then this method do anything.

For example “buffer.dqm”, source code:

Output result:

The result not output “contentA”(source code line: 2 to 5), because we clear all buffer data at source code line 6. You can seen from restlt that the content(at source code line 7 to 10) size is 88 bytes, the content(at source code line 7 to 13) size is 135 butes.

4.5　Directly output data

Built-in object “out” extends “java.io.OutputStream”, so base on polymorphism feature, you can think built-in “out” equal “java.io.OutputStream”.

For example “screen.dqm”, it can capture the server screen, then output screenshot to client. Source code:

The execute result is server’s screenshot. First program initialize java robot(At source code line 7). Next initialize a canvas that size same with server desktop size(At source code line 8 and 9). Next let java robot capture the server screen(soure code line 10), and save screenshot to canvas(soure code line 11). Last output cancas to client.

The “ImageIO.write” method at source line 12:

public static boolean write(RenderedImage im, String formatName, OutputStream output) throws IOException

You can seen No.3 parameter’s type is “OutputStream”. This place we send built-in “out” object to No.3 parameter, this can prove that built-in “out” equal “java.io.OutputStream”.