Contents:

The Objects (API)
The Database Structure
Installation and Configuration
Setting Up Users
Creating and Managing Threads and Entries
Retrieving Threads and Entries
Designing Visual Interfaces

The Objects (API):

blog has 6 objects, three of which represent the journal components (threads, entries and users), two which actually interact with the database and perform functions on the journal (adding, deleting and viewing) and one exception object.

Objects:

blogThread - Contains thread data.
blogEntry - Contains entry data.
blogUser - Contains user data and manages authentication and access rights checking.
blogAdmin - Creates and deletes threads and entries and manages users.
blogView - Reads from the journal and retrieves the threads and entries.
blogException - Thrown from blogAdmin, blogView and blogUser to show error.

Refer to the API javadocs for more an in-depth explanation of the API.

The Database Structure:

blog requires a SQL-based database to store the journal in. Their must also be a JDBC driver for this database format that can be used with blog. Both the JDBC driver class name (e.g. org.gjt.mm.mysql.Driver) and the connection string to the database (specific to the JDBC driver) are stored in the preferences file (pref.xml) that comes with blog. The database must have a very specific format in order to work with blog. I have created a set of utilities designed to make setting up blog easier, one of these tools initBlog will create the tables in your database for you.

The database is structured as such:

Installation and Configuration:

Installation and configuration of blog is fairly simple, so don't fear. After downloading and unpacking the compressed download file into the folder where you want to store blog there are a few steps you must take before using blog.

First add blog.jar and nb.jar files (blog requires another package NOT distributed with it, the JCE) to your classpath of your servlet container. Next, you must create an database for blog (NOTE: if you are already using blog, you will have to hand edit the database structure so as not to overwrite your journal). Next, make sure you have also downloaded the blog utilities (KeyGen, initBlog), and run both of them (they have their own documentation).

Next, you need to edit your preferences file (pref.xml is included in the blog distribution). Alter the file so that it reflects your preferences where applicable. You must specify what JDBC driver class you are using, what connection string connects to your journal database, what file your private encryption key (you probably ran KeyGen to create this) is in, and what your administrative user name is (default to user - that's what initBlog sets it to).

Setting Up Users:

Version 1.2 of blog introduces user authentication and access rights. There is one root user who has *god-like* privleges and is the only user who can set up new users and groups. This user (specified in the preferences file) must login to blog by creating a blogUser instance using your root account, (simply constructing this object authenticates you).

blogUser user = new blogUser(username, password, path_to_preference_file)

Then create a blogAdmin instance and call createGroup() and createUser() to set up group and user accounts, respectively.

blogAdmin admin = new blogAdmin(user, path_to_preferences_file)
admin.createGroup(groupname);
admin.createUser(username, password, groupname);

Any user with an account in blog has the capability to create threads, and view/write entries for those which they have either created, or are part of a group which has been given access to them. To give a group access to a thread the root user must call setGroupRights() in blogAdmin and specify with a predefined flag what rights that group will have. The rights are RIGHT_READ and RIGHT_READ_WRITE.

admin.setGroupRights(groupID, threadID, rightsFlag);

When blogView is used to return threads or their entries, they will only receive records for which they have rights to. The same applies to using blogAdmin to add entries to threads, or to delete threads or entries.

Creating and Managing Threads and Entries:

All interaction involving changes to your journal takes place using blogAdmin. Login to blogAdmin as any user by creating a blogUser object (you are automatically authenticated by constructing the object) and passing it to a new blogAdmin object.

blogUser user = new blogUser(username, password, path_to_preferences_file);
blogAdmin admin = new blogAdmin(user, path_to_preferences_file);

To create a new thread (which any user with an account can do), call createThread() and pass a new blogThread object to it containing the data you wish to add. Note that because blog version q.2 has the ability to nest threads within threads you must either specify a parent thread, or set the parent argument to zero to specify that it is a top-level thread.

admin.createThread(new blogThread(0, parent_threadID_or_zero, title, ""));

To create a new entry (which only users with access to the parent thread can do) call createEntry() and pass it a new blogEntry object contaning the data you wish to add.

admin.createEntry(new blogEntry(parent_threadID, 0, name, author, new java.util.Date().toString(), content));

To remove an entry (which only users with access to the parent thread can do) simply call deleteEntry() and pass it the entryID of whichever entry you wish to delete and the threadID of its parent.

admin.deleteEntry(entryID, threadID);

To delete a thread and all of its children call deleteThread() and pass it the threadID of whichever thread you wish to delete.

admin.deleteThread(threadID);

Retrieving Threads and Entries:

All interaction involving the retrieval of a thread or entry is accomplished through blogView. Each call to a blogView function involves a database interaction, so use them judiciously. With both threads and entries, you have two retrieval options, you can return a specific thread or entry or an array of all threads or all entries which are children of the thread you specify (NOTE: to retrieve the top-level threads set the threadID to zero). First login to blog by creating a blogUser instance (constructing the object authenticates you) and pass it to a new blogView instance.

blogUser user = new blogUser(username, password, path_to_preferences_file);
blogView view = new blogView(user, path_to_preferences_file);

To retrieve a specific thread call getThread and pass it the threadID of the thread you want.

blogThread thread = view.getThread(threadID);

To retrieve a specific entry call getEntry and pass it the entryID of the entry you want.

blogEntry entry = view.getEntry(entryID);

To retrieve an array of all threads whose parent is <threadID> call getAllThreads and pass it the threadID of the parent thread.

blogThread threads[] = view.getAllThreads(threadID);

To retrieve an array of all entries whose parent is <threadID> call getAllEntries and pass it the threadID of the parent thread.

blogEntry entries[] = view.getAllEntries(threadID);

Designing Visual Interfaces:

blog is only a set of interfaces (API), not a means of displaying the journal data, that has been left up to your tastes. However, there are a couple of ways to design these interfaces which may make the job simpler (or harder if you don't like JSP). Because blog is written in Java, there are a limited number of ways to retrieving the journal data (all of them also using Java). JSP (Java Server Pages) is a relatively new technology that is very good at manipulating data for design on-the-fly. JSP are java servlets that have been written (like ASP - Active Server Pages or CFML - Cold Fusion Markup Language) into the HTML outputed pages. A servlet container (like Tomcat) parses the JSP into servlets and generates the HTML that is then sent to the user's browser. This all happens on the web server so the user needs no special software other than a basic web browser. JSP is an easy technology to learn, but the application server can be a bit of a pain to configure. If this is not your problem, but your webmaster's, then all the better for you.

To display the journal data, you need some sort of design scheme that appropriately takes advantage of blog's heirarchichal nature. Probably the best way to display the data is according to it's nature structure, threads grouped together with a means of visually traversing into a specific thread's list of entries (one thread at a time). Then from there, the user can view the content of the entries as he or she desires by again traversing into a specific entry.

Here is a sample JSP that shows all threads:

Here is a sample JSP that shows a thread's entries:

Obviously, the design is not sufficent for any real application, but you get the idea.