Permalink
Browse files

added some comments for javadoc

  • Loading branch information...
1 parent 48dbdf3 commit 8e8d694f26c1d8d0220cc00db6c8cd3bf18d20dd @technige technige committed Feb 20, 2012
@@ -27,13 +27,47 @@
import java.util.HashMap;
import java.util.Map;
+/**
+ * Main entry point for high-level functions. A {@link Subgraph} may be merged into,
+ * inserted into or deleted from a Neo4j graph database using one of the static
+ * methods contained within this class.
+ */
public class Geoff {
// debug switch used for conditional compilation
static final boolean DEBUG = false;
+ private Geoff() { }
+
/**
- * Merge a subgraph into a graph database
+ * Merge a subgraph into a graph database. The following rules describe specific behaviour:
+ *
+ * <h3>Nodes</h3>
+ * <table border="1" cellpadding="4" style="border: 1px solid #000; border-collapse: collapse; font-size: small; text-align: center;">
+ * <tr style="background-color: #DDD;"><th>Rule</th><th>(A) defined</th><th>(A) undefined</th></tr>
+ * <tr><td>(A)</td><td>update (A)</td><td>define (A) as new node</td></tr>
+ * </table>
+ *
+ * <h3>Named Relationships</h3>
+ * <table border="1" cellpadding="4" style="border: 1px solid #000; border-collapse: collapse; font-size: small; text-align: center;">
+ * <tr style="background-color: #DDD;"><th>Rule</th><th>[R] defined</th><th>[R] undefined</th></tr>
+ * <tr><td>[R]</td><td>update [R]</td><td>~</td></tr>
+ * <tr><td>(A)-[R]->(B)</td><td>update [R]</td><td>define and update [R] as existing relationship between
+ * (A) and (B) if one exists</td></tr>
+ * <tr><td>[R:TYPE]</td><td>update [R]</td><td>define [R] as new relationship of type TYPE between two new
+ * nodes</td></tr>
+ * <tr><td>(A)-[R:TYPE]->(B)</td><td>update [R]</td><td>define and update [R] as existing relationship of type TYPE
+ * between (A) and (B) if one exists, or create new relationship otherwise</td></tr>
+ * </table>
+ *
+ * <h3>Unnamed Relationships</h3>
+ * <table border="1" cellpadding="4" style="border: 1px solid #000; border-collapse: collapse; font-size: small; text-align: center;">
+ * <tr style="background-color: #DDD;"><th>Rule</th><th>Behaviour</th></tr>
+ * <tr><td>[]</td><td>~</td></tr>
+ * <tr><td>(A)-[]->(B)</td><td>~</td></tr>
+ * <tr><td>[:TYPE]</td><td>create relationship of type TYPE between two new nodes</td></tr>
+ * <tr><td>(A)-[:TYPE]->(B)</td><td>create relationship of type TYPE between (A) and (B)</td></tr>
+ * </table>
*
* @param subgraph the subgraph to merge
* @param graphDB the database into which to merge
@@ -58,7 +92,7 @@
}
/**
- * Insert a subgraph into a graph database
+ * Insert a subgraph into a graph database. The following rules describe specific behaviour:
*
* @param subgraph the subgraph to insert
* @param graphDB the database into which to insert
@@ -83,7 +117,7 @@
}
/**
- * Delete a subgraph from a graph database
+ * Delete a subgraph from a graph database. The following rules describe specific behaviour:
*
* @param subgraph the subgraph to delete
* @param graphDB the database from which to delete
@@ -31,7 +31,7 @@
import java.util.*;
/**
- * GraphProxy for use with Neo4j
+ * Implementation of {@link GraphProxy} for use with Neo4j.
*
* @author Nigel Small
*/
@@ -51,11 +51,11 @@ public int compare(Relationship rel1, Relationship rel2) {
}
- protected final GraphDatabaseService graphDB;
- protected final EntityStore<NodeToken, Node> nodeStore;
- protected final EntityStore<RelationshipToken, Relationship> relationshipStore;
+ private final GraphDatabaseService graphDB;
+ private final EntityStore<NodeToken, Node> nodeStore;
+ private final EntityStore<RelationshipToken, Relationship> relationshipStore;
- protected int ruleNumber = 0;
+ private int ruleNumber = 0;
/**
* Set up a new proxy for the supplied GraphDatabaseService
@@ -85,7 +85,9 @@ public void inputParams(Map<String, PropertyContainer> params) {
} else if (param.getValue() instanceof Relationship && (isRelKey || isUntypedKey)) {
relationshipStore.put(new RelationshipToken(key), (Relationship) param.getValue());
} else {
- throw new IllegalArgumentException(String.format("Illegal parameter '%s':%s ", key, param.getValue().getClass().getName()));
+ throw new IllegalArgumentException(String.format(
+ "Illegal parameter '%s':%s ", key, param.getValue().getClass().getName()
+ ));
}
}
}
@@ -149,46 +149,105 @@ public String toString() {
private final ArrayList<Rule> rules = new ArrayList<Rule>();
- private Subgraph() { }
-
- public Subgraph(Iterable<?> rules) throws IOException, RuleFormatException {
+ /**
+ * Create an empty subgraph.
+ */
+ public Subgraph() { }
+
+ /**
+ * Create a subgraph from one or more {@link Rule} objects.
+ *
+ * @param rules initial rules to add
+ */
+ public Subgraph(Rule... rules) {
this.add(rules);
}
- public Subgraph(Reader ruleReader) throws IOException, RuleFormatException {
- this.add(ruleReader);
+ /**
+ * Create a subgraph from one or more String formatted rules.
+ *
+ * @param rules initial rules to add
+ * @throws RuleFormatException if a rule string is badly formatted
+ */
+ public Subgraph(String... rules) throws RuleFormatException {
+ this.add(rules);
}
- public Subgraph(String... ruleStrings) throws IOException, RuleFormatException {
- for (String ruleString : ruleStrings) {
- this.add(ruleString);
- }
+ /**
+ * Create a subgraph by reading through String formatted rules.
+ *
+ * @param reader Reader object to read initial rules from
+ * @throws IOException if a read failure occurs
+ * @throws RuleFormatException if a rule string is badly formatted
+ */
+ public Subgraph(Reader reader) throws IOException, RuleFormatException {
+ this.add(reader);
}
- public void add(Iterable<?> rules) throws IOException, RuleFormatException {
- StringReader reader;
- for(Object item : rules) {
- if (item instanceof Rule) {
- this.rules.add((Rule) item);
- } else if (item instanceof Iterable) {
- this.add((Iterable) item);
- } else if (item instanceof Reader) {
- this.add((Reader) item);
- } else if (item instanceof CharSequence) {
- reader = new StringReader(item.toString());
+ /**
+ * Create a subgraph from a variable collection of objects.
+ *
+ * @param rules objects from which to obtain initial rules
+ * @throws IOException if a read failure occurs
+ * @throws RuleFormatException if a rule string is badly formatted
+ */
+ public Subgraph(Iterable<?> rules) throws IOException, RuleFormatException {
+ this.add(rules);
+ }
+
+ /**
+ * Add one or more {@link Rule} objects.
+ *
+ * @param rules rules to add
+ */
+ public void add(Rule... rules) {
+ this.rules.addAll(Arrays.asList(rules));
+ }
+
+ /**
+ * Add one or more String formatted rules.
+ *
+ * @param rules rules to add
+ * @throws RuleFormatException if a rule string is badly formatted
+ */
+ public void add(String... rules) throws RuleFormatException {
+ for (String ruleString : rules) {
+ if (ruleString.contains("\n")) {
+ StringReader reader = new StringReader(ruleString);
try {
this.add(reader);
+ } catch (IOException ex) {
+ //
} finally {
reader.close();
}
} else {
- throw new IllegalArgumentException("Cannot process rules of type " + item.getClass().getName());
+ if (ruleString.trim().isEmpty() || ruleString.charAt(0) == '#') {
+ // empty line or comment
+ } else if (ruleString.startsWith("[\"")) {
+ try {
+ for(String string : JSON.toListOfStrings(ruleString)) {
+ this.rules.add(Rule.from(string));
+ }
+ } catch (JSONException e) {
+ throw new RuleFormatException("Cannot parse JSON list", e);
+ }
+ } else {
+ this.rules.add(Rule.from(ruleString));
+ }
}
}
}
- public void add(Reader ruleReader) throws IOException, RuleFormatException {
- BufferedReader bufferedReader = new BufferedReader(ruleReader);
+ /**
+ * Add to subgraph by reading through String formatted rules.
+ *
+ * @param reader Reader object to read rules from
+ * @throws IOException if a read failure occurs
+ * @throws RuleFormatException if a rule string is badly formatted
+ */
+ public void add(Reader reader) throws IOException, RuleFormatException {
+ BufferedReader bufferedReader = new BufferedReader(reader);
try {
String ruleString = bufferedReader.readLine();
while (ruleString != null) {
@@ -200,36 +259,31 @@ public void add(Reader ruleReader) throws IOException, RuleFormatException {
}
}
- public void add(Rule rule) throws RuleFormatException {
- this.rules.add(rule);
- }
-
- public void add(String... ruleStrings) throws IOException, RuleFormatException {
- for (String ruleString : ruleStrings) {
- if (ruleString.contains("\n")) {
- StringReader reader = new StringReader(ruleString);
+ /**
+ * Add to subgraph from a variable collection of objects.
+ *
+ * @param rules objects from which to obtain rules
+ * @throws IOException if a read failure occurs
+ * @throws RuleFormatException if a rule string is badly formatted
+ */
+ public void add(Iterable<?> rules) throws IOException, RuleFormatException {
+ StringReader reader;
+ for(Object item : rules) {
+ if (item instanceof Rule) {
+ this.rules.add((Rule) item);
+ } else if (item instanceof Iterable) {
+ this.add((Iterable) item);
+ } else if (item instanceof Reader) {
+ this.add((Reader) item);
+ } else if (item instanceof CharSequence) {
+ reader = new StringReader(item.toString());
try {
this.add(reader);
} finally {
reader.close();
}
} else {
- if (ruleString.trim().isEmpty() || ruleString.charAt(0) == '#') {
- // empty line or comment
- } else if (ruleString.startsWith("[\"")) {
- try {
- List<String> strings = JSON.toListOfStrings(ruleString);
- ArrayList<Rule> rules = new ArrayList<Rule>(strings.size());
- for(String string : strings) {
- rules.add(Rule.from(string));
- }
- this.add(rules);
- } catch (JSONException e) {
- throw new RuleFormatException("Cannot parse JSON list", e);
- }
- } else {
- this.rules.add(Rule.from(ruleString));
- }
+ throw new IllegalArgumentException("Cannot process rules of type " + item.getClass().getName());
}
}
}
@@ -0,0 +1,10 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+ <title></title>
+</head>
+<body>
+<p>Geoff exceptions.</p>
+</body>
+</html>
@@ -0,0 +1,10 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+ <title></title>
+</head>
+<body>
+<p>Public classes for Geoff functionality.</p>
+</body>
+</html>
@@ -0,0 +1,10 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+ <title></title>
+</head>
+<body>
+<p>Geoff entity store and token management classes.</p>
+</body>
+</html>
@@ -0,0 +1,10 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+ <title></title>
+</head>
+<body>
+<p>Supporting classes, not specific to Geoff.</p>
+</body>
+</html>

0 comments on commit 8e8d694

Please sign in to comment.