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

Content format

ODataJClient supports two serialization formats for OData model objects:

1. Atom / XML
2. application/atom+xml (for Entity and Entity Set)
3. application/xml (for any other model object)
4. JSON, in its three variants
5. No Metadata application/json;odatda=nometadata
6. Minimal Metadata application/json or application/json;odatda=minimalmetadata
7. Full Metadata application/json;odatda=fullmetadata

Any ODataRequest object allows the content format to be specified; when not specified, application/json is the default set.

Examples

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

1. Entity retrieve
2. EntitySet retrieve
3. Property retrieve