Hula is a Java client API to the [WikiRPCInterface]. This allows one to programmatically manipulate the content of a Wiki that implements this interface. Hula is distributed under the [GNU General Public License|http://www.gnu.org/licenses/gpl.html]




%%tabbedSection
%%tab-Existing Applications
*The [EmailGenerator], which sends out daily notices of changes to a Wiki. You can sign up for such emails at [NotificationList].
*Creating the seed data for the animated Wiki visualization tool, see [TouchGraphWikiBrowser].
*Amalgamating pages together into a single printable or PDA-snarfable page ([PrintWiki]). Running examples using JSPWiki are available at [http://www.mahlen.org/jspwiki] and [http://www.mahlen.org/jspwiki/TOCstart.jsp].

%%
%%tab-Download
The latest version of Hula is attached. The ''full'' version supplies all the outside libraries used, ''nolibs'' doesn't. Source, classes, and javadocs are included in both.

You can also download the latest set of sources using CVS:

{{{
cvs -d anonymous@cvs.jspwiki.org:/p/cvs co Hula
}}}

%%
%%tab-Usage
*Forgive me if I'm being a bit dense here, but how does one activate the EmailGenerator to read the NotificationList page?  From the *.sh file?   From within another Wiki page?  Is it automatic after the initial activation?  -- JoshuaBecker
** Modify the emailgenerator.properties file and run the emailgenerator.sh/.bat script. It's a script that keeps running eternally, doing this work. Primitive, I know. I really should add some documentation. Sorry. -- [MahlenMorris]

* It took me 15 minutes to get Hula wrapped as a Windows Service using the awesome [Java Service Wrapper|http://wrapper.tanukisoftware.org/doc/english/introduction.html]. I used the simple integration model described [here|http://wrapper.tanukisoftware.org/doc/english/integrate-simple-win.html] (and yes, it is open source).\\
 -- [NascifAbousalhNeto], 15-Nov-2006
 
*I tried installing this on my wiki and got the following stack trace error after running ./emailgenerator.sh:
propFile = emailgenerator.properties
Attempting to contact Wiki Server at 'http://www.mydomain.net/mywiki/'...
Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/commons/codec/DecoderException
    at org.apache.xmlrpc.XmlRpc.createTypeFactory(XmlRpc.java:235)
    at org.apache.xmlrpc.XmlRpc.<init>(XmlRpc.java:190)
    at org.apache.xmlrpc.XmlRpcClientResponseProcessor.<init>(XmlRpcClientResponseProcessor.java:49)
    at org.apache.xmlrpc.XmlRpcClientWorker.<init>(XmlRpcClientWorker.java:44)
    at org.apache.xmlrpc.XmlRpcClient.getWorker(XmlRpcClient.java:351)
    at org.apache.xmlrpc.XmlRpcClient.execute(XmlRpcClient.java:191)
    at org.apache.xmlrpc.XmlRpcClient.execute(XmlRpcClient.java:185)
    at org.apache.xmlrpc.XmlRpcClient.execute(XmlRpcClient.java:178)
    at org.mahlen.hula.rpcclient.RPCClient.getRPCVersionSupported(RPCClient.java:107)
    at org.mahlen.hula.rpcclient.RPCClient.checkConnect(RPCClient.java:83)
    at org.mahlen.hula.rpcclient.RPCClient.<init>(RPCClient.java:69)
    at org.mahlen.hula.apps.EmailGenerator.<init>(EmailGenerator.java:202)
    at org.mahlen.hula.apps.EmailGenerator.main(EmailGenerator.java:123)

Does anybody have any insight as to why this might be happening?

I have used common-codec-*.jar and it works fine for this solution.

%%
%%tab-Dependencies
Different bits of the sample applications require different libraries. The .zip file with 'full' in the name supplies these libraries.
*Everything requires ''xmlrpc.jar'', which can be found at [http://xml.apache.org/xmlrpc/] and ''jakarta-oro.jar'', found at [http://jakarta.apache.org/oro/index.html].
*The [EmailGenerator] application needs ''activation.jar'' and ''mail.jar'', from [http://java.sun.com/products/javabeans/glasgow/jaf.html] and [http://java.sun.com/products/javamail/], respectively. That's how it sends emails.
Xmlrpc.jar and jakarta-oro.jar are also found in the [JSPWiki 1.7.0 download|JSPWikiDownload]. And, as I said, they are all provided in the ''full'' version of the .zip file.

%%
%%tab-News
----
[JanneJalkanen]: This project has been imported into CVS tree at cvs.jspwiki.org.  A new release is forthcoming.

[MahlenMorris]: Version 2003-12-14 is now out:
*Fix to RPCClient to deal with possible memory leak in XmlRpcClient. I'm not certain what the deal is, but it looks like XmlRpcClient can hold onto great gobs of memory when called several times, eventually crashing the JVM. My solution is for RPCClient to create a new XmlRpcClient each time it does a call, which seems to work much better. 
*Added TOC (Table of Contents) concept to both LinkUtil and EmailGenerator, making it possible to select a group of pages that are pointed to by another page.
*Also added author exclusion to EmailGenerator.
*Now create and use hula.jar, not hula.zip (thank you for that suggestion, [AlexMcLintock]).
*Added TOCstart.jsp and TOCshow.jsp as demos of TOC printing.

[MahlenMorris]: Version 2002-12-24 is now out:
*I think I fixed a bug I discovered such that if EmailGenerator is running on a slower machine that was causing it to skip hours occasionally. I think that Thread.sleep() can get more inaccurate on slower machines.
*Made EmailGenerator more robust in circumstances when the XML-RPC server is unavailable for a long time, due to downtime or network problems.
*Now EmailGenerator can be called with a command line argument that is the name of the .properties to read for instructions, instead of always using emailgenerator.properties (it will default to emailgenerator.properties if not specified). This means that you can name the properties 'foo.properties', and installing a new version of Hula over the previous one won't affect it.

;:''You know, I was wondering a bit about the skipped hours... But I never managed to get into checking if the fault was in my [XML-RPC] code or where :-).  --[JanneJalkanen]''

----
[MahlenMorris]: Version 2002-05-19 is now out:
*Grrrr. Bug in EmailGenerator was causing it to skip checking every other hour.  These Stupid Pills I've been taking are way too strong :0
----
[MahlenMorris]: Version 2002-05-18 is now out:
*Whoops! NPE in interveningPages() if the page is new. Fixed.
*Fixed crash if server is down for over an hour.
----
[MahlenMorris]: Version 2002-05-17 is now out:
*EmailGenerator now mentions who made the changes described on the page. PageInfo now has a interveningAuthors() method to support this.
*I've included the [PrintWiki] *.jsp pages. Look in the __apps__ directory. You'll have to edit them yourselves to point them to other Wikis, and you'll likely want to edit the introductory text.
*I've dropped the useless RPCClient argument from VersionUtil.diff().
*Fixed a couple little bugs in PrintWiki.assemble().
*The current state of the [Hoop] code is included, mainly because my build included it automatically. Don't use it for anything.
----
[MahlenMorris]: Version 2002-04-20 is now out:
*I've given up on version numbers for the time being, as they have become increasingly non-sensical.
*EmailGenerator:
**Added text justification width as a new property ''message.justify''. Default is 72 characters long; if the property is missing, no justification will be done.
**Added ability for users to specify that when a page has changed, send the whole page in the email, not just the delta. Can apply to an individual page or to RecentChanges. Property ''entry.wholepageindicator'' lets the email administrator pick the string that decides this; current default is ''!''.
**At startup will mention the Wiki server it's trying to contact.
** ''Seems to be working nicely.  Preformatted text (stuff between 3x{ and 3x}) seems to lose its indentations, but solving that would require parsing of the input. --[JanneJalkanen]''
** ''Check also a new application at [TouchGraphWikiBrowser].''
---- 
[MahlenMorris]: Version 0.7.4 is now out:
*PageInfo has methods for getting raw text and HTML.
*EmailGenerator has property so that default time zone can be local time.
*In EmailGenerator, ''-pagename'' means changes to that page(s) won't be shown.

''Hey, the last one is a cool feature I was just going to ask you for...  You read my mind :-)  --[JanneJalkanen]''

----
[MahlenMorris]: Version 0.7.3 is now in place:
*PrintWiki.assemble() can now be used with Wiki's other than this one :)
*RPCClient now uses ORO's CacheLRU to cache recently used PageInfo's and raw page text. So there's value in keeping RPCClient's around, as the caching can make retrieval significantly faster.
----
[MahlenMorris]: Version 0.7.1 is now out:
*The .zip file is now better organized. You can just unzip the 'full' version and run it.
*There are scripts for running the email generator (modify the properties file first!). ''Please test the .sh version and inform me of its flaws; I don't have a Unix box to try it on.''
*[EmailGenerator] is now more robust when communications with the Wiki XML-RPC server fails. If any exception occurs when trying to put together the email, EmailGenerator should sleep 3 minutes and then try again.
*The thread doesn't sleep for as long between emails, so the email should be sent within a minute of the hour designated. ''Really, though, I should just be calculating how long to sleep. Describing the behavior of my code always makes me aware of its flaws.''
----
[MahlenMorris]: Version 0.7 of Hula is now available at [http://www.mahlen.org/hula/0.7]. I believe that this version fully supports the JSPWiki 1.7.0 base-64 XML-RPC API. Improvements from 0.6 include:
*[EmailGenerator] now has an emailgenerator.properties file, where connection info and so forth can be specified. A sample is available in the hula-config.zip file. The emailgenerator.properties file should be in the current directory when EmailGenerator is started. It is re-read each hour, so that you can tweak the format of the emails or what have you without stopping the program.
*[EmailGenerator] now doesn't halt when the server is unavailable.
*The LinkUtil class is now more useful. I'm working on an application that uses  it.
*listLinks now supports 1.7.0 method.
*Janne's superior UTC<->Local conversion technique is now used.
*Whatever other random dumbness i noticed.

It's 1:30 in the morning here in California as I post this, so any bugs wouldn't be a surprise :). But I'd still like to hear about them below.
----
[MahlenMorris]: Version 0.6 is available at [http://www.mahlen.org/hula/0.6]. Much cleaner code, a few new methods, and it can autodetermine the time zone (which is now in milliseconds). Plus there's now code for diffing between different versions of a page; it's being used in the Email code for [NotificationList]. Completely incompatible with version 0.5, by the way, the packages have all changed.

As you may observe, I'm toying with the name __Hula__ for this project. 

The email generation code used for [NotificationList] is also now included.

All comments welcome.
----
[I|MahlenMorris] have created a little Java class library that makes it easier to write clients that connect to the [WikiRPCInterface]. It's currently at the rather arbitrary version number of 0.5. It's compatible with the 1.6.12-beta of the server. It relies on the [Apache XML-RPC|http://xml.apache.org/xmlrpc/] class library.

Also included is the PrintWiki class that's doing the work of merging the pages on [this page|http://www.mahlen.org/jspwiki/]. It's not very sophisticated, and currently works strictly with this Wiki site.  (on Feb 28 2003 the mahlen.org page linked above was returning a 500 servlet exception.)

%%
%%tab-Discussion

This is quite cool, I have to admit :-).

Note that the XML-RPC API changed a bit in 1.7.0.  Any chances in getting the changes reflected in the RPCClient code?  I'd love to install this on an other Wiki site I'm running... --[JanneJalkanen]

What changes have I missed, Janne? The only ones i know of are:
*UTF-8 support. Not sure i need this, since I'm doing all the conversions already.
*listLinks changes. I have updated code for this, I just haven't pushed out a new version yet. ''Done.''
*Your improved time-zone-figuring-out-code. Will fold it in soon. ''Done.''

Otherwise, as far as I know, the code i have is working fine against 1.7.0. Mind you, I have a long list of things I'd like to add, but no other compatibility issues. What am I unaware of? --[MahlenMorris]

[JanneJalkanen]: I was referring to the listLinks changes, especially the fact that we're now using strings to denote the link type instead of integers.  But if you've already updated it, then I have nothing to worry about :-).  Anyway, the API should be stable now, i.e. I'll add to it, but I won't change it unless I really, really have to...
----
Do you still have to make the link parsing JSPWiki-specific?  Isn't the plain HREF enough?  I'm referring to version 0.7.1. --[JanneJalkanen]

I'm presuming you're talking about the PrintWiki class. I haven't put any time into that lately (I've been polishing EmailGenerator), so it hasn't been updated to use listLinks(). But if someone's actually going to use it, I'll try to sharpen it up. -- [MahlenMorris]

Janne, does 0.7.3 do the trick? -- [MahlenMorris]

''It would seem so.''

[MahlenMorris]: Actually, it may not exactly work. I noticed today that you've changed the currently running JSPWiki back to link HREF's with fully qualified links (with http://www.ecyrd...) instead of the relative links you had a while ago, which I wasn't expecting. This has the effect of making links to pages outside of the current set not work correctly. If you're just printing the page or moving it to some object where those links don't matter, then this bug on my part is not an issue. I've fixed it in the code, and it will be in the next release.

But now I'm curious, Janne, what are you using/planning to use it for, may I ask?

[JanneJalkanen]: Well, isn't it just about doing a simple search-replace operation when link type is "internal"?  Whether we give out the full link or not depends on whether the jspwiki.baseURL has been set in jspwiki.properties or not.  This is required for the [RSS feed for JSPWiki] to work, since it has no implicit concept of an originating server.

As for what I was going to use it for... Well, I have some wacky ideas brewing in my mind.  Also, I want to make sure that the RPC API does not limit you to JSPWiki only (even though there are quite few Wikis that support it so far).

[MahlenMorris]: My fix for the above bug is that it checks the href of an internal link, and only prepends the baseURL if the href doesn't start with "http://". Before it was always prepending the baseURL. Bad assumption on my part.

And i as well am trying to make sure the Hula apps work across WikiEngines. Along those lines, [Hoop] is progressing, albeit slowly (cursed real life!)
I hope to release the .jsp files for the page selector in the next release.

----

I also use the eMail-notification of changes to keep up with changes in this Wiki. Great work, thanks! 

Two things would make it even better though:

* having a few lines of context (like in diff -u format)
* breaking long lines at some reasonable limit preserving the initial '>' and '<' characters

[MahlenMorris]: Those are both good ideas, Torsten. I'll have to rub my chin over them, so as to make it appear that I'm thinking hard :)

----

*[JimMcNealy] I'm having trouble with emailgenerator on a intranet where authentication is required. Is there a version of emailgenerator that uses authentication?
*[AlexMcLintock] I would really like to print out my Wiki in a "tree-like" fashion - printing the Main page, then the pages linked from there, and then the pages linked from each of those pages in turn. I guess we could try breadth or depth first. 
However I don't see how to use the XML-RPC interface to control this.
**[MahlenMorris] Try the new TOCstart.jsp page and look at the code it calls.

----

I have downloaded Hula plugin, but i dont know how to use it. Can you explain in detail please.

--[Murali Krishna|mailto:murali_chanda@yahoo.co.in], 10-Jul-2006

----
[Leo Hart] Is hula still supported?  When I tried following the install directions I get a "WARN:oejd.DeploymentManager:Unable to reach node goal: started java.lang.NoSuchMethodError: com.ecyrd.jspwiki.TextUtil.createProperties([Ljava/lang/String;)Ljava/util/Properties; at com.ecyrd.jspwiki.PropertyReader.getDefaultProperties(PropertyReader.java:189)" error on wiki startup.
--[Leo Hart|mailto:leo.hart@fmr.com], 10-Jul-2012

----
%%
%%