2009-02-24T12:24:16Z

912 Home 49

2802

= [[image: wembed.gif]] The embedded container launcher = Wembed is a tiny utility that encapsulates servlet containers that can be embedded so they can be used more easily to test web applications. The idea is to allow developers to test web applications with different containers just by doing some small configuration changes, and also allowing them to be able to use those embedded containers in automatic tests with [http://ant.apache.org/ Ant]. == [[image: contents.png]] Documentation index == * [[image: agt_runit.png]] [[#quickstart| Quickstart]] * [[image: ark.png ]] [[#step|Step by step installation]] * [[image: player_play.png ]] [[#running|Running YOUR web application with Wembed]] * [[image: mymac.png]] [[#showcase|Showcasing your web application with different containers]] * [[image: testbed_protocol.png]] [[ AntHtmlUnit | Using Wembed inside Ant to perform JUnit tests]] == [[image: agt_runit.png]]Quickstart == * You need to have Java 6 properly installed. * Go to the [http://kenai.com/projects/wembed/downloads downloads section] and grab the Wembed standalone release. * Unpack the zip file to the directory of your liking. * Edit bin/server.properties and set the '''base property''' to the directory where you have your web application deployed. * Edit bin/server.properties and set the '''extra property''' to the directory where you have the extra jar files that your application requires and are usually provided by the container. * Move to the bin directory and execute '''java -jar bin\Wembed-server.jar''', or if you have the .jar files correctly associated, simply double-click on '''bin\Wembed-server.jar'''. * Go to [http://localhost:8080/] to see your application up & running. == [[image: ark.png ]]Step by step installation == The first thing to do is to download Wembed from the [http://kenai.com/projects/wembed/downloads downloads section]. Let's suppose you grab the .zip version (Wembed_XX_standalone), download it and uncompress it in a folder. * You need to have Java 6 installed and properly configured. To verify open a command window and type '''java -version''', you should see something like: > java -version java version "1.6.0_11" Java(TM) SE Runtime Environment (build 1.6.0_11-b03) Java HotSpot(TM) Client VM (build 11.0-b16, mixed mode, sharing) * Once you have Java 6 properly set up, open a command window and move to the directory where you just uncompressed Wembed. Then type '''java -jar bin\Wembed-server.jar'''. That's it! After a brief splash screen, you should see a window open like this one: [[image: Wembed-GUI-sample.gif ]] You can then go and check the URL where the default web application is deployed (by default [http://localhost:8080/]) If everything went fine, you should see a page with the simple message “Hello wembed!”. If you want, you can also make sure that the datasources are also working fine by accessing the page [http://localhost:8080/jdbc.jsp]. There you should see a list of four items ordered alphabetically, which are the result of running a query against an embedded HSQL database, accessed through a container managed data source. If anything goes wrong, push the button “Console Show/Hide” of the GUI and you will be able to see the server logs to find out what went wrong. = [[image: player_play.png ]] Running YOUR web application with Wembed = By default, Wembed mounts as a web application the folder called web at the installation directory. But don't worry, in order to use it with your own application, you don't need to copy your application in that folder, you just need to edit the bin/server.properties file and configure the '''base property''' to point to the directory where your web application has been deployed. So, for example, if your applications is deployed at the directory ''/home/me/Apps/MyWebApp'', simply configure the property like this: # Default is ./web # base=./web base=/home/me/Apps/MyWebApp ... Run the Wembed-server.jar again and you should see your application up & running it. Note that you can also do it through the command line, setting the base as a System property, like this: java -Dbase=/home/me/Apps/MyWebApp -jar Wembed-server.jar '''Warning:''': The embedded containers included with Wembed come with a very basic set of dependencies, enough to compile JSP pages, create a DataSource and access it through JNDI. So if you start your application and see various ''ClassNotFoundException'', that's normal :). That's what the '''extra property''' is for. This setting configures a directory where you will be putting the ''extra'' .jar libraries that your application requires but are not included with it because they are usually shipped with the servlet container. == [[image: mymac.png]] Showcasing your web application with different containers == Wembed provides encapsulates the embedded servlet container implementation so you can test you application with different containers. Wembed ships currently with two implementations: * '''JettyEmbeddedContainer''', using [http://www.mortbay.org/jetty/ Jetty 6.1.7] as embedded container. * '''TomcatEmbeddedContainer''', using [http://tomcat.apache.org/ Tomcat 5.5] as embedded container. By default, Wembed uses the first container implementation that is found in the bin directory (of the lib-XXX form), so if you don't install one of them, it will automatically use the other. But if you want to choose specifically which container to use, you simply need to specify the '''container property''' to the name of the implementation you want to use. You can do it either through the '''server.properties''' file: # Default is the first one that appears in the classpath #container=jetty #container=tomcat container=XXX ... or setting the container system property when you execute the .jar file, like this: java -Dcontainer=XXX -jar Wembed-server.jar Other containers such as [http://www.caucho.com/ Caucho Resin] have been tested and have a WIP implementation, and others are planned for when the servlet containers implement the proper hooks. == other interesting things to check == * [[image: testbed_protocol.png]] [[ AntHtmlUnit | Using Wembed inside Ant to perform JUnit tests]] * [[image: agt_utilities.png ]] Modifying the Wembed configuration * [[image: agt_softwareD.png ]] Building Wembed from the source === Supported embedded containers === The list of containers that are currently supported by Wembed are the following: * [http://www.mortbay.org/jetty/ Jetty 6.1.7]: Included with Wembed * [http://tomcat.apache.org/tomcat-5.5-doc/ Tomcat 5.5]: Included with Wembed Some other containers that are being tested or ''in the works'' * [http://kenai.com/jira/browse/WEMBED-3 WEMBED-3] -> [http://www.caucho.com/ Caucho Resin]: Implementation almost ready with Resin 4.0. The tests are all green, and the remaining issues are simply facilitating deployment and usage. * [http://kenai.com/jira/browse/WEMBED-10 WEMBED-10] -> [https://embedded-glassfish.dev.java.net/ Embedded GlassFish v3]: GlassFish v3 itself is in beta and the embedded version is missing some basic features. * [http://kenai.com/jira/browse/WEMBED-11 WEMBED-11] -> [https://grizzly.dev.java.net/ Grizzly]: It misses the abilty to add some extra classpath to the applications. Once it is implemented, it seems it will be very easy to add to the list. * [http://kenai.com/jira/browse/WEMBED-14 WEMBED-14] -> [http://tomcat.apache.org/tomcat-6.0-doc/ Tomcat 6.0]: It won't be supported. If you have a favourite embedded servlet container that is not in the list, feel free to suggest it to us. In order to be able to be integrated with Wembed, the basic features a container has to implement: * Be able to be started/stop from Java code and be able to configure: ** The listening port ** The context name * Be able to deploy an exploded application (a directory) * Be able to set some extra classpath for the libraries that are not included by the application ---- ''Using icons from [http://www.everaldo.com/crystal/ the Crystal project ]''

<h1><a name='The_embedded_container_launcher'></a> <?link_for_image wembed.gif?> The embedded container launcher </h1> Wembed is a tiny utility that encapsulates servlet containers that can be embedded so they can be used more easily to test web applications. The idea is to allow developers to test web applications with different containers just by doing some small configuration changes, and also allowing them to be able to use those embedded containers in automatic tests with <a class='external' href="http://ant.apache.org/">Ant</a>. <h2><a name='Documentation_index'></a> <?link_for_image contents.png?> Documentation index </h2> <ul><li> <?link_for_image agt_runit.png?> <a href='#quickstart' class='internal'> Quickstart</a></li><li> <?link_for_image ark.png?> <a href='#step' class='internal'>Step by step installation</a></li><li> <?link_for_image player_play.png?> <a href='#running' class='internal'>Running YOUR web application with Wembed</a></li><li> <?link_for_image mymac.png?> <a href='#showcase' class='internal'>Showcasing your web application with different containers</a></li><li> <?link_for_image testbed_protocol.png?> <a href='<?url_for_page AntHtmlUnit ?>' class='internal'> Using Wembed inside Ant to perform JUnit tests</a></li></ul><h2><a name='Quickstart'></a> <?link_for_image agt_runit.png?>Quickstart </h2> <ul><li> You need to have Java 6 properly installed. </li><li> Go to the <a class='external' href="http://kenai.com/projects/wembed/downloads">downloads section</a> and grab the Wembed standalone release. </li><li> Unpack the zip file to the directory of your liking. </li><li> Edit bin/server.properties and set the base property to the directory where you have your web application deployed. </li><li> Edit bin/server.properties and set the extra property to the directory where you have the extra jar files that your application requires and are usually provided by the container. </li><li> Move to the bin directory and execute java -jar bin\Wembed-server.jar, or if you have the .jar files correctly associated, simply double-click on bin\Wembed-server.jar. </li><li> Go to <a class='external' href="http://localhost:8080/">http://localhost:8080/</a> to see your application up & running. </li></ul><h2><a name='Step_by_step_installation'></a> <?link_for_image ark.png?>Step by step installation </h2> The first thing to do is to download Wembed from the <a class='external' href="http://kenai.com/projects/wembed/downloads">downloads section</a>. Let's suppose you grab the .zip version (Wembed_XX_standalone), download it and uncompress it in a folder. <ul><li> You need to have Java 6 installed and properly configured. To verify open a command window and type java -version, you should see something like: </li></ul><pre> > java -version java version "1.6.0_11" Java(TM) SE Runtime Environment (build 1.6.0_11-b03) Java HotSpot(TM) Client VM (build 11.0-b16, mixed mode, sharing) </pre><ul><li> Once you have Java 6 properly set up, open a command window and move to the directory where you just uncompressed Wembed. Then type java -jar bin\Wembed-server.jar. That's it! </li></ul>After a brief splash screen, you should see a window open like this one: <?link_for_image Wembed-GUI-sample.gif?> You can then go and check the URL where the default web application is deployed (by default <a class='external' href="http://localhost:8080/">http://localhost:8080/</a>) If everything went fine, you should see a page with the simple message “Hello wembed!”. If you want, you can also make sure that the datasources are also working fine by accessing the page <a class='external' href="http://localhost:8080/jdbc.jsp">http://localhost:8080/jdbc.jsp</a>. There you should see a list of four items ordered alphabetically, which are the result of running a query against an embedded HSQL database, accessed through a container managed data source. If anything goes wrong, push the button “Console Show/Hide” of the GUI and you will be able to see the server logs to find out what went wrong. <h1><a name='Running_YOUR_web_application_with_Wembed'></a> <?link_for_image player_play.png?> Running YOUR web application with Wembed </h1> By default, Wembed mounts as a web application the folder called web at the installation directory. But don't worry, in order to use it with your own application, you don't need to copy your application in that folder, you just need to edit the bin/server.properties file and configure the base property to point to the directory where your web application has been deployed. So, for example, if your applications is deployed at the directory /home/me/Apps/MyWebApp, simply configure the property like this: <pre> # Default is ./web # base=./web base=/home/me/Apps/MyWebApp ... </pre>Run the Wembed-server.jar again and you should see your application up & running it. Note that you can also do it through the command line, setting the base as a System property, like this: <pre> java -Dbase=/home/me/Apps/MyWebApp -jar Wembed-server.jar </pre>Warning:: The embedded containers included with Wembed come with a very basic set of dependencies, enough to compile JSP pages, create a DataSource and access it through JNDI. So if you start your application and see various ClassNotFoundException, that's normal :). That's what the extra property is for. This setting configures a directory where you will be putting the extra .jar libraries that your application requires but are not included with it because they are usually shipped with the servlet container. <h2><a name='Showcasing_your_web_application_with_different_containers'></a> <?link_for_image mymac.png?> Showcasing your web application with different containers </h2> Wembed provides encapsulates the embedded servlet container implementation so you can test you application with different containers. Wembed ships currently with two implementations: <ul><li> JettyEmbeddedContainer, using <a class='external' href="http://www.mortbay.org/jetty/">Jetty 6.1.7</a> as embedded container. </li><li> TomcatEmbeddedContainer, using <a class='external' href="http://tomcat.apache.org/">Tomcat 5.5</a> as embedded container. </li></ul>By default, Wembed uses the first container implementation that is found in the bin directory (of the lib-XXX form), so if you don't install one of them, it will automatically use the other. But if you want to choose specifically which container to use, you simply need to specify the container property to the name of the implementation you want to use. You can do it either through the server.properties file: <pre> # Default is the first one that appears in the classpath #container=jetty #container=tomcat container=XXX ... </pre>or setting the container system property when you execute the .jar file, like this: <pre> java -Dcontainer=XXX -jar Wembed-server.jar </pre>Other containers such as <a class='external' href="http://www.caucho.com/">Caucho Resin</a> have been tested and have a WIP implementation, and others are planned for when the servlet containers implement the proper hooks. <h2><a name='other_interesting_things_to_check'></a> other interesting things to check </h2> <ul><li> <?link_for_image testbed_protocol.png?> <a href='<?url_for_page AntHtmlUnit ?>' class='internal'> Using Wembed inside Ant to perform JUnit tests</a></li><li> <?link_for_image agt_utilities.png?> Modifying the Wembed configuration </li><li> <?link_for_image agt_softwareD.png?> Building Wembed from the source </li></ul><h3><a name='Supported_embedded_containers'></a> Supported embedded containers </h3> The list of containers that are currently supported by Wembed are the following: <ul><li> <a class='external' href="http://www.mortbay.org/jetty/">Jetty 6.1.7</a>: Included with Wembed </li><li> <a class='external' href="http://tomcat.apache.org/tomcat-5.5-doc/">Tomcat 5.5</a>: Included with Wembed </li></ul> Some other containers that are being tested or in the works<ul><li> <a class='external' href="http://kenai.com/jira/browse/WEMBED-3">WEMBED-3</a> -> <a class='external' href="http://www.caucho.com/">Caucho Resin</a>: Implementation almost ready with Resin 4.0. The tests are all green, and the remaining issues are simply facilitating deployment and usage. </li><li> <a class='external' href="http://kenai.com/jira/browse/WEMBED-10">WEMBED-10</a> -> <a class='external' href="https://embedded-glassfish.dev.java.net/">Embedded GlassFish v3</a>: GlassFish v3 itself is in beta and the embedded version is missing some basic features. </li><li> <a class='external' href="http://kenai.com/jira/browse/WEMBED-11">WEMBED-11</a> -> <a class='external' href="https://grizzly.dev.java.net/">Grizzly</a>: It misses the abilty to add some extra classpath to the applications. Once it is implemented, it seems it will be very easy to add to the list. </li><li> <a class='external' href="http://kenai.com/jira/browse/WEMBED-14">WEMBED-14</a> -> <a class='external' href="http://tomcat.apache.org/tomcat-6.0-doc/">Tomcat 6.0</a>: It won't be supported. </li></ul> If you have a favourite embedded servlet container that is not in the list, feel free to suggest it to us. In order to be able to be integrated with Wembed, the basic features a container has to implement: <ul><li> Be able to be started/stop from Java code and be able to configure: <ul><li> The listening port </li><li> The context name </li></ul></li><li> Be able to deploy an exploded application (a directory) </li><li> Be able to set some extra classpath for the libraries that are not included by the application </li></ul> <hr></hr>Using icons from <a class='external' href="http://www.everaldo.com/crystal/">the Crystal project </a>

2009-05-22T07:27:52Z

3492