You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@abdera.apache.org by jm...@apache.org on 2006/07/14 19:02:05 UTC
svn commit: r421948 - in /incubator/abdera/java/trunk: build/
build/build.xml docs/building.html docs/gettingstarted.html docs/index.html
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 © 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<Feed> 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<Entry> 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<Feed> 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<Feed> 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<Entry> 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<Feed> doc = Parser.INSTANCE.parse(inputStream, uri);
+Feed feed = doc.getRoot();
+URI id = feed.getId();
+Text.Type titleType = feed.getTitleType();
+String title = feed.getTitle();
+
+List<Entry> 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<Feed> 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><?xml version='1.0' ?>
+<feed xmlns='http://www.w3.org/2005/Atom'>
+ ...
+ <a:myExtension xmlns:a="urn:foo">This is an extension</a:myExtension>
+ <link href="http://example.org"
+ xmlns:a="urn:foo"
+ a:myAttribute="My Attribute" />
+</feed>
+ </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 © 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<Feed> document =
- Parser.INSTANCE.parse(stream, baseUri, options);
- Feed feed = document.getRoot();
-
- // Parsing an entry document
- Document<Entry> document =
- Parser.INSTANCE.parse(stream, baseUri, options);
- Entry entry = document.getRoot();
-
- // Parsing an introspection document
- Document<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("<b>My Title</b>");
- entry.setUpdated(new Date());
- entry.addLik("http://example.org");
- entry.setContentAsHtml("This is <i>HTML</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>
- <feed xmlns="http://www.w3.org/2005/Atom" xml:base="http://example.org/blog/">
- ...
- <link rel="alternate" href="/index.html" />
- <link rel="self" href="index.atom" />
- ...
- </feed>
-</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>
- <entry xmlns="..." xmlns:thr="...">
- <id>tag:example.org,2006:foo:2</id>
- <thr:in-reply-to ref="tag:example.org,2006:foo:1" />
- </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>
- <entry xmlns="http://www.w3.org/2005/Atom">
- ...
- <link rel="replies" href="http://www.example.org" thr:count="10"
- xmlns:thr="http://purl.org/syndication/thread/1.0" />
- ...
- </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>
- <entry xmlns="http://www.w3.org/2005/Atom">
- ...
- <f:foo xmlns:f="urn:foo">bar</f:foo>
- ...
- </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>