commit 97cf26dc47b25477e2fc867336ae6ab200cdd31a Author: iwakeh iwakeh@torproject.org Date: Tue Jul 5 20:54:01 2016 +0000

Tweaked file structure and added cobertura. --- build.xml | 104 +++++++++++++++++++++++++++++++++------ resources/overview.html | 69 -------------------------- src/main/resources/overview.html | 69 ++++++++++++++++++++++++++ 3 files changed, 158 insertions(+), 84 deletions(-)

diff --git a/build.xml b/build.xml index f24c293..3f62199 100644 --- a/build.xml +++ b/build.xml @@ -1,13 +1,18 @@ <project default="jar" name="descriptor" basedir="."> <property name="release.version" value="1.2.0-dev" /> <property name="sources" value="src/main/java"/> - <property name="resources" value="resources"/> + <property name="resources" value="src/main/resources"/> <property name="generated" value="generated/"/> - <property name="classes" value="classes"/> - <property name="docs" value="javadoc"/> + <property name="classes" value="${generated}/classes"/> + <property name="docs" value="${generated}/javadoc"/> <property name="tests" value="src/test/java"/> <property name="testresources" value="src/test/resources/"/> + <property name="testresult" value="${generated}/test-results"/> + <property name="coverageresult" value="${generated}/coverage-report/"/> + <property name="instrument" value="${generated}/instrument/"/> + <property name="testclasses" value="${generated}/testclasses/"/> <property name="libs" value="lib"/> + <property name="cobertura.ser.file" value="${basedir}/cobertura.ser" /> <property name="jarfile" value="descriptor-${release.version}.jar" /> <property name="jarsourcesfile" value="descriptor-${release.version}-sources.jar" /> @@ -16,13 +21,15 @@ value="descriptor-${release.version}.tar.gz" /> <property file="build.properties" />

+ <patternset id="runtime" > + <include name="commons-compress-1.9.jar"/> + <include name="xz-1.5.jar"/> + </patternset> + <path id="classpath"> <pathelement path="${classes}"/> <fileset dir="${libs}"> - <include name="commons-compress-1.4.1.jar"/> - <include name="junit4-4.10.jar"/> - <include name="hamcrest-core-1.2.jar"/> - <include name="xz-1.0.jar"/> + <patternset refid="runtime" /> </fileset> </path>

@@ -32,10 +39,44 @@ </fileset> </path>

+ <path id="test.classpath"> + <pathelement path="${classes}"/> + <pathelement path="${testclasses}"/> + <pathelement path="${testresources}"/> + <fileset dir="${libs}"> + <patternset refid="runtime" /> + </fileset> + <fileset dir="${libs}"> + <include name="junit4-4.11.jar"/> + <include name="hamcrest-all-1.3.jar"/> + </fileset> + </path> + + <path id="cobertura.classpath"> + <fileset dir="${libs}"> + <include name="cobertura-2.1.1.jar" /> + <include name="slf4j-api-1.7.7.jar" /> + <include name="commons-lang3-3.3.2.jar" /> + <include name="asm4-5.0.3.jar" /> + <include name="asm4-util-5.0.3.jar" /> + <include name="asm4-tree-5.0.3.jar" /> + <include name="asm4-commons-5.0.3.jar" /> + <include name="asm4-analysis-5.0.3.jar" /> + <include name="oro-2.0.8.jar" /> + <include name="logback-core-1.1.2.jar" /> + <include name="logback-classic-1.1.2.jar" /> + </fileset> + </path> + + <path id="cobertura.test.classpath"> + <path location="${instrument}" /> + <path refid="test.classpath" /> + <path refid="cobertura.classpath" /> + </path> + <target name="clean" > - <delete includeEmptyDirs="true"> - <fileset dir="${classes}" defaultexcludes="false" includes="**" /> - <fileset dir="${docs}" defaultexcludes="false" includes="**" /> + <delete includeEmptyDirs="true" quiet="true"> + <fileset dir="${generated}" defaultexcludes="false" includes="**" /> </delete> <delete file="${jarfile}"/> <delete file="${jarsourcesfile}"/> @@ -44,8 +85,10 @@

<target name="init"> <mkdir dir="${classes}"/> + <mkdir dir="${testclasses}"/> <mkdir dir="${docs}"/> - <mkdir dir="${generated}"/> + <mkdir dir="${testresult}"/> + <mkdir dir="${instrument}"/> </target>

<target name="compile" @@ -78,7 +121,7 @@ </target>

<target name="testcompile" depends="init"> - <javac destdir="${classes}" + <javac destdir="${testclasses}" srcdir="${tests}" source="${source-and-target-java-version}" target="${source-and-target-java-version}" @@ -87,16 +130,16 @@ optimize="false" failonerror="true" includeantruntime="false"> - <classpath refid="classpath"/> + <classpath refid="test.classpath"/> </javac> </target>

<target name="test" depends="compile,testcompile"> <junit fork="true" haltonfailure="true" printsummary="off"> - <classpath refid="classpath"/> + <classpath refid="test.classpath"/> <formatter type="plain" usefile="false"/> <batchtest> - <fileset dir="${classes}" + <fileset dir="${testclasses}" includes="**/*Test.class"/> </batchtest> </junit> @@ -184,5 +227,36 @@ prefix="descriptor-${release.version}/${libs}" /> </tar> </target> + + <taskdef classpathref="cobertura.classpath" resource="tasks.properties" /> + <target name="coverage" depends="compile,testcompile"> + <copy todir="${instrument}" > + <fileset dir="${classes}"/> + </copy> + <cobertura-instrument ignoreTrivial="true"> + <fileset dir="${instrument}"> + <include name="**/**/*.class" /> + </fileset> + </cobertura-instrument> + <junit fork="true" haltonfailure="false" printsummary="on"> + <sysproperty key="net.sourceforge.cobertura.datafile" + file="${cobertura.ser.file}" /> + <classpath refid="cobertura.test.classpath" /> + <formatter type="xml" /> + <batchtest toDir="${testresult}" > + <fileset dir="${testclasses}" + includes="**/*Test.class"/> + </batchtest> + </junit> + <cobertura-report format="html" destdir="${coverageresult}" > + <fileset dir="${sources}"> + <include name="**/*.java" /> + </fileset> + </cobertura-report> + <cobertura-check branchrate="0" totallinerate="31" totalbranchrate="41" > + <regex pattern="org.torproject.descriptor.benchmark.*" branchrate="0" linerate="0"/> + </cobertura-check> + </target> + </project>

diff --git a/resources/overview.html b/resources/overview.html deleted file mode 100644 index f5c6b51..0000000 --- a/resources/overview.html +++ /dev/null @@ -1,69 +0,0 @@ -<html> -<body> -<p>DescripTor API, which is provided and supported by Tor's Metrics -Team, is a library to obtain and process descriptors containing Tor -network data. It is the main Java tool for processing Tor descriptors -and provides a standard API consisting of interfaces and a reference -implementation for all of them.</p> - -<p>Most Tor descriptors understood by this library are specified in the -<a href="https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt">Tor -directory protocol, version 3</a> or in the earlier -<a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v2.txt">version 2</a> or -<a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v1.txt">version 1</a> -of that document. -Other descriptors are specified on the -<a href="https://collector.torproject.org/">CollecTor website</a>.</p> - -<p>The interfaces in -<a href="./org/torproject/descriptor/package-summary.html">{@code org.torproject.descriptor}</a> -as well as their implementations in the -{@code org.torproject.descriptor.impl} package were driven by two main -goals originating from the primary use case to make Tor network data -accessible for statistical analysis:</p> - -<ul> -<li><em>Complete coverage:</em> This library is supposed to cover the -complete range of Tor descriptors made available by the -<a href="https://collector.torproject.org">CollecTor</a> service.</li> -<li><em>Runtime and memory efficiency:</em> Processing large amounts of -descriptors in bulk is supposed to be efficient in terms of runtime and -required memory.</li> -</ul> - -<p>At the same time the current design and implementation were done with a -number of non-goals in mind, even though some of these might turn into -goals in the future:</p> - -<p><ul> -<li><em>Verification:</em> The descriptor parser performs some basic -verifications of descriptor formats, but no cryptographic verifications. -It may not even be possible to write a cryptographic verification tool -using parsed descriptor contents, though this has not been attempted -yet.</li> -<li><em>Potentially lossy conversion:</em> Descriptor contents may be -converted to a format that is easier to process, even if that conversion -makes it harder or impossible to re-create the original descriptor -contents from a parsed descriptor.</li> -<li><em>Generating descriptors:</em> This library does not contain any -functionality to generate new descriptors for testing or related purposes, -neither from previously set data nor randomly.</li> -<li><em>Writing descriptors:</em> This library does not support writing -descriptors to the file system or a database, both of which are left to -the application. Stated differently, there are no descriptor sinks that -would correspond to the provided descriptor sources.</li> -</ul></p> - -<p>Hints about using DescripTor can be found in the -<a href="./org/torproject/descriptor/package-summary.html#package.description">{@code org.torproject.descriptor} package description</a>. -</p> - -<p>Contact and further information: -<ul> -<li><a href="https://trac.torproject.org/projects/tor/query?status=!closed&component=Metrics%2Fmetrics-lib">DescripTor Bug Tracker</a></li> -<li><a href="https://lists.torproject.org/cgi-bin/mailman/listinfo/metrics-team">Metrics Team Mailing List</a></li> -<li><a href="https://trac.torproject.org/projects/tor/wiki/org/teams/MetricsTeam">Metrics Team Website</a></li> -</ul> -</body> -</html> - diff --git a/src/main/resources/overview.html b/src/main/resources/overview.html new file mode 100644 index 0000000..f5c6b51 --- /dev/null +++ b/src/main/resources/overview.html @@ -0,0 +1,69 @@ +<html> +<body> +<p>DescripTor API, which is provided and supported by Tor's Metrics +Team, is a library to obtain and process descriptors containing Tor +network data. It is the main Java tool for processing Tor descriptors +and provides a standard API consisting of interfaces and a reference +implementation for all of them.</p> + +<p>Most Tor descriptors understood by this library are specified in the +<a href="https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt">Tor +directory protocol, version 3</a> or in the earlier +<a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v2.txt">version 2</a> or +<a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v1.txt">version 1</a> +of that document. +Other descriptors are specified on the +<a href="https://collector.torproject.org/">CollecTor website</a>.</p> + +<p>The interfaces in +<a href="./org/torproject/descriptor/package-summary.html">{@code org.torproject.descriptor}</a> +as well as their implementations in the +{@code org.torproject.descriptor.impl} package were driven by two main +goals originating from the primary use case to make Tor network data +accessible for statistical analysis:</p> + +<ul> +<li><em>Complete coverage:</em> This library is supposed to cover the +complete range of Tor descriptors made available by the +<a href="https://collector.torproject.org">CollecTor</a> service.</li> +<li><em>Runtime and memory efficiency:</em> Processing large amounts of +descriptors in bulk is supposed to be efficient in terms of runtime and +required memory.</li> +</ul> + +<p>At the same time the current design and implementation were done with a +number of non-goals in mind, even though some of these might turn into +goals in the future:</p> + +<p><ul> +<li><em>Verification:</em> The descriptor parser performs some basic +verifications of descriptor formats, but no cryptographic verifications. +It may not even be possible to write a cryptographic verification tool +using parsed descriptor contents, though this has not been attempted +yet.</li> +<li><em>Potentially lossy conversion:</em> Descriptor contents may be +converted to a format that is easier to process, even if that conversion +makes it harder or impossible to re-create the original descriptor +contents from a parsed descriptor.</li> +<li><em>Generating descriptors:</em> This library does not contain any +functionality to generate new descriptors for testing or related purposes, +neither from previously set data nor randomly.</li> +<li><em>Writing descriptors:</em> This library does not support writing +descriptors to the file system or a database, both of which are left to +the application. Stated differently, there are no descriptor sinks that +would correspond to the provided descriptor sources.</li> +</ul></p> + +<p>Hints about using DescripTor can be found in the +<a href="./org/torproject/descriptor/package-summary.html#package.description">{@code org.torproject.descriptor} package description</a>. +</p> + +<p>Contact and further information: +<ul> +<li><a href="https://trac.torproject.org/projects/tor/query?status=!closed&component=Metrics%2Fmetrics-lib">DescripTor Bug Tracker</a></li> +<li><a href="https://lists.torproject.org/cgi-bin/mailman/listinfo/metrics-team">Metrics Team Mailing List</a></li> +<li><a href="https://trac.torproject.org/projects/tor/wiki/org/teams/MetricsTeam">Metrics Team Website</a></li> +</ul> +</body> +</html> +