You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@esme.apache.org by bu...@apache.org on 2011/06/27 15:55:31 UTC
svn commit: r791676 [2/8] - /websites/staging/esme/trunk/content/
Added: websites/staging/esme/trunk/content/api-2.0---design.cwiki
==============================================================================
--- websites/staging/esme/trunk/content/api-2.0---design.cwiki (added)
+++ websites/staging/esme/trunk/content/api-2.0---design.cwiki Mon Jun 27 13:55:28 2011
@@ -0,0 +1,184 @@
+{float:right|width=40%}
+{panel:title=Contents}
+{toc}
+{panel}
+
+{panel:title=Points for discussion, resolution, further work}
+# Is the use of HTTP sessions necessary? Is it desirable?
+# Request signing methods?
+# Payload and response schemas must be defined
+# Should API contain admin functions?
+# Webhooks ([http://blog.webhooks.org/])
+#* ESME has webhooks as part of its actions framework, but we may want to document their existence as part of the API, and possibly improve the functionality if there are use cases ([http://incubator.apache.org/esme/actions.html])
+# What is a conversation?
+# Authorization approach (see above)
+# What is our streaming approach?
+{panel}
+{float}
+
+h2. Streams vs. Resources
+
+In the design below, all parts of ESME are modeled as resources, in keeping with a RESTful approach. Our streaming resources (also thought of as delta-queue resources) are collections that are only additive. We have defined a general streaming interface that strives to be RESTful while prioritizing the performance benefits of streams.
+
+References - Dev mailing list thread - [http://www.mail-archive.com/esme-dev@incubator.apache.org/msg00976.html]
+
+h2. Resource/Object/Stream Hierarchy
+
+The above is based on a rough object hierarchy as follows:
+
+* ESME API instance (api/)
+** Session (api2/session)
+** Users (api2/users)
+*** Specific User (api2/users/USERID)
+**** User's tokens (api2/users/USERID/tokens)
+** Messages posted by logged in user (api2/user/messages) (1)
+** Users followed by logged in user (api2/user/followees)
+** Users following logged in user (api2/user/followers)
+** Trackers belonging to logged in user (api2/user/tracks)
+*** Messages from a track (api2/user/tracks/TRACKID/messages) (1)
+** Actions belonging to logged in user (api2/user/actions)
+** Messages (api2/messages) (1)
+** Tags (api2/tags)
+*** Messages posted to a tag (api2/tags/TAG/messages) (1)
+** Conversations (api2/conversations)
+*** Messages posted to a conversation (api2/conversations/CONVERSATIONID/messages) (1)
+** Pools (api2/pools)
+*** Users associated with a pool (api2/pools/POOLID/users)
+*** Messages posted to a pool (api2/pools/POOLID/messages) (1)
+** Searches ?? (1)
+** Trends ??
+
+(1) Stream interface
+
+Each of these bullets represents a set of objects. The resource representing an individual object lives at api/objects/OBJECTID. For example, api/conversations/1. As much as is reasonable, one would expect to be able to GET (read), POST (create), PUT (update/amend), or DELETE (delete) any individual member of each of these object sets. Going through each of these objects to ask what it would mean to create, read, update, or delete that object may reveal holes in the existing API, some of which I have filled in above.
+
+h2. Methods, Resources, and Descriptions
+
+*Bold* means the resource and method is implemented in the current /api2/ endpoint.
+
+|| Resource || Method || Description/Payload schema/Response schema || Streaming? || Admin Only? ||
+| *api2/session* | *GET*,*POST*,*DELETE* | Post parameter: token | |
+| *api2/users* | *GET*, *POST* | Post parameters: nickname, password - returns: user created | | *POST* |
+| api2/users/USERID | GET | | |
+| *api2/users/USERID/tokens* | *GET*, *POST* | Post parameters: description - returns: token created | | *GET*, *POST* |
+| *api2/user/messages* | *GET*,*POST* | Post parameters: message, via (opt), pool (opt), realm (opt), metadata (opt), tags (opt), replyto (opt) | *Yes* |
+| api2/user/tags/TAG | GET | | |
+| *api2/user/tags/TAG/messages* | *GET* | | Yes |
+| *api2/user/followers* | *GET* | | |
+| *api2/user/followees* | *GET*,*POST* | Post parameter: userId | |
+| *api2/user/followees/USERID* | *DELETE* | | |
+| *api2/user/tracks* | *GET*,*POST* | Post parameter: track (regex) | |
+| *api2/user/tracks/TRACKID* | GET,*DELETE* | | |
+| api2/user/tracks/TRACKID/messages | GET | | Yes |
+| *api2/user/actions* | *GET*,*POST* | Post parameter: name, test, action | |
+| *api2/user/actions/ACTIONID* | GET,*PUT*,*DELETE* | Put parameter: enabled (boolean) | |
+| api2/messages/MESSAGEID | GET | | |
+| api2/messages | GET,POST | | Yes |
+| *api2/conversations/CONVERSATIONID* | *GET* | | |
+| api2/conversations/CONVERSATIONID/messages | GET,POST | | Yes |
+| *api2/pools* | *GET*,*POST* | | |
+| api2/pools/POOLID | GET,DELETE | | |
+| *api2/pools/POOLID/users* | GET,*POST* | Post parameters: realm, userId, permission | |
+| api2/pools/POOLID/users/USERID | DELETE | | |
+| *api2/pools/POOLID/messages* | *GET*,POST | | *Yes* |
+
+One point to note is that some HTTP clients do not currently support the "PUT" or "DELETE" methods, so these may have to be simulated through POST methods with an extra parameter. I think that because of the close mapping to resource verbs, is worth using these methods in the specification and defining the simulation method for the entire API separately.
+
+h2.
+
+{panel}
+*Note on the call: *[api2/user/messages|http://esmecloudserverapache.dickhirsch.staxapps.net/api2/user/messages?via=SAPRiver&tag=bob&message=User+']
+
+That call uses "tag", not "tags". Looking at the API2 code, the parameter name needs to be "tags".
+
+When it does work, I think the behavior may be a bit misleading, as tags added using the tags parameter do not necessarily show up in the message at all. So make sure to keep an eye on the tag cloud or go to the page for the specific tag you are trying to add and see if it shows up there.
+{panel}
+
+h2. Streams
+
+There are a lot of ways we can model streams and I'm very interested in input here. Options for interfacing to streams that I have seen:
+
+* XMPP - [http://xmpp.org/]
+* AMQP - [http://jira.amqp.org/confluence/display/AMQP/Advanced+Message+Queuing+Protocol]
+* HTTP
+** Polling (bad)
+** Comet/long-polling - Bayeux - [http://svn.cometd.com/trunk/bayeux/bayeux.html]
+** Reverse HTTP - [http://www.reversehttp.net/]
+** PubSubHubBub? - possibly via Reverse HTTP - [http://www.reversehttp.net/demos/endpoint.html]
+
+h3. Authorization and roles
+
+Certain API methods are only available to certain roles, as defined in property files. If an API method has a notation in the "Admin only?" column, this means that the user attempting to interact with that API method must have the proper role assigned in the relevant property file.
+
+For example, take a look at the test.default.props file in the /server/resources/props directory.
+
+Or, for example, create a prod.default.props file in the "server/resources/props" directory. In this file, add the line "role.myuser=integration-admin", where
+"myuser" is the username that you want to have super-powers.
+("integration-admin" is what we're calling the role.)
+
+h3. ESME HTTP Comet/long-polling implementation for streams
+
+In general, for any resource URL that indicates streaming is implemented above, we will implement an HTTP-based streaming interface. This interface might better be referred to as a "delta" interface. The URL will behave as follows (we use api2/user/messages as an example):
+
+|| URL || Request || Query Parameters || Behavior ||
+| api2/user/messages | GET | | Returns any messages not already read by the client |
+| api2/user/messages | GET | timeout=20 | If new messages not already read by the client exist, these are returned. If no new messages exist, the request will stall for a number of seconds as defined in the timeout= parameter. If a new message arrives during this time, the request will immediately resolve, returning the new message. |
+| api2/user/messages | GET | history=10 | Returns the last 10 messages in the timeline |
+
+Response codes follow normal HTTP meanings:
+
+|| Response Code || Meaning ||
+| 200 | Success - Response body should include messages |
+| 204 | No Content - No new messages in the stream (only returned for base URL and ?timeout= requests, not for ?history= requests). Should be 304 Not Modified, but not currently supported in Lift. |
+| 403 | Forbidden - Either the session is invalid or non-existent, or the user is not authorized to access the resource. Eventually we'll move to 401s for invalid/non-existent sessions, but currently we can't return a WWW-Authenticate header field that will result in the right behavior, so we're just stopping the request dead with a 403. |
+| 404 | Not found - for example, a request for the stream of a tag that doesn't exist |
+
+
+Once this interface is implemented where planned for a URL, the "Yes" above in the "Streaming?" column will be bolded.
+
+{gliffy:name=ESME delta message HTTP API|space=ESME|page=API 2.0 - Design|pageid=2329310|align=left|size=M}
+
+h3. Streams/Message-queues in ESME and in general
+
+{gliffy:name=ESME message queues|space=ESME|page=API 2.0 - Design|pageid=2329310|align=left|size=M}
+
+h2. Formats
+
+h3. Request formats
+
+*Format specification*
+
+If there is a request body, format should be specified using the Content-Type HTTP header.
+
+*Formats to be supported*
+
+* XML ?
+* JSON ?
+* Multi-part Form-encoded ?
+* Form-encoded
+
+h3. Response formats
+
+*Format specification*
+
+Format could be specified using the HTTP Accept header - [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html]
+
+Another option (though not as robust) would be to append the format to the resource request url. For example /api/users/USERID.json
+
+*Formats to be supported*
+
+* XML ?
+* JSON ?
+* ...
+
+h2. Authorization
+
+Currently the ESME REST API uses tokens as the authorization mechanism. A token is used to establish a session and then the session is used to persist the authorization of the API client across the length of the session.
+
+There are a couple of problems with this, though we don't have a better approach at the moment:
+# Sessions are not natively supported in a lot of API programming environments, especially environments that do not have a persistent data-store available to the application.
+# The current API design appears encourage that the token sent to establish the session be sent in the clear over an unencrypted connection.
+
+h2. Clients
+
+Daniel Koller has created an initial client for the Streaming api. The client is currently attached to a [Jira item|http://issues.apache.org/jira/secure/attachment/12426366/esme2java.jar]
\ No newline at end of file
Added: websites/staging/esme/trunk/content/api-2.0---design.html
==============================================================================
--- websites/staging/esme/trunk/content/api-2.0---design.html (added)
+++ websites/staging/esme/trunk/content/api-2.0---design.html Mon Jun 27 13:55:28 2011
@@ -0,0 +1,312 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ 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.
+-->
+
+ <link href="/css/esme.css" rel="stylesheet" type="text/css">
+ <title>Apache ESME - API 2.0 - Design</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/images/esme-logo/stanbol-favicon.png"/>
+</head>
+
+<body>
+ <div id="navigation">
+ <img alt="Apache ESME" width="220" height="101" src="/images/esme-logo/esme-powerd.gif"/>
+ <h1 id="esme_links">ESME links</h1>
+<ul>
+<li><a href="/index.html">Home</a></li>
+<li><a href="/team.html">Project Team</a></li>
+<li><a href="/docs/buildfromSVN.html">Building ESME</a></li>
+<li><a href="/docs/faq.html">FAQ</a></li>
+<li><a href="/docs/actions.html">Actions</a></li>
+<li><a href="/docs/apis.html">APIs</a></li>
+<li><a href="/docs/clients.html">Clients</a></li>
+<li><a href="/docs/collaboration.html">Collaboration</a></li>
+<li><a href="/docs/install.html">Installation Guides</a></li>
+<li><a href="/docs/yql.html">YQL</a><br />
+</li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">API 2.0 - Design</h1>
+ <p>{float:right|width=40%}
+{panel:title=Contents}
+ * <a href="#API2.0-Design-Streamsvs.Resources">Streams vs. Resources</a>
+ * <a href="#API2.0-Design-Resource/Object/StreamHierarchy">Resource/Object/Stream Hierarchy</a>
+ * <a href="#API2.0-Design-Methods,Resources,andDescriptions">Methods, Resources, and Descriptions</a>
+ * <a href="#API2.0-Design-" />
+ * <a href="#API2.0-Design-Streams">Streams</a>
+ * <a href="#API2.0-Design-Authorizationandroles">Authorization and roles</a>
+ * <a href="#API2.0-Design-ESMEHTTPComet/long-pollingimplementationforstreams">ESME HTTP Comet/long-polling implementation for streams</a>
+ * <a href="#API2.0-Design-Streams/Message-queuesinESMEandingeneral">Streams/Message-queues in ESME and in general</a>
+ * <a href="#API2.0-Design-Formats">Formats</a>
+ * <a href="#API2.0-Design-Requestformats">Request formats</a>
+ * <a href="#API2.0-Design-Responseformats">Response formats</a>
+ * <a href="#API2.0-Design-Authorization">Authorization</a>
+ * <a href="#API2.0-Design-Clients">Clients</a>
+{panel}</p>
+<p>{panel:title=Points for discussion, resolution, further work}
+1. Is the use of HTTP sessions necessary? Is it desirable?
+1. Request signing methods?
+1. Payload and response schemas must be defined
+1. Should API contain admin functions?
+1. Webhooks (<a href="http://blog.webhooks.org/">http://blog.webhooks.org/</a>
+)
+1. * ESME has webhooks as part of its actions framework, but we may want to document their existence as part of the API, and possibly improve the functionality if there are use cases (<a href="http://incubator.apache.org/esme/actions.html">http://incubator.apache.org/esme/actions.html</a>
+)
+1. What is a conversation?
+1. Authorization approach (see above)
+1. What is our streaming approach?
+{panel}
+{float}</p>
+<p><a name="API2.0-Design-Streamsvs.Resources"></a></p>
+<h2 id="streams_vs_resources">Streams vs. Resources</h2>
+<p>In the design below, all parts of ESME are modeled as resources, in keeping
+with a RESTful approach. Our streaming resources (also thought of as
+delta-queue resources) are collections that are only additive. We have
+defined a general streaming interface that strives to be RESTful while
+prioritizing the performance benefits of streams.</p>
+<p>References - Dev mailing list thread - <a href="http://www.mail-archive.com/esme-dev@incubator.apache.org/msg00976.html">http://www.mail-archive.com/esme-dev@incubator.apache.org/msg00976.html</a></p>
+<p><a name="API2.0-Design-Resource/Object/StreamHierarchy"></a></p>
+<h2 id="resourceobjectstream_hierarchy">Resource/Object/Stream Hierarchy</h2>
+<p>The above is based on a rough object hierarchy as follows:</p>
+<ul>
+<li>ESME API instance (api/)
+<strong> Session (api2/session)
+</strong> Users (api2/users)
+<strong><em> Specific User (api2/users/USERID)
+</em></strong><em> User's tokens (api2/users/USERID/tokens)
+<strong> Messages posted by logged in user (api2/user/messages) (1)
+</strong> Users followed by logged in user (api2/user/followees)
+<strong> Users following logged in user (api2/user/followers)
+</strong> Trackers belonging to logged in user (api2/user/tracks)
+<strong><em> Messages from a track (api2/user/tracks/TRACKID/messages) (1)
+<strong> Actions belonging to logged in user (api2/user/actions)
+</strong> Messages (api2/messages) (1)
+** Tags (api2/tags)</em></strong> Messages posted to a tag (api2/tags/TAG/messages) (1)
+<strong> Conversations (api2/conversations)
+<strong><em> Messages posted to a conversation
+(api2/conversations/CONVERSATIONID/messages) (1)
+** Pools (api2/pools)
+</em></strong> Users associated with a pool (api2/pools/POOLID/users)
+</strong></em> Messages posted to a pool (api2/pools/POOLID/messages) (1)
+<strong> Searches ?? (1)
+</strong> Trends ??</li>
+</ul>
+<p>(1) Stream interface</p>
+<p>Each of these bullets represents a set of objects. The resource
+representing an individual object lives at api/objects/OBJECTID. For
+example, api/conversations/1. As much as is reasonable, one would expect to
+be able to GET (read), POST (create), PUT (update/amend), or DELETE
+(delete) any individual member of each of these object sets. Going through
+each of these objects to ask what it would mean to create, read, update, or
+delete that object may reveal holes in the existing API, some of which I
+have filled in above.</p>
+<p><a name="API2.0-Design-Methods,Resources,andDescriptions"></a></p>
+<h2 id="methods_resources_and_descriptions">Methods, Resources, and Descriptions</h2>
+<p><em>Bold</em> means the resource and method is implemented in the current /api2/
+endpoint.</p>
+<table>
+<tr><th> Resource </th><th> Method </th><th> Description/Payload schema/Response schema </th><th>
+Streaming? </th><th> Admin Only? </th></tr>
+<tr><td> *api2/session* </td><td> *GET*,*POST*,*DELETE* </td><td> Post parameter: token </td><td> </td></tr>
+<tr><td> *api2/users* </td><td> *GET*, *POST* </td><td> Post parameters: nickname, password -
+returns: user created </td><td> </td><td> *POST* </td></tr>
+<tr><td> api2/users/USERID </td><td> GET </td><td> </td><td> </td></tr>
+<tr><td> *api2/users/USERID/tokens* </td><td> *GET*, *POST* </td><td> Post parameters: description
+- returns: token created </td><td> </td><td> *GET*, *POST* </td></tr>
+<tr><td> *api2/user/messages* </td><td> *GET*,*POST* </td><td> Post parameters: message, via
+(opt), pool (opt), realm (opt), metadata (opt), tags (opt), replyto (opt) </td><td>
+*Yes* </td></tr>
+<tr><td> api2/user/tags/TAG </td><td> GET </td><td> </td><td> </td></tr>
+<tr><td> *api2/user/tags/TAG/messages* </td><td> *GET* </td><td> </td><td> Yes </td></tr>
+<tr><td> *api2/user/followers* </td><td> *GET* </td><td> </td><td> </td></tr>
+<tr><td> *api2/user/followees* </td><td> *GET*,*POST* </td><td> Post parameter: userId </td><td> </td></tr>
+<tr><td> *api2/user/followees/USERID* </td><td> *DELETE* </td><td> </td><td> </td></tr>
+<tr><td> *api2/user/tracks* </td><td> *GET*,*POST* </td><td> Post parameter: track (regex) </td><td> </td></tr>
+<tr><td> *api2/user/tracks/TRACKID* </td><td> GET,*DELETE* </td><td> </td><td> </td></tr>
+<tr><td> api2/user/tracks/TRACKID/messages </td><td> GET </td><td> </td><td> Yes </td></tr>
+<tr><td> *api2/user/actions* </td><td> *GET*,*POST* </td><td> Post parameter: name, test, action </td><td>
+</td></tr>
+<tr><td> *api2/user/actions/ACTIONID* </td><td> GET,*PUT*,*DELETE* </td><td> Put parameter:
+enabled (boolean) </td><td> </td></tr>
+<tr><td> api2/messages/MESSAGEID </td><td> GET </td><td> </td><td> </td></tr>
+<tr><td> api2/messages </td><td> GET,POST </td><td> </td><td> Yes </td></tr>
+<tr><td> *api2/conversations/CONVERSATIONID* </td><td> *GET* </td><td> </td><td> </td></tr>
+<tr><td> api2/conversations/CONVERSATIONID/messages </td><td> GET,POST </td><td> </td><td> Yes </td></tr>
+<tr><td> *api2/pools* </td><td> *GET*,*POST* </td><td> </td><td> </td></tr>
+<tr><td> api2/pools/POOLID </td><td> GET,DELETE </td><td> </td><td> </td></tr>
+<tr><td> *api2/pools/POOLID/users* </td><td> GET,*POST* </td><td> Post parameters: realm, userId,
+permission </td><td> </td></tr>
+<tr><td> api2/pools/POOLID/users/USERID </td><td> DELETE </td><td> </td><td> </td></tr>
+<tr><td> *api2/pools/POOLID/messages* </td><td> *GET*,POST </td><td> </td><td> *Yes* </td></tr>
+</table>
+
+<p>One point to note is that some HTTP clients do not currently support the
+"PUT" or "DELETE" methods, so these may have to be simulated through POST
+methods with an extra parameter. I think that because of the close mapping
+to resource verbs, is worth using these methods in the specification and
+defining the simulation method for the entire API separately.</p>
+<p><a name="API2.0-Design-"></a></p>
+<h2 id="" />
+<p>{panel}
+<em>Note on the call: </em><a href="http://esmecloudserverapache.dickhirsch.staxapps.net/api2/user/messages?via=SAPRiver&tag=bob&message=User+'">api2/user/messages</a></p>
+<p>That call uses "tag", not "tags". Looking at the API2 code, the parameter
+name needs to be "tags". </p>
+<p>When it does work, I think the behavior may be a bit misleading, as tags
+added using the tags parameter do not necessarily show up in the message at
+all. So make sure to keep an eye on the tag cloud or go to the page for the
+specific tag you are trying to add and see if it shows up there.
+{panel}</p>
+<p><a name="API2.0-Design-Streams"></a></p>
+<h2 id="streams">Streams</h2>
+<p>There are a lot of ways we can model streams and I'm very interested in
+input here. Options for interfacing to streams that I have seen:</p>
+<ul>
+<li>XMPP - <a href="http://xmpp.org/">http://xmpp.org/</a></li>
+<li>AMQP - <a href="http://jira.amqp.org/confluence/display/AMQP/Advanced+Message+Queuing+Protocol">http://jira.amqp.org/confluence/display/AMQP/Advanced+Message+Queuing+Protocol</a></li>
+<li>HTTP
+<strong> Polling (bad)
+</strong> Comet/long-polling - Bayeux - <a href="http://svn.cometd.com/trunk/bayeux/bayeux.html">http://svn.cometd.com/trunk/bayeux/bayeux.html</a>
+<strong> Reverse HTTP - <a href="http://www.reversehttp.net/">http://www.reversehttp.net/</a>
+</strong> PubSubHubBub? - possibly via Reverse HTTP - <a href="http://www.reversehttp.net/demos/endpoint.html">http://www.reversehttp.net/demos/endpoint.html</a></li>
+</ul>
+<p><a name="API2.0-Design-Authorizationandroles"></a></p>
+<h3 id="authorization_and_roles">Authorization and roles</h3>
+<p>Certain API methods are only available to certain roles, as defined in
+property files. If an API method has a notation in the "Admin only?"
+column, this means that the user attempting to interact with that API
+method must have the proper role assigned in the relevant property file.</p>
+<p>For example, take a look at the test.default.props file in the
+/server/resources/props directory.</p>
+<p>Or, for example, create a prod.default.props file in the
+"server/resources/props" directory. In this file, add the line
+"role.myuser=integration-admin", where
+"myuser" is the username that you want to have super-powers.
+("integration-admin" is what we're calling the role.)</p>
+<p><a name="API2.0-Design-ESMEHTTPComet/long-pollingimplementationforstreams"></a></p>
+<h3 id="esme_http_cometlong-polling_implementation_for_streams">ESME HTTP Comet/long-polling implementation for streams</h3>
+<p>In general, for any resource URL that indicates streaming is implemented
+above, we will implement an HTTP-based streaming interface. This interface
+might better be referred to as a "delta" interface. The URL will behave as
+follows (we use api2/user/messages as an example):</p>
+<table>
+<tr><th> URL </th><th> Request </th><th> Query Parameters </th><th> Behavior </th></tr>
+<tr><td> api2/user/messages </td><td> GET </td><td> </td><td> Returns any messages not already read by the
+client </td></tr>
+<tr><td> api2/user/messages </td><td> GET </td><td> timeout=20 </td><td> If new messages not already read
+by the client exist, these are returned. If no new messages exist, the
+request will stall for a number of seconds as defined in the timeout=
+parameter. If a new message arrives during this time, the request will
+immediately resolve, returning the new message. </td></tr>
+<tr><td> api2/user/messages </td><td> GET </td><td> history=10 </td><td> Returns the last 10 messages in
+the timeline </td></tr>
+</table>
+
+<p>Response codes follow normal HTTP meanings:</p>
+<table>
+<tr><th> Response Code </th><th> Meaning </th></tr>
+<tr><td> 200 </td><td> Success - Response body should include messages </td></tr>
+<tr><td> 204 </td><td> No Content - No new messages in the stream (only returned for base
+URL and ?timeout= requests, not for ?history= requests). Should be 304 Not
+Modified, but not currently supported in Lift. </td></tr>
+<tr><td> 403 </td><td> Forbidden - Either the session is invalid or non-existent, or the
+user is not authorized to access the resource. Eventually we'll move to
+401s for invalid/non-existent sessions, but currently we can't return a
+WWW-Authenticate header field that will result in the right behavior, so
+we're just stopping the request dead with a 403. </td></tr>
+<tr><td> 404 </td><td> Not found - for example, a request for the stream of a tag that
+doesn't exist </td></tr>
+</table>
+
+<p>Once this interface is implemented where planned for a URL, the "Yes" above
+in the "Streaming?" column will be bolded.</p>
+<p>{gliffy:name=ESME delta message HTTP API|space=ESME|page=API 2.0 -
+Design|pageid=2329310|align=left|size=M}</p>
+<p><a name="API2.0-Design-Streams/Message-queuesinESMEandingeneral"></a></p>
+<h3 id="streamsmessage-queues_in_esme_and_in_general">Streams/Message-queues in ESME and in general</h3>
+<p>{gliffy:name=ESME message queues|space=ESME|page=API 2.0 -
+Design|pageid=2329310|align=left|size=M}</p>
+<p><a name="API2.0-Design-Formats"></a></p>
+<h2 id="formats">Formats</h2>
+<p><a name="API2.0-Design-Requestformats"></a></p>
+<h3 id="request_formats">Request formats</h3>
+<p><em>Format specification</em></p>
+<p>If there is a request body, format should be specified using the
+Content-Type HTTP header.</p>
+<p><em>Formats to be supported</em></p>
+<ul>
+<li>XML ?</li>
+<li>JSON ?</li>
+<li>Multi-part Form-encoded ?</li>
+<li>Form-encoded</li>
+</ul>
+<p><a name="API2.0-Design-Responseformats"></a></p>
+<h3 id="response_formats">Response formats</h3>
+<p><em>Format specification</em></p>
+<p>Format could be specified using the HTTP Accept header - <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html</a></p>
+<p>Another option (though not as robust) would be to append the format to the
+resource request url. For example /api/users/USERID.json</p>
+<p><em>Formats to be supported</em></p>
+<ul>
+<li>XML ?</li>
+<li>JSON ?</li>
+<li>...</li>
+</ul>
+<p><a name="API2.0-Design-Authorization"></a></p>
+<h2 id="authorization">Authorization</h2>
+<p>Currently the ESME REST API uses tokens as the authorization mechanism. A
+token is used to establish a session and then the session is used to
+persist the authorization of the API client across the length of the
+session.</p>
+<p>There are a couple of problems with this, though we don't have a better
+approach at the moment:
+1. Sessions are not natively supported in a lot of API programming
+environments, especially environments that do not have a persistent
+data-store available to the application.
+1. The current API design appears encourage that the token sent to establish
+the session be sent in the clear over an unencrypted connection.</p>
+<p><a name="API2.0-Design-Clients"></a></p>
+<h2 id="clients">Clients</h2>
+<p>Daniel Koller has created an initial client for the Streaming api. The
+client is currently attached to a <a href="http://issues.apache.org/jira/secure/attachment/12426366/esme2java.jar">Jira item</a></p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, ESME and the Apache feather and ESME logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Added: websites/staging/esme/trunk/content/api.cwiki
==============================================================================
--- websites/staging/esme/trunk/content/api.cwiki (added)
+++ websites/staging/esme/trunk/content/api.cwiki Mon Jun 27 13:55:28 2011
@@ -0,0 +1,21 @@
+h3. APIs
+
+|| Name || Description \\ || Default URL prefix \\ || Status \\ ||
+| [Original|Original API]\\ | *Deprecated* \- This is our original "REST-like" API \\ | /api \\ | Available \\ |
+| [Streaming|ESME:API 2.0 - Design]\\ | *Current* \- This is our newest API that deals allows for streaming-based access \\ | /api2 \\ | Available \\ |
+| [Twitter|Twitter API]\\ | *Twitter* \- We also support the Twitter API which allows for clients that support laconica to also use Apache ESME \\ | /twitter \\ | Available |
+| [JMX|ESME:JMX REST API]\\ | This is an API that will users to access JMX-based \\ | /jmx \\ | Currently being designed \\ |
+*Note*: _It is possible to change the used URL prefixes for the individual APIs via properties._
+
+h4. Using an API
+
+*Clients should be developed using /api2.*
+
+
+If you wish to use a API, then you must take the server name and add the URL prefix.
+
+For example, _[http://esmecloudserverapache.dickhirsch.staxapps.net/twitter|http://esmecloudserverapache.dickhirsch.staxapps.net/twitter_]_
+
+h5. Token
+
+All these APIs require that you use a token.
\ No newline at end of file
Added: websites/staging/esme/trunk/content/api.html
==============================================================================
--- websites/staging/esme/trunk/content/api.html (added)
+++ websites/staging/esme/trunk/content/api.html Mon Jun 27 13:55:28 2011
@@ -0,0 +1,85 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ 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.
+-->
+
+ <link href="/css/esme.css" rel="stylesheet" type="text/css">
+ <title>Apache ESME - API</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/images/esme-logo/stanbol-favicon.png"/>
+</head>
+
+<body>
+ <div id="navigation">
+ <img alt="Apache ESME" width="220" height="101" src="/images/esme-logo/esme-powerd.gif"/>
+ <h1 id="esme_links">ESME links</h1>
+<ul>
+<li><a href="/index.html">Home</a></li>
+<li><a href="/team.html">Project Team</a></li>
+<li><a href="/docs/buildfromSVN.html">Building ESME</a></li>
+<li><a href="/docs/faq.html">FAQ</a></li>
+<li><a href="/docs/actions.html">Actions</a></li>
+<li><a href="/docs/apis.html">APIs</a></li>
+<li><a href="/docs/clients.html">Clients</a></li>
+<li><a href="/docs/collaboration.html">Collaboration</a></li>
+<li><a href="/docs/install.html">Installation Guides</a></li>
+<li><a href="/docs/yql.html">YQL</a><br />
+</li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">API</h1>
+ <p><a name="API-APIs"></a></p>
+<h3 id="apis">APIs</h3>
+<p><em>Note</em>: <em>It is possible to change the used URL prefixes for the individual
+APIs via properties.</em></p>
+<p><a name="API-UsinganAPI"></a></p>
+<h4 id="using_an_api">Using an API</h4>
+<p><em>Clients should be developed using /api2.</em></p>
+<p>If you wish to use a API, then you must take the server name and add the
+URL prefix.</p>
+<p>For example, <em><a href="http://esmecloudserverapache.dickhirsch.staxapps.net/twitter_">http://esmecloudserverapache.dickhirsch.staxapps.net/twitter</a>
+</em></p>
+<p><a name="API-Token"></a></p>
+<h5 id="token">Token</h5>
+<p>All these APIs require that you use a token.</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, ESME and the Apache feather and ESME logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Added: websites/staging/esme/trunk/content/architecture-patterns.cwiki
==============================================================================
--- websites/staging/esme/trunk/content/architecture-patterns.cwiki (added)
+++ websites/staging/esme/trunk/content/architecture-patterns.cwiki Mon Jun 27 13:55:28 2011
@@ -0,0 +1,31 @@
+Possible variants on the uses of Apache ESME in the Internet (cloud-based), in an extranet and in an intranet. We have also looked at different configurations for Apache ESMEâs database as well as its user management functionality (âCorporate LDAPâ).
+
+
+!Slide01.jpg|border=1!
+
+
+!Slide02.jpg|border=1!
+
+
+!Slide03.jpg|border=1!
+
+
+!Slide04.jpg|border=1!
+
+
+!Slide05.jpg|border=1!
+
+
+!Slide06.jpg|border=1!
+
+
+!Slide07.jpg|border=1!
+
+
+!Slide08.jpg|border=1!
+
+
+!Slide09.jpg|border=1!
+
+
+!Slide10.jpg|border=1!
Added: websites/staging/esme/trunk/content/architecture-patterns.html
==============================================================================
--- websites/staging/esme/trunk/content/architecture-patterns.html (added)
+++ websites/staging/esme/trunk/content/architecture-patterns.html Mon Jun 27 13:55:28 2011
@@ -0,0 +1,85 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ 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.
+-->
+
+ <link href="/css/esme.css" rel="stylesheet" type="text/css">
+ <title>Apache ESME - Architecture Patterns</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/images/esme-logo/stanbol-favicon.png"/>
+</head>
+
+<body>
+ <div id="navigation">
+ <img alt="Apache ESME" width="220" height="101" src="/images/esme-logo/esme-powerd.gif"/>
+ <h1 id="esme_links">ESME links</h1>
+<ul>
+<li><a href="/index.html">Home</a></li>
+<li><a href="/team.html">Project Team</a></li>
+<li><a href="/docs/buildfromSVN.html">Building ESME</a></li>
+<li><a href="/docs/faq.html">FAQ</a></li>
+<li><a href="/docs/actions.html">Actions</a></li>
+<li><a href="/docs/apis.html">APIs</a></li>
+<li><a href="/docs/clients.html">Clients</a></li>
+<li><a href="/docs/collaboration.html">Collaboration</a></li>
+<li><a href="/docs/install.html">Installation Guides</a></li>
+<li><a href="/docs/yql.html">YQL</a><br />
+</li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">Architecture Patterns</h1>
+ <p>Possible variants on the uses of Apache ESME in the Internet (cloud-based),
+in an extranet and in an intranet. We have also looked at different
+configurations for Apache ESMEâs database as well as its user management
+functionality (âCorporate LDAPâ).</p>
+<p>!Slide01.jpg|border=1!</p>
+<p>!Slide02.jpg|border=1!</p>
+<p>!Slide03.jpg|border=1!</p>
+<p>!Slide04.jpg|border=1!</p>
+<p>!Slide05.jpg|border=1!</p>
+<p>!Slide06.jpg|border=1!</p>
+<p>!Slide07.jpg|border=1!</p>
+<p>!Slide08.jpg|border=1!</p>
+<p>!Slide09.jpg|border=1!</p>
+<p>!Slide10.jpg|border=1!</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, ESME and the Apache feather and ESME logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Added: websites/staging/esme/trunk/content/branding.cwiki
==============================================================================
--- websites/staging/esme/trunk/content/branding.cwiki (added)
+++ websites/staging/esme/trunk/content/branding.cwiki Mon Jun 27 13:55:28 2011
@@ -0,0 +1,31 @@
+h4. New Logo
+
+h5. Alternative 1:
+
+
+!4-600.jpg|border=1!
+
+
+h5. Alternative 2:
+
+
+!LOGO ESME #2 variations 1.jpg|border=1!
+
+h5. Alternative 3:
+
+!LOGO ESME blue.jpg|border=1!
+
+
+h4. ESME Inside logo:
+
+
+!ESME LOGO inside-variations.jpg|border=1!
+
+
+h4. Powered by ESME logo:
+
+
+!powered.jpg|border=1!
+
+
+!4powered.gif|border=1!
Added: websites/staging/esme/trunk/content/branding.html
==============================================================================
--- websites/staging/esme/trunk/content/branding.html (added)
+++ websites/staging/esme/trunk/content/branding.html Mon Jun 27 13:55:28 2011
@@ -0,0 +1,89 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ 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.
+-->
+
+ <link href="/css/esme.css" rel="stylesheet" type="text/css">
+ <title>Apache ESME - Branding</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/images/esme-logo/stanbol-favicon.png"/>
+</head>
+
+<body>
+ <div id="navigation">
+ <img alt="Apache ESME" width="220" height="101" src="/images/esme-logo/esme-powerd.gif"/>
+ <h1 id="esme_links">ESME links</h1>
+<ul>
+<li><a href="/index.html">Home</a></li>
+<li><a href="/team.html">Project Team</a></li>
+<li><a href="/docs/buildfromSVN.html">Building ESME</a></li>
+<li><a href="/docs/faq.html">FAQ</a></li>
+<li><a href="/docs/actions.html">Actions</a></li>
+<li><a href="/docs/apis.html">APIs</a></li>
+<li><a href="/docs/clients.html">Clients</a></li>
+<li><a href="/docs/collaboration.html">Collaboration</a></li>
+<li><a href="/docs/install.html">Installation Guides</a></li>
+<li><a href="/docs/yql.html">YQL</a><br />
+</li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">Branding</h1>
+ <p><a name="Branding-NewLogo"></a></p>
+<h4 id="new_logo">New Logo</h4>
+<p><a name="Branding-Alternative1:"></a></p>
+<h5 id="alternative_1">Alternative 1:</h5>
+<p>!4-600.jpg|border=1!</p>
+<p><a name="Branding-Alternative2:"></a></p>
+<h5 id="alternative_2">Alternative 2:</h5>
+<p>!LOGO ESME #2 variations 1.jpg|border=1!</p>
+<p><a name="Branding-Alternative3:"></a></p>
+<h5 id="alternative_3">Alternative 3:</h5>
+<p>!LOGO ESME blue.jpg|border=1!</p>
+<p><a name="Branding-ESMEInsidelogo:"></a></p>
+<h4 id="esme_inside_logo">ESME Inside logo:</h4>
+<p>!ESME LOGO inside-variations.jpg|border=1!</p>
+<p><a name="Branding-PoweredbyESMElogo:"></a></p>
+<h4 id="powered_by_esme_logo">Powered by ESME logo:</h4>
+<p>!powered.jpg|border=1!</p>
+<p>!4powered.gif|border=1!</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, ESME and the Apache feather and ESME logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Added: websites/staging/esme/trunk/content/build-apache-esme-from-subversion.cwiki
==============================================================================
--- websites/staging/esme/trunk/content/build-apache-esme-from-subversion.cwiki (added)
+++ websites/staging/esme/trunk/content/build-apache-esme-from-subversion.cwiki Mon Jun 27 13:55:28 2011
@@ -0,0 +1,34 @@
+h3. Mac OS X 10.5/6
+
+h4. Prerequisites
+
+* MacPorts (recommended) - install instructions at [http://www.macports.org/install.php]
+* Maven - with MacPorts run command "sudo port install maven"
+* Subversion - comes with Mac OS X 10.5/6
+
+h4. Checkout latest Apache ESME, build, and run
+
+Run the following commands, starting in the directory where you want to download Apache ESME:
+
+# svn checkout [http://svn.apache.org/repos/asf/esme/] esme
+# cd esme/server/
+# mvn jetty:run
+
+The third step can take a while the first time it is run as it needs to download all of Apache ESME's dependencies (and there are quite a few of those).
+
+After this you should be able to open your web browser and navigate to [http://localhost:80/esme_server_SNAPSHOT_3.0] and see ESME running\!
+
+h4. Optionally running under a separate Tomcat installation
+
+# Install Tomcat
+#* Download latest Tomcat 6 Core .zip file from [http://tomcat.apache.org/download-60.cgi]
+# In esme/server directory run "mvn package"
+# Copy .war file in esme/server/target directory into the webapps/ directory of your Tomcat installation
+# Start Tomcat (bin/startup.sh in the main Tomcat directory)
+# Navigate your browser to [http://localhost:80/esme_server_SNAPSHOT_3.0]
+
+
+h3. Windows
+
+
+h3. Linux
\ No newline at end of file
Added: websites/staging/esme/trunk/content/build-apache-esme-from-subversion.html
==============================================================================
--- websites/staging/esme/trunk/content/build-apache-esme-from-subversion.html (added)
+++ websites/staging/esme/trunk/content/build-apache-esme-from-subversion.html Mon Jun 27 13:55:28 2011
@@ -0,0 +1,114 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ 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.
+-->
+
+ <link href="/css/esme.css" rel="stylesheet" type="text/css">
+ <title>Apache ESME - Build Apache ESME from Subversion</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/images/esme-logo/stanbol-favicon.png"/>
+</head>
+
+<body>
+ <div id="navigation">
+ <img alt="Apache ESME" width="220" height="101" src="/images/esme-logo/esme-powerd.gif"/>
+ <h1 id="esme_links">ESME links</h1>
+<ul>
+<li><a href="/index.html">Home</a></li>
+<li><a href="/team.html">Project Team</a></li>
+<li><a href="/docs/buildfromSVN.html">Building ESME</a></li>
+<li><a href="/docs/faq.html">FAQ</a></li>
+<li><a href="/docs/actions.html">Actions</a></li>
+<li><a href="/docs/apis.html">APIs</a></li>
+<li><a href="/docs/clients.html">Clients</a></li>
+<li><a href="/docs/collaboration.html">Collaboration</a></li>
+<li><a href="/docs/install.html">Installation Guides</a></li>
+<li><a href="/docs/yql.html">YQL</a><br />
+</li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">Build Apache ESME from Subversion</h1>
+ <p><a name="BuildApacheESMEfromSubversion-MacOSX10.5/6"></a></p>
+<h3 id="mac_os_x_1056">Mac OS X 10.5/6</h3>
+<p><a name="BuildApacheESMEfromSubversion-Prerequisites"></a></p>
+<h4 id="prerequisites">Prerequisites</h4>
+<ul>
+<li>MacPorts (recommended) - install instructions at <a href="http://www.macports.org/install.php">http://www.macports.org/install.php</a></li>
+<li>Maven - with MacPorts run command "sudo port install maven"</li>
+<li>Subversion - comes with Mac OS X 10.5/6</li>
+</ul>
+<p><a name="BuildApacheESMEfromSubversion-CheckoutlatestApacheESME,build,andrun"></a></p>
+<h4 id="checkout_latest_apache_esme_build_and_run">Checkout latest Apache ESME, build, and run</h4>
+<p>Run the following commands, starting in the directory where you want to
+download Apache ESME:</p>
+<ol>
+<li>svn checkout <a href="http://svn.apache.org/repos/asf/esme/">http://svn.apache.org/repos/asf/esme/</a>
+ esme</li>
+<li>cd esme/server/</li>
+<li>mvn jetty:run</li>
+</ol>
+<p>The third step can take a while the first time it is run as it needs to
+download all of Apache ESME's dependencies (and there are quite a few of
+those).</p>
+<p>After this you should be able to open your web browser and navigate to <a href="http://localhost:80/esme_server_SNAPSHOT_3.0">http://localhost:80/esme_server_SNAPSHOT_3.0</a>
+ and see ESME running!</p>
+<p><a name="BuildApacheESMEfromSubversion-OptionallyrunningunderaseparateTomcatinstallation"></a></p>
+<h4 id="optionally_running_under_a_separate_tomcat_installation">Optionally running under a separate Tomcat installation</h4>
+<ol>
+<li>Install Tomcat</li>
+<li>
+<ul>
+<li>Download latest Tomcat 6 Core .zip file from <a href="http://tomcat.apache.org/download-60.cgi">http://tomcat.apache.org/download-60.cgi</a></li>
+</ul>
+</li>
+<li>In esme/server directory run "mvn package"</li>
+<li>Copy .war file in esme/server/target directory into the webapps/
+directory of your Tomcat installation</li>
+<li>Start Tomcat (bin/startup.sh in the main Tomcat directory)</li>
+<li>Navigate your browser to <a href="http://localhost:80/esme_server_SNAPSHOT_3.0">http://localhost:80/esme_server_SNAPSHOT_3.0</a></li>
+</ol>
+<p><a name="BuildApacheESMEfromSubversion-Windows"></a></p>
+<h3 id="windows">Windows</h3>
+<p><a name="BuildApacheESMEfromSubversion-Linux"></a></p>
+<h3 id="linux">Linux</h3>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, ESME and the Apache feather and ESME logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Added: websites/staging/esme/trunk/content/ce-installation-guide.cwiki
==============================================================================
--- websites/staging/esme/trunk/content/ce-installation-guide.cwiki (added)
+++ websites/staging/esme/trunk/content/ce-installation-guide.cwiki Mon Jun 27 13:55:28 2011
@@ -0,0 +1,61 @@
+*Note: this is currently a work in progress.*
+
+This guide describes how to build ESME and deploy it to the SAP NetWeaver Composition Environment (aka "CE"), which is SAP's Java EE 5-compliant application server and integration platform.
+
+h3. 1. Build ESME from the latest code drop
+
+
+h3. 2. Convert the esme.war into a deployable element
+
+On your CE installation, there are [scripts|http://help.sap.com/saphelp_nwce71/helpdata/en/46/1bd4293d034f08e10000000a114a6b/content.htm] to do such actions
+
+
+D:\usr\sap\CE1\J00\j2ee\deployment\scripts>make_SDA esme.war \-pr esme.propertiesContents of esme.properties file
+
+{noformat}
+softwaretype=single-module
+subtype=war
+context-root=/esme
+vendor=esme.apache.org
+location=Deployment Manager
+counter=1
+{noformat}
+
+h3. 3. Deploy
+
+
+h4. 3.1. via the Netweaver Developer Studio
+
+Deploy the war file created in step 2 via the Deplyoment Perspective in NWDS.
+
+
+h4. 3.2 via telnet
+
+you can also deploy using telnet ([http://help.sap.com/saphelp_nwpi711/helpdata/en/45/0ad8e787652d6ae10000000a11466f/content.htm|http://help.sap.com/saphelp_nwpi711/helpdata/en/45/0ad8e787652d6ae10000000a11466f/content.htm]):
+
+h4. 3.3 via script
+
+D:\usr\sap\CE1\J00\j2ee\deployment\scripts> deploy administrator:abcd1234@localhost:50004 esme.war
+
+h3. Tips
+
+
+h5. Using container-based autnetication
+
+You must also change the web.xml file
+
+{noformat}
+<resource-ref>
+<res-ref-name>esme</res-ref-name>
+<res-type>javax.sql.DataSource</res-type>
+<res-auth>Container</res-auth>
+</resource-ref>
+{noformat}
+You also have to of course create a data source and the necessary JDBC drivers to the CE environment. Here are two blogs with details on how to do this:
+* [Creating JDBC Data sources using NWA for different Databases in CE|http://www.sdn.sap.com/irj/scn/weblogs?blog=/pub/wlg/12141]
+* [Connecting an Application to an External Database in SAP NW CE 7.1|http://www.sdn.sap.com/irj/scn/weblogs?blog=/pub/wlg/8675]
+
+If you are using derby as your DB to perform tests, the following info is useful:
+* DB driver class: _org.apache.derby.jdbc.EmbeddedDriver_
+* URL: _jdbc:derby:esme_db;create=true_
+* JAR_: derby-10.5.1.1.jar\_
\ No newline at end of file
Added: websites/staging/esme/trunk/content/ce-installation-guide.html
==============================================================================
--- websites/staging/esme/trunk/content/ce-installation-guide.html (added)
+++ websites/staging/esme/trunk/content/ce-installation-guide.html Mon Jun 27 13:55:28 2011
@@ -0,0 +1,128 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ 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.
+-->
+
+ <link href="/css/esme.css" rel="stylesheet" type="text/css">
+ <title>Apache ESME - CE Installation Guide</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/images/esme-logo/stanbol-favicon.png"/>
+</head>
+
+<body>
+ <div id="navigation">
+ <img alt="Apache ESME" width="220" height="101" src="/images/esme-logo/esme-powerd.gif"/>
+ <h1 id="esme_links">ESME links</h1>
+<ul>
+<li><a href="/index.html">Home</a></li>
+<li><a href="/team.html">Project Team</a></li>
+<li><a href="/docs/buildfromSVN.html">Building ESME</a></li>
+<li><a href="/docs/faq.html">FAQ</a></li>
+<li><a href="/docs/actions.html">Actions</a></li>
+<li><a href="/docs/apis.html">APIs</a></li>
+<li><a href="/docs/clients.html">Clients</a></li>
+<li><a href="/docs/collaboration.html">Collaboration</a></li>
+<li><a href="/docs/install.html">Installation Guides</a></li>
+<li><a href="/docs/yql.html">YQL</a><br />
+</li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">CE Installation Guide</h1>
+ <p><em>Note: this is currently a work in progress.</em></p>
+<p>This guide describes how to build ESME and deploy it to the SAP NetWeaver
+Composition Environment (aka "CE"), which is SAP's Java EE 5-compliant
+application server and integration platform.</p>
+<p><a name="CEInstallationGuide-1.BuildESMEfromthelatestcodedrop"></a></p>
+<h3 id="1_build_esme_from_the_latest_code_drop">1. Build ESME from the latest code drop</h3>
+<p><a name="CEInstallationGuide-2.Converttheesme.warintoadeployableelement"></a></p>
+<h3 id="2_convert_the_esmewar_into_a_deployable_element">2. Convert the esme.war into a deployable element</h3>
+<p>On your CE installation, there are <a href="http://help.sap.com/saphelp_nwce71/helpdata/en/46/1bd4293d034f08e10000000a114a6b/content.htm">scripts</a>
+ to do such actions</p>
+<p>D:usrsapCE1J00j2eedeploymentscripts>make_SDA esme.war -pr
+esme.propertiesContents of esme.properties file</p>
+<div class="codehilite"><pre><span class="n">softwaretype</span><span class="o">=</span><span class="n">single</span><span class="o">-</span><span class="n">module</span>
+<span class="n">subtype</span><span class="o">=</span><span class="n">war</span>
+<span class="n">context</span><span class="o">-</span><span class="n">root</span><span class="o">=/</span><span class="n">esme</span>
+<span class="n">vendor</span><span class="o">=</span><span class="n">esme</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">org</span>
+<span class="n">location</span><span class="o">=</span><span class="n">Deployment</span> <span class="n">Manager</span>
+<span class="n">counter</span><span class="o">=</span><span class="mi">1</span>
+</pre></div>
+
+
+<p><a name="CEInstallationGuide-3.Deploy"></a></p>
+<h3 id="3_deploy">3. Deploy</h3>
+<p><a name="CEInstallationGuide-3.1.viatheNetweaverDeveloperStudio"></a></p>
+<h4 id="31_via_the_netweaver_developer_studio">3.1. via the Netweaver Developer Studio</h4>
+<p>Deploy the war file created in step 2 via the Deplyoment Perspective in
+NWDS.</p>
+<p><a name="CEInstallationGuide-3.2viatelnet"></a></p>
+<h4 id="32_via_telnet">3.2 via telnet</h4>
+<p>you can also deploy using telnet (<a href="http://help.sap.com/saphelp_nwpi711/helpdata/en/45/0ad8e787652d6ae10000000a11466f/content.htm">http://help.sap.com/saphelp_nwpi711/helpdata/en/45/0ad8e787652d6ae10000000a11466f/content.htm</a>
+):</p>
+<p><a name="CEInstallationGuide-3.3viascript"></a></p>
+<h4 id="33_via_script">3.3 via script</h4>
+<p>D:usrsapCE1J00j2eedeploymentscripts> deploy
+administrator:abcd1234@localhost:50004 esme.war</p>
+<p><a name="CEInstallationGuide-Tips"></a></p>
+<h3 id="tips">Tips</h3>
+<p><a name="CEInstallationGuide-Usingcontainer-basedautnetication"></a></p>
+<h5 id="using_container-based_autnetication">Using container-based autnetication</h5>
+<p>You must also change the web.xml file</p>
+<div class="codehilite"><pre><span class="nt"><resource-ref></span>
+<span class="nt"><res-ref-name></span>esme<span class="nt"></res-ref-name></span>
+<span class="nt"><res-type></span>javax.sql.DataSource<span class="nt"></res-type></span>
+<span class="nt"><res-auth></span>Container<span class="nt"></res-auth></span>
+<span class="nt"></resource-ref></span>
+</pre></div>
+
+
+<p>You also have to of course create a data source and the necessary JDBC
+drivers to the CE environment. Here are two blogs with details on how to do
+this:
+<em> <a href="http://www.sdn.sap.com/irj/scn/weblogs?blog=/pub/wlg/12141">Creating JDBC Data sources using NWA for different Databases in CE</a>
+</em> <a href="http://www.sdn.sap.com/irj/scn/weblogs?blog=/pub/wlg/8675">Connecting an Application to an External Database in SAP NW CE 7.1</a></p>
+<p>If you are using derby as your DB to perform tests, the following info is
+useful:
+<em> DB driver class: <em>org.apache.derby.jdbc.EmbeddedDriver</em></em> URL: <em>jdbc:derby:esme_db;create=true</em>
+* JAR_: derby-10.5.1.1.jar_</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, ESME and the Apache feather and ESME logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Added: websites/staging/esme/trunk/content/collaboration-with-akibot.cwiki
==============================================================================
--- websites/staging/esme/trunk/content/collaboration-with-akibot.cwiki (added)
+++ websites/staging/esme/trunk/content/collaboration-with-akibot.cwiki Mon Jun 27 13:55:28 2011
@@ -0,0 +1,56 @@
+{section:border=true}
+{column:width=70%}
+h4. Background
+
+Akibot is the first semantic actionable micro-blogging platform for the enterprise. Akibot not only allows real-time group collaboration and awareness through short, instant messages (like a Twitter for the company), but it also understands those messages and, if applicable, takes action.
+
+A good description is provided by this ReadWriteWeb [blog|http://www.readwriteweb.com/archives/akibot_an_enterprise_twitter_clone_infused_with_ai.php].
+
+
+h4. Technical Description of the architecture
+
+
+Akibot works with 2 modules: the front end (the microblog) and the robot (the "brain"). Both modules are completely independent and separate, and they communicate via HTTP POST and XML. When you write a message and post it in the microblog module, it does an HTTP POST call to the robot with the message. The robot gets the message and sends back an XML acknowledging the receipt.
+
+In the background the robot queues the message for processing. Processing means the message goes through the robot's Contextual Analyzer. The Contextual Analyzer determines the entity (inventory item, vendor, client. contact, marketing campaign, etc. etc.) and the situation (how that entity is being affected in the message/conversation), and, if applicable, makes an HTTP call to inquiry information from the corresponding software (e.g. ERP \-SAP; Navision; etc-, Groupware \-Exchange, Salesforce, etc. etc).
+
+Once the robot has all this information, it decides if an action is required (usually the action is a response back to the microblog module - but can also be updates, alerts, pushing data to other applications, etc) and proceeds to do so by pushing a message back to the microblog module via HTTP POST (the actions are defined by directives, Akibot comes equipped with some standard directives but you can teach him more that are more specific to your industry).
+
+h2. Suggested architecture
+
+{gliffy:name=Collaboration with Akibot\|space=ESME\|page=Collaboration with Akibot\|pageid=5965899\|align=left\|size=M}
+
+
+h4. General Use Case
+
+Basically this is how it is working now. The only change would be that Apache ESME would be posting messages to Akibot (robot module, just like the microblog module is doing now) and Akibot would reply back to Apache ESME if needed, and would interface with enterprise software (ERP, Groupware applications).
+
+h4. Integration possibilitites: Overview
+
+
+There are three basic scenarios
+# via an Apache ESME action that posts messages to the Akibot API.
+# A bot that follows the Apache ESME message stream and either 1) makes a remote call to the RESTAPIlocated on another server or, if the bot was located on the GAE then accesses your API without making a remote call.
+# Another idea would be to directly embed akibot functionality in Apache ESME as some sort of a plug-in.
+
+
+
+{column}
+
+h5.
+
+{column:width=30%}
+
+h3. Use Cases
+
+h5. Use Messages for Back-end Requests
+
+* The idea here would be to use Apache ESME to ask the back-end for certain pieces of information.
+* [Detailed description of use case|ESME:Akibot Use Case description]
+
+h5.
+
+h3.
+
+{column}
+{section}
\ No newline at end of file
Added: websites/staging/esme/trunk/content/collaboration-with-akibot.html
==============================================================================
--- websites/staging/esme/trunk/content/collaboration-with-akibot.html (added)
+++ websites/staging/esme/trunk/content/collaboration-with-akibot.html Mon Jun 27 13:55:28 2011
@@ -0,0 +1,142 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ 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.
+-->
+
+ <link href="/css/esme.css" rel="stylesheet" type="text/css">
+ <title>Apache ESME - Collaboration with Akibot</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/images/esme-logo/stanbol-favicon.png"/>
+</head>
+
+<body>
+ <div id="navigation">
+ <img alt="Apache ESME" width="220" height="101" src="/images/esme-logo/esme-powerd.gif"/>
+ <h1 id="esme_links">ESME links</h1>
+<ul>
+<li><a href="/index.html">Home</a></li>
+<li><a href="/team.html">Project Team</a></li>
+<li><a href="/docs/buildfromSVN.html">Building ESME</a></li>
+<li><a href="/docs/faq.html">FAQ</a></li>
+<li><a href="/docs/actions.html">Actions</a></li>
+<li><a href="/docs/apis.html">APIs</a></li>
+<li><a href="/docs/clients.html">Clients</a></li>
+<li><a href="/docs/collaboration.html">Collaboration</a></li>
+<li><a href="/docs/install.html">Installation Guides</a></li>
+<li><a href="/docs/yql.html">YQL</a><br />
+</li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">Collaboration with Akibot</h1>
+ <p>{section:border=true}
+{column:width=70%}
+<a name="CollaborationwithAkibot-Background"></a></p>
+<h4 id="background">Background</h4>
+<p>Akibot is the first semantic actionable micro-blogging platform for the
+enterprise. Akibot not only allows real-time group collaboration and
+awareness through short, instant messages (like a Twitter for the company),
+but it also understands those messages and, if applicable, takes action.</p>
+<p>A good description is provided by this ReadWriteWeb <a href="http://www.readwriteweb.com/archives/akibot_an_enterprise_twitter_clone_infused_with_ai.php">blog</a>
+.</p>
+<p><a name="CollaborationwithAkibot-TechnicalDescriptionofthearchitecture"></a></p>
+<h4 id="technical_description_of_the_architecture">Technical Description of the architecture</h4>
+<p>Akibot works with 2 modules: the front end (the microblog) and the robot
+(the "brain"). Both modules are completely independent and separate,
+and they communicate via HTTP POST and XML. When you write a message and
+post it in the microblog module, it does an HTTP POST call to the robot
+with the message. The robot gets the message and sends back an XML
+acknowledging the receipt. </p>
+<p>In the background the robot queues the message for processing. Processing
+means the message goes through the robot's Contextual Analyzer. The
+Contextual Analyzer determines the entity (inventory item, vendor, client.
+contact, marketing campaign, etc. etc.) and the situation (how that entity
+is being affected in the message/conversation), and, if applicable, makes
+an HTTP call to inquiry information from the corresponding software (e.g.
+ERP -SAP; Navision; etc-, Groupware -Exchange, Salesforce, etc. etc).</p>
+<p>Once the robot has all this information, it decides if an action is
+required (usually the action is a response back to the microblog module -
+but can also be updates, alerts, pushing data to other applications, etc)
+and proceeds to do so by pushing a message back to the microblog module via
+HTTP POST (the actions are defined by directives, Akibot comes equipped
+with some standard directives but you can teach him more that are more
+specific to your industry). </p>
+<p><a name="CollaborationwithAkibot-Suggestedarchitecture"></a></p>
+<h2 id="suggested_architecture">Suggested architecture</h2>
+<p>{gliffy:name=Collaboration with Akibot|space=ESME|page=Collaboration with
+Akibot|pageid=5965899|align=left|size=M}</p>
+<p><a name="CollaborationwithAkibot-GeneralUseCase"></a></p>
+<h4 id="general_use_case">General Use Case</h4>
+<p>Basically this is how it is working now. The only change would be that
+Apache ESME would be posting messages to Akibot (robot module, just like
+the microblog module is doing now) and Akibot would reply back to Apache
+ESME if needed, and would interface with enterprise software (ERP,
+Groupware applications).</p>
+<p><a name="CollaborationwithAkibot-Integrationpossibilitites:Overview"></a></p>
+<h4 id="integration_possibilitites_overview">Integration possibilitites: Overview</h4>
+<p>There are three basic scenarios
+1. via an Apache ESME action that posts messages to the Akibot API.
+1. A bot that follows the Apache ESME message stream and either 1) makes a
+remote call to the RESTAPIlocated on another server or, if the bot was
+located on the GAE then accesses your API without making a remote call.
+1. Another idea would be to directly embed akibot functionality in Apache
+ESME as some sort of a plug-in.</p>
+<p>{column}</p>
+<p><a name="CollaborationwithAkibot-"></a></p>
+<h5 id="" />
+<p>{column:width=30%}</p>
+<p><a name="CollaborationwithAkibot-UseCases"></a></p>
+<h3 id="use_cases">Use Cases</h3>
+<p><a name="CollaborationwithAkibot-UseMessagesforBack-endRequests"></a></p>
+<h5 id="use_messages_for_back-end_requests">Use Messages for Back-end Requests</h5>
+<ul>
+<li>The idea here would be to use Apache ESME to ask the back-end for certain
+pieces of information.</li>
+<li><a href="esme:akibot-use-case-description.html">Detailed description of use case</a></li>
+</ul>
+<p><a name="CollaborationwithAkibot-"></a></p>
+<h5 id="_1" />
+<p><a name="CollaborationwithAkibot-"></a></p>
+<h3 id="_2" />
+<p>{column}
+{section}</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, ESME and the Apache feather and ESME logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Added: websites/staging/esme/trunk/content/collaboration-with-ofbiz.cwiki
==============================================================================
--- websites/staging/esme/trunk/content/collaboration-with-ofbiz.cwiki (added)
+++ websites/staging/esme/trunk/content/collaboration-with-ofbiz.cwiki Mon Jun 27 13:55:28 2011
@@ -0,0 +1,67 @@
+{section:border=true}
+{column:width=70%}
+
+h2. Background
+
+The [Apache Open For Business Project|http://ofbiz.apache.org/] is an open source enterprise automation software project licensed under the Apache License Version 2.0. By open source enterprise automation we mean: Open Source ERP, Open Source CRM, Open Source E-Business / E-Commerce, Open Source SCM, Open Source MRP, Open Source CMMS/EAM, and so on.
+
+h2. Suggested architecture
+
+h4. Integration possibilitites: Initial thoughts
+
+There are two basic scenarios
+
+# via an ESME action that posts messages to a OfBiz API. The easiest way may be to have ESME just send an email to the OFBiz environment.
+# A bot that follows the ESME message stream and either 1) makes a remote call to the OfBiz API
+
+The fundamental idea is to use [OFBiz Event Condition Action (ECAs)|http://ofbiz.apache.org/docs/services.html#ECAs] as the basis for the integration.
+
+h5. About ECAs:
+
+ECAs are pretty straight forward: when an Event occurs, if the Condition(s) are met then Action(s) are performed. The Events supported currently are Entity (EECA) events which basically correspond to database record CRUD events, Service (SECA) events which correspond the various stages of a given service's invocation (invoke, validate, commit, return, etc.) and Mail (MECA) events which occur when an email is received.
+Conditions are defined against whatever context is will be available when the event occurs, the record fields for an EECA, the in/out parameters for a SECA and the email contents for a MECA (from, to, subject, etc.)
+
+Actions are just OFBiz services to be invoked when the conditions are met.
+
+h5. Sending event notifications
+
+
+ECAs are the way to go for this and we'd just define services to be used as actions which send the message to ESME. You'd probably create a single generic service that is used to send any message and then use that service within other services for sending specific messages e.g. an ECA would invoke sendPurchaseOrderChangeNotification which would prepare the message contents and call sendEsmeMessage to actually send the message.
+
+
+h5. Receiving messages
+
+For this we could either create a new type of ECA specifically for ESME messages or perhaps even generalize MECAs to support any type of message so that it stands for Message rather then Mail. ECAs would then be defined and evaluated when an ESME message is received and service actions invoked to handle any processing and responses that need to occur.
+
+The receipt of the message in OFBiz can occur via various means. If OFBiz has a RESTAPI for ECAs, then you can create an [ESME action|http://cwiki.apache.org/confluence/display/ESME/Actions] to send messages to OFBiz when certain ESME events occur. Or if there some sort of ECA for dealing with email events, then we can also use an action that sends email. If you want a deeper integration, you could have a bot that uses one of our various [APIs|http://cwiki.apache.org/confluence/display/ESME/API] to read the message queue and then create OFBiz events.
+
+
+ECAs are only triggered by internal events, as I described above: an OFBiz service invocation, database operation or email receipt. We don't have a REST API for invoking services, there is basic support via SOAP, JMS or HTTPS (but not what you'd call REST). Services can also be invoked using HTTP(S) POSTs via our standard request handler (typically used for serving regular web pages and ajax calls) but that requires a little additional legwork in that you have to define request-event-response mappings in our XML based web app controllers.
+
+
+
+
+
+
+
+{column}
+
+h5.
+
+{column:width=30%}
+
+h3. Use Cases
+
+h5. Send users status information from OfBiz
+
+* The idea here would be to use Apache ESME to send users status messages based on events in OfBiz (ala SalesForce "Chatter")
+* [Initial description for simple use case.|ESME:Simple Use Case - OFBiz sends message to ESME]
+
+h5. Use Apache ESME to provide Chat\+ functionality
+
+
+* The idea here would be to use Apache ESME to provide chat functionality to OfBiz
+* [Initial description of the use case|ESME as Chat in OfBiz]
+
+{column}
+{section}
\ No newline at end of file
Added: websites/staging/esme/trunk/content/collaboration-with-ofbiz.html
==============================================================================
--- websites/staging/esme/trunk/content/collaboration-with-ofbiz.html (added)
+++ websites/staging/esme/trunk/content/collaboration-with-ofbiz.html Mon Jun 27 13:55:28 2011
@@ -0,0 +1,158 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ 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.
+-->
+
+ <link href="/css/esme.css" rel="stylesheet" type="text/css">
+ <title>Apache ESME - Collaboration with OFbiz</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/images/esme-logo/stanbol-favicon.png"/>
+</head>
+
+<body>
+ <div id="navigation">
+ <img alt="Apache ESME" width="220" height="101" src="/images/esme-logo/esme-powerd.gif"/>
+ <h1 id="esme_links">ESME links</h1>
+<ul>
+<li><a href="/index.html">Home</a></li>
+<li><a href="/team.html">Project Team</a></li>
+<li><a href="/docs/buildfromSVN.html">Building ESME</a></li>
+<li><a href="/docs/faq.html">FAQ</a></li>
+<li><a href="/docs/actions.html">Actions</a></li>
+<li><a href="/docs/apis.html">APIs</a></li>
+<li><a href="/docs/clients.html">Clients</a></li>
+<li><a href="/docs/collaboration.html">Collaboration</a></li>
+<li><a href="/docs/install.html">Installation Guides</a></li>
+<li><a href="/docs/yql.html">YQL</a><br />
+</li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">Collaboration with OFbiz</h1>
+ <p>{section:border=true}
+{column:width=70%}</p>
+<p><a name="CollaborationwithOFbiz-Background"></a></p>
+<h2 id="background">Background</h2>
+<p>The <a href="http://ofbiz.apache.org/">Apache Open For Business Project</a>
+ is an open source enterprise automation software project licensed under
+the Apache License Version 2.0. By open source enterprise automation we
+mean: Open Source ERP, Open Source CRM, Open Source E-Business /
+E-Commerce, Open Source SCM, Open Source MRP, Open Source CMMS/EAM, and so
+on.</p>
+<p><a name="CollaborationwithOFbiz-Suggestedarchitecture"></a></p>
+<h2 id="suggested_architecture">Suggested architecture</h2>
+<p><a name="CollaborationwithOFbiz-Integrationpossibilitites:Initialthoughts"></a></p>
+<h4 id="integration_possibilitites_initial_thoughts">Integration possibilitites: Initial thoughts</h4>
+<p>There are two basic scenarios </p>
+<ol>
+<li> via an ESME action that posts messages to a OfBiz API. The easiest
+way may be to have ESME just send an email to the OFBiz environment.</li>
+<li>A bot that follows the ESME message stream and either 1) makes a remote
+call to the OfBiz API</li>
+</ol>
+<p>The fundamental idea is to use <a href="http://ofbiz.apache.org/docs/services.html#ECAs">OFBiz Event Condition Action (ECAs)</a>
+ as the basis for the integration.</p>
+<p><a name="CollaborationwithOFbiz-AboutECAs:"></a></p>
+<h5 id="about_ecas">About ECAs:</h5>
+<p>ECAs are pretty straight forward: when an Event occurs, if the Condition(s)
+are met then Action(s) are performed. The Events supported currently
+are Entity (EECA) events which basically correspond to database record CRUD
+events, Service (SECA) events which correspond the various stages of a
+given service's invocation (invoke, validate, commit, return, etc.) and
+Mail (MECA) events which occur when an email is received.
+Conditions are defined against whatever context is will be available when
+the event occurs, the record fields for an EECA, the in/out parameters for
+a SECA and the email contents for a MECA (from, to, subject, etc.)</p>
+<p>Actions are just OFBiz services to be invoked when the conditions are met.</p>
+<p><a name="CollaborationwithOFbiz-Sendingeventnotifications"></a></p>
+<h5 id="sending_event_notifications">Sending event notifications</h5>
+<p>ECAs are the way to go for this and we'd just define services to be used as
+actions which send the message to ESME. You'd probably create a
+single generic service that is used to send any message and then use that
+service within other services for sending specific messages e.g. an ECA
+would invoke sendPurchaseOrderChangeNotification which would prepare the
+message contents and call sendEsmeMessage to actually send the message.</p>
+<p><a name="CollaborationwithOFbiz-Receivingmessages"></a></p>
+<h5 id="receiving_messages">Receiving messages</h5>
+<p>For this we could either create a new type of ECA specifically for ESME
+messages or perhaps even generalize MECAs to support any type of message so
+that it stands for Message rather then Mail. ECAs would then be
+defined and evaluated when an ESME message is received and service actions
+invoked to handle any processing and responses that need to occur.</p>
+<p>The receipt of the message in OFBiz can occur via various means. If
+OFBiz has a RESTAPI for ECAs, then you can create an <a href="http://cwiki.apache.org/confluence/display/ESME/Actions">ESME action</a>
+ to send messages to OFBiz when certain ESME events occur. Or if
+there some sort of ECA for dealing with email events, then we can also use
+an action that sends email. If you want a deeper integration, you could
+have a bot that uses one of our various [APIs|http://cwiki.apache.org/confluence/display/ESME/API]
+ to read the message queue and then create OFBiz events.</p>
+<p>ECAs are only triggered by internal events, as I described above: an OFBiz
+service invocation, database operation or email receipt. We don't
+have a REST API for invoking services, there is basic support via SOAP, JMS
+or HTTPS (but not what you'd call REST). Services can also be invoked
+using HTTP(S) POSTs via our standard request handler (typically used for
+serving regular web pages and ajax calls) but that requires a little
+additional legwork in that you have to define request-event-response
+mappings in our XML based web app controllers.</p>
+<p>{column}</p>
+<p><a name="CollaborationwithOFbiz-"></a></p>
+<h5 id="" />
+<p>{column:width=30%}</p>
+<p><a name="CollaborationwithOFbiz-UseCases"></a></p>
+<h3 id="use_cases">Use Cases</h3>
+<p><a name="CollaborationwithOFbiz-SendusersstatusinformationfromOfBiz"></a></p>
+<h5 id="send_users_status_information_from_ofbiz">Send users status information from OfBiz</h5>
+<ul>
+<li>The idea here would be to use Apache ESME to send users status messages
+based on events in OfBiz (ala SalesForce "Chatter")</li>
+<li><a href="esme:simple-use-case---ofbiz-sends-message-to-esme.html">Initial description for simple use case.</a></li>
+</ul>
+<p><a name="CollaborationwithOFbiz-UseApacheESMEtoprovideChatklzzwxh:0029functionality"></a></p>
+<h5 id="use_apache_esme_to_provide_chat_functionality">Use Apache ESME to provide Chat+ functionality</h5>
+<ul>
+<li>The idea here would be to use Apache ESME to provide chat functionality
+to OfBiz</li>
+<li><a href="esme-as-chat-in-ofbiz.html">Initial description of the use case</a></li>
+</ul>
+<p>{column}
+{section}</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, ESME and the Apache feather and ESME logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>