What's the different between CreateFile and CreateKey?

[iceboundx]

I found that there are two methods to create an object(file) in Ozone:

1. createKey: https://github.com/apache/ozone/blob/master/hadoop-ozone/client/src/main/java/org/apache/hadoop/ozone/client/protocol/ClientProtocol.java#L338
2. createFile: https://github.com/apache/ozone/blob/master/hadoop-ozone/client/src/main/java/org/apache/hadoop/ozone/client/protocol/ClientProtocol.java#L857

I did not find the difference between the two in both document and the design doc, which made me very confused.
To add to my confusion, after I read the OM source code for both, I found that:

1. createKey just acquires a key path lock when the BucketLayout is OBJECT_STORE or not enable FileSystemPaths: https://github.com/apache/ozone/blob/master/hadoop-ozone/ozone-manager/src/main/java/org/apache/hadoop/ozone/om/request/key/OMKeyCreateRequest.java#L220
   https://github.com/apache/ozone/blob/master/hadoop-ozone/ozone-manager/src/main/java/org/apache/hadoop/ozone/om/lock/OzoneLockProvider.java
2. However, create file acquires a bucket level write lock, which means that it will lock the whole bucket: https://github.com/apache/ozone/blob/master/hadoop-ozone/ozone-manager/src/main/java/org/apache/hadoop/ozone/om/request/file/OMFileCreateRequest.java#L214

So why we have two seprated interface to create keys in OM? What's the different of them? Why file create needs bucket level write lock?
Does bucket-level locking significantly affect performance as concurrency increases?
If someone can give the answer, it would be really appreciated.

[sadanand48]

I think the API's evolved to be the same , createFile got introduced here https://issues.apache.org/jira/browse/HDDS-1300 pre OM HA , The difference was that createKey earlier also was used to create multipart uploads and other OBS related functionality but createFile was specifically called from Ozone FS. Now, I guess multipart uploads have different request response api's so ultimately and the functionality converged b/w createFile & key.
I don't think the keypath lock is enabled too since it is disabled by default in the config so bucket lock is only used for both API's

public static final boolean OZONE_OM_KEY_PATH_LOCK_ENABLED_DEFAULT = false;

[sadanand48]

I looked into the code and could find a difference, The CreateFileRequest has an extra field 'recursive' . The effect of this is that if recursive is true, the parent directory of the file would be created even if it doesn't exist.

This is not true for createKey as it doesn't have a recursive param that the client can set, parent dirs are created for createKey depending on the value of ozone.om.enable.filesystem.paths . This can be set to either true/false in LEGACY buckets. If true, parent dir is created , else parent dir is not created for createKey. For other bucket types, this config doesn't take any effect (for FSO it's always true and OBS false)

I wrote a simple unit test when ozone.om.enable.filesystem.paths = false to depict the difference b/w createFile and createKey

  @Test
  public void testCreateKeyAndCreateFile() throws IOException {
    // ozone.om.enable.filesystem.paths = false
    OzoneBucket bucket =
        TestDataUtil.createVolumeAndBucket(client, BucketLayout.LEGACY);
    String keyName = "a/b/c";
    TestDataUtil.createKey(bucket, keyName, "");
    List<String> keys = new ArrayList<>();
    Iterator<? extends OzoneKey> keyIter = bucket.listKeys("");
    while (keyIter.hasNext()){
      keys.add(keyIter.next().getName());
    }
    // only a single key
    Assert.assertEquals(1,keys.size());
    bucket.deleteKey("a/b/c");
    keys.clear();
    try (OzoneOutputStream oos = bucket.createFile(keyName, 0,
        RatisReplicationConfig.getInstance(HddsProtos.ReplicationFactor.THREE),
        true, true)) {
      oos.flush();
    }
    keyIter = bucket.listKeys("");
    while (keyIter.hasNext()){
      keys.add(keyIter.next().getName());
    }
    // 3 keys for createFile a/, a/b/ , a/b/c even though
    // ozone.om.enable.filesystem.paths = false
    Assert.assertEquals(3,keys.size());
  }

Hope this answers your question!