Getting a KiiObject

There are two methods to get KiiObjects on Kii Cloud: getting a specific KiiObject by ID or URI and getting a bunch of KiiObjects that meet a condition within a bucket by querying KiiObjects. This topic explains how to get a KiiObject by ID or URI.

Either method allows you to get data such as key-value pairs in a KiiObject. See Getting a Key-value Pair for getting key-value pairs from an obtained KiiObject.

In order to get a KiiObject by ID or URI, you need to save the ID or URI of a KiiObject somewhere when it is created. You can get the KiiObject with the saved ID or URI later.

Using a KiiObject ID

Getting a KiiObject ID

To get a KiiObject ID, read the uuid property of the target KiiObject.

Swift 3:

// Get the ID of an existing KiiObject.
let id = object!.uuid

Objective-C:

// Get the ID of an existing KiiObject.
NSString *id = object.uuid;

Referencing a KiiObject by ID

First, execute the createObject(withID:) method of the bucket where the KiiObject is stored with the ID. This will create an instance of the KiiObject.

Swift 3:

  • // Instantiate a KiiObject in a bucket "_app_bucket_" in the application scope.
    let bucket = Kii.bucket(withName: "_app_bucket_")
    let object = bucket.createObject(withID: id)
    
    do {
      // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
      try object.refreshSynchronous()
    } catch let error as NSError {
      // Handle the error.
      return
    }
  • // Instantiate a KiiObject in a bucket "_app_bucket_" in the application scope.
    let bucket = Kii.bucket(withName: "_app_bucket_")
    let object = bucket.createObject(withID: id)
    
    // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
    object.refresh { (object : KiiObject?, error : Error?) -> Void in
      if error != nil {
        // Handle the error.
        return
      }
    }

Objective-C:

  • NSError *error = nil;
    
    // Instantiate a KiiObject in a bucket "_app_bucket_" in the application scope.
    KiiBucket *bucket = [Kii bucketWithName:@"_app_bucket_"];
    KiiObject *object = nil;
    @try {
      object = [bucket createObjectWithID:id];
    }
    @catch (NSException *exp) {
      // The KiiObject ID is invalid.
      return;
    }
    
    // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
    [object refreshSynchronous:&error];
    if (error != nil) {
      // Handle the error.
      return;
    }
  • NSError *error = nil;
    
    // Instantiate a KiiObject in a bucket "_app_bucket_" in the application scope.
    KiiBucket *bucket = [Kii bucketWithName:@"_app_bucket_"];
    KiiObject *object = nil;
    @try {
      object = [bucket createObjectWithID:id];
    }
    @catch (NSException *exp) {
      // The KiiObject ID is invalid.
      return;
    }
    
    // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
    [object refreshWithBlock:^(KiiObject *object, NSError *error) {
      if (error != nil) {
        // Handle the error.
        return;
      }
    }];

The KiiObject ID is unique only within a bucket. Therefore, when instantiating a KiiObject, specify the target bucket explicitly as shown in the sample code above. Note that there could be multiple KiiObjects with the same ID in other buckets. See Object ID and URI for more discussion.

The ID assigned by Kii Cloud is in the UUID format. If you choose to have your mobile app to assign an ID to a KiiObject, the assigned IDs remain in the specified format.

After a KiiObject is instantiated, execute the refresh(_:) method and then access the key-value pairs in the KiiObject. By executing the refresh(_:) method, the latest KiiObject data is fetched from Kii Cloud and the local KiiObject is refreshed with the latest data. You need to refresh the KiiObject instance explicitly, or it will not be updated with the latest data.

Using a KiiObject URI

Getting a KiiObject URI

To get a KiiObject URI, read the objectURI property of the target KiiObject.

Swift 3:

// Get the URL of an existing KiiObject.
let uri = object!.objectURI

Objective-C:

// Get the URL of an existing KiiObject.
NSString *uri = object.objectURI;

Referencing a KiiObject by URI

First, execute the KiiObject(URI:) method with the URI. This will create an instance of the KiiObject.

Swift 3:

  • // Instantiate a KiiObject.
    let object = KiiObject(uri: uri)!
    
    do {
      // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
      try object.refreshSynchronous()
    } catch let error as NSError {
      // Handle the error.
      return
    }
  • // Instantiate a KiiObject.
    let object = KiiObject(uri: uri)!
    
    // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
    object.refresh { (object : KiiObject?, error : Error?) -> Void in
      if error != nil {
        // Handle the error.
        return
      }
    }

Objective-C:

  • NSError *error = nil;
    
    // Instantiate a KiiObject.
    KiiObject *object = [KiiObject objectWithURI:uri];
    
    // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
    [object refreshSynchronous:&error];
    if (error != nil) {
      // Handle the error.
      return;
    }
  • NSError *error = nil;
    
    // Instantiate a KiiObject.
    KiiObject *object = [KiiObject objectWithURI:uri];
    
    // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
    [object refreshWithBlock:^(KiiObject *object, NSError *error) {
      if (error != nil) {
        // Handle the error.
        return;
      }
    }];

The KiiObject URI contains the information about the bucket that the KiiObject belongs to. Therefore, you do not need to specify the target bucket explicitly as shown in the sample code above. See Object ID and URI for more discussion.

After a KiiObject is instantiated, execute the refresh(_:) method and then access the key-value pairs in the KiiObject. By executing the refresh(_:) method, the latest KiiObject data is fetched from Kii Cloud and the local KiiObject is refreshed with the latest data. You need to refresh the KiiObject instance, or it will not be updated with the latest data.

Note that a KiiObject that is instantiated with the KiiObject(URI:) method does not have its ID locally until the refresh(_:) method is executed. Make sure to execute the refresh(_:) method before getting the KiiObject ID.