1--
2--  Copyright (c) 2008-2012,
3--  Reto Buerki, Adrian-Ken Rueegsegger
4--
5--  This file is part of Alog.
6--
7--  Alog is free software; you can redistribute it and/or modify
8--  it under the terms of the GNU Lesser General Public License as published
9--  by the Free Software Foundation; either version 2.1 of the License, or
10--  (at your option) any later version.
11--
12--  Alog is distributed in the hope that it will be useful,
13--  but WITHOUT ANY WARRANTY; without even the implied warranty of
14--  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15--  GNU Lesser General Public License for more details.
16--
17--  You should have received a copy of the GNU Lesser General Public License
18--  along with Alog; if not, write to the Free Software
19--  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
20--  MA  02110-1301  USA
21--
22
23with Ada.Finalization;
24with Ada.Unchecked_Deallocation;
25with Ada.Strings.Unbounded;
26
27with Alog.Facilities;
28with Alog.Transforms;
29with Alog.Controlled_Map;
30
31--  Logger instance. Facilities can be attached to a logger instance in order
32--  to log to different targets simultaneously. A logger provides different
33--  helper functions for logging facilities configuration.
34package Alog.Logger is
35
36   type Instance (Init : Boolean) is tagged limited private;
37   --  Logger instance. The Init discriminant defines whether or not a default
38   --  'stdout' (FD facility without logfile set) is attached automatically.
39   --- Set Init to 'True' if you want to make sure minimal stdout logging is
40   --  possible as soon as a new logger is instantiated.
41
42   type Handle is access all Instance;
43   --  Handle to logger type.
44
45   procedure Attach_Facility
46     (Logger   : in out Instance;
47      Facility :        Facilities.Handle);
48   --  Attach a facility to logger instance.
49
50   procedure Attach_Default_Facility (Logger : in out Instance);
51   --  Attach default facility with name Default_Facility_Name to logger
52   --  instance. If the default facility is already attached do nothing.
53
54   procedure Detach_Facility
55     (Logger : in out Instance;
56      Name   :        String);
57   --  Detach a facility with name 'Name' from logger instance. If the facility
58   --  is not found a Facility_Not_Found exception is raised.
59
60   procedure Detach_Default_Facility (Logger : in out Instance);
61   --  Detach default facility with name Default_Facility_Name from logger
62   --  instance. If the default facility is not attached do nothing.
63
64   function Facility_Count (Logger : Instance) return Natural;
65   --  Return number of attached facilites.
66
67   procedure Update
68     (Logger  : Instance;
69      Name    : String;
70      Process : not null access
71        procedure (Facility_Handle : Facilities.Handle));
72   --  Update a specific Facility identified by 'Name'. Call the 'Process'
73   --  procedure to perform the update operation.
74
75   procedure Iterate
76     (Logger  : Instance;
77      Process : not null access
78        procedure (Facility_Handle : Facilities.Handle));
79   --  Call 'Process' for all attached facilities.
80
81   procedure Attach_Transform
82     (Logger    : in out Instance;
83      Transform :        Transforms.Handle);
84   --  Attach a transform to logger instance.
85
86   procedure Detach_Transform
87     (Logger : in out Instance;
88      Name   :        String);
89   --  Detach a transform with name 'Name' from logger instance. If the
90   --  transform is not found a Transform_Not_Found exception is raised.
91
92   function Transform_Count (Logger : Instance) return Natural;
93   --  Return number of attached transforms.
94
95   procedure Update
96     (Logger  : Instance;
97      Name    : String;
98      Process : not null access
99        procedure (Transform_Handle : Transforms.Handle));
100   --  Update a specific Transform identified by 'Name'. Call the 'Process'
101   --  procedure to perform the update operation.
102
103   procedure Iterate
104     (Logger  : Instance;
105      Process : not null access
106        procedure (Transform_Handle : Transforms.Handle));
107   --  Call 'Process' for all attached transforms.
108
109   procedure Clear (L : in out Instance);
110   --  Clear logger instance. Detach and teardown all attached facilities and
111   --  transforms.
112
113   procedure Log_Message
114     (Logger : Instance;
115      Level  : Log_Level;
116      Msg    : String;
117      Source : String := "");
118   --  Log a message. The Write_Message() procedure of all attached facilities
119   --  is called. Depending on the Log-Threshold set, the message is logged to
120   --  different targets (depending on the facilites) automatically.
121   --
122   --  Prior to actually processing the given log message the policy database
123   --  is inquired if the log message with given source and level should be
124   --  logged.
125
126   procedure Free is new Ada.Unchecked_Deallocation
127     (Object => Facilities.Class,
128      Name   => Facilities.Handle);
129   --  Free memory allocated by a facility.
130
131   procedure Free is new Ada.Unchecked_Deallocation
132     (Object => Transforms.Class,
133      Name   => Transforms.Handle);
134   --  Free memory allocated by a transform.
135
136   Facility_Not_Found        : exception;
137   --  Will be raised if a requested facility is not found.
138   Facility_Already_Present  : exception;
139   --  Will be raised if a facility is already present.
140   Transform_Not_Found       : exception;
141   --  Will be raised if a requested transform is not found.
142   Transform_Already_Present : exception;
143   --  Will be raised if a facility is already present. .
144
145   Default_Facility_Name : constant String := "__Default_Facility";
146
147private
148
149   use Ada.Strings.Unbounded;
150   use Alog.Facilities;
151   use Alog.Transforms;
152
153   procedure Initialize (Logger : in out Instance);
154   --  Initialize the logger instance.
155
156   procedure Finalize (Logger : in out Instance);
157   --  Finalize procedure used to cleanup.
158
159   package Map_Of_Transforms_Package is new Alog.Controlled_Map
160     (Key_Type       => Unbounded_String,
161      Element_Type   => Transforms.Class,
162      Element_Handle => Transforms.Handle);
163
164   package MOTP renames Map_Of_Transforms_Package;
165
166   package Map_Of_Facilities_Package is new Alog.Controlled_Map
167     (Key_Type       => Unbounded_String,
168      Element_Type   => Facilities.Class,
169      Element_Handle => Facilities.Handle);
170
171   package MOFP renames Map_Of_Facilities_Package;
172
173   type Instance (Init : Boolean) is new
174     Ada.Finalization.Limited_Controlled with record
175      Facilities   : MOFP.Map;
176      --  Attached facilities.
177
178      Transforms   : MOTP.Map;
179      --  Attached transforms.
180   end record;
181
182end Alog.Logger;
183