Author: jmsnell
Date: Tue Dec 27 19:58:27 2011
New Revision: 1224997
URL: http://svn.apache.org/viewvc?rev=1224997&view=rev
Log:
docs and fixes
Modified:
abdera/abdera2/common/src/main/java/org/apache/abdera2/common/http/EntityTag.java
abdera/abdera2/common/src/main/java/org/apache/abdera2/common/http/Preference.java
abdera/abdera2/docs/Getting.Started/common.xml
Modified:
abdera/abdera2/common/src/main/java/org/apache/abdera2/common/http/EntityTag.java
URL:
http://svn.apache.org/viewvc/abdera/abdera2/common/src/main/java/org/apache/abdera2/common/http/EntityTag.java?rev=1224997&r1=1224996&r2=1224997&view=diff
==============================================================================
---
abdera/abdera2/common/src/main/java/org/apache/abdera2/common/http/EntityTag.java
(original)
+++
abdera/abdera2/common/src/main/java/org/apache/abdera2/common/http/EntityTag.java
Tue Dec 27 19:58:27 2011
@@ -49,6 +49,14 @@ public class EntityTag
public static final EntityTag WILD = new EntityTag("*");
+ public static EntityTag create(String tag) {
+ return new EntityTag(tag);
+ }
+
+ public static EntityTag weak(String tag) {
+ return new EntityTag(tag,true);
+ }
+
public static EntityTag parse(String entity_tag) {
checkNotNull(entity_tag);
checkArgument(entity_tag.length() > 0, "Invalid");
Modified:
abdera/abdera2/common/src/main/java/org/apache/abdera2/common/http/Preference.java
URL:
http://svn.apache.org/viewvc/abdera/abdera2/common/src/main/java/org/apache/abdera2/common/http/Preference.java?rev=1224997&r1=1224996&r2=1224997&view=diff
==============================================================================
---
abdera/abdera2/common/src/main/java/org/apache/abdera2/common/http/Preference.java
(original)
+++
abdera/abdera2/common/src/main/java/org/apache/abdera2/common/http/Preference.java
Tue Dec 27 19:58:27 2011
@@ -82,11 +82,11 @@ public class Preference implements Seria
public static final Preference PREF_RETURN_REPRESENTATION =
new Preference(RETURN_REPRESENTATION);
- public static Preference WAIT(long millis) {
+ public static Preference WAIT(long seconds) {
return
make()
.token(WAIT)
- .value(millis)
+ .value(seconds)
.get();
}
Modified: abdera/abdera2/docs/Getting.Started/common.xml
URL:
http://svn.apache.org/viewvc/abdera/abdera2/docs/Getting.Started/common.xml?rev=1224997&r1=1224996&r2=1224997&view=diff
==============================================================================
--- abdera/abdera2/docs/Getting.Started/common.xml (original)
+++ abdera/abdera2/docs/Getting.Started/common.xml Tue Dec 27 19:58:27 2011
@@ -72,7 +72,233 @@ col.getItems(activityPublished(atOrBetwe
<section title="HTTP Headers">
- <t>TBD</t>
+ <t>The Abdera2 Common Library includes support for a handful of
+ complex HTTP Headers including WWW-Authenticate, Cache-Control,
+ ETag, Link and Preference.</t>
+
+ <section title="WWW-Authenticate">
+
+ <t>The Authentication header support makes it easier to support
+ custom authentication mechanisms within Abdera2 applications.
+ For instance, to use OAuth 2.0 Bearer Tokens, you can use:</t>
+
+ <figure><artwork>
+ Authentication bearer =
+ Authentication.make()
+ .scheme("bearer")
+ .param("realm", "example")
+ .get();
+ </artwork></figure>
+
+ <figure><preamble>Which generates:</preamble><artwork>
+ WWW-Authenticate: bearer realm="example"
+ </artwork></figure>
+
+ <t>Adding additional parameters is straightforward:</t>
+
+ <figure><artwork>
+ Authentication bearer =
+ Authentication.make()
+ .scheme("bearer")
+ .param("realm", "example")
+ .param("error", "invalid_token")
+ .param("error_description", "The access token expired")
+ .get();
+ </artwork></figure>
+
+ <t>Parsing the header is equally straightforward:</t>
+
+ <figure><artwork><![CDATA[
+ Iterable<Authentication> auths =
+ Authentication.parse(
+ "bearer realm=\"example\", error=invalid_token"+
+ ", error_description=\"The access token expired\"");
+
+ Authentication auth = auths.iterator().next();
+
+ System.out.println(auth.getScheme());
+ for (String name : auth) {
+ System.out.println(
+ String.format(
+ "%s = %s",
+ name,
+ auth.getParam(name)));
+ }
+ ]]></artwork></figure>
+
+ </section>
+
+ <section title="Cache-Control">
+
+ <t>The CacheControl class makes it simple to generate and parse any
+ combination of Cache-Control directives:</t>
+
+ <figure><artwork>
+ CacheControl cc =
+ CacheControl.make()
+ .isPublic()
+ .maxAge(1000)
+ .mustRevalidate()
+ .get();
+ </artwork></figure>
+
+ <figure><preamble>Generates:</preamble><artwork>
+ Cache-Control: public, must-revalidate, max-age=1000
+ </artwork></figure>
+
+ <figure><artwork>
+ CacheControl cc =
+ CacheControl.make()
+ .noCache()
+ .noStore()
+ .noTransform()
+ .isPrivate()
+ .get();
+ </artwork></figure>
+
+ <figure><preamble>Generates:</preamble><artwork>
+ Cache-Control: private, no-cache, no-store, no-transform
+ </artwork></figure>
+
+ <t>Extension directives are also supported:</t>
+
+ <figure><artwork>
+ CacheControl cc =
+ CacheControl.make()
+ .isPublic()
+ .extension("foo", "bar")
+ .get();
+ </artwork></figure>
+
+ <figure><preamble>Generates:</preamble><artwork>
+ Cache-Control: public, foo=bar
+ </artwork></figure>
+
+ </section>
+
+ <section title="Entity Tags">
+
+ <figure><preamble>Create a simple strong EntityTag:</preamble><artwork>
+ EntityTag tag = EntityTag.create("FooBarBaz")
+ </artwork></figure>
+
+ <figure><preamble>Generates:</preamble><artwork>
+ ETag: "FooBarBaz"
+ </artwork></figure>
+
+ <figure><preamble>Create a weak EntityTag:</preamble><artwork>
+ EntityTag tag = EntityTag.weak("FooBarBaz");
+ </artwork></figure>
+
+ <figure><preamble>Generates:</preamble><artwork>
+ ETag: W/"FooBarBaz"
+ </artwork></figure>
+
+ <figure><preamble>Generating an Entity Tag from source
material:</preamble><artwork>
+ EntityTag tag = EntityTag.generate("foo","bar","baz");
+ </artwork></figure>
+
+ <figure><preamble>Generates:</preamble><artwork>
+ ETag: "6DF23DC03F9B54CC38A0FC1483DF6E21"
+ </artwork></figure>
+
+ <figure><preamble>Parsing Entity Tags:</preamble><artwork><![CDATA[
+ Iterable<EntityTag> list =
+ EntityTag.parseTags(
+ "\"FooBarBaz\", W/\"6DF23DC03F9B54CC38A0FC1483DF6E21\"");
+
+ for (EntityTag tag : list) {
+ System.out.println(
+ String.format(
+ "%s, is weak? %s",
+ tag.getTag(),
+ tag.isWeak()
+ ));
+ ]]></artwork></figure>
+
+ <figure><preamble>Outputs:</preamble><artwork>
+ FooBarBaz, is weak? false
+ 6DF23DC03F9B54CC38A0FC1483DF6E21, is weak? true
+ </artwork></figure>
+
+ </section>
+
+ <section title="Links">
+
+ <figure><artwork>
+ WebLink link =
+ WebLink.make()
+ .iri("styles.css")
+ .rel("stylesheet")
+ .title("Just an example")
+ .media("print")
+ .get();
+ </artwork></figure>
+
+ <figure><preamble>Generates:</preamble><artwork><![CDATA[
+ Link: <styles.css>;rel="stylesheet";media="print";title="Just an example"
+ ]]></artwork></figure>
+
+ <figure><preamble>Parsing:</preamble><artwork><![CDATA[
+ Iterable<WebLink> list =
+ WebLink.parse(
+ "<styles.css>;rel=\"stylesheet\";"+
+ "media=\"print\";title=\"Just an example\"");
+
+ for (WebLink link : list) {
+ System.out.println(link.getIri());
+ System.out.println(link.getRel());
+ System.out.println(link.getMedia());
+ System.out.println(link.getTitle());
+ }
+ ]]></artwork></figure>
+
+ <figure><preamble>Outputs:</preamble><artwork>
+ styles.css
+ [stylesheet]
+ [print]
+ Just an example
+ </artwork></figure>
+
+ </section>
+
+ <section title="Preference">
+
+ <t>The <eref
target="http://tools.ietf.org/html/draft-snell-http-prefer-10";>Prefer
header</eref>
+ is a proposed extension to HTTP.</t>
+
+ <figure><artwork>
+ import static org.apache.abdera2.common.http.Preference.*;
+
+ System.out.println(
+ toString(
+ PREF_LENIENT,
+ PREF_RETURN_ASYNCH,
+ WAIT(1000)));
+ </artwork></figure>
+
+ <figure><preamble>Generates:</preamble><artwork>
+ Prefer: lenient,return-asynch,wait=1000
+ </artwork></figure>
+
+ <figure><preamble>Parsing:</preamble><artwork><![CDATA[
+ Iterable<Preference> list =
+ parse(
+ "lenient,return-asynch,wait=1000");
+
+ if (contains(list, LENIENT)) {
+ // use lenient processing
+ }
+
+ if (contains(list, RETURN_ASYNCH)) {
+ // use asynchronous processing
+ Preference wait = get(list, WAIT);
+ long time = wait.getLongValue();
+ // ...
+ }
+ ]]></artwork></figure>
+
+ </section>
</section>
