SDK by dandanhuanghuang


									EBSCO Industries

July 2009
Target Audience
This SDK is intended for use by software developers working on .Net solutions that use the SUSHI and
COUNTER standards to store and retrieve usage data.

Extremely Brief COUNTER and SUSHI Overview
Both COUNTER and SUSHI are standards with details and intricacies that are beyond the scope of this
document, but the following limited definitions will suffice for our purposes .

COUNTER (Counting Online Usage of Networked Electronic Resources ) is a standard for how usage is
recorded and reported. Basically, it defines what constitutes a “use” , and provides a standard XML schema for
transporting this information.

SUSHI (Standardized Usage Statistics Harvesting Initiative ) is the protocol for sending and receiving
COUNTER data on the web. Based on SOAP, it is essentially a web service contract for retrieving COUNTER

There is a merged SUSHI-COUNTER XML schema specification. It completely defines what a report request
and the corresponding response looks like. The XML formatted COUNTER data is essentially just wrapped in a
SUSHI protocol XML/SOAP response.

The following dataflow diagram should illustrate how COUNTER and SUSHI are used to transmit data between
the server and client.


                        DB            COUNTER Data
         SUSHI Client

                                                                       SUSHI Server

                                     SUSHI Response
                                                                                          App Server

                                     SUSHI Request

SDK Overview
This SDK includes .Net classes that will facilitate working with COUNTER 3.0 data and SUSHI 1.6 services.
Whether the intended solution is a SUSHI client or server, these classes will provide the groundwork to allow
developers to focus on the logic rather than implementing the standard .

The .Net solution is divided into folders: Documentati on, Samples, and SDK Classes.

The documentation folder, of course, contains this document as well as any other supporting documents, and
a copy of the XML schemas (in XSD format) that the SDK is based on.

The samples folder contains a simple SUSHI server implementation, and a very basic client that will make a
SUSHI request and display the response. Both of these use WCF as the transport service.

The SDK Classes folder contains all the generated classes, as well as infrastructure interfaces for working
with SUSHI services and COUNTER data.

Many of these classes were generated from the schemas provided by the respective standards, but there have
been some modifications where the code generation tool failed to bring over the desired class details.

Using the SDK to Build a Client Application
The following code demonstrates using the included proxy class to make a call to the SUSHI service. Most of
the code is filling the request object. When the call is complete, you will have a GetReportResponse obj ect
(populated with data and/or any exceptions) that you can process as you see fit.

  //create a new instance of a proxy to the WCF service
  //This reads WCF settings from app.config <system.serviceModel> <client>
  using (var proxy = new SushiServiceProxy())
     //make the call building the request object on the fly
     GetReportResponse report = proxy.GetReport(new GetReportRequest()
        ReportRequest = new ReportRequest()
           Created = DateTime.Now,
           CreatedSpecified = true,
           CustomerReference = new CustomerReference
              ID = "1234",
              Name = "ACME"
           ID = Guid.NewGuid().ToString(),
           ReportDefinition = new ReportDefinition
              Filters = new ReportDefinitionFilters
                 UsageDateRange = new Range
                    Begin = DateTime.Parse("1/1/2008"),
                    End = DateTime.Parse("1/31/2008")
              Name = "JR1",
              Release = "1"
           Requestor = new Requestor
              Email = "",
              ID = "1234",
              Name = "ACME"

From the app.config file:


Using the SDK to Build a Server Application
Creating a server is somewhat more involved than creating a client. You will need to follow
these 4 steps:

1. Create a class that implements IAuthorizationAuthority

This interface has only one method that accepts the req uestor and customer reference objects
from a SUSHI report request and returns a Boolean value indicating whether or not to allow
the request to be filled.

2. Create a class that implements IUsageReportRepository

Again, there is only one method to implement. It accepts basic repor t request criteria and
should return an array of report objects. This is where the bulk of your service logic will live.
Basically, your code should query your usage data (files, database, etc…) and populate report
objects that return the data. You will ne ed to understand the structure of COUNTER reports to
be able to fill the report object accurately.

3. Create a class that implements ISushiService

Once more, there is only one method to implement. The code should be fairly straightforward.
Create an instance of SushiComponent, passing the classes from step 1 and 2 to the
constructor. Then call the GetSushiReports method to get an array of the reports as returned
by the UsageReportRepository class (assuming that’s what you named the class that
implements IUsageReportRepository). These results can be placed directly into the response
object. Here is a sample implementation:
public GetReportResponse GetReport(GetReportRequest request)
   var businessLogic = new SushiComponent(new UsageReportRepository(), new AuthorizationAuthority());

    var response = new GetReportResponse()
                          ReportResponse = new CounterReportResponse()
                                                 Created = DateTime.Now,
                                                 CreatedSpecified = true,
                                                 CustomerReference = request.ReportRequest.CustomerReference,
                                                 ID = request.ReportRequest.ID,
                                                 ReportDefinition = request.ReportRequest.ReportDefinition,
                                                 Requestor = request.ReportRequest.Requestor,
        response.ReportResponse.Report = businessLogic.GetSushiReports(request.ReportRequest.Requestor,
    catch (Exception ex)
        response.ReportResponse.Exception = ex.ToSushiExceptions().ToArray();

    return response;

4. Host the service class

Hosting the service class can be done with a windows service or via an IIS web site. This will
be specific to your environment. Visual Studio will automatically host your classes for you (for

debugging purposes) with WCFSvcHost.exe if you put it inside a WCF Service Library project.
Set the project as the startup project for your solution and then start (F5) a debugging
instance. Examples and how-to’s for hosting WCF services in IIS and as a Windows service are
readily found on the web.

The Included Samples
This sample client is the simplest of samples. It is a plain UI for entering the information to build a request
object, with a TreeView to display the parsed XML results. There is no validation or special error handling.
The base WCF configuration is read from the app.config file, and the user is allowed to override the URI for
the endpoint via a text box on the UI. The rest of the WCF configuration is not changeable from the UI.

The sample server has a little more implementation to it. The basi c design assumes that there will be a folder
containing all the XML COUNTER JR1 reports for the server’s customers. These fi les must have filenames in
the format of YYYYMMDD-ReportType-CustomerId.xml. When a request is being processed, the server will
search the folder for filenames with the correct report type, customer ID, and date. Each file will be loaded
and its contents moved to the response object.

There is no processing of usage data. The contents of the file are merely passed on to the client as th ey are
found in the files.


To top