abdera-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jmsn...@apache.org
Subject svn commit: r421948 - in /incubator/abdera/java/trunk: build/ build/build.xml docs/building.html docs/gettingstarted.html docs/index.html
Date Fri, 14 Jul 2006 17:02:05 GMT
Author: jmsnell
Date: Fri Jul 14 10:02:03 2006
New Revision: 421948

URL: http://svn.apache.org/viewvc?rev=421948&view=rev
Log:
Updating the documentation that ships with the dist image.

Added:
    incubator/abdera/java/trunk/docs/building.html
    incubator/abdera/java/trunk/docs/gettingstarted.html
Modified:
    incubator/abdera/java/trunk/build/   (props changed)
    incubator/abdera/java/trunk/build/build.xml
    incubator/abdera/java/trunk/docs/index.html

Propchange: incubator/abdera/java/trunk/build/
------------------------------------------------------------------------------
--- svn:ignore (original)
+++ svn:ignore Fri Jul 14 10:02:03 2006
@@ -2,3 +2,4 @@
 .project
 test
 work
+tools

Modified: incubator/abdera/java/trunk/build/build.xml
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/build/build.xml?rev=421948&r1=421947&r2=421948&view=diff
==============================================================================
--- incubator/abdera/java/trunk/build/build.xml (original)
+++ incubator/abdera/java/trunk/build/build.xml Fri Jul 14 10:02:03 2006
@@ -177,7 +177,9 @@
              destdir="${javadocs}"
              windowtitle="Abdera"
              classpathref="jar.dependencies" />
-    <copy file="${basedir}/docs/index.html" todir="${docs}" />
+    <copy  todir="${docs}">
+      <fileset dir="${basedir}/docs/" includes="*.html" />
+    </copy>
   </target>
   
   <target name="test" depends="build">

Added: incubator/abdera/java/trunk/docs/building.html
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/docs/building.html?rev=421948&view=auto
==============================================================================
--- incubator/abdera/java/trunk/docs/building.html (added)
+++ incubator/abdera/java/trunk/docs/building.html Fri Jul 14 10:02:03 2006
@@ -0,0 +1,81 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<title>Apache Abdera</title>
+<link rel="stylesheet" href="../style/main.css" type="text/css" />
+</head>
+
+<body>
+  <!-- Header -->
+  <div id="banner">
+    <h1><a href="http://incubator.apache.org/abdera">Apache Abdera</a></h1>
+    <p>Version 0.1-SNAPSHOT (Incubating)</p>
+    <hr/>
+  </div>
+  <div id="divider"></div>
+
+  <div>  
+    <div id="content">
+    
+    <h1>Building Abdera</h1>
+    
+    <h2>Abdera Java Project Layout</h2>
+    
+    <p>The Abdera project consists of a set of individual modules.  The <code>core</code>
+    module contains the source of the Feed Object Model.  The <code>parser</code>
+    module contains the default StAX and Axiom based parser implementation.</p>
+    
+    <ul class="folderlayout">
+      <li>%Abdera_Home</li>
+      <ul>
+        <li>/java</li>
+        <ul>
+          <li>/build</li>
+          <li>/core</li>
+          <li>/dependencies</li>
+          <li>/docs</li>
+          <li>/examples</li>
+          <li>/extensions</li>
+          <li>/parser</li>
+          <li>/security</li>
+          <li>/server</li>
+        </ul>
+      </ul>
+    </ul>
+    
+    <h2>Building with Maven</h2>
+    
+    <p>To build with Maven, navigate to %Abdera_Home/java in a console window and type:</p>
+    
+    <pre>mvn install</pre>
+    
+    <p>The compiled jar files will be added to your local Maven repository.</p>
+    
+    <h2>Building with Ant</h2>
+    
+    <p>To build with Ant, navigate to %Abdera_Home/java in a console window and type:</p>
+    
+    <pre>ant -f build/build.xml dist</pre>
+    
+    <p>The compiled jar files will be available under a newly created %Abdera_Home/java/dist
directory</p>
+    
+    <h2>Building with Eclipse</h2>
+    
+    <p>TODO</p>
+    
+    <h2>Building with {other IDE}</h2>
+    
+    <p>TODO</p>
+    
+    </div>
+
+    <div id="footer">
+      Copyright &#xA9 2006, The Apache Software Foundation
+    </div>
+
+  </div>
+  
+
+</body>
+
+</html>
\ No newline at end of file

Added: incubator/abdera/java/trunk/docs/gettingstarted.html
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/docs/gettingstarted.html?rev=421948&view=auto
==============================================================================
--- incubator/abdera/java/trunk/docs/gettingstarted.html (added)
+++ incubator/abdera/java/trunk/docs/gettingstarted.html Fri Jul 14 10:02:03 2006
@@ -0,0 +1,227 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<title>Apache Abdera</title>
+</head>
+
+<body>
+  <!-- Header -->
+  <div id="banner">
+    <h1><a href="http://incubator.apache.org/abdera">Apache Abdera</a></h1>
+    <p>Version 0.1-SNAPSHOT (Incubating)</p>
+    <hr/>
+  </div>
+  <div id="divider"></div>
+
+  <div>      
+    <div id="content">
+    
+    <h1>Getting Started</h1>
+    
+    <h2>Downloading and Building the Source</h2>
+    
+    <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>Parsing Atom Feed and Entry Documents</h2>
+    
+    <p>The Abdera parser is capable of handling Atom Feed and Entry documents,
+    Atom Publishing Protocol Introspection Documents, and any other arbitrary, 
+    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
+    <code>Parser</code> instance.
+    
+    <pre>Parser parser = Parser.INSTANCE;
+// or
+Parser parser = new FOMParser();
+// or
+Parser parser = new MyCustomParser();</pre>
+
+    <p>The <code>Parser</code> will automatically detect the kind of document
+    being parsed and will return an appropriate <code>org.apache.abdera.model.Document</code>.
+    
+    <h3>Parsing an Atom Feed</h3>
+        
+    <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>
+
+    <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
+    URI resolution throughout the document.</p>
+
+    <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>
+   
+    <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();
+options.setCharset('utf-8');
+//.. set other parser options</b>
+Document&lt;Feed&gt; doc = Parser.INSTANCE.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>,
+    or may create their own Factory instance.</t>
+    
+    <pre>Factory factory = Factory.INSTANCE;
+// or
+Factory factory = new FOMFactory();
+// or
+Factory factory = new MyCustomFactory();</pre>
+
+    <h3>Creating Atom Feed Documents</h3>
+    
+    <pre>Feed feed = Factory.INSTANCE.newFeed();
+feed.setId("tag:example.org,2005:/myfeed", false);
+feed.setTitle("My Example Feed");
+// .. set other feed properties
+Document&lt;Feed&gt; doc = feed.getDocument();
+doc.writeTo(System.out); // serializes the feed document to System.out
+    </pre>
+    
+    <h3>Creating Atom Entry Documents</h3>
+
+    <pre>Entry entry = Factory.INSTANCE.newEntry();
+entry.setId("tag:example.org,2005:/myentry", false);
+entry.setTitle("My Example Entry");
+// .. set other feed properties
+Document&lt;Entry&gt; doc = entry.getDocument();
+doc.writeTo(System.out); // serializes the entry document to System.out
+    </pre>
+    
+    <h2>The Feed Object Model</h2>
+    
+    <p>The Feed Object Model (FOM) is a set of interfaces designed around the 
+    Atom Syndication Format data model.  The object model provides the API 
+    by which Atom documents are read and created.</p>
+    
+    <pre>URI uri = ...
+InputStream inputStream = ...
+Document&lt;Feed&gt; doc = Parser.INSTANCE.parse(inputStream, uri);
+Feed feed = doc.getRoot();
+URI id = feed.getId();
+Text.Type titleType = feed.getTitleType();
+String title = feed.getTitle();
+
+List&lt;Entry&gt; entries = feed.getEntries();
+for (Entry entry : entries) {
+  URI entryId = entry.getId();
+  Text.Type entryTitleType = entry.getTitleType();
+  String entryTitle = entry.getTitle();
+}
+...</pre>
+    
+    <h2>Using XPath</h2>
+    
+    <p>As an alternative to navigating the Feed Object Model manually, developer's
+    may use XPath to query a parsed <code>Document</code>.
+    
+    <pre>URI uri = ...
+InputStream inputStream = ...
+Document&lt;Feed&gt; doc = Parser.INSTANCE.parse(inputStream, uri);
+
+// Select the id of the document
+String id = XPath.INSTANCE.valueOf("/a:feed/a:id", doc);
+
+// Select all entries from the document
+List entries = XPath.INSTANCE.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);
+
+// 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>
+    
+    <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();
+// ... set other feed properties
+feed.addSimpleExtension(
+  new QName("urn:foo", "myExtension", "a"), 
+  "This is an extension"
+);
+
+Link link = feed.addLink("http://example.org");
+link.setAttributeValue(
+  new QName("urn:foo", "myAttribute", "a"), 
+  "My Attribute");</pre>
+  
+    <p>This results in the following Atom feed:</p>
+    
+    <pre>&lt;?xml version='1.0' ?&gt;
+&lt;feed xmlns='http://www.w3.org/2005/Atom'&gt;
+  ...
+  &lt;a:myExtension xmlns:a="urn:foo">This is an extension&lt;/a:myExtension>
+  &lt;link href="http://example.org" 
+        xmlns:a="urn:foo" 
+        a:myAttribute="My Attribute" />
+&lt;/feed&gt;
+    </pre>
+    
+    <p>As an alternative to using the dynamic extensions support built into the
+    Feed Object Model, developers may configure static extensions using the 
+    <code>org.apache.abdera.factory.ExtensionFactory</code> mechanism.
+    Extension Factories are covered in detail in the <a href="developers.html">Developer's
Guide</a>.</p>
+    
+    <h2>Signing and Encrypting Atom Documents</h2>
+    
+    <p>Atom Feed and Entry documents may be digitally signed and/or encrypted 
+    by using the <i>optional</i> Abdera Security module.  The security module
currently 
+    depends on the Apache Xerces, Apache XML Security Projects and the Bouncy 
+    Castle Java cryptography implementation.</p>
+    
+    <h3>Digitally Signing Atom Documents</h3>
+    
+    <pre>Feed feed = Factory.INSTANCE.newFeed();
+PrivateKey myPrivateKey = ...
+X509Certificate myX509Cert = ...
+Signature sig = Signature.INSTANCE;
+SignatureOptions options = sig.getDefaultSignatureOptions();
+options.setSigningKey(myPrivateKey);
+options.setCertificate(myX509Cert);
+feed = sig.sign(feed, options);
+//any modifications to the feed after this point will break the signature</pre>
+
+    <h3>Encrypting Atom Documents</h3>
+    
+    <pre>Feed feed = Factory.INSTANCE.newFeed();
+Key kek = ... // Key encryption key
+Key dek = ... // Data encryption key
+Encryption enc = Encryption.INSTANCE;
+EncryptionOptions options = enc.getDefaultEncryptionOptions();
+options.setKeyEncryptionKey(kek);
+options.setDataEncryptionKey(dek);
+options.setIncludeKeyInfo(true);
+Document doc = enc.encrypt(feed.getDocument(), options);
+doc.writeTo(System.out); // outs the encrypted XML</pre>
+
+    </div>
+
+    <div id="footer">
+      Copyright &#xA9 2006, The Apache Software Foundation
+    </div>
+
+  </div>
+  
+
+</body>
+
+</html>
\ No newline at end of file

Modified: incubator/abdera/java/trunk/docs/index.html
URL: http://svn.apache.org/viewvc/incubator/abdera/java/trunk/docs/index.html?rev=421948&r1=421947&r2=421948&view=diff
==============================================================================
--- incubator/abdera/java/trunk/docs/index.html (original)
+++ incubator/abdera/java/trunk/docs/index.html Fri Jul 14 10:02:03 2006
@@ -1,6 +1,6 @@
 <html>
 <head>
-<title>Atom Reference Implementation</title>
+<title>Apache Abdera</title>
 <style>
   pre {
     border: 1pt solid black;
@@ -10,257 +10,19 @@
 </style>
 </head>
 <body>
-<h1>Abdera</h1>
-<hr/>
-<p>Atom Implementation<br />Version 0.1</p>
-<hr/>
-<p>Abdera is an implementation of the <a href="http://www.ietf.org/rfc/rfc4287.txt">Atom
Syndication Format</a> 
-and <a href="http://www.ietf.org/internet-drafts/draft-ietf-atompub-protocol-08.txt">Atom
Publishing Protocol</a> 
-specifications published by the IETF Atompub working group.  At the core of the implementation
is the 
-"Feed Object Model" (<a href="api/index.html">javadoc</a>), a set of interfaces
for reading and building 
-Atom documents.</p>
-
-<h2>Parsing Atom Documents</h2>
-
-<p>The Parser interface is used to parse Atom documents.</p>
-
-<pre>
-  Parser parser = Parser.INSTANCE;
-  URI baseUri = {The Base URI of the Document to Parse}
-  InputStream inputStream = {acquire input stream}
-  ParserOptions options = parser.getDefaultParserOptions();
-    // set parser options
-  Document document = Parser.INSTANCE.parse(stream, baseUri, options);
-</pre>
-
-<p>The architecture of Abdera is such that applications may plug in their 
-own parser implementations.  The default parser that ships with Abdera 
-is based on the StAX XML parser and the Apache Axiom object model and is 
-capable of parsing Atom Feed documents, Entry documents and Atom Publishing 
-Protocol Introspection documents.</p>
-
-<pre>
-  // Parsing a feed document
-  Document&lt;Feed> document = 
-    Parser.INSTANCE.parse(stream, baseUri, options);
-  Feed feed = document.getRoot();
-  
-  // Parsing an entry document
-  Document&lt;Entry> document =
-    Parser.INSTANCE.parse(stream, baseUri, options);
-  Entry entry = document.getRoot();
-    
-  // Parsing an introspection document
-  Document&lt;Service> document = 
-    Parser.INSTANCE.parse(stream, baseUri, options);    
-  Service service = document.getRoot();
-</pre>
-
-<h3>Parser Options</h3>
-
-<p>TBD</p>
-
-<h2>Building Atom Documents</h2>
-
-<p>The Factory interface is used to build Atom documents.</p>
-
-<pre>
-  // Build the feed
-  Feed feed = Factory.INSTANCE.newFeed();
-  feed.setId("tag:example.org,2006:/foo", false);
-  feed.setTitleAsText("My Feed);
-  feed.setSubtitleAsText("My Feed Subtitle");
-  feed.setUpdated(new Date());
-  feed.addLink("http://example.org");
-  feed.addLink("self", "http://example.org/atom.xml");
-  feed.addAuthor("John Doe", "jdoe@example.com", "http://example.com");
-  
-  // Build the entry
-  Entry entry = feed.insertEntry();
-  entry.setId("tag:example.org,2006:/foo/1", false);
-  entry.setTitleAsHtml("&lt;b>My Title&lt;/b>");
-  entry.setUpdated(new Date());
-  entry.addLik("http://example.org");
-  entry.setContentAsHtml("This is &lt;i>HTML&lt;/i> content");
-
-  // Serialize the feed document
-  feed.getDocument().writeTo(System.out);
-</pre>
-
-<h2>The Atom Publishing Protocol</h2>
-
-<p>TBD</p>
-
-<h2>Extended Features</h2>
-
-<p>To be completed</p>
-
-<h3>Relative URI References</h3>
-
-<p>Abdera provides full support for Relative URI references through the use
-of xml:base, Content-Location and request URI's.  Every method on the Feed 
-Object Model that is capable of returning a relative URI reference has an
-alternative getResolved___ form that returns the fully qualified form of the 
-URI resolved according to the in-scope base URI.<p>
-
-<pre>
-  &lt;feed xmlns="http://www.w3.org/2005/Atom" xml:base="http://example.org/blog/"&gt;
-  ...
-    &lt;link rel="alternate" href="/index.html" />
-    &lt;link rel="self" href="index.atom" />
-  ...
-  &lt;/feed&gt;
-</pre>
-
-<pre>
-  FeedDocument doc = (FeedDocument)Parser.INSTANCE.parse(inputStream);
-  Feed feed = doc.getFeed();
-  Link alt = feed.getAlternateLink();
-  System.out.println(alt.getHref());         // outputs /index.html
-  System.out.println(alt.getResolvedHref()); // outputs http://example.org/index.html
-  
-  Link self = feed.SelfLink();
-  System.out.println(self.getHref());         // outputs index.atom
-  System.out.println(self.getResolvedHref()); // outputs http://example.org/blog/index.atom
   
-</pre>
-
-<h3>XPath Support</h3>
-
-<pre>
-  Feed feed = Factory.INSTANCE.newFeed();
-  feed.setTitleAsText("Foo");
-  
-  Map<String,String> namespaces = XPath.INSTANCE.getDefaultNamespaces();
-  namespaces.put("a", "http://www.w3.org/2005/Atom");
-  String title = XPath.INSTANCE.valueOf("a:title", feed, namespaces);
-  System.out.println(title);  // "Foo"
-</pre>
-
-<h3>Feed Thread Extension Support</h3>
-
-<pre>
-  Entry entry1 = Factory.INSTANCE.newEntry();
-  entry1.setId("tag:example.org,2006:foo:1", false);
-  ...
-  
-  Entry entry2 = Factory.INSTANCE.newEntry();
-  entry2.setId("tag:example.org,2006:foo:2", false);
-  entry2.addInReplyTo(entry1);
-  ...
-</pre>
-
-<p>Produces,</p>
-
-<pre>
-  &lt;entry xmlns="..." xmlns:thr="...">
-    &lt;id>tag:example.org,2006:foo:2&lt;/id>
-    &lt;thr:in-reply-to ref="tag:example.org,2006:foo:1" />
-  &lt;/entry>  
-</pre>
-
-<h3>Extension Elements</h3>
-
-<p>The Feed Object Model provides an API for working with extensions to the Atom
-format. The API allows developers to work with extensions dynamically or via
-static Java classes and custom factories.</p>
-
-<p>Namespaced extension attributes may be added to any Feed Object Model object. 
-For instance, the example below:</p>
-
-<pre>
-  Entry entry = Factory.INSTANCE.newEntry();
-  ...
-  Link link = entry.addLink("replies", "http://www.example.org");
-  link.setAttributeValue(
-    "http://purl.org/syndication/thread/1.0",
-    "count", "thr", "10");
-</pre>
-
-<p>Produces the following,</p>
-
-<pre>
-  &lt;entry xmlns="http://www.w3.org/2005/Atom">
-    ...
-    &lt;link rel="replies" href="http://www.example.org" thr:count="10"
-      xmlns:thr="http://purl.org/syndication/thread/1.0" />
-    ...
-  &lt;/entry>
-</pre>
-
-<p>Namespaced extension elements may be added to any Feed Object Model object
-that implements the ExtensibleElement interface.</p>
-
-<pre>
-  Entry entry = Factory.INSTANCE.newEntry();
-  ...
-  entry.addSimpleExtension("urn:foo", "foo", "f", "bar");
-</pre>
-
-<p>Produces the following,</p>
-
-<pre>
-  &lt;entry xmlns="http://www.w3.org/2005/Atom">
-    ...
-    &lt;f:foo xmlns:f="urn:foo">bar&lt;/f:foo>
-    ...
-  &lt;/entry>
-</pre>
-
-<p>TODO: Complete discussion of static extensions</p>
-
-<h3>XML Digital Signature Support</h3>
-
-<p>Note: XML Digital Signature Support is currently not built by default!</p>
-
-<pre>
-  Signature sig = Signature.INSTANCE;
-  SignatureOptions options = sig.getDefaultSignatureOptions();
-  // set signature options (e.g. signing key)
-  
-  Entry entry = Factory.INSTANCE.newEntry();
-  // set entry data
-  
-  // sign the entry
-  entry = sig.sign(entry, options);
-  
-  // validate the signature
-  boolean valid = sig.verify(entry, options);
-</pre>
-
-<h3>XML Encryption Support</h3>
-
-<p>Note: XML Digital Signature Support is currently not built by default!</p>
-
-<pre>
-  Encryption enc = Encryption.INSTANCE;
-  EncryptionOptions options = enc.getDefaultEncryptionOptions();
-  // set encryption options (e.g. algorithm, key encryption key, etc)
-  
-  Feed feed = Factory.INSTANCE.newFeed();
-  // set feed data
-  
-  // encrypt the feed
-  Document doc = enc.encrypt(feed.getDocument(), options);
-  
-  // decrypt the feed
-  Document doc = enc.decrypt(doc, options);
-</pre>
-
-<h2>Configuation Guide</h2>
-
-<p>TBD</p>
-
-<h2>Developers Guide</h2>
-
-<p>TBD</p>
-
-<h3>Extending Abdera</h3>
-
-<p>TBD</p>
-
-<h3>Writing your own parser implementation?</h3>
-
-<p>TBD</p>
-
+  <div id="banner">
+    <h1><a href="http://incubator.apache.org/abdera">Apache Abdera</a></h1>
+    <p>Version 0.1-SNAPSHOT (Incubating)</p>
+    <hr/>
+  </div>
+  <div id="divider"></div>
+
+  <div>      
+    <ul>
+      <li><a href="building.html">Building</a></li>
+      <li><a href="gettingstarted.html">Getting Started</a></li>
+      <li><a href="api/index.html">Javadocs</a></li>
+    </ul>
+  </div>
 </body>
 </html>



Mime
View raw message