Merge pull request #18 from burnalting/issue17

Document parse-uri xslt function and extractFromUri dashboard expressions

Author: stroomdev66

user-guide/dashboards/queries.md

@@ -87,4 +87,33 @@ Or all data for the previous year:
 
 Or this year so far:
 
-`greater than year()`
+`greater than year()`
+
+## URI Fields
+Fields containing a Uniform Resource Identifier (URI) in string form can queried to extract the URI's individual components of `authority`, `fragment`, `host`, `path`, `port`, `query`, `scheme`, `schemeSpecificPart` and `userInfo`. See either [RFC 2306: Uniform Resource Identifiers (URI): Generic Syntax](http://www.ietf.org/rfc/rfc2396.txt) or Java's java.net.URI Class for details regarding the components. If any component is not present within the passed URI, then an empty string is returned.
+
+The extraction functions are
+
+* extractAuthorityFromUri\(\) - extract the Authority component
+* extractFragmentFromUri\(\) - extract the Fragment component
+* extractHostFromUri\(\) - extract the Host component
+* extractPathFromUri\(\) - extract the Path component
+* extractPortFromUri\(\) - extract the Port component
+* extractQueryFromUri\(\) - extract the Query component
+* extractSchemeFromUri\(\) - extract the Scheme component
+* extractSchemeSpecificPartFromUri\(\) - extract the Scheme specific part component
+* extractUserInfoFromUri\(\) - extract the UserInfo component
+
+If the URI is `http://foo:[email protected]:8080/very/long/path.html?p1=v1&p2=v2#more-details` the table below displays the extracted components
+
+Expression | Extraction
+--- | ---
+extractAuthorityFromUri(${URI})	| foo:bar@w1.superman.com:8080
+extractFragmentFromUri(${URI}) | more-details
+extractHostFromUri(${URI}) | w1.superman.com
+extractPathFromUri(${URI}) | /very/long/path.html
+extractPortFromUri(${URI}) | 8080
+extractQueryFromUri(${URI}) | p1=v1&p2=v2
+extractSchemeFromUri(${URI}) | http
+extractSchemeSpecificPartFromUri(${URI}) | //foo:bar@w1.superman.com:8080/very/long/path.html?p1=v1&p2=v2
+extractUserInfoFromUri(${URI}) | foo:bar

user-guide/pipelines/xslt/xslt-functions.md

@@ -40,6 +40,7 @@ The following functions are available to aid your translation:
 * `lookup(String map, String key, String time, Boolean ignoreWarnings)` - Look up a reference data map using a specified time, e.g. the event time, and ignore any warnings generated by a failed lookup
 * `meta(String key)` - Lookup a meta data value for the current stream using the specified key. The key can be `Feed`, `StreamType`, `CreatedTime`, `EffectiveTime`, `Pipeline` or any other attribute supplied when the stream was sent to Stroom, e.g. meta('System').
 * `numeric-ip(String ipAddress)` - Convert an IP address to a numeric representation for range comparison
+* `parse-uri(String URI)` - Returns an XML structure of the URI providing `authority`, `fragment`, `host`, `path`, `port`, `query`, `scheme`, `schemeSpecificPart`, and `userInfo` components if present.
 * `random()` - Get a system generated random number between 0 and 1.
 * `search-id()` - Get the id of the batch search when a pipeline is processing as part of a batch search
 * `stream-id()` - Get the id of the current input stream that is being processed
@@ -159,3 +160,39 @@ An example of how to count records is shown below:
       <xsl:attribute name="Value" select="$count" />
     </data>
 ```
+
+## `parse-uri()`
+The parse-uri() function takes a Uniform Resource Identifier (URI) in string form and returns an XML node with a namespace of `uri` containing the URI's individual components of `authority`, `fragment`, `host`, `path`, `port`, `query`, `scheme`, `schemeSpecificPart` and `userInfo`. See either [RFC 2306: Uniform Resource Identifiers (URI): Generic Syntax](http://www.ietf.org/rfc/rfc2396.txt) or Java's java.net.URI Class for details regarding the components.
+
+The following xml
+
+```xml
+    <!-- Display and parse the URI contained within the text of the rURI element -->
+    <xsl:variable name="u" select="s:parseUri(rURI)" />
+
+    <URI>
+      <xsl:value-of select="rURI" />
+    </URI>
+    <URIDetail>
+      <xsl:copy-of select="$v"/>
+    </URIDetail>
+```
+given the rURI text contains
+```
+   http://foo:[email protected]:8080/very/long/path.html?p1=v1&amp;p2=v2#more-details
+```
+would provide
+```xml
+    <URL>http://foo:[email protected]:8080/very/long/path.html?p1=v1&amp;p2=v2#more-details</URL>
+    <URIDetail>
+      <authority xmlns="uri">foo:[email protected]:8080</authority>
+      <fragment xmlns="uri">more-details</fragment>
+      <host xmlns="uri">w1.superman.com</host>
+      <path xmlns="uri">/very/long/path.html</path>
+      <port xmlns="uri">8080</port>
+      <query xmlns="uri">p1=v1&amp;p2=v2</query>
+      <scheme xmlns="uri">http</scheme>
+      <schemeSpecificPart xmlns="uri">//foo:[email protected]:8080/very/long/path.html?p1=v1&amp;p2=v2</schemeSpecificPart>
+      <userInfo xmlns="uri">foo:bar</userInfo>
+    </URIDetail>
+```