You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@abdera.apache.org by ro...@apache.org on 2006/10/27 23:07:13 UTC
svn commit: r468543 - in /incubator/abdera/site/trunk:
docs/gettingstarted.html faq.html
Author: rooneg
Date: Fri Oct 27 14:07:13 2006
New Revision: 468543
URL: http://svn.apache.org/viewvc?view=rev&rev=468543
Log:
Update docs and FAQ to match new APIs in trunk.
* docs/gettingstarted.html: Update examples, add section about the new
top level Abdera class.
* faq.html: Update examples.
Modified:
incubator/abdera/site/trunk/docs/gettingstarted.html
incubator/abdera/site/trunk/faq.html
Modified: incubator/abdera/site/trunk/docs/gettingstarted.html
URL: http://svn.apache.org/viewvc/incubator/abdera/site/trunk/docs/gettingstarted.html?view=diff&rev=468543&r1=468542&r2=468543
==============================================================================
--- incubator/abdera/site/trunk/docs/gettingstarted.html (original)
+++ incubator/abdera/site/trunk/docs/gettingstarted.html Fri Oct 27 14:07:13 2006
@@ -47,7 +47,28 @@
<p>Before you can use Abdera, you need to download and build the source.
Instructions for bulding are available in the <a href="building.html">Builder's Guide</a>.
-
+
+ <h2>The Abdera Class</h2>
+
+ <p>Abdera uses a class (<code>org.apache.abdera.Abdera</code>) as its top
+ level entry point. Upon creation, an instance of the <code>Abdera</code>
+ class will attempt to create singleton instances of the <code>Parser</code>,
+ <code>Factory</code>, and other interfaces based on the configuration
+ options built into the library. Once you have an instance of the
+ <code>Abdera</code> class you can use the various <code>getFoo</code>
+ methods to retrieve those singletons, or you can use the various
+ <code>newFoo</code> methods to create new instances of them. If you are in
+ a hurry and don't really care about efficiency in creating these objects
+ you can use the various static <code>getNewFoo</code> methods defined in
+ the Abdera class to create <code>Parsers</code>, <code>Factories</code>,
+ etc.</p>
+
+ <p>The examples in this document make use of the static methods for
+ brevity, but in a real world application you would likely want to create
+ an actual instance of <code>Abdera</code> to avoid duplicating the setup
+ work every time you create a <code>Parser</code> or <code>Factory</code>.
+ </p>
+
<h2>Parsing Atom Feed and Entry Documents</h2>
<p>The Abdera parser is capable of handling Atom Feed and Entry documents,
@@ -55,10 +76,10 @@
well-formed XML document.</p>
<p>User's can either use the default <code>org.apache.abdera.parser.Parser</code>
- instance by calling <code>Parser.INSTANCE</code>, or they may create an new
+ instance by calling <code>Abdera.getNewParser()</code>, or they may create an new
<code>Parser</code> instance.
- <pre>Parser parser = Parser.INSTANCE;
+ <pre>Parser parser = Abdera.getNewParser();
// or
Parser parser = new FOMParser();
// or
@@ -71,7 +92,7 @@
<pre>URI uri = new URI("http://example.org/feed.xml");
InputStream in = uri.toURL().openStream();
-Document<Feed> doc = Parser.INSTANCE.parse(in, uri);</pre>
+Document<Feed> doc = Abdera.getNewParser().parse(in, uri);</pre>
<p>The <code>uri</code> parameter on the <code>parse</code> method establishes
the Base URI for the parsed document and is used as the basis for relative
@@ -80,25 +101,26 @@
<h3>Parsing an Atom Entry</h3>
<pre>URI uri = new URI("http://example.org/entry.xml");
InputStream in = uri.toURL().openStream();
-Document<Entry> doc = Parser.INSTANCE.parse(in, uri);</pre>
+Document<Entry> doc = Abdera.getNewParser().parse(in, uri);</pre>
<h3>Configuring the Parser</h3>
<pre>URI uri = new URI("http://example.org/feed.xml");
InputStream in = uri.toURL().openStream();
-<b>ParserOptions options = Parser.INSTANCE.getDefaultParserOptions();
+Parser parser = Abdera.getNewParser();
+<b>ParserOptions options = parser.getDefaultParserOptions();
options.setCharset('utf-8');
//.. set other parser options</b>
-Document<Feed> doc = Parser.INSTANCE.parse(in, uri, options);</pre>
+Document<Feed> doc = parser.parse(in, uri, options);</pre>
<h2>Creating Atom Feed and Entry Documents</h2>
<t>Atom Feed and Entry documents are created using instances of the
<code>org.apache.abdera.factory.Factory</code> interface. User's can
- either use the default configured Factory by calling <code>Factory.INSTANCE</code>,
+ either use the default configured Factory by calling <code>Abdera.getNewFactory()</code>,
or may create their own Factory instance.</t>
- <pre>Factory factory = Factory.INSTANCE;
+ <pre>Factory factory = Abdera.getNewFactory();
// or
Factory factory = new FOMFactory();
// or
@@ -106,7 +128,7 @@
<h3>Creating Atom Feed Documents</h3>
- <pre>Feed feed = Factory.INSTANCE.newFeed();
+ <pre>Feed feed = Abdera.getNewFactory().newFeed();
feed.setId("tag:example.org,2005:/myfeed", false);
feed.setTitle("My Example Feed");
// .. set other feed properties
@@ -116,7 +138,7 @@
<h3>Creating Atom Entry Documents</h3>
- <pre>Entry entry = Factory.INSTANCE.newEntry();
+ <pre>Entry entry = Abdera.getNewFactory().newEntry();
entry.setId("tag:example.org,2005:/myentry", false);
entry.setTitle("My Example Entry");
// .. set other feed properties
@@ -132,7 +154,7 @@
<pre>URI uri = ...
InputStream inputStream = ...
-Document<Feed> doc = Parser.INSTANCE.parse(inputStream, uri);
+Document<Feed> doc = Abdera.getNewParser().parse(inputStream, uri);
Feed feed = doc.getRoot();
URI id = feed.getId();
Text.Type titleType = feed.getTitleType();
@@ -153,31 +175,33 @@
<pre>URI uri = ...
InputStream inputStream = ...
-Document<Feed> doc = Parser.INSTANCE.parse(inputStream, uri);
+Document<Feed> doc = Abdera.getNewParser().parse(inputStream, uri);
+
+XPath xpath = Abdera.getNewXPath();
// Select the id of the document
-String id = XPath.INSTANCE.valueOf("/a:feed/a:id", doc);
+String id = xpath.valueOf("/a:feed/a:id", doc);
// Select all entries from the document
-List entries = XPath.INSTANCE.valueOf("//a:entry", doc);
+List entries = xpath.valueOf("//a:entry", doc);
for (Iterator i = entries.iterator(); i.hasNext();) {
Entry entry = (Entry)i.next();
//...
}
// Determine if a feed contains a specific extension
-boolean hasFoo = XPath.INSTANCE.isTrue("//x:foo", doc);
+boolean hasFoo = xpath.isTrue("//x:foo", doc);
// The XPath support works on any element in the FOM
-Entry entry = (Entry)XPath.INSTANCE.selectSingleNode("//a:entry", doc);
-String id = XPath.INSTANCE.valueOf("a:id", entry);</pre>
+Entry entry = (Entry)xpath.selectSingleNode("//a:entry", doc);
+String id = xpath.valueOf("a:id", entry);</pre>
<h2>Using Extensions</h2>
<p>The Feed Object Model is designed to fully and dynamically support
extensions to the Atom Feed format.</p>
- <pre>Feed feed = Factory.INSTANCE.newFeed();
+ <pre>Feed feed = Abdera.getNewFactory().newFeed();
// ... set other feed properties
feed.addSimpleExtension(
new QName("urn:foo", "myExtension", "a"),
@@ -215,10 +239,12 @@
<h3>Digitally Signing Atom Documents</h3>
- <pre>Feed feed = Factory.INSTANCE.newFeed();
+ <pre>Abdera abdera = new Abdera();
+AbderaSecurity asec = new AbderaSecurity(abdera);
+Feed feed = abdera.getNewFactory().newFeed();
PrivateKey myPrivateKey = ...
X509Certificate myX509Cert = ...
-Signature sig = Signature.INSTANCE;
+Signature sig = asec.getNewSignature();
SignatureOptions options = sig.getDefaultSignatureOptions();
options.setSigningKey(myPrivateKey);
options.setCertificate(myX509Cert);
@@ -227,10 +253,12 @@
<h3>Encrypting Atom Documents</h3>
- <pre>Feed feed = Factory.INSTANCE.newFeed();
+ <pre>Abdera abdera = new Abdera();
+AbderaSecurity asec = new AbderaSecurity(abdera);
+Feed feed = abdera.getNewFactory().newFeed();
Key kek = ... // Key encryption key
Key dek = ... // Data encryption key
-Encryption enc = Encryption.INSTANCE;
+Encryption enc = asec.getNewEncryption();
EncryptionOptions options = enc.getDefaultEncryptionOptions();
options.setKeyEncryptionKey(kek);
options.setDataEncryptionKey(dek);
Modified: incubator/abdera/site/trunk/faq.html
URL: http://svn.apache.org/viewvc/incubator/abdera/site/trunk/faq.html?view=diff&rev=468543&r1=468542&r2=468543
==============================================================================
--- incubator/abdera/site/trunk/faq.html (original)
+++ incubator/abdera/site/trunk/faq.html Fri Oct 27 14:07:13 2006
@@ -139,7 +139,7 @@
<dd>
<pre>
URL url = new URL("http://www.example.org/atom.xml");
-Document<Feed> doc = Parser.INSTANCE.parse(url.openStream(), uri.toURI());
+Document<Feed> doc = Abdera.getNewParser().parse(url.openStream(), uri.toURI());
Feed feed = doc.getRoot();
</pre>
</dd>
@@ -149,7 +149,7 @@
<dd>
<pre>
URL url = new URL("http://www.example.org/atomentry.xml");
-Document<Entry> doc = Parser.INSTANCE.parse(url.openStream(), uri.toURI());
+Document<Entry> doc = Abdera.getNewParser().parse(url.openStream(), uri.toURI());
Entry entry = doc.getRoot();
</pre>
</dd>