jaminid (Java Mini Daemon) HOWTO FAQ
Description: How-to and FAQ for jaminid, a lightweight HTTP server to embed in JAVA web applications without using Servlets
Keywords: Constantinos Michael, HOW-TO, FAQ, Servlets, Java, JRE, HTTP Protocol, HTTP Server, Daemon, Embedded HTTP, PHP, ASP, JSP, Perl, templates, thin-client, thin-client interfaces, client-server, web applications, jaminid, JHU

| about | download | how-to | javadoc

| # Frequently Asked Questions (FAQ) ## General 1. If jaminid does not serve files, or have scripts, how can you serve active content through it? jaminid works through demultiplexors of HTTP requests called ContentOracles - that extend the ContentOracle class. Content oracles by contract do one things: they produce the content as a regular java String. 2. How do I set up a Daemon and a ContentOracle for my Application? Usually you will need to extend the ContentOracle class and override the demultiplex(..) function. A good, quick example is in the com.prolixtech.jaminid-example.HelloWorldServer class. Here's a recap: Make a new class that will serve as your ContentOracle
    	  public class HelloWorldServer extends ContentOracle {
    		  // other functions you may use
    		  public String demultiplex(Request connRequest, Response connResponse) {
    		  	// here you can use the request object to view information about the request,
    			// and optionally the reply object to inform the server of the response
    			// (error codes, cookies, and more)

    			return theWebPageInHTML; // a String you have assembled in the function
    		  }
    	  }
Now, in your main class, start a Daemon using the ContentOracle you made:
    		HelloWorldServer s = new HelloWorldServer();
          	Daemon myDaemon = new Daemon(PORT, s);
    		// where PORT is the HTTP port (usually HTTP holds port 80)
Note that Daemon runs as a thread, so your application will continue to run even after it finishes. Usually, daemons by definition keep running; if you need to close the daemon for some reason, call the tearDown() function. 3. Is this Daemon HTTP1.1 compliant? Yes. 4. Who wrote this project? Constantinos Michael wrote the initial project and is currently the project leader. 5. Why was this project written? Because surprisingly, there was nothing out there that could perform these simple functions. You'll find Perl code to do what this project does, and you could actually also perform a system reminescent of the ContentOracle by using custom apache plugins. This project was in essence written as part of a larger project - Project MuseBox, however I feel jaminid is good enough to release on its own. 6. What are some examples I can use jaminid for? search engines file sharing programs internet jukebox players remote administration tools web servers email / newsreaders lightweight Web Services - infact, interprocess communication database accessors 7. What does jaminid mean? JAva MINI Daemon. 8. Can I use standard Java Servlets with jaminid? Yes. See below, as well as Thin Client Interfaces, also below. 9. Did you use Servlets as a model when you were designing ContentOracles? No. I had never used servlets before, but I've been using embedded HTTP servers for a long time. The fact that I arrived at a system that has similarities with Servlets is purely coincidental, as well as extremely practical. The servlet service method has the following signature:
    public void service(ServletRequest req, ServletResponse res) ;
The equivalent ContentOracle method has this signature:
    public String demultiplex(Request connRequest, Response connResponse);
Why does the ContentOracle demultiplex method return a string? Because this way, you can nest ContentOracles inside other ContentOracles. So it can have a nice functional tree effect. Often times when you are making web applications you find yourself calling the same functions for different pages. Why not make pages contain other pages? A bridging class would hold a Servlet instance, then convert Request and Response objects to ServletRequest and ServletResponse, and then have demultiplex call the servlet instance with the converts, and obtain and return the output string of ServletResponse. This is known as an Adapter Design Pattern. ## Security 1. Are there any security issues with using this Daemon? No. Remember, on its own, the daemon does not serve any files, nor even accesses the filesystem at all apart from configuration files. That is where the largest errors have been in other major web servers. If a user needs to implement a file server running on this daemon, they must be careful to follow a few good ideas: Try not to run as root on operating systems that have users and groups. Make sure the Canonical filenames fall within the root paths allowed by your application - i.e. no symlinks are followed, and the "../.." trick is not used. Whenever possible, just use a single directory for files and put everything in it. If for some reason you need to have such a large number of files that this becomes impractical, perhaps you should look into a traditional HTTP server. 2. Is HTTP authentication implemented? No, it will be implemented very shortly however. It is very simple to do non-http authentication, and if you have a user authentication system already in place, it is very easy to use that instead. 3. Does jaminid support secure-HTTP? No. There are plans to implement it in the future. 4. Can I block a particular IP from accessing the server? Yes. Just check the IP field of the Request parameter in the demultiplex(..) function. If you don't like the IP that's making the request, just return an error message. You can always block all incoming connections using a firewall, or very simply, just block all IPs that are not 127.0.0.1 in the beginning of demultiplex(..). ## Thin Client Interfaces 1. What other ways can I use to make thin-client interfaces? Does it have to be through HTTP? In short, no. There are plenty of methods to make thin-client interfaces, but HTML/HTTP is the most commonly used method for the simple reason that there are browsers installed everywhere. You could always design your own methods. There is a growing tendency to design XML powered interfaces - the Mozilla project has developed a promising standard. However, jaminid is not concerned at all with XML or HTML - all it does is, it transfers HTTP data. Theres a solution that is more standard than jaminid albeit only slightly harder to use - you can use servlets, and you can have the bonus feature of jaminid - the bundle in your application - by using an embedded server. You can use jaminid in fact as your embedded server if you write a (short and easy) class to bridge Servlets with ContentOracles. You can also use a more heavy weight server such as jetty - which at 350+K is about 10 times as big as jaminid but is still quite fast. Jetty might be more suitable if you want a server for multiple projects. 2. Why are thin-client interfaces good? Where are they useful? For the majority of applications, they are suitable. They do not take more time to program than regular interfaces, and in fact, they can be cheaper to program - web designers can do it, it doesnt take programmers. Depending on what method is used, the interface is programmed independently of the rest of the application. (That is usually not true with ASP, JSP, and PHP, which infact do not discourage seperation of form and function, which is a major trap with traditional programming also.) Furthermore, there is an added bonus: Added features can and will deploy seemlessly on their thin clients. You don't need to "download" new versions of your favorite websites to view the added features. 3. Why use jaminid instead of {PHP|ASP|JSP|...}? Because you're a traditional programmer and this style of I/O appeals to you more. Because you don't know the scripting language. Because you don't want to have a third party server around. Because you want to bundle the entire application together. Because you'd like everything to be in Java. Because you want to enforce seperation of content and function (this is a step, but not a guarantee) 4. Is there no templating system bundled with this at all? No. Templates are subjective. There are a few options out there; I definetely reccomend the excellent HTML.Template.java, which is a java "port" of the HTML::Template.pm templating system from Perl. You define template files with placeholders that can be as complicated as tables of tables of tables (e.t.c.) and you pass the parameters you want put there in the form of a standard java Hashtable. It's fast and easy. If you are obsessed with speed, perhaps you should not even use templates at all, or you should look into producing XSLT and XML pairs of files that burden the client with production instead of the server. 5. I'd like to built my own web server instead! Sure. Building a web server is fun. The best page to start would be the HTTP Protocol Specification on W3 Consortium. If you think that is an overload of information for a starting developer, look at HTTP Made Really Easy. My advice to you would be, study the protocol header transcripts - monitor port 80 on your computer as you use your browser. There are several ways to do this; you can use Mozilla with an http viewing plugin. Also you can use the Web Snifter page to do the whole thing online, if you dont have mozilla. Study a lot of the headers in different situations, where there are cookies, where there's authentication going on. If you like programming web servers also, you should work for this project! If you just want a good server to put on your webpage, there's no doubt: Apache is the best, it's free, and the license is very flexible. If you're interested in running Java on your server, you can use either jaminid or Jetty to run servlets, Apache Jakarta Tomcat to run Servlets and JSP. Caucho Resin looks extremely promising also. 6. What's the difference between servlets and Java Server Pages (JSP)? The essential difference is the style of programming. JSP is closer to ASP and PHP, where the logic and content lie on the same page. JSP is dynamically compiled to a servlet when it is run, so the performance is bounded by the same limitations. However, servlets tend to promote better programming disciplines, and tend to be cleaner, as they are programmed with a different attitude since integration of content and logic is not as straight forward. Both of these are usually harder to configure than jaminid. There are plenty of resources available that cover this area; here's a good servlet starting point from Sun, and here's an over view of Java Server Pages (JSP). ## Open Source 1. Can I contribute to this project? Of course! That is the whole idea. Unfortunately I don't have time to perfect the Daemon, so any help I can get is valuable. If you see a bug you should immediately let me know, and if you can, fix it! 2. Can i get this released under a different license? Depends. Ask me. 3. What are some things that need to be done with jaminid? Servlet and even JSP integration as a plugin module. Lots of testing. Some cleaning up of the code. Anything else you can think of.
| Download jaminid on SourceForge.net
The project leader is Constantinos Michael. This project is open source, released under the LGPL. If you need to use this project and would like to obtain it under a different license, please contact the administrators to ask for it.