abdera-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From roo...@apache.org
Subject svn commit: r468543 - in /incubator/abdera/site/trunk: docs/gettingstarted.html faq.html
Date Fri, 27 Oct 2006 21:07:13 GMT
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&lt;Feed&gt; doc = Parser.INSTANCE.parse(in, uri);</pre>
+Document&lt;Feed&gt; 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&lt;Entry&gt; doc = Parser.INSTANCE.parse(in, uri);</pre>
+Document&lt;Entry&gt; 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&lt;Feed&gt; doc = Parser.INSTANCE.parse(in, uri, options);</pre>
+Document&lt;Feed&gt; 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&lt;Feed&gt; doc = Parser.INSTANCE.parse(inputStream, uri);
+Document&lt;Feed&gt; 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&lt;Feed&gt; doc = Parser.INSTANCE.parse(inputStream, uri);
+Document&lt;Feed&gt; 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&lt;Feed> doc = Parser.INSTANCE.parse(url.openStream(), uri.toURI());
+Document&lt;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&lt;Entry> doc = Parser.INSTANCE.parse(url.openStream(), uri.toURI());
+Document&lt;Entry> doc = Abdera.getNewParser().parse(url.openStream(), uri.toURI());
 Entry entry = doc.getRoot();
       </pre>
       </dd>



Mime
View raw message