pageRef fun + docs

README.md

@@ -31,11 +31,28 @@ Once started, there won't be an actual proxy running until you create a new prox
     [~]$ curl -X POST http://localhost:9090/proxy
     {"port":9091}
 
-Once that is done, a new proxy will be available on the port returned. All you have to do is point a browser to that proxy on that port. The following additional APIs will then be available:
+Once that is done, a new proxy will be available on the port returned. All you have to do is point a browser to that proxy on that port and you should be able to browser the internet. The following additional APIs will then be available:
 
+ - PUT /proxy/[port]/har - creates a new HAR attached to the proxy and returns the HAR content if there was a previous HAR. Supports the following parameters:
+  - initialPageRef - the string name of the first page ref that should be used in the HAR. Defaults to "Page 1".
+ - PUT /proxy/[port]/har/pageRef - starts a new page on the existing HAR. Supports the following parameters:
+  - pageRef - the string name of the first page ref that should be used in the HAR. Defaults to "Page N" where N is the next page number.
+ - PUT /proxy/[port]/har/pageRef - creates a new HAR attached to the proxy and returns the HAR content if there was a previous HAR
  - DELETE /proxy/port - shuts down the proxy and closed the port
  - GET /proxy/port/har - returns the JSON/HAR content representing all the HTTP traffic passed through the proxy
 
+For example, once you've started the proxy you can create a new HAR to start recording data like so:
+
+    [~]$ curl -X PUT -d 'initialPageRef=Foo' http://localhost:8080/proxy/9091/har
+
+Now when traffic goes through port 9091 it will be attached to a page reference named "Foo". Consult the HAR specification for more info on what a "pageRef" is. You can also start a new pageRef like so:
+
+    [~]$ curl -X PUT -d 'pageRef=Bar' http://localhost:8080/proxy/9091/har/pageRef
+
+That will ensure no more HTTP requests get attached to the old pageRef (Foo) and start getting attached to the new pageRef (Bar). You can also get the HAR content at any time like so:
+
+    [~]$ curl http://localhost:8080/proxy/9091/har
+
 *TODO*: Other REST APIs supporting all the BrowserMob Proxy features will be added soon.
 
 Embedded Mode

src/main/java/org/browsermob/proxy/bricks/ProxyResource.java

@@ -5,10 +5,12 @@
 import com.google.sitebricks.At;
 import com.google.sitebricks.client.transport.Json;
 import com.google.sitebricks.headless.Reply;
+import com.google.sitebricks.headless.Request;
 import com.google.sitebricks.headless.Service;
 import com.google.sitebricks.http.Delete;
 import com.google.sitebricks.http.Get;
 import com.google.sitebricks.http.Post;
+import com.google.sitebricks.http.Put;
 import org.browsermob.core.har.Har;
 import org.browsermob.proxy.ProxyManager;
 import org.browsermob.proxy.ProxyServer;
@@ -37,7 +39,31 @@ public Reply<Har> getHar(@Named("port") int port) {
         ProxyServer proxy = proxyManager.get(port);
         Har har = proxy.getHar();
 
-        return Reply.with(proxy.getHar()).as(Json.class);
+        return Reply.with(har).as(Json.class);
+    }
+
+    @Put
+    @At("/:port/har")
+    public Reply<?> newHar(@Named("port") int port, Request request) {
+        String initialPageRef = request.param("initialPageRef");
+        ProxyServer proxy = proxyManager.get(port);
+        Har oldHar = proxy.newHar(initialPageRef);
+
+        if (oldHar != null) {
+            return Reply.with(oldHar).as(Json.class);
+        } else {
+            return Reply.saying().noContent();
+        }
+    }
+
+    @Put
+    @At("/:port/har/pageRef")
+    public Reply<?> setPage(@Named("port") int port, Request request) {
+        String pageRef = request.param("pageRef");
+        ProxyServer proxy = proxyManager.get(port);
+        proxy.newPage(pageRef);
+
+        return Reply.saying().ok();
     }
 
     @Delete