deliverable 3.1.a: big iot api design - first...

BIG IoT – Bridging the Interoperability Gap of the Internet of Things

Deliverable 3.1.a:

BIG IoT API Design - First ReleaseVersion 1.0.1

Date: 31.12.2016

This project has received funding from the European Union’s Horizon 2020 research andinnovation program under grant agreement No 688038.

Deliverable 3.1.a – BIG IoT API Design D3.1.a

© 2017 2

Responsible Person and Affiliation Siemens AG:

Andreas Ziller

Due Date / Delivery Date 31.12.2016

State Final Version

Reviewers Ernest Teniente (UPC)

Yong Wang (TUC)

Version 1.0

Confidentiality Public


© 2017 3

List of Authors

Organization Authors Main organizations’ contributionsBosch Stefan Schmid, Denis Kramer Chapter 2, 3

Econais Dimitra Patroumpa, Costas Pipilas Section 4.2

Siemens Andreas Ziller, Arne Bröring Chapter 1, 3, 4, 5


© 2017 4

Table of ContentsAbbreviations ....................................................................................................................... 6

1 Introduction .................................................................................................................. 7

1.1 Motivation ....................................................................................................................... 7

1.2 Relation to other Deliverables ......................................................................................... 8

2 BIG IoT API in context of the High-Level Architecture ................................................ 11

2.1 Core Concepts of the BIG IoT Architecture ..................................................................... 11

2.2 BIG IoT Architecture Overview ....................................................................................... 122.2.1 High-level Architecture Building Blocks .................................................................................... 13

2.3 Interfaces and Interactions ............................................................................................ 15

3 BIG IoT API Tutorial ..................................................................................................... 16

3.1 Introduction ................................................................................................................... 16

3.2 Setup .............................................................................................................................. 163.2.1 Preparation of your System ..................................................................................................... 173.2.2 Install and run Marketplace and eXchange ............................................................................... 183.2.3 Preperare and Run Demo......................................................................................................... 20

3.3 Registration on the Marketplace.................................................................................... 25

3.4 BIG IoT from a Provider's Perspective ............................................................................ 253.4.1 Authentication on the Marketplace ......................................................................................... 253.4.2 Create an Offering ................................................................................................................... 263.4.3 Registration of Offerings .......................................................................................................... 273.4.4 Implementing the access Callback ............................................................................................ 273.4.5 Activation of Offerings ............................................................................................................. 28

3.5 BIG IoT from a Consumer's Perspective ......................................................................... 293.5.1 Authentication on a BIG IoT Marketplace ................................................................................. 293.5.2 Creating a Query ...................................................................................................................... 293.5.3 Querying the Marketplace ....................................................................................................... 303.5.4 Accessing Offerings .................................................................................................................. 323.5.5 Continuous Access of Offerings ................................................................................................ 33

4 BIG IoT Web API .......................................................................................................... 35

4.1 Deployment Example ..................................................................................................... 36

4.2 Proxy Support for device-level Platforms ....................................................................... 40


© 2017 5

4.3 Blocking and Non-Blocking Operations .......................................................................... 41

4.4 Access Operation ........................................................................................................... 434.4.1 Specification ............................................................................................................................ 444.4.2 Dealing with Non-REST-like IoT platforms ................................................................................ 45

4.5 Feed Operation .............................................................................................................. 454.5.1 Synchronous vs. asynchronous feeds ....................................................................................... 454.5.2 Feed support in BIG IoT............................................................................................................ 474.5.3 Concepts for retrofitting Feed support ..................................................................................... 494.5.4 Lifecycle Management ............................................................................................................. 50

5 Conclusion & Outlook ................................................................................................. 53

Figures and Tables .............................................................................................................. 55

References .......................................................................................................................... 56

Appendix A UML Class Diagrams ........................................................................................ 57

Appendix B BIG IoT API Documentation ............................................................................. 61


© 2017 6

AbbreviationsAbbreviation MeaningA1 Access Interface #1API Advanced Programming InterfaceBCN Barcelona (pilot)BIG IoT Project title: Bridging the Interoperability Gap of the Internet of ThingsDOA Description of ActionHTTP Hypertext Transfer ProtocolID IdentifierIoT Internet of ThingsIP Internet ProtocolISO International Organization for StandardizationJAR Java ArchiveJSON JavaScript Object NotationMQTT Message Queue Telemetry SupportMS MilestoneNAT Network Address TranslationNG Northern Germany (pilot)OD Offering DescriptionOGC Open Geospatial ConsortiumP1 Programming Interface #1P2 Programming Interface #2P3 Programming Interface #1PIE Piedmont (pilot)RDF Resource Description FrameworkREST Representational State TransferSDK Software Development KitSES Sensor Event ServiceSOS Sensor Observation ServiceSPARQL SPAQRL Protocol and RDF Query LanguageSPS Sensor Planning ServiceSWE Sensor Web EnablementTCP Transmission Control ProtocolUI User InterfaceURI Uniform Resource IdentifierURL Uniform Resource Locator


© 2017 7

1 Introduction

This chapter introduces to this deliverable, motivates the topic, and defines its scope.

1.1 Motivation

The idea of an Internet of Things is no more a futuristic vision, but indeed an increasingcommercial reality that reaches to various application domains ranging from quantified selfand smart home applications, over smarter cities and eHealth systems, to Industry 4.0. Doz-ens of IoT platforms are upcoming. These include cloud solutions, such as Evrythng [1],ThingWorx [2], Xively [3], or Yaler [4], but also on premise solutions such as Bosch’s IoTSuite [5], as well as thematically or geographically focused platforms, such as the Smart Dataplatform for the Piedmont region [6]. However, up to now, these IoT platforms failed toform vibrant IoT ecosystems.

Currently, there is no vibrant collaborative IoT ecosystem, since the number of stakeholdersinvolved in IoT ecosystems (e.g., IoT platform providers, service and application providers) islarge, the market entry barriers are high, and the potential gain is low for a single stake-holder. Providers of platforms and services require a simple, established way to offer accessto their resources. Marketplaces that enable providers to monetize access to the resourcesoffered by their platforms and services are not yet available. Once these marketplaces areestablished, developers will be able to easily build IoT services and applications and buildtheir products around these. Revenue streams can then be shared across all contributingentities (i.e., IoT platform and service providers). A key task of a marketplace is to provideextended functionalities to enable the advertising, dynamic discovery, automated orches-tration, and negotiation of services to facilitate their usage.

However, before such marketplaces can bring their effect, a serious market barrier needs tobe tackled: the missing interoperability. The fragmentation of the IoT and the lack of in-teroperability prevent the emergence of broadly accepted IoT ecosystems [7]. A recentMcKinsey study [8] estimates that a 40% share of the potential economic value of the IoTdirectly depends on interoperability between IoT platforms. Today, we are dealing with var-ious vertically oriented and mostly closed systems. Architectures for IoT are built onheterogeneous standards (e.g., IETF CoAP [9], OASIS MQTT [10], OMA LWM2M [11], OGCSWE [12], or OneM2M [13]) or even proprietary interfaces. As a result, most existing andemerging IoT platforms offer heterogeneous ways for accessing IoT resources.


© 2017 8

This causes interoperability problems when overarching, cross-platform, and cross-domainapplications are to be built, and eventually prevents the emergence of vibrant IoT ecosys-tems. Additionally, it leads to barriers for business opportunities, especially for smallinnovative enterprises, which cannot afford to offer their solution across multiple platforms.They can only provide applications and services for a small number of platforms, e.g., a traf-fic information application for an IoT platform of a specific city. This lack of interoperabilityresults in lost business opportunities and prevents innovative business ideas.

In order to address these shortcomings in today's IoT landscape, the BIG IoT project has de-veloped an architecture as a foundation for building IoT ecosystems (see D2.4). Itovercomes the above described hurdles through (1) a common API, (2) semantic descrip-tions of resources and services, as well as (3) a marketplace as a nucleus of the ecosystem.This will allow new services by combining data from multiple platforms (e.g., parking infor-mation from various smart city platforms). In addition, platforms from multiple domains(e.g. home and city) and regions will be combined, such that applications can utilize all rele-vant information and work seamlessly across regions (e.g. the same smart parkingapplication works on top of a smart city platform in Berlin, in Barcelona and in London).

The scope of this document is the specification of the BIG IoT API. This BIG IoT API can beseen from two complementary perspectives, as (1) a Programming API implemented as li-braries (libs) of an SDK and (2) a Web API. Both perspectives are covered in this document.The Programming API is provided to developers in order to facilitate the implementation ofapplications or the provision of platforms and services. The Web API defines protocols andencodings for actual message exchange to implement the various interactions and work-flows designed. Thereby, the Programming API abstracts from the underlyingcommunication protocols defined in the Web API.

Parts of this deliverable (mainly section 3) will be used as online documentation, which willbe accessible to developers. For an easy understanding, those parts are written in a tutorial-style. This documentation will facilitate the onboarding of external developers joiningthrough an open call and it will generally help to grow the BIG IoT ecosystem.

1.2 Relation to other Deliverables

The tasks of WP3 and WP4 are highly interrelated, however, their deliverables have eachtheir own, clear responsibilities. Figure 1 follows the general BIG IoT architecture descrip-tion in D2.4 and illustrates at hand of this architecture the scope of each of the differentdeliverables of the tasks 3.1, 3.2, 4.1, 4.2, and 4.3.


© 2017 9

Figure 1 Relation of deliverables

D3.1 covers the description of the BIG IoT API. This entails a specification of the Web API(e.g., interaction model, and encodings) as well as description of the programmatic API thatis implemented as part of consumer and provider lib of the SDK.

D4.1 describes the architecture of the BIG IoT Marketplace. This includes the general design,the workflows of interactions, the GraphQL-based API of the marketplace, as well as theuser interface of the portal to utilize the marketplace. Also contained in this deliverable is adescription on how to map between the GraphQL API of the marketplace frontend and itsSPARQL based triple store backend.

D3.2 describes the model and schema of the core semantic model of BIG IoT. This semanticmodel is used as a basis for (1) the Offering description to define the capabilities of offeringsprovided by IoT platforms or services, and (2) the underlying data model of the BIG IoT Mar-ketplace.


© 2017 10

D4.2 builds up on the core semantic model of D3.2 and defines the application domainmodel, which specifies a vocabulary of terms that can be used in Offering descriptions, andin the triple store of the marketplace.

D4.3 addresses the orchestration and composition of the offerings of BIG IoT providers (i.e.,platforms or services). A composition of offerings can be specified by defining a Recipe. Thesemantic model and examples of such recipes is the scope of this deliverable.


© 2017 11

2 BIG IoT API in context of the High-Level Architecture

This section introduces the high-level architecture of BIG IoT with the goal to explain thecontext for the BIG IoT API discussion. The full specification of the BIG IoT Architecture -Release 1 is provided in Deliverable D2.4.a.

2.1 Core Concepts of the BIG IoT Architecture

This section summarizes the underlying concepts of the BIG IoT architecture and the inter-actions between them, namely offerings, (offering) providers and consumers, and theinteractions of registering and discovering offerings via a marketplace, and accessing theresources offered by a provider (see Figure 2).

An offering encompasses a set of IoT resources, typically a set of related information (e.g.low-level sensor data like temperature or aggregate information across a region) or func-tions (e.g. actuation tasks like open a gate or computational functions like compute a route),that are offered on a marketplace.

Providers register their offerings on a marketplace and provide access to the offered re-sources via a common API. A provider can be either a platform or a service instance thatoffers available resources, i.e., some information or access to functions that it wants toshare or trade on the marketplace (e.g. an IoT platform of a parking loT provider). Consum-ers discover and subscribe to offerings of interest via a marketplace in order to access theresources. A consumer can be either an application or a service instance that requires ac-cess to IoT resources in order to implement an intended service or function (e.g., a smartparking service provided by the city).

In technical terms, a provider registers its offerings on the marketplace by providingan offering description for each offering. An offering can for example entail parking infor-mation for a city and include data such as geo location or address of the parking lot, thetype of lot (e.g. garage or on-street), available spots, occupied spots, etc. In order to in-crease interoperability between different IoT platforms, the offering description is providedin a machine interpretable manner. All relevant communication metadata is provided onhow the offering can be accessed (e.g., endpoint URL, which HTTP method, etc.). As a de-fault vocabulary set, the offering description includes a local identifier (unique to aprovider), a name of the offering, and the input and/or output data provided toa consumer when the offering is accessed. The description may also include information


© 2017 12

about the region (e.g. the city or spatial extent) where the resources relate to, the price foraccessing the resources, the license of the data provided, the access control list, etc.

Figure 2 Core Concepts

Consumers discover offerings of interest on the marketplace by providing an (offering) que-ry. The query entails a specification of the type of offerings the consumer is interested in.For example, a consumer can provide a description of the desired resources (such as type ofparking information), and also define the maximum price, the desired license types, the re-gion, etc. Upon a discovery request, the marketplace identifies all matching offerings andreturns them to the consumer. The consumer can then choose the offerings of interest andsubscribe to those on the marketplace. Since the discovery can take place at run-time, aconsumer is able to identify and subscribe to newly offered resources as they emerge. Final-ly, to limit the data to be transmit upon accessing an offering, a consumer can also provide afilter in the request.

2.2 BIG IoT Architecture Overview

This section provides an overview of the BIG IoT architecture.


© 2017 13

2.2.1 High-level Architecture Building Blocks

As shown in Figure 3, we distinguish the following five core building blocks:

1. BIG IoT enabled platform – this IoT platform implements (as a provider)the common API, which is called the BIG IoT API, to register offerings on a BIG IoTMarketplace, and grants BIG IoT Services or Applications (as consumers) access tothe offered resources.

2. BIG IoT Application – this application software implements and uses the BIG IoT API,(as a consumer) to discover offerings on a BIG IoT Marketplace, and to access the re-sources provided by one or more BIG IoT Services or Platforms (as providers).

3. BIG IoT Service – this IoT service implements and uses the BIG IoT API to register of-ferings on a BIG IoT Marketplace (as a provider) and/or to discover and accessofferings provided via a BIG IoT Marketplace (as a consumer).

4. BIG IoT Marketplace – this composite system consists of sub-components: The mar-ketplace API serves as an entry point for all communications and interactions withthe marketplace; the Identity Management Service (IdM) which authenticates andauthorizes providers and consumers; the eXchange, which allows registration anddiscovery of offerings using semantic technologies; the Web Portal for users of themarketplace; and the Charging Service, which collects accounting information.

5. BIG IoT Lib – this is an implementation of the BIG IoT API that supports service andapplication developers. The BIG IoT Lib consists of a Provider Lib and a ConsumerLib part. It translates function calls from the respective application or service logic, orthe platform code into interactions with the marketplace, or peer-services or -platforms. The Provider Lib allows a platform or service to authenticate itself ona marketplace and to register offerings. The Consumer Lib allows an application orservice to authenticate itself on a marketplace, to discover available offerings basedon semantic queries, and to subscribe to offerings of interest. The use of semantictechnologies enables the eXchange to perform semantic matching even in case pro-viders and consumers use different semantic models or formats, as long as acommon meta-model defines the relations/mapping between the different semanticmodels and converters for the different semantic formats are supported.


© 2017 14

Figure 3 Building Block View on BIG IoT Architecture

The architecture supports the following platform integration modes in order to meet thearchitectural requirements defined in deliverable D2.3.a:

∂ Mode 1: the platform developer uses the Programming Interface P1 provided by theProvider Lib to programmatically extend an existing or new IoT platform.

∂ Mode 2: the provider develops and operates a BIG IoT Gateway Service, which han-dles all BIG IoT related interactions and translates the relevant requests into callssupported by the existing platform (Integration Interface I1).

∂ Mode 3: the provider develops and operates a BIG IoT Management Service, whichhandles the interactions with the marketplace. It integrates with the legacy platformby implementing the Integration Interface I2. Access to the resource offerings is pro-vided directly by the legacy platform.

∂ Mode 4: the provider develops and operates a BIG IoT Proxy Service, which handlesthe interactions with the marketplace and offers the Access Interface A1. The proxy-


© 2017 15

service acts as an “always-available” proxy on behalf of a typically constrained de-vice-level platform.

2.3 Interfaces and Interactions

Besides the core components, Figure 3 also depicts the relevant interfaces of the architec-ture. The Programming Interfaces P1 and P2, provided by the BIG IoT Lib, are offered todevelopers to connect their components with the marketplace and other entities. For easyintegration of constrained device-level platforms, a special BIG IoT Lib is provided, whichallows developers to easily interact with the BIG IoT Proxy Service (via the ProgrammingInterface P3).

The BIG IoT Marketplace provides five interfaces to allow interactions with its services.The M1 interface is used by the provider and consumer instances to authenticate them-selves on the marketplace at start-up. Upon successful authentication, the Provider orConsumer Libs will obtain the required credentials for any further communication and in-teraction with the marketplace. The M2 interface is used by providers to register/deregisterofferings, while the M3 interface is used by consumers to discover offerings onthe marketplace. Once a registration request is received, the BIG IoT eXchange validates theofferings and stores them in a semantic database. To subscribe/unsubscribe to offerings,consumer applications use the M4 interface. With a subscription, a consumer indicates itsintent to access the offered resources, and confirms its consent with respect to the offer-ing's license, price, etc. Once an offering is subscribed, the eXchange provides the consumerunique credentials to access this offering. In case the offering has expired or has been up-dated by the provider, the eXchange revokes the subscription and indicates the cause in theresponse. The M5 interface is used by consumers and providers to send accounting infor-mation in regular time intervals to the Charging Service. Accounting types (e.g. per message)can differ between offerings, and are specified by a provider in the offering description. Theinterfaces M1-M4 are used in the same way by the Web Portal.

The Access Interface A1 is the interface via which a consumer gets access to resources of-fered by a provider. Depending on the Provider Lib implementation, it will support differentaccess means. All Provider Libs shall support the HTTP-based request/response access. Op-tionally, a Provider Lib can also support other protocols (e.g. WebSockets, MQTT) or otheraccess paradigms (e.g. streaming).


© 2017 16

3 BIG IoT API Tutorial

This section gives Developer a quick introduction to the utilization of the BIG IoT API. It iswritten in a language addressing developers directly. This tutorial shall be part of the BIG IoTAPI documentation which will be used in the BIG IoT Open Call.

3.1 Introduction

Using the BIG IoT software development kit (SDK), it is easy to get started to dive into theBIG IoT ecosystem. It is a Java SDK allowing providers to register and manage their offeringsand consumers to access offerings from the BIG IoT Marketplace. The sources are availableat https://gitlab.com/groups/BIG-IoT. Currently (December 2016) it is required that youhave a Gitlab account and that you are member of the group BIG-IoT.

In this tutorial, a general walkthrough through the BIG IoT Lib is provided. We distribute thistutorial into two parts: The first part will provide a basic "Hello world" example from a pro-vider perspective. It shows how to extend an existing IoT platform to be BIG IoT enabled.The example platform is a simple IoT platform which offers temperature data from differentlocations and makes them public on the BIG IoT Marketplace. The second part will showhow to use the BIG IoT Consumer Library to access this data from a service developer's per-spective.

3.2 Setup

If you want to try the tutorial by yourself, you have to execute the following steps, whichcomprise the preparation of your system (1), the setup of the marketplace and eXchange (2)and the execution of the demo (3). Therefore, you have to install some software packagesand finally to deploy software, which open ports on your machine. You need to have a directinternet connection when building the code. We recommend to install all the software in anon-productive system. We prefer using a virtual machine. See https://www.virtualbox.orgif you want to get in touch with that. Please make sure that the security policies of your or-ganization cover all those steps.

By today (December, 2016) the access to the source code for the demo requires a Gitlabaccount and a membership to the group “BIG-IoT”.


© 2017 17

3.2.1 Preparation of your System

In order to run the demo, you have to install the software packages below. In the column“We used …” you find remarks to the setup procedure. For further support you can go tothe websites provided in “Where you find it”. We used Windows 7 as hosting operating sys-tem.

Youhave toinstall…

We used … Where you find it

Git The Git dis-tribution ofgit-scm.com(v2.11.0 )

https://git-scm.com/

Java Java SE De-velopmentKit 8 (JDK 8)

http://www.oracle.com/technetwork/java/javase/downloads/index.html

Eclipse Eclipse Ne-on.1a (v4.6.1)

in the distri-bution

“Eclipse IDEfor Java EEDevelopers”

If you installwith eclipseinstaller,make sureyou selectthe rightdistribution!

http://www.eclipse.org

Gradle The Eclipseplugin“BuildshipGradle Inte-

In Eclipse: go to “Help”⇓ “Eclipse Marketplace”. Search for “buildship”


© 2017 18

gration 1.0”

Node.js v6.9.2 LTS https://nodejs.org

Scalasbt

Version0.13.13.1

http://www.scala-sbt.org/

3.2.2 Install and run Marketplace and eXchange

The example applications of this tutorial requires the BIG IoT Marketplace and eXchange forregistering and discovering the offerings. They come as two applications, which have to beseparately build and deployed. For setting up the marketplace, you have to perform thefollowing steps in a new shell window (e.g. Windows Command Prompt) and a folder ofyour choice (we started in the Eclipse workspace folder[c:\Users\yourlogin\workspace]):


© 2017 19

cd <a folder of your choice>

git clone https://gitlab.com/BIG-IoT/marketplace.git

cd marketplace

git checkout 0ae48e

run

The download of all dependencies and the compilations takes a couple of minutes. Acceptall communication request shown by your firewall (obey your security policies!). If the buildis successful, you should see in the last line of you shell:

Server online at http://0.0.0.0:8082

The marketplace is now running. Leave the window open! Next you have to deploy eX-change in a new shell window with the following commands:

cd <a folder of your choice>

git clone https://gitlab.com/BIG-IoT/exchange.git

cd exchange

git checkout c64983

run

Again it takes a couple of minutes until you see in you the following in the shell:

exchange Starting exchange.server.Server.main()

[success] Total time: 384 s, completed 19.12.2016 14:22:00

1. Waiting for source changes... (press enter to interrupt)

Marketplace and eXchange are now running, leave both windows open. You can now startthe demo application.


© 2017 20

3.2.3 Preperare and Run Demo

We decided to show how to run the demo in Eclipse. Setting up the demo there has thebenefit that you can better explore the code with IDE support.

First you have to retrieve the sources via Git. We use the command line tool for that. Open anew shell and execute:

cd <your Eclipse workspace folder (e.g. C:\Users\andreas\workspace)>

git clone https://gitlab.com/BIG-IoT/lib-java.git

cd lib-java

git checkout 9ff16

Figure 4 Install Buildship Gradle Integration


© 2017 21

The BIG IoT API comes as a gradle project. If you haven’t done yet, you have to install Gra-dle. We had good experience using the Eclipse plugin “buildship”. So, in Eclipse menu barchoose “Help”⇓ “Eclipse Marketplace”. Search for “buildship”, search and install “BuildshipGradle Integration”. You have to accept the license conditions; Eclipse is restarted afterthat.

Figure 5 Eclipse Neon with fresh, empty workspace

We recommend that you start from a fresh workspace (this is the case if you just installedEclipse). In order to setup the BIG IoT API as new Java project, proceed as follows:

Choose “File”⇓ “Import”.


© 2017 22

Figure 6 Importing a Gradle Project

Select “Gradle\Gradle Project”.

Figure 7 Import Gradle Project Wizard

Hit “Next”


© 2017 23

Figure 8 Import Gradle Project Wizard - Setting Project Root Directory

In the “Project root directory” text field, set the folder where the API sources are located(here C:\Users\andreas\workspace\lib-java). It takes a couple of minutes until alldependencies are retrieved via Gradle.

Figure 9 Retrieving Dependencies via Gradle


© 2017 24

In the following, you probably receive the following question:

Figure 10 Question during Gradle Build

Choose “Overwrite”.

Figure 11 Having the BIG IoT API imported in Eclipse

Now, you can start the demo. First you run in the directory“src/main/java/org/bigiot/lib/examples” the file ExampleProvider.java,e.g. by selecting the file ExampleProvider.java in the “Project Explorer”, hitting “Run”⇓ “Run as”⇓ “Java Application”. Accept the firewall dialogue. The Provider is now running,it offers a spatial temperature service, which is registered in the background and deployedas a web service on your machine.


© 2017 25

The last step is to execute the consumer application. You have to run ExampleConsum-er.java the same way as for the provider application. It is located in the same folder asExampleProvider.java.

3.3 Registration on the Marketplace

Before you can use the Provider and Consumer Lib, you have to create an user account onthe marketplace. Deliverable D4.1 describes this process in the eXchange API chapter.

At the end of the registration process you will receive a marketplace API key, a provid-er/consumer ID and a provider/consumer certificate, which you can use in the API.

3.4 BIG IoT from a Provider's Perspective

Assuming you have built a simple IoT platform that gathers temperature data from yourneighborhood through temperature sensors. Now you want to make this data public. Howdo you connect your platform to the BIG IoT Marketplace in order to provide this data toother developers so they can use your data in their applications?

Using the BIG IoT Provider Lib, you can manage your data on the BIG IoT Marketplace interms of offerings. The Provider Lib offers the following main functionalities:

∂ Authentication∂ Registration of offerings∂ Activation and de-activation of offerings∂ Providing access callbacks

3.4.1 Authentication on the Marketplace

Before you can register your temperature sensor data on the marketplace as an offering,you need to authenticate with the marketplace.

Authentication

Provider provider = new Provider(“Barcelona_City-provider3”, "http://localhost:8080");

provider.initialize("localhost", 9001);

provider.authenticate(MARKETPLACE_API_KEY, PROVIDER_CERT_FILE);


© 2017 26

First of all, you create a Provider object, passing a Provider ID and a Marketplace URI youwant to connect to. Alongside your API key, you also received a unique ID and a certificate.You pass this data to the provider object's authenticate function in order to finish your au-thentication on the marketplace. The Provider object will be used for all subsequentinteractions with the marketplace.

3.4.2 Create an Offering

Now that you are authenticated you can create an offering for your temperature data. Thenext code block shows how you can use the Offering class to do this:

Offering creation

OfferingDescription offeringDescription = OfferingDescription.create("Temperature data offering")

.withInformation(new Information ("Temperature data offering", new RDFType("schema:temperature")))

.addInputDataElement(“longitude”, new RDFType(“schema:longitude”))

.addInputDataElement(“latitude”, new RDFType(“schema:latitude”))

.addInputDataElement(“radius”, new RDFType(“schema:geoRadius”))

.addOutputDataElement(“temperature”, new RDFType(“schema:temperature”))

.inRegion(Region.city(“Barcelona”))

.withPrice(Euros.amount(0.002)

.withAccountingType(AccountingType.PER_ACCESS)

.withLicenseType(LicenseType.OPEN_DATA_LICENSE)

.addEndpoint(EndpointType.HTTP_GET, AccessInterfaceTypes.BIGIOT_LIB, “/temperature”);

The OfferingDescription class provides a builder method that lets you easily create anew offering. For your offering to be visible on the Marketplace, you have to provide aname for it. Also it is important to define a type for the offering so that consumers can au-tomatically find it (see Consumer section). This information is encapsulated inthe Information object. Additionally, you can define input parameters that can be set byyour service’s consumers when accessing your platform. Here we provide an example howto add a location based filter as an input element to your offering. You provide the output ofyour offering through the addOutputDataElement function which is temperature data inthis example. The consumer of your data will have the possibility to query for data within aspecific area and radius. He will retrieve data that conforms to the schema of the type"schema:temperature".


© 2017 27

Both input and output elements use the RDFType class which makes it easy to semanticallyannotate your data. Providing a region, a price, a license type and an endpoint completesthe offering description. The endpoint defines the access method to your platform.

3.4.3 Registration of Offerings

Now that you created the Offering, it should be registered on the Marketplace so that otherdevelopers can find it. You will use the register function for that:

Register offering

String offeringId = provider.register(offeringDescription, accessCallback);

The register function requires the Offering object and a callback class as input parame-ters. The callback is later used to handle incoming requests for your offering. This isexplained in the next chapter.

3.4.4 Implementing the access Callback

Every time someone uses your offering, the BIG IoT Consumer Lib will forward the requestto the provided callback function. We will show a simple example of how such a callbackfunction implementation could look like:

Callback function

private static AccessRequestHandler accessCallback = new AccessRequestHandler(){

@Override

public String processRequestHandler (OfferingDescription offeringDescription, Map<String,String> inputData) {

double longitude=0, latitude=0, radius=0;

if (inputData.containsKey("longitude")) {

longitude = new Double(inputData.get("longitude"));

}

if (inputData.containsKey("latitude")) {

latitude = new Double(inputData.get("latitude"));

}

if (inputData.containsKey("radius")) {

radius = new Double(inputData.get("radius"));

}


© 2017 28

Random r = new Random();

return String.format(Locale.US, "{\"schema:temperature\": %.2f,\n \"schema:latitude\": %.4f,\n \"schema:longitude\": %.4f,\n}", r.nextFloat()*3+17 , r.nextFloat()*0.01+longitude, r.nextFloat()*0.01+latitude);

};

};

The AccessRequestHandler class is an abstract class that requires you to overridethe processRequestHandler method. This method receives the OfferingDescrip-tion object that we created earlier and the inputData HashMap which contains the inputfilters that the consumer has specified during his access request. If any of the possible filtershave been used, we pass them to a service function that simply retrieves the temperaturedata from our platform's database. However, you could of course implement a more appro-priate service logic here. AccessRequestHandler is implemented as a functionalinterface. If you prefer, you can also provide the business logic in the Lambda notation.

3.4.5 Activation of Offerings

Now you are almost done! The last part you need to do is to activate your registered offer-ing in order for others to use it. Use the activateOffering method from the providerobject for this.

Activate offering

provider.activateOffering(offeringDescription);

As you can see, this is pretty straightforward. To deactivate your offering, you guessed it,use the deactivateOffering method.

Deactivate offering

provider.deactivate(offeringDescription);

Congratulations! You have created your first offering on the BIG IoT Marketplace.


© 2017 29

3.5 BIG IoT from a Consumer's Perspective

Assuming, you want to create an environmental monitoring service for the city of Barcelonathat should only display temperature data on a web dashboard for different places in thecity. Using the BIG IoT Consumer Lib, it is very easy to make your service use the BIG IoTMarketplace to query relevant data sources and access them.

The Consumer Lib offers the following main functionalities:

∂ Authentication on a BIG IoT Marketplace∂ Querying the Marketplace to find relevant offerings∂ (Un-)Subscribing to offerings to be notified of any events regarding the offerings∂ Accessing offerings

3.5.1 Authentication on a BIG IoT Marketplace

To get started with the Consumer Lib, you have to create an instance ofthe Consumer class. The constructor requires a unique consumer ID and a marketplace URI.

To authenticate with the marketplace, you have to use the authenticate method providedby the consumer object. This method requires the marketplace API key and a consumer cer-tificate which you both received when you registered on the BIG IoT Marketplace portal.

Consumer instantiation

Consumer consumer = new Consumer("Barcelona_City_Example_Service", "http://localhost:8080");

/* Authenticate on the marketplace */

consumer.authenticate("DUMMY_KEY", "dummy.cert");

If you want to connect to a different marketplace, you just repeat the previous steps by cre-ating a new Consumer object. This way it is easy to retrieve data from an arbitrary numberof BIG IoT Marketplaces.

3.5.2 Creating a Query

Now that you are authenticated on the marketplace, you can find there relevant tempera-ture sensor data to feed into your service. To do that, you query the marketplace usingthe OfferingQuery object. The query gets constructed using a builder pattern which first,creates the empty OfferingQuery object that is completed with additional query filters,such as a specific search region, a desired accounting type, a maximum price, etc. The mar-


© 2017 30

ketplace will later retrieve all matching offerings for this query. In this example, the query isquite simple however it can be more complex in other situations.

Offering Query

OfferingQuery query = OfferingQuery.create(”TemperatureQuery”)

.withInformation(new Information("Temperature sensor query", "schema:temperature"))

.inRegion(Region.city("Barcelona"))

.withAccountingType(EnumTypes.AccountingType.PER_ACCESS)

.withMaxPrice(Euros.amount(0.002))

.withLicenseType(LicenseType.OPEN_DATA_LICENSE);

Here we create a query, that is called "TemperatureQuery". The type of offerings re-turned should be of type "schema:Temperature". The types of offerings that are availablecan be evaluated using the online documentation of the BIG IoT Marketplace. The query isusing a region filter that selects only offerings that are provided in the city of Barcelona.Also the accounting type should be based on the number of accesses and not, for example,on a monthly fee. The price should not exceed 0.2 cents per access and the data licenseshould be the Open Data License. The Consumer Lib offers you Enum classes that you canconsult to see, which other licenses or accounting types are available.

3.5.3 Querying the Marketplace

To execute the query on the marketplace, the Consumer object provides different options.The dedicated method for this is .discover() and provides different signatures to takedifferent programming preferences into account.

Overloading of discover()

CompletableFuture<List<OfferingDescription>> discover();

void discover(DiscoverResponseHandler onSuccess, DiscoverResponseErrorHandler onFailure);

void discover(DiscoverResponseHandler onSuccess);

The first variant uses a CompletableFuture as a return type which is a promise on a listof OfferingDescriptions, which is part of the functional programming styles intro-duced in Java 8. The other two variants are using callback mechanisms.


© 2017 31

The following code shows how to discover offerings getting them as a CompletableFu-ture on the list of OfferingDescriptions:

Executing Discover returning a CompletableFuture

CompletableFuture<List<OfferingDescription>> listFuture = consumer.discover();

List<OfferingDescription> offerings = listFuture.get();

Offering concreteOffering = offerings.get(0).subscribe();

The .discover() call is actually non-blocking. So, you could do something in between, e.g.handing over the CompletableFuture object to your management thread. Or alterna-tives, you can directly receive the list by calling the .get() method. This call is blocking andwill wait on the list of OfferingDescriptions. The motivation of using Completable-Future here is, that you can come easily from an asynchronous behavior to a blockingbehavior and further you can utilize reactive concepts if you want. For example by calling.thenApply() as a monad on the CompletableFuture object allows you to apply func-tions once the list of offering Descriptions is received.

Chaining functions on Discover Response

listFuture.thenApply(BigHelper::showOfferingDescriptions);

Before you can utilize an offering, you have to subscribe on the OfferingDescriptionobject. Subscription is done through the correspondent subscribe method which returnsan Offering object. The offering object provides different access methods as describedlater.

can also use callbacks for discovering offerings. Here is an example how to achieve that:

Executing Discover with callbacks

query.discover((r,l)->{BigHelper.showOfferingDescriptions(l)});

The callback function in this example again just prints the returned offering descriptions,however usually you would provide your offering selection logic here that selects the ap-propriate offerings for your use case. The example again utilizes the functionalprogramming features introduced in Java 8. With lambdas you can express functionality


© 2017 32

without much boilerplate code. Alternatively every other instance of DiscoverRe-sponseHandler is accepted by .discover().

As a side note: Of cause you can reuse your query object for subsequent queries. Only if youwant to change something regarding the filtering you have to create anew OfferingQuery object.

3.5.4 Accessing Offerings

Before we describe how to access an offering that was retrieved from the marketplace, itmakes sense that you look at the different access concepts provided. The IOffering inter-face provides the following signatures for access:

Accessing an Offeringpublic void accessOneTime(AccessParameters parameters,

AccessResponseSuccessHandler onSuccess);

public void accessOneTime(AccessParameters parameters,AccessResponseSuccessHandler onSuccess,AccessResponseFailureHandler onFailure);

public CompletableFuture<Response> accessOneTime(AccessParameters parameters);

public IAccessFeed accessContinuously( AccessParameters parameters,Duration lifetime,FeedNotificationSuccessHandler onSuccess,FeedNotificationFailureHandler onFailure);

To access offerings, we distinguish between two types: one-time access and continuous ac-cess. One-time means that you execute an access request every time you want to get newdata. Continous is the continuous reception of data as a feed.

For one-time access, the Consumer Lib supports again different programming styles. Youcan either use callback functions for pure asynchronous access or you can usea CompletableFuture to do reactive programming or even having a blocking call. In ei-ther case, you have to provide an AccessParameters object for the access call. In includesthe parameters, which are will be passed to the platform that serves the data. Typically theyare needed to filter the output or configure the access.

Here is an example, how to access the temperature offering we retrieved earlier:


© 2017 33

Setting parameters

/* Create a hashmap to hold parameters for filtering access*/

AccessParameters accessParameters = AccessParameters.create()

.addRdfTypeValue(new RDFType(“schema:longitude”), 12.3)

.addRdfTypeValue(new RDFType(“schema:latitude”), 42.73)

.addRdfTypeValue(new RDFType(“schema:geoRadius”),1000);

/* Execute one time access and print the result */

CompletableFuture<BigResponse> response = offering.accessOneTime(accessParameters);

response.thenAccept((r) -> dashboard.display(r));

As you can see, accessing an offering can be that simple. We use the one-time access meth-od and pass the parameters object that restricts the access to the specified longitude andlatitude coordinates and a radius of 1000. Since we use accessOneTime returning aCompletableFuture, we can apply a function on the result. Here we forwards the resulton an imaginary display method, which shows the received data on a web dashboard. Notethat the response object is of the type JsonNode, which already includes the parsed re-sponse message and provides functionality for traversing the response.

3.5.5 Continuous Access of Offerings

Since we want to show the returned temperature data in real time on our dashboard, itwould be even nicer if we could access the temperature data continuously.

Here we describe how this can be done:

Access data continuouslyint seconds = 60;

System.out.println("Access continuously as sync feed every "+BigConstants.syncFeedIntervalMillis.toMillis()/1000 +"s for " + seconds + "s");

AccessFeed accessFeed = offering.accessContinuously( accessParameters,Duration.ofSeconds(60),(o,r)->System.out.println("feed result = "+r),(o,r)->System.out.println("Ups, something happened"));

You notice that the procedure is very similar to the access on a per request base. We usethe accessContinuously method of the OfferingQuery object which requires the ac-


© 2017 34

cessParameters object, a duration, a success callback and a failure callback in case some-thing went wrong. The difference is that when calling .accessCalling() that we createa feed, which requires a lifecycle management. The accessFeed object brings functionalityfor stopping (.stop()), resuming (.resume()) and getting the status of a feed subscrip-tion (.status()). which we don’t want to use now.

If you stop want to use an offering, you can unsubscribe accordingly.

Unsubscribing from an Offering

offering.unsubscribe();

Make sure to always call the .terminate() method of the consumer object before stop-ping your application in order to terminate any open network connections.

That's it! You have just learned how to use the BIG IoT Library as a data provider as well as adata consumer.


© 2017 35

4 BIG IoT Web API

During chapter 3 covers how to use the BIG IoT API with the programming interface, thischapter is about the underlying mechanisms, which are used for the communication be-tween the BIG IoT Library instances on the provider and consumer side. The underlyingmechanisms are transparent for developers. Indeed the Web API covers also the interactionof consumer and provider with the marketplace. However, these aspects are addressed indeliverable D4.1. Security aspects, such as the authentication at the marketplace, are ad-dressed in deliverable D3.3.

Section 4.1 gives a practical example to get an impression from a network perspective howofferings can be deployed. Section 4.2 discusses API aspects for constrained devices, whichforesee proxy functionality. Underlying API concepts regarding synchronicity of web servicecalls are addressed in section 4.3. The specification of the A1 interface, addressing the ac-cess of data in a per request or continuous fashion, is included in sections 4.4 and 4.5.

The Web API (also referred as A1 interface) enables all operations, which are provided by anOffering. Although it is thinkable that the end user consumes an offering directly via theWeb API instead of using the programming interface of the BIG IoT Library, it is currentlyforeseen that the Web API is exclusively consumed by the BIG IoT Consumer Lib (ConsumerLib). The motivation for that design is, that the software library brings also additional func-tionality which cannot easily be rendered by a web interface. For example the Consumer Libshall also support accounting of the data access. Further, the Consumer Lib provides datatransformation functionality. Depending on the integration mode, the degree of transfor-mation capabilities increases there.

The A1 interface place a central role in all integration modes, where direct BIG IoT support isforeseen on the platform side. Either by direct implementation of the A1 interface (Integra-tion Mode 1) or by running the provider lib in the BIG IoT Gateway Service (IntegrationModes 2 and 4). Integration Mode 3 foresees direct access on the platform, which doesn’trequire the A1 interface.

A BIG IoT Offering can be understood as an element to abstract from the underlying mecha-nisms of the resources offered by an IoT Platform. We introduce operations on BIG IoTOfferings in order to cover the different operations on an offering. These operations areaccess, feed, event and task. An offering can support one or multiple of those operations.The operation “access” addresses the sporadic retrieval of information, which is typical e.g.for reading a sensor value on a request/response basis. The operation “feed” enables thecontinuous retrieval of information. This is different to the “access” operation as the con-


© 2017 36

tinuous data access requires lifecycle management of the feed subscription. The operation“event” is the retrieval of information according to a ruleset. Data is only received if certainconditions apply. These could be for example getting a notification if a threshold is exceed-ed or if spatial data is emitted for a specific area. “Event” can be seen as an extension to the“feed” operation. In contrast to these information retrieval centric operations, the opera-tion “task” covers the sending of information towards the platform. This is required if anaction or state change shall be executed. Examples for this are switching-on a light, config-uring the sensitivity level of a noise sensor, moving a camera to a specific direction.

Since the BIG IoT ecosystem is flexible regarding the offering description, it is legal to specifyofferings supporting just one operation or even multiple operations. It is up to the platformoperator how to appropriately tailor his platform functionality into BIG IoT Offerings.

The operations “access” and “feed” are described in Sections 4.4 and 4.5. “Event” and“task” will be addressed in future deliverables.

4.1 Deployment Example

The A1 web interface is used in Integration Mode 1, 2 and 4. A deployment example formode 2 could be as in in Figure 12.


© 2017 37

Figure 12 Deployment Example

The platform "My Platform" is integrated into BIG IoT via Integration Mode 2. It has twoofferings (OfferingA and OfferingB). In Integration Mode 2 offerings are accessed via A1 in-terface, which is always implemented inside the BIG IoT Gateway Service. The platformoperator decided to run the BIG IoT Gateway Service as a web service which has the URLhttp://bigiot.myplatform.com on port 80 (TCP/IP perspective). The two offerings aremodeled as resources following a REST concept (HTTP perspective). Accordingly, the URLsare included in the platform's offering Description as described in D3.2 (e.g. end-points={uri=http://bigiot.platform.com/offeringA}) The sequence ofinteraction is depicted in Figure 13Fehler! Verweisquelle konnte nicht gefunden werden..


© 2017 38

Figure 13 Sequence Diagram Offering access in Integration Mode 2


© 2017 39

Keep in mind: hosting the gateway service under http://bigiot.myplatform.com isonly an example for a deployment. The gateway service could be also a resource underhttp://data.platform.com. For example, underhttp://data.platform.com/bigiot. The offering on the IoT platform is accessed viathe BIG IoT Gateway Service. The Gateway Service routes the call to the respective internalservice logic, which forwards the call with the correct syntax and semantics to the IoT plat-form. The transformation rules are provided by the IoT platform operator e.g. viaimplementing a delegate. Typically, there could be different operations available for an of-fering (access, feed, task, event). The operations are represented by different End Points inthe offering Description (as described in D3.2).

As seen in the example it is possible to manage multiple offerings with one deployment ofthe BIG IoT Gateway Service, but this implies also that the endpoint URI of the managedofferings have to lie in his domain/resource tree. This has direct implications for the defini-tion of a correct offering Description. The endpoint URIs have to fit:

∂ http://bigiot.myplatform.com/offeringA andhttp://bigiot.myplatform.com/myFavoriteOffering/somewhere/down/here is working

∂ http://bigiot.myplatform.com/offeringA andhttp://coolOffering.com/hereIsIt is not working, you need two runninginstances of the Gateway Service (assuming that both endpoints have different IPaddresses)

Note: The URI in the OD locates the offering on the Web. Furthermore, the operation on theoffering has to be selected. This could be accessing of data in a request/response manner(access), subscribing to data as a feed (feed) or executing a task on the offering (task). Inorder to select an operation on an offering, they are modeled as web services (A1-ACCESS,A1-FEED, A1-TASK, A1-EVENT). For convenience the URLs of the respective service opera-tions are preferably modeled as a resource below the URI of the offering (for example thiscould be http://bigiot.myplatform.com/offeringa/access). However, the offer-ing Description allows also to have separate URIs per offering operation.

The example shows also that the A1 interface is always REST-ified, which means it requiresthat it is hosted on a Webserver, which acts as an application server (e.g. Apache Tomcat).The motivation behind this is, that with integration mode 1, 2, 4 the legacy platform inter-face is hidden by a standardized interface.


© 2017 40

4.2 Proxy Support for device-level Platforms

A BIG IoT enabled Platform is an IoT platform that implements and uses the BIG IoT API (asprovider) to register offerings on a BIG IoT Marketplace, and to allow BIG IoT Services orApplications (as consumers) to gain access to the offered information or function. One ofthe integration modes that have been identified is mode 4, where the BIG IoT API is imple-mented on the device level (as provider). Because of the characteristics of such constraineddevices (limited resources, not always reachable) the device-level IoT platforms are inte-grated into the BIG IoT Ecosystem by means of a BIG IoT Proxy Service. The Proxy Serviceacts as an "always-available" proxy on behalf of the constrained devices. Figure 14 showsthe interaction in Integration Mode 4.

Moreover, in order to overcome the limitations of their constrained nature, a lite version ofthe Provider Lib shall be implemented, the Proxy (Provider) Lib, which implements a subsetof the total functionalities provided by the BIG IoT Provider Lib. More specifically, the au-thentication of the device-level IoT platforms as providers on the BIG IoT Marketplace (M1interface) and the registration of new offerings on the BIG IoT eXchange (M2 interface), willnot be provided by the Proxy Lib, since they are actually one-time operations while the de-vice-level IoT platforms may lose and regain their network connectivity periodically. The BIGIoT Proxy Service will represent the constrained platform and will be responsible for per-forming the above operations.

On the other hand, the access requests performed by the consumers will be served by theProxy (Provider) Lib directly. This means that it will act as a web server, which, in the case ofa constrained device, has some limitations, for example on the number of simultaneousrequests and the type of data access it will be able to serve (i.e. it will serve either “onetime” access or “feed”, and not both of them). As a result, when the Proxy Lib running onthe device reaches its limit on the requests it can serve, it will reject any other incomingaccess requests. In this case, the Proxy Service will take over and respond to the consumer.

The Proxy Service will queue requests until the device-level platform wakes up or recon-nects. The Proxy Lib will be responsible to fetch the operation requests that have beenqueued by the Proxy Service, in order to serve them asynchronously. Such an operation re-quest can either be a subscription to a feed (see A1-FEED) or a request for a Task function,both of which can be started and executed asynchronously by the IoT platform. Regardingthe data-access (A1-ACCESS) served by the Proxy Service: Instead of the Proxy Lib, due tounavailability of the device, the Proxy Service will first of all respond to the consumer withthe corresponding last value it has stored. It will also queue the request, so that when the


© 2017 41

IoT platform becomes available and fetches the request, to update the Proxy Service’sstored value, for future consumer’s requests.

The above operations of the Proxy Service and the Proxy Provider of the IoT platform areimplemented through the Programming Interface P3.

Figure 14 Interaction in Proxy Mode

4.3 Blocking and Non-Blocking Operations

The A1 interface includes blocking as well as non-blocking calling patterns. Depending onthe operation the call is either blocking, non-blocking or can be both.

Blocking means that the response of the web service to A1 is blocked until the result of theoperation is available. This is a typical pattern for accessing data via A1-ACCESS interface, asit is assumed that the data can be quickly read out of a database.


© 2017 42

Figure 15 Blocking Call

However, operations can also be long lasting, as e.g. the calculation of a route. In this casethe consumer doesn't want to hold the connection open until the result is available. Thismeans that there can be multiple calls on the A1-ACCESS interface to complete an opera-tion. The first call to the A1-ACCESS interface starts the operation. The response messageincludes, instead of the expected result, a reference with which on following calls the statusor respectively the result of the completed operation can be retrieved. Other utilization ex-amples for the non-blocking access pattern are creating and managing data feeds (A1-FEED),or executing a remote task (A1-TASK).


© 2017 43

Figure 16 Non-Blocking Call

4.4 Access Operation

The access of data provided by IoT platforms is an important function block of the BIG IoTAPI. Sensor data as well as aggregated data is made available on the basis of offerings. Thesupported access modes comprise the data access on a per-request base where the con-sumer requests data every time he needs it as well as the continuous access to a data feed.The continuous access requires a lifecycle management for creation and termination of thedata feed, which is addressed in section 4.5. The input parameters for both modes are de-termined by the offering Description. It is intended that the same offering can allow theaccess per-request as well as continuously.

The utilization of the data access from a consumer perspective is performed per program-ming interface, which is described in section 3.5. The underlying communication mechanismbetween the endpoints is described in this section.

Except for Integration Mode 3 the data communication is between deployed BIG IoT Librar-ies on the consumer respectively the provider’s side. Therefore, the A1-ACCESS web


© 2017 44

interface is specified which is offered by the BIG IoT Provider Lib. The underlying applicationlogic performs the translation of the semantics of the interface call to the native interface ofthe provider. Therefore, the programming interface P1 is used.

4.4.1 Specification

The A1-ACCESS interface is offered by the BIG IoT Provider Lib. It is an internal interface,which is only used by BIG IoT Libs (which might change in later revisions). Depending on theIntegration Mode, the BIG IoT Lib runs inside the BIG IoT Gateway Service or is natively inte-grated in the so called BIG IoT enabled platform. In Integration Mode 4 it runs inside the BIGIoT Proxy Service. The web service call syntax and semantics are the same for all of thosemodes where the A1-ACCESS interface is used.

The implementation dependent structure of A1-ACCESS with all necessary parameters isshown in Table 1.

HTTP GET {offering.endpoint[ACCESS].uri}

Field Type Location Required Description

Request

credentials String query yes Credentials (e.g. an API key token) au-thorizing the requesting client

encodedParameters JSON query yes Input Parameters for offering (e.g. fil-ters) specified in offering Description

Response

status String body yes Status code indicating the success orfailure of the operation

result JSON body yes Data structure encoded according tooutput parameter specification in offer-ing description

Table 1 A1-ACCESS Specification

The data access "per-request" is implemented as a HTTP GET on a URL with a fixed sub-URLscheme (e.g. http://myplatform.example.com/myapi/bigiot/access). The URL isspecified in the offering Description.

The parameter credentials include a security token, which authorizes the user. The offeringspecific parameters for data access are included in the field encodedParameters. Thesingle parameters with their semantics covered by the field encodedParameters are de-fined in the offering Description. encodedParameters is included as query parametersadded to URL. However, due to the de-facto maximal length of a URL of about 2000 charac-


© 2017 45

ter [14] - [17], it cannot be guaranteed that a GET call is successful with encodedParame-ters as a query parameter. In that case the Request shall be a HTTP Post with theencoded parameters included in the message body.

A1-ACCESS relates to the P2 interface offered by the BIG IoT Consumer Lib as it is its pen-dant as a web service interface. It is equivalent regarding offering related inputparametrization.

The parameter specification is different from offering to offering. The concrete parametriza-tion is on a key/value basis. The semantical description of the data types of singleparameters is included in the offering Description. In order to leverage a runtime access ofofferings, which have been unknown during development time, the utilization of profiledsemantical types is recommended for offering input parameters.

4.4.2 Dealing with Non-REST-like IoT platforms

Although the A1-ACCESS uses a REST-like HTTP GET call with parameters added as queryparameters to the URL all kinds of “per-request”-based endpoints are covered. This includesof course all REST-like endpoints, as well as RPC-like endpoints such as Soap. The translationto the respective endpoint is performed (in case the integration mode foresees an A1-ACCESS interface) inside the BIG IoT Provider Lib and can be adapted via the P1 Program-ming Interface.

4.5 Feed Operation

As mentioned in section 4.4 the access on data can be in a continuous fashion. Typically,such a pattern is referenced as a data stream or data feed. In the following the term “feed”is used. The BIG IoT API enables the lifecycle management for data feeds with the A1-FEEDinterface. The utilization of feeds by the consumer is performed by the P2 interface. This isaddressed in the tutorials section of the Deliverable.

The typical data access pattern is that a consumer sends a retrieval request to the data plat-form and gets the data immediately in return in the response. However, depending on theapplication scenario and the nature of the data source, the consumer wants to retrieveforthcoming data on a regular time basis or on availability.

4.5.1 Synchronous vs. asynchronous feeds

Data feeds can be either synchronous or asynchronous. The difference between both typesis that with synchronous feeds the data is transmitted to the consumer in a regular time


© 2017 46

interval independently of the timely behavior of the emitting of new values on the datasource. In contrast, asynchronous feeds foresee transmissions to the consumer whenevernew data is emitted or the data producer decides to update its feed subscribers.

Typically, synchronous feeds are good if the update rate of the data source is high and theapplication requires a lower data renewal frequency, e.g. because a data gauge in the UI hasto be updated with a new value. As the timing behavior is deterministic here, the updatecan be realized by periodic data polls initiated by the consumer. Synchronous data streamshave their benefits when server initiated data communication towards the consumer is notpossible. If there are security restrictions or the data consumer is behind a NAT then syn-chronous feeds are the only option for continuous data streams. However, in any case thereis a tradeoff between timeliness of the reception and bandwidth utilization. This is cumber-some if an application requires fast responses without having sufficient bandwidthresources.

Asynchronous data feeds are beneficial if the data emitting at the provider has an irregularevent character or in turn the notification of the feed subscriber shall be immediate (nowaiting till the next synchronized update is due). As it is not predictable when new data isavailable, new data is transmitted here to the client when it is emitted. It is optimal in termsof bandwidth utilization and realtime support. However, for asynchronous feeding the pro-ducer must be able to initiate a transmission towards the consumer. This is not alwayspossible e.g. because the consumer has no open port to send the data to or no persistentconnections are available. Firewall rules might also complicate asynchronous feeds.

Figure 17 shows the different aspects of synchronous and asynchronous feeds.


© 2017 47

Figure 17 Synchronous and asynchronous Feeds

4.5.2 Feed support in BIG IoT

The BIG IoT API defines different options for asynchronous as well as for synchronous feeds.Which ones are available for a consumer of an offering depends on restrictions on the pro-vider as well as on the consumer side. During the timing of data transmissions is always inthe control of the provider side with asynchronous feeds, synchronous feeds can be alsorealized by explicit data polls by the consumer. The latter case is the only option if feedmechanisms are not available for an offering/provider. Synchronous polling is addressed insection 4.5.3.

Arriving feed data at the BIG IoT Consumer Lib is handed over to the consumer code via thecallback method defined by the P2-FEED interface. In Integration Mode 3, transformationcode has to be available in order to transform the incoming data format in the respectivereturn format for the programming Interface.


© 2017 48

Figure 18 Feeds in Integration Mode 3

Data is transmitted to the feed subscriber when it arrives at the platform or when the plat-form decides to send it. This can be in a synchronous as well as in an asynchronous manner.Many platforms support natively such a data transmission pattern, for example per MQTTvia WebSockets. In Integration Mode 3 BIG IoT relies on the platform original feed mecha-nism (if available) for data transport (see Figure 18) or introduces (Integration Mode 2) anown feed data mechanism between Provider Lib and Consumer Lib, which transport thefeed data. The original mechanism would be then used between BIG IoT Provider Lib in theGateway Service and the legacy IoT platform (see Figure 19). The benefit of the first methodis that no repacking of feed data is necessary. The second method allows more control ofthe feed mechanism by the consumer. For example, in order to circumvent networking re-strictions e.g. by using a mandatory HTTP proxy.

Figure 19 Feeds in all Integration Modes with BIG IoT Provider Lib


© 2017 49

Other options regarding retrofitting an offering or provider not supporting asynchronous orno feeds at all are described in section 4.5.3.

4.5.3 Concepts for retrofitting Feed support

Not all data offerings come with direct native feed support by the legacy platforms. In orderto enable use cases for these offerings building on top of continuous data access, we intro-duce a concept to retrofit feed support by moving feed functionality inside the BIG IoT Libs.One approach is to enable synchronous feeds per repeated polling of the A1-ACCESS inter-face by the Consumer Lib. The other concept is to retrofit asynchronous feeds by repeatedpolling of the legacy interface by the Provider Lib running in Integration mode 2.

Retrofitting synchronous Feeds

Synchronous feeds do not necessarily require native support by the data producer. Since thedata transmission interval is fixed here, the control of the data transmission can be on theside of the consumer. That's why synchronous feed support can always be achieved by theBIG IoT Consumer Lib (see Figure 20). The feed functionality is achieved by repeated accessof the platforms A1-ACCESS interface according to a consumer specific time interval. Anoption could be to select whether all new values are polled or just the latest.

Figure 20 Retrofitting synchronous Feeds

Retrofitting asynchronous Feed support

Actually asynchronous feeds need support from the data provider side. If this is not fore-seen, it can be partly enabled by functionality on the provider side (see Figure 21).


© 2017 50

If a platform doesn't provide native feed support out-of-the-box, a kind of asynchronousfeed can be enabled by the BIG IoT Provider Lib. The mechanism is as follows: The callbackfunction inside the BIG IoT Provider Lib polls for new data regularly in a high interval. Ifpolled values change they are transmitted asynchronously to the feed subscribers, e.g. byusing a WebSocket connection. Although this is also a kind of a synchronous feed, it takesplace on the premises of the provider, which means that bandwidth resources are suffi-ciently high and the polling interval is optimal for the data source. For consumers thisrealization pattern is transparent.

Figure 21 Retrofitting asynchronous Feeds

4.5.4 Lifecycle Management

The creation and termination of feeds is a side action, which is necessary when enablingcontinuous access. A1-FEED introduces a web interface for feed lifecycle management in allIntegration Modes where the Provider Lib is required. In turn the P2 interface provides pro-gramming functions for lifecycle management for the consumer in all Integration Modes. Itprovides mechanisms for lifecycle operations like “subscribe”, “unsubscribe” and feed “sta-tus” information retrieval. It is used for all kinds of underlying mechanisms realizing thetransport of the feed data. The handling is always the same, independently of the Integra-tion Mode or whether the feed is realized synchronously or asynchronously.

The specification for a feed interface tries to be as much transparent to the consumer aspossible in order to hide underlying mechanisms. However due to different constraints ofproviding feed functionality the consumer has to be involved in the setup of a feed subscrip-tion. E.g. he has to decide when to start and when to end the transmissions by a


© 2017 51

subscription or respectively an unsubscription. If it applies it is also important for the feeddata provider to know when to stop sending.

The feed mechanisms of the legacy IoT platforms are masked thru BIG IoT. The Big IoT Libterminates existing feed mechanisms. The handover of feed data to the consumer's busi-ness logic happens inside the callback method of the BIG IoT Consumer. The callbackmethod is an offering dependent implementation similar to the callback methods used forthe access interface. The callback method implements the P2 programming interface pro-vided by the BIG IoT Consumer Lib.

Table 2 includes the required parameters for the A1-FEED interface. It is agnostic tothe concrete interface protocol binding. Concrete implementations by Java, JavaScript orweb services use the same semantics. Lifecycle management requires different parametersets for each phase, A1-FEED has a selector parameter for subscription, unsubscription, sta-tus. The implementation of the interface has to switch between the lifecycle phaseaccordingly with e.g. with a parameter selector.

Direction Field Type Required Description

SELECTOR "subscription"

Request offeringId String yes Identifies a specific offering on a provider. ThisofferingId could be the reference to a dedicateddata feed or to a normal data access offering. In thelatter case the feed mechanism is synchronous

credentials String no Credentials (e.g. an API key token) authorizing therequesting client

lifetime Integer yes Seconds defining the lifetime of the subscription

The following parameters are equivalent to A1-ACCESS. Not every feed offering might allow furtherparametrization.

encodedParame-ters

JSON no Function Parameters for offering (e.g. filters). Canbe also feed mechanism parameters as callbackURL if IoT platform feed mechanism requires (e.g.for OGC SES)

Response successCode String yes Status of the operation

subscriptionId String yes Reference to subscription

expirationDate Date yes Expiration date in ISO 8601 (e.g. 2016-10-19T11:25:59+02:00)

feedEndpoint URL yes Feed endpoint e.g. the URL for a WebSocket

SELECTOR "unsubscription"


© 2017 52

Request subscriptionId String yes Reference to subscription


SELECTOR "list"

Request verbose Boole-an

yes Enables verbose subscription listing


array of

subscriptionId String yes Reference to subscription

expirationDate Date no Expiration date in ISO 8601 (e.g. 2016-10-19T11:25:59+02:00)

type String no Type of the feed mechanism. Can be∂ sync for synchronous feeds∂ async for asynchronous feeds∂ external for the utilization of an external mes-

saging system, as iOS (push) notification

offeringDescription JSON no Offering description serialized in JSON

Table 2 A1-FEED Specification


© 2017 53

5 Conclusion & Outlook

This deliverable describes comprehensively the first release of the BIG IoT API, contributingto MS1. It already comprises a broad range of functionalities, such as handling data accessor feeds. Based on this first release, we will iteratively add further functionalities to the APIin the coming months. This will result in the release 2 (contributing to MS3) and release 3(contributing to MS5). In between those official releases, we conduct an agile development,which provides intermediary versions of the API to dependent tasks, such as the develop-ment of services and applications in WP5.

The BIG IoT API can be seen from 2 perspectives, as (1) a Web API and (2) a ProgrammingAPI. Both perspectives on the BIG IoT API have been described in this document. The de-tailed technical specification of the Web API in section 4 comprises descriptions of thedifferent interactions realized by the API as well as their implementation in concrete com-munication protocols. The description of the Programming API (section 3) will be publishedas online documentation in a tutorial style in order to attract new developers who contrib-ute services, platforms or applications. The Programming API is provided in this first releasein Java, but further implementations in other languages (e.g., Python and JavaScript) areplanned.

The design of the BIG IoT API follows some fundamental principles as guideline for the de-velopment. A key principle underlying our work is “description before adaptation”. I.e., wedo not define all parameters of the API in advance, as it is often done by standards such asOGC SOS. Instead, the parameterization of API calls is widely kept generic, by allowing todefine the type and value of input and output data parameters using semantic concepts.The input and output data parameters accepted by a platform or service are defined by therespective offering in its offering Description (as defined in D3.2). Hence, the description ofthe resource becomes a more important role than in other APIs, which are usually imple-mented through plain adaptation. The main advantage of this approach is the very highdegree of flexibility gained. An unrestricted number of semantic types for input and outputdata parameters can be supported through this approach. Thus, we do not limit the API to aparticular domain or application.

The generic design of the BIG IoT API demands clear semantic (and syntactic) descriptions ofthe parameters. Thereby, in order to ignite an IoT ecosystem it is crucial to select or definean initial set of concepts allowed to be used and which developers can rely on. Here, thework of Task 4.2 on defining an application domain model is key. The resulting deliverableD4.2 defines a narrow, agreed vocabulary to start the BIG IoT ecosystem. This narrow vo-cabulary can then be further extended over time and with the growing of the ecosystem.


© 2017 54

In the future, the missing functionalities of the BIG IoT API need to be defined and imple-mented in the SDK. This includes tasking, i.e., the transmission of commands to actors (e.g.,sending a message to control a robot arm). Also important is to support eventing, i.e., ena-bling client to subscribe to and receive events according to a defined set of rules related toan offering.

More extensive research will be invested into further facilitating the integration of plat-forms and services into the ecosystem. We are envisaging a very easy and partiallyautomated mechanism to adapt and integrate existing platforms by generating gatewayservices based on descriptions.


© 2017 55

Figures and Tables

Figures

Figure 1 Relation of deliverables ........................................................................................... 9Figure 2 Core Concepts ....................................................................................................... 12Figure 3 Building Block View on BIG IoT Architecture .......................................................... 14Figure 4 Install Buildship Gradle Integration ........................................................................ 20Figure 5 Eclipse Neon with fresh, empty workspace ............................................................ 21Figure 6 Importing a Gradle Project ..................................................................................... 22Figure 7 Import Gradle Project Wizard ................................................................................ 22Figure 8 Import Gradle Project Wizard - Setting Project Root Directory ............................... 23Figure 9 Retrieving Dependencies via Gradle....................................................................... 23Figure 10 Question during Gradle Build ............................................................................... 24Figure 11 Having the BIG IoT API imported in Eclipse .......................................................... 24Figure 12 Deployment Example ........................................................................................... 37Figure 13 Sequence Diagram Offering access in Integration Mode 2 ................................... 38Figure 14 Interaction in Proxy Mode ................................................................................... 41Figure 15 Blocking Call ........................................................................................................ 42Figure 16 Non-Blocking Call ................................................................................................. 43Figure 17 Synchronous and asynchronous Feeds ................................................................. 47Figure 18 Feeds in Integration Mode 3 ................................................................................ 48Figure 19 Feeds in all Integration Modes with BIG IoT Provider Lib ..................................... 48Figure 20 Retrofitting synchronous Feeds ........................................................................... 49Figure 21 Retrofitting asynchronous Feeds.......................................................................... 50Figure 22 Focus Consumer Class .......................................................................................... 57Figure 23 Focus OfferingQuery Class ................................................................................... 58Figure 24 Focus Offering Class ............................................................................................. 59Figure 25 Focus Provider Class ............................................................................................ 60

Tables

Table 1 A1-ACCESS Specification ......................................................................................... 44Table 2 A1-FEED Specification ............................................................................................. 52


© 2017 56

References

[1] https://evrythng.com

[2] https://www.thingworx.com

[3] https://www.xively.com

[4] https://www.yaler.net

[5] https://www.bosch-si.com/de/produkte/bosch-iot-suite/iot-platform/vorteile.html

[6] https://www.smartdatanet.it

[7] Bröring, A., S. Schmid, C.-K.Schindhelm, A. Khelil, S. Kaebisch, D. Kramer,D. Le Phuoc, J. Mitic, D. Anicic, E. Teniente (2017, forthcoming): EnablingIoT Ecosystems through Platform Interoperability. IEEE Software, specialissue on: Software Engineering for the Internet of Things.

[8] J. Manyika, M. Chui, P. Bisson, J. Woetzel, R. Dobbs, J. Bughin and D.Aharon, "The Internet of Things: Mapping the Value Beyond the Hype,"McKinsey Global Institute, 2015.

[9] https://tools.ietf.org/html/rfc7252

[10] https://www.oasis-open.org/committees/mqtt

[11] http://technical.openmobilealliance.org/Technical/technical-information/release-program/current-releases/oma-lightweightm2m-v1-0

[12] http://www.opengeospatial.org/ogc/markets-technologies/swe

[13] http://www.onem2m.org

[14] http://tools.ietf.org/html/rfc7230#section-3.1.1

[15] https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.2.1

[16] https://support.microsoft.com/en-us/kb/208427

[17] https://boutell.com/newfaq/misc/urllength.html


© 2017 57

Appendix A UML Class Diagrams

Figure 22 Focus Consumer Class


© 2017 58

Figure 23 Focus OfferingQuery Class


© 2017 59

Figure 24 Focus Offering Class


© 2017 60

Figure 25 Focus Provider Class


© 2017 61

Appendix B BIG IoT API Documentation

The documentation is generated as a JavaDoc and follows this page.

BIG IoT API Reference

Deliverable 3.1.a: BIG IoT API Design - First ReleaseAnnex B

Package

org.bigiot.lib

B2

org.bigiot.libClass BigIotAPIjava.lang.Object | +-org.bigiot.lib.BigIotAPI

public class BigIotAPIextends Object

This class is the base class of the BIG IoT API, it brings authentication functionality.

Direct Known Subclasses:Consumer, Provider

Fields

clientIdprotected java.lang.String clientId

marketplaceUriprotected java.lang.String marketplaceUri

Constructors

BigIotAPIpublic BigIotAPI(String clientId, String marketplaceUri)

Methods

authenticatepublic void authenticate(String marketplaceApiKey, String consumerCertFilename)

Authenticates the Consumer or Provider instance on the Marketplace.

Parameters:marketplaceApiKey - API Key for authentication at the marketplaceconsumerCertFilename - (optional)

terminatepublic void terminate()

B3

org.bigiot.lib.BigIotAPI

(continued from last page)

Terminate the Consumer or Provider instance.

B4

org.bigiot.lib.BigIotAPI

org.bigiot.libClass Consumerjava.lang.Object | +- | +-org.bigiot.lib.Consumer

public class Consumerextends BigIotAPIimplements IConsumer

This class covers the basic function set, which is consumer lib specific. Consumer foresees discover operations for OfferingDescriptions on the marketplace. The interface functions are all non-blocking either by returning a completable future or passingdelegate objects for callback. CompletableFuture allows stream processing and reactive operations on the Type of the nestedObject in the CompletableFuture. Calling .get() returns the nested object in a synchronized manner. The call blocks until theoperation is finished. Alternatively method calls foresee callback via delegate objects. The relevant delegate types are defined asfunctional interfaces, which allow lambda expression.

All Implemented Interfaces:IConsumer

Constructors

Consumerpublic Consumer(String consumerId, String marketplaceUri)

Instantiates the Consumer instance

Parameters:consumerId - Identifier of the Consumer instance - as provided by the Marketplace.marketplaceUri - URI to the Marketplace API (e.g. https://marketplace.big-iot.eu:8080/)

Methods

discoverpublic CompletableFuture discover(IOfferingQuery offeringQuery)

Performs a marketplace discovery for Offerings matching the implementation as Offering Query. The call is non-blockingas it returns the list of Offering Descriptions as a completable future.

Parameters:offeringQuery - Offering query used for discover

Returns:List of found Offering Descriptions matching Offering Query as CompletableFuture.

B5

org.bigiot.lib.Consumer


discoverpublic void discover(IOfferingQuery offeringQuery, DiscoverResponseHandler onSuccess, DiscoverResponseErrorHandler onFailure)

Performs a marketplace discovery for Offerings matching the implementation as Offering Query. The call is non-blocking.On successful execution, onSuccess receives the result via executing its callback method. On failure the respectivecallback method of onFailure is called.

Parameters:offeringQuery - Offering query used for discoveronSuccess - Delegate object for processing successful discoveriesonFailure - Delegate object for failing discoveries

discoverpublic void discover(IOfferingQuery offeringQuery, DiscoverResponseHandler onSuccess)

Performs a marketplace discovery for Offerings matching the implementation as Offering Query. The call is non-blocking.On successful execution, onSuccess receives the result via executing its callback method. On failure nothing is done.

Parameters:offeringQuery - Offering query used for discoveronSuccess - Delegate object for processing successful discoveries

B6

org.bigiot.lib.Consumer

org.bigiot.libInterface IConsumer

public interface IConsumerextends

Interface for the BIG IoT Consumer Lib. IConsumer foresees discover operations for Offering Descriptions on the marketplace.The interface functions are all non-blocking either by returning a completable future or passing delegate objects for callback.CompletableFuture allows stream processing and reactive operations on the Type of the nested Object in the CompletableFuture.Calling .get() returns the nested object in a synchronized manner. The call blocks until the operation is finished. Alternativelymethod calls foresee callback via delegate objects. The relevant delegate types are defined as functional interfaces, which allowlambda expression.

All Known Implementing Classes:Consumer

Methods

authenticatepublic abstract void authenticate(String marketplaceApiKey, String consumerCertFilename)

Authenticates the user at the marketplace.

Parameters:marketplaceApiKey - API KeyconsumerCertFilename - Filename of the private certificate for authorization of the consumer

discoverpublic abstract CompletableFuture discover(IOfferingQuery offeringQuery)

Performs a marketplace discovery for Offerings matching the implementation as Offering Query. The call is non-blockingas it returns the list of Offering Descriptions as a completable future.

Parameters:offeringQuery - Offering query used for discover

Returns:List of found Offering Descriptions matching Offering Query as CompletableFuture.

discoverpublic abstract void discover(IOfferingQuery offeringQuery, DiscoverResponseHandler onSuccess, DiscoverResponseErrorHandler onFailure)

Performs a marketplace discovery for Offerings matching the implementation as Offering Query. The call is non-blocking.On successful execution, onSuccess receives the result via executing its callback method. On failure the respectivecallback method of onFailure is called.


B7

org.bigiot.lib.IConsumer


onFailure - Delegate object for failing discoveries

discoverpublic abstract void discover(IOfferingQuery offeringQuery, DiscoverResponseHandler onSuccess)

Performs a marketplace discovery for Offerings matching the implementation as Offering Query. The call is non-blocking.On successful execution, onSuccess receives the result via executing its callback method. On failure nothing is done.


terminatepublic abstract void terminate()

Terminates Consumer session on marketplace

B8

org.bigiot.lib.IConsumer

org.bigiot.libInterface IProvider

public interface IProviderextends

All Known Implementing Classes:Provider

Methods

authenticatepublic abstract void authenticate(String providerApiKey, String certificateFile)

authenticates the Provider instance on the Marketplace based on the API Key and an optional certificate file.

Parameters:clientId

certificateFile - (optional)

initializepublic abstract void initialize(String accessDomainName, int accessPort)

initializes the Provider instance and configures the access interface parameters.

Parameters:accessDomainName

accessPort

registerpublic abstract String register(OfferingDescription offeringDescription, AccessRequestHandler accessRequestHandler)

registers an OfferingDescription on the Marketplace and initates the Access Interface (A1) for that offering. The ProviderLib will call the accessRequestHandler upon receiving an access request.

Parameters:offeringDescription

accessRequestHandler

Returns:offeringId

registerpublic abstract String register(String offeringId, AccessRequestHandler accessRequestHandler)

B9

org.bigiot.lib.IProvider


registers an OfferingDescription on the Marketplace based on an OfferingId. It is assumed here that theOfferingDescription has already been created using the WebPortal of the Marketplace. This function also initates theAccess Interface (A1) for that offering. The Provider Lib will call the accessRequestHandler upon receiving an accesrequest.

Parameters:offeringId

accessRequestHandler

Returns:offeringId

deregisterpublic abstract void deregister(OfferingDescription offeringDescription)

deregisters an OfferingDescripton on the Marketplace This function will also deactivate the Access Interface (A1) for thisoffering.


deregisterpublic abstract void deregister(String offeringId)

deregisters an OfferingDescripton on the Marketplace based on the OfferingID. This function will also deactivate theAccess Interface (A1) for this offering.


terminatepublic abstract void terminate()

Terminate the Provider instance. This will deregister all OfferingDescriptions and stop all Access Interface (A1) terminatethe Access Interfaces.

B10

org.bigiot.lib.IProvider

org.bigiot.libClass Providerjava.lang.Object | +- | +-org.bigiot.lib.Provider

public class Providerextends BigIotAPIimplements IProvider

All Implemented Interfaces:IProvider

Fields

offeringsprotected java.util.Map offerings

offeringCallbacksprotected java.util.Map offeringCallbacks

accessDomainNameprotected java.lang.String accessDomainName

accessPortprotected int accessPort

ACCESS_PATHprotected static final java.lang.String ACCESS_PATH

Constant value: /bigiot/access

Constructors

B11

org.bigiot.lib.Provider


Providerpublic Provider(String providerId, String marketplaceUri)

Instantiates the Provider instance

Parameters:providerId - Identifier of the Provider instance - as provided by the Marketplace.marketplaceUri - URI to the Marketplace API (e.g. https://marketplace.big-iot.eu:8080/)

Methods

initializepublic void initialize(String accessDomainName, int accessPort)

Initialization function Perform Provider specific initializations, e.g. start server thread to listen for access requests (A1)

terminatepublic void terminate()

Terminate function Perform Provider specific initializations, e.g. start server thread to listen for access requests (A1)

registerpublic String register(OfferingDescription offeringDescription, AccessRequestHandler accessRequestHandler)

Registers an offering Steps: - Transform offering into the format required by the marketplace registration API - Makeregistration API call to marketplace and register offering - If registration was successful, add offering to local list ofregistered offerings - Add a unique ID to the offering and return to the caller - Ensure that the local access server (for A1)is running and configured to listen on the registered offering EndPoint

registerpublic String register(String offeringId, AccessRequestHandler accessRequestHandler)

Register an Offering by ID. Steps: - Make registration API call to marketplace and register offering - If registration wassuccessful, add offering to local list of registered offerings - Ensure that the local access server (for A1) is running andconfigured to listen on the registered offering EndPoint

deregisterpublic void deregister(OfferingDescription offeringDescription)

De-registers an offering Steps: - Check if offering has a unique ID and if it is still in the list of active offerings - If so, removeit from the local list of active offerings - Make de-registration API call towards marketplace to de-register this offering

deregisterpublic void deregister(String offeringId)

B12

org.bigiot.lib.Provider

org.bigiot.libClass Provider.OfferingCallbackjava.lang.Object | +-org.bigiot.lib.Provider.OfferingCallback

public class Provider.OfferingCallbackextends Object

Helper class to maintain a list of routes and callbacks

Fields

offeringDescriptionpublic org.bigiot.lib.offering.OfferingDescriptionData offeringDescription

accessRequestHandlerpublic org.bigiot.lib.handlers.AccessRequestHandler accessRequestHandler

Constructors

OfferingCallbackpublic OfferingCallback(OfferingDescriptionData offeringDescription, AccessRequestHandler accessRequestHandler)

B13

org.bigiot.lib.Provider.OfferingCallback

Package

org.bigiot.lib.examples

B14

org.bigiot.lib.examplesClass ExampleConsumerjava.lang.Object | +-org.bigiot.lib.examples.ExampleConsumer

public class ExampleConsumerextends Object

Example for using BIG IoT API as a consumer. This example corresponds with ExampleProviderNew.java

Constructors

ExampleConsumerpublic ExampleConsumer()

Methods

mainpublic static void main(String[] args) throws InterruptedException, ExecutionException

B15

org.bigiot.lib.examples.ExampleConsumer

org.bigiot.lib.examplesClass ExampleProviderjava.lang.Object | +-org.bigiot.lib.examples.ExampleProvider

public class ExampleProviderextends Object

Example for using BIG IoT API as a provider. This example corresponds with ExampleConsumerNew.java

Constructors

ExampleProviderpublic ExampleProvider()

Methods

mainpublic static void main(String[] args) throws InterruptedException

B16

org.bigiot.lib.examples.ExampleProvider

org.bigiot.lib.examplesClass ParameterEncoderTestjava.lang.Object | +-org.bigiot.lib.examples.ParameterEncoderTest

public class ParameterEncoderTestextends Object

Constructors

ParameterEncoderTestpublic ParameterEncoderTest()

Methods

createUserpublic static ParameterEncoderTest.User createUser()

mainpublic static void main(String[] args)

B17

org.bigiot.lib.examples.ParameterEncoderTest

org.bigiot.lib.examplesClass ParameterEncoderTest.Addressjava.lang.Object | +-org.bigiot.lib.examples.ParameterEncoderTest.Address

public static class ParameterEncoderTest.Addressextends Object

Fields

streetpublic java.lang.String street

citypublic java.lang.String city

Constructors

Addresspublic Address()

Addresspublic Address(String street, String city)

Methods

toStringpublic String toString()

getStreetpublic String getStreet()

B18

org.bigiot.lib.examples.ParameterEncoderTest.Address

setStreetpublic void setStreet(String street)

getCitypublic String getCity()

setCitypublic void setCity(String city)

B19

org.bigiot.lib.examples.ParameterEncoderTest.Address

org.bigiot.lib.examplesClass ParameterEncoderTest.Productjava.lang.Object | +-org.bigiot.lib.examples.ParameterEncoderTest.Product

public static class ParameterEncoderTest.Productextends Object

Fields

namepublic java.lang.String name

Constructors

Productpublic Product()

Productpublic Product(String name, double version)

Methods


getNamepublic String getName()

setNamepublic void setName(String name)

B20

org.bigiot.lib.examples.ParameterEncoderTest.Product

getVersionpublic double getVersion()

setVersionpublic void setVersion(double version)

B21

org.bigiot.lib.examples.ParameterEncoderTest.Product

org.bigiot.lib.examplesClass ParameterEncoderTest.Userjava.lang.Object | +-org.bigiot.lib.examples.ParameterEncoderTest.User

public static class ParameterEncoderTest.Userextends Object

Fields


birthdaypublic java.util.Date birthday

addresspublic org.bigiot.lib.examples.ParameterEncoderTest.Address address

productspublic java.util.LinkedList products

nicknamespublic java.lang.String nicknames

Constructors

Userpublic User(String name, Date birthday, ParameterEncoderTest.Address address, LinkedList products, String[] nicknames)

B22

org.bigiot.lib.examples.ParameterEncoderTest.User

Userpublic User()

Methods


B23

org.bigiot.lib.examples.ParameterEncoderTest.User

Package

org.bigiot.lib.feed

B24

org.bigiot.lib.feedClass AccessFeedjava.lang.Object | +-org.bigiot.lib.feed.AccessFeed

public abstract class AccessFeedextends Objectimplements IAccessFeed

AccessFeed represents data feed and brings functionality for lifecycle management

All Implemented Interfaces:IAccessFeed

Direct Known Subclasses:AccessFeedAsync, AccessFeedSync

Fields

expirationDateprotected java.util.Date expirationDate

onSuccessprotected org.bigiot.lib.handlers.FeedNotificationSuccessHandler onSuccess

onFailureprotected org.bigiot.lib.handlers.FeedNotificationFailureHandler onFailure

Constructors

AccessFeedpublic AccessFeed(Date expirationDate, FeedNotificationSuccessHandler onSuccess, FeedNotificationFailureHandler onFailure)

Methods

resumepublic abstract void resume()

B25

org.bigiot.lib.feed.AccessFeed


Resumes a stopped data feed

stoppublic abstract void stop()

Explicitly stop data reception

setLifetimepublic abstract void setLifetime(java.time.Duration lifetime)

Set lifetime of data feed with duration. After that the feed is automatically terminated.

getStatuspublic abstract FeedStatus getStatus()

Returns status of data feed

getExpirationDatepublic Date getExpirationDate()

Expiration data of data feed

B26

org.bigiot.lib.feed.AccessFeed

org.bigiot.lib.feedClass AccessFeedAsyncjava.lang.Object | +- | +-org.bigiot.lib.feed.AccessFeedAsync

public class AccessFeedAsyncextends AccessFeed

Implementation for asynchronous feed support. AccessFeedAsync represents data feed and brings functionality for lifecyclemanagement


Constructors

AccessFeedAsyncpublic AccessFeedAsync(Date expirationDate, FeedNotificationSuccessHandler onSuccess, FeedNotificationFailureHandler onFailure)

Methods

stoppublic void stop()


getStatuspublic FeedStatus getStatus()

Returns status of Feed

setLifetimepublic void setLifetime(java.time.Duration lifetime)

Set lifetime of feed with duration. After that the feed is automatically terminated.

resumepublic void resume()


B27

org.bigiot.lib.feed.AccessFeedAsync

org.bigiot.lib.feedClass AccessFeedSyncjava.lang.Object | +- | +-org.bigiot.lib.feed.AccessFeedSync

public class AccessFeedSyncextends AccessFeed

Implementation for synchronous feed support


Constructors

AccessFeedSyncpublic AccessFeedSync(ScheduledExecutorService executor, Offering offering, AccessParameters accessParameters, Date expirationDate, java.time.Duration intervalMillis, FeedNotificationSuccessHandler onSuccess, FeedNotificationFailureHandler onFailure)

Methods

stoppublic void stop()


getStatuspublic FeedStatus getStatus()


setLifetimepublic void setLifetime(java.time.Duration lifetime)

Set lifetime of feed with duration. After that the feed is automatically terminated.

resumepublic void resume()


B28

org.bigiot.lib.feed.AccessFeedSync

org.bigiot.lib.feedClass FeedStatusjava.lang.Object | +-org.bigiot.lib.feed.FeedStatus

public class FeedStatusextends Object

FeedStatus represents the status of a data feed

Constructors

FeedStatuspublic FeedStatus(boolean terminated, Date expirationDate)

B29

org.bigiot.lib.feed.FeedStatus

org.bigiot.lib.feedInterface IAccessFeed

public interface IAccessFeedextends

Interface for lifecycle operations on data feeds

All Known Implementing Classes:AccessFeed

Methods

resumepublic abstract void resume()


stoppublic abstract void stop()


setLifetimepublic abstract void setLifetime(java.time.Duration lifetime)

Set lifetime of data feed with duration. After that the feed is automatically terminated.

getExpirationDatepublic abstract Date getExpirationDate()

Expiration data of data feed

getStatuspublic abstract FeedStatus getStatus()


B30

org.bigiot.lib.feed.IAccessFeed

Package

org.bigiot.lib.handlers

B31

org.bigiot.lib.handlersInterface AccessRequestHandler

public interface AccessRequestHandlerextends

Handles incoming Offering requests

Methods

processRequestHandlerpublic abstract String processRequestHandler(OfferingDescription offeringDescription, Map inputData)

Process incoming Offering requests

Parameters:offeringDescription - Reference to OfferingDescriptioninputData - Input parameter list

Returns:

B32

org.bigiot.lib.handlers.AccessRequestHandler

org.bigiot.lib.handlersInterface AccessResponseFailureHandler

public interface AccessResponseFailureHandlerextends

Handles access failure

Methods

processResponseOnFailurepublic abstract void processResponseOnFailure(IOffering reference, BigResponse response)

Processes failure on Offering access

Parameters:reference - Reference to offeringresponse - Response from Offering

B33

org.bigiot.lib.handlers.AccessResponseFailureHandler

org.bigiot.lib.handlersInterface AccessResponseSuccessHandler

public interface AccessResponseSuccessHandlerextends

Handles successful data reception.

Methods

processResponseOnSuccesspublic abstract void processResponseOnSuccess(IOffering reference, BigResponse response)

Process incoming responses of an Offering access

Parameters:reference - Reference to offeringresponse - Response from Offering access

B34

org.bigiot.lib.handlers.AccessResponseSuccessHandler

org.bigiot.lib.handlersClass DiscoverFailureExceptionjava.lang.Object | +- | +- | +-org.bigiot.lib.handlers.DiscoverFailureException

public class DiscoverFailureExceptionextends Exception

Exception for DiscoveryFailure

All Implemented Interfaces:Serializable

Constructors

DiscoverFailureExceptionpublic DiscoverFailureException()

B35

org.bigiot.lib.handlers.DiscoverFailureException

org.bigiot.lib.handlersInterface DiscoverResponseErrorHandler

public interface DiscoverResponseErrorHandlerextends

Handles discovery error

Methods

processResponsepublic abstract void processResponse(IOfferingQuery reference, DiscoverFailureException failure)

Processes an discovery failure

Parameters:reference - Reference to Offering Queryfailure - Failure object

B36

org.bigiot.lib.handlers.DiscoverResponseErrorHandler

org.bigiot.lib.handlersInterface DiscoverResponseHandler

public interface DiscoverResponseHandlerextends

Handles successful discoveries on Marketplace

Methods

processResponsepublic abstract void processResponse(IOfferingQuery reference, List offeringDescriptions)

Processes incoming Offering Descriptions

Parameters:reference - Reference to Offering QueryofferingDescriptions - List of Offering Descriptions

B37

org.bigiot.lib.handlers.DiscoverResponseHandler

org.bigiot.lib.handlersClass FeedFailureExceptionjava.lang.Object | +-org.bigiot.lib.handlers.FeedFailureException

public class FeedFailureExceptionextends Object

Feed Failure Exception

Constructors

FeedFailureExceptionpublic FeedFailureException()

B38

org.bigiot.lib.handlers.FeedFailureException

org.bigiot.lib.handlersInterface FeedNotificationFailureHandler

public interface FeedNotificationFailureHandlerextends

Handles feed failures

Methods

processNotificationOnFailurepublic abstract void processNotificationOnFailure(IAccessFeed reference, FeedFailureException failure)

Process feed failure

Parameters:reference - Reference to AccessFeedfailure - Failure object

B39

org.bigiot.lib.handlers.FeedNotificationFailureHandler

org.bigiot.lib.handlersInterface FeedNotificationSuccessHandler

public interface FeedNotificationSuccessHandlerextends

Handles successful feed notifications

Methods

processNotificationOnSuccesspublic abstract void processNotificationOnSuccess(IAccessFeed reference, BigResponse response)

Process incoming feed data

Parameters:reference - Reference to Feedresponse - Incoming Data

B40

org.bigiot.lib.handlers.FeedNotificationSuccessHandler

Package

org.bigiot.lib.misc

B41

org.bigiot.lib.miscClass BigConstantsjava.lang.Object | +-org.bigiot.lib.misc.BigConstants

public class BigConstantsextends Object

Fields

discoverySubUrlpublic static java.lang.String discoverySubUrl

syncFeedIntervalMillispublic static java.time.Duration syncFeedIntervalMillis

Constructors

BigConstantspublic BigConstants()

B42

org.bigiot.lib.misc.BigConstants

org.bigiot.lib.miscClass BigHelperjava.lang.Object | +-org.bigiot.lib.misc.BigHelper

public class BigHelperextends Object

Fields

df00public static final java.text.DecimalFormat df00



df0_0000public static final java.text.DecimalFormat df0_0000

Constructors

BigHelperpublic BigHelper()

Methods

formatStringpublic static String formatString(String format, Object[] args)

Convenience function for String.format() using US locale

B43

org.bigiot.lib.misc.BigHelper

extractOfferingDescriptionsFromHttpResponsepublic static List extractOfferingDescriptionsFromHttpResponse(HttpResponse response)

Maps Offering Descriptions in JSON format to OfferingDescription

Parameters:response

Returns:List of OfferingDescription

showOfferingDescriptionspublic static List showOfferingDescriptions(List l)

Pretty print of list of Offering Description

Parameters:l

Returns:

roundpublic static double round(double d, int i)

B44

org.bigiot.lib.misc.BigHelper

org.bigiot.lib.miscClass BigHttpSupportjava.lang.Object | +-org.bigiot.lib.misc.BigHttpSupport

public class BigHttpSupportextends Object

Support for HTTP based access of web resources with static and blocking methods. Utilizes CompletableFuture for return types.

Constructors

BigHttpSupportpublic BigHttpSupport()

Methods

getpublic static CompletableFuture get(String url)

Executes HTTP GET on URL

Parameters:url - URL as String

Returns:HttpResponse as CompletableFuture

getpublic static CompletableFuture get(String url, Map addedHeaders)

Executes HTTP GET on URL with Headers

Parameters:url - URL as String


postpublic static CompletableFuture post(String url, StringEntity requestEntity)

Executes HTTP POST on URL

Parameters:

B45

org.bigiot.lib.misc.BigHttpSupport


url - URL as StringrequestEntity - Body


postpublic static CompletableFuture post(String url, StringEntity requestEntity, Map addedHeaders)

Executes HTTP POST on URL with Headers

Parameters:url - URL as StringrequestEntity - BodyaddedHeaders - HTTP headers


putpublic static CompletableFuture put(String url, StringEntity requestEntity)

Executes HTTP PUT on URL

Parameters:url - URL as StringrequestEntity - Body


putpublic static CompletableFuture put(String url, StringEntity requestEntity, Map addedHeaders)

Executes HTTP PUT on URL with Headers

Parameters:url - URL as StringrequestEntity - BodyaddedHeaders - HTTP headers


deletepublic static CompletableFuture delete(String url)

Executes HTTP DELETE on URL

Parameters:

B46



url - URL as String


deletepublic static CompletableFuture delete(String url, Map addedHeaders)

Executes HTTP DELETE on URL with Headers

Parameters:url - URL as StringaddedHeaders - HTTP headers


B47


org.bigiot.lib.miscClass BigRandomjava.lang.Object | +-org.bigiot.lib.misc.BigRandom

public class BigRandomextends Object

Convenience functions for random number generation based on Apache Commons Math

Fields

testpublic static final java.lang.String test

Constant value: TEST

Constructors

BigRandompublic BigRandom()

Methods

getNextUniformpublic static double getNextUniform(double lower, double upper)

Generates a double in an interval with uniform distribution

Parameters:lower

upper

Returns:

getNextUniformpublic static long getNextUniform(long lower, long upper)

Generates a long in an interval with uniform distribution

Parameters:lower

upper

B48

org.bigiot.lib.misc.BigRandom


Returns:

nextBooleanpublic static boolean nextBoolean()

Generates a random boolean

Returns:

getRandomPositionInsidepublic static Location getRandomPositionInside(Area area)

Generates a random location in an spatial area.

Parameters:area

Returns:

getRandomPositionInsidepublic static Location getRandomPositionInside(Area area, int digits)

Generates a random location in an spatial area with a fixed precision

Parameters:area

digits

Returns:

B49

org.bigiot.lib.misc.BigRandom

org.bigiot.lib.miscClass FilloutTemplatejava.lang.Object | +-org.bigiot.lib.misc.FilloutTemplate

public class FilloutTemplateextends Object

Enables template based message generation with keywords

Direct Known Subclasses:OfferingQueryPriceTemplate, OfferingQueryRequestTemplate

Constructors

FilloutTemplatepublic FilloutTemplate(String fileName, HashMap kvp)

Constructor with a filename for template and hashmap for keyword and value combinations

Parameters:fileName

kvp

Methods

fillOutpublic String fillOut()

Fills out template and returns it as a string

Returns:

B50

org.bigiot.lib.misc.FilloutTemplate

Package

org.bigiot.lib.model

B51

org.bigiot.lib.modelClass Areajava.lang.Object | +-org.bigiot.lib.model.Area

public class Areaextends Object

Geographical area based on Location

Constructors

Areapublic Area(Location firstCorner, Location secondCorner)

Methods

getSouthWestCornerpublic Location getSouthWestCorner()

getNorthEastCornerpublic Location getNorthEastCorner()


B52

org.bigiot.lib.model.Area

org.bigiot.lib.modelClass Descriptionjava.lang.Object | +-org.bigiot.lib.model.Description

public abstract class Descriptionextends Object

Description element in Offering Description

Direct Known Subclasses:Information

Constructors

Descriptionpublic Description(String name, String domain, RDFType rdfType)

Methods


getRDFTypepublic RDFType getRDFType()


B53

org.bigiot.lib.model.Description

org.bigiot.lib.modelClass EndPointjava.lang.Object | +-org.bigiot.lib.model.EndPoint

public class EndPointextends Object

Endpoint Information of Offering

Constructors

EndPointpublic EndPoint()

EndPointpublic EndPoint(EndPoint.EndpointType endpointType, EndPoint.AccessInterfaceType accessInterfaceType, String uri)

EndPointpublic EndPoint(EnumTypes.EndpointType endpointType, EnumTypes.AccessInterfaceTypes accessInterfaceType, String uri)

Methods

getUripublic String getUri()

setUripublic void setUri(String uri)

getEndpointTypepublic EndPoint.EndpointType getEndpointType()

B54

org.bigiot.lib.model.EndPoint

setEndpointTypepublic void setEndpointType(EndPoint.EndpointType endpointType)

getAccessInterfaceTypepublic EndPoint.AccessInterfaceType getAccessInterfaceType()

setAccessInterfaceTypepublic void setAccessInterfaceType(EndPoint.AccessInterfaceType accessInterfaceType)


B55

org.bigiot.lib.model.EndPoint

org.bigiot.lib.modelClass EndPoint.EndpointTypejava.lang.Object | +-org.bigiot.lib.model.EndPoint.EndpointType

public class EndPoint.EndpointTypeextends Object

Constructors

EndpointTypepublic EndpointType()

EndpointTypepublic EndpointType(String endpointType)

Methods

setEndpointTypepublic void setEndpointType(String endpointType)

getEndpointTypepublic String getEndpointType()

B56

org.bigiot.lib.model.EndPoint.EndpointType

org.bigiot.lib.modelClass EndPoint.AccessInterfaceTypejava.lang.Object | +-org.bigiot.lib.model.EndPoint.AccessInterfaceType

public class EndPoint.AccessInterfaceTypeextends Object

Constructors

AccessInterfaceTypepublic AccessInterfaceType()

AccessInterfaceTypepublic AccessInterfaceType(String accessInterfaceType)

Methods

setAccessInterfaceTypepublic void setAccessInterfaceType(String accessInterfaceType)

getAccessInterfaceTypepublic String getAccessInterfaceType()

B57

org.bigiot.lib.model.EndPoint.AccessInterfaceType

org.bigiot.lib.modelClass EnumTypesjava.lang.Object | +-org.bigiot.lib.model.EnumTypes

public class EnumTypesextends Object

Constructors

EnumTypespublic EnumTypes()

B58

org.bigiot.lib.model.EnumTypes

org.bigiot.lib.modelClass EnumTypes.AccountingTypejava.lang.Object | +- | +-org.bigiot.lib.model.EnumTypes.AccountingType

public static final class EnumTypes.AccountingTypeextends Enum

All Implemented Interfaces:Serializable, Comparable

Fields

ANYpublic static final org.bigiot.lib.model.EnumTypes.AccountingType ANY

FREEpublic static final org.bigiot.lib.model.EnumTypes.AccountingType FREE

PER_ACCESSpublic static final org.bigiot.lib.model.EnumTypes.AccountingType PER_ACCESS

PER_MESSAGEpublic static final org.bigiot.lib.model.EnumTypes.AccountingType PER_MESSAGE

PER_MONTHpublic static final org.bigiot.lib.model.EnumTypes.AccountingType PER_MONTH

PER_BYTEpublic static final org.bigiot.lib.model.EnumTypes.AccountingType PER_BYTE

B59

org.bigiot.lib.model.EnumTypes.AccountingType


Methods

valuespublic static EnumTypes.AccountingType[] values()

valueOfpublic static EnumTypes.AccountingType valueOf(String name)

B60

org.bigiot.lib.model.EnumTypes.AccountingType

org.bigiot.lib.modelClass EnumTypes.LicenseTypejava.lang.Object | +- | +-org.bigiot.lib.model.EnumTypes.LicenseType

public static final class EnumTypes.LicenseTypeextends Enum


Fields

ANYpublic static final org.bigiot.lib.model.EnumTypes.LicenseType ANY

OPEN_DATA_LICENSEpublic static final org.bigiot.lib.model.EnumTypes.LicenseType OPEN_DATA_LICENSE

Methods

valuespublic static EnumTypes.LicenseType[] values()

valueOfpublic static EnumTypes.LicenseType valueOf(String name)

B61

org.bigiot.lib.model.EnumTypes.LicenseType

org.bigiot.lib.modelClass EnumTypes.FormatTypejava.lang.Object | +- | +-org.bigiot.lib.model.EnumTypes.FormatType

public static final class EnumTypes.FormatTypeextends Enum


Fields

FORMAT_JSONLDpublic static final org.bigiot.lib.model.EnumTypes.FormatType FORMAT_JSONLD

FORMAT_XMLpublic static final org.bigiot.lib.model.EnumTypes.FormatType FORMAT_XML

Methods

valuespublic static EnumTypes.FormatType[] values()

valueOfpublic static EnumTypes.FormatType valueOf(String name)

B62

org.bigiot.lib.model.EnumTypes.FormatType

org.bigiot.lib.modelClass EnumTypes.EndpointTypejava.lang.Object | +- | +-org.bigiot.lib.model.EnumTypes.EndpointType

public static final class EnumTypes.EndpointTypeextends Enum


Fields

HTTP_GETpublic static final org.bigiot.lib.model.EnumTypes.EndpointType HTTP_GET

HTTP_POSTpublic static final org.bigiot.lib.model.EnumTypes.EndpointType HTTP_POST

WEBSOCKETpublic static final org.bigiot.lib.model.EnumTypes.EndpointType WEBSOCKET

Methods

valuespublic static EnumTypes.EndpointType[] values()

valueOfpublic static EnumTypes.EndpointType valueOf(String name)

B63

org.bigiot.lib.model.EnumTypes.EndpointType

org.bigiot.lib.modelClass EnumTypes.FunctionTypejava.lang.Object | +- | +-org.bigiot.lib.model.EnumTypes.FunctionType

public static final class EnumTypes.FunctionTypeextends Enum


Fields

ACCESSpublic static final org.bigiot.lib.model.EnumTypes.FunctionType ACCESS

FEEDpublic static final org.bigiot.lib.model.EnumTypes.FunctionType FEED

TASKpublic static final org.bigiot.lib.model.EnumTypes.FunctionType TASK

EVENTpublic static final org.bigiot.lib.model.EnumTypes.FunctionType EVENT

Methods

valuespublic static EnumTypes.FunctionType[] values()

valueOfpublic static EnumTypes.FunctionType valueOf(String name)

B64

org.bigiot.lib.model.EnumTypes.FunctionType

org.bigiot.lib.modelClass EnumTypes.AccessInterfaceTypesjava.lang.Object | +- | +-org.bigiot.lib.model.EnumTypes.AccessInterfaceTypes

public static final class EnumTypes.AccessInterfaceTypesextends Enum


Fields

UNSPECIFIEDpublic static final org.bigiot.lib.model.EnumTypes.AccessInterfaceTypes UNSPECIFIED

BIGIOT_LIB_ACCESSpublic static final org.bigiot.lib.model.EnumTypes.AccessInterfaceTypesBIGIOT_LIB_ACCESS

BIGIOT_EXTERNAL_ACCESSpublic static final org.bigiot.lib.model.EnumTypes.AccessInterfaceTypesBIGIOT_EXTERNAL_ACCESS

BIGIOT_PROXY_ACCESSpublic static final org.bigiot.lib.model.EnumTypes.AccessInterfaceTypesBIGIOT_PROXY_ACCESS

BIGIOT_LIBpublic static final org.bigiot.lib.model.EnumTypes.AccessInterfaceTypes BIGIOT_LIB

BIGIOT_PROXYpublic static final org.bigiot.lib.model.EnumTypes.AccessInterfaceTypes BIGIOT_PROXY

B65

org.bigiot.lib.model.EnumTypes.AccessInterfaceTypes


EXTERNALpublic static final org.bigiot.lib.model.EnumTypes.AccessInterfaceTypes EXTERNAL

Methods

valuespublic static EnumTypes.AccessInterfaceTypes[] values()

valueOfpublic static EnumTypes.AccessInterfaceTypes valueOf(String name)

B66

org.bigiot.lib.model.EnumTypes.AccessInterfaceTypes

org.bigiot.lib.modelClass EnumTypes.FeedTypesjava.lang.Object | +- | +-org.bigiot.lib.model.EnumTypes.FeedTypes

public static final class EnumTypes.FeedTypesextends Enum


Fields

ASYNCpublic static final org.bigiot.lib.model.EnumTypes.FeedTypes ASYNC

SYNCpublic static final org.bigiot.lib.model.EnumTypes.FeedTypes SYNC

Methods

valuespublic static EnumTypes.FeedTypes[] values()

valueOfpublic static EnumTypes.FeedTypes valueOf(String name)

B67

org.bigiot.lib.model.EnumTypes.FeedTypes

org.bigiot.lib.modelClass EnumTypes.ResponseStatusjava.lang.Object | +- | +-org.bigiot.lib.model.EnumTypes.ResponseStatus

public static final class EnumTypes.ResponseStatusextends Enum


Fields

okaypublic static final org.bigiot.lib.model.EnumTypes.ResponseStatus okay

failurepublic static final org.bigiot.lib.model.EnumTypes.ResponseStatus failure

Methods

valuespublic static EnumTypes.ResponseStatus[] values()

valueOfpublic static EnumTypes.ResponseStatus valueOf(String name)

getCodepublic int getCode()

B68

org.bigiot.lib.model.EnumTypes.ResponseStatus

org.bigiot.lib.modelClass Informationjava.lang.Object | +- | +-org.bigiot.lib.model.Information

public class Informationextends Description

Information element

Constructors

Informationpublic Information(String name, String domain, RDFType rdfType)

Informationpublic Information(String name, RDFType rdfType)

Informationpublic Information(String name, String rdfTypeUri)

Informationpublic Information(String name, String rdfTypeName, String rdfTypeUri)

B69

org.bigiot.lib.model.Information

org.bigiot.lib.modelClass IODatajava.lang.Object | +-org.bigiot.lib.model.IOData

public class IODataextends Object

Input parameter element

Constructors

IODatapublic IOData()

IODatapublic IOData(String name, RDFType rdfType)

Methods



getRdfTypepublic RDFType getRdfType()

setRdfTypepublic void setRdfType(RDFType rdfType)

B70

org.bigiot.lib.model.IOData



B71

org.bigiot.lib.model.IOData

org.bigiot.lib.modelClass Licensejava.lang.Object | +-org.bigiot.lib.model.License

public class Licenseextends Object

Offering access license

Constructors

Licensepublic License(EnumTypes.LicenseType type)

Licensepublic License(EnumTypes.LicenseType type, String text)

Methods

getTypepublic EnumTypes.LicenseType getType()

setTypepublic void setType(EnumTypes.LicenseType type)

getTextpublic String getText()

setTextpublic void setText(String text)

B72

org.bigiot.lib.model.License



B73

org.bigiot.lib.model.License

org.bigiot.lib.modelClass Locationjava.lang.Object | +-org.bigiot.lib.model.Location

public class Locationextends Object

Location as a 2D Location based on latitude and longitude

Constructors

Locationpublic Location(double latitude, double longitude)

Methods

getLatitudepublic double getLatitude()

getLongitudepublic double getLongitude()


B74

org.bigiot.lib.model.Location

org.bigiot.lib.modelClass Pricejava.lang.Object | +-org.bigiot.lib.model.Price

public class Priceextends Objectimplements Comparable

Price consisting of value and currency

All Implemented Interfaces:Comparable

Direct Known Subclasses:PriceWithAccountingType

Fields

EUROpublic static final java.lang.String EURO

Constant value: EUR

USDOLLARpublic static final java.lang.String USDOLLAR

Constant value: USD

amountprotected double amount

currencyShortprotected java.lang.String currencyShort

Constructors

Pricepublic Price(double amount, String currencyShort)

B75

org.bigiot.lib.model.Price

Methods

getAmountpublic double getAmount()

setAmountpublic void setAmount(double amount)

getCurrencyShortpublic String getCurrencyShort()

setCurrencyShortpublic void setCurrencyShort(String currencyShort)


compareTopublic int compareTo(Price o)

B76

org.bigiot.lib.model.Price

org.bigiot.lib.modelClass Price.Eurosjava.lang.Object | +-org.bigiot.lib.model.Price.Euros

public static class Price.Eurosextends Object

Factory class for prices in EURO

Constructors

Eurospublic Euros()

Methods

amountpublic static Price amount(double euros)

B77

org.bigiot.lib.model.Price.Euros

org.bigiot.lib.modelClass PriceWithAccountingTypejava.lang.Object | +- | +-org.bigiot.lib.model.PriceWithAccountingType

public class PriceWithAccountingTypeextends Price

Price with accounting type

All Implemented Interfaces:Comparable

Fields

accountingTypeprotected org.bigiot.lib.model.EnumTypes.AccountingType accountingType

Constructors

PriceWithAccountingTypepublic PriceWithAccountingType(double amount, String currencyShort, EnumTypes.AccountingType accountingType)

PriceWithAccountingTypepublic PriceWithAccountingType(Price price, EnumTypes.AccountingType accountingType)

Methods

getAccountingTypepublic EnumTypes.AccountingType getAccountingType()

setAccountingTypepublic void setAccountingType(EnumTypes.AccountingType accountingType)

B78

org.bigiot.lib.model.PriceWithAccountingType

org.bigiot.lib.modelClass RDFTypejava.lang.Object | +-org.bigiot.lib.model.RDFType

public class RDFTypeextends Object

RDF Type with name and URI

Constructors

RDFTypepublic RDFType()

RDFTypepublic RDFType(String name, String uri)

RDFTypepublic RDFType(String uri)

Methods



getUripublic String getUri()

B79

org.bigiot.lib.model.RDFType


setUripublic void setUri(String uri)


hashCodepublic int hashCode()

equalspublic boolean equals(Object obj)

B80

org.bigiot.lib.model.RDFType

org.bigiot.lib.modelClass Regionjava.lang.Object | +-org.bigiot.lib.model.Region

public class Regionextends Object

Class for defining spatial region

Constructors

Regionpublic Region(String lng, String lat, int r)

Regionpublic Region(String city)

Methods

toRegistrationStringpublic String toRegistrationString()


B81

org.bigiot.lib.model.Region

org.bigiot.lib.modelClass Region.Addressjava.lang.Object | +-org.bigiot.lib.model.Region.Address

public class Region.Addressextends Object

Fields

steetpublic java.lang.String steet

numberpublic java.lang.String number

postCodepublic java.lang.String postCode

citypublic java.lang.String city

statepublic java.lang.String state

countrypublic java.lang.String country

Constructors

B82

org.bigiot.lib.model.Region.Address


Addresspublic Address()

B83

org.bigiot.lib.model.Region.Address

org.bigiot.lib.modelClass Region.GeoLocjava.lang.Object | +-org.bigiot.lib.model.Region.GeoLoc

public class Region.GeoLocextends Object

Fields

lngpublic java.lang.String lng

latpublic java.lang.String lat

radiuspublic int radius

B84

org.bigiot.lib.model.Region.GeoLoc

org.bigiot.lib.modelClass Region.Cityjava.lang.Object | +-org.bigiot.lib.model.Region.City

public class Region.Cityextends Object

Fields


B85

org.bigiot.lib.model.Region.City

Package

org.bigiot.lib.offering

B86

org.bigiot.lib.offeringClass AccessParametersjava.lang.Object | +-org.bigiot.lib.offering.AccessParameters

public class AccessParametersextends Object

Container for access parameters. AccessParameters supports name/value pair as well as type/value pairs

Constructors

AccessParameterspublic AccessParameters()

Methods

createpublic static AccessParameters create()

addNameValuepublic AccessParameters addNameValue(String parameterName, Object value)

Adds a name/value pair

Parameters:value

Returns:

addRdfTypeValuepublic AccessParameters addRdfTypeValue(RDFType parameterType, Object value)

Adds a (RDF-)type/value pair

Parameters:parameterType

value

Returns:

B87

org.bigiot.lib.offering.AccessParameters

toNameMappublic Map toNameMap(List inputData)

Returns a map with name/value pairs and takes care that it is consistent according to a Offering Description parameterlist

Parameters:inputData - Input parameter list of Offering Description

Returns:

B88

org.bigiot.lib.offering.AccessParameters

org.bigiot.lib.offeringClass AccessParametersTuplejava.lang.Object | +-org.bigiot.lib.offering.AccessParametersTuple

public abstract class AccessParametersTupleextends Object

Container Element of AccessParameters

Direct Known Subclasses:Type, Name

Constructors

AccessParametersTuplepublic AccessParametersTuple(Object value)

Methods

getValuepublic Object getValue()

B89

org.bigiot.lib.offering.AccessParametersTuple

org.bigiot.lib.offeringClass AccessParametersTuple.Namejava.lang.Object | +- | +-org.bigiot.lib.offering.AccessParametersTuple.Name

public static class AccessParametersTuple.Nameextends AccessParametersTuple

Name/value based parameter tuple

Constructors

Namepublic Name(String name, Object value)

Methods


B90

org.bigiot.lib.offering.AccessParametersTuple.Name

org.bigiot.lib.offeringClass AccessParametersTuple.Typejava.lang.Object | +- | +-org.bigiot.lib.offering.AccessParametersTuple.Type

public static class AccessParametersTuple.Typeextends AccessParametersTuple

Type/value base parameter tuple

Constructors

Typepublic Type(RDFType rdfType, Object value)

Methods


B91

org.bigiot.lib.offering.AccessParametersTuple.Type

org.bigiot.lib.offeringClass BigResponsejava.lang.Object | +-org.bigiot.lib.offering.BigResponse

public class BigResponseextends Object

Response of an BIG IoT Offering

Constructors

BigResponsepublic BigResponse(String message)

Methods


getNodepublic JsonNode getNode()

Returns response as a data structure for traversing

Returns:

getMessagepublic String getMessage()

Returns response as a Json String

getStatuspublic EnumTypes.ResponseStatus getStatus()

Returns response status

Returns:ResponseStatus

B92

org.bigiot.lib.offering.BigResponse

org.bigiot.lib.offeringInterface IOffering

public interface IOfferingextends

Interface for an Offering implementation. It provides access to the operations of the Offering

All Known Implementing Classes:Offering

Methods

accessOneTimepublic abstract CompletableFuture accessOneTime(AccessParameters accessParameters)

Retrieves data from an Offering in a request/response manner asynchronously. Since the return value is aCompletableFuture, a blocking behavior can be achieved on calling .get() on the return value.

Parameters:accessParameters - Input parameter container

Returns:CompletableFuture of the Offering response

accessOneTimepublic abstract void accessOneTime(AccessParameters accessParameters, AccessResponseSuccessHandler onSuccess, AccessResponseFailureHandler onFailure)

Retrieves data from an Offering in a request/response manner. Method call is nonblocking.

Parameters:accessParameters - Input parameter containeronSuccess - Delegate object for callback on incoming dataonFailure - Delegate object for callback on failure

accessOneTimepublic abstract void accessOneTime(AccessParameters accessParameters, AccessResponseSuccessHandler onSuccess)


Parameters:accessParameters - Input parameter containeronSuccess - Delegate object for callback on incoming data

B93

org.bigiot.lib.offering.IOffering


accessContinuouspublic abstract IAccessFeed accessContinuous(AccessParameters accessParameters, java.time.Duration lifetime, FeedNotificationSuccessHandler onSuccess, FeedNotificationFailureHandler onFailure)

Retrieves data from an Offering continuously as a feed. Lifecycle operations are performed on the returned object. It istaken care that the feed setup is correctly according to the feed capabilities of the Offering. Multiple calls e.g. withvarying parameter set is supported in order to create multiple feeds for the same Offering.

Parameters:accessParameters - Input parameter containerlifetime - Lifetime of feedonSuccess - Delegate object for callback every time new feed data arrivesonFailure - Delegate object for callback on failure

Returns:Feed Object enabling lifecycle operations

getMyAccessFeedspublic abstract List getMyAccessFeeds()

Returns a list of all feed subscriptions

Returns:List of feed subscriptions

unsubscribepublic abstract void unsubscribe()

Terminates the subscription to the Offering. Don't confuse it with a termination of a subscription to a feed. It isperformed on the specific feed object.

B94

org.bigiot.lib.offering.IOffering

org.bigiot.lib.offeringClass Offeringjava.lang.Object | +-org.bigiot.lib.offering.Offering

public abstract class Offeringextends Objectimplements IOffering

All Implemented Interfaces:IOffering

Direct Known Subclasses:OfferingOnProviderLib

Fields

offeringDescriptionprotected org.bigiot.lib.offering.OfferingDescription offeringDescription

offeringTokenprotected java.lang.String offeringToken

feedsprotected java.util.LinkedList feeds

Constructors

Offeringpublic Offering(OfferingDescription offeringDescription, String offeringToken)

Methods

accessOneTimepublic abstract CompletableFuture accessOneTime(AccessParameters accessParameters)

B95

org.bigiot.lib.offering.Offering



Parameters:accessParameters - Input parameter container

Returns:CompletableFuture of the Offering response

accessOneTimepublic abstract void accessOneTime(AccessParameters accessParameters, AccessResponseSuccessHandler onSuccess, AccessResponseFailureHandler onFailure)


Parameters:accessParameters - Input parameter containeronSuccess - Delegate object for callback on incoming dataonFailure - Delegate object for callback on failure

accessOneTimepublic abstract void accessOneTime(AccessParameters accessParameters, AccessResponseSuccessHandler onSuccess)


Parameters:accessParameters - Input parameter containeronSuccess - Delegate object for callback on incoming data

accessContinuouspublic abstract AccessFeed accessContinuous(AccessParameters accessParameters, java.time.Duration lifetime, FeedNotificationSuccessHandler onSuccess, FeedNotificationFailureHandler onFailure)


Parameters:accessParameters - Input parameter containerlifetime - Lifetime of feedonSuccess - Delegate object for callback every time new feed data arrivesonFailure - Delegate object for callback on failure

Returns:Feed Object enabling lifecycle operations

getMyAccessFeedspublic abstract List getMyAccessFeeds()


Returns:

B96



List of feed subscriptions

unsubscribepublic abstract void unsubscribe()


getOfferingDescriptionpublic OfferingDescription getOfferingDescription()

Returns Offering Description

Returns:

B97


org.bigiot.lib.offeringClass OfferingDescriptionjava.lang.Object | +- | +-org.bigiot.lib.offering.OfferingDescription

public class OfferingDescriptionextends OfferingDescriptionData

OfferingDescription is a subscribable extension of an OfferingDescriptionData. In order to create the access object (Offering) foran Offering Description this class provides the subscribe() method

Direct Known Subclasses:OfferingDescriptionChain

Fields

loggerprotected static final Logger logger

Constructors

OfferingDescriptionprotected OfferingDescription()

OfferingDescriptionprotected OfferingDescription(String localId)

Methods

createpublic static OfferingDescriptionChain create(String localId)

Creates a basic Offering Description for incremental Offering Description building

Parameters:localId

Returns:

B98

org.bigiot.lib.offering.OfferingDescription


subscribepublic Offering subscribe()

Subscribe to an offering and creates the Offering object for access

isPojoAValidParameterObjectpublic boolean isPojoAValidParameterObject(Object parameters)

Checks whether a parameter set is a valid input parameter set

Parameters:parameters

Returns:

B99

org.bigiot.lib.offering.OfferingDescription

org.bigiot.lib.offeringClass OfferingDescriptionChainjava.lang.Object | +- | +- | +-org.bigiot.lib.offering.OfferingDescriptionChain

public class OfferingDescriptionChainextends OfferingDescription

This implementation allows the incremental construction of an Offering via chaining functions. The methods in this class addelements to the offering query, e.g. a price, an accounting type or a region. An example for the usage is

OfferingDescription offeringDescription = OfferingDescription.create("... LocalID ...")

.withInformation(new Information("Example Offering

Query", "bigiot:Parking"))

.addInputDataElement("longitude", new

RDFType("schema:longitude"))

.addInputDataElement("latitude", new

RDFType("schema:latitude"))

.addInputDataElement("radius", new

RDFType("schema:geoRadius"))

.addOutputDataElement("available", new

RDFType("datex:availableparking"))

.addOutputDataElement("occupied", new

RDFType("datex:occupiedparking"))


.withPrice(new

PriceWithAccountingType(Euros.amount(0.002), AccountingType.PER_ACCESS))

.withLicense(LicenseType.OPEN_DATA_LICENSE)

.addEndPoint(EndpointTypes.HTTP_GET,

AccessInterfaceTypes.BIGIOT_LIB, "/parkinginfo");

Constructors

OfferingDescriptionChainprotected OfferingDescriptionChain(String localId)

Methods

B100

org.bigiot.lib.offering.OfferingDescriptionChain


withInformationpublic OfferingDescriptionChain withInformation(Description description)

inRegionpublic OfferingDescriptionChain inRegion(Region region)

withPricepublic OfferingDescriptionChain withPrice(Price price)

withAccountingTypepublic OfferingDescriptionChain withAccountingType(EnumTypes.AccountingTypeaccountingType)

withLicenseTypepublic OfferingDescriptionChain withLicenseType(EnumTypes.LicenseType type)

addEndPointpublic OfferingDescriptionChain addEndPoint(EnumTypes.EndpointType endpointType, EnumTypes.AccessInterfaceTypes accessInterfaceType, String uri)

addInputDataElementpublic OfferingDescriptionChain addInputDataElement(String name, RDFType rdfType)

addOutputDataElementpublic OfferingDescriptionChain addOutputDataElement(String name, RDFType rdfType)

B101

org.bigiot.lib.offering.OfferingDescriptionChain

org.bigiot.lib.offeringClass OfferingDescriptionDatajava.lang.Object | +-org.bigiot.lib.offering.OfferingDescriptionData

public class OfferingDescriptionDataextends Object

Data Object representing Offering Description

Direct Known Subclasses:OfferingDescription

Constructors

OfferingDescriptionDatapublic OfferingDescriptionData()

OfferingDescriptionDatapublic OfferingDescriptionData(String localId)

Methods

getIdpublic String getId()

setIdpublic void setId(String id)



B102

org.bigiot.lib.offering.OfferingDescriptionData


setRdfTypepublic void setRdfType(RDFType rdfType)

getProviderIdpublic String getProviderId()

setProviderIdpublic void setProviderId(String providerId)

getDescriptionpublic Description getDescription()

setDescriptionpublic void setDescription(Description description)

getEndpointspublic List getEndpoints()

setEndpointspublic void setEndpoints(List endpoints)

getRegionpublic Region getRegion()

setRegionpublic void setRegion(Region region)

B103



getPricepublic Price getPrice()

setPricepublic void setPrice(Price price)

getLicensepublic License getLicense()

setLicensepublic void setLicense(License license)

getOfferingpublic String getOffering()

setOfferingpublic void setOffering(String offering)

getInputDatapublic List getInputData()

setInputDatapublic void setInputData(List inputData)

addInputDatapublic void addInputData(IOData inputData)

B104



getOutputDatapublic List getOutputData()

setOutputDatapublic void setOutputData(List outputData)

addOutputDatapublic void addOutputData(IOData outputData)

getFormatpublic EnumTypes.FormatType getFormat()

setFormatpublic void setFormat(EnumTypes.FormatType format)

getActivepublic Boolean getActive()

setActivepublic void setActive(Boolean active)

getAccessInterfaceTypespublic EnumTypes.AccessInterfaceTypes getAccessInterfaceTypes()

setAccessInterfaceTypespublic void setAccessInterfaceTypes(EnumTypes.AccessInterfaceTypesaccessInterfaceTypes)

getEndpointpublic EndPoint getEndpoint()

B105



setEndpointpublic void setEndpoint(EndPoint endpoint)


toRegistrationStringpublic String toRegistrationString(String providerId)

Generates a valid registration message accepted by the Marketplace

Parameters:providerId - Identifier of the provider issued by the Marketplace

Returns:Message for Offering registration

toActivationStringpublic String toActivationString()

Generates activation message

Returns:Activation message

toDeActivationStringpublic String toDeActivationString()

Generates deactivation message

Returns:Deactivation message

B106


org.bigiot.lib.offeringClass OfferingOnProviderLibjava.lang.Object | +- | +-org.bigiot.lib.offering.OfferingOnProviderLib

public class OfferingOnProviderLibextends Offering

Implementation for Offering running in Integration mode 1,2 and 4. The A1 interface is provided by the BIG IoT provider Lib.Accordingly the transformation of the call semantics to the legacy platform semantics is performed by the Provider Lib.

All Implemented Interfaces:IOffering

Constructors

OfferingOnProviderLibpublic OfferingOnProviderLib(OfferingDescription offeringDescription, String offeringToken)

Methods

accessOneTimepublic CompletableFuture accessOneTime(AccessParameters accessParameters)


accessOneTimepublic void accessOneTime(AccessParameters accessParameters, AccessResponseSuccessHandler onSuccess, AccessResponseFailureHandler onFailure)


accessOneTimepublic void accessOneTime(AccessParameters accessParameters, AccessResponseSuccessHandler onSuccess)


B107

org.bigiot.lib.offering.OfferingOnProviderLib


accessContinuouspublic AccessFeed accessContinuous(AccessParameters accessParameters, java.time.Duration lifetime, FeedNotificationSuccessHandler onSuccess, FeedNotificationFailureHandler onFailure)


unsubscribepublic void unsubscribe()


getMyAccessFeedspublic List getMyAccessFeeds()


B108

org.bigiot.lib.offering.OfferingOnProviderLib

Package

org.bigiot.lib.offering.encoder

B109

org.bigiot.lib.offering.encoderClass ParameterEncoderjava.lang.Object | +-org.bigiot.lib.offering.encoder.ParameterEncoder

public abstract class ParameterEncoderextends Object

Encoder for parameterization of Offering access

Direct Known Subclasses:ParameterEncoderJson, ParameterEncoderUrl

Constructors

ParameterEncoderpublic ParameterEncoder()

Methods

encodepublic abstract String encode(Object parameters)

Generates a valid encoding for the access parameters used for an Offering call.


Returns:

B110

org.bigiot.lib.offering.encoder.ParameterEncoder

org.bigiot.lib.offering.encoderClass ParameterEncoderJsonjava.lang.Object | +- | +-org.bigiot.lib.offering.encoder.ParameterEncoderJson

public class ParameterEncoderJsonextends ParameterEncoder

Parameter Encoder for Json

Constructors

ParameterEncoderJsonpublic ParameterEncoderJson()

Methods

encodepublic String encode(Object parameters)

Generates a valid encoding in JSON notation for the access parameters used for an Offering call.


Returns:

B111

org.bigiot.lib.offering.encoder.ParameterEncoderJson

org.bigiot.lib.offering.encoderClass ParameterEncoderUrljava.lang.Object | +- | +-org.bigiot.lib.offering.encoder.ParameterEncoderUrl

public class ParameterEncoderUrlextends ParameterEncoder

Parameter encoder for URL query parameters

Constructors

ParameterEncoderUrlpublic ParameterEncoderUrl()

Methods

encodepublic String encode(Object parameters)

Generates a valid encoding as a URL parameter string for the parameterization of an Offering call.


Returns:

B112

org.bigiot.lib.offering.encoder.ParameterEncoderUrl

Package

org.bigiot.lib.query

B113

org.bigiot.lib.queryInterface IOfferingQuery

public interface IOfferingQueryextends

Interface for an Offering Query.

All Known Implementing Classes:OfferingQuery

Methods

toOfferingQueryStringpublic abstract String toOfferingQueryString(String consumerId)

Compiles a Offering Query message accepted by the Marketplace

Parameters:consumerId - Consumer identifier issued by Marketplace

Returns:Offering Query string

B114

org.bigiot.lib.query.IOfferingQuery

org.bigiot.lib.queryClass OfferingQueryjava.lang.Object | +-org.bigiot.lib.query.OfferingQuery

public abstract class OfferingQueryextends Objectimplements IOfferingQuery

This abstract class implements IOfferingQuery. It leaves the implementation of query string generation (toOfferingQueryString())open.

All Implemented Interfaces:IOfferingQuery

Direct Known Subclasses:OfferingQueryChain, OfferingQueryText

Constructors

OfferingQuerypublic OfferingQuery()

Methods

toOfferingQueryStringpublic abstract String toOfferingQueryString(String consumerId)



Returns:

createpublic static OfferingQueryChain create(String localId)

Factory methods for incremental Offering Query creation

Parameters:consumerId - Consumer ID

Returns:

B115

org.bigiot.lib.query.OfferingQuery

org.bigiot.lib.queryClass OfferingQueryChainjava.lang.Object | +- | +-org.bigiot.lib.query.OfferingQueryChain

public class OfferingQueryChainextends OfferingQuery

This implementation of an Offering Query allows the incremental construction of an Offering Query via chaining functions. Themethods in this class add elements to the offering query, e.g. a max price, an accounting type or a region. As a central element inthe BIG IoT API, the implementation of OfferingQuery shall allow natural, user centric query generation. Motivation is that theuser gets a strongly typed interface for Offering Query Generation without being overstrained by parameters he needn't for hisquery. The stream orientation of the incremental approach and the method names oriented an natural language support this. An example for the usage is


IOfferingQuery query = OfferingQuery.create("... Local Query Id ...")

.withInformation(new Information("Example Offering

Query", "bigiot:Parking"))


.withAccountingType(EnumTypes.AccountingType.PER_ACCESS)

.withMaxPrice(Euros.amount(0.002))

.withLicenseType(LicenseType.OPEN_DATA_LICENSE);

Constructors

OfferingQueryChainpublic OfferingQueryChain(String localId)

Constructs a minimal Offering Query

Parameters:consumerId - Consumer ID

Methods

withInformationpublic OfferingQueryChain withInformation(Information information)

Queries for Offering with specified information element

B116

org.bigiot.lib.query.OfferingQueryChain


Parameters:information - Information Element

Returns:Offering Query

withMaxPricepublic OfferingQueryChain withMaxPrice(Price price)

Queries for offerings with a max price

Parameters:price - Price


inRegionpublic OfferingQueryChain inRegion(Region region)

Queries for offerings in a region

Parameters:region - Region


withAccountingTypepublic OfferingQueryChain withAccountingType(EnumTypes.AccountingType accountingType)

Queries for Offering with specified accounting type

Parameters:accountingType - Accounting Type

Returns:

withLicenseTypepublic OfferingQueryChain withLicenseType(EnumTypes.LicenseType licenseType)

Queries for Offering with specified license type

Parameters:licenseType - Licens Type

Returns:


B117



toOfferingQueryStringpublic String toOfferingQueryString(String consumerId)



Returns:

B118


org.bigiot.lib.queryClass OfferingQueryTextjava.lang.Object | +- | +-org.bigiot.lib.query.OfferingQueryText

public class OfferingQueryTextextends OfferingQuery

OfferingQueryText brings support for manually generated Offering Queries. This is convenient for those user who want to utilizefunctionality of Marketplace Discoveries which are not yet implemented by OfferingQueryChain


Constructors

OfferingQueryTextpublic OfferingQueryText(String offeringQueryString)

Methods

toOfferingQueryStringpublic String toOfferingQueryString(String consumerId)



Returns:

B119

org.bigiot.lib.query.OfferingQueryText

Package

org.bigiot.lib.query.elements

B120

org.bigiot.lib.query.elementsClass PriceFilterjava.lang.Object | +-org.bigiot.lib.query.elements.PriceFilter

public abstract class PriceFilterextends Objectimplements QueryElement

Abstract price filter used for Offering Query

All Implemented Interfaces:QueryElement

Direct Known Subclasses:PriceFilterBetween, PriceFilterMin, PriceFilterMax

Constructors

PriceFilterpublic PriceFilter()

Methods

setAccountingTypepublic abstract void setAccountingType(EnumTypes.AccountingType accountingType)

Sets accotuning type

Parameters:accountingType

getAccountingTypepublic abstract EnumTypes.AccountingType getAccountingType()

Returns accounting type

Returns:

setPricepublic abstract void setPrice(Price price)

Sets price

Parameters:

B121

org.bigiot.lib.query.elements.PriceFilter


price

B122

org.bigiot.lib.query.elements.PriceFilter

org.bigiot.lib.query.elementsClass PriceFilter.PriceFilterMaxjava.lang.Object | +- | +-org.bigiot.lib.query.elements.PriceFilter.PriceFilterMax

public static class PriceFilter.PriceFilterMaxextends PriceFilter

Max pricefilter


Constructors

PriceFilterMaxpublic PriceFilterMax(PriceWithAccountingType max)

Methods

getMaxpublic PriceWithAccountingType getMax()

toQueryElementpublic String toQueryElement()




Sets price


B123

org.bigiot.lib.query.elements.PriceFilter.PriceFilterMax



B124

org.bigiot.lib.query.elements.PriceFilter.PriceFilterMax

org.bigiot.lib.query.elementsClass PriceFilter.PriceFilterMinjava.lang.Object | +- | +-org.bigiot.lib.query.elements.PriceFilter.PriceFilterMin

public static class PriceFilter.PriceFilterMinextends PriceFilter

Min price filter


Constructors

PriceFilterMinpublic PriceFilterMin(PriceWithAccountingType min)

Methods

getMinpublic PriceWithAccountingType getMin()





Sets price


B125

org.bigiot.lib.query.elements.PriceFilter.PriceFilterMin



B126

org.bigiot.lib.query.elements.PriceFilter.PriceFilterMin

org.bigiot.lib.query.elementsClass PriceFilter.PriceFilterBetweenjava.lang.Object | +- | +-org.bigiot.lib.query.elements.PriceFilter.PriceFilterBetween

public static class PriceFilter.PriceFilterBetweenextends PriceFilter

Filter for price in an interval


Constructors

PriceFilterBetweenpublic PriceFilterBetween(Price min, Price max, EnumTypes.AccountingType accountingType)

Methods

getMinpublic Price getMin()

getMaxpublic Price getMax()




B127

org.bigiot.lib.query.elements.PriceFilter.PriceFilterBetween



Sets price



B128

org.bigiot.lib.query.elements.PriceFilter.PriceFilterBetween

org.bigiot.lib.query.elementsInterface QueryElement

public interface QueryElementextends

ABstract Query Element knowing how to represent in an Offering Query

All Known Implementing Classes:PriceFilter, Region

Methods

toQueryElementpublic abstract String toQueryElement()

B129

org.bigiot.lib.query.elements.QueryElement

org.bigiot.lib.query.elementsClass Regionjava.lang.Object | +-org.bigiot.lib.query.elements.Region

public abstract class Regionextends Objectimplements QueryElement

Region as an query element used as spatial filter


Direct Known Subclasses:RegionFilterCircle, RegionFilterBox, city, RegionFilterDescriptive

Constructors

Regionpublic Region()

Methods

citypublic static Region.city city(String cityName)

Factory for city filter

Parameters:cityName

Returns:

inAreapublic static Region.RegionFilterBox inArea(Location swCorner, Location neCorner)

Factory for spatial box filter

Parameters:swCorner

neCorner

Returns:

B130

org.bigiot.lib.query.elements.Region

inRangeAroundpublic static Region.RegionFilterCircle inRangeAround(Location location, double meters)

Facotry for range filter

Parameters:location

meters

Returns:

B131

org.bigiot.lib.query.elements.Region

org.bigiot.lib.query.elementsClass Region.RegionFilterDescriptivejava.lang.Object | +- | +-org.bigiot.lib.query.elements.Region.RegionFilterDescriptive

public static class Region.RegionFilterDescriptiveextends Region

Region as a descriptive text


Constructors

RegionFilterDescriptivepublic RegionFilterDescriptive(String description)

Methods

getDescriptionpublic String getDescription()


B132

org.bigiot.lib.query.elements.Region.RegionFilterDescriptive

org.bigiot.lib.query.elementsClass Region.cityjava.lang.Object | +- | +-org.bigiot.lib.query.elements.Region.city

public static class Region.cityextends Region

Region as a city name


Constructors

citypublic city(String cityName)

Methods


toRegistrationStringpublic String toRegistrationString()

B133

org.bigiot.lib.query.elements.Region.city

org.bigiot.lib.query.elementsClass Region.RegionFilterBoxjava.lang.Object | +- | +-org.bigiot.lib.query.elements.Region.RegionFilterBox

public static class Region.RegionFilterBoxextends Region

Region as a spatial box


Constructors

RegionFilterBoxpublic RegionFilterBox(Location swCorner, Location neCorner)

Methods

getSwCornerpublic Location getSwCorner()

getNeCornerpublic Location getNeCorner()


B134

org.bigiot.lib.query.elements.Region.RegionFilterBox

org.bigiot.lib.query.elementsClass Region.RegionFilterCirclejava.lang.Object | +- | +-org.bigiot.lib.query.elements.Region.RegionFilterCircle

public static class Region.RegionFilterCircleextends Region

Region as a spatial circle


Constructors

RegionFilterCirclepublic RegionFilterCircle(Location location, double meters)

Methods

getLocationpublic Location getLocation()

getMeterspublic double getMeters()


B135

org.bigiot.lib.query.elements.Region.RegionFilterCircle

Package

org.bigiot.lib.security

B136

org.bigiot.lib.securityClass AccessTokenjava.lang.Object | +-org.bigiot.lib.security.AccessToken

public class AccessTokenextends Object

Constructors

AccessTokenpublic AccessToken()

Methods

generatepublic static String generate(String consumerId, String offeringId)

generatepublic static String generate(String consumerId, String offeringId, String secret)

validatepublic static boolean validate(String jwtToken)

validatepublic static boolean validate(String jwtToken, String secret)

getCurrentDatepublic static Date getCurrentDate()

B137

org.bigiot.lib.security.AccessToken

getExpirationDatepublic static Date getExpirationDate(long ttl)

getCurrentTimepublic long getCurrentTime()

B138

org.bigiot.lib.security.AccessToken

Package

org.bigiot.lib.templates

B139

org.bigiot.lib.templatesClass OfferingQueryPriceTemplatejava.lang.Object | +- | +-org.bigiot.lib.templates.OfferingQueryPriceTemplate

public class OfferingQueryPriceTemplateextends FilloutTemplate

Template for Price Filter in Offering Query

Constructors

OfferingQueryPriceTemplatepublic OfferingQueryPriceTemplate(String amount, String currencyShort, String accountingModel)

OfferingQueryPriceTemplatepublic OfferingQueryPriceTemplate(HashMap kvp)

B140

org.bigiot.lib.templates.OfferingQueryPriceTemplate

org.bigiot.lib.templatesClass OfferingQueryRequestTemplatejava.lang.Object | +- | +-org.bigiot.lib.templates.OfferingQueryRequestTemplate

public class OfferingQueryRequestTemplateextends FilloutTemplate

Template for Offering Query

Constructors

OfferingQueryRequestTemplatepublic OfferingQueryRequestTemplate(String consumerId, String localId, String name, String rdfUri, String licenseType, String priceFilter, String regionFilter)

OfferingQueryRequestTemplatepublic OfferingQueryRequestTemplate(HashMap kvp)

B141

Index

IndexA

ACCESS 64

ACCESS_PATH 11

accessContinuous 93, 96, 107

accessDomainName 11

AccessFeed 25

AccessFeedAsync 27

AccessFeedSync 28

AccessInterfaceType 57

accessOneTime 93, 95, 96, 107

AccessParameters 87

AccessParametersTuple 89

accessPort 11

accessRequestHandler 13

AccessToken 137

accountingType 78

addEndPoint 101

addInputData 104

addInputDataElement 101

addNameValue 87

addOutputData 105

addOutputDataElement 101

addRdfTypeValue 87

Address 18, 82

address 22

amount 75, 77

ANY 59, 61

Area 52

ASYNC 67

authenticate 3, 7, 9

B

BigConstants 42

BigHelper 43

BigHttpSupport 45

BIGIOT_EXTERNAL_ACCESS 65

BIGIOT_LIB 65

BIGIOT_LIB_ACCESS 65

BIGIOT_PROXY 65

BIGIOT_PROXY_ACCESS 65

BigIotAPI 3

BigRandom 48

BigResponse 92

birthday 22

C

city 18, 82, 130, 133

clientId 3

compareTo 76

Consumer 5

country 82

create 87, 98, 115

createUser 17

currencyShort 75

D

delete 46, 47

deregister 10, 12

Description 53

df00 43

df000 43

df0000 43

df0_0000 43

discover 5, 6, 7, 8

DiscoverFailureException 35

discoverySubUrl 42

E

encode 110, 111, 112

EndPoint 54

EndpointType 56

EnumTypes 58

equals 80

EURO 75

Euros 77

EVENT 64

ExampleConsumer 15

ExampleProvider 16

expirationDate 25

EXTERNAL 66

extractOfferingDescriptionsFromHttpResponse 44

F

B142

Index

failure 68

FEED 64

FeedFailureException 38

feeds 95

FeedStatus 29

fillOut 50

FilloutTemplate 50

FORMAT_JSONLD 62

FORMAT_XML 62

formatString 43

FREE 59

G

generate 137

get 45

getAccessInterfaceType 55, 57

getAccessInterfaceTypes 105

getAccountingType 78, 121, 123, 125, 128

getActive 105

getAmount 75

getCity 19

getCode 68

getCurrencyShort 76

getCurrentDate 137

getCurrentTime 138

getDescription 103, 132

getEndpoint 105

getEndpoints 103

getEndpointType 54, 56

getExpirationDate 26, 30, 138

getFormat 105

getId 102

getInputData 104

getLatitude 74

getLicense 104

getLocation 135

getLongitude 74

getMax 123, 127

getMessage 92

getMeters 135

getMin 125, 127

getMyAccessFeeds 94, 96, 108

getName 20, 53, 70, 79, 90, 102

getNeCorner 134

getNextUniform 48

getNode 92

getNorthEastCorner 52

getOffering 104

getOfferingDescription 97

getOutputData 104

getPrice 104

getProviderId 103

getRandomPositionInside 49

getRDFType 53

getRdfType 70, 91, 103

getRegion 103

getSouthWestCorner 52

getStatus 26, 27, 28, 30, 92

getStreet 18

getSwCorner 134

getText 72

getType 72

getUri 54, 79

getValue 89

getVersion 21

H

hashCode 80

HTTP_GET 63

HTTP_POST 63

I

inArea 130

Information 69

initialize 9, 12

inRangeAround 131

inRegion 101, 117

IOData 70

isPojoAValidParameterObject 99

L

lat 84

License 72

lng 84

Location 74

B143

Index

logger 98

M

main 15, 16, 17

marketplaceUri 3

N

Name 90

name 20, 22, 85

nextBoolean 49

nicknames 22

number 82

O

Offering 95

OfferingCallback 13

offeringCallbacks 11

OfferingDescription 98

offeringDescription 13, 95

OfferingDescriptionChain 100

OfferingDescriptionData 102

OfferingOnProviderLib 107

OfferingQuery 115

OfferingQueryChain 116

OfferingQueryPriceTemplate 140

OfferingQueryRequestTemplate 141

OfferingQueryText 119

offerings 11

offeringToken 95

okay 68

onFailure 25

onSuccess 25

OPEN_DATA_LICENSE 61

P

ParameterEncoder 110

ParameterEncoderJson 111

ParameterEncoderTest 17

ParameterEncoderUrl 112

PER_ACCESS 59

PER_BYTE 59

PER_MESSAGE 59

PER_MONTH 59

post 45, 46

postCode 82

Price 75

PriceFilter 121

PriceFilterBetween 127

PriceFilterMax 123

PriceFilterMin 125

PriceWithAccountingType 78

processNotificationOnFailure 39

processNotificationOnSuccess 40

processRequestHandler 32

processResponse 36, 37

processResponseOnFailure 33

processResponseOnSuccess 34

Product 20

products 22

Provider 11

put 46

R

radius 84

RDFType 79

Region 81, 130

RegionFilterBox 134

RegionFilterCircle 135

RegionFilterDescriptive 132

register 9, 12

resume 25, 27, 28, 30

round 44

S

setAccessInterfaceType 55, 57

setAccessInterfaceTypes 105

setAccountingType 78, 121, 123, 125, 127

setActive 105

setAmount 76

setCity 19

setCurrencyShort 76

setDescription 103

setEndpoint 106

setEndpoints 103

B144

Index

setEndpointType 55, 56

setFormat 105

setId 102

setInputData 104

setLicense 104

setLifetime 26, 27, 28, 30

setName 20, 70, 79, 102

setOffering 104

setOutputData 105

setPrice 104, 121, 123, 125, 127

setProviderId 103

setRdfType 70, 103

setRegion 103

setStreet 19

setText 72

setType 72

setUri 54, 79

setVersion 21

showOfferingDescriptions 44

state 82

steet 82

stop 26, 27, 28, 30

street 18

subscribe 98

SYNC 67

syncFeedIntervalMillis 42

T

TASK 64

terminate 3, 8, 10, 12

test 48

toActivationString 106

toDeActivationString 106

toNameMap 88

toOfferingQueryString 114, 115, 118, 119

toQueryElement 123, 125, 127, 129, 132, 133, 134, 135

toRegistrationString 81, 106, 133

toString 18, 20, 23, 52, 53, 55, 70, 72, 74, 76, 80, 81, 92, 106,

117

Type 91

U

UNSPECIFIED 65

unsubscribe 94, 97, 108

USDOLLAR 75

User 22, 23

V

validate 137

valueOf 60, 61, 62, 63, 64, 66, 67, 68

values 59, 61, 62, 63, 64, 66, 67, 68

W

WEBSOCKET 63

withAccountingType 101, 117

withInformation 100, 116

withLicenseType 101, 117

withMaxPrice 117

withPrice 101

B145

Index

deliverable 3.1.a: big iot api design - first...

Documents