abdera-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jmsn...@apache.org
Subject svn commit: r1215249 - in /abdera/abdera2/docs/Getting.Started: ./ activities.out.xml activities.xml build.xml whatsnew.xml
Date Fri, 16 Dec 2011 19:40:44 GMT
Author: jmsnell
Date: Fri Dec 16 19:40:43 2011
New Revision: 1215249

URL: http://svn.apache.org/viewvc?rev=1215249&view=rev
Log:
documentation

Added:
    abdera/abdera2/docs/Getting.Started/
    abdera/abdera2/docs/Getting.Started/activities.out.xml   (with props)
    abdera/abdera2/docs/Getting.Started/activities.xml   (with props)
    abdera/abdera2/docs/Getting.Started/build.xml   (with props)
    abdera/abdera2/docs/Getting.Started/whatsnew.xml   (with props)

Added: abdera/abdera2/docs/Getting.Started/activities.out.xml
URL: http://svn.apache.org/viewvc/abdera/abdera2/docs/Getting.Started/activities.out.xml?rev=1215249&view=auto
==============================================================================
    (empty)

Propchange: abdera/abdera2/docs/Getting.Started/activities.out.xml
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: abdera/abdera2/docs/Getting.Started/activities.xml
URL: http://svn.apache.org/viewvc/abdera/abdera2/docs/Getting.Started/activities.xml?rev=1215249&view=auto
==============================================================================
--- abdera/abdera2/docs/Getting.Started/activities.xml (added)
+++ abdera/abdera2/docs/Getting.Started/activities.xml Fri Dec 16 19:40:43 2011
@@ -0,0 +1,537 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<?xml-stylesheet type='text/xsl' href='./rfc2629.xslt' ?>
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
+<?rfc toc="yes"?>
+<?rfc tocompact="yes"?>
+<?rfc tocdepth="3"?>
+<?rfc tocindent="yes"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes"?>
+<?rfc comments="yes"?>
+<?rfc inline="yes"?>
+<?rfc compact="yes"?>
+<?rfc subcompact="no"?>
+<?rfc private=" "?>
+<?rfc authorship="no"?>
+<rfc docName="whatsnew" ipr="none">
+  <front>
+    <title abbrev="Activity Streams">Abdera2 - Activity Streams</title>
+    <author fullname="James M Snell" initials="J.M." surname="Snell">
+      <organization></organization>
+    </author>
+    <date month="December" year="2011" />
+    <abstract>
+      <t>TBD</t>
+    </abstract>
+  </front>
+  <middle>
+
+  <section title="Introduction">
+  
+  <t></t>
+    
+  </section>
+    
+  <section title="A Simple Activity">
+  
+  <t>An Activity represents an event that has occurred and consists of four 
+  primary components:</t>
+  
+  <t><list style="hanging">
+    <t hangText="Actor">Identifies the entity that performed the action.</t>
+    <t hangText="Verb">Identifies the action that was taken.</t>
+    <t hangText="Object">Identifies the object that was acted upon.</t>
+    <t hangText="Target">Identifies the object to which the action was directed.</t>
+  </list></t>
+  
+  <t>For instance, given the sentence, "Joe posted a link to Sally's Profile", 
+  "Joe" is the Actor, "posted" is the verb, "a link" is the object, and 
+  "Sally's Profile" is the target.</t>
+  
+  <t>To represent this activity using the JSON Activity Streams Format using 
+  Abdera2, we would use the following code:</t>
+  
+  <figure><artwork>
+Activity activity =
+  makeActivity()
+    .actor(makePerson("Joe"))
+    .verb(POST)
+    .object(makeBookmark("http://example.org"))
+    .target(makeService().displayName("Sally's Wall"))
+    .get();
+  </artwork></figure>
+  
+  <t>Once created, we can serialize the activity to the standardized JSON 
+  format simply by calling the writeTo method on the activity:</t>
+  
+  <figure><artwork>
+IO io = IO.make().prettyPrint().get();
+activity.writeTo(io, System.out);
+  </artwork></figure>
+  
+  <t>For now, ignore the code that creates the IO object, we'll get back to
+  the IO object in a bit. By calling writeTo in this way, however, Abdera2 
+  will print out a nicely formatted JSON object:</t>
+  
+  <figure><artwork>
+{
+  "objectType": "activity",
+  "actor": {
+    "objectType": "person",
+    "displayName": "Joe"
+  },
+  "verb": "post",
+  "object": {
+    "objectType": "bookmark",
+    "targetUrl": "http://example.org"
+  },
+  "target": {
+    "objectType": "service",
+    "displayName": "Sally\u0027s Wall"
+  }
+}
+  </artwork></figure>
+  
+  <t>So now we have an Activity, but we do not quite yet have an Activity *Stream*.
+  For that, we need to create a stream that contains the activity. If you're
+  familiar with the Atom Syndication Format and RSS, Activities and Streams are
+  the logical equivalent to Entries and Feeds.</t>
+  
+  <figure><artwork><![CDATA[
+    Collection<Activity> stream = 
+      Collection.<Activity>makeCollection()
+      .item(activity)
+      .get();
+  ]]></artwork></figure>
+  
+  <t>Once the activity has been added to the stream, we can use the writeTo
+  method (and the IO object we created) to output the results:</t>
+  
+  <figure><artwork>
+{
+  "objectType": "collection",
+  "totalItems": 1,
+  "items": [
+    {
+      "objectType": "activity",
+      "actor": {
+        "objectType": "person",
+        "displayName": "Joe"
+      },
+      "verb": "post",
+      "object": {
+        "objectType": "bookmark",
+        "targetUrl": "http://example.org"
+      },
+      "target": {
+        "objectType": "service",
+        "displayName": "Sally\u0027s Wall"
+      }
+    }
+  ]
+}
+  </artwork></figure>
+
+  <t>We now have a simple Activity Stream containing exactly one Activity.</t>
+
+  <t>Note that the code example above uses a variety of objects and functions
+  that have been statically imported to improve code readability. The imports
+  used are shown below. In particular, note the static import of the various
+  factory methods (e.g. makeCollection, makeActivity, etc). We'll touch more
+  on the Factory API a bit later.</t>
+  
+  <figure><artwork>
+import static org.apache.abdera2.activities.model.Collection.makeCollection;
+import static org.apache.abdera2.activities.model.Activity.makeActivity;
+import static org.apache.abdera2.activities.model.objects.PersonObject.makePerson;
+import static org.apache.abdera2.activities.model.objects.ServiceObject.makeService;
+import static org.apache.abdera2.activities.model.objects.BookmarkObject.makeBookmark;
+import static org.apache.abdera2.activities.model.Verb.POST;
+import org.apache.abdera2.activities.model.Activity;
+import org.apache.abdera2.activities.model.Collection;
+import org.apache.abdera2.activities.model.IO;
+  </artwork></figure>
+  
+  </section>
+  
+  <section title="Reading the Activity Stream">
+  
+  <t>Reading the Activity Stream is as equally straightforward. Let's
+  assume that our Activity Stream has been handed to us in the form of a
+  Reader, parsing the stream is as simple as:</t>
+  
+  <figure><artwork><![CDATA[
+Reader reader = ...
+Collection<Activity> stream = io.readCollection(reader);
+  ]]></artwork></figure>
+  
+  <t>Note that we're just reusing the IO object from the previous example.</t>
+  
+  <t>The readCollection method gives us back a Collection object that we can
+  then iterate over to extract the Activity:</t>
+  
+  <figure><artwork>
+for (Activity a : stream.getItems()) {
+  System.out.println(a.getActor().getDisplayName());
+  System.out.println(a.getVerb());
+  System.out.println(a.getObject().getObjectType());
+  System.out.println(a.getTarget().getDisplayName());
+}
+  </artwork></figure>
+  
+  </section>
+  
+  <section title="The IO Object">
+  
+  <t>The IO object is the primary interface through which Activity Streams
+  are Serialized and Deserialized. It handles all the details of converting
+  between JSON and the Java Objects.</t>
+  
+  <t>Every IO object is created using a simple factory pattern that is leveraged
+  extensively throughout the entire Activity Streams implementation. Once created,
+  IO objects are immutable and threadsafe.</t>
+  
+  <t>There are two basic ways of creating an IO object. The first is to call
+  the static get() method on the IO class, which returns an IO object that 
+  uses default configuration parameters. One or more TypeAdapters can be 
+  passed in as arguments to the get() method, but we'll address TypeAdapters
+  later.</t>
+  
+  <figure><artwork>
+IO io = IO.get(); // create default, immutable IO object
+  </artwork></figure>
+  
+  <t>The second way of creating IO is to use the static IO.make() method to 
+  create an IO Factory used to configure the IO will non-default options.
+  You've already seen one example of using make() in the previous examples.</t>
+  
+  <figure><artwork>
+IO io = IO.make()
+  .prettyPrint()
+  .autoClose()
+  .get();
+  </artwork></figure>
+  
+  <t>Using the IO Factory is most useful when dealing with custom object 
+  serializations, which will be covered in more detail later.</t>
+  
+  <section title="Serializing Objects using IO">
+  
+    <t>Using the IO object to serialize Activity objects is as simple as
+    calling an appropriate write() method. There are a variety of options
+    depending on the specific needs of your application:</t>
+    
+    <figure><preamble>Serialize to a String:</preamble><artwork>
+String s = io.write(stream);
+    </artwork></figure>
+    
+    <figure><preamble>Serialize to a Writer</preamble><artwork>
+Writer writer = ...
+io.write(stream, writer);
+    </artwork></figure>
+    
+    <figure><preamble>Serialize to an OutputStream</preamble><artwork>
+OutputStream out = ...
+io.write(stream, out);
+    </artwork></figure>
+  
+    <t>One of the more advanced features of the IO object is the ability
+    to perform nonblocking serialization and deserialization. This is 
+    done by integrating with the mechanisms provided by the 
+    java.util.concurrent.* package:</t>
+    
+    <figure><preamble>Nonblocking Serialization</preamble><artwork>
+OutputStream out = ...
+ExecutorService exec = MoreExecutors2.getExitingExecutor();
+io.write(stream, out, exec);
+    </artwork></figure>
+    
+  </section>
+  
+  <section title="Deserializing Object using IO">
+  
+    <t>Using the IO object to deserialize Activity objects is just
+    a slightly more complicated in that, because of the typeless 
+    nature of JSON Documents, you have to be reasonably sure in 
+    advance what exactly it is you're parsing (e.g. individual 
+    Activity or a Stream). Calling the io.read() method, IO will
+    attempt to make a best guess based on heuristic analysis of the 
+    objects content to determine what kind of object is being parsed
+    but it doesn't always get it right. Accordingly, if you know 
+    that you're parsing a Stream, you should use the appropriate
+    readCollection methods. If you know you're parsing an individual
+    Activity object, then use the readActivity method.</t>
+    
+    <figure><preamble>Reading from a String</preamble><artwork><![CDATA[
+String s = ...
+Collection<Activity>stream = io.readCollection(s)
+    ]]></artwork></figure>
+    
+    <figure><preamble>Reading from a Reader</preamble><artwork><![CDATA[
+Reader reader = ...
+Collection<Activity>stream = io.readCollection(reader)
+    ]]></artwork></figure>
+    
+    <figure><preamble>Reading from an InputStream</preamble><artwork><![CDATA[
+InputStream in = ...
+Collection<Activity>stream = io.readCollection(in)
+    ]]></artwork></figure>
+  
+    <t>Non-blocking deserialization is also possible:</t>
+    
+    <figure><artwork><![CDATA[
+Reader reader = ...
+ExecutorService exec = MoreExecutors2.getExitingExecutor();
+io.readCollection(
+  reader, 
+  exec, 
+  new Listener<Collection<Activity>>() {
+    public void onComplete(Collection<Activity> stream) {
+      // do something with the stream
+    }        
+  });
+    ]]></artwork></figure>
+    
+    <t>You can also use a Future to wait for the result:</t>
+    
+    <figure><artwork><![CDATA[
+Future<Collection<Activity>> future =
+  io.readCollection(
+  s, 
+  MoreExecutors2.getExitingExecutor());
+  
+Collection<Activity> stream = future.get();
+    ]]></artwork></figure>
+  
+  </section>
+  
+  </section>
+  
+  <section title="Creating Objects">
+  
+  <t>All Activity objects are created using a simple factory pattern. Created
+  instances are all Immutable and Threadsafe. Let's look back at the very 
+  first example and break it down:</t>
+  
+    <figure><artwork>
+Activity activity =
+  makeActivity()
+    .actor(makePerson("Joe"))
+    .verb(POST)
+    .object(makeBookmark("http://example.org"))
+    .target(makeService().displayName("Sally's Wall"))
+    .get();
+  </artwork></figure>
+  
+  <t>The first thing you should notice is that the factory uses what is known
+  as a <eref target="http://en.wikipedia.org/wiki/Fluent_interface">"Fluent" API</eref>.

+  Another name for this is "method chaining". This pattern is utilized extensively
+  throughout Abdera2. If you've never used a Fluent API before, it can take 
+  some getting used to, but with some practice it becomes very natural to use.</t>
+  
+  <t>The makeActivity() method is statically imported from the 
+  org.apache.abdera2.activities.model.Activity object:</t>
+  
+  <figure><artwork>
+import static org.apache.abdera2.activities.model.Activity.makeActivity;
+  </artwork></figure>
+  
+  <t>It returns an ActivityBuilder object that is used to construct our 
+  activity. The methods of this object reflect all the various properties
+  of the Activity. The call to "actor()" sets the value of the Activities
+  "actor" property, etc. Notice how calls to other statically imported
+  factory methods are mixed in. Each of these returns builders for their
+  own respective types of objects. The makePerson method, for instance, 
+  returns a PersonBuilder, whilch makeBookmark returns a BookmarkBuilder.
+  The final call to get() triggers the ActivityBuilder to build the immutable
+  Activity object using the specified properties.</t>
+  
+  <t>Let's take a look at another example.</t>
+  
+  <figure><preamble>Creating a Person Object</preamble><artwork>
+PersonObject person = 
+  makePerson()
+    .displayName("John Doe")
+    .email("john.doe@example.org")
+    .id("acct:john.doe@example.org")
+    .name(makeName()
+      .givenName("John")
+      .familyName("Doe"))
+    .set("foo","bar")
+    .get();
+  </artwork></figure>
+  
+  <t>If we call the writeTo method on the person object we can get an 
+  idea of the JSON produced by this code:</t>
+  
+  <figure><artwork>
+{
+  "objectType": "person",
+  "displayName": "John Doe",
+  "id": "acct:john.doe@example.org",
+  "name": {
+    "objectType": "name",
+    "givenName": "John",
+    "familyName": "Doe"
+  },
+  "foo": "bar",
+  "emails": [
+    "john.doe@example.org"
+  ]
+}
+  </artwork></figure>
+  
+  <t>The Activity Streams implementation supports a broad range of specific
+  object types like PersonObject that will be discussed shortly. These are 
+  designed to be composed together with Activities as the values of the 
+  actor, object and target properties.</t>
+  
+    <section title="Object Templates">
+    
+    <t>All Activity Objects, once created, are immutable. To modify the 
+    properties of an object, we need to use it as a template to create
+    a new object entirely.</t>
+    
+    <t>Suppose, for example, that we wish to add a property to the 
+    person object example given previously:</t>
+    
+    <figure><artwork><![CDATA[
+person = 
+ person.<PersonObject,PersonBuilder>template()
+ .aboutMe("This is John Doe")
+ .get();
+    ]]></artwork></figure>
+    
+    <t>The template() method is available on all objects and returns a
+    builder object appropriate for that type. By default, the builder 
+    will have all the properties of the original object set. If you 
+    wish to change the value of an existing property, you must create 
+    a template that filters out the value to be modified:</t>
+    
+    <figure><artwork><![CDATA[
+import static org.apache.abdera2.activities.model.ASBase.withoutFields;
+//....    
+person = 
+  person.<PersonObject,PersonBuilder>template(withoutFields("emails"))
+  .email("john.doe@example2.org")
+  .get();
+    ]]></artwork></figure>
+    
+    </section>
+    
+    <section title="Changing Object Types">
+    
+    <t>There are occasions, albeit rare, that you'll need to treat one
+    kind of object as if it were another type. This is most common when 
+    IO ends up generating the wrong kind of object during parse. Every
+    object supports an as() method that creates a new instance of the 
+    desired type with a copy of the source objects properties.</t>
+    
+    <figure><artwork>
+ServiceObject service = person.as(ServiceObject.class);
+    </artwork></figure>
+    
+    <t>The ability to convert objects like this leads to some rather 
+    interesting advanced capabilities that are beyond the scope of 
+    this getting started guide. Advanced topics will be covered 
+    separately.</t>
+    
+    </section>
+    
+    <section title="Type-Safe Extension">
+    
+    <t>Activity Stream objects are arbitrarily extensible. That is, new 
+    properties can be added to any object type at any time. The basic 
+    builder for each object supports a generic set property whose arguments
+    take a string and any arbitrary object as the value. This is useful, 
+    but it's not typesafe. For instance, suppose our application requires
+    that a Person have an extension property named "friendCount" whose 
+    value must be a integer. Using set, there's no way for us to enforce 
+    that constraint:</t>
+    
+    <figure><artwork>
+PersonObject person = 
+  makePerson()
+    .displayName("John Doe")
+    .set("friendCount","1")
+    .get();
+    </artwork></figure>
+    
+    <t>To enforce type-safety constraints, Abdera2 supports an alternative. 
+    First, let's define an extension interface:</t>
+    
+    <figure><artwork>
+public static interface MyExt extends Extra.ExtensionBuilder {
+  MyExt friendCount(int i);
+}
+    </artwork></figure>
+    
+    <t>Then, let's extend the PersonBuilder dynamically,</t>
+    
+    <figure><artwork><![CDATA[
+PersonObject person = 
+  makePerson()
+    .displayName("John Doe")
+    .extend(MyExt.class)
+    .friendCount(10)
+    .<PersonBuilder>unwrap()
+    .get();
+    ]]></artwork></figure>
+    
+    <t>Note that "friendCount" is now set in a manner that is completely
+    type-safe, and we maintain our Fluent API pattern.</t>
+    
+    <t>The objects themselves can also be extended in similar fashion:</t>
+    
+    <figure><artwork>
+public static interface MyExt2 extends Extra.ExtensionObject {
+  int getFriendCount();
+}
+
+int fc = person.extend(MyExt2.class).getFriendCount();
+    </artwork></figure>
+    
+    </section>
+  
+  </section>
+  
+  <section title="Using CollectionWriter">
+  
+  <t>The CollectionWriter interface provides a simplified interface for
+  streaming serialization of collections of Activity objects.</t>
+  
+  <figure><artwork>
+CollectionWriter cw = 
+  io.getCollectionWriter(System.out, "UTF-8");
+cw.writeObject(
+  makeActivity()
+    .verb(POST)
+    .actor(makePerson("Joe"))
+    .object(makeBookmark("http://example.org")));
+  </artwork></figure>
+  
+  </section>
+    
+  <section title="Custom Type Adapters and Property Mappings">
+    <t>TBD</t>
+  </section>
+  
+  <section title="Object Types">
+    <t>TBD</t>
+  </section>
+  
+  <section title="Audience Targeting">
+    <t>TBD</t>
+  </section>
+  
+  <section title="Converting Activities to and from Atom">
+    <t>TBD</t>
+  </section>
+  
+  <section title="Miscellaneous">
+    <t>TBD</t>
+  </section>
+    
+  </middle>
+  <back></back>
+</rfc>
\ No newline at end of file

Propchange: abdera/abdera2/docs/Getting.Started/activities.xml
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: abdera/abdera2/docs/Getting.Started/build.xml
URL: http://svn.apache.org/viewvc/abdera/abdera2/docs/Getting.Started/build.xml?rev=1215249&view=auto
==============================================================================
--- abdera/abdera2/docs/Getting.Started/build.xml (added)
+++ abdera/abdera2/docs/Getting.Started/build.xml Fri Dec 16 19:40:43 2011
@@ -0,0 +1,236 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<?xml-stylesheet type='text/xsl' href='./rfc2629.xslt' ?>
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
+<?rfc toc="yes"?>
+<?rfc tocompact="yes"?>
+<?rfc tocdepth="3"?>
+<?rfc tocindent="yes"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes"?>
+<?rfc comments="yes"?>
+<?rfc inline="yes"?>
+<?rfc compact="yes"?>
+<?rfc subcompact="no"?>
+<?rfc private=" "?>
+<?rfc authorship="no"?>
+<rfc docName="source-installing" ipr="none">
+  <front>
+    <title abbrev="Building">Abdera2 - Source and Installation</title>
+    <author fullname="James M Snell" initials="J.M." surname="Snell">
+      <organization></organization>
+    </author>
+    <date month="December" year="2011" />
+    <abstract>
+      <t>TBD</t>
+    </abstract>
+  </front>
+  <middle>
+
+  <section title="Source Code">
+  
+    <t>Source code for the Apache Abdera2 Project is currently managed 
+    through Subversion (SVN).</t>
+
+    <section title="Web Access">
+    <t>If you just want to browse the source code, you can use 
+    the <eref target="http://svn.apache.org/repos/asf/abdera/abdera2/">web interface</eref>

+    to Subversion.</t>
+    </section>
+    
+    <section title="Normal Subversion Access">
+    <t>Anyone can check code out of Subversion. You only need to specify a 
+    username and password in order to update the Subversion repository but 
+    only Abdera committers have the permissions to do that.</t>
+    <t>You can use the command line in order to check out the current 
+    version of Abdera2 code:</t>
+    <figure><artwork>
+svn checkout http://svn.apache.org/repos/asf/abdera/abdera2/
+    </artwork></figure>
+    </section>
+    
+    <section title="Commit Changes to Subversion">
+   
+    <t>Any Abdera committer should have access to the abdera repository at 
+    svn.apache.org. If not please write a mail to dev@abdera.apache.org.</t>
+
+    <t>Please make sure that you used a secure connection for checkout 
+    (or use relocate):</t>
+    
+    <figure><artwork>
+svn checkout https://svn.apache.org/repos/asf/abdera/abdera2/
+    </artwork></figure>
+    
+    <t>Committing changes:</t>
+
+    <figure><artwork>
+svn commit
+    </artwork></figure>
+
+    <t>If Subversion can't figure out your username, you can tell it 
+    explicitly:</t>
+
+    <figure><artwork>
+svn --username you commit
+    </artwork></figure>
+    
+    <t>Subversion will prompt you for a password, and once you enter it 
+    once, it will remember it for you.</t>
+
+    </section>
+  
+  </section>
+  
+  <section title="Building with Maven">
+  
+    <t>Abdera2 uses <eref target="http://maven.apache.org/">Maven</eref>
for 
+    building and dependency management. Simply navigate to the root of the 
+    Abdera2 project and run:</t>
+    
+    <figure><artwork>
+mvn install
+    </artwork></figure>
+  
+    <t>To build the distribution, include the deploy profile:</t>
+    
+    <figure><artwork>
+mvn install -Pdeploy
+    </artwork></figure>
+    
+    <t>The built artfacts for the project will be installed to your local
+    Maven Repository.</t>
+  
+  </section>
+
+  <section title="The Classpath">
+    
+    <t>The Abdera2 build generates a handful of individual jar files, each
+    of which can be used in various combinations depending on the specific
+    requirements of your application. These modules include:</t>
+    
+    <t><list style="hanging">
+      <t hangText="Common (abdera2-common-2.0-SNAPSHOT.jar):">
+        Contains the Abdera2 Common Code Library, a generic collection
+        of utilities supporting a broad range of functionality including
+        URI Templates, Date/Time handling, extended HTTP Header support,
+        IRI and Language Tags, and much more. The Common Code Library 
+        can be used independently of the rest of the Abdera2 code. 
+      </t>
+      <t hangText="Client (abdera2-client-2.0-SNAPSHOT.jar):">
+        Contains the generic Abdera2 HTTP Client. Implemented as a thin
+        layer on top of the <eref target="http://hc.apache.org/">Apache 
+        HttpComponents Client</eref>, the Abdera2 Client library provides 
+        a client API for working with REST services.
+      </t>
+      <t hangText="Atom Core (abdera2-core-2.0-SNAPSHOT.jar):">
+        Contains the core of the Atom Syndication Format and Atom Publishing
+        Protocol code, including the Feed Object Model API znc Atom-specific 
+        extensions to the HTTP Client. 
+      </t>
+      <t hangText="Atom Server (abdera2-server-2.0-SNAPSHOT.jar):">
+        Contains the core of the Atom Publishing Protocol Server Framework.
+      </t>
+      <t hangText="Atom Security (abdera2-security-2.0-SNAPSHOT.jar):">
+        Contains the XML Digital Signatures and XML Encryption implementations
+        for the Atom Syndication Format.
+      </t>
+      <t hangText="Atom Extensions ()abdera2-ext-2.0-SNAPSHOT.jar):">
+        Contains a range of standard and common extensions to the Atom
+        Syndication Format including Threading, Paging, Licensing, etc
+      </t>
+      <t hangText="Activity Streams (abdera2-activities-2.0-SNAPSHOT.jar):">
+        Contains the <eref target="http://activitystrea.ms">JSON Activity
+        Streams</eref> implementation. This module depends directly on the
+        Common and Client modules, but can be used independently of all the
+        Atom Syndication Format and Atom Publishing Protocol code.
+      </t>
+    </list></t>
+    
+    <section title="Dependencies">
+    
+    <t>To see the list of dependencies required by Abdera2, you can run the 
+    following command using Maven (<eref target="http://grep.codeconsult.ch/2010/07/08/list-all-your-maven-dependencies/">source</eref>):</t>
+    
+    <figure><artwork>
+mvn -o dependency:list | grep ":.*:.*:.*" | cut -d] -f2- | sed 's/:[a-z]*$//g' | sort -u
+    </artwork></figure>
+       
+    </section>
+   
+    <section title="Maven">
+    
+      <t>To use Abdera2 within a Maven-based project, simply add the following
+      dependencies to you pom.xml:</t>
+      
+      <figure><preamble>Common:</preamble><artwork><![CDATA[
+<dependency>
+  <groupId>org.apache.abdera2</groupId>
+  <artifactId>abdera2-common</artifactId>
+  <version>2.0-SNAPSHOT</version>
+</dependency>
+      ]]>
+      </artwork></figure>
+    
+      <figure><preamble>Client:</preamble><artwork><![CDATA[
+<dependency>
+  <groupId>org.apache.abdera2</groupId>
+  <artifactId>abdera2-client</artifactId>
+  <version>2.0-SNAPSHOT</version>
+</dependency>
+      ]]>
+      </artwork></figure>
+    
+      <figure><preamble>Atom Core:</preamble><artwork><![CDATA[
+<dependency>
+  <groupId>org.apache.abdera2</groupId>
+  <artifactId>abdera2-core</artifactId>
+  <version>2.0-SNAPSHOT</version>
+</dependency>
+      ]]>
+      </artwork></figure>
+    
+      <figure><preamble>Atom Server:</preamble><artwork><![CDATA[
+<dependency>
+  <groupId>org.apache.abdera2</groupId>
+  <artifactId>abdera2-server</artifactId>
+  <version>2.0-SNAPSHOT</version>
+</dependency>
+      ]]>
+      </artwork></figure>
+    
+      <figure><preamble>Atom Security:</preamble><artwork><![CDATA[
+<dependency>
+  <groupId>org.apache.abdera2</groupId>
+  <artifactId>abdera2-security</artifactId>
+  <version>2.0-SNAPSHOT</version>
+</dependency>
+      ]]>
+      </artwork></figure>
+    
+      <figure><preamble>Atom Extensions:</preamble><artwork><![CDATA[
+<dependency>
+  <groupId>org.apache.abdera2</groupId>
+  <artifactId>abdera2-ext</artifactId>
+  <version>2.0-SNAPSHOT</version>
+</dependency>
+      ]]>
+      </artwork></figure>
+    
+      <figure><preamble>Activity Streams:</preamble><artwork><![CDATA[
+<dependency>
+  <groupId>org.apache.abdera2</groupId>
+  <artifactId>abdera2-activities</artifactId>
+  <version>2.0-SNAPSHOT</version>
+</dependency>
+      ]]>
+      </artwork></figure>
+    
+      <t>Maven will automatically pull in all the necessary dependencies
+      for each of the modules.</t>
+    
+    </section>
+    
+  </section>
+
+  </middle>
+  <back></back>
+</rfc>
\ No newline at end of file

Propchange: abdera/abdera2/docs/Getting.Started/build.xml
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: abdera/abdera2/docs/Getting.Started/whatsnew.xml
URL: http://svn.apache.org/viewvc/abdera/abdera2/docs/Getting.Started/whatsnew.xml?rev=1215249&view=auto
==============================================================================
--- abdera/abdera2/docs/Getting.Started/whatsnew.xml (added)
+++ abdera/abdera2/docs/Getting.Started/whatsnew.xml Fri Dec 16 19:40:43 2011
@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<?xml-stylesheet type='text/xsl' href='./rfc2629.xslt' ?>
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
+<?rfc toc="yes"?>
+<?rfc tocompact="yes"?>
+<?rfc tocdepth="3"?>
+<?rfc tocindent="yes"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes"?>
+<?rfc comments="yes"?>
+<?rfc inline="yes"?>
+<?rfc compact="yes"?>
+<?rfc subcompact="no"?>
+<?rfc private=" "?>
+<?rfc authorship="no"?>
+<rfc docName="whatsnew" ipr="none">
+  <front>
+    <title abbrev="What's New">Abdera2 - What's New</title>
+    <author fullname="James M Snell" initials="J.M." surname="Snell">
+      <organization></organization>
+    </author>
+    <date month="December" year="2011" />
+    <abstract>
+      <t>TBD</t>
+    </abstract>
+  </front>
+  <middle>
+
+  <section title="Highlights">
+  
+    <t>Abdera2 is a major update to the project that introduces a broad range 
+    of new features and functionality as well as bug fixes and improved 
+    performance.</t>
+
+    <t>New features include:</t>
+    
+    <t><list>
+      <t>Updated all dependencies to latest versions</t>
+      <t>Introduced new dependencies on <eref target="http://joda-time.sourceforge.net/">Joda-Time</eref>

+      and <eref target="http://code.google.com/p/guava-libraries/">Guava Libraries</eref></t>
+      <t>Refactored package layout, new packaging structure</t>
+      <t>New Common Code Library:
+        <list>
+          <t>Selector Framework, extension to the Guava Predicate API, used extensively
throughout Abdera2.</t>
+          <t>Updated and Extended URI Template Implementation</t>
+          <t>Updated Unicode Support using ICU4J</t>
+          <t>Improved efficiency in IRI implementation</t>
+          <t>Enhanced ISO8601 Date/Time handling using Joda-Time, Guava and the Selector
framework</t>
+          <t>Enhanced support for common HTTP Headers (Authentication, Cache Control,
ETag, Preference, Web Linking)</t>
+          <t>Simplified Lang Tag Support</t>
+          <t>Enhanced Media Type Support</t>
+          <t>New lightweight "Pusher" interface.. acts as a shim for simple pub/sub
applications.</t>
+          <t>Lightweight MapReduce implementation built around the Guava Function API
designed primarily for relatively small, in-memory analysis operations. Supports asynchronous,
non-blocking operations.</t>
+          <t>Simple Chained Invocation API extending the Guava Function API</t>
+          <t>API Key and One Time Password Implementations</t>
+          <t>Utilities for simplifying Hash and HMAC generation and validation</t>
+          <t>Variety of other useful utilities...</t>
+        </list></t>
+      <t>Updated Feed Object Model API, using Joda-Time for all Date-Time handling,
use of the Selector API for filtering results</t>
+      <t>Simplified the Named Writer and Named Parser mechanism in the Atom implementation</t>
+      <t>Completely refactored HTTP Client API based around the Apache HTTP Client
Components 4.x.</t>
+      <t>Support for Asynchronous, non-blocking HTTP Client operations leveraging the
java.util.concurrent.Executor framework and java.util.concurrent.Future</t>
+      <t>Refactored Publishing Server Provider framework, simplifying the overall architecture
and tying in new capabilities from the new Common Code library.</t>
+      <t>Improved Atom Parsing Performance (my informal testing has demonstrated about
a 20-25% improvement on average)</t>
+      <t>Complete JSON Activity Streams implementation:
+        <list>      
+          <t>Support for generating and consuming Activity Streams</t>
+          <t>Support for all core Object Types and Verbs</t>
+          <t>Support for a number of extension Object Types and Verbs</t>
+          <t>Fluent, factory-model API</t>
+          <t>Immutable, thread-safe objects</t>
+          <t>Streaming Serialization API</t>
+          <t>API for using existing Activities objects as template to create new objects</t>
+          <t>Extensible serialization/deserialization</t>
+          <t>Asynchronous, non-blocking parsing and serialization</t>
+          <t>Support for primary Activity Streams extensions such as Replies and Audience
Targeting</t>
+          <t>Experimental mode that allows playing around with new experimental extensions</t>
+          <t>JSON Web Token Support</t>
+          <t>Client and Server side Activity Streams based API support</t>
+          <t>Type-safe dynamic extensibility API</t>
+          <t>Merge/Diff API</t>
+          <t>Filter API based on Selectors</t>
+          <t>Conversion of JSON Activity Stream to and from Atom</t>
+        </list></t>
+    </list></t>
+
+    <t>It is important to point out that Abdera2 is NOT binary compatible with 
+    the 1.x version. While much of the basic Feed Object Model (FOM) API 
+    remains unchanged, there have been many changes specifically in the area 
+    of Date handling and the introduction of the Selector framework. 
+    Accordingly, the Abdera2 Java Package has been changed to 
+    org.apache.abdera2.*.</t>
+    
+    <t>Also, it must be noted that the Server and Client frameworks have 
+    been completely refactored as well. Custom Provider implementations based 
+    on the BasicProvider API should require fairly little modification to work 
+    under Abdera2, but in general, Adapters and Providers written to the 1.x 
+    code will need to be migrated to the new refactored design. Detailed 
+    documentation on the new design will be provided.</t>
+    
+  </section>
+    
+  <section title="Package Changes">
+  
+  <t>TBD</t>
+  
+  </section>
+    
+  </middle>
+  <back></back>
+</rfc>
\ No newline at end of file

Propchange: abdera/abdera2/docs/Getting.Started/whatsnew.xml
------------------------------------------------------------------------------
    svn:mime-type = text/plain



Mime
View raw message