User guide

This page shows some basic concepts and examples to work with of ODataJClient, Open Source (Apache License 2.0) library that enables Java applications to deal with OData 3.0 services.

Preconditions

• Apache Maven >= 3.0.3
• JDK >= 1.6.0-23

Obtaining ODataJClient

1. Obtain source code by either
2. downloading source ZIP archive
3. or git clone git@github.com:MSOpenTech/ODataJClient.git
4. Build

$ cd ODataJClient
$ mvn clean install

At this point ODataJClient is installed into your local Maven repository and must be added as dependency to your own Maven project as

<dependency>
  <groupId>com.msopentech.odatajclient</groupId>
  <artifactId>odatajclient-engine</artifactId>
  <version>M3</version>
</dependency>

Introduction

There are some common basic concepts that need to be introduced before starting with ODataJClient.

URI management

URIs are a key concept in the OData protocol specification, so you should be already aware of the elements below (full reference to URI syntax is also available):

1. Service Root and Path Prefix
2. Resource Path
3. Query Options

Many methods referenced below in the Examples section require an URI parameter; with ODataJClient two options are available for this purpose:

1. provide an URI value via plain String: URI.create("http://services.odata.org/OData/OData.svc/Products");
2. feature the provided ODataURIBuilder - see the Examples below for some sample usage.

Request / Response handling

Working with ODataJClient can be generally summarized as:

1. get an ODataRequest instance (for the required kind of request) via one of the provided Factory objects;
2. (optionally) use another Factory object to build the parameter(s) to pass to the request created above;
3. execute the request and obtain a specialized ODataResponse instance (generally, at this point the actual REST communication with remote OData service takes place);
4. inspect the response object and read the body into one of Java classes built to represent the OData model objects (entity, entity set, property, and so on - read more about OData abstract data model).

Examples

In the following, let testODataServiceRootURL be the String representation of your OData service root (http://services.odata.org/OData/OData.svc/ for example).

Entity retrieve

// Use ODataURIBuilder for building valid URI for entity type
ODataURIBuilder uriBuilder = new ODataURIBuilder(testODataServiceRootURL).
    appendEntityTypeSegment("Customer(1)");

// Obtain a typed request instance via ODataRetrieveRequestFactory
// Note that you could also write here
// ODataEntityRequest req =ODataRetrieveRequestFactory.getEntityRequest(
//    URI.create("http://services.odata.org/V3/OData/OData.svc/Products(0)"));
ODataEntityRequest req = ODataRetrieveRequestFactory.getEntityRequest(uriBuilder.build());

// Send the request to remote OData service, get typed response back
ODataRetrieveResponse<ODataEntity> res = req.execute();

// Access response information: (1) code
res.getStatusCode();
// (2) message
res.getStatusMessage();
// (3) common headers
res.getContentType();
res.getEtag();
// (4) all headers
res.getHeaderNames();
res.getHeader("DataServiceVersion");

// Get response body as ODataEntity
ODataEntity entity = res.getBody();

// Access entity elements: (1) edit link
entity.getEditLink();
// (2) properties
List<ODataProperty> properties = entity.getProperties();
ODataProperty property = entity.getProperty("Id");
// (3) navigation links
List<ODataLink> navLinks = getNavigationLinks();
// (4) association links
List<ODataLink> assLinks = getAssociationLinks();
// (5) media edit links
List<ODataLink> meLinks = getEditMediaLinks();
// (6) bound operations (functions, actions)
List<ODataOperation> operations = getOperations();