[cosmo-dev] IMPORTANT: new webapp packaging

[Brian Moseley]

as of r6372, we've moved to a slightly different way of configuring
the cosmo webapp for Tomcat.

config changes
============

the war now includes /META-INF/context.xml with <Environment> and
<Resource> elements for the config properties file location, the JDBC
DataSource, and the JavaMail Session.

the snarf server.xml no longer includes those elements, though it
still has the commented out example secure <Connector> and the
access-logging <Valve>. additionally, the <Host> has the
"deployOnStartup" attribute turned on.

Tomcat, upon finding the war in its webapps directory, expands and
auto-deploys the war. it creates the file
$CATALINA_HOME/conf/Catalina/localhost/chandler.xml, which is a copy
of the war's context.xml, and uses that to configure the webapp at
runtime. if chandler.xml already exists, Tomcat just uses it as-is
rather than overwriting it from the war's context.xml.

Tomcat names the file and mounts it in url-space based on the war
name. for example, if the war is named cosmo-0.12-SNAPSHOT.war, Tomcat
creates $CATALINA_HOME/conf/Catalina/localhost/cosmo-0.12-SNAPSHOT.xml
and makes it available on the web at /cosmo-0.12-SNAPSHOT/. thus,
there will be an upcoming change to the snarf build to name the webapp
artifact chandler.war to make sure Tomcat mounts it at /chandler.

the end result is that we now have a war which can be dropped into a
non-snarf Tomcat instance and will use the best-available Tomcat
configuration mechanism. deployers will still need to customize the
generated chandler.xml, but this is preferred over modifying
server.xml itself. the next step is to make an additional package
available for download with the war, release notes, license info, etc.
this artifat will continue to be named with the version number, eg
cosmo-0.12-SNAPSHOT.war.

for developers
===========

this changes how we set up our dev environment. you have two choices
now: you can either use a snarf build like you're used to, or you can
use a standalone Tomcat. the instructions for either are the same:

1) make a $CATALINA_HOME/conf/Catalina/localhost/chandler.xml file.
here's what mine looks like:

<Context path="/chandler" reloadable="true"
docBase="/Users/bcm/work/osaf/cosmo/cosmo/src/main/webapp">

  <Environment name="cosmo/config"
value="file:/Users/bcm/.cosmo/cosmo.properties"
               type="java.lang.String" override="false" />

  <Resource name="jdbc/cosmo" type="javax.sql.DataSource" maxActive="100"
            maxIdle="30" maxWait="10000" username="cosmo"
            password="cosmo" defaultAutoCommit="false"
                    driverClassName="com.mysql.jdbc.Driver"

url="jdbc:mysql://localhost:3306/cosmo?useUnicode=true&amp;characterEncoding=UTF-8"
/>

  <Resource name="mail/cosmo" type="javax.mail.Session"
                mail.transport.protocol="smtp"
                    mail.smtp.host="localhost"
                    mail.smtps.host="localhost"
                    mail.smtp.starttls.enable="false" />

</Context>

things to notice:

a - the context is reloadable
b - the doc base is my war:inplace-built cosmo source tree
c - the config properties file is in my homedir at  ~/.cosmo/cosmo.properties
d - i'm using mysql instead of derby

2) make ~/.cosmo/cosmo.properties. here's mine:

cosmo.hibernate.dialect=org.osaf.cosmo.hibernate.CosmoMySQL5InnoDBDialect
cosmo.service.account.requireActivation=false
cosmo.log.HttpLoggingFilter.format=%M %U %Q %C %I

(it's kind of annoying that PropertyPlaceholderConfigurer dies if any
of these parameters aren't set. it really ought to just set null or
false and let the bean provide a default value. this would reduce the
properties file to just the dialect property.)

what's cool about using a standalone Tomcat is that you can support
multiple branches simply by mounting contexts at various paths, like
/cosmo-trunk, /cosmo-0.10, /cosmo-streaming, etc. you'd have separate
context config files for each within
$CATALINA_HOME/conf/Catalina/localhost/, each with docBase pointing to
the appropriate source tree. each could use a single cosmo.properties,
or you could point one at a different properties file if necessary.
there'd be no need to build snarf at all.

okay, i think that's everything. let me know if anything's broken.