Method: Aliyun::OSS::OSSObject.find

Defined in:

lib/aliyun/oss/object.rb

.find(key, bucket = nil) ⇒ Object

Returns the object whose key is name in the specified bucket. If the specified key does not exist, a NoSuchKey exception will be raised.

# File 'lib/aliyun/oss/object.rb', line 146

def find(key, bucket = nil)
  # N.B. This is arguably a hack. From what the current OSS API exposes, when you retrieve a bucket, it
  # provides a listing of all the files in that bucket (assuming you haven't limited the scope of what it returns).
  # Each file in the listing contains information about that file. It is from this information that an OSSObject is built.
  #
  # If you know the specific file that you want, OSS allows you to make a get request for that specific file and it returns
  # the value of that file in its response body. This response body is used to build an OSSObject::Value object. 
  # If you want information about that file, you can make a head request and the headers of the response will contain 
  # information about that file. There is no way, though, to say, give me the representation of just this given file the same 
  # way that it would appear in a bucket listing.
  #
  # When fetching a bucket, you can provide options which narrow the scope of what files should be returned in that listing.
  # Of those options, one is <tt>marker</tt> which is a string and instructs the bucket to return only object's who's key comes after
  # the specified marker according to alphabetic order. Another option is <tt>max-keys</tt> which defaults to 1000 but allows you
  # to dictate how many objects should be returned in the listing. With a combination of <tt>marker</tt> and <tt>max-keys</tt> you can
  # *almost* specify exactly which file you'd like it to return, but <tt>marker</tt> is not inclusive. In other words, if there is a bucket
  # which contains three objects who's keys are respectively 'a', 'b' and 'c', then fetching a bucket listing with marker set to 'b' will only
  # return 'c', not 'b'. 
  #
  # Given all that, my hack to fetch a bucket with only one specific file, is to set the marker to the result of calling String#previous on
  # the desired object's key, which functionally makes the key ordered one degree higher than the desired object key according to 
  # alphabetic ordering. This is a hack, but it should work around 99% of the time. I can't think of a scenario where it would return
  # something incorrect.
  
  # We need to ensure the key doesn't have extended characters but not uri escape it before doing the lookup and comparing since if the object exists, 
  # the key on OSS will have been normalized
  key    = key.remove_extended unless key.valid_utf8?
  bucket = Bucket.find(bucket_name(bucket), :marker => key.previous, :max_keys => 1)
  # If our heuristic failed, trigger a NoSuchKey exception
  if (object = bucket.objects.first) && object.key == key
    object 
  else 
    raise NoSuchKey.new("No such key `#{key}'", bucket)
  end
end