<!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://incubator.apache.org/abdera">Apache Abdera</a></h1>
    <p>Version 0.4.0-incubating-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&lt;Feed&gt; feeddoc = parser.parse(in);
Document&lt;Entry&gt; entrydoc = parser.parse(in);
Document&lt;Service&gt; 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&lt;Feed&gt; 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&lt;Entry&gt; 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&lt;Feed&gt; 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&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.newEntry();
entry.setId("tag:example.org,2005:/myentry");
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.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.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>&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>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 &#xA9 2006, The Apache Software Foundation
    </div>

  </div>
  

</body>

</html>