Browse images

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.

:::note 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

:::

:::note handler features

can be combined with handler uploading an image Default parameters
can be combined with handler displaying an image Simple
uses default parameters to fetch page item attribute Image GET URL from the plug-in access token

:::

:::note handler features

must be combined with handler uploading an image Custom parameters
can be combined with handler displaying an image Simple
uses default parameters to fetch page item attribute Image GET URL from the plug-in access token
uses custom parameter folder to save additional information about an image in the database
requires definining custom parameter using Initialization JavaScript Code and option imageManagerLoadParams or using the supporting dynamic action plug-in Image Browser Parameters

:::

:::note 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:

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

Handler definition

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

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

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

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

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;

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;

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

  /* default query parameters computed on page load */
  v_param_accessToken   varchar2(32767) := :accessToken;
  v_param_sessionId     varchar2(32767) := :sessionId;
  v_param_filename      varchar2(32767) := :filename;

  /* custom query parameter "folder" */
  //highlight-next-line
  v_custom_folder       varchar2(32767) := :folder;
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;

  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
      folder         = v_custom_folder
      and 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;

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.

[
  { "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" }
]

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

[
  { "url":"https://example-domain.com/ords/workspacename/customrest/display-simple/29780" },
  { "url":"https://example-domain.com/ords/workspacename/customrest/display-simple/29781" },
  { "url":"https://example-domain.com/ords/workspacename/customrest/display-simple/29782" }
]

[
  { "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.