rework SPEC and README to reflect new terminology

README.textile

@@ -25,21 +25,21 @@ To see a more sophisticated Ring app, run:
 
   java -Djava.ext.dirs=deps clojure.main src/ring/examples/wrapping.clj
 
- * If you request @http://localhost:8080/@ in your browser the @ring.dump@ endpoint will respond with an HTML page representing the Ring request that it received (see the @SPEC@ for details on the Ring request).
+ * If you request @http://localhost:8080/@ in your browser the @ring.dump@ handler will respond with an HTML page representing the request map that it received (see the @SPEC@ for details on the request map).
  * If you request @http://localhost:8080/clojure.png@, the @ring.file@ middleware will detect that there is a @clojure.png@ file in the app's @public@ directory and return that image as a response.
  * If you request @http://localhost:8080/error@, the app will produce an error that will be caught by the @ring.show-exceptions@ middleware, which will in turn return a readable backtrace as the HTML response.
 
 h2. All Available Libs
 
- * @ring.jetty@: Handler for the Jetty webserver.
- * @ring.httpcore@: Handler for the Apache HttpCore webserver. 
+ * @ring.jetty@: Adapter for the Jetty webserver.
+ * @ring.httpcore@: Adapter for the Apache HttpCore webserver. 
  * @ring.file@: Middleware that serves static files out of a public directory.
  * @ring.file-info@: Middleware that augments response headers with info about File responses.
  * @ring.static@: Middleware that serves static files with specified prefixes out of a public directory.
- * @ring.dump@: Endpoint that dumps the Ring requests as HTML responses for debugging.
+ * @ring.dump@: Handler that dumps request maps as HTML responses for debugging.
  * @ring.show-exceptions@: Middleware that catches exceptions and displays readable backtraces for debugging.
  * @ring.reload@: Middleware to automatically reload selected libs before each requests, minimizing server restarts.
- * @ring.builder@: Helpers for combining Ring endpoints and middleware into Ring apps.
+ * @ring.builder@: Helpers for composing Ring apps from multiple handlers and middleware.
  * @ring.lint@: Linter for the Ring interface, ensures compliance with the Ring spec.
  * @ring.examples.*@: Various example Ring apps.
 
@@ -66,11 +66,11 @@ This project borrows heavily from Ruby's Rack and Python's WSGI, and I thank the
 ---
 
 <pre><code>
-     +--->HTTP Request--->[Handler]--->Req1---->[Middleware]--->Req2----+
+     +--->HTTP Request--->[Adapter]--->Req1---->[Middleware]--->Req2----+
      |                                                                  |
- [Client]                                                          [Endpoint]
+ [Client]                                                           [Handler]
      |                                                                  |
-     +----HTTP Response<--[Handler]<---Resp2<---[Middleware]<---Resp1<--+
+     +----HTTP Response<--[Adapter]<---Resp2<---[Middleware]<---Resp1<--+
 </code></pre>
 
 Copyright (c) 2009 Mark McGranaghan and released under an MIT license.

SPEC

@@ -1,37 +1,38 @@
 === Ring Spec (Draft Version)
-Ring is defined in terms of Components, Handlers, Requests, and Responses,
-each of which are described below.
+Ring is defined in terms of Handlers, Middleware, Adapters, Requests Maps, and 
+Response Maps, each of which are described below.
 
 
-== Components
-Ring components constitute the logic of the web application and are abstracted 
-form the details of the HTTP protocol.  They are implemented as Clojure 
-functions that process a given request to generate and return a response.
+== Handlers
+Ring handlers constitute the core logic of the web application and are 
+abstracted from the details of the HTTP protocol.  Handlers are implemented as 
+Clojure functions that process a given request map to generate and return a 
+response map.
 
-A component is either an 'endpoint' or 'middleware'. An endpoint component is
-used at the leaf of a component tree, i.e. it does not call any other components 
-to generate it's response. A 'middleware' component in contrast may invoke
-other components to generate its response. We can combine 1 or more endpoints
-with 0 or more middleware components to build a complete Ring 'app'. Such an
-app can then be run by a Ring handler.
 
-== Handlers
-A Ring handler is a server implementation than can 'run' apps. Handlers are 
-responsible for implementing the HTTP protocol and abstracting the apps that 
-they run from the details of the protocol.
+== Middleware
+Ring middleware augments the functionality of handlers by invoking them in the 
+process of generating responses. Typically middleware will be implemented as a higher-order function that takes one or more handlers and configuration options
+as arguments and returns a new handler with the desired compound behavior.
+
+
+== Adapters
+Handlers are run via Ring adapters, which are in turn responsible for 
+implementing the HTTP protocol and abstracting the handlers that they run from 
+the details of the protocol.
 
-Handlers are implemented as functions of two arguments, an options map and a 
-Ring app. The options map provides any needed configuration to the handler, such 
+Adapters are implemented as functions of two arguments: an options map and a 
+handler. The options map provides any needed configuration to the adapter, such 
 as the port on which to run.
 
-Once initialized, handlers receive HTTP requests, parse them to construct an 
-Ring request, and then invoke their Ring app with this request as an
-argument. Once the app returns a Ring response, the handler uses it to construct 
-and send an HTTP response to the client.
+Once initialized, adapters receive HTTP requests, parse them to construct an 
+request map, and then invoke their handler with this request map as an
+argument. Once the handler returns a response map, the adapter uses it to 
+construct and send an HTTP response to the client.
 
 
-== Ring Requests
-A Ring request is a Clojure map containing at least the following keys and 
+== Request Map
+A request map is a Clojure map containing at least the following keys and 
 corresponding values:
 
 :server-port
@@ -84,13 +85,13 @@ corresponding values:
   (Optional, InputStream)
   An InputStream for the request body, if present.
 
-If a component invokes another component with an environment containing 
+If a component invokes another component with a request map containing 
 additional keys, these keys must be namespaced using the Clojure 
 :name.space/key-name convention. The ring.* namespaces are reserved.
 
 
-== Ring Responses
-A Ring response is a Clojure map containing at least the following keys and corresponding values:
+== Response Map
+A response map is a Clojure map containing at least the following keys and corresponding values:
 
 :status
   (Required, Integer)
@@ -118,5 +119,5 @@ A Ring response is a Clojure map containing at least the following keys and corr
     Contents are consumed from the stream and sent to the client. When the
     stream is exhausted, it is .close'd.
 
-As with environments, keys other than those listed above should be appropriately
-namespaced.
+As with request maps, keys in response maps other than those listed above should 
+be appropriately namespaced.