About Fisherman

Fisherman is a system for managing and monitoring the sustainable exploitation of wild or communally owned natural resources, such as fish, shellfish, wild game, timber or firewood. Originally developed for and modelled on the Solway Shellfish Management Association, which manages extraction of shellfish from the Scottish shore of the Solway Firth, Fisherman is widely applicable to situations where a natural resource is sustainably managed.

General concepts and framework

Fisherman is based on the concept that people entitled to exploit the resource apply for and are issued with licences. Each licence is valid for a season and carries a certain quota; there may be different classes of licence with different quota. Within a season, each licencee may purchase tags from the licencing authority up to the amount of their quota. Licencees must attach a tag to each unit of resource extracted. Licencees may not reuse a tag, nor resell one to anyone else. A licencee who breaks the terms of the licence may have the licence revoked.

In the terminology of the system:

The licencing authority: Is the body responsible for managing the extraction of the resource. It may be anything from a government agency to an informal association of resource users.
An inspector: Is an agent of the licencing authority empowered to inspect licences and tags in the field.
A licencee: Is simply someone permitted to exploit the resource. The licencee is typically issued with, in addition to a licence, an identifying badge which may be barcoded or RFID'd with the licencee's person number.
A licence: Is simply a permit to extract a certain quota of the resource within a given season. A charge may or may not be made by the licencing authority for the licence.
A tag: Is something which can be used to identify a unit of extracted resource. It bears an identifying number, and possibly a bar-code or RFID chip to allow that number to be read automatically. In the case of shellfish, the tag is marked on the side of a standard sized bag in which catch can be landed. Tags are purchased from the licencing authority by licencees against their quota for the season; once they have reached their quota they may not purchase any more tags.

For this scheme to operate, the licencing authority must have means to inspect resources as they are extracted and to record the tags used. This need only be a random check; it is not necessary to inspect every unit of resource extracted, provided inspection is frequent enough to detect either units of resource extracted without being tagged (e.g., shellfish landed in bags other than the special tagged bags), or tags being reused or used by a person other than the licencee to whom they were issued.

Requiring the licencees to log each tag used is helpful but not necessary.

Customisation

In order to be flexible enough to manage the exploitation of a wide range of different resources, Fisherman is highly configurable.

Types of licence: The types of licence which may be issued is configurable. Arbitrarily many types of licence may be used. Each type of licence may have a different quota. Every licence, however, is valid for one season; if different periods of validity were required changes would have to be made to the underlying software.
Types of taggable: The types of things which may be tagged is configurable. Arbitrarily many may be defined. However, currently, each tag has the same value; if different values of tag were required (e.g. a tag for a 10Kg bag, a tag for a 25Kg bag), changes would have to be made to the underlying software.
Workflow: The workflow for issuing, monitoring and revoking of licences is fully customisable by defining licence statuses, states a licence may be in (e.g. applied for, checked, granted, under warning, revoked), and actions which move a licence from one status to another.

Dependencies

Fisherman is shipped with, and depends upon, the following packages:


Package	Source	Version	Licence	Provides
Jacquard	http://www.journeyman.cc/weft/library/jacquard/	1.10.16	BSD	forms, widgets and database abstraction layer
jTDS	http://jtds.sourceforge.net/	1.0.3	LGPL	Database driver for MS SQL Server databases (not recommended)
Postgresql-jdbc3	http://www.postgresql.org/	8.1	BSD	Database driver for Postgres databases (recommended)
Apache regexp	http://jakarta.apache.org/regexp/	1.4	Apache	Regular expression matching

In addition, Fisherman requires a RDBMS to handle the data and to ensure data integrity. While database definitions are provided to allow either Oracle or MS SQL Server to be used, we develop with and strongly recommend Postgres, version 7 or later. Fisherman is implemented as a Java webapp conforming to the Servlet 2.2 specification, and requires a conformant Servlet container. While in principle any conformant servlet container will do, we develop with and recommend Apache Tomcat, version 4.1 or later.

User Documentation

This documentation is primarily aimed at people modifying or maintaining the system.

Copyright and Licence

Fisherman is copyright (c) 2006 Simon Brooke t/a the Web Engineering Factory and Toolworks. It is licenced under the GNU General Public Licence as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Hosted at SourceForge.

Getting and building the source

You can download source distribution bundles of Fisherman from here. Fisherman is developed with eclipse and built with ant. To build the source, untar the distribution, connect to the distribution directory,.and just run

ant installer

This will build the installer which should be identical to the one you can download from SourceForge

Contributing and Taking Part

I would welcome active collaborators in developing Fisherman further. If you'd like to join in, the project page is here.

Configuring andInstalling

These instructions assume you're running Tomcat version 5 and Postgres version 7. If you're running a different servlet container and/or database engine, you may find things are slightly more complex, but you should be able to work it out.

To install Fisherman, you should first set up your database by typing

createdb databasename

at the command line on the machine on which you're running Postgres, where databasename is the name you choose for the database.

Then download the installer from here; then run the installer, either by selecting its icon or by running

java -jar fisherman-major-version.minor-version-installer.jar

and answering all the questions.

If you request the installer to initialise the database it will set up the appropriate tables and data. If you encounter a problem go on to What to do if the database install script fails, below. Once the database installation is completed (again, it may take a few seconds) you should be able to try

http://your.host.name:8080/fisherman/

Your Fisherman system is now installed. Log in to administer it (use the username and password that you typed into the installer).

That's it! You're up and running. Enjoy!

Things which could go wrong

What to do if you can't connect to the database

You must create a database to hold Fisherman's data. It does not matter what this database is called, but it must be accessible via JDBC. This discussion assumes you will use Postgres. You don't have to use Postgres; in principle Fisherman should work with any database engine which supports views and transactions and which is accessible via JDBC. It should be fairly easy to get Fisherman working with Oracle, somewhat less easy with MS SQL Server. With other databases you're on your own.

Firstly, you must ensure that Postgres is listening on a port, usually 5432. The simplest way to do this is to run the postmaster with the -i flag (see the postmaster man page). However, many packaged postgres installations nowadays have configuration files to control this sort of thing so you should check the configuration files of your particular installation. You must also allow your database to be connected to from the machine which runs the servlet container. Note that the database engine does not need to be running on the same server as the servlet container, but bear in mind that JDBC connections pass passwords over unencrypted network connections so if they are not on the same machine you need to be confident that the network between them cannot be snooped. To allow connections over the network, you need to edit the pg_hba.conf configuration file of your postgres installation, to add a line like:

host fisherman 192.168.4.72 255.255.255.248 password

where

host is a keyword and must be 'host'
Fisherman is the name of your database, whatever you have called it
192.168.1.72 is the IP address of the machine or network from which connections will be accepted
255.255.255.248 is the netmask which defines what part of that address is significant
password is a keyword and must be just 'password'

So this example would allow the subnet consisting of the six machines from 192.168.1.73 to 192.168.1.78 to connect. To test that you have configured this correctly, first run

createdb fisherman

on the machine on which postgres is running to create the database. Then, from the machine which runs your servlet engine, run

psql -h database.machine.address -i 5432 fisherman

where

database.machine.address is the IP address or a valid DNS name of your database machine
5432 is the port on which that machine listens for postgres connections
Fisherman is the name of the database you have created.

If this call succeeds and you get the database prompt your database is set up correctly. If it isn't, sort it out before going on to the next stage.

Special note it you're using Oracle

We do not ship Oracle JDBC drivers with Fisherman for copyright reasons. To install them, after the war file has been unpacked, drop the Oracle JDBC driver archive file which came with your Oracle installation into appname/WEB-INF/lib, where appname is the name you gave the Fisherman web application.

What to do if the database install script fails

The database install script, called if you request it in the installer, can fail. It will fail if

There is already a group called 'appnameadmins'' or a group called 'appnameinspectors' known to your database system, where appname is the name you gave to the Fisherman webapp
There is already a user with the username you set up for Administrator's username
You don't have sufficient privilege to create users, groups, tables, views, indexes or constraints on your database system

Don't panic, this is not a disaster. The script which the database is setup from will be found in the unpacked war file.

for Postgres 7, the script will be found in appname/WEB-INF/pgsql7.sql
for MS SQL Server 2K and subsequent, the script will be found in appname/WEB-INF/mssql2k.sql
for Oracle 8 and subsequent, the script will be found in appname/WEB-INF/oracle8.sql

in each case where appname is the name you gave to the Fisherman web application. Using either the database engine's interactive command line tool (e.g. psql, Query Analyser, sqldba) or use a JDBC tool such as SQL Workbench/J, copy and paste individual SQL statements from the database script in turn and run them against the database. Note where one fails and fix the problem before going on to the next.

What to do if the WAR didn't unpack

In order to maintain store uploaded attachments and images, Fisherman needs the servlet container in which it is run to unpack the WAR file. The servlet specification doesn't require this - it's optional. Tomcat 5.0.24 does unpack war files by default, but some versions of Tomcat 4 don't, and the copy you have may have been configured differently in any case.

The simplest thing to do if you have this problem (the symptom is you can't get the contactnote servlet to work), is to unpack the war file by hand. Go to the directory into which the war file has been put, and create a new subdirectory with the same base name as the war file (i.e., if the war file is called fisherman.war the directory should be called fisherman). Unpack the contents of the war file into that directory using either the jar utility, or any zip unpacking tool such as winzip or ark. If you do this you should ensure that the directory you created and all of its contents are owned by the user which your servlet engine runs as.

If you want to configure Tomcat, either version 4 or version 5, to automatically unpack war files, you can edit the server.xml configuration file, and find the host element for the virtual host your Fisherman system will run in. you must set its unpackWARs attribute to true.

<Host name="your.server.name" debug="0"

appBase="webapps" unpackWARs="true">

If you are in doubt which virtual host is appropriate, there should be no harm in setting unpackWARs to true for all of them. If you are not the administrator of your Tomcat installation you may have to ask the system administrator to do this.

Alternatively, in later versions of Tomcat 4 and in Tomcat 5, you can use the Tomcat Web Server Administration Tool. In the tool, click on the host icon for the appropriate host entry in the tree view (unless you are doing something quite complex, there will only be one host entry). Set 'Unpack Wars' to 'True' and click 'Save'. Then click 'Commit Changes'.

If you don't run Tomcat, of course, you must configure the servlet container you do run to unpack war files. I don't know of any servlet containers which won't allow you to unpack war files. If you have one then at present you can't run Fisherman.

Enquiries and support

If you need support getting Fisherman running please feel free to contact me.

Reporting Bugs

If you find bugs in Fisherman, or have suggestions for improvements or new features, you can use this form.

[Web Engineering] Copyright © 2004 Simon Brooke trading as the Web Engineering Factory and Toolworks
This document fisherman/project_web_site/index.html $Revision: 1.3 $ $Date:2006-08-01$ $Author: simon_brooke $

Now hosted at SourceForge.