Template handler displaying image

This document covers sample implementations for template GET handler displaying uploaded images in the plug-in built-in image browser. All examples displays images from the plug-in table UC_FROALA_SAMPLE_BLOBS. The difference between handlers is complexity of PL/SQL code, whether handler uses default query parameters, custom parameters or uses image checksum to secure display handler.

Simple

handler features

• can be combined with handler uploading an image Simple
• can be combined with handler displaying an image Simple
• doesn't use default parameters and the URL to displaying image handler (page item attribute Image GET URL) is hardcoded in the code

Default parameters

handler features

• must be combined with handler uploading an image Image checksum
• must be combined with handler displaying an image Image checksum
• uses default parameters to fetch page item attribute Image GET URL from the plug-in access token
• uses access token static function encode to create image checksum securing display handler from unauthorized access to images

Requirements

Handler displaying uploaded image must meet the following requirements:

1. must use GET method
2. must be compilable at the run time
3. must return 200 HTTP status
4. must print array of JSON objects describing images

Handler definition

Simple

Attribute	Value
RESTful Service Module	A custom RESTservice
Module Base Path	/customrest/
URI Template	browse-simple
Full URL	https://example-domain.com/ords/workspacename/customrest/browse-simple
Handler Method	GET
Source Type	PL/SQL
Mime Types Allowed	Not defined

Default parameters

Attribute	Value
RESTful Service Module	A custom RESTservice
Module Base Path	/customrest/
URI Template	browse-checksum
Full URL	https://example-domain.com/ords/workspacename/customrest/browse-checksum
Handler Method	GET
Source Type	PL/SQL
Mime Types Allowed	Not defined

Handler parameters

The browse handler doesn't require registering resource parameters as long as REST specific bind variable :status_code is used to set request HTTP status.

Handler Source

Simple

declare
  v_sys_refcursor sys_refcursor;    
  v_url           varchar2(4000);    
begin  
  v_url := 'https://example-domain.com/ords/workspacename/customrest/display/';

  open v_sys_refcursor for  
    select     
      v_url||id as "url"  
    from     
      UC_FROALA_SAMPLE_BLOBS
  ;    
      
  apex_json.write( v_sys_refcursor );
  
  :status_code := 200;

exception
  when others then
    :status_code := 500;

    apex_json.open_object;    
    apex_json.write('error', SQLERRM);  
    apex_json.close_object;  
end;

Default parameters

declare
  v_sys_refcursor       sys_refcursor;    
  v_url                 varchar2(4000);    
  v_access_token        uc_rte_access_token;

  /* default query parameters computed on page load */
  //highlight-start
  v_param_accessToken   varchar2(32767) := :accessToken;
  v_param_sessionId     varchar2(32767) := :sessionId;
  //highlight-end  
begin  
  /* get access token type from encoded token */
  //highlight-next-line
  v_access_token := uc_rte_access_token.create_from_token( p_access_token );

  /* validate access token expiry time */
  if v_access_token.is_valid = 0 then
    raise_application_error(-20001, 'Invalid access token');  
  end if;

  /* get "Image GET URL" value defined for plug-in instance */
  //highlight-next-line
  v_url := v_access_token.url_get_image;

  open v_sys_refcursor for  
    select     
      v_url||id as "url"  
    from     
      UC_FROALA_SAMPLE_BLOBS    
    where
      //highlight-next-line
      session_id = v_param_sessionId
  ;    
      
  apex_json.write( v_sys_refcursor );
  
  :status_code := 200;

exception
  when others then
    if SQLCODE = -20001 then
      :status_code := 403;
    else
      :status_code := 500;

      apex_json.open_object;    
      apex_json.write('error', SQLERRM);  
      apex_json.close_object;  

    end if;
end;

Custom parameters

declare
  v_sys_refcursor sys_refcursor;    
  v_access_token  uc_rte_access_token;
  v_checksum      varchar2(4000);
  v_url           varchar2(4000);

  /* default query parameters computed on page load */
  v_param_accessToken   varchar2(32767) := :accessToken;
begin  
  v_access_token := uc_rte_access_token.create_from_token( v_param_accessToken );

  if v_access_token.is_valid = 0 then
    raise_application_error(-20001, 'Invalid access token');  
  end if;

  apex_json.open_array;

  for image in ( select * from UC_FROALA_SAMPLE_BLOBS ) loop
    //highlight-start
    v_checksum := UC_RTE_ACCESS_TOKEN.encode( image.FILE_NAME||','||image.ID ); 
    v_url := v_access_token.url_get_image||image.FILE_NAME||'?checksum='||v_checksum;
    //highlight-end

    apex_json.open_object;
    apex_json.write('url', v_url);
    apex_json.close_object;

  end loop;

  apex_json.close_array;
  
  :status_code := 200;

exception
  when others then
    if SQLCODE = -20001 then
      :status_code := 403;
    else
      :status_code := 500;

      apex_json.open_object;    
      apex_json.write('error', SQLERRM);  
      apex_json.close_object;  

    end if;
end;

Handler Output

The handler output must be Array of JSON objects describing uploaded images with property url.

Simple

List of images for image browser

[
  { "url":"https://example-domain.com/ords/workspacename/customrest/display-simple/29774" },
  { "url":"https://example-domain.com/ords/workspacename/customrest/display-simple/29775" },
  { "url":"https://example-domain.com/ords/workspacename/customrest/display-simple/29776" }
]

Default parameters

List of images for image browser

[
  { "url":"https://example-domain.com/ords/workspacename/customrest/display-checksum/oracle-apex-png.png?checksum=32FF1661BEE92F605BF4AD4A7FAB22856C04D171465900B9328456D81ECC58FF" },
  { "url":"https://example-domain.com/ords/workspacename/customrest/display-checksum/sample.jpg?checksum=5157A467FCC1A328AD7889E7025022CE85F23C9ECA09BA1980A84D982B93D708" },
  { "url":"https://example-domain.com/ords/workspacename/customrest/display-checksum/baloon.jpg?checksum=87FEBB8EC7CC1D1F00DD5E4D6DF8FFA21DB0409BFF6313483EE2BA513F71F1F9" }
]

Error handling

The plug-in display browse images error as APEX inline page notification error.