Author: batosai
Date: 2008-09-23 11:10:42 +0000 (Tue, 23 Sep 2008)
New Revision: 22760
Modified:
trunk/plugins/WoT/IdentityFetcher.java
trunk/plugins/WoT/IdentityInserter.java
trunk/plugins/WoT/IdentityParser.java
Log:
Javadoc.
Modified: trunk/plugins/WoT/IdentityFetcher.java
===================================================================
--- trunk/plugins/WoT/IdentityFetcher.java 2008-09-23 11:00:04 UTC (rev
22759)
+++ trunk/plugins/WoT/IdentityFetcher.java 2008-09-23 11:10:42 UTC (rev
22760)
@@ -24,8 +24,10 @@
import freenet.support.Logger;
/**
+ * Fetches Identities from Freenet.
+ * Contains an ArrayList of all current requests.
+ *
* @author Julien Cornuwel (batosai at freenetproject.org)
- *
*/
public class IdentityFetcher implements ClientCallback {
@@ -33,6 +35,12 @@
private HighLevelSimpleClient client;
private ArrayList<ClientGetter> requests;
+ /**
+ * Creates a new IdentityFetcher.
+ *
+ * @param db A reference to the database
+ * @param client A reference to a {@link HighLevelSimpleClient}
+ */
public IdentityFetcher(ObjectContainer db, HighLevelSimpleClient
client) {
this.db = db;
@@ -40,11 +48,24 @@
requests = new ArrayList<ClientGetter>();
}
+ /**
+ * Fetches an Identity from Freenet.
+ * Sets nextEdition to false by default if not specified.
+ *
+ * @param identity the Identity to fetch
+ */
public void fetch(Identity identity) {
fetch(identity, false);
}
+ /**
+ * Fetches an Identity from Freenet.
+ * Sets nextEdition to false by default if not specified.
+ *
+ * @param identity the Identity to fetch
+ * @param nextEdition whether we want to check current edition or the
next one
+ */
public void fetch(Identity identity, boolean nextEdition) {
try {
@@ -57,6 +78,12 @@
}
}
+ /**
+ * Fetches a file from Freenet, by its URI.
+ *
+ * @param uri the {@link FreenetURI} we want to fetch
+ * @throws FetchException if the node encounters a problem
+ */
public void fetch(FreenetURI uri) throws FetchException {
FetchContext fetchContext = client.getFetchContext();
@@ -66,6 +93,9 @@
Logger.debug(this, "Start fetching identity "+uri.toString());
}
+ /**
+ * Stops all running requests.
+ */
public void stop() {
Iterator<ClientGetter> i = requests.iterator();
Logger.debug(this, "Trying to stop "+requests.size()+"
requests");
@@ -73,6 +103,10 @@
Logger.debug(this, "Stopped all current requests");
}
+ /**
+ * Called when the node can't fetch a file OR when there is a newer
edition.
+ * If this is the later, we restart the request.
+ */
public void onFailure(FetchException e, ClientGetter state) {
if ((e.mode == FetchException.PERMANENT_REDIRECT) || (e.mode ==
FetchException.TOO_MANY_PATH_COMPONENTS )) {
@@ -110,6 +144,10 @@
}
+ /**
+ * Called when a file is successfully fetched. We then create an
+ * {@link IdentityParser} and give it the file content.
+ */
public void onSuccess(FetchResult result, ClientGetter state) {
Logger.debug(this, "Fetched key (ClientGetter) : " +
state.getURI());
Modified: trunk/plugins/WoT/IdentityInserter.java
===================================================================
--- trunk/plugins/WoT/IdentityInserter.java 2008-09-23 11:00:04 UTC (rev
22759)
+++ trunk/plugins/WoT/IdentityInserter.java 2008-09-23 11:10:42 UTC (rev
22760)
@@ -32,6 +32,8 @@
import freenet.support.io.TempBucketFactory;
/**
+ * Inserts OwnIdentities to Freenet when they need it.
+ *
* @author Julien Cornuwel (batosai at freenetproject.org)
*
*/
@@ -43,6 +45,13 @@
boolean isRunning;
+ /**
+ * Creates an IdentityInserter.
+ *
+ * @param db A reference to the database
+ * @param client A reference to an {@link HighLevelSimpleClient} to
perform inserts
+ * @param tbf Needed to create buckets from Identities before insert
+ */
public IdentityInserter(ObjectContainer db, HighLevelSimpleClient
client, TempBucketFactory tbf) {
this.db = db;
this.client = client;
@@ -50,6 +59,10 @@
tBF = tbf;
}
+ /**
+ * Starts the IdentityInserter thread. Every 30 minutes,
+ * it exports to XML and inserts OwnIdentities that need it.
+ */
public void run() {
try{
Thread.sleep(30 * 1000); // Let the node start up (30
seconds)
@@ -77,11 +90,28 @@
}
}
+ /**
+ * Stops the IdentityInserter thread.
+ */
public void stop() {
isRunning = false;
Logger.debug(this, "Stopping IdentityInserter thread");
}
-
+
+ /**
+ * Inserts an OwnIdentity.
+ *
+ * @param identity the OwnIdentity to insert
+ * @throws TransformerConfigurationException
+ * @throws FileNotFoundException
+ * @throws ParserConfigurationException
+ * @throws TransformerException
+ * @throws IOException
+ * @throws Db4oIOException
+ * @throws DatabaseClosedException
+ * @throws InvalidParameterException
+ * @throws InsertException
+ */
public void insert(OwnIdentity identity) throws
TransformerConfigurationException, FileNotFoundException,
ParserConfigurationException, TransformerException, IOException,
Db4oIOException, DatabaseClosedException, InvalidParameterException,
InsertException {
Bucket tempB = tBF.makeBucket(1);
Modified: trunk/plugins/WoT/IdentityParser.java
===================================================================
--- trunk/plugins/WoT/IdentityParser.java 2008-09-23 11:00:04 UTC (rev
22759)
+++ trunk/plugins/WoT/IdentityParser.java 2008-09-23 11:10:42 UTC (rev
22760)
@@ -28,6 +28,8 @@
import freenet.support.Logger;
/**
+ * Parses an identity.xml file and updates Identity's data.
+ *
* @author Julien Cornuwel (batosai at freenetproject.org)
*
*/
@@ -39,6 +41,15 @@
SAXParser saxParser;
Identity identity;
+ /**
+ * Creates an IdentityParser and make it ready to parse the file.
+ *
+ * @param db A reference to the database
+ * @param client A reference to an {@link HighLevelSimpleClient}
+ * @param fetcher A reference to the {@link IdentityFetcher} object, in
order to request new editions or newly discovered identities
+ * @throws ParserConfigurationException if the parser encounters a
problem
+ * @throws SAXException if the parser encounters a problem
+ */
public IdentityParser(ObjectContainer db, HighLevelSimpleClient client,
IdentityFetcher fetcher) throws ParserConfigurationException, SAXException {
this.db = db;
@@ -47,6 +58,17 @@
saxParser = SAXParserFactory.newInstance().newSAXParser();
}
+ /**
+ * Parses an identity.xml file, passed from {@link IdentityFetcher} as
an {@link InputStream}
+ *
+ * @param is the InputStream to parse
+ * @param uri the {@link FreenetURI} we just fetched, used to find the
corresponding Identity
+ * @throws InvalidParameterException should never happen
+ * @throws SAXException if the parser encounters a problem
+ * @throws IOException don't know if this can even happen
+ * @throws UnknownIdentityException if the Identity hasn't been created
before fetching it (should never happen)
+ * @throws DuplicateIdentityException if there is more than one
Identity is the database with this requestURI (should never happen)
+ */
public void parse (InputStream is, FreenetURI uri) throws
InvalidParameterException, SAXException, IOException, UnknownIdentityException,
DuplicateIdentityException {
identity = Identity.getByURI(db,uri);
@@ -59,12 +81,24 @@
Logger.debug(this, "Successfuly parsed identity '" +
identity.getNickName() + "'");
}
+ /**
+ * Subclass that actually handles the parsing. Methods are called
+ * by SAXParser for each XML element.
+ *
+ * @author Julien Cornuwel batosai at freenetproject.org
+ *
+ */
public class IdentityHandler extends DefaultHandler {
+ /**
+ * Default constructor
+ */
public IdentityHandler() {
-
}
-
+
+ /**
+ * Called by SAXParser for each XML element.
+ */
public void startElement(String nameSpaceURI, String localName,
String rawName, Attributes attrs) throws SAXException {
String elt_name;
