com.siemens.mindsphere.sdk.iot.event.apiclient

Class EventClient

Object

MindsphereAPIClient

EventClient

public class EventClient
extends MindsphereAPIClient

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EventClient.ClientBuilder

Nested classes/interfaces inherited from class MindsphereAPIClient

MindsphereAPIClient.Builder<T extends MindsphereAPIClient.Builder<T>>

Field Summary

Fields inherited from class MindsphereAPIClient

credentials, restClientConfig, restTemplate

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	EventClient(EventClient.ClientBuilder builder)

Method Summary

Modifier and Type	Method and Description
static EventClient.ClientBuilder	builder()
CustomEvent	createCustomEvent(CustomEvent customEvent) Creates custom event with the provided content.
CustomEvent	createCustomEvent(String customEventJson) Creates custom event with the provided content.
BaseEvent	createEvent(String eventJson) Creates a Mindsphere Standard event or Custom event depending on the provided content.
MindsphereStandardEvent	createStandardEvent(MindsphereStandardEvent standardEvent) Creates a Mindsphere Standard event with the provided.
MindsphereStandardEvent	createStandardEvent(String standardEventJson) Creates a Mindsphere Standard Event with the provided.
BaseEvent	getEventById(String eventId) Returns an Event with the specified ID
BaseEvent	getEventById(String eventId, String ifNoneMatch) Returns an Event with the specified ID
Events	getEvents() Returns Mindsphere Standard Events based on the request parameters.
Events	getEvents(Integer size) Returns Mindsphere Standard Events based on the request parameters.
Events	getEvents(Integer size, boolean history) Returns Mindsphere Standard Events based on the request parameters.
Events	getEvents(Integer size, Integer page) Returns Mindsphere Standard Events based on the request parameters.
Events	getEvents(Integer size, Integer page, boolean history) Returns Mindsphere Standard Events based on the request parameters.
Events	getEvents(Integer size, Integer page, String sort) Returns Mindsphere Standard Events based on the request parameters.
Events	getEvents(Integer size, Integer page, String sort, boolean history) Returns Mindsphere Standard Events based on the request parameters.
Events	getEvents(Integer size, Integer page, String filter, String sort, String ifNoneMatch, Boolean history) Returns events based on the request parameters. If no typeId is given in the filter expression then MindsphereStandardEvent typed events (and its descendants excluding descendant specific fields) will be returned.
Events	getEvents(String sort) Returns Mindsphere Standard Events based on the request parameters.
Events	getEvents(String sort, boolean history) Returns Mindsphere Standard Events based on the request parameters.
Events	getEvents(String sort, String filter) Returns Mindsphere Standard Events based on the request parameters. If no typeId is given in the filter expression then MindsphereStandardEvent typed events (and its descendants excluding descendant specific fields) will be returned.
CustomEvent	updateCustomEvent(String eventId, CustomEvent customEvent, String ifMatch) Update an existing custom event specified by ID.
CustomEvent	updateCustomEvent(String eventId, String customEventJson, String ifMatch) Update an existing custom event specified by ID.
BaseEvent	updateEvents(String eventId, String eventJson, String ifMatch) Update an existing event specified by ID.
MindsphereStandardEvent	updateStandardEvent(String eventId, MindsphereStandardEvent standardEvent, String ifMatch) Update an existing Mindsphere Standard Event specified by ID.
MindsphereStandardEvent	updateStandardEvent(String eventId, String standardEventJson, String ifMatch) Update an existing Mindsphere Standard Event specified by ID.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EventClient

protected EventClient(EventClient.ClientBuilder builder)

Method Detail

builder

public static EventClient.ClientBuilder builder()

getEvents

public Events getEvents(Integer size,
                        Integer page,
                        String filter,
                        String sort,
                        String ifNoneMatch,
                        Boolean history)
                 throws MindsphereException

Returns events based on the request parameters.
If no typeId is given in the filter expression then MindsphereStandardEvent typed events (and its descendants excluding descendant specific fields) will be returned.

200 - A page of events.

304 - Not Modified

400 - The request will return 400 BAD REQUEST in following cases :

• Not filterable field is present in the filter expression
• Sorting events by a not sortable field
• BaseEvent type is present in the filter expressions typeId parameter

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Parameters:

size - Specifies the number of elements in a page. Default is 20

page - Specifies the requested page index. Default is 0

filter - Filter parameter (JSON) encoded format

• If timestamp is not provided in the filter, the events from the 7 days will be filtered for by default.
• Multiple typeId expressions (by using and, or logical operators) in filter parameter is not allowed. Only equality function is supported on it.
• Filtering with typeId having BaseEvent is not supported. If typeId is missing from filter expression then MindsphereStandardEvent typed (including) descendants polymorphic query) events will be returned.
• Negation of typeId in filter expression is not allowed.
• If there are multiple events that have the samecorrelationId and entityId then only the latest one will be present in the returning list of events if history is false (false is deafult value)

sort - Order in which events are returned. Supported only on filterable fields. Default is timestamp in descending order

ifNoneMatch - ETag hash of previous request to allow caching

history - Optional parameter, if we want to retrieve the history of an event

Returns:

List of events satisfying the provided criteria

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

getEvents

public Events getEvents()
                 throws MindsphereException

Returns Mindsphere Standard Events based on the request parameters.

200 - A page of events.

304 - Not Modified

400 - The request will return 400 BAD REQUEST in following cases :

• Not filterable field is present in the filter expression
• Sorting events by a not sortable field
• BaseEvent type is present in the filter expressions typeId parameter

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Returns:

List of Events

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

getEvents

public Events getEvents(Integer size)
                 throws MindsphereException

Returns Mindsphere Standard Events based on the request parameters.

200 - A page of events.

304 - Not Modified

400 - The request will return 400 BAD REQUEST in following cases :

• Not filterable field is present in the filter expression
• Sorting events by a not sortable field
• BaseEvent type is present in the filter expressions typeId parameter

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Parameters:

size - Specifies the number of elements in a page. Default is 20

Returns:

List of Events

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

getEvents

public Events getEvents(Integer size,
                        boolean history)
                 throws MindsphereException

Returns Mindsphere Standard Events based on the request parameters.

200 - A page of events.

304 - Not Modified

400 - The request will return 400 BAD REQUEST in following cases :

• Not filterable field is present in the filter expression
• Sorting events by a not sortable field
• BaseEvent type is present in the filter expressions typeId parameter

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Parameters:

size - Specifies the number of elements in a page. Default is 20

history - Optional parameter, if we want to retrieve the history of an event

Returns:

List of events satisfying the provided criteria

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

getEvents

public Events getEvents(Integer size,
                        Integer page)
                 throws MindsphereException

Returns Mindsphere Standard Events based on the request parameters.

200 - A page of events.

304 - Not Modified

400 - The request will return 400 BAD REQUEST in following cases :

• Not filterable field is present in the filter expression
• Sorting events by a not sortable field
• BaseEvent type is present in the filter expressions typeId parameter

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Parameters:

size - Specifies the number of elements in a page. Default is 20

page - Specifies the requested page index. Default is 0

Returns:

List of Events

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

getEvents

public Events getEvents(Integer size,
                        Integer page,
                        boolean history)
                 throws MindsphereException

Returns Mindsphere Standard Events based on the request parameters.

200 - A page of events.

304 - Not Modified

400 - The request will return 400 BAD REQUEST in following cases :

• Not filterable field is present in the filter expression
• Sorting events by a not sortable field
• BaseEvent type is present in the filter expressions typeId parameter

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Parameters:

size - Specifies the number of elements in a page. Default is 20

page - Specifies the requested page index. Default is 0

history - Optional parameter, if we want to retrieve the history of an event

Returns:

List of Events

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

getEvents

public Events getEvents(Integer size,
                        Integer page,
                        String sort)
                 throws MindsphereException

Returns Mindsphere Standard Events based on the request parameters.

200 - A page of events.

304 - Not Modified

400 - The request will return 400 BAD REQUEST in following cases :

• Not filterable field is present in the filter expression
• Sorting events by a not sortable field
• BaseEvent type is present in the filter expressions typeId parameter

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Parameters:

size - Specifies the number of elements in a page. Default is 20

page - Specifies the requested page index. Default is 0

sort - Order in which events are returned. Supported only on filterable fields. Default is timestamp in descending order

Returns:

List of Events

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

getEvents

public Events getEvents(Integer size,
                        Integer page,
                        String sort,
                        boolean history)
                 throws MindsphereException

Returns Mindsphere Standard Events based on the request parameters.

200 - A page of events.

304 - Not Modified

400 - The request will return 400 BAD REQUEST in following cases :

• Not filterable field is present in the filter expression
• Sorting events by a not sortable field
• BaseEvent type is present in the filter expressions typeId parameter

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Parameters:

size - Specifies the number of elements in a page. Default is 20

page - Specifies the requested page index. Default is 0

sort - Order in which events are returned. Supported only on filterable fields. Default is timestamp in descending order

history - Optional parameter, if we want to retrieve the history of an event

Returns:

List of Events

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

getEvents

public Events getEvents(String sort)
                 throws MindsphereException

Returns Mindsphere Standard Events based on the request parameters.

200 - A page of events.

304 - Not Modified

400 - The request will return 400 BAD REQUEST in following cases :

• Not filterable field is present in the filter expression
• Sorting events by a not sortable field
• BaseEvent type is present in the filter expressions typeId parameter

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Parameters:

sort - Order in which events are returned. Supported only on filterable fields. Default is timestamp in descending order

Returns:

List of Events

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

getEvents

public Events getEvents(String sort,
                        String filter)
                 throws MindsphereException

Returns Mindsphere Standard Events based on the request parameters.
If no typeId is given in the filter expression then MindsphereStandardEvent typed events (and its descendants excluding descendant specific fields) will be returned.

200 - A page of events.

304 - Not Modified

400 - The request will return 400 BAD REQUEST in following cases :

• Not filterable field is present in the filter expression
• Sorting events by a not sortable field
• BaseEvent type is present in the filter expressions typeId parameter

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Parameters:

sort - Order in which events are returned. Supported only on filterable fields. Default is timestamp in descending order

filter - Filter parameter (JSON) encoded format

• If timestamp is not provided in the filter, the events from the 7 days will be filtered for by default.
• Multiple typeId expressions (by using and, or logical operators) in filter parameter is not allowed. Only equality function is supported on it.
• Filtering with typeId having BaseEvent is not supported. If typeId is missing from filter expression then MindsphereStandardEvent typed (including) descendants polymorphic query) events will be returned.
• Negation of typeId in filter expression is not allowed.
• If there are multiple events that have the samecorrelationId and entityId then only the latest one will be present in the returning list of events if history is false (false is deafult value)

Returns:

List of Events

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

getEvents

public Events getEvents(String sort,
                        boolean history)
                 throws MindsphereException

Returns Mindsphere Standard Events based on the request parameters.

200 - A page of events.

304 - Not Modified

400 - The request will return 400 BAD REQUEST in following cases :

• Not filterable field is present in the filter expression
• Sorting events by a not sortable field
• BaseEvent type is present in the filter expressions typeId parameter

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Parameters:

sort - Order in which events are returned. Supported only on filterable fields. Default is timestamp in descending order

history - Optional parameter, if we want to retrieve the history of an event

Returns:

List of Events

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

getEventById

public BaseEvent getEventById(String eventId,
                              String ifNoneMatch)
                       throws MindsphereException

Returns an Event with the specified ID

200 - OK

304 - Not Modified

401 - Unauthorized

403 - Forbidden

404 - The request will return 404 NOT FOUND if there is no event stored in the database with the given event ID

500 - Internal Server Error

Parameters:

eventId - eventId of an event

ifNoneMatch - ETag hash of previous request to allow caching

Returns:

Base event object which can be type-casted by user into either Mindsphere standard event or Custom event using the instanceOf keyword

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

getEventById

public BaseEvent getEventById(String eventId)
                       throws MindsphereException

Returns an Event with the specified ID

200 - OK

304 - Not Modified

401 - Unauthorized

403 - Forbidden

404 - The request will return 404 NOT FOUND if there is no event stored in the database with the given event ID

500 - Internal Server Error

Parameters:

eventId - eventId of an event

Returns:

Base event object which can be type-casted by user into either Mindsphere standard event or Custom event using the instanceOf keyword

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

createStandardEvent

public MindsphereStandardEvent createStandardEvent(MindsphereStandardEvent standardEvent)
                                            throws MindsphereException

Creates a Mindsphere Standard event with the provided. A standard event has 5 additional fields besides the fields defined in the Event data model:

• description (string, not required, not filterable, updatable)
• severity (integer, not required, filterable, updatable)
• code (string, not required, filterable, updatable)
• source (string, not required, filterable, updatable)
• acknowledged (boolean, not required, filterable, updatable)

201 - Created

400 - The request will return 400 BAD REQUEST in following cases:

• severity is not between the 1-99 number range
• code is longer than 16 characters
• source is longer than 255 characters
• description is longer than 255 characters
• entityId is not given in the request
• timestamp is not given in the request body
• timestamp is not a valid UTC timestamp
• timestamp plus the TTL (defined by the events type) is less than the current timestamp
• correlationId is longer than 36 characters Custom Events
• creating event having base event type

401 - Unauthorized

403 - Forbidden

404 - The request will return 404 NOT FOUND in case the given event type does not exist

500 - Internal Server Error

Parameters:

standardEvent - StandardEvent object content to be created

Returns:

Created standard event

Throws:

MindsphereException - If an error occurs while attempting to invoke the API

createStandardEvent

public MindsphereStandardEvent createStandardEvent(String standardEventJson)
                                            throws MindsphereException

Creates a Mindsphere Standard Event with the provided. A standard event has 5 additional fields besides the fields defined in the Event data model:

• description (string, not required, not filterable, updatable)
• severity (integer, not required, filterable, updatable)
• code (string, not required, filterable, updatable)
• source (string, not required, filterable, updatable)
• acknowledged (boolean, not required, filterable, updatable)

201 - Created

400 - The request will return 400 BAD REQUEST in following cases:

• severity is not between the 1-99 number range
• code is longer than 16 characters
• source is longer than 255 characters
• description is longer than 255 characters
• entityId is not given in the request
• timestamp is not given in the request body
• timestamp is not a valid UTC timestamp
• timestamp plus the TTL (defined by the events type) is less than the current timestamp
• correlationId is longer than 36 characters Custom Events
• creating event having base event type

401 - Unauthorized

403 - Forbidden

404 - The request will return 404 NOT FOUND in case the given event type does not exist

500 - Internal Server Error

Parameters:

standardEventJson - Json string format of StandardEvent event to be created

Returns:

Created standard event

Throws:

MindsphereException - If an error occurs while attempting to invoke the API

createCustomEvent

public CustomEvent createCustomEvent(CustomEvent customEvent)
                              throws MindsphereException

Creates custom event with the provided content.

201 - Created

400 - The request will return 400 BAD REQUEST in following cases:

• entityId is not given in the request
• timestamp is not given in the request body
• timestamp is not a valid UTC timestamp
• timestamp plus the TTL (defined by the events type) is less than the current timestamp
• correlationId is longer than 36 characters
• creating event having base event type
• required field is missing
• incompatible value to a custom field

401 - Unauthorized

403 - Forbidden

404 - The request will return 404 NOT FOUND in cases you can find below. - The given event type does not exist

500 - Internal Server Error

Parameters:

customEvent - CustomEvent to be created

Returns:

Created Custom Event

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

createCustomEvent

public CustomEvent createCustomEvent(String customEventJson)
                              throws MindsphereException

Creates custom event with the provided content.

201 - Created

400 - The request will return 400 BAD REQUEST in following cases:

• entityId is not given in the request
• timestamp is not given in the request body
• timestamp is not a valid UTC timestamp
• timestamp plus the TTL (defined by the events type) is less than the current timestamp
• correlationId is longer than 36 characters
• creating event having base event type
• required field is missing
• incompatible value to a custom field

401 - Unauthorized

403 - Forbidden

404 - The request will return 404 NOT FOUND in cases you can find below. - The given event type does not exist

500 - Internal Server Error

Parameters:

customEventJson - Json string representing CustomEvent to be created

Returns:

Created Custom Event

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

createEvent

public BaseEvent createEvent(String eventJson)
                      throws MindsphereException

Creates a Mindsphere Standard event or Custom event depending on the provided content. If no typeId is given in the request, then a MindsphereStandardEvent will be created.

201 - Created

400 - The request will return 400 BAD REQUEST in following cases:

• severity is not between the 1-99 number range
• code is longer than 16 characters
• source is longer than 255 characters
• description is longer than 255 characters
• entityId is not given in the request
• timestamp is not given in the request body
• timestamp is not a valid UTC timestamp
• timestamp plus the TTL (defined by the events type) is less than the current timestamp
• correlationId is longer than 36 characters
• creating event having base event type
• required field is missing
• incompatible value to a custom field

401 - Unauthorized

403 - Forbidden

404 - The request will return 404 NOT FOUND in cases you can find below. - The given event type does not exist

500 - Internal Server Error

Parameters:

eventJson - Json string representing event to be created

Returns:

Base event object which can be type-casted by user into either Mindsphere standard event or Custom event depending on the type of event being created

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

updateStandardEvent

public MindsphereStandardEvent updateStandardEvent(String eventId,
                                                   String standardEventJson,
                                                   String ifMatch)
                                            throws MindsphereException

Update an existing Mindsphere Standard Event specified by ID.

200 - Updated

400 - The request will return 400 BAD REQUEST in following cases: you can find

• Updating a field with invalid value
• Updating fields that are not updatable (typeId, correlationId, timestamp, entityId, etc.)
• Updating without required field in input
• Updating without typeId
• Updating a required field to null

401 - Unauthorized

403 - Forbidden

404 - The request will return 404 BAD REQUEST on attempting to update a non-existing event

409 - Conflict

412 - Precondition Failed

500 - Internal Server Error

Parameters:

eventId - ID of an event

ifMatch - Used for optimistic concurrency control

standardEventJson - Json string representing standard Event content to be updated

Returns:

Updated standard event

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

updateStandardEvent

public MindsphereStandardEvent updateStandardEvent(String eventId,
                                                   MindsphereStandardEvent standardEvent,
                                                   String ifMatch)
                                            throws MindsphereException

Update an existing Mindsphere Standard Event specified by ID.

200 - Updated

400 - The request will return 400 BAD REQUEST in following cases: you can find

• Updating a field with invalid value
• Updating fields that are not updatable (typeId, correlationId, timestamp, entityId, etc.)
• Updating without required field in input
• Updating without typeId
• Updating a required field to null

401 - Unauthorized

403 - Forbidden

404 - The request will return 404 BAD REQUEST on attempting to update a non-existing event

409 - Conflict

412 - Precondition Failed

500 - Internal Server Error

Parameters:

eventId - ID of an event

ifMatch - Used for optimistic concurrency control

standardEvent - JStandard Event content to be updated

Returns:

Updated standard event

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

updateCustomEvent

public CustomEvent updateCustomEvent(String eventId,
                                     String customEventJson,
                                     String ifMatch)
                              throws MindsphereException

Update an existing custom event specified by ID.

200 - Updated

400 - The request will return 400 BAD REQUEST in following cases:

• Updating a field with invalid value
• Updating fields that are not updatable (typeId, correlationId, timestamp, entityId, etc.)
• Updating without required field in input
• Updating without typeId
• Updating a required field to null
• Updating a custom field with incompatible type

401 - Unauthorized

403 - Forbidden

404 - The request will return 404 BAD REQUEST on attempting to update a non-existing event

409 - Conflict

412 - Precondition Failed

500 - Internal Server Error

Parameters:

eventId - ID of an event

ifMatch - Used for optimistic concurrency control

customEventJson - Json string representing custom Event content to be updated

Returns:

Updated Custom Event

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

updateCustomEvent

public CustomEvent updateCustomEvent(String eventId,
                                     CustomEvent customEvent,
                                     String ifMatch)
                              throws MindsphereException

Update an existing custom event specified by ID.

200 - Updated

400 - The request will return 400 BAD REQUEST in following cases:

• Updating a field with invalid value
• Updating fields that are not updatable (typeId, correlationId, timestamp, entityId, etc.)
• Updating without required field in input
• Updating without typeId
• Updating a required field to null
• Updating a custom field with incompatible type

401 - Unauthorized

403 - Forbidden

404 - The request will return 404 BAD REQUEST on attempting to update a non-existing event

409 - Conflict

412 - Precondition Failed

500 - Internal Server Error

Parameters:

eventId - ID of an event

ifMatch - Used for optimistic concurrency control

customEvent - Custom Event content to be updated

Returns:

Updated Custom Event

Throws:

MindsphereException - if an error occurs while attempting to invoke the API

updateEvents

public BaseEvent updateEvents(String eventId,
                              String eventJson,
                              String ifMatch)
                       throws MindsphereException

Update an existing event specified by ID.

200 - Updated

400 - The request will return 400 BAD REQUEST in following cases:

• Updating a field with invalid value
• Updating fields that are not updatable (typeId, correlationId, timestamp, entityId, etc.)
• Updating without required field in input
• Updating without typeId
• Updating a required field to null
• Updating a custom field with incompatible type

401 - Unauthorized

403 - Forbidden

404 - The request will return 404 BAD REQUEST on attempting to update a non-existing event

409 - Conflict

412 - Precondition Failed

500 - Internal Server Error

Parameters:

eventId - ID of an event

ifMatch - Used for optimistic concurrency control

eventJson - Json string repesenting the event content to be updated

Returns:

Updated Event as a BaseEvent which can then be type-casted by user into either Mindsphere standard event or Custom event using the instanceOf keyword

Throws:

MindsphereException - if an error occurs while attempting to invoke the API