14.7.6 Reading and Writing Binary Content

Read binary content with a Media Resource handler and store uploads using the :body bind variable.

When writing an ORDS handler that needs to return binary content, the simple way is to use a Media Resource type handler. Write a query with two columns that returns a single row. The first column provides the MIME type value, and the second column is the BLOB content to return. Imagine a template /attachments/:id in a module that needs to return an attachment by id. After choosing Media Resource handler type, write the query:

select mime_type, file_contents
  from attachments
 where id = :id

When writing PL/SQL handlers that accept a binary payload, use the :body implicit variable to reference it. For example, suppose you have a template /attachments and you write a POST handler to store an uploaded attachment. You can reference the implicit :content_type and :body parameters to insert the attachment like this:

begin
   your_package.insert_attachment(
       p_mime_type     => :content_type,
       p_file_contents => :body);
   commit;
end;

Caution:

Your handler can only reference the :body variable a single time. Any attempt beyond the first one to read it returns null. So, if you need to reference it in multiple places, assign the bind variable to a local PL/SQL variable first, then reference the variable anywhere you need to.