| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. The ASF licenses this file to You |
| under the Apache License, Version 2.0 (the "License"); you may not |
| use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. For additional information regarding |
| copyright in this work, please see the NOTICE file in the top level |
| directory of this distribution. --> |
| <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://abdera.apache.org">Apache Abdera</a></h1> |
| <p>Version 1.0-SNAPSHOT</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> |
| |
| <pre>Abdera abdera = new Abdera(); |
| Parser parser = abdera.getParser(); |
| // 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>. |
| |
| <pre> |
| InputStream in = ... |
| Document<Feed> feeddoc = parser.parse(in); |
| Document<Entry> entrydoc = parser.parse(in); |
| Document<Service> servicedoc = parser.parse(in); |
| </pre> |
| |
| <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.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.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.getDefaultParserOptions(); |
| options.setCharset("utf-8"); |
| //.. set other parser options</b> |
| Document<Feed> doc = parser.parse(in, uri, options);</pre> |
| |
| <h2>Creating Atom Feed and Entry Documents</h2> |
| |
| <p>Atom Feed and Entry documents are created using instances of the |
| <code>org.apache.abdera.factory.Factory</code> interface.</p> |
| |
| <pre>Abdera abdera = new Abdera(); |
| Factory factory = abdera.getFactory(); |
| // or |
| Factory factory = new MyCustomFactory();</pre> |
| |
| <h3>Creating Atom Feed Documents</h3> |
| |
| <pre>Feed feed = factory.newFeed(); |
| feed.setId("tag:example.org,2005:/myfeed"); |
| 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.newEntry(); |
| entry.setId("tag:example.org,2005:/myentry"); |
| 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.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.parse(inputStream, uri); |
| |
| // Select the id of the document |
| XPath xpath = abdera.getXPath(); |
| String id = xpath.valueOf("/a:feed/a:id", doc); |
| |
| // Select all entries from the document |
| 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.booleanValueOf("//x:foo", doc); |
| |
| // The XPath support works on any element in the FOM |
| 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.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>Abdera abdera = new Abdera(); |
| AbderaSecurity absec = new AbderaSecurity(abdera); |
| Factory factory = abdera.getFactory(); |
| Feed feed = factory.newFeed(); |
| PrivateKey myPrivateKey = ... |
| X509Certificate myX509Cert = ... |
| Signature sig = absec.getSignature(); |
| 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>Abdera abdera = new Abdera(); |
| AbderaSecurity absec = new AbderaSecurity(abdera); |
| Feed feed = factory.newFeed(); |
| Key kek = ... // Key encryption key |
| Key dek = ... // Data encryption key |
| Encryption enc = absec.getEncryption(); |
| 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> |