From 3d50052b67dd6a26884a5dc2ffe3d880d845e125 Mon Sep 17 00:00:00 2001 From: Martin Wiesner Date: Fri, 1 Dec 2023 13:37:42 +0100 Subject: [PATCH] #287 - Reduce JavaDoc warnings for jwpl-api to zero (#288) - applies fixes to many api classes and interfaces to clear out hundreds of warnings - removes (super) dead and worthless code from several very long classes (along the path) Fixes #287 --- dkpro-jwpl-api/pom.xml | 10 + .../java/org/dkpro/jwpl/api/Category.java | 14 + .../jwpl/api/CategoryDescendantsIterable.java | 14 + .../jwpl/api/CategoryDescendantsIterator.java | 8 + .../org/dkpro/jwpl/api/CategoryGraph.java | 460 ++++-------------- .../dkpro/jwpl/api/CategoryGraphManager.java | 57 ++- .../org/dkpro/jwpl/api/CategoryIterable.java | 12 + .../org/dkpro/jwpl/api/CategoryIterator.java | 7 + .../java/org/dkpro/jwpl/api/CycleHandler.java | 4 +- .../dkpro/jwpl/api/DatabaseConfiguration.java | 6 + .../java/org/dkpro/jwpl/api/MetaData.java | 6 +- .../main/java/org/dkpro/jwpl/api/Page.java | 15 +- .../java/org/dkpro/jwpl/api/PageIterable.java | 16 + .../java/org/dkpro/jwpl/api/PageIterator.java | 22 +- .../java/org/dkpro/jwpl/api/PageQuery.java | 42 ++ .../org/dkpro/jwpl/api/PageQueryIterable.java | 8 + .../org/dkpro/jwpl/api/PageQueryIterator.java | 6 + .../main/java/org/dkpro/jwpl/api/Title.java | 5 +- .../org/dkpro/jwpl/api/TitleIterable.java | 12 + .../org/dkpro/jwpl/api/TitleIterator.java | 7 + .../org/dkpro/jwpl/api/WikipediaInfo.java | 41 +- .../jwpl/api/exception/WikiApiException.java | 26 +- .../jwpl/api/exception/WikiException.java | 26 +- .../WikiInitializationException.java | 25 +- .../exception/WikiPageNotFoundException.java | 23 +- .../exception/WikiTitleParsingException.java | 23 +- .../dkpro/jwpl/api/hibernate/Category.java | 41 ++ .../dkpro/jwpl/api/hibernate/CategoryDAO.java | 11 +- .../dkpro/jwpl/api/hibernate/GenericDAO.java | 38 +- .../dkpro/jwpl/api/hibernate/MetaData.java | 102 +++- .../dkpro/jwpl/api/hibernate/MetaDataDAO.java | 7 +- .../org/dkpro/jwpl/api/hibernate/Page.java | 62 ++- .../org/dkpro/jwpl/api/hibernate/PageDAO.java | 11 +- .../dkpro/jwpl/api/hibernate/PageMapLine.java | 34 +- .../jwpl/api/hibernate/WikiHibernateUtil.java | 11 + .../jwpl/api/sweble/PlainTextConverter.java | 152 +++++- .../api/sweble/TemplateNameExtractor.java | 12 +- .../org/dkpro/jwpl/api/util/ApiUtilities.java | 14 +- .../dkpro/jwpl/api/util/CommonUtilities.java | 7 +- .../org/dkpro/jwpl/api/util/DbUtilities.java | 13 + .../dkpro/jwpl/api/util/GraphUtilities.java | 16 +- .../jwpl/api/util/HibernateUtilities.java | 10 +- .../main/java/org/dkpro/jwpl/api/util/OS.java | 5 + .../api/util/SerializableDirectedGraph.java | 11 +- .../org/dkpro/jwpl/api/util/StringUtils.java | 3 + .../jwpl/api/util/UnmodifiableArraySet.java | 16 + .../distance/LevenshteinStringDistance.java | 4 + .../api/util/distance/StringDistance.java | 9 + .../wikiapi_simple_20090119_stripped.script | 2 +- 49 files changed, 1053 insertions(+), 433 deletions(-) diff --git a/dkpro-jwpl-api/pom.xml b/dkpro-jwpl-api/pom.xml index 2483cf11..91406037 100644 --- a/dkpro-jwpl-api/pom.xml +++ b/dkpro-jwpl-api/pom.xml @@ -182,6 +182,16 @@ + + org.apache.maven.plugins + maven-javadoc-plugin + + + + org/dkpro/jwpl/api/WikiConstants.java + + + org.codehaus.mojo build-helper-maven-plugin diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Category.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Category.java index 2c46398d..722a1fa4 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Category.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Category.java @@ -28,6 +28,16 @@ import org.hibernate.Session; import org.hibernate.type.StandardBasicTypes; +/** + * Represents a category as conceptually defined by Wikipedia. + * Each category can group several {@link Page pages}. + *

+ * It can be subdivided further, that is, every category can have descendents or siblings. + * Structurally, Wikipedia defined categories to be represented as a graph. Consequently, + * a category can have multiple parent categories. + * + * @see Page + */ public class Category implements WikiConstants { @@ -383,6 +393,10 @@ public Iterable getDescendants() /** * Returns *all* recursively collected descendants (=subcategories) of this category. * + * @param bufferSize The size of the page buffer. With {@code bufferSize = 1}, a database connection is needed for + * retrieving a single article. Higher {@code bufferSize} values gives better performance, + * but require more memory. Must not be less or equal to {@code 0}. + * * @return An iterable of all descendants (=subcategories) of this category. */ protected Iterable getDescendants(int bufferSize) diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryDescendantsIterable.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryDescendantsIterable.java index 6ef5ce87..5f5299c7 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryDescendantsIterable.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryDescendantsIterable.java @@ -36,12 +36,26 @@ public class CategoryDescendantsIterable */ private int bufferSize = 25; + /** + * Initializes a {@link CategoryDescendantsIterable} instance. Uses a default buffer size of {@code 25}. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param startCategory The Wikipedia category to start descending from. Must not be {@code null}. + */ public CategoryDescendantsIterable(Wikipedia wiki, Category startCategory) { this.wiki = wiki; this.startCategory = startCategory; } + /** + * Initializes a {@link CategoryDescendantsIterable} instance. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param bufferSize The number of pages to be buffered after a query to the database. + * Higher bufferSize gives better performance, but require more memory. + * @param startCategory The Wikipedia category to start descending from. Must not be {@code null}. + */ public CategoryDescendantsIterable(Wikipedia wiki, int bufferSize, Category startCategory) { this.wiki = wiki; diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryDescendantsIterator.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryDescendantsIterator.java index 04f51446..901ce90e 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryDescendantsIterator.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryDescendantsIterator.java @@ -52,6 +52,14 @@ public class CategoryDescendantsIterator */ private final Set expandedCategoryIds; + /** + * Initializes a {@link CategoryDescendantsIterator} instance. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param bufferSize The number of pages to be buffered after a query to the database. + * Higher bufferSize gives better performance, but require more memory. + * @param startCategory The Wikipedia category to start descending from. Must not be {@code null}. + */ public CategoryDescendantsIterator(Wikipedia wiki, int bufferSize, Category startCategory) { this.wiki = wiki; diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryGraph.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryGraph.java index 12cd4ced..02a5c6bb 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryGraph.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryGraph.java @@ -63,49 +63,73 @@ public class CategoryGraph private static final Logger logger = LoggerFactory .getLogger(MethodHandles.lookup().lookupClass()); - static final long serialVersionUID = 1L; + private static final long serialVersionUID = 1L; - // the wikipedia object + /** + * The wikipedia object + */ private Wikipedia wiki; - // the category graph + /** + * The category graph, directed. + */ private DefaultDirectedGraph graph; - // the category graph + + /** + * The category graph, undirected. + */ private AsUndirectedGraph undirectedGraph; - // a map holding the degree distribution of the graph + /** + * A map holding the degree distribution of the graph + */ private Map degreeDistribution; - // number of nodes in the graph + /** + * Number of nodes in the graph + */ private int numberOfNodes; - // number of edges in the graph + /** + * Number of edges in the graph + */ private int numberOfEdges; - // A map holding the (recursive) number of hyponyms for each node. - // Recursive means that the hyponyms of hyponyms are also taken into account. + /** + * A map holding the (recursive) number of hyponyms for each node. + * Recursive means that the hyponyms of hyponyms are also taken into account. + */ private Map hyponymCountMap = null; - private final String hyponymCountMapFilename = "hypoCountMap"; - // a mapping from all nodes to a list of nodes on the path to the root + /** + * A mapping from all nodes to a list of nodes on the path to the root + */ private Map> rootPathMap = null; - private final String rootPathMapFilename = "rootPathMap"; + /** + * The average shortest path length. Initially: {@link Double#NEGATIVE_INFINITY}. + */ private double averageShortestPathLength = Double.NEGATIVE_INFINITY; + + /** + * The diameter of a category graph. Initially: {@link Double#NEGATIVE_INFINITY}. + */ private double diameter = Double.NEGATIVE_INFINITY; + + /** + * The average degree of a category graph. Initially: {@link Double#NEGATIVE_INFINITY}. + */ private double averageDegree = Double.NEGATIVE_INFINITY; + + /** + * The cluster coefficient of a category graph. Initially: {@link Double#NEGATIVE_INFINITY}. + */ private double clusterCoefficient = Double.NEGATIVE_INFINITY; - private double depth = Double.NEGATIVE_INFINITY; /** - * Creates an empty {@link CategoryGraph}. You cannot do much with such a graph. Sometimes an - * empty category graph can be useful if you just need a CategoryGraph object, but do not care - * about its content. + * The depth of a category graph. Initially: {@link Double#NEGATIVE_INFINITY}. */ - public CategoryGraph() throws WikiApiException - { - logger.warn("Attention. You created an empty category graph. Intentionally?"); - } + private double depth = Double.NEGATIVE_INFINITY; /** * Creates an {@link CategoryGraph} using a serialized DirectedGraph object. @@ -216,15 +240,20 @@ protected CategoryGraph(Wikipedia pWiki, Set pPageIDs) throws WikiApiEx constructCategoryGraph(pWiki, pPageIDs, null); } + /** + * Creates a category graph using a subset (that may also be the full set :) of the categories. + * + * @param pWiki + * The wiki object. + * @param pGraph A valid {@link DefaultDirectedGraph} representation. + */ public CategoryGraph(Wikipedia pWiki, DefaultDirectedGraph pGraph) - throws WikiApiException { constructCategoryGraph(pWiki, pGraph); } private void constructCategoryGraph(Wikipedia pWiki, DefaultDirectedGraph pGraph) - throws WikiApiException { this.wiki = pWiki; this.graph = pGraph; @@ -339,86 +368,6 @@ private void constructCategoryGraph(Wikipedia pWiki, Set pPageIDs, } - //// older version without filterList - // private void constructCategoryGraph(Wikipedia pWiki, Set pPageIDs) throws - //// WikiApiException { - // // create the graph as a directed Graph - // // algorithms that need to be called on a undirected graph or should ignore direction - // // can be called on an AsUndirectedGraph view of the directed graph - // graph = new DefaultDirectedGraph(DefaultEdge.class); - // - // wiki = pWiki; - // - // degreeDistribution = new HashMap(); - // - // for (int pageID : pPageIDs) { - // graph.addVertex(pageID); - // } - // - // // add edges - // logger.info(OS.getUsedMemory() + " MB memory used."); - // int progress = 0; - // for (int pageID : pPageIDs) { - // progress++; - // ApiUtilities.printProgressInfo(progress, pPageIDs.size(), 10, - //// ApiUtilities.ProgressInfoMode.TEXT, "Adding edges"); - // - // long hibernateID = pWiki.__getHibernateId(pageID); - // if (hibernateID == -1) { - // throw new WikiApiException(pageID + " is not a valid pageID"); - // } - // - // // get the category - // Category cat; - // try { - // cat = new Category(this.wiki, hibernateID); - // } catch (WikiPageNotFoundException e) { - // throw new WikiApiException("Category not found"); - // } - // - // // get parents and children - // // if the corresponding nodes are in the graph (it could be a subset) => add them to the - //// graph - // Set inLinks = cat.__getInlinkIDs(); - // Set outLinks = cat.__getOutlinkIDs(); - // - // // add edges - // // If an edge already exits, it is silenty ignored by JGraphT. So we do not have to check - //// this. - // for (int inLink : inLinks) { - // if (pPageIDs.contains(inLink)) { - // if (inLink == pageID) { - // logger.warn("Self-loop for node " + pageID + " (" + cat.getTitle() + ")"); - // } - // else { - // graph.addEdge(inLink, pageID); - // } - // } - // } - // for (int outLink : outLinks) { - // if (pPageIDs.contains(outLink)) { - // if (outLink == pageID) { - // logger.warn("Self-loop for node " + pageID + " (" + cat.getTitle() + ")"); - // } - // else { - // graph.addEdge(pageID, outLink); - // } - // } - // } - // } - // - // logger.info("Added " + this.getNumberOfNodes() + " nodes."); - // logger.info("Added " + this.getNumberOfEdges() + " edges."); - // - // CycleHandler cycleHandler = new CycleHandler(wiki, this); - // logger.info("Graph contains cycles: " + cycleHandler.containsCycle()); - // cycleHandler.removeCycles(); - // logger.info("Graph contains cycles: " + cycleHandler.containsCycle()); - // - // this.depth = getDepth(); - // logger.info(this.depth); - // } - /** * Checks whether the category title matches the filter (a filter matches a string, if the * string starts with the filter expression). @@ -455,6 +404,9 @@ private boolean matchesFilter(Category cat, List filterList) * @param category2 * The second category node. * @return The lowest common subsumer of the two nodes, or null if there is no LCS. + * + * @throws WikiApiException + * Thrown if errors occurred. */ public Category getLCS(Category category1, Category category2) throws WikiApiException { @@ -472,6 +424,9 @@ public Category getLCS(Category category1, Category category2) throws WikiApiExc * The pageid of the second category node. * @return The pageId of the lowest common subsumer of the two nodes, or null if there is no * LCS. + * + * @throws WikiApiException + * Thrown if errors occurred. */ public int getLCSId(int categoryPageId1, int categoryPageId2) throws WikiApiException { @@ -535,6 +490,9 @@ public int getLCSId(int categoryPageId1, int categoryPageId2) throws WikiApiExce * @param categoryPageId2 * The pageid of the second category node. * @return The lowest common subsumer of the two nodes, or null if there is no LCS. + * + * @throws WikiApiException + * Thrown if errors occurred. */ public Category getLCS(int categoryPageId1, int categoryPageId2) throws WikiApiException { @@ -542,126 +500,6 @@ public Category getLCS(int categoryPageId1, int categoryPageId2) throws WikiApiE return lcsid > -1 ? wiki.getCategory(getLCSId(categoryPageId1, categoryPageId2)) : null; } - // /** - // * Gets the lowest common subsumer (LCS) of two nodes. - // * The LCS of two nodes is first node on their paths to the root that is shared between the - // nodes. - // * Nodes that are not in the same connected component as the root node are defined to have no - // LCS. - // * @param rootCategory The root node of the category hierarchy. - // * @param category1 The first category node. - // * @param category2 The second category node. - // * @return The lowest common subsumer of the two nodes, or null if there is no LCS. - // */ - // public Category getLCS(Category rootCategory, Category category1, Category category2) throws - // WikiApiException { - // - // int root = rootCategory.getPageId(); - // int node1 = category1.getPageId(); - // int node2 = category2.getPageId(); - // - //// TODO here might be a problem concerning multiple inheritence in the category graph, if - // there is more than one path of equal length to the root, the method will only find one, but - // may be the other (not found) LCS has a higher information content - // - // logger.debug("root: " + root); - // logger.debug("n1: " + node1); - // logger.debug("n2: " + node2); - // - // // if one of the nodes is not in the same connected component as the root node, we cannot get - // the LCS - // if (!undirectedGraph.containsVertex(node1) || !undirectedGraph.containsVertex(node2)) { - // logger.warn("Cannot get lowest common subsumer because the nodes are not in the same - // connected component."); - // return null; - // } - // - //// TODO due to multiple inheritance there may be a non-shortest path that leads to a lcs below - // the root - //// this should be considered here!! - // // get the path from root node to node 1 - // List edgeList1 = DijkstraShortestPath.findPathBetween(undirectedGraph, node1, - // root); - // - // // get the path from root node to node 2 - // List edgeList2 = DijkstraShortestPath.findPathBetween(undirectedGraph, node2, - // root); - // - // // if one of the nodes is not in the same connected component as the root node, there is no - // path - // // return -1 in this case - // if (edgeList1 == null || edgeList2 == null) { - // return null; - // } - // - // // convert the edge lists to node sets - // List nodeList1 = edgeList2nodeList(edgeList1, root, node1); - // List nodeList2 = edgeList2nodeList(edgeList2, root, node2); - // - // logger.debug(edgeList1); - // logger.debug(edgeList2); - // logger.debug(nodeList1); - // logger.debug(nodeList2); - // - // // node 1 subsumes node 2 ? - // for (int tmpNode2 : nodeList2) { - // if (tmpNode2 == node1) { - // return wiki.__getCategory(node1); - // } - // } - // - // // node 2 subsumes node 1 ? - // for (int tmpNode1 : nodeList1) { - // if (tmpNode1 == node2) { - // return wiki.__getCategory(node2); - // } - // } - // // they have a lcs ? - // for (int tmpNode1 : nodeList1) { - // for (int tmpNode2 : nodeList2) { - // if (tmpNode1 == tmpNode2) { - // return wiki.__getCategory(tmpNode1); - // } - // } - // } - // - // return null; - // } - - // /** - // * Converts an edgeList as returned by the Dijkstra-Shortest-Path algorithm into a list of - // nodes on this path. - // * @param edgeList The list of edges of this path running from the searched node to the root - // node. - // * @return The corresponding list of nodes on the path running from the searched node to the - // root node. - // */ - // private List edgeList2nodeList(List edgeList, int root, int node) - // throws WikiApiException { - // Iterator it = edgeList.iterator(); - // - // List nodeList = new ArrayList(); - // // init with start node - // nodeList.add(node); - // int currentNode = node; - // - // while(it.hasNext()) { - // DefaultEdge currentEdge = it.next(); - // if (graph.getEdgeSource(currentEdge) != currentNode) { - // nodeList.add(graph.getEdgeSource(currentEdge)); - // currentNode = graph.getEdgeSource(currentEdge); - // } - // else if (graph.getEdgeTarget(currentEdge) != currentNode) { - // nodeList.add(graph.getEdgeTarget(currentEdge)); - // currentNode = graph.getEdgeTarget(currentEdge); - // } - // else { - // throw new WikiApiException("Path is broken"); - // } - // } - // return nodeList; - // } - /** * Returns the shortest path from node to root as a list of pageIds of the nodes on the path. * Node and root are included in the path node list. @@ -861,25 +699,6 @@ public int getTaxonomicallyBoundPathLengthInEdges(Category cat1, Category cat2) return -1; } - public int getTaxonomicallyBoundPathLengthInNodes(Category cat1, Category cat2) - throws WikiApiException - { - int retValue = getTaxonomicallyBoundPathLengthInEdges(cat1, cat2); - - if (retValue == 0) { - return 0; - } - else if (retValue > 0) { - return (--retValue); - } - else if (retValue == -1) { - return -1; - } - else { - throw new WikiApiException("Unknown return value."); - } - } - /** * Gets the path length between two category nodes - measured in "nodes". * @@ -889,6 +708,9 @@ else if (retValue == -1) { * The second node. * @return The number of nodes of the path between node1 and node2. 0, if the nodes are * identical or neighbors. -1, if no path exists. + * + * @throws WikiApiException + * Thrown if errors occurred. */ public int getPathLengthInNodes(Category node1, Category node2) throws WikiApiException { @@ -914,6 +736,7 @@ else if (retValue == -1) { * each node. "recursive" means that the hyponyms of hyponyms are also taken into account. * * @throws WikiApiException + * Thrown if errors occurred. */ private void createHyponymCountMap() throws WikiApiException { @@ -922,6 +745,7 @@ private void createHyponymCountMap() throws WikiApiException return; } + String hyponymCountMapFilename = "hypoCountMap"; File hyponymCountMapSerializedFile = new File( wiki.getWikipediaId() + "_" + hyponymCountMapFilename); hyponymCountMap = new HashMap<>(); @@ -977,7 +801,7 @@ private void createHyponymCountMap() throws WikiApiException } if (invalid) { - // One of the childs is not in the hyponymCountMap yet + // One of the children is not in the hyponymCountMap yet // Re-Enter the node into the queue and continue with next node queue.add(currNode); continue; @@ -1039,6 +863,7 @@ private void scaleHyponymCountMap() throws WikiApiException /** * @return The leaf nodes of the graph, i.e. nodes with outdegree = 0. * @throws WikiApiException + * Thrown if errors occurred. */ protected Set __getLeafNodes() throws WikiApiException { @@ -1117,7 +942,8 @@ public void createRootPathMap() throws WikiApiException return; } - File rootPathFile = new File(wiki.getWikipediaId() + "_" + this.rootPathMapFilename); + String rootPathMapFilename = "rootPathMap"; + File rootPathFile = new File(wiki.getWikipediaId() + "_" + rootPathMapFilename); // try to load rootPathMap from precomputed file if (rootPathFile.exists()) { @@ -1167,22 +993,6 @@ public void createRootPathMap() throws WikiApiException this.serializeMap(rootPathMap, rootPathFile); } - // TODO the method is only public, because the test deletes the file after creating it - I have - // no idea at the moment how to do it - - /** - * Deleted the root path map file. - * - * @throws WikiApiException - * Thrown if errors occurred. - */ - public void deleteRootPathMap() throws WikiApiException - { - File rootPathFile = new File(this.rootPathMapFilename + "_" + wiki.getLanguage() + "_" - + wiki.getMetaData().getVersion()); - rootPathFile.delete(); - } - private void fillRootPathMap(List queue) throws WikiApiException { int root = wiki.getMetaData().getMainCategory().getPageId(); @@ -1292,6 +1102,9 @@ protected Set __getParents(int pageID) /** * @return Returns the largest connected component as a new graph. If the base graph already is * connected, it simply returns the whole graph. + * + * @throws WikiApiException + * Thrown if errors occurred. */ public CategoryGraph getLargestConnectedComponent() throws WikiApiException { @@ -1575,79 +1388,6 @@ private void setGraphParameters() this.clusterCoefficient = clusterCoefficientSum / nodes.size(); } - // /** - // * Computes and sets the diameter, the average degree and the average shortest path length of - // the graph. - // * Do not call this in the constructor. May run a while. - // * It is called in the getters, if parameters are not yet initialized when retrieved. - // */ - // public void setGraphParameters_slow() { - // - // // Diameter is the maximum of all shortest path lengths - // // Average shortest path length is (as the name says) the average of the shortest path length - // between all node pairs - // - // double maxDiameter = 0.0; - // double shortestPathLengthSum = 0.0; - // double degreeSum = 0.0; - // double clusterCoefficientSum = 0.0; - // - // // iterate over all node pairs - // Set nodes = undirectedGraph.vertexSet(); - // Object[] nodeArray = nodes.toArray(); - // // sort the Array so we can use a simple iteration with two for loops to access all pairs - // Arrays.sort(nodeArray); - // - // int progress = 0; - // for (int i=0; i 1) { - // clusterCoefficientSum += getNumberOfNeighborConnections(outerNode, undirectedGraph) / - // (undirectedGraph.degreeOf(outerNode) * (undirectedGraph.degreeOf(outerNode)-1)); - // } - // - // for (int j=i+1; j maxDiameter) { - // maxDiameter = pathLength; - // } - // } - // } - // - // this.averageShortestPathLength = shortestPathLengthSum / ( nodes.size() * (nodes.size()-1) / - // 2 ); // sum of path lengths / (number of node pairs) - // this.diameter = maxDiameter; - // this.averageDegree = degreeSum / nodes.size(); - // this.clusterCoefficient = clusterCoefficientSum / nodes.size(); - // } - /** * Computes the shortest path from node to all other nodes. Paths to nodes that have already * been the source of the shortest path computation are omitted (the path was already added to @@ -1658,12 +1398,12 @@ private void setGraphParameters() * @param pStartNode * The start node of the search. * @param pShortestPathLengthSum - * The sum of the shortes path lengths. + * The sum of the shortest path lengths. * @param pMaxPathLength * The maximum path length found so far. * @param pWasSource * A set of nodes which have been the start node of the computation process. For such - * nodes all path lengths have beeen already computed. + * nodes all path lengths have been already computed. * @return An array of double values. The first value is the shortestPathLengthSum and the * second value is the maxPathLength. They are returned as an double array for * performance reasons. I do not want to create an object, as this function is called @@ -1727,13 +1467,12 @@ private double[] computeShortestPathLenghts(int pStartNode, double pShortestPath } } } - double[] returnArray = { pShortestPathLengthSum, pMaxPathLength }; - return returnArray; + return new double[]{ pShortestPathLengthSum, pMaxPathLength }; } /** * This parameter is already set in the constructor as it is needed for computation of - * relatedness values. Therefore its computation does not trigger setGraphParameters (it is too + * relatedness values. Therefore, its computation does not trigger setGraphParameters (it is too * slow), even if the depth is implicitly determined there, too. * * @return The depth of the category graph, i.e. the maximum path length starting with the root @@ -1759,7 +1498,7 @@ public double getDepth() throws WikiApiException /** * This parameter is already set in the constructor as it is needed for computation of - * relatedness values. Therefore its computation does not trigger setGraphParameters (it is too + * relatedness values. Therefore, its computation does not trigger setGraphParameters (it is too * slow), even if the depth is implicitly determined there, too. * * @return The depth of the category graph, i.e. the maximum path length starting with the root @@ -1815,36 +1554,46 @@ private double computeDepth() throws WikiApiException return maxPathLength; } + /** + * @return Creates and returns a graph properties information string. + */ public String getGraphInfo() { StringBuffer sb = new StringBuffer(1000); Map degreeDistribution = getDegreeDistribution(); - sb.append("Number of Nodes: " + getNumberOfNodes() + LF); - sb.append("Number of Edges: " + getNumberOfEdges() + LF); - sb.append("Avg. path length: " + getAverageShortestPathLength() + LF); - sb.append("Diameter: " + getDiameter() + LF); - sb.append("Average degree: " + getAverageDegree() + LF); - sb.append("Cluster coefficient: " + getClusterCoefficient() + LF); - sb.append( - "Degree distribution: " + CommonUtilities.getMapContents(degreeDistribution) + LF); + sb.append("Number of Nodes: ").append(getNumberOfNodes()).append(LF); + sb.append("Number of Edges: ").append(getNumberOfEdges()).append(LF); + sb.append("Avg. path length: ").append(getAverageShortestPathLength()).append(LF); + sb.append("Diameter: ").append(getDiameter()).append(LF); + sb.append("Average degree: ").append(getAverageDegree()).append(LF); + sb.append("Cluster coefficient: ").append(getClusterCoefficient()).append(LF); + sb.append("Degree distribution: ").append(CommonUtilities.getMapContents(degreeDistribution)).append(LF); return sb.toString(); } /** - * @return Returns the graph. + * @return Returns the {@link DefaultDirectedGraph directed graph}. */ public DefaultDirectedGraph getGraph() { return graph; } + /** + * @return Returns the {@link AsUndirectedGraph undirected graph}. + */ public AsUndirectedGraph getUndirectedGraph() { return undirectedGraph; } + /** + * @return Retrieves a map for the frequencies (value) of hyponyms (key). + * @throws WikiApiException + * Thrown if errors occurred. + */ public Map getHyponymCountMap() throws WikiApiException { if (hyponymCountMap == null) { @@ -1853,6 +1602,11 @@ public Map getHyponymCountMap() throws WikiApiException return this.hyponymCountMap; } + /** + * @return Retrieves a map of root paths. + * @throws WikiApiException + * Thrown if errors occurred. + */ public Map> getRootPathMap() throws WikiApiException { if (rootPathMap == null) { @@ -1862,12 +1616,12 @@ public Map> getRootPathMap() throws WikiApiException } /** - * Serialize a Map. + * Serializes the specified {@link Map map} to a {@code file}. * * @param map - * The map to serialize. + * The map to serialize. Must not be {@code null}. * @param file - * The file for saving the map. + * The file for saving the map. Must not be {@code null}. */ private void serializeMap(Map map, File file) { @@ -1881,10 +1635,11 @@ private void serializeMap(Map map, File file) } /** - * Deserialize a map + * Deserializes a {@link Map map} from the specified {@code file}. * * @param file - * The file with the map. + * The file with the map. Must not be {@code null}. + * @return The reconstructed {@link Map} or {@code null} if errors occurred. */ private Map deserializeMap(File file) { @@ -1908,7 +1663,6 @@ private void serializeMap(Map map, File file) * @throws WikiApiException * Thrown if errors occurred. */ - // TODO should be refactored a bit. public void saveGraph(String destination) throws WikiApiException { try { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryGraphManager.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryGraphManager.java index 4d4970e9..2da994d5 100755 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryGraphManager.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryGraphManager.java @@ -29,9 +29,15 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; +/** + * Provides ways to create and retrieve {@link CategoryGraph graphs} from the Wikipedia backend. + * + * @see Wikipedia + * @see CategoryGraph + */ // TODO category graph manager implements real singletons for category graphs -// up to now, it is only used in LSR -// There should be no way to construct a category graph that circumvents the manager. +// up to now, it is only used in LSR. +// There should be no way to construct a category graph that circumvents the manager. public class CategoryGraphManager { @@ -42,23 +48,70 @@ public class CategoryGraphManager private final static String catGraphSerializationFilename = "catGraphSer"; + /** + * Retrieves a {@link CategoryGraph} instance for all categories in a {@link Wikipedia} instance. + * Additionally, the graph is persisted if it could be constructed successfully. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @return A graph representation of all categories in {@code wiki}. + * + * @throws WikiApiException Thrown if errors occurred. + */ public static CategoryGraph getCategoryGraph(Wikipedia wiki) throws WikiApiException { return getCategoryGraph(wiki, null, true); } + /** + * Retrieves a {@link CategoryGraph} instance for all categories in a {@link Wikipedia} instance. + * Additionally, the graph is persisted if it could be constructed successfully. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param serialize If {@code true}, attempts to load a serialized version of the graph, + * {@code false} otherwise. If {@code true} and no previous version of exists, + * a completely new graph instance is created and retrieved via {@code wiki}. + * @return A graph representation of all categories in {@code wiki}. + * + * @throws WikiApiException Thrown if errors occurred. + */ public static CategoryGraph getCategoryGraph(Wikipedia wiki, boolean serialize) throws WikiApiException { return getCategoryGraph(wiki, null, serialize); } + + /** + * Retrieves a {@link CategoryGraph} instance for all categories in a {@link Wikipedia} instance. + * Additionally, the graph is persisted if it could be constructed successfully. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param pageIds A set of page ids (of category pages) that should be used to build the category + * graph from. + * @return A graph representation of all categories in {@code wiki}. + * + * @throws WikiApiException Thrown if errors occurred. + */ public static CategoryGraph getCategoryGraph(Wikipedia wiki, Set pageIds) throws WikiApiException { return getCategoryGraph(wiki, pageIds, true); } + /** + * Retrieves a {@link CategoryGraph} instance for all categories in a {@link Wikipedia} instance. + * Additionally, the graph is persisted if it could be constructed successfully. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param pageIds A set of page ids (of category pages) that should be used to build the category + * graph from. + * @param serialize If {@code true}, attempts to load a serialized version of the graph, + * {@code false} otherwise. If {@code true} and no previous version of exists, + * a completely new graph instance is created and retrieved via {@code wiki}. + * @return A graph representation of all categories in {@code wiki}. + * + * @throws WikiApiException Thrown if errors occurred. + */ public static CategoryGraph getCategoryGraph(Wikipedia wiki, Set pageIds, boolean serialize) throws WikiApiException diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryIterable.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryIterable.java index aec0c532..64f8da02 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryIterable.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryIterable.java @@ -35,11 +35,23 @@ public class CategoryIterable */ private int bufferSize = 500; + /** + * Initializes a {@link CategoryIterable} instance. Uses a default buffer size of {@code 500}. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + */ public CategoryIterable(Wikipedia wiki) { this.wiki = wiki; } + /** + * Initializes a {@link CategoryIterable} instance. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param bufferSize The number of pages to be buffered after a query to the database. + * Higher bufferSize gives better performance, but require more memory. + */ public CategoryIterable(Wikipedia wiki, int bufferSize) { this.wiki = wiki; diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryIterator.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryIterator.java index bede8d44..faa6e4b9 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryIterator.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryIterator.java @@ -39,6 +39,13 @@ public class CategoryIterator private final CategoryBuffer buffer; + /** + * Initializes a {@link CategoryIterator} instance. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param bufferSize The number of pages to be buffered after a query to the database. + * Higher bufferSize gives better performance, but require more memory. + */ public CategoryIterator(Wikipedia wiki, int bufferSize) { buffer = new CategoryBuffer(bufferSize, wiki); diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CycleHandler.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CycleHandler.java index 11e96031..83d0b20e 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CycleHandler.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CycleHandler.java @@ -28,7 +28,9 @@ import org.slf4j.LoggerFactory; /** - * Methods for handling cycles in the category graph. + * Provides methods for handling cycles in the category graph. + * + * @see CategoryGraph */ public class CycleHandler { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/DatabaseConfiguration.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/DatabaseConfiguration.java index 345bb29c..5c38edc3 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/DatabaseConfiguration.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/DatabaseConfiguration.java @@ -32,6 +32,12 @@ public class DatabaseConfiguration private String jdbcURL; private String databaseDriver; + /** + * A no-arg constructor required by frameworks. + * It is recommended to use + * {@link DatabaseConfiguration#DatabaseConfiguration(String, String, String, String, + * String, String, WikiConstants.Language)} instead. + */ public DatabaseConfiguration() { } diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/MetaData.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/MetaData.java index 551156a2..afc320de 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/MetaData.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/MetaData.java @@ -23,6 +23,8 @@ /** * Provides access to meta-data about a certain {@link Wikipedia} instance. + * + * @see Wikipedia */ public class MetaData implements WikiConstants @@ -32,7 +34,9 @@ public class MetaData private final org.dkpro.jwpl.api.hibernate.MetaData hibernateMetaData; /** - * Creates a meta data object. + * Instantiates a new {@link MetaData} object. + * + * @param wiki A valid {@link Wikipedia} reference. Must no be {@code null}. */ protected MetaData(Wikipedia wiki) { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Page.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Page.java index a4cccbf9..2d4943c3 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Page.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Page.java @@ -37,7 +37,12 @@ import de.fau.cs.osr.ptk.common.AstVisitor; /** - * Represents a Wikipedia article page. + * Represents an article page as conceptually defined by Wikipedia. + * Each page can link to other {@link Page pages} or be referenced to. + *

+ * Moreover, a page can be contained in one or more {@link Category categories}. + * + * @see Category */ // Adapter class for hiding hibernate session management from the user. public class Page @@ -58,12 +63,10 @@ public class Page private boolean isRedirect = false; /** - * Creates a page object. + * Instantiates a {@link Page} object. * - * @param wiki - * The wikipedia object. - * @param id - * The hibernate id of the page. + * @param wiki A valid {@link Wikipedia} reference. Must no be {@code null}. + * @param id The hibernate id of the page. * @throws WikiApiException * Thrown if errors occurred. */ diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageIterable.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageIterable.java index 2f5de70c..2e5d3ba1 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageIterable.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageIterable.java @@ -40,12 +40,28 @@ public class PageIterable */ private int bufferSize = 500; + /** + * Initializes a {@link PageIterable} instance. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param onlyArticles {@code True} if only full article pages shall be processed, yet no disambiguation pages. + * {@code False} if disambiguation pages shall considered as well. + */ public PageIterable(Wikipedia wiki, boolean onlyArticles) { this.wiki = wiki; this.onlyArticles = onlyArticles; } + /** + * Initializes a {@link PageIterable} instance. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param onlyArticles {@code True} if only full article pages shall be processed, yet no disambiguation pages. + * {@code False} if disambiguation pages shall considered as well. + * @param bufferSize The number of pages to be buffered after a query to the database. + * Higher bufferSize gives better performance, but require more memory. + */ protected PageIterable(Wikipedia wiki, boolean onlyArticles, int bufferSize) { this.wiki = wiki; diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageIterator.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageIterator.java index 34283bd0..8d9f0a77 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageIterator.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageIterator.java @@ -43,11 +43,29 @@ public class PageIterator private final PageBuffer buffer; + /** + * Initializes a {@link PageIterator} instance. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param ids A set of page ids to iterate over. Must not be {@code null}. + * @param titles A set of page titles to iterate over. Must not be {@code null}. + * @param bufferSize The number of pages to be buffered after a query to the database. + * Higher bufferSize gives better performance, but require more memory. + */ public PageIterator(Wikipedia wiki, Set ids, Set titles, int bufferSize) { buffer = new PageBuffer(bufferSize, wiki, ids, titles); } + /** + * Initializes a {@link PageIterator} instance. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param onlyArticles {@code True} if only full article pages shall be processed, yet no disambiguation pages. + * {@code False} if disambiguation pages shall considered as well. + * @param bufferSize The number of pages to be buffered after a query to the database. + * Higher bufferSize gives better performance, but require more memory. + */ public PageIterator(Wikipedia wiki, boolean onlyArticles, int bufferSize) { buffer = new PageBuffer(bufferSize, wiki, onlyArticles); @@ -121,10 +139,10 @@ public PageBuffer(int bufferSize, Wikipedia wiki, Set ids, Set t } /** - * If there are elements in the buffer left, then return true. If the end of the filled + * If there are elements in the buffer left, then return {@code true}. If the end of the filled * buffer is reached, then try to load new buffer. * - * @return True, if there are pages left. False otherwise. + * @return {@code True} if there are pages left, {@code false} otherwise. */ public boolean hasNext() { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageQuery.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageQuery.java index 343640d9..8255d619 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageQuery.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageQuery.java @@ -85,6 +85,9 @@ public class PageQuery */ private int maxTokens; + /** + * Instantiates a new {@link PageQuery} with default values. + */ public PageQuery() { onlyDisambiguationPages = false; @@ -108,66 +111,105 @@ public PageQuery() } + /** + * @return Retrieves the upper category limit. + */ protected int getMaxCategories() { return maxCategories; } + /** + * @return Retrieves the upper in-degree limit. + */ protected int getMaxIndegree() { return maxIndegree; } + /** + * @return Retrieves the upper out-degree limit. + */ protected int getMaxOutdegree() { return maxOutdegree; } + /** + * @return Retrieves the upper redirect limit. + */ protected int getMaxRedirects() { return maxRedirects; } + /** + * @return Retrieves the lower category limit. + */ protected int getMinCategories() { return minCategories; } + /** + * @return Retrieves the lower in-degree limit. + */ protected int getMinIndegree() { return minIndegree; } + /** + * @return Retrieves the lower out-degree limit. + */ protected int getMinOutdegree() { return minOutdegree; } + /** + * @return Retrieves the lower redirect limit. + */ protected int getMinRedirects() { return minRedirects; } + /** + * @return {@code True} if only full article pages shall be fetched, {@code false} otherwise. + */ protected boolean onlyArticlePages() { return onlyArticlePages; } + /** + * @return {@code True} if only disambiguation pages shall be fetched, {@code false} otherwise. + */ protected boolean onlyDisambiguationPages() { return onlyDisambiguationPages; } + /** + * @return Retrieves the lower token limit. + */ protected int getMinTokens() { return minTokens; } + /** + * @return Retrieves the upper token limit. + */ protected int getMaxTokens() { return maxTokens; } + /** + * @return Retrieves the pattern for titles. + */ protected String getTitlePattern() { return titlePattern; diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageQueryIterable.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageQueryIterable.java index 45989dca..f2a5a151 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageQueryIterable.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageQueryIterable.java @@ -44,6 +44,14 @@ public class PageQueryIterable private final Wikipedia wiki; private final List pageIdList; + /** + * Instantiates a new {@link PageQueryIterable} via a {@link PageQuery}. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param q The {@link PageQuery} to process. Must not be {@code null}. + * + * @throws WikiApiException Thrown if errors occurred. + */ public PageQueryIterable(Wikipedia wiki, PageQuery q) throws WikiApiException { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageQueryIterator.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageQueryIterator.java index d2143d6c..2c4e9be5 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageQueryIterator.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/PageQueryIterator.java @@ -39,6 +39,12 @@ public class PageQueryIterator private int iterPosition; private final List pageIDs; + /** + * Instantiates a new {@link PageQueryIterable} via a {@link PageQuery}. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param pPageIDs A {@link List} of page ids to process. Must not be {@code null}. + */ public PageQueryIterator(Wikipedia wiki, List pPageIDs) { this.wiki = wiki; diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Title.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Title.java index db107daa..03583e88 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Title.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Title.java @@ -173,13 +173,16 @@ public String getSectionText() } /** - * @return The wikistyle title, with spaces replaced by underscores. + * @return The wikistyle title with spaces replaced by underscores. */ public String getWikiStyleTitle() { return wikiStyleTitle; } + /** + * @return The raw title with no replacements applied. + */ protected String getRawTitleText() { return rawTitleText; diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/TitleIterable.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/TitleIterable.java index dc50df60..4119cd98 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/TitleIterable.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/TitleIterable.java @@ -35,11 +35,23 @@ public class TitleIterable */ private int bufferSize = 5000; + /** + * Initializes a {@link TitleIterable} instance. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + */ public TitleIterable(Wikipedia wiki) { this.wiki = wiki; } + /** + * Initializes a {@link TitleIterator} instance. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param bufferSize The number of pages to be buffered after a query to the database. + * Higher bufferSize gives better performance, but require more memory. + */ public TitleIterable(Wikipedia wiki, int bufferSize) { this.wiki = wiki; diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/TitleIterator.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/TitleIterator.java index 3ed4a87e..8f609486 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/TitleIterator.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/TitleIterator.java @@ -33,6 +33,13 @@ public class TitleIterator private final TitleBuffer buffer; + /** + * Initializes a {@link TitleIterator} instance. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param bufferSize The number of pages to be buffered after a query to the database. + * Higher bufferSize gives better performance, but require more memory. + */ public TitleIterator(Wikipedia wiki, int bufferSize) { buffer = new TitleBuffer(bufferSize, wiki); diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/WikipediaInfo.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/WikipediaInfo.java index 3481890d..c4b41bdc 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/WikipediaInfo.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/WikipediaInfo.java @@ -58,6 +58,8 @@ public class WikipediaInfo * * @param pWiki * The wiki object. + * + * @throws WikiApiException Thrown if errors occurred. */ public WikipediaInfo(Wikipedia pWiki) throws WikiApiException { @@ -71,6 +73,8 @@ public WikipediaInfo(Wikipedia pWiki) throws WikiApiException * * @param pPages * A set of pages. Only this subset of wiki pages is used in the info object. + * + * @throws WikiApiException Thrown if errors occurred. */ public WikipediaInfo(Iterable pPages) throws WikiApiException { @@ -163,10 +167,8 @@ public int getNumberOfPages() * @param pNodes * The category nodes that should be used to build the map. * @return A mapping from categories to article sets. - * @throws WikiPageNotFoundException */ private Map> getCategoryArticleMap(Wikipedia pWiki, Set pNodes) - throws WikiPageNotFoundException { Map> categoryArticleMap = new HashMap<>(); @@ -212,7 +214,7 @@ public void getGraphParameters(CategoryGraph catGraph) * The wikipedia object. * @param catGraph * The category graph. - * @throws WikiApiException + * @throws WikiApiException Thrown if errors occurred. */ public void getOverlapping(Wikipedia pWiki, CategoryGraph catGraph) throws WikiApiException { @@ -239,10 +241,8 @@ public void getOverlapping(Wikipedia pWiki, CategoryGraph catGraph) throws WikiA * @param pGraph * The category graph. * @return The number of articles that have at least one category in common. - * @throws WikiPageNotFoundException */ private int getArticlesWithOverlappingCategories(Wikipedia pWiki, CategoryGraph pGraph) - throws WikiPageNotFoundException { Set overlappingArticles = new HashSet<>(); @@ -284,28 +284,44 @@ private int getArticlesWithOverlappingCategories(Wikipedia pWiki, CategoryGraph return overlappingArticles.size(); } - public void getCategorizedArticles(Wikipedia pWiki, CategoryGraph catGraph) + /** + * Retrieves categorized articles and prints the result as a summary. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param catGraph A {@link CategoryGraph} to be used for traversal and report generation. + * @throws WikiApiException Thrown if errors occurred. + */ + public void getCategorizedArticles(Wikipedia wiki, CategoryGraph catGraph) throws WikiApiException { double startTime = System.currentTimeMillis(); - int numberOfCategorizedArticles = getNumberOfCategorizedArticles(pWiki, catGraph); + int numberOfCategorizedArticles = getNumberOfCategorizedArticles(wiki, catGraph); double categorizedArticlesRatio = (double) numberOfCategorizedArticles - / (double) pWiki.getMetaData().getNumberOfPages(); + / (double) wiki.getMetaData().getNumberOfPages(); logger.info("Categorized articles: {}", numberOfCategorizedArticles); - logger.info("All articles: {}", pWiki.getMetaData().getNumberOfPages()); + logger.info("All articles: {}", wiki.getMetaData().getNumberOfPages()); logger.info("Ratio: {}", categorizedArticlesRatio); double endTime = (System.currentTimeMillis() - startTime) / 1000.0; logger.debug("{}ms", endTime); } - public double getAveragePathLengthFromRoot(Wikipedia pWiki, CategoryGraph connectedCatGraph) + /** + * Computes the average path length starting from a root page. + * + * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}. + * @param connectedCatGraph A {@link CategoryGraph} to be used for traversal. + * + * @return The averaged path length computed for {@code connectedCatGraph}. + * @throws WikiApiException Thrown if errors occurred. + */ + public double getAveragePathLengthFromRoot(Wikipedia wiki, CategoryGraph connectedCatGraph) throws WikiApiException { // get root node - Category rootCategory = pWiki.getMetaData().getMainCategory(); + Category rootCategory = wiki.getMetaData().getMainCategory(); int root = rootCategory.getPageId(); int pathLengthSum = computeShortestPathLenghts(root, connectedCatGraph); @@ -322,6 +338,7 @@ public double getAveragePathLengthFromRoot(Wikipedia pWiki, CategoryGraph connec * @param catGraph * The category graph. * @return The number of categorized articles, i.e. articles that have at least one category. + * @throws WikiApiException Thrown if errors occurred. */ public int getNumberOfCategorizedArticles(Wikipedia pWiki, CategoryGraph catGraph) throws WikiApiException @@ -342,7 +359,7 @@ public int getNumberOfCategorizedArticles(Wikipedia pWiki, CategoryGraph catGrap * The category graph. * @return A map containing the distribution mapping from a degree to the number of times this * degree is found in the category graph. - * @throws WikiPageNotFoundException + * @throws WikiPageNotFoundException Thrown if parts in {@code catGraph} could not be found. */ public Map getDistributionOfArticlesByCategory(Wikipedia pWiki, CategoryGraph catGraph) diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiApiException.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiApiException.java index 7d5f38d6..30bd62fc 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiApiException.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiApiException.java @@ -17,27 +17,49 @@ */ package org.dkpro.jwpl.api.exception; +/** + * Signals a problematic situation which occurred using the API. + */ public class WikiApiException extends WikiException { private static final long serialVersionUID = 4780158247277092677L; + /** + * Creates an empty message {@link WikiException}. + */ public WikiApiException() { super(); } - public WikiApiException(String txt) + /** + * Creates a {@link WikiApiException} detailed by {@code message}. + * + * @param message The textual notification for the cause or error information. + */ + public WikiApiException(String message) { - super(txt); + super(message); } + /** + * Creates a {@link WikiApiException} detailed by {@code message}. + * + * @param message The textual notification for the cause or error information. + * @param cause The original {@link Throwable cause} that caused an exceptional situation. + */ public WikiApiException(String message, Throwable cause) { super(message, cause); } + /** + * Creates a {@link WikiApiException} detailed by {@code cause}. + * + * @param cause The original {@link Throwable cause} that caused an exceptional situation. + */ public WikiApiException(Throwable cause) { super(cause); diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiException.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiException.java index a242cd0a..ff3068dd 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiException.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiException.java @@ -17,27 +17,49 @@ */ package org.dkpro.jwpl.api.exception; +/** + * Represents a generic exceptional situation which occurred using JWPL. + */ public class WikiException extends Exception { private static final long serialVersionUID = 3891003920835683241L; + /** + * Creates an empty message {@link WikiApiException}. + */ public WikiException() { super(); } - public WikiException(String txt) + /** + * Creates a {@link WikiException} detailed by {@code message}. + * + * @param message The textual notification for the cause or error information. + */ + public WikiException(String message) { - super(txt); + super(message); } + /** + * Creates a {@link WikiException} detailed by {@code message}. + * + * @param message The textual notification for the cause or error information. + * @param cause The original {@link Throwable cause} that caused an exceptional situation. + */ public WikiException(String message, Throwable cause) { super(message, cause); } + /** + * Creates a {@link WikiException} detailed by {@code cause}. + * + * @param cause The original {@link Throwable cause} that caused an exceptional situation. + */ public WikiException(Throwable cause) { super(cause); diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiInitializationException.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiInitializationException.java index 7d965054..d64a3874 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiInitializationException.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiInitializationException.java @@ -18,7 +18,7 @@ package org.dkpro.jwpl.api.exception; /** - * Thrown, when the Wikipedia object could not be properly initialized. + * Thrown, when the {@link org.dkpro.jwpl.api.Wikipedia} object could not be properly initialized. */ public class WikiInitializationException extends WikiApiException @@ -26,21 +26,40 @@ public class WikiInitializationException private static final long serialVersionUID = 7240072132466204183L; + /** + * Creates an empty message {@link WikiInitializationException}. + */ public WikiInitializationException() { super(); } - public WikiInitializationException(String txt) + /** + * Creates an empty message {@link WikiInitializationException}. + * + * @param message The textual notification for the cause or error information. + */ + public WikiInitializationException(String message) { - super(txt); + super(message); } + /** + * Creates a {@link WikiInitializationException} detailed by {@code message}. + * + * @param message The textual notification for the cause or error information. + * @param cause The original {@link Throwable cause} that caused an exceptional situation. + */ public WikiInitializationException(String message, Throwable cause) { super(message, cause); } + /** + * Creates a {@link WikiInitializationException} detailed by {@code cause}. + * + * @param cause The original {@link Throwable cause} that caused an exceptional situation. + */ public WikiInitializationException(Throwable cause) { super(cause); diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiPageNotFoundException.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiPageNotFoundException.java index 39faaff8..e8adb71b 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiPageNotFoundException.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiPageNotFoundException.java @@ -26,21 +26,40 @@ public class WikiPageNotFoundException private static final long serialVersionUID = -3676016515948761351L; + /** + * Creates an empty message {@link WikiPageNotFoundException}. + */ public WikiPageNotFoundException() { super(); } - public WikiPageNotFoundException(String txt) + /** + * Creates a {@link WikiPageNotFoundException} detailed by {@code message}. + * + * @param message The textual notification for the cause or error information. + */ + public WikiPageNotFoundException(String message) { - super(txt); + super(message); } + /** + * Creates a {@link WikiPageNotFoundException} detailed by {@code message}. + * + * @param message The textual notification for the cause or error information. + * @param cause The original {@link Throwable cause} that caused an exceptional situation. + */ public WikiPageNotFoundException(String message, Throwable cause) { super(message, cause); } + /** + * Creates a {@link WikiPageNotFoundException} detailed by {@code cause}. + * + * @param cause The original {@link Throwable cause} that caused an exceptional situation. + */ public WikiPageNotFoundException(Throwable cause) { super(cause); diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiTitleParsingException.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiTitleParsingException.java index f5b4ba11..68786fe3 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiTitleParsingException.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/exception/WikiTitleParsingException.java @@ -26,21 +26,40 @@ public class WikiTitleParsingException private static final long serialVersionUID = 7152744066557304950L; + /** + * Creates an empty message {@link WikiTitleParsingException}. + */ public WikiTitleParsingException() { super(); } - public WikiTitleParsingException(String txt) + /** + * Creates a {@link WikiTitleParsingException} detailed by {@code message}. + * + * @param message The textual notification for the cause or error information. + */ + public WikiTitleParsingException(String message) { - super(txt); + super(message); } + /** + * Creates a {@link WikiTitleParsingException} detailed by {@code message}. + * + * @param message The textual notification for the cause or error information. + * @param cause The original {@link Throwable cause} that caused an exceptional situation. + */ public WikiTitleParsingException(String message, Throwable cause) { super(message, cause); } + /** + * Creates a {@link WikiTitleParsingException} detailed by {@code message}. + * + * @param cause The original {@link Throwable cause} that caused an exceptional situation. + */ public WikiTitleParsingException(Throwable cause) { super(cause); diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/Category.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/Category.java index 733e9298..d70b4299 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/Category.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/Category.java @@ -20,6 +20,14 @@ import java.util.HashSet; import java.util.Set; +/** + * An object-relational entity which maps a {@link org.dkpro.jwpl.api.Category} + * to data attributes in a database. Those are persisted and retrieved by + * an OR mapper, such as Hibernate. + *

+ * It is accessed via an equally named class in the {@code api} package + * to hide session management from the user. + */ public class Category { private long id; @@ -36,6 +44,9 @@ public Category() { } + /** + * @return Retrieves the primary key identifying this persistent object. + */ public long getId() { return id; @@ -47,51 +58,81 @@ private void setId(long id) this.id = id; } + /** + * @return Retrieves the page identifier as used in Wikipedia. + */ public int getPageId() { return pageId; } + /** + * @param pageId The page identifier as used in Wikipedia. + */ public void setPageId(int pageId) { this.pageId = pageId; } + /** + * @return Retrieves a set of {@link Page pageIds} a {@link Category} is referenced from. + */ public Set getInLinks() { return inLinks; } + /** + * @param inLinks A set of {@link Page pageIds} this {@link Category} is referenced from. + */ public void setInLinks(Set inLinks) { this.inLinks = inLinks; } + /** + * @return Retrieves the category title as used in Wikipedia. + */ public String getName() { return name; } + /** + * @param name The category title as used in Wikipedia. + */ public void setName(String name) { this.name = name; } + /** + * @return Retrieves a set of {@link Page pageIds} a {@link Category} references to. + */ public Set getOutLinks() { return outLinks; } + /** + * @param outLinks A set of {@link Page pageIds} a {@link Category} references to. + */ public void setOutLinks(Set outLinks) { this.outLinks = outLinks; } + /** + * @return Retrieves a set of {@link Page pages} a {@link Category} groups together. + */ public Set getPages() { return pages; } + /** + * @param pages The set of {@link Page pages} a {@link Category} groups together. + */ public void setPages(Set pages) { this.pages = pages; diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/CategoryDAO.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/CategoryDAO.java index d2f1442e..dcc78e80 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/CategoryDAO.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/CategoryDAO.java @@ -26,8 +26,8 @@ /** * Data access object for class {@link Category} * - * @author Hibernate Tools * @see org.dkpro.jwpl.api.Category + * @see org.dkpro.jwpl.api.hibernate.Category */ public class CategoryDAO extends GenericDAO @@ -36,9 +36,14 @@ public class CategoryDAO private static final Logger logger = LoggerFactory .getLogger(MethodHandles.lookup().lookupClass()); - public CategoryDAO(Wikipedia pWiki) + /** + * Instantiates a {@link CategoryDAO}. + * + * @param wiki A valid {@link Wikipedia} instance. Must not be {@code null}. + */ + public CategoryDAO(Wikipedia wiki) { - super(pWiki, Category.class); + super(wiki, Category.class); } @Override diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/GenericDAO.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/GenericDAO.java index 4595a302..4d742c6c 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/GenericDAO.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/GenericDAO.java @@ -27,7 +27,7 @@ import org.slf4j.LoggerFactory; /** - * A common base class for DAO classes. + * An abstract, common base class for DAO classes. * * @param * The entity type to provide persistence features for. @@ -65,11 +65,19 @@ private SessionFactory getSessionFactory() return sessionFactory; } + /** + * @return Retrieves the current {@link Session} instance. + */ protected Session getSession() { return getSessionFactory().getCurrentSession(); } + /** + * Persists a transient or existing instance of {@link T}. + * + * @param transientInstance The instance of {@link T} to persist. + */ public void persist(T transientInstance) { logger.debug("persisting MetaData instance"); @@ -83,6 +91,11 @@ public void persist(T transientInstance) } } + /** + * Deletes an existing instance of {@link T} from the persistence store. + * + * @param persistentInstance The instance of {@link T} to delete. + */ public void delete(T persistentInstance) { try { @@ -95,6 +108,13 @@ public void delete(T persistentInstance) } } + /** + * Reattaches (merges) a detached instance of {@link T} to a session context. + * + * @param detachedInstance The instance of {@link T} to re-attach, aka merge. + * @return A merged representation of the specified {@code detachedInstance}, reflecting the last valid + * state in the current session, aka persistence context. + */ public T merge(T detachedInstance) { try { @@ -108,6 +128,11 @@ public T merge(T detachedInstance) } } + /** + * Attaches and locks a new (clean) instance of {@link T} to a session context. + * + * @param instance The instance of {@link T} to attach. + */ public void attachClean(T instance) { try { @@ -120,6 +145,11 @@ public void attachClean(T instance) } } + /** + * Reattaches (merges) an existing instance of {@link T} to a session context. + * + * @param instance The instance of {@link T} to attach. + */ public void attachDirty(T instance) { try { @@ -132,6 +162,12 @@ public void attachDirty(T instance) } } + /** + * Retrieves an instance of {@link T} via its primary key, specified by {@code id}. + * + * @param id The primary key associated with the instance of {@link T}. + * @return A valid instance of {@link T} or {@code null} if no match can be retrieved for {@code id}. + */ public T findById(Long id) { try { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/MetaData.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/MetaData.java index 70854505..4aedb2eb 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/MetaData.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/MetaData.java @@ -17,6 +17,14 @@ */ package org.dkpro.jwpl.api.hibernate; +/** + * An object-relational entity which maps a {@link org.dkpro.jwpl.api.MetaData} + * to data attributes in a database. Those are persisted and retrieved by + * an OR mapper, such as Hibernate. + *

+ * It is accessed via an equally named class in the {@code api} package + * to hide session management from the user. + */ public class MetaData { @@ -39,91 +47,145 @@ public MetaData() { } + /** + * @return Retrieves the category title used for disambiguation. + */ public String getDisambiguationCategory() { return disambiguationCategory; } + /** + * @param disambiguationCategory The category title used for disambiguation. + */ public void setDisambiguationCategory(String disambiguationCategory) { this.disambiguationCategory = disambiguationCategory; } + /** + * @return Retrieves the title of main (or root) category associated with this Wikipedia. + */ public String getMainCategory() { return mainCategory; } + /** + * @param mainCategory The title of the main (or root) category associated with this Wikipedia. + */ public void setMainCategory(String mainCategory) { this.mainCategory = mainCategory; } - public long getNrofCategories() - { - return nrofCategories; - } - - public long getNrofDisambiguationPages() - { - return nrofDisambiguationPages; - } - - public long getNrofPages() - { - return nrofPages; - } - - public long getNrofRedirects() - { - return nrofRedirects; - } - + /** + * @return Retrieves the primary key identifying a {@link MetaData} instance. + */ public long getId() { return id; } + /** + * @param id The primary key identifying a {@link MetaData} instance. + */ public void setId(long id) { this.id = id; } + /** + * @return Retrieves the main language associated by the {@link MetaData} of a Wikipedia instance. + */ public String getLanguage() { return language; } + /** + * @param language The main language associated by the {@link MetaData} of a Wikipedia instance. + */ public void setLanguage(String language) { this.language = language; } + /** + * @return Retrieves the total number of available categories for a Wikipedia instance. + */ + public long getNrofCategories() + { + return nrofCategories; + } + + /** + * @param nrofCategories The total number of available categories for a Wikipedia instance. + */ public void setNrofCategories(long nrofCategories) { this.nrofCategories = nrofCategories; } + /** + * @return Retrieves the total number of disambiguation pages for a Wikipedia instance. + */ + public long getNrofDisambiguationPages() + { + return nrofDisambiguationPages; + } + + /** + * @param nrofDisambiguationPages The total number of disambiguation pages for a Wikipedia instance. + */ public void setNrofDisambiguationPages(long nrofDisambiguationPages) { this.nrofDisambiguationPages = nrofDisambiguationPages; } + /** + * @return Retrieves the total number of pages for a Wikipedia instance. + */ + public long getNrofPages() + { + return nrofPages; + } + + /** + * @param nrofPages The total number of pages for a Wikipedia instance. + */ public void setNrofPages(long nrofPages) { this.nrofPages = nrofPages; } + /** + * @return Retrieves the total number of redirects for a Wikipedia instance. + */ + public long getNrofRedirects() + { + return nrofRedirects; + } + + /** + * @param nrofRedirects The total number of redirects for a Wikipedia instance. + */ public void setNrofRedirects(long nrofRedirects) { this.nrofRedirects = nrofRedirects; } + /** + * @return Retrieves the version of a {@link MetaData} instance. + */ public String getVersion() { return version; } + /** + * @param version The version of a {@link MetaData} instance. + */ public void setVersion(String version) { this.version = version; diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/MetaDataDAO.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/MetaDataDAO.java index 0d0687f2..d47048eb 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/MetaDataDAO.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/MetaDataDAO.java @@ -27,8 +27,8 @@ /** * Data access object for class {@link MetaData}. * - * @author Hibernate Tools * @see org.dkpro.jwpl.api.MetaData + * @see org.dkpro.jwpl.api.hibernate.MetaData */ public class MetaDataDAO extends GenericDAO @@ -38,6 +38,11 @@ public class MetaDataDAO private static final Logger logger = LoggerFactory .getLogger(MethodHandles.lookup().lookupClass()); + /** + * Instantiates a {@link MetaDataDAO}. + * + * @param wiki A valid {@link Wikipedia} instance. Must not be {@code null}. + */ public MetaDataDAO(Wikipedia wiki) { super(wiki, MetaData.class); diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/Page.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/Page.java index aa8f416b..cb8a3a21 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/Page.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/Page.java @@ -21,8 +21,12 @@ import java.util.Set; /** - * The page class that is actually persisted by Hibernate. It is accessed via a equally named class - * in the api package to hide session management from the user. + * An object-relational entity which maps a {@link org.dkpro.jwpl.api.Page} + * to data attributes in a database. Those are persisted and retrieved by + * an OR mapper, such as Hibernate. + *

+ * It is accessed via an equally named class in the {@code api} package + * to hide session management from the user. */ public class Page { @@ -44,6 +48,9 @@ public Page() { } + /** + * @return Retrieves the primary key identifying this persistent object. + */ public long getId() { return id; @@ -55,86 +62,137 @@ private void setId(long id) this.id = id; } + /** + * @return Retrieves the page identifier as used in Wikipedia. + */ public int getPageId() { return pageId; } + /** + * @param pageId The page identifier as used in Wikipedia. + */ public void setPageId(int pageId) { this.pageId = pageId; } + /** + * @return Retrieves a set of {@link Category categoryIDs} a {@link Page} is found in. + */ public Set getCategories() { return categories; } + /** + * @param categories A set of {@link Category categoryIDs} a {@link Page} is found in. + */ public void setCategories(Set categories) { this.categories = categories; } + /** + * @return Retrieves a set of {@link Page pageIds} a {@link Page} is referenced from. + */ public Set getInLinks() { return inLinks; } + /** + * @param inLinks set of {@link Page pageIds} this {@link Page} is referenced from. + */ public void setInLinks(Set inLinks) { this.inLinks = inLinks; } + /** + * @return Retrieves the page title as used in Wikipedia. + */ public String getName() { return name; } + /** + * @param name The page title as used in Wikipedia. + */ public void setName(String name) { this.name = name; } + /** + * @return Retrieves a set of {@link Page pageIds} a {@link Page} references to. + */ public Set getOutLinks() { return outLinks; } + /** + * @return Retrieves the cardinality of outgoing page references. + */ public int getOutDegree() { return outLinks.size(); } + /** + * @param outLinks A set of {@link Page pageIds} a {@link Page} references to. + */ public void setOutLinks(Set outLinks) { this.outLinks = outLinks; } + /** + * @return Retrieves a set of {@link String redirects} which exist for a {@link Page}. + */ public Set getRedirects() { return redirects; } + /** + * @param redirects A set of {@link String redirects} which exist for a {@link Page}. + */ public void setRedirects(Set redirects) { this.redirects = redirects; } + /** + * @return Retrieves a page's content (text) as used in Wikipedia. + */ public String getText() { return text; } + /** + * @param text The page's content (text) as used in Wikipedia. + */ public void setText(String text) { this.text = text; } + /** + * @return {@code True} if a page is a disambiguation page, {@code false} otherwise. + */ public boolean getIsDisambiguation() { return isDisambiguation; } + /** + * @param isDisambiguation {@code True} if a page is a disambiguation page, {@code false} otherwise. + */ public void setIsDisambiguation(Boolean isDisambiguation) { if (isDisambiguation == null) { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/PageDAO.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/PageDAO.java index b583aadc..bda599f0 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/PageDAO.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/PageDAO.java @@ -26,8 +26,8 @@ /** * Data access object for class {@link Page}. * - * @author Hibernate Tools * @see org.dkpro.jwpl.api.Page + * @see org.dkpro.jwpl.api.hibernate.Page */ public class PageDAO extends GenericDAO @@ -36,9 +36,14 @@ public class PageDAO private static final Logger logger = LoggerFactory .getLogger(MethodHandles.lookup().lookupClass()); - public PageDAO(Wikipedia pWiki) + /** + * Instantiates a {@link PageDAO}. + * + * @param wiki A valid {@link Wikipedia} instance. Must not be {@code null}. + */ + public PageDAO(Wikipedia wiki) { - super(pWiki, Page.class); + super(wiki, Page.class); } @Override diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/PageMapLine.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/PageMapLine.java index 41ff5c78..d111c7ac 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/PageMapLine.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/PageMapLine.java @@ -17,6 +17,10 @@ */ package org.dkpro.jwpl.api.hibernate; +/** + * An object-relational entity to reflect data attributes in a database. + * Eventually, those are retrieved by an OR mapper, such as Hibernate. + */ public class PageMapLine { private long id; @@ -32,51 +36,79 @@ public PageMapLine() { } + /** + * @return Retrieves the primary key identifying this persistent object. + */ public long getId() { return id; } - public void setId(long id) + @SuppressWarnings("unused") + private void setId(long id) { this.id = id; } + /** + * @return Retrieves the name as used in Wikipedia. + */ public String getName() { return name; } + /** + * @param name The name as used in Wikipedia. + */ public void setName(String name) { this.name = name; } + /** + * @return Retrieves the page identifier as used in Wikipedia. + */ public int getPageID() { return pageID; } + /** + * @param pageID The page identifier as used in Wikipedia. + */ public void setPageID(int pageID) { this.pageID = pageID; } + /** + * @return Retrieves the lemma. + */ public String getLemma() { return lemma; } + /** + * @param lemma The lemma to set. + */ public void setLemma(String lemma) { this.lemma = lemma; } + /** + * @return Retrieves the stem. + */ public String getStem() { return stem; } + /** + * @param stem The stem to set. + */ public void setStem(String stem) { this.stem = stem; diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/WikiHibernateUtil.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/WikiHibernateUtil.java index 256f7830..77066755 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/WikiHibernateUtil.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/hibernate/WikiHibernateUtil.java @@ -27,12 +27,23 @@ import org.hibernate.boot.registry.StandardServiceRegistryBuilder; import org.hibernate.cfg.Configuration; +/** + * A utility class which provides access to underlying Hibernate session factories. + */ public class WikiHibernateUtil implements WikiConstants { private static final Map sessionFactoryMap = new HashMap<>(); + /** + * Retrieves (and creates) a {@link SessionFactory} for a specified {@link DatabaseConfiguration}. + * + * @param config The {@link DatabaseConfiguration} to obtain the factory for. Must not be {@code null}. + * @return A fully initialized {@link SessionFactory} instance. + * + * @throws ExceptionInInitializerError Thrown if the {@code config} instance was incorrect or incomplete. + */ public static SessionFactory getSessionFactory(DatabaseConfiguration config) { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/sweble/PlainTextConverter.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/sweble/PlainTextConverter.java index 7e59c7d2..cc7ff012 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/sweble/PlainTextConverter.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/sweble/PlainTextConverter.java @@ -212,16 +212,34 @@ protected Object after(WtNode node, Object result) * // write("<"); // write(n.getNodeName()); // write(" />"); } */ + /** + * Called when a {@link WtNodeList node list} is about to be processed. + * + * @param n + * A node representing a node list. + */ public void visit(WtNodeList n) { iterate(n); } + /** + * Called when a {@link WtPage page} is about to be processed. + * + * @param p + * A node representing a page element. + */ public void visit(WtPage p) { iterate(p); } + /** + * Called when a {@link AstText text element} is about to be processed. + * + * @param text + * A node representing a text element. + */ public void visit(AstText text) { if (currentCell != null) { @@ -235,11 +253,23 @@ public void visit(AstText text) } + /** + * Called when a {@link WtItalics whitespace} is about to be processed. + * + * @param w + * A node representing a whitespace element. + */ public void visit(WtWhitespace w) { write(" "); } + /** + * Called when a {@link WtItalics bold element} is about to be processed. + * + * @param b + * A node representing a bold formatted element. + */ public void visit(WtBold b) { // write("**"); @@ -247,6 +277,12 @@ public void visit(WtBold b) // write("**"); } + /** + * Called when an {@link WtItalics italic element} is about to be processed. + * + * @param i + * A node representing an italic formatted element. + */ public void visit(WtItalics i) { // write("//"); @@ -254,14 +290,25 @@ public void visit(WtItalics i) // write("//"); } + /** + * Called when a {@link WtXmlCharRef character reference} is about to be processed. + * + * @param cr + * A node representing a character reference. + */ public void visit(WtXmlCharRef cr) { write(Character.toChars(cr.getCodePoint())); } + /** + * Called when a {@link WtXmlEntityRef entity reference} is about to be processed. + * + * @param er + * A node representing an entity reference. + */ public void visit(WtXmlEntityRef er) { - String ch = er.getResolved(); if (ch == null) { write('&'); @@ -273,6 +320,12 @@ public void visit(WtXmlEntityRef er) } } + /** + * Called when a {@link WtUrl URL} is about to be processed. + * + * @param url + * A node representing a URL. + */ public void visit(WtUrl url) { write(url.getProtocol()); @@ -280,6 +333,12 @@ public void visit(WtUrl url) write(url.getPath()); } + /** + * Called when an {@link WtExternalLink external link} is about to be processed. + * + * @param link + * A node representing an external link. + */ public void visit(WtExternalLink link) { // TODO How should we represent external links in the plain text output? @@ -288,6 +347,12 @@ public void visit(WtExternalLink link) write(']'); } + /** + * Called when an {@link WtInternalLink internal link} is about to be processed. + * + * @param link + * A node representing an internal link. + */ public void visit(WtInternalLink link) { currentLinkTitleInCell = null; @@ -323,6 +388,12 @@ public void visit(WtInternalLink link) write(link.getPostfix()); } + /** + * Called when a {@link WtSection section} is about to be processed. + * + * @param s + * A node representing a section. + */ public void visit(WtSection s) { finishLine(); @@ -381,12 +452,24 @@ public void visit(WtSection s) sections.add(sections.removeLast() + 1); } + /** + * Called when a {@link WtParagraph paragraph} is about to be processed. + * + * @param p + * A node representing a paragraph. + */ public void visit(WtParagraph p) { iterate(p); newline(1); } + /** + * Called when a {@link WtHorizontalRule rule} is about to be processed. + * + * @param hr + * A node representing a horizontal rule. + */ public void visit(WtHorizontalRule hr) { newline(1); @@ -394,6 +477,13 @@ public void visit(WtHorizontalRule hr) // newline(1); } + + /** + * Called when an {@link WtXmlElement XML element} is about to be processed. + * + * @param e + * A node representing an XML element. + */ public void visit(WtXmlElement e) { if (e.getName().equalsIgnoreCase("br")) { @@ -404,16 +494,34 @@ public void visit(WtXmlElement e) } } + /** + * Called when an {@link WtXmlEndTag XML end tag} is about to be processed. + * + * @param t + * A node representing an XML end tag. + */ public void visit(WtXmlEndTag t) { iterate(t); } + /** + * Called when an {@link WtXmlAttribute XML attribute} is about to be processed. + * + * @param n + * A node representing an XML attribute. + */ public void visit(WtXmlAttribute n) { // ignore formatting information from xml attributes as the result is expected in plain text } + /** + * Called when a {@link WtListItem list item} is about to be processed. + * + * @param n + * A node representing a list item. + */ public void visit(WtListItem n) { iterate(n); @@ -521,30 +629,72 @@ private void processCellContent(WtInnerNode2 n) // ========================================================================= // Stuff we want to hide + /** + * Called when an {@link WtImageLink image link} is about to be processed. + * + * @param n + * A node representing an image link. + */ public void visit(WtImageLink n) { } + /** + * Called when an {@link WtIllegalCodePoint illegal code point} is about to be processed. + * + * @param n + * A node representing an illegal code point. + */ public void visit(WtIllegalCodePoint n) { } + /** + * Called when an {@link WtXmlComment XML comment} is about to be processed. + * + * @param n + * A node representing an XML comment. + */ public void visit(WtXmlComment n) { } + /** + * Called when a {@link WtTemplate template} is about to be processed. + * + * @param n + * A node representing a template. + */ public void visit(WtTemplate n) { } + /** + * Called when a {@link WtTemplateArgument template argument} is about to be processed. + * + * @param n + * A node representing a template argument. + */ public void visit(WtTemplateArgument n) { } + /** + * Called when a {@link WtTemplateArgument template parameter} is about to be processed. + * + * @param n + * A node representing a template parameter. + */ public void visit(WtTemplateParameter n) { } + /** + * Called when a {@link WtTagExtension tag extension} is about to be processed. + * + * @param n + * A node representing a tag extension. + */ public void visit(WtTagExtension n) { } diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/sweble/TemplateNameExtractor.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/sweble/TemplateNameExtractor.java index 06aa1425..7357a0fd 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/sweble/TemplateNameExtractor.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/sweble/TemplateNameExtractor.java @@ -52,7 +52,7 @@ public class TemplateNameExtractor /** * Creates a new visitor that extracts anchors of internal links from a parsed Wikipedia article - * using the default Sweble config as defined in WikiConstants.SWEBLE_CONFIG. + * using the default Sweble config as defined in {@link org.dkpro.jwpl.api.WikiConstants#SWEBLE_CONFIG}. */ public TemplateNameExtractor() { @@ -87,11 +87,21 @@ protected Object after(WtNode node, Object result) // ========================================================================= + /** + * Called when a {@link WtNode node} instance is processed. + * @param n The node which is visited. + */ public void visit(WtNode n) { iterate(n); } + /** + * Called when a {@link WtTemplate template} instance is processed. + * @param tmpl The template which is visited. + * + * @throws IOException Thrown if IO errors occurred. + */ public void visit(WtTemplate tmpl) throws IOException { for (AstNode n : tmpl.getName()) { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/ApiUtilities.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/ApiUtilities.java index d2c23e30..065a7171 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/ApiUtilities.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/ApiUtilities.java @@ -22,6 +22,9 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; +/** + * Provides extra method(s) for working with the JWPL API. + */ public class ApiUtilities { @@ -29,11 +32,18 @@ public class ApiUtilities .getLogger(MethodHandles.lookup().lookupClass()); /** - * DOTS - print progress dots. TEXT - print a message with progress in percent. + * The mode of printing progress. */ public enum ProgressInfoMode { - DOTS, TEXT + /** + * DOTS - print progress dots. + */ + DOTS, + /** + * TEXT - print a message with progress in percent. + */ + TEXT } /** diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/CommonUtilities.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/CommonUtilities.java index 391a39a7..e16ca15d 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/CommonUtilities.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/CommonUtilities.java @@ -21,11 +21,14 @@ import java.util.Map; import java.util.Set; +/** + * Provides utility methods to extract certain information from collections. + */ public class CommonUtilities { /** - * Debug output an internal set structure. + * Debug output an internal {@link Set} structure. * * @param s * Must not be {@code null}. @@ -53,7 +56,7 @@ public static String getSetContents(Set s) } /** - * Debug output an internal map structure as key-value pairs. + * Debug output an internal {@link Map} structure as key-value pairs. * * @param m * Must not be {@code null}. diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/DbUtilities.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/DbUtilities.java index 6cd3ffe7..e1493bd1 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/DbUtilities.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/DbUtilities.java @@ -27,6 +27,8 @@ import org.slf4j.LoggerFactory; /** + * Provides extra method(s) for working directly with a database. + * * @deprecated To be removed without replacement. */ @Deprecated(since = "2.0.0", forRemoval = true) @@ -38,11 +40,22 @@ public class DbUtilities private static final Logger logger = LoggerFactory .getLogger(MethodHandles.lookup().lookupClass()); + /** + * Instantiates a {@link DbUtilities} object. + * + * @param conn A valid {@link Connection} instance. Must not be {@code null}. + */ public DbUtilities(Connection conn) { this.conn = conn; } + /** + * Checks if a table identified by {@code tableName} exists on the currently connected database. + * + * @param tableName The name of the table to check for. Must not be {@code null}. + * @return {@code True} if it exists, {@code false} otherwise. + */ public boolean tableExists(String tableName) { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/GraphUtilities.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/GraphUtilities.java index c66ea71a..5c9455e0 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/GraphUtilities.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/GraphUtilities.java @@ -26,6 +26,11 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; +/** + * Provides helpful methods for traversing or sampling page graphs. + * + * @deprecated To be removed without replacement. + */ public class GraphUtilities { @@ -33,6 +38,15 @@ public class GraphUtilities .getLogger(MethodHandles.lookup().lookupClass()); /** + * Get a random subset (of {@code pResultSetSize}) of the page set passed to the method. + * + * @param pages + * The pages. + * @param pResultSetSize + * The size of the result set. + * @return A random subset of the original page set of the given size or null, if the requested + * subset size is larger than the original page set. + * * @deprecated Use {@link #getRandomPageSubset(Set, int)} instead. */ @Deprecated(since = "2.0.0", forRemoval = true) @@ -46,7 +60,7 @@ public static Set getRandomPageSubset(Iterable pages, int pResult } /** - * Get a random subset (of size pSize) of the page set passed to the method. + * Get a random subset (of {@code pResultSetSize}) of the page set passed to the method. * * @param pPageIDs * The pages. diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/HibernateUtilities.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/HibernateUtilities.java index 254a4610..43feb394 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/HibernateUtilities.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/HibernateUtilities.java @@ -26,6 +26,8 @@ import org.hibernate.Session; /** + * Provides helpful methods for working with the ORM Hibernate. + * * @deprecated To be removed without replacement. */ @Deprecated(since = "2.0.0", forRemoval = true) @@ -35,7 +37,13 @@ public class HibernateUtilities private final DatabaseConfiguration dbConfig; - public HibernateUtilities(Language pLanguage, DatabaseConfiguration dbConfig) + /** + * Instantiates {@link HibernateUtilities} via a {@code dbConfig} for a certain {@code language}. + * + * @param language The language to use as a constraint. + * @param dbConfig A valid {@link DatabaseConfiguration} instance, ready to use. + */ + public HibernateUtilities(Language language, DatabaseConfiguration dbConfig) { this.dbConfig = dbConfig; } diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/OS.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/OS.java index b0aeb68e..9d294146 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/OS.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/OS.java @@ -17,6 +17,11 @@ */ package org.dkpro.jwpl.api.util; +/** + * Provides helpful methods for working with runtime environment on a certain operating system (OS). + * + * @deprecated To be removed without replacement. + */ public class OS { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/SerializableDirectedGraph.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/SerializableDirectedGraph.java index be7b6c98..fb01d4ac 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/SerializableDirectedGraph.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/SerializableDirectedGraph.java @@ -38,13 +38,16 @@ public final class SerializableDirectedGraph */ private static final long serialVersionUID = -192220033577521277L; + /** + * The directed graph instance. + */ private final DefaultDirectedGraph graph; /** - * This Constructor is intended to be used before the serialization of the
- * directed graph. + * Instantiates a new {@link SerializableDirectedGraph} object. + * This Constructor is intended to be used before the serialization of the directed graph. * - * @param graph + * @param graph The {@link DefaultDirectedGraph directed graph} to serialize */ public SerializableDirectedGraph(DefaultDirectedGraph graph) { @@ -52,7 +55,7 @@ public SerializableDirectedGraph(DefaultDirectedGraph grap } /** - * @return A {@link DefaultDirectedGraph graph} instance. + * @return Returns the wrapped {@link DefaultDirectedGraph graph} instance. */ public DefaultDirectedGraph getGraph() { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/StringUtils.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/StringUtils.java index b14cee97..60a7be56 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/StringUtils.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/StringUtils.java @@ -20,6 +20,9 @@ import java.util.Collection; import java.util.Iterator; +/** + * Provides methods to manipulate strings for special use cases. + */ public class StringUtils { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/UnmodifiableArraySet.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/UnmodifiableArraySet.java index 809c67a5..3d13000d 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/UnmodifiableArraySet.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/UnmodifiableArraySet.java @@ -22,17 +22,33 @@ import java.util.Iterator; import java.util.Set; +/** + * An implementation of {@link Set} which is based on an array and can not be modified + * via {@link Set#add(Object)} or {@link Set#remove(Object)}, or similar bulk-wise methods. + * + * @param The type for the elements contained in the {@link Set}, kept by the underlying array. + */ public class UnmodifiableArraySet implements Set { private final Object[] data; + /** + * Instantiates a new {@link UnmodifiableArraySet} via the specified array of {@link E} elements. + * + * @param aData A non-empty array of {@link E} elements. + */ public UnmodifiableArraySet(E[] aData) { data = new Object[aData.length]; System.arraycopy(aData, 0, data, 0, data.length); } + /** + * Instantiates a new {@link UnmodifiableArraySet} via the specified set of {@link E} elements. + * + * @param aData A non-empty {@link Set} of {@link E} elements. + */ public UnmodifiableArraySet(Set aData) { data = new Object[aData.size()]; diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/distance/LevenshteinStringDistance.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/distance/LevenshteinStringDistance.java index c4b2164a..1b427e5d 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/distance/LevenshteinStringDistance.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/distance/LevenshteinStringDistance.java @@ -17,6 +17,10 @@ */ package org.dkpro.jwpl.api.util.distance; +/** + * Provides an implementation of {@link StringDistance} to compute + * the editing according to Levenshtein. + */ public class LevenshteinStringDistance implements StringDistance { diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/distance/StringDistance.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/distance/StringDistance.java index b02ce5c4..36424f6d 100644 --- a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/distance/StringDistance.java +++ b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/util/distance/StringDistance.java @@ -17,9 +17,18 @@ */ package org.dkpro.jwpl.api.util.distance; +/** + * Provides methods to compute the editing distance among strings. + */ public interface StringDistance { + /** + * Computes the editing distance between {@code s1} and {@code s2}. + * @param s1 A non-empty string. Must not be {@code null}. + * @param s2 A non-empty string. Must not be {@code null}. + * @return The editing distance between {@code s1} and {@code s2}. + */ double distance(String s1, String s2); } diff --git a/dkpro-jwpl-revisionmachine/src/test/resources/db/wikiapi_simple_20090119_stripped.script b/dkpro-jwpl-revisionmachine/src/test/resources/db/wikiapi_simple_20090119_stripped.script index ba989eb7..7d4f5d8f 100644 --- a/dkpro-jwpl-revisionmachine/src/test/resources/db/wikiapi_simple_20090119_stripped.script +++ b/dkpro-jwpl-revisionmachine/src/test/resources/db/wikiapi_simple_20090119_stripped.script @@ -29,7 +29,7 @@ SET FILES NIO TRUE SET FILES NIO SIZE 256 SET FILES LOG TRUE SET FILES LOG SIZE 200 -SET FILES CHECK 2888 +SET FILES CHECK 3146 SET DATABASE COLLATION "German" NO PAD CREATE USER SA PASSWORD DIGEST 'd41d8cd98f00b204e9800998ecf8427e' CREATE SCHEMA PUBLIC AUTHORIZATION DBA