GRS2Broker

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 :

http://SERVLET_HOSTNAME:SERVLET_PORT/SERVLET_URL?locator=LOCATOR&schema=SCHEMA&[max=MAX] 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. http://localhost:35453?key=431b4202-e8d5-4ebe-97e5-84c3401b44d3
• 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 and 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 runs 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 returned in XML format that 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 key features of the gRS2 Broker servlet are the following:

• 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 for using the gRS2 Broker instead a classic gRS2 Reader is that all the required work is done on 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 the need to deploy the gRS2 Service libraries.

Examples

Example of random string results:

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

1st Response:

<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>

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

2nd Response:

<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>