Sambuca Embedded HTTP Framework - Integrate Sambuca

Navigation

How to Integrate Sambuca into your Java Apps

This example will make references to the SambucaHttpServerDemo.java class, which is a demo File Web Server that comes packaged with the Sambuca Framework. Please read the Security Advisory before running the Demo on your system.

Integration Steps - High Level Summary

  1. Implement a com.roguelogic.sambuca.ServiceHandler class. This class should contain the "business logic" or at least the entry point for the business logic to process incoming HTTP Requests and write HTTP Responses to be sent back to the client. Implementations of this class *should not* be singletons for performance considerations. Although some very specific implementations in environments with tight resources may consider this type of implementation. The demo server implementation include a File based Service Handler called: SimpleDirServiceHandler. See this class for more details.
  2. Implement a com.roguelogic.sambuca.ServiceHandlerFactory class. This class will be used by the SambucaHttpServer instance to create new instances of the User Defined ServiceHandler Implementation as needed by the server. The demo server implementation include the Service Handler Factory called: SimpleDirServiceHandlerFactory which creates and returns instances of SimpleDirServiceHandler. See this class for more details. Also to properly instanciate an instance of SimpleDirServiceHandlerFactory please see the class: SimpleDirServiceHandlerFactory and also refer to these steps:
    1. Create the Factory instance: SimpleDirServiceHandlerFactory factory = new SimpleDirServiceHandlerFactory();
    2. Set the WWW Root Directory (the directory on your local machine that you want to share via the HTTP Server) by calling the setWwwRoot(String) method on the factory object.
    3. Set the default HTML file that should be used if a user enters a URL without a filename by calling the setIndexFile(String) method on the factory object. Example: setIndexFile("index.htm");
    4. Set the MIME Type Map (represented as a properties object) by calling the method setMimeTypes(Properties) on the factory object.
      1. To load a properties object with MIME Types the Key needs to be the filename extension/suffix (examples: HTM, HTML, JPG, GIF, EXE, DOC) and the Value needs to be the MIME Type String (examples: text/html, image/jpeg).
      2. Sambuca includes a default properties file with various common filename extensions mapped to their corresponding MIME Types. The SambucaHttpServerDemo class will load this file by default, but you can use it in your own programs by loading it via a resource stream from the classpath.
    5. Set the Logger implementation by calling the setLogger(SambucaLogger) method on the factory object. The current implementation of the Demo SimpleDirServiceHandler does not make use of the logger. However the method flow was created as an example how ServiceHandler implementations can reference and use a logger.
  3. Optionally implement a logger class implementing interface: com.roguelogic.sambuca.SambucaLogger. If no special logging requirements are needed, it is recommended to instanciate com.roguelogic.sambuca.StdIoLogger and pass this to the instance of the SambucaHttpServer. Although NULL may be passed to the SambucaHttpServer or the setLogger(...) method may not even be called, it is recommended that you always instanicated and pass a logger implementation to the server.
  4. Create Instance of the Sambuca HTTP Server class: com.roguelogic.sambuca.SambucaHttpServer. See the Demo class: SambucaHttpServerDemo which instanciates a Sambuca HTTP Server that will act as a simple File Web Server.
    1. Set Port to listen on using method setPort(int) on object of class SambucaHttpServer
    2. Set Logger Implementation using method setLogger(com.roguelogic.sambuca.SambucaLogger) on object of class SambucaHttpServer. Default logger implementation can be used by setting new instance of com.roguelogic.sambuca.StdIoLogger
    3. Set Service Handler Factory Implementation using method setHandlerFactory(com.roguelogic.sambuca.ServiceHandlerFactory) on object of class SambucaHttpServer. The Demo Server includes a Service Handler Factory Implementation called: SimpleDirServiceHandlerFactory
    4. Invoke the listen() method on object of class SambucaHttpServer to put the server in "listening" or active mode in which it will accept incoming connections.
    5. If you would like the current calling thread to block and wait while the Sambuca HTTP Server is listening, invoke method waitWhileListening() on the object of class SambucaHttpServer which is already listening.
    6. Usage of the Demo File Web Server: java <-DMimeTypes=[MIME_TYPES.PROPERTIES]> <-DSambucaLogger=[CLASS_NAME]> com.roguelogic.sambuca.SambucaHttpServerDemo [WWW_ROOT_DIR] [PORT]
      Where [WWW_ROOT_DIR] is a directory on your local computer to be made available for browsing via connection on the supplied [PORT].
  5. To shutdown a Sambuca HTTP Server instance that is listening and accepting incoming connections simply invoke the shutdown() method on the object instance of the SambucaHttpServer that is currently listening.


RogueLogic