refreshMetadata

Reload latest metadata from the backend server. If the metadata was previously loaded (or was obtained from generated proxy classes), then a compatibility check is performed. If the latest metadata is not compatible with the previous metadata, {@link com.sap.cloud.mobile.kotlin.odata.csdl.CsdlException} will be thrown. If the latest metadata is compatible with the previous metadata, the latest metadata will be applied. It is generally recommended to use this function during application startup to check if the server's metadata has been updated since the client application was constructed. If an application wishes to use the data service for actions or updates, while refreshing the metadata in another thread, the code using the data service for actions or updates should perform those operations while holding a read lock on the {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#metadataLock DataServiceAsync.metadataLock}. Execution of functions or queries will automatically obtain a read lock on {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#metadataLock DataServiceAsync.metadataLock}.

Compatible metadata changes include:

• Adding structural/navigation properties to complex/entity types.
• Adding new types (enumeration, simple, complex, entity).
• Adding new entity sets or singletons.
• Adding new actions or functions.
• Adding an action parameter that is nullable to the end of the parameter list.

Other additions, changes, and removals are considered incompatible by default, including:

• Adding members to an enumeration type.
• Changing the base type for any type.
• Changing the value of an enumeration member.
• Changing the type (or nullability) of any structural/navigation property.
• Changing the type (or nullability) of any action/function parameter or result.
• Removing the definition of a model element.
• Removing members from an enumeration type.
• Removing structural/navigation properties from a complex/entity type.

Addition of enumeration members can be pre-approved by a caller using the dynamic API before calling refreshMetadata (see {@link com.sap.cloud.mobile.kotlin.odata.csdl.CsdlDocument#hasOpenEnumerations CsdlDocument.hasOpenEnumerations}). If an application uses generated proxy classes, then generating them with the "-open:enumerations" option will automate the necessary pre-approval. The hasOpenEnumerations flag should only be explicitly set when using the dynamic API. Explicitly setting the hasOpenEnumerations flag when using generated proxy classes (generated without the "-open:enumerations" option) could result in runtime exceptions.

Changes to model elements can be pre-approved by a caller using the dynamic API before calling refreshMetadata (see {@link com.sap.cloud.mobile.kotlin.odata.csdl.CsdlDocument#canChangeAnything CsdlDocument.canChangeAnything}). Applications using generated proxy classes should not pre-approve such changes, as they are likely to result in application instability. For example, if a property's data type is changed, it could result in runtime exceptions since proxy class properties have a pre-determined type that is embedded into the application's compiled code.

Removal of model elements can be pre-approved by the caller before calling refreshMetadata (see {@link com.sap.cloud.mobile.kotlin.odata.csdl.CsdlDocument#canRemoveAnything CsdlDocument.canRemoveAnything}), or preferably by setting the canBeRemoved flag on model elements that the application is prepared for the removal of. Application developers should take care not to pre-approve the removal of model elements unless the application is coded to check at runtime for the possible removal of those elements. The allowance for removals is intended to support "newer" versions of client applications communicating with "older" service implementations but in the general case may require the application to have some embedded knowledge of the changes that were made to the service metadata between the older and newer service implementations. If a newer client application makes unconditional use of a model element that did not exist in an older service implementation, then the non-existence of that model element after calling refreshMetadata could result in runtime exceptions.

If refreshMetadata succeeds, then any added model elements will have isExtension == true, and any removed model elements will have isRemoved == true. Changed model elements will not be distinguishable.

See Also:

{@link com.sap.cloud.mobile.kotlin.odata.Property#isExtension Property.isExtension}, {@link com.sap.cloud.mobile.kotlin.odata.StructureType#extensionProperties StructureType.extensionProperties}, {@link com.sap.cloud.mobile.kotlin.odata.StructureType#isExtension StructureType.isExtension}, {@link com.sap.cloud.mobile.kotlin.odata.SimpleType#isExtension SimpleType.isExtension}, {@link com.sap.cloud.mobile.kotlin.odata.EnumType#isExtension EnumType.isExtension}, {@link com.sap.cloud.mobile.kotlin.odata.DataMethod#isExtension DataMethod.isExtension}, {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#isExtension EntitySet.isExtension}.