Freelib 1.0 ------------ Digital Library group at Old Dominion University Project Website: http://p2pdl.cs.odu.edu/ Group Website: http://dlib.cs.odu.edu/ Contact: p2pdl@list.odu.edu 1. Introduction: ---------------- Freelib is digital library framework based on peer-to-peer. Every participating node maintains a small collection and makes it available to other nodes. Every Freelib node keeps track of peers that share the same interest as the node. This is done by analyzing the mutual access patterns between the node and its peers. Every node has a small server that listens to requests. A request could be a search request, access (download) request, join request, leave request, etc. Every node makes its local collection available to other nodes by responding to the search requests with a list of relevant items it has and responding to download requests that ask for items in its collection. 2. System requirements: ----------------------- To build Freelib, you need to have the following software installed on your machine: - JDK 1.5.0 or later - Apache Ant To run Freelib you need to have the following software installed and configured on your machine. - JDK 1.5.0 or later To download and install JDK 1.5.x, go to http://java.sun.com/ To download and install Apache Ant, go to http://ant.apache.org/ 3. Installation Instructions: ------------------------------ - Downloading the package from http://p2pdl.cs.odu.edu/ - Unzip it to your hard drive - This creates the folder freelib1.0 4. The package structure: ------------------------- The distribution package has the following directory structure: freelib1.0 Root directory dist Contains the compiled code and the supporting files help Contains help files image Contains images for logo, buttons, etc. info The client saves data, metadata, and config info here conf Contains the configuration information data Contains the data, metadata, and indexes log Contains the access information lib Contains the jar files prj Contains the ant script src Contains the source code Readme.txt This Readme file freelib.bat Batch file for running Freelib on windows platforms freelib.sh Shell script for running Freelib on Unix and Linux platforms 5. Compiling and running Freelib: ---------------------------------- To build Freelib: > cd prj > ant -buildfile build.xml dist To run a Freelib client on Windows platforms: > cd freelib1.0 > freelib To run a Freelib client on Unix/Linux platforms: > cd freelib1.0 > sh freelib.sh 6. Starting Freelib: --------------------- - Open a terminal (command window) - Change directory to the extracted folder > cd freelib1.0 - For MS Windows Enter the command: > freelib - For Unix/Linux Enter the command: > sh freelib.sh 7. Joining an existing network: ------------------------------- In order to join an existing Freelib network: - Start your Freelib client - Click the button Settings on the main interface - In the initial contacts area, enter the IP and the port number of some node that is already connected to the network. That node serves as a Network Entry Point (NEP) for you to connect to the network. Consult the Website of your Freelib network for a list of NEPs. - Click the button OK to save the changes - On the main interface, click the button Connect to join the network. Once you are connected, the Connect button is replaced with a Disconnect button that you may click at any time to disconnect from the network. 8. Starting your own Freelib peer-to-peer network: --------------------------------------------------- In order to build a Freelib peer-to-peer network, you need to start a seed node. When a seed node starts, it forms a freelib network of one node. It follows a special join protocol. To enable other users to join the network, you need to make the host name (or the IP) and the port number of one or more online nodes available to the users. We call those nodes the Network Entry Points (NEP), or just Entry Points for short. The IP and Port information is typically published on a web site. You may use the seed node as a NEP, however, we do not recommend that. It is a good practice that a network have few NEPs and none of them should be the seed node of the network. To start a Freelib network: 1) Start a seed node: - Edit the configuration file: freelib1.0/dist/info/conf/registry.xml - Locate the following element. 0 If the element is not there add it as a child of the main document element. - Change the 0 to 1. - Locate the following element and change the port number as you like: . .
. . 2048 .
. - Start your freelib client as described above. - Click the button Connect to start the network. 2) Start one or more NEPs: - For each NEP, create a new installation as described above. - After starting each NEP, open the Settings window and: * Add the IP and Port of the seed node in the Initial contacts and click the add button to add an Initial contact entry. * Change the port number for the Freelib Local Server to the port number you want - Click the button Connect to join the network. 3) Publish the IPs and the Port numbers of your NEPs: - Publish the IP and the port number of your NEPs on your Website so that other people can join your network. 9. What if the seed node goes down? ------------------------------------ If the seed node goes down or gets disconnected, special steps needs to be followed. If no other nodes are connected to the network, restart the seed node as described above. If your Freelib network is already established and running, do NOT start the node as a seed node again as it may start a totally different Freelib network. In this case, you have one of two choices: 1) start the node again but as a regular node (not as a seed node), and 2) do not start it at all. The first choice becomes necessary if the node is also the only NEP in your network. 10. Using the Freelib services: -------------------------------- The main interface provides access to the main services such as Search, Download, and Configuration of the client, etc. Click the button Help on the main interface for detailed information on how access the various services and how to configure the Freelib client. 11. LICENSE ------------ This software is distributed in an UIUC/NCSA Open Source License, which is approved by Open Source Initiative in http://www.opensource.org/licenses/UoI-NCSA.php University of Illinois/NCSA Open Source License Copyright (c) 2002 Old Dominion University All rights reserved. Developed by: Digital Library Group Old Dominion University http://dlib.cs.odu.edu Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal with the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimers. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimers in the documentation and/or other materials provided with the distribution. Neither the names of Digital Library Group, Old Dominion University, nor the names of its contributors may be used to endorse or promote products derived from this Software without specific prior written permission. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE SOFTWARE.