1.2 to 1.3 Milestone 1 upgrade

Changes (compared to Daisy 1.2)

Features

Document Variants: it is possible to have multiple variants of one document, which can be branch-variants or language-variants. These variants all share the same document ID, but are then distinguished by their branch and language.
Document Tasks: these are tasks that run across a number of documents and are executed in the background. This was added to enable the creation of branches (see variants) across a number of documents, but is useful for many other things as well. Tasks can be written in Javascript (Administrators only) or selected from predefined actions.
daisy-js: a small shell script which sets the Java classpath to contain all Daisy client jars and then launches a Javascript interpreter (Rhino). This provides a low entry-bar for people who want to experiment with the Daisy API.
Navigation tree: when there is an error in a query or a recursive import of navigation trees, a special error node is now inserted in the tree, instead of showing "Error generating the navigation tree".
Made the installation easier: automated more steps (no more editing of files by hand), clarified the texts displayed by the installation programs, ask less questions, added log4j config for openjms dbtool so that its error messages become visible, added check for MySQL database version, provide zip download for Windows users, and more.
Passwords are now stored as SHA digests in the database (previously they were stored as clear text)

Bug Fixes and improvements

Daisy 1.3-M1 contains numerous bug fixes and smaller improvements. We didn't really keep track of each and everyone, here are some from the top of my head:

Daisy now works on Java 1.5 (Java 5)
Fixed a potential encoding issue that could occur when there's a proxy (such as Apache) in between the browser and the Daisy Wiki, or when using certain servlet containers.
Use TCP as default transport protocol for OpenJMS (instead of RMI), which is more firewall friendly since it uses a fixed port.
Fixed issues with unhandable redirects in the navigation tree.
The id attribute of link nodes was not supported by the graphical navigation tree editor, causing it to be dropped.
Show little triangles before expandable nodes in the navigation tree (when the navigation tree is not rendered fully expanded). For this, an attribute named hasChildren has been added to document nodes in the output of the navigation tree.
Fixed an error in the determination of available documenttypes (DSY-118)
Added document URLs in comment notfication mails
The order of out-of-line links was not maintained when using the remote API.
Use appropriate HTTP status codes in the Daisy Wiki (e.g. 404 when a document does not exist)
IE improvements: items in the page menu (on the right) are now spaced correctly, the sample queries on the Query Search page now work.
The navigation tree editor didn't escape special characters when generating the navigation tree XML (such as < and &).
Some fixes in the HTML cleanup:

sometimes whitespace could be introduced where it shouldn't be
once a <pre> tag was encountered, <br/> elements in any elements followng that would be removed
remove <br/>s at the end of <li>s, which Mozilla/Firefox tends to insert

Fixed problem with encoding of HTMLArea language files, causing the failure of the wysiwyg editor to load for some languages in Internet Explorer.
Enabled the switching of the block-style within lists.
Daisy now ships with Cocoon 2.1.7 (instead of an SVN snapshot).
Fixed a bug that could cause a lot of "" to appear at the end of a document after editing using Internet Explorer.
...

Miscellaneous

In this Milestone release only the English and Dutch language bundles are up to date.
Due to the introduction of the variants feature, some incompatible API changes occured (both in the Java and HTTP API), though nothing major. In general the specification of the branch and language is optional and defaults to the built-in "main" branch and "default" language. There are also a few new JMS events related to branches: DocumentVariantCreated, DocumentVariantUpdated, DocumentVariantDeleted, (Branch|Language)(Created|Updated|Deleted).

Upgrading

Before starting

Shutdown Daisy (the Repository Server, the Daisy Wiki, and the OpenJMS server)

Make backups! More specifically:

make a copy of the daisy data directory
do a dump of the database:
mysqldump daisyrepository -uuser -ppassword > daisyrepo.sql

Update database schema

There have been changes to the database schema (among other things, to support the document variants and the document task manager).

To do the appropriate changes to the MySQL database, an upgrade script is available.

Daisy 1.3 has a new feature called language variants that allows to have multiple language versions of the same document. By default, after migrating the repository, all documents will belong to a language called "default". If all the documents in your current repository are in the same language, and you want them to be classified under a more specific langauge then "default", then see the instructions at the top of the file misc/daisy-1_2-to-1_3_M1.sql

To execute the upgrade script, perform the following steps in a command prompt or shell:

cd <DAISY_HOME>/misc
mysql -Ddaisyrepository -udaisy -p<password>
[then on the mysql prompt]
\. daisy-1_2-to-1_3_M1.sql

Update OpenJMS configuration

Starting with Daisy 1.3-M1, the installation configures OpenJMS to use TCP instead of RMI as transport protocol, which has the advantage that is more firewall-friendly since it uses a fixed port number.

Therefore, perform the following steps:

copy <OLD_DAISY_HOME>/openjms/config/openjms.xml to <NEW_DAISY_HOME>/openjms/config/openjms.xml
Open the file <NEW_DAISY_HOME>/openjms/config/openjms.xml in a text editor

Inside the <Connectors> element, add the following:

    <Connector scheme="tcp">
      <ConnectionFactories>
        <QueueConnectionFactory name="TCPQueueConnectionFactory"/>
        <TopicConnectionFactory name="TCPTopicConnectionFactory"/>
      </ConnectionFactories>
    </Connector>

Add the following element somewhere as a child of the root element (for example, before the </Configuration> closing tag):
```
<TcpConfiguration port="3030" jndiPort="3035"/>
```

open the file <DAISY_DATA>/conf/myconfig.xml in a text editor. Look for the following line:

<target path="/daisy/jmsclient/jmsclient">

and replace the content of the <configuration> element following it with the following, but be sure to keep the old password on the credentials element:

<configuration>
  <jmsConnection>
    <credentials username="admin" password="openjms"/>
    <initialContext>
      <property name="java.naming.provider.url" value="tcp://localhost:3035/"/>
      <property name="java.naming.factory.initial"
                value="org.exolab.jms.jndi.InitialContextFactory"/>
    </initialContext>
    <topicConnectionFactoryName>TCPTopicConnectionFactory</topicConnectionFactoryName>
    <queueConnectionFactoryName>TCPQueueConnectionFactory</queueConnectionFactoryName>
  </jmsConnection>
</configuration>

Copy over the old configuration

Copy <OLD_DAISY_HOME>/daisywiki/webapp/daisy/sites/* to <NEW_DAISY_HOME>/daisywiki/webapp/daisy/sites
In <NEW_DAISY_HOME>/daisywiki/webapp/WEB-INF/cocoon.xconf, adjust the following passwords with the values you can find in <OLD_DAISY_HOME>/daisywiki/webapp/WEB-INF/cocoon.xconf:
- Adjust the password for openjms user (if not left to default): <credentials password="openjms" username="admin"/>
- Adjust the password for "internal' user: <cacheUser login="internal" password="defaultpwd"/>
- Adjust the password for the "registrar" user: <registrarUser login="registrar" password="defaultpwd"/>
If you created any document type-specific stylesheets, you can copy them over also
If you developed a custom skin, then you'll have to update it to work with the new version. There's no easy or quick way to do this.

Edit <DAISY_HOME>/openjms/bin/setenv.(sh|bat), uncomment the line defining the CLASSPATH and put the MySQL driver in the CLASSPATH, which can be found at (substitute DAISY_HOME by its actual location):

DAISY_HOME/lib/mysql/jars/mysql-connector-java-3.0.15-ga-bin.jar

Update siteconf.xml files

This step is only needed if you did not use the "default" language when upgrading your database (thus if you adjusted the language in the daisy-1_2-to-1_3_M1.sql file).

Edit all your siteconf.xml files, thus those found in <NEW_DAISY_HOME>/daisywiki/webapp/daisy/sites/<sitename>/siteconf.xml

In each file, add the following element somewhere as child of the root element:

<language>your_language</language>

for example:

<language>en</language>

Erase Full Text Indexer files

Because of the introduction of the document variants feature, the format of the full text index files has changed. Therefore, delete all the files in the directory <DAISY_DATA>/indexstore.

Start the servers

Start OpenJMS, the Daisy Repository Server, and the Daisy Wiki.

If necessary, first update the DAISY_HOME and OPENJMS_HOME variables to point to the location of the new Daisy version.

Trigger full text index updating

Recreating the full text index can be done via the JMX console. Open a webbrowser and surf to http://localhost:9264.

If this prompts for a password and you don't know it, look in the file <DAISY_DATA>/conf/myconfig.xml for a line like:

<httpAdaptor authenticationMethod="none" host="localhost"
             password="daisyjmx" port="9264" username="daisyjmx"/>

and use the username and password mentioned there.

By default, the JMX console only allows connection from localhost. Change the host attribute on the above configuration element if needed. You need to restart the Daisy Repository Server for this change to take effect.

In the JMX web interface, follow the link that says "Daisy:name=FullTextIndexUpdater". Then press the Invoke button on the line that starts with "reIndexAllDocuments". Press this button only once, depending on the number of documents you have this can take a little while.

Note about static resources and caching

Since static resources are cached for about 5 hours by your browser, you might need to do a full reload (shift + reload button on the browsers' toolbar). Also when opening the editor for the first time do a shift + reload.

If these instructions or unclear to you, or if you find an error in them, please share them with us on the Daisy mailing list or by leaving a comment.

Comments (0)