JPublish requires JDK 1.2 or higher and a servlet engine which is compatible with version 2.2 of the Servlet Specification. JPublish has been tested with Tomcat 3.2.1 the reference servlet implementation developed by the Apache group and with JBoss 2.2.1 for EJB support.
To install JPublish you need to bind the JPublishServlet class as a servlet within the servlet engine and to configure your web site paths.
JPublish includes a sample site which will help you become familiar with how JPublish sites are organized. Let's say we want to install the JPublish example in the ROOT context of Tomcat. This way JPublish will handle all incoming requests. First insert the following XML in the WEB-INF/web.xml:
<servlet> <servlet-name>jpublish</servlet-name> <servlet-class>org.jpublish.servlet.JPublishServlet</servlet-class> <load-on-startup>1</load-on-startup> <init-param> <param-name>config</param-name> <param-value>dir/config.xml</param-value> </init-param> </servlet>
Replace dir with the directory containing the config.xml file. If the web.xml file doesn't exist you can copy the example/web.xml file into the WEB-INF directory and use that as the basis for your web.xml file.
Next, specify the correct paths to the templates, pages, static elements, and actions in the config.xml file.
<jpublish:page-root>site-root/pages</jpublish:page-root> <jpublish:template-root>site-root/templates</jpublish:template-root> <jpublish:action-root>site-root/actions</jpublish:action-root> <jpublish:static-root>site-root/static</jpublish:static-root>
Replace site-root with the site's root directory.
You can also configure one or more repositories as required.
<jpublish:repository name="fs_repository" classname="org.jpublish.repository.filesystem.FileSystemRepository"> <root>path-to-content</root> </jpublish:repository>
Copy the lib directory to the directory WEB-INF/lib. You can also add whatever JARs required by your web site to this directory. If you are going to be using any scripting languages (which are supported by IBM's Bean Scripting Framework) other than Python then you should also copy those files into the WEB-INF/lib directory.
If you are running Tomcat 3.2 then add the following line to Tomcat's server.xml configuration file. This file is located in TOMCAT_HOME/conf.
<RequestInterceptor
className="org.apache.tomcat.request.Jdk12Interceptor"/>
Finally restart your servlet engine.
Accessing a web page through JPublish is exactly the same as any static web content (even though it is not static.) In the background JPublish will actually do some work to locate the correct resources and template for the given page type (i.e. HTML, WML, etc.) and language based on the requested document's name as well as HTTP headers.
Each page is a mixture of several items. First is the page definition which is XML. Your XML definitions are located in the site-root/pages directory. The directory structure of this hiearchy is an exact representation of what is available through your web site. The next component is the template which is located in the site-root/templates directory. Each page can define its default template that it will use. The final component is the content which is located in the site-root/content directory. This content is accessed through the FileSystemRepository class.
An example web site is provided so that you may become familiar with how JPublish works.
Each web page is defined in an XML document located in the site-root/pages. It is easiest to take an example: suppose that a visitor to your site requests the page /dogs.html. JPublish will look for the dogs.xml file in the pages directory for the page definition. If the same visitor requested /development/java/stuff.html then JPublish would look for the file /development/java/stuff.xml in the pages directory. As you can see this structure is exactly the same as the structure which visitors to your site will see.
You can also expose EJBHome objects and EJB session beans directly in pages by including a directive in each page's XML configuration file. See the file example/pages/ejb.xml for an example of this.
JPublish uses the Velocity template engine from the Apache group for its templating language. Velocity documentation can be found at http://jakarta.apache.org/velocity. Each page has a default template which is used to render the page. Changes made to the template will be reflected throughout your web site.
Accessing content in JPublish is done through repositories. Repositories are registered at startup time through the config.xml file. Since each repository is registered with a name accessing the repository from a template is as simple as $name.get(content) where name is the repository name and content is a path to the content you are loading.
There are two typical use-cases for loading content:
fs_repository.get("global/copyright.html").fs_repository.get($page.Path).JPublish also supports static elements such as images and other media files. JPublish will first look for any file requested in the static directory before looking in the page definitions.
The JPublish framework defines the Action interface as a way of invoking custom actions in response to form data. There are two ways to provide actions:
actions directory.Actions can be invoked at several different locations. JPublish currently supports 5 different locations for invoking actions:
The syntax is:
<jpublish:startup-action name="script|name"/>The syntax is:
<jpublish:global-action name="script|name"/>The syntax is:
<jpublish:path-action path="path" name="script|name"/>action is used if there is no identifier specified in the configuration.)In order for script actions to function the scripting langauge's JAR files must be included in the WEB-INF/lib directory in your web application.
Registered actions can be executed by name whereas a script action should include the filename extension (for example page.html?action=Hello.py.)
Actions can issue cause page redirects by inserting the attribute "redirect" in the Velocity context. Redirects can be to a JPublish page or a URL. To issue a redirect to a JPublish page the value of "redirect" should be the path to the page without a suffix. The current page's suffix will be appended to the value of the redirect attribute. Values ending with a suffix or a slash will be considered URLs. The reasoning behind this is that a script doesn't need to know what type of page was requested (i.e. HTML, WML, etc.) rather it uses the current pages type be default.
JPublish uses the formproc library for form handling. Form objects are retrieved from a FormManager which will configure the form object using an XML configuration file. A target object is set for a Form and then the form will fill the target object upon receipt of the form data using the Java Reflection API. Additionally, form data can be automatically validated through regular expressions, scripting languages such as Python, or through Java classes all of which are configured from the same XML configuration file.
FormProc's configuration is done through an XML file in a manner similar to JPublish. You must set any relevent paths in FormProc before launching JPublish. FormProc will monitor your form configuration files though so you can make changes while your servlet engine is running.
JPublish provides methods for allowing simple integration with EJB objects. EJB home interfaces can be specified in the main JPublish configuration file and on a per-page basis. Session beans can automatically be exposed at both the application level (in the main configuration file) or at the page level. Home interfaces and exposed session beans are placed directly in the Velocity context for access by page developers. Action scripts can also get at these beans through the vc object (which is a reference to the the Velocity context).
JPublish uses log4j as its logging engine, albiet indirectly through the EdenLib logging API. Logging can be configured by placing a Log4J properties file called log.properties in the WEB-INF/ directory of the application context. The example application which comes with JPublish includes a basic log configuration file.
JPublish exposes an object called syslog in the Velocity context and in the scripting engine. Script and page authors can send log messages to this logging stream. Actions which are written as Java classes can also access this log stream through org.jpublish.util.LogSystem.syslog.
The source for JPublish development.
The template engine used by JPublish.
The Servlet 2.2 reference implementation.
Open source application server.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
This product includes software developed by the JDOM Project (http://www.jdom.org/).
This product includes JNP 0.2 which was developed by dreamBean Software. You can download the source code at the dreamBean web site.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.