View source for GRS2Broker

<!-- CATEGORIES -->
[[Category:Developer's Guide]]
<!-- END CATEGORIES -->
== Introduction ==
The goal of the gRS2 Broker Servlet is to expose result set as an HTTP endpoint. The gRS2 Broker Servlet acts as gRS2 Reader on a result set that has been created and its key (URI) is known and provided to the gRS2 Broker Servlet. Note that once the the result set is consumed it is not longer available for further reading since the gRS2 Broker reads the results incrementally.

== Functionality ==

gRS2 Broker is actually a servlet that runs on an application server. The servlet listens for GET requests of the following format :

'''''<nowiki>http://SERVLET_HOSTNAME:SERVLET_PORT/SERVLET_URL?locator=LOCATOR&schema=SCHEMA&[max=MAX]</nowiki>''''' where:
*''SERVLET_HOSTNAME'' is the hostname of the server that the servlet is deployed e.g. localhost
*''SERVLET_PORT is'' the port that the server listens e.g. 8080
*''SERVLET_URL'' is the url path of the servlet e.g. gRS2WebBroker/Broker
*''LOCATOR'' is the result set locator e.g. <nowiki>http://localhost:35453?key=431b4202-e8d5-4ebe-97e5-84c3401b44d3</nowiki>
*''SCHEMA'' is the schema of the result set locator. Could be HTTP or TCP
*''MAX'' is an optional parameter that indicates the maximum number of records that will be returned. If emitted all records will be returned


gRS2 Broker is designed and implemented to work in a gradually manner. This means that each call may consume some of the records, so in order to consume all the records some state
needs to be kept on the servlet side for each request.
When a request is retrieved from the servlet it is examined if the locator has been opened. If not a KeepAliveReader is opened and kept in memory for a predefined time period (lease time), otherwise the KeepAliveReader is retrieved from the memory and continues the reader and the lease time is renewed. In order to close the opened readers that their lease time has expired, a custom garbage collector run periodically. 

The same approach is used for storing the files locally, since files need to be stored locally for a period until the reader may request them.

The records are return in XML format so can be read by any client that can parse XML files and the whole response is compressed with gzip in order to reduce the size of the bytes transmitted and optimize the total performance.

== Features ==

The are the key features of the gRS2 Broker servlet:
* Results are exposed as an HTTP endpoint
* Results are in XML format
* Server response is compressed in order to achieve performance benefits
* The records are retrieved iteratively - gradually
* Number of results can be customized (max parameter)
* Files are stored locally on the server (garbage collection)

== Benefits ==

The benefits from using the gRS2 Broker instead a classic gRS2 Reader is that all the complexity that is required in order to work is completely done on the Servlet side, so the client doesn't bother managing the Reader. 
Furthermore, since the communication between the client and the servlet is done completely over the HTTP and the retrieved records are in XML format, any client that supports HTTP can act as a gRS2 reader without needing to deploy the gRS2 Service libraries.

== Examples ==

Example of random string results:

1st Request: ''<nowiki>http://localhost:8080/gRS2Broker_java/Broker?max=2&locator=http://localhost:57058?key=e99fe856-76c2-4375-bdfc-d58f7e2b727d&schema=HTTP</nowiki>''

1st Response:
<source lang="XML">
<Records>
	<Record id=“0”>
		<Fields>
			<Field>
				<Name>myField</Name>
				<Value>Hello world 0</Value>
			</Field>
		</Fields>
	<Record>
	<Record id=“1”>
		<Fields>
			<Field>
				<Name>myField</Name>
				<Value>Hello world 1</Value>
			</Field>
		</Fields>
	<Record>
</Records>
</source>


2nd Request : ''<nowiki>http://localhost:8080/gRS2Broker_java/Broker?max=2&locator=http://localhost:57058?key=e99fe856-76c2-4375-bdfc-d58f7e2b727d&schema=HTTP</nowiki>''

2nd Response:
<source lang="XML">
<Records>
	<Record id=“2”>
		<Fields>
			<Field>
				<Name>myField</Name>
				<Value>Hello world 2</Value>
			</Field>
		</Fields>
	<Record>
	<Record id=“3”>
		<Fields>
			<Field>
				<Name>myField</Name>
				<Value>Hello world 3</Value>
			</Field>
		</Fields>
	<Record>
</Records>
</source>