diff --git a/build.xml b/build.xml index 81c2fbd..129c4ed 100644 --- a/build.xml +++ b/build.xml @@ -1,6 +1,7 @@ + @@ -57,6 +58,7 @@ diff --git a/resources/overview.html b/resources/overview.html new file mode 100644 index 0000000..531057e --- /dev/null +++ b/resources/overview.html @@ -0,0 +1,60 @@ + + +

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.

+ +

The interfaces in + {@code org.torproject.descriptor} + 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:

+ +
    +
  • Complete coverage: This library is supposed to cover the + complete range of Tor descriptors made available by the + CollecTor + service.
  • +
  • Runtime and memory efficiency: Processing large amounts of + descriptors in bulk is supposed to be efficient in terms of runtime and + required memory.
  • +
+ +

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:

+ +

    +
  • Verification: 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.
  • +
  • Potentially lossy conversion: 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.
  • +
  • Generating descriptors: This library does not contain any + functionality to generate new descriptors for testing or related + purposes, neither from previously set data nor randomly.
  • +
  • Writing descriptors: 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.
  • +

+ +

Hints about using DescripTor can be found in the + {@code org.torproject.descriptor} package description. +

+ +

Contact and further information: +

+ + diff --git a/src/org/torproject/descriptor/DescriptorSourceFactory.java b/src/org/torproject/descriptor/DescriptorSourceFactory.java index 8622c3c..8eb0bc7 100644 --- a/src/org/torproject/descriptor/DescriptorSourceFactory.java +++ b/src/org/torproject/descriptor/DescriptorSourceFactory.java @@ -17,6 +17,22 @@ package org.torproject.descriptor; * own impl package. This may be overridden by setting Java properties, * though most users will simply use the default implementations.

* + *

These properties can be used for setting the implementation: + *

    + *
  • {@code descriptor.collector}
  • + *
  • {@code descriptor.downloader}
  • + *
  • {@code descriptor.parser}
  • + *
  • {@code descriptor.reader}
  • + *

+ * + *

Assuming the classpath contains the special implementation referenced, + * your application classes as well as a descriptor API jar the following is an + * example for using a different implementation of the descriptor downloader:

+ * + *

+ * java -Ddescriptor.downloader=my.special.descriptorimpl.Downloader my.app.Mainclass + *

+ * * @since 1.0.0 */ public final class DescriptorSourceFactory { diff --git a/src/org/torproject/descriptor/package-info.java b/src/org/torproject/descriptor/package-info.java index d444bc2..5b34554 100644 --- a/src/org/torproject/descriptor/package-info.java +++ b/src/org/torproject/descriptor/package-info.java @@ -5,8 +5,7 @@ * Interfaces and essential classes for obtaining and processing Tor * descriptors. * - *

This is a library to obtain and process descriptors containing Tor - * network data. This package contains all relevant interfaces and + *

This package contains all relevant interfaces and * classes that an application would need to use this library. * Applications are strongly discouraged from accessing types from the * implementation package ({@code org.torproject.descriptor.impl}) @@ -75,43 +74,6 @@ * ({@link org.torproject.descriptor.TorperfResult}). * * - *

The interfaces in this package 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:

- * - *
    - *
  • Complete coverage: This library is supposed to cover the - * complete range of Tor descriptors made available by the CollecTor - * service.
  • - *
  • Runtime and memory efficiency: Processing large amounts of - * descriptors in bulk is supposed to be efficient in terms of runtime and - * required memory.
  • - *
- * - *

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:

- * - *
    - *
  • Verification: 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.
  • - *
  • Potentially lossy conversion: 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.
  • - *
  • Generating descriptors: This library does not contain any - * functionality to generate new descriptors for testing or related - * purposes, neither from previously set data nor randomly.
  • - *
  • Writing descriptors: 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.
  • - *
- * * @since 1.0.0 */ package org.torproject.descriptor;