EntityValue

Decode the encoded data from the Decoder object and insantiate a new EntityValue object from it.

Encode the object instance

open func encodeEntityValueExample() throws -> Void {
let provider = OnlineODataProvider(serviceName: "NorthwindService",
    serviceRoot: "http://services.odata.org/V4/Northwind/Northwind.svc/")
let service = NorthwindService(provider: provider)

// Download the entity by proxy classes which will be encoded
let query = DataQuery()
let entityValueToBeEncoded = try service.fetchEmployees(matching: query).first

// Encode the EntityValue with JSONEncoder (other encoder exists such as PropertyListEncoder)
let encoder = JSONEncoder()
if let encodedEntityValue = try? encoder.encode(entityValueToBeEncoded) {
    if let json = String(data: encodedEntityValue, encoding: .utf8){
        print(json)
    }

    // Decoding
    // JSONDecoder is used, but other decoders are available, such as PropertyListDecoder
    let decoder = JSONDecoder()
    // Add typeInfo to the decoder
    decoder.userInfo[CSDLDocument.csdlInfoKey] = service.metadata

    // Decode
    let decodedEntityValue = try? decoder.decode(EntityValue.self,
        from: encodedEntityValue)
}
}

Example of encode/decode of an EntityValue using dynamic API

open func encodeEntityValueExample() throws -> Void {
    let provider = OnlineODataProvider(serviceName: "NorthwindService",
        serviceRoot: "http://services.odata.org/V4/Northwind/Northwind.svc/")
    let service = DataService(provider: provider)

    // Explicitly load metadata, it must be cached manually. The reason is that type infos
    // will not be implicitly encoded. The dataservice's metadata contains all such infos,
    // so it must be cached, and parsed later at decoding.
    service.serviceOptions.csdlOptions = ( service.serviceOptions.csdlOptions |
        CSDLOption.retainResolvedText | CSDLOption.retainOriginalText )
    try service.loadMetadata()
    let metadataCachedAsString = service.metadata.resolvedText!

    // Get the entity to be encoded by dynamic API
    let peopleEntitySet = try service.entitySet(withName: "Employees")
    let query = DataQuery().from(peopleEntitySet)
    let entityValueToBeEncoded = try service.executeQuery(query).entityList().first

    // Encode the EntityValue with JSONEncoder (other encoder exists such as PropertyListEncoder)
    let encoder = JSONEncoder()
    if let encodedEntityValue = try? encoder.encode(entityValueToBeEncoded) {
        if let json = String(data: encodedEntityValue, encoding: .utf8){
            print(json) // Check
        }

        // Decoding
        // JSONDecoder is used, but other decoders are available, such as PropertyListDecoder
        let decoder = JSONDecoder()

        // Get type infos from cached metadata by parsing it to CSDLDocument
        let parser: CSDLParser = CSDLParser()
        parser.csdlOptions = (CSDLOption.processMixedVersions | CSDLOption.retainOriginalText |
            CSDLOption.resolveUndefinedTerms)
        var csdlDocument: CSDLDocument = parser.parseInProxy(metadataCachedAsString, url: "")

        // Add typeInfo to the decoder
        decoder.userInfo[CSDLDocument.csdlInfoKey] = csdlDocument

        // Decode
        let decodedEntityValue = try? decoder.decode(EntityValue.self, from: encodedEntityValue)
    }
}

Paths (usually of type Property) to which deepCreate or deepUpdate should cascade.

Construct a new entity value. This constructor is intended for use by custom entity value subclasses. Use ofType for regular construction.

true if create/update/delete conflicts (duplicate key conflicts or optimistic concurrency conflicts) for this entity should not log/throw exceptions.

Set isDraft to true.

Entity tag from backend system (may differ from entityTag for entities used with SQLDatabaseProvider).

Bind an entity to a property of the current entity. This can be used before DataService.createEntity or DataService.updateEntity to create or update the bindings of navigation properties.

Example using proxy classes

open func bindEntityExample() throws -> Void {
    let service = self.service
    let categoryQuery = DataQuery().top(1).expand(Category.products)
    let category = try service.fetchCategory(matching: categoryQuery)
    let productQuery = DataQuery().top(1)
    let product = try service.fetchProduct(matching: productQuery)
    category.bindEntity(product, to: Category.products)
    try service.updateEntity(category)
}

Example using dynamic API

open func bindEntityExample() throws -> Void {
    let service = self.service
    let categoriesEntitySet = service.entitySet(withName: "Categories")
    let productsEntitySet = service.entitySet(withName: "Products")
    let categoryEntityType = categoriesEntitySet.entityType
    let productsProperty = categoryEntityType.property(withName: "Products")
    let categoryQuery = DataQuery().from(categoriesEntitySet).top(1)
        .expand(productsProperty)
    let category = try service.executeQuery(categoryQuery).requiredEntity()
    let productQuery = DataQuery().from(productsEntitySet).top(1)
    let product = try service.executeQuery(productQuery).requiredEntity()
    category.bindEntity(product, to: productsProperty)
    try service.updateEntity(category)
}

The canonical URL for this entity, relative to the service root URL. Uses OData V4 URL conventions.

Compare two entities for sorting by primary key.

Copy the values of all key properties from a specified entity into this entity.

Copy structural/dynamic property values from source entity value into this entity value.

Data type with a DataType.code of DataType.ENTITY_VALUE.

If this entity is marked for deep update, should the deep update use delta payload format? Defaults to false.

Can be used to hold the “last modified time” for a changed entity.

The edit link for this value, preferably relative to the service root URL. If an entity does not have an explicit edit link, then writers should use the valuePath, or if that is not set, then a canonical URL (refer to the OData specification).

OData entity id (IRI) for this entity, preferably relative to the service root URL. If an entity does not have an explicit entity id, then callers should use the canonical URL.

The entity key for this value.

The entity set for this value.

Server-generated entity tag for this entity. If non-null, it is used for conflict detection during DataService.updateEntity and DataService.deleteEntity calls.

The entity type metadata for this value (dataType cast to EntityType).

Set a flag to mark this entity to be copied by a subsequent DataService.makeDraftCopy call, in preparation for a later DataService.activateDraft call that will create the entity. Set cascadePaths to paths to nil.

Set a flag to mark this entity to be copied by a subsequent DataService.makeDraftCopy call, in preparation for a later DataService.activateDraft call that will create the entity. Set cascadePaths to paths if paths is non-empty, otherwise set cascadePaths to nil. If paths is empty, the subsequent deep create should include composition children (recursively) which are specified with on-delete-cascade.

Set a flag to mark this entity to be copied by a subsequent DataService.makeDraftCopy call, in preparation for a later DataService.activateDraft call that will update the entity. Set cascadePaths to paths if paths is non-empty, otherwise set cascadePaths to nil. If paths is empty, the subsequent deep update should include composition children (recursively) which are specified with on-delete-cascade.

Set a flag to mark this entity to be copied by a subsequent DataService.makeDraftCopy call, in preparation for a later DataService.activateDraft call that will update the entity. Set cascadePaths to paths to nil.

Set isDraft to true, and set the primary key for this entity to a value likely to be suitable for a local offline draft. For key properties of type int', this will be a value > 2000000000 offset by an amount determined from current UTC dateTime (month/day/hour/minute/second). For key properties of typelong’, this will be a value > 9000000000000000000 offset by an amount determined from current UTC dateTime (month/day/hour/minute/second). For key properties of type string', 'binary' or 'guid', this will be a random GUID value converted to the appropriate type. For key properties of typestring’ where the Property.maxLength is insufficient to hold a GUID (between 10 and 31 inclusive), then the value will be the string equivalent of the value that would be used for type ‘long’ or ‘int’, whichever should fit. For key properties of type binary' where theProperty.maxLength` is insufficient to hold a complete GUID (less than 16 bytes), then a random GUID value will be truncated to fit. Key properties of any other data type will not be set.

true if this entity has binding-related changes.

true if a create/update/delete conflict was detected for this entity.

true if the entity is related to entities which are local (entities that have local requests executed that have either not been sent or have been sent but not yet downloaded).

true if there are unsent requests in the request queue.

true if the entity is related to entities that have unsent requests in the request queue.

true if this entity is in error state, for example due to the failed backend execution of an uploaded offline create/update/delete operation. If true, then one of isCreated, isUpdated or isDeleted should also be true to indicate the kind of failed operation. In some cases (e.g. system unable to distinguish create from update due to “upsert” behaviour) then isCreated, isUpdated and isDeleted might all be false.

Change the entity set for this entity. Having a non-null entity set is optional if only one entity set in the DataService uses the entity type, but is required (before DataService.createEntity is called) if multiple entity sets use the same entity type.

Example using proxy classes

open func createInSetExample() throws -> Void {
    let service = self.service
    let customer = Customer()
    customer.companyName = "Voyager Inc."
    customer.contactName = "Kathryn Janeway"
    try service.createEntity(customer.inSet(NorthwindService.customers))
}

Example using dynamic API

open func createInSetExample() throws -> Void {
    let service = self.service
    let customersEntitySet = service.entitySet(withName: "Customers")
    let customerEntityType = customersEntitySet.entityType
    let companyNameProperty = customerEntityType.property(withName: "CompanyName")
    let contactNameProperty = customerEntityType.property(withName: "ContactName")
    let customer = EntityValue.ofType(customerEntityType)
    companyNameProperty.setStringValue(in: customer, to: "Voyager Inc.")
    contactNameProperty.setStringValue(in: customer, to: "Kathryn Janeway")
    try service.createEntity(customer.inSet(customersEntitySet))
}

true if this object is an entity binding. The isReference property should also be true for bindings.

true if this object is contained a the navigation property of its parent.

true if this entity has just been created in the local database or backend system.

true if this entity has just been deleted from the local database or backend system.

true if this entity is in a draft state. To enable offline drafts with Mobile Back-End Tools (and Offline OData), add to the EntityType element in the CSDL XML metadata. To enable Fiori-style online drafts with CDS models, add the @odata.draft.enabled annotation to the CDS entity definition.`)

true if a change (create, update or delete) has been submitted to the local database, but not yet synchronized to the backend system.

true if this entity has been newly instantiated, but not yet created, updated or deleted in the local database or backend system.

true if this object is an entity reference. If true, the editLink and/or readLink will be non-null, or the key properties will be available. Non-key properties will not be available.

‘true’ if the entity was already resolved by CsdlDocument’s resolveEntity.

‘true’ if the entity is being resolved by CsdlDocument’s resolveEntity.

true if this entity has just been updated in the local database or backend system.

‘true’ if the entity is being upserted.

Stream link for media entities. Should not be used with non-media entities.

true if the entity must be modified by an update request, even if it is apparently unchanged. This ensures that DataService.updateEntity will force an update in the backend database/system.

true if the entity state must be reloaded (via loadEntity) after a create/update request.

true if operations on this entity should not be locally cascaded to children.

Construct a new entity value of the specified entity type.

Contains the original values for all structural properties of this entity value. Used by DataService.updateEntity to determine the changed properties for PATCH requests.

Parent entity when this entity is to be created as a related child.

Parent property when this entity is to be created as a related child.

The read link for this value, preferably relative to the service root URL. If an entity does not have an explicit read link, then readers should use the valuePath, or if that is not set, then a canonical URL (refer to the OData specification).

The complex type metadata for this value (dataType cast to StructureType).

A system-generated numeric key for this entity. Not guaranteed to be unique. For internal use. Should not be changed by application code.

Remember a snapshot of the values of structural/dynamic properties of this entity in oldEntity. Snapshots are used to detect which properties have changed when an update is to be issued.

Convert this data value to a string. If the dataType is defined by XML Schema Part 2: Datatypes, then the corresponding lexical format is used. JSON format is used for structured values (arrays and objects).

Data type code of the wrapped value, equivalent to dataType.code.

Unbind an entity from a property of the current entity. This can be used before DataService.createEntity or DataService.updateEntity to create or update the bindings of navigation properties.

Example using proxy classes

open func unbindEntityExample() throws -> Void {
    let service = self.service
    let categoryQuery = DataQuery().top(1).expand(Category.products)
    let category = try service.fetchCategory(matching: categoryQuery)
    let products = category.products
    if products.count != 0 {
        let product = products.first!
        category.unbindEntity(product, from: Category.products)
    }
    try service.updateEntity(category)
}

Example using dynamic API

open func unbindEntityExample() throws -> Void {
    let service = self.service
    let categoriesEntitySet = service.entitySet(withName: "Categories")
    let categoryEntityType = categoriesEntitySet.entityType
    let productsProperty = categoryEntityType.property(withName: "Products")
    let categoryQuery = DataQuery().from(categoriesEntitySet).top(1)
        .expand(productsProperty)
    let category = try service.executeQuery(categoryQuery).requiredEntity()
    let products = productsProperty.entityList(from: category)
    if products.length != 0 {
        let product = products.first()
        category.unbindEntity(product, from: productsProperty)
    }
    try service.updateEntity(category)
}

true if the entity was not modified by an update request, because none of its properties were changed by the application before the attempt to update.

Set a flag to mark this entity to be created by a subsequent DataService.activateDraft call. Set cascadePaths to paths to nil.

Set a flag to mark this entity to be created by a subsequent DataService.activateDraft call, or by a DataService.createEntity call that should perform a deep create. Set cascadePaths to paths if paths is non-empty, otherwise set cascadePaths to nil. If paths is empty, the subsequent deep create should include composition children (recursively) which are specified with on-delete-cascade.

Example using proxy classes

open func deepCreateExample() throws -> Void {
    let service = self.service
    let customer = Customer()
    customer.companyName = "Enterprise Inc."
    customer.contactName = "LeVar Burton"
    let order1 = Order()
    let order2 = Order()
    customer.bindEntity(order1, to: Customer.orders)
    customer.bindEntity(order2, to: Customer.orders)
    try service.createEntity(customer.withDeepCreate())
}

Set a flag to mark this entity to be updated by a subsequent DataService.activateDraft call, or by a DataService.updateEntity call that should perform a deep update. Set cascadePaths to paths if paths is non-empty, otherwise set cascadePaths to nil. If paths is empty, the subsequent deep update should include composition children (recursively) which are specified with on-delete-cascade.

Example with proxy classes

open func deepUpdateExample() throws -> Void {
    let service = self.service
    let query = DataQuery().top(1).expand(Customer.orders)
        .filter(Customer.contactName.equal("Beverly Crusher"))
    let customer = try service.fetchCustomer(matching: query)
    let orders = customer.orders
    let firstOrder = orders[0]
    let nextOrder = orders[1]
    let newOrder = Order()
    newOrder.orderDate = GlobalDateTime.now()
    customer.unbindEntity(firstOrder, from: Customer.orders)
    nextOrder.requiredDate = GlobalDateTime.now().plusDays(7)
    customer.bindEntity(newOrder, to: Customer.orders)
    customer.deepUpdateDelta = true
    try service.updateEntity(customer.withDeepUpdate())
}

Change the primary key for this entity.

Set a flag to mark this entity to be updated by a subsequent DataService.activateDraft call. Set cascadePaths to paths to nil.