GNU-Paperclips

Programatically binding servlets to resources

The GNU-Paperclips API can be used by programmers to bind servlets into the engine in a number of ways. This makes it easy to build small boot-strap classes to act as custom start ups for Paperclips. In effect this is all that the class org.gnu.paperclips.Paperclips is. It simply starts a GNU-Paperclips HttpService and then binds in a number of default servlets. In other environments other servlets might be wanted by default and in that case you should write your own boot-strap class.
 

Binding in GNU-Paperclips

In Paperclips a binding is a relationship between some executable content that the server understands and a resource path. Most administration is done through resource paths, allowing executable content other than servlets to be easily included in GNU-Paperclips. Right now, only Servlets are supported but Paperclips is likely to support CGI scripts (without a servlet wrapper as such) very soon.
 

The HttpService binding methods

The Paperclips class HttpService represents a running web server and as such you can bind new resource path handlers into it. These handlers are not defined specifically as a class of objects, it is implicit: if Paperclips provides a method to bind some sort of handler to a resource path then a handler is installed in the engine.

The methods available are:
 

bindPath(String path,String handler); the servlet identfied by handler will be bound to the engine, this method may in the futrue be used for CGI scripts as well;
bindPath(String path,
         String filterpath,
         String classname,
         Hashtable initparams);		 the servlet specified by the classname string is bound to the resource path, the filterpath is used as the filter for the servlet and the initparams is used for the initalisation parameters - specifically for servlet classes though this may change in future;
bindPath(String path,
         String filterpath,
         String classname);		 again, for servlets only right now but might change, this one the same as the above only no initialisation parameters are provided;
bindServlet(String classname); a servlet only method - provided for servlets which implement GNU-Paperclips auto load interface AdministrationSuggestion. See below for details.

There are many illustrations throught the Paperclips code of how to use these methods.

Try to use bindPath() methods whenever possible, AdministrationSuggestion loading is useful but un-portable.
 

AdministrationSuggestion Servlets

For those writing servlets which will be used within GNU-Paperclips there is an interface which can be used by the servlet author to specify the initialisation parameters for the servlet. You can specify the filter path, the initialisation parameters and the resource path the servlet is mapped to.

The next version of the Servlet API is said to include such a feature so GNU-Paperclips has it as an experimental feature. Servlets you write in this way can only be exepected to load the way you want them under Paperclips, other servers are not likely to support Paperclips AdministrationSuggestion.

To use AdministrationSuggestion with your servlets you simply implement the interface org.gnu.paperclips.AdministrationSuggestion. You then use the defined naming convention to specify your various initialization information. The interface has final statics which define this naming convention:
 

String MAPPATH_FIELDNAME is the definition of what you should call the variable which will be used to hold the resource path to which you wish to map the servlet, the variable should be a String;
String FILTERPATH_FIELDNAME is the definition of what you should call the variable which will be used to hold the filter path for the servlet, this variable should also be a String;
String PARAMETERS_FIELDNAME is the definition of what you should call the variable which will be used to hold the parameters table for the servlet, the parameters table is a Hashtable.

The servlet can then be bound to the engine with the HttpService.bindServlet() call, you must pass the classname of the servlet as a String parameter.

GNU-Paperclips then loads the class and uses the Java Reflection API to extract the information it needs for the servlet.

Initialisation parameters
The correct values for the initialisation parameters are inserted into the parameters table by the binding process but it is okay to insert them yourself.