Beans, Date, Encode, HTML, INI and XML Utilities

This document provides basic details on the usage of the date format, encode, HTML template, INI, security and XML utilities of the ProSyst Util Bundle.

Contents:

Beans
Encode
HTML Template
INI
XML

Beans

The com.prosyst.util.beans package contains classes for easier handling of JavaBeans within an OSGi-enabled environment, e.g. for introspecting a bean class for properties.

Encode

The encode utilities implement the most widely used encoding algorithm, such as Base64, variable type conversion, hexadecimal binary string coding, and byte array transformations.

Base64

Base64 coding is used mainly in MIME mapping application as MIME formatted data is in Base64. The utility class is com.prosyst.util.encode.Base64.

Hexadecimal

The hexadecimal coding utility translates bytes into hexadecimal strings, and vice versa. The utility class is com.prosyst.util.encode.Hex.

Byte Array

The byte array utility splits, couples and extracts designated elements from byte arrays. The class to use is com.prosyst.util.encode.Axill.

HTML Template

The HTML Template utility in the com.prosyst.util.template package allows you to define template pages for servlets that generate HTML code. In this pages via labels you can mark the parameter that your servlet writes at runtime. The HTML template utility is represented by the HTMLTemplate interface, which is implemented by HTMLTemplateFileImpl.

The HTML template utility saves you efforts to write many constant HTML code in your servlet. It also saves memory as template pages are not kept there. Instead, when the page is initially passed, the utility analyzes it and cuts into pieces from label to label. Then, these pieces are written as separate files in the framework storage. When the servlet calls the HTML template writer, the content is taken straight from the stored temporary files and written to the HTTP output.

Two types of data can be specified as labels:

Data which is not known when the template is written but it is retrieved when the page is loaded in the HTML template utility, e.g. an alias in the HTTP Service. In such case, you may specify these labels as init labels - that is they are loaded immediately and finally by the HTML template utility and are not treated as labels any more.
Data which is dynamically generated by a servlet in response to a request.

The labels in the template page are surrounded by the "$" symbol. The label name can be any string. Two labels can have one and the same name.

<html>
  <head>
    <title>My Template Page</title>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  </head>

  <body>
    <h1>My Template Page</h1>
    <p>$my_label$</p>
  </body>
</html>

Listing 1.1: An example HTML template page.

After you model the template page, to be able to use it you should be able to supply a URL to it - e.g. you can place the HTML file inside the bundle JAR file.

Next from your HTTP servlet, registered in the OSGi HTTP Service:

Instantiate HTMLTemplateFileImpl passing the URL of the template file together with some initial values of the labels as [label,ini_value] string arrays.
To get a writer for the template page - an instance of TemplateWriter, call the getTemplateWriter method with the java.io.PrintWriter of the HttpServletResponse, assigned for your servlet.
To print the HTML code from the current position to the next label in the template, use the writeToNextLabel method of TemplateWriter. This method returns the string of the reached label in the HTML template.
Write the required label value through the PrintWriter.
When the end of the template page is reached, the writeToNextLabel returns null.

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
import org.osgi.service.http.HttpService;

import com.prosyst.util.template.*;

import javax.servlet.*;
import javax.servlet.http.*;

import java.io.IOException;
import java.io.PrintWriter;

public class HTMLTemplateTester extends HttpServlet implements BundleActivator { 
  private ServiceReference refHttpService = null; 
  private HttpService httpService = null; 
  final static String SERVICE_HTTPSERVICE = "org.osgi.service.http.HttpService";
  HTMLTemplateFileImpl template;

  public void start(BundleContext bc) throws Exception {
    try { 
      refHttpService = bc.getServiceReference(SERVICE_HTTPSERVICE);
      if (refHttpService != null) { 
        httpService = (HttpService)bc.getService(refHttpService); 
        template = new HTMLTemplateFileImpl(getClass().getResource("/my_template.html"), 
                                            null,
                                            bc);
        httpService.registerServlet("/myservlet", this, null, new MyHttpContext());
      }
    } catch (Exception e) {
      e.printStackTrace();
    } 
  }

  public void stop(BundleContext bc) throws Exception { 
    if (refHttpService != null) { 
      bc.ungetService(refHttpService);
    }
  }
         
  public void doGet(HttpServletRequest request, HttpServletResponse response)
              throws IOException { 
    PrintWriter out = response.getWriter(); 
    TemplateWriter templateWriter = template.getTemplateWriter(out);
         
    while(true) { 
      String label = templateWriter.writeToNextLabel(); 
      if(label == null) {
        break;
      } 
      if(label.equals("$my_label$")){
        out.println("<p>Hello!</p>"); 
      }
    } 
  }
}

Listing 1.2: Loading a template page through the HTML template utility.

INI

The com.prosyst.util.ini.IniFile class represents a utility for management of INI files, structured as sections (IniSection objects) of key=value pairs:

[<section1>]
<key11>=<value11>
<key12>=<value12>
. . .
[<sectionN>]
<keyN1>=<valueN1>
<keyN2>=<valueN2>
. . .

Listing 2: The structure of a file manageable through the ini file utility.

IniFile allows you to create an INI file, fill it with data and save it, as well as load a ready INI file, parse it and make some changes if necessary. The ini utility also supports // line comments and ## key=value comments.

XML

The com.prosyst.util.xml package contains classes that can be used to read and parse an XML document.

Through the XMLReader class you can read an XML from an input stream or through a reader. To get aware of every read tag, you should pass a TagListener implementation as an argument in the chosen read method of XMLReader. When the end of a tag is reached, the TagListener will receive an instance of TagClass for this tag. To get the name, line, attributes, content, and child tags at specified positions, you can use TagClass provided to the listener. When using XMLReader, tag attributes are not parsed and validated until explicitly retrieved from the TagClass instance.

Through the XMLParser class you can parse an XML again from an input stream or through a reader. To parser an XML and get notified about every read tag, call the proper parseXML method the ExTagListener which will receive the notifications. The XMLParser makes difference between opening and closing tags and calls respectively the startTag and endTag methods of the ExTagListener for the parsed document. To get the name, line, attributes, content, and child tags at specified positions, you can use Tag class provided to the listener. When using XMLParser, a tag's attributes are parsed and validated on reading the opening tag. In general, the XMLParser works a little slower that the XMLReader but provides more complete XML processing.

With the XMLUtil class you can replace a tag.

Note that you cannot create new XMLs with the XML utilities.

Log Reference Utility