!This Combination tested:
(Latest versions of everything as at mid-December 2005)
*Windows 2000 or XP
*Java 1.5.0_06
*JBoss 4.0.3 SP1
*JSPWiki 2.3.57
*Eclipse 3.1.1 and JBossIDE plugin. (Required for further jspwiki development only).

!Assumptions
*You are already familiar enough with jboss to know how to get it up and running, and perform basic configuration tasks.

!Preliminaries
*Remove log4j.jar from the jspwiki.war. This eliminates an error I was getting at startup time. (You want logging to be controlled by jboss log4j logger instance).
*Comment out the line in jspwiki.properties that sets up the root logger. JBoss controls this, using its own conf/log4j.xml file.
{{{
#log4j.rootCategory=INFO,FileLog
}}}
*Deploy the jspwiki.war contents to the correct jboss deploy folder. Recommend exploding the archive, although technically it does work either way. However, jboss will dynamically explode the war if you don't deploy in exploded form. This also means that any changes made to the UserDatabase, if you are using the default config, will be lost when the server is shut down.

!Security
*By default, jspwiki uses an xml database for usernames, passwords and profile settings. This file is created automatically if necessary.
*Have a good read of [Security2.3].

!JAAS Security
To enable jboss container (jaas) security is pretty straight forward:
*Uncomment the section in WEB-INF/web.xml as denoted by the comments.
*Comment out the <resource-ref> section at the bottom unless you are actually using the JDBCUserDatabase. Otherwise you will get a jndi error at server bootup which may prevent jspwiki from properly starting up.
*The jspwiki.jaas file has to be converted into a jboss-style xml configuration, and appended to jboss's conf/login-config.xml. This will look like this:
{{{
    <application-policy name="JSPWiki-container">
      <authentication>
        <login-module  code="com.ecyrd.jspwiki.auth.login.WebContainerLoginModule"
          flag="sufficient"/>
        <login-module  code="com.ecyrd.jspwiki.auth.login.CookieAssertionLoginModule"
          flag="sufficient"/>
        <login-module  code="com.ecyrd.jspwiki.auth.login.AnonymousLoginModule"
          flag="sufficient"/>
      </authentication>
    </application-policy>

    <application-policy name="JSPWiki-custom">
      <authentication>
        <login-module  code="com.ecyrd.jspwiki.auth.login.UserDatabaseLoginModule"
          flag="required"/>
      </authentication>
    </application-policy>
}}}
*Unless you've already changed it, by default JBoss will use a very simple authentication database consisting of two properties files. Add user names and passwords (in the clear) to conf/users.properties and roles to conf/roles.properties. Do not use usernames with embedded periods, as the period is a delimiter in the syntax of roles.properties.
!JDBC User Security
A more sophisticated approach to managing users and wiki profiles is to hold this data in a database instead of xml files. This is quite easy to set up, and you can use a common database for both Jboss's general security as well as the Wiki specific profile settings.
In this example, I used a JBoss HSQLDB service to create a simple relational database. The first thing be done is to create the database service in JBoss. This is achieved through the following entries in __deploy/hsqldb-ds.xml__
{{{
<datasources>

   <local-tx-datasource>
      <jndi-name>UserDS</jndi-name>
      <connection-url>jdbc:hsqldb:hsql://localhost:1702</connection-url>
      <driver-class>org.hsqldb.jdbcDriver</driver-class>
      <user-name>sa</user-name>
      <password></password>
      <min-pool-size>5</min-pool-size>
      <max-pool-size>20</max-pool-size>
      <idle-timeout-minutes>0</idle-timeout-minutes>
      <track-statements/>
      <depends>jboss:service=Hypersonic,database=UserDB</depends>
   </local-tx-datasource>

   <mbean code="org.jboss.jdbc.HypersonicDatabase" 
     name="jboss:service=Hypersonic,database=UserDB">
     <attribute name="Port">1702</attribute>
     <attribute name="Silent">true</attribute>
     <attribute name="Database">userDB</attribute>
     <attribute name="Trace">false</attribute>
     <attribute name="No_system_exit">true</attribute>
   </mbean>

</datasources>
}}}
This creates a new database service as well as a jndi data source called 'UserDS'. Once the service is running, you can connect to the database service through the HSQLDB jdbc driver, perhaps using a general purpose tool such as DBVisualizer.

Now create the database structure using this script:
{{{
CREATE SCHEMA PUBLIC AUTHORIZATION DBA
CREATE MEMORY TABLE USERS(USERID VARCHAR(32) NOT NULL PRIMARY KEY,PASSWD VARCHAR(32) NOT NULL,EMAIL VARCHAR(64),CREATED TIMESTAMP,MODIFIED TIMESTAMP,FIRSTNAME VARCHAR(20),LASTNAME VARCHAR(20),FULLNAME VARCHAR(50),WIKINAME VARCHAR(50),ISGROUP BOOLEAN DEFAULT false NOT NULL)
CREATE MEMORY TABLE ROLES(USERID VARCHAR(32) NOT NULL,ROLEID VARCHAR(32) NOT NULL,PRIMARY KEY(USERID,ROLEID),CONSTRAINT FK_USERS FOREIGN KEY(USERID) REFERENCES USERS(USERID))
CREATE MEMORY TABLE GROUPMEMBERS(USERID VARCHAR(32) NOT NULL,GROUPID VARCHAR(32) NOT NULL,CONSTRAINT FK_GRPMEM_USERS FOREIGN KEY(USERID) REFERENCES USERS(USERID),CONSTRAINT FK_GRPMEM_GROUPS FOREIGN KEY(GROUPID) REFERENCES USERS(USERID))
CREATE VIEW V_ROLES (USERID,GROUPID,ROLEID) AS select USERID,GM.GROUPID,ROLEID\u000d\u000afrom GROUPMEMBERS AS GM \u000d\u000ainner join ROLES on GM.GROUPID=ROLES.USERID\u000d\u000aunion \u000d\u000aselect USERID,null, ROLEID\u000d\u000afrom USERS\u000d\u000ainner join ROLES on USERS.USERID=ROLES.USERID\u000d\u000awhere USERS.ISGROUP=FALSE
CREATE USER SA PASSWORD ""
GRANT DBA TO SA
SET WRITE_DELAY 20

}}}
This structure allows for users, groups and roles. Roles can be assigned to either groups or users, and users can me made members of zero or more groups. The view V_ROLES is used to enumerate all the roles that a user possesses, either directly, or indirectly through group membership. A group is defined in the USERS table with the value of ISGROUP set to true. Note that while it is possible to make a group a member of another group, the view is not recursive; it will only deliver the roles up to the first level of group membership.

The next task is to change the default JBoss security authentication to use this database. These settings are held in __conf/login-config.xml__.
{{{
<policy>

    <!-- The default login configuration used by any security domain that
    does not have a application-policy entry with a matching name
    -->

    <application-policy name = "other">
       <authentication>
          <login-module code = "org.jboss.security.auth.spi.DatabaseServerLoginModule"
             flag = "required">
             <module-option name = "unauthenticatedIdentity">guest</module-option>
             <module-option name = "dsJndiName">java:/UserDS</module-option>
             <module-option name = "principalsQuery">SELECT PASSWD FROM USERS WHERE USERID=? AND ISGROUP=FALSE</module-option>
             <module-option name = "rolesQuery">SELECT ROLEID, 'Roles' FROM V_ROLES WHERE USERID=?</module-option>
          </login-module>
       </authentication>
    </application-policy>

    <application-policy name="JSPWiki-container">
      <authentication>
        <login-module  code="com.ecyrd.jspwiki.auth.login.WebContainerLoginModule"
          flag="sufficient"/>
        <login-module  code="com.ecyrd.jspwiki.auth.login.CookieAssertionLoginModule"
          flag="sufficient"/>
        <login-module  code="com.ecyrd.jspwiki.auth.login.AnonymousLoginModule"
          flag="sufficient"/>
      </authentication>
    </application-policy>

}}}

Whilst this is enough for JBoss authentication, a few more settings are needed for JSPWiki to be able to integrate its profile maintenance in the same database. Firstly, in __deploy/JSPWiki.war/WEB-INF/web.xml__ ensure the following lines are present:
{{{
   <resource-ref>
       <description>
           Resource reference to JNDI factory for the JDBCUserDatabase.
       </description>
       <res-ref-name>
           jdbc/UserDS
       </res-ref-name>
       <res-type>
           javax.sql.DataSource
       </res-type>
       <res-auth>
           Container
       </res-auth>
   </resource-ref>
}}}
Note that the name of the data source is arbitrary, but it must match the datasource name defined in jspwiki.properties. (NB: The name I used here is not the default that comes in the JSPWiki distribution).

Also required in the same folder is a __jboss-web.xml__ file. This completes the jndi name lookup linkage. This creates a linkage between the datasource name used above, and the jndi datasource named used in hsqldb-ds.xml. The file looks like this:
{{{
<?xml version="1.0" encoding="ISO-8859-1"?>

<jboss-web>
   <resource-ref>
       <res-ref-name>
           jdbc/UserDS
       </res-ref-name>
       <res-type>
           javax.sql.DataSource
       </res-type>
       <jndi-name>
           java:UserDS
       </jndi-name>
   </resource-ref>
</jboss-web>

}}}

Finally, the __jspwiki.properties__ file needs these entries:

{{{
###########################################################################
#
#  JDBC Configuration. Tells JSPWiki which tables and columns to map
#  to for the JDBCUserDatabase. For more info, see the JavaDoc
#  for class com.ecyrd.jspwiki.auth.user.JDBCUserDatabase.
#
jspwiki.userdatabase = com.ecyrd.jspwiki.auth.user.JDBCUserDatabase
jspwiki.userdatabase.datasource=jdbc/UserDS
jspwiki.userdatabase.table=USERS
jspwiki.userdatabase.email=EMAIL
jspwiki.userdatabase.fullName=FULLNAME
jspwiki.userdatabase.loginName=USERID
jspwiki.userdatabase.password=PASSWD
jspwiki.userdatabase.wikiName=WIKINAME
jspwiki.userdatabase.created=CREATED
jspwiki.userdatabase.modified=MODIFIED
}}}

Remember to comment out the other jspwiki.userdatabase property setting that specifies the use of the XML file. (Which is the default mechanism).

That's it!

Notes:
# The groups concept in the JBoss authentication database has nothing to do with JSPWiki groups. JSPWiki cannot even see these group names, although it would be rather neat if it did! (Enhancement idea!)
# It is possible to tell JBoss that the passwords are held in encrypted form in the database by adding additional settings in conf/login-config.xml. However, you must devise your own method for getting them into the database in encrypted form.
# I would really like a mechanism for users to change their own passwords when using container-based authentication, along with email based lookup of forgotten passwords and lockout after x tries. 



!Debugging with Eclipse 3.1.1
I was able to set up the JBossIDE plugin for Eclipse, checkout jspwiki from the cvs repository, and build in the IDE using the ant script. I was then able to deploy the war file and start up debugging in the IDE. Set a breakpoint in either jsp files or other parts of jspwiki, and away it went! Under Windows, I had to ensure that the jdk\bin directory was on the path otherwise when the build script tries to launch jarsigner.exe it failed.


----

Uncommenting the JAAS section in the web.xml broke logging in for me.  I'm running JBoss 4.0.5GA though, so I don't know if something changed since 4.0.3 (although I doubt it).  I believe it is breaking because it enables Container Managed Authentication which, unless you are doing authentication to a database or something besides the default XML database, is not needed.  If someone knows why this doesn't work please let us know.  

--[AndrewSerff|http://andrew.serff.net], 21-Jan-2007

I have installed JSPWiki in JBoss and use MS SQL Server 2000 Database. I configured all the properties for jdbc provider also. When i run the Install.jsp file and click configure it is showing no admin account. My database is getting initialized and the connection is getting closed by the CachedConnectionManager. Also i get that the connection handle has been closed and is unusable when i try to save a profile. Please help me out at the earliest.

--yesesnono, 19-Jul-2007

I deployed the latest version to JBoss 4.0.4. I have followed the above steps, but when I tried to navigate to login page, it failed to display the page. Anyone knows why?


----

I can confirm that JSPWiki 2.6.0 dies on JBoss 4.0.5.GA.
\\__Specs__
*JVM 1.4.1_02_Build6
*JSPWiki 2.6.0
*JBoss 4.0.5.GA.

The front page doesn't complete loading. The following exception gets thrown:
{{{
java.lang.NoClassDefFoundError: org/apache/taglibs/standard/tag/common/fmt/BundleSupport
	at javax.servlet.jsp.jstl.fmt.LocaleSupport.getLocalizedMessage(Unknown Source)
	at javax.servlet.jsp.jstl.fmt.LocaleSupport.getLocalizedMessage(Unknown Source)
	...
	at org.apache.jasper.runtime.PageContextImpl.include(PageContextImpl.java:602)
	at com.ecyrd.jspwiki.tags.ContentTag.doEndTag(ContentTag.java:126)
}}}

--Louis, 08-Oct-2008 20:28
\\P.S.
*Also occurs on JDK 1.5.0_11
*Also occurs with JSPWiki 2.6.4 Stable

--lysior@gmx.de, 24-Sep-2009:
can be solved by deploying maven-2.2.1-uber.jar and standard-1.0.3.jar from apache Maven project


----

Oracle script:\\
\\CREATE TABLE USERS(USERID VARCHAR(32) NOT NULL PRIMARY KEY,
PASSWD VARCHAR(32) NOT NULL,
EMAIL VARCHAR(64),
CREATED TIMESTAMP,
MODIFIED TIMESTAMP,
FIRSTNAME VARCHAR(20),
LASTNAME VARCHAR(20),
FULLNAME VARCHAR(50),
WIKINAME VARCHAR(50),
ISGROUP NUMBER DEFAULT 0 NOT NULL);
\\
\\CREATE TABLE ROLES(USERID VARCHAR(32) NOT NULL,
ROLEID VARCHAR(32) NOT NULL,
PRIMARY KEY(USERID,ROLEID),
CONSTRAINT FK_USERS FOREIGN KEY(USERID) REFERENCES USERS(USERID));
\\
\\CREATE TABLE GROUPMEMBERS(USERID VARCHAR(32) NOT NULL,
GROUPID VARCHAR(32) NOT NULL,
CONSTRAINT FK_GRPMEM_USERS FOREIGN KEY(USERID) REFERENCES USERS(USERID),
CONSTRAINT FK_GRPMEM_GROUPS FOREIGN KEY(GROUPID) REFERENCES USERS(USERID));
\\
\\CREATE VIEW V_ROLES (USERID,GROUPID,ROLEID) AS select gm.USERID, gm.GROUPID, r.ROLEID
from GROUPMEMBERS gm 
inner join ROLES r on gm.GROUPID = r.USERID
union 
select u.USERID, null, r.ROLEID
from USERS u
inner join ROLES r on u.USERID = r.USERID
where u.ISGROUP=0;


--Dean Pullen, 11-Nov-2008 11:57

----

! Issue with JBOSS-5.0.0.GA and JSPWiki 2.6.4

I successfully implemented JSPWiki 2.6.4 on JBOSS 3.2.6RC2 on a Windows 2000 Server.  To do so I removed log4j from JSPWiki.war as suggested earlier in this page.  I was then able to deploy.  I then exploded the war file as suggested and that also worked fine.

When I upgraded JBOSS to 5.0.0.GA, I was unable to deploy JSPWiki 2.6.4.  When I tried to do so, I got the following errors and warnings:

{{{
WARN  [SaxJBossXBParser] SchemaLocation: schemaLocation value = 'http://java.sun.com/xml/ns/j2ee/web-app-2_4.xsd' must have an event number of URI's. @ vfszip:/C:/jboss-5.0.0.GA/server/default/deploy/JSPWiki.war/WEB-INF/web.xml[6,23]
ERROR [AbstractKernelController] error installing to Parse: name-vfszip:/C:/jboss-5.0.0.GA/server/default/deploy/JSPWiki.war state=Not Installed mode=Manual requiredState=Parse
org.jboss.deployers.spi.DeploymentException: Error creaing managed object for vfszip:C:/jboss-5.0.0.GA/server/default/deploy/JSPWiki.war 
...
}}}

With the help of Harry Metske and Romano Silva, I was able to resolve this problem.

The resolution to this problem is two-fold.  The web.xml in JSPWiki version 2.6.4 is not quite correct (this has already been corrected in JSPWiki 2.8) if you don't want to switch to 2.8, you can try to hack the JSPWiki JSPWiki.war/WEB-INF/web.xml file:

Change:

{{{
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
        version="2.4">

to read

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
         version="2.4">
}}}

That fixes the first problem you encounter.  The second problem happens when you make the fix above.  After fixing the above, you get the error:

{{{
ERROR [[/JSPWiki]] Exception starting filter WikiJSPFilter
Java.lang.LinkageError: loader constraints violated when linking 
org/xml/sax/DTDHandler class
     at org.jdom.input.SAXBuilder.configureParser(SAXBuilder.java:614)
...

ERROR [[/JSPWiki]] Exception starting filter WikiServletFilter 
Java.lang.NoClassDefFoundError
     at com.ecyrd.jspwiki.WikiEngine.initialize(WikiEngine.java:504)
...
}}}

To fix that error, use the hint found in the [BugProblemsWithCommonLogging] page:

* replace JSPWiki.war/WEB-INF/lib/commons-logging-api.jar with commons-logging-adapters-1.1.1.jar which appears in the [Apache Commons Logging site | http://commons.apache.org/downloads/download_logging.cgi]
* remove JSPWiki.war/WEB-INF/lib/xmlrpc.jar

''Note: a [web posting | http://article.gmane.org/gmane.comp.java.xdoclet.user/7798] provides the clue to above.''

--Tom Duffy, 15-May-2009 13:24