-----------------------------------------------------------------------
--  asf-contexts-exceptions -- Exception handlers in faces context
--  Copyright (C) 2011, 2018 Stephane Carrez
--  Written by Stephane Carrez (Stephane.Carrez@gmail.com)
--
--  Licensed under the Apache License, Version 2.0 (the "License");
--  you may not use this file except in compliance with the License.
--  You may obtain a copy of the License at
--
--      http://www.apache.org/licenses/LICENSE-2.0
--
--  Unless required by applicable law or agreed to in writing, software
--  distributed under the License is distributed on an "AS IS" BASIS,
--  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
--  See the License for the specific language governing permissions and
--  limitations under the License.
-----------------------------------------------------------------------

with Ada.Finalization;
with Ada.Exceptions;

with ASF.Events.Exceptions;
private with Util.Strings.Maps;

--  The <b>ASF.Contexts.Exceptions</b> package holds the exception handler framework which
--  allows an application to handle unexpected exceptions and perform specific actions to
--  somehow recover and notify the user.  This package defines a default exception handler
--  which provides some reasonable behavior to report the error or redirect the user to an
--  error page.  Applications can provide their own mechanisms by inheriting from the
--  base exception handler and overriding the <b>Handle</b procedure.
--
--  See JSR 314 - JavaServer Faces Specification 6.2 ExceptionHandler
package ASF.Contexts.Exceptions is

   --  Message used when an exception without a message is raised.
   EXCEPTION_MESSAGE_BASIC_ID    : constant String := "asf.exceptions.unexpected.basic";

   --  Message used when an exception with a message is raised.
   EXCEPTION_MESSAGE_EXTENDED_ID : constant String := "asf.exceptions.unexpected.extended";

   --  ------------------------------
   --  Exception Handler
   --  ------------------------------
   type Exception_Handler is new Ada.Finalization.Limited_Controlled with private;
   type Exception_Handler_Access is access all Exception_Handler'Class;

   --  Take action to handle the <b>Exception_Event</b> instances that have been queued by
   --  calls to <b>Application.Publish_Event</b>.
   --
   --  This operation is called after each ASF phase by the life cycle manager.
   procedure Handle (Handler : in out Exception_Handler);

   --  Set the message id to be used when a given exception name is raised.
   procedure Set_Message (Handler    : in out Exception_Handler;
                          Name       : in String;
                          Message_Id : in String);

   --  ------------------------------
   --  Exception Queue
   --  ------------------------------
   --  The <b>Exception_Queue</b> contains the pending exception events that have been raised
   --  while processing an ASF phase.  The queue contains two lists of events:
   --  <ul>
   --    <li>A list of exceptions that have not yet been processed,
   --    <li>A list of exceptions that were processed by an exception handler
   --  </ul>
   --  When an exception handler has processed an exception event and indicated it as being
   --  <b>PROCESSED</b>, the exception event is moved to the second list.
   type Exception_Queue is new Ada.Finalization.Limited_Controlled with private;

   --  Queue an exception event to the exception handler.  The exception event will be
   --  processed at the end of the current ASF phase.
   procedure Queue_Exception (Queue : in out Exception_Queue;
                              Ex    : in Ada.Exceptions.Exception_Occurrence);

   --  Clear the exception queue.
   overriding
   procedure Finalize (Queue : in out Exception_Queue);

private

   type Exception_Queue is new Ada.Finalization.Limited_Controlled with record
      Unhandled_Events : ASF.Events.Exceptions.Exception_Event_Vector;
      Handled_Events   : ASF.Events.Exceptions.Exception_Event_Vector;
   end record;

   type Exception_Handler is new Ada.Finalization.Limited_Controlled with record
      Mapping : Util.Strings.Maps.Map;
   end record;

end ASF.Contexts.Exceptions;