File: alog-logger.ads

## Documentation

Table of Contents
Class Inheritance Tree

1.     --

2.     --  Copyright (c) 2008,

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.     --

23.     with Ada.Finalization;

24.     with Ada.Unchecked_Deallocation;

25.     with Ada.Strings.Unbounded;

27.     with Alog.FacilitiesTo API docTo specTo body;

28.     with Alog.TransformsTo API docTo specTo body;

29.     with Alog.Controlled_MapTo API docTo specTo body;

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.

34.     package Alog.LoggerTo API docTo specTo body is

36.        type InstanceTo API docTo body (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.

42.        type Handle is access all InstanceTo API docTo specTo body;

43.        --  Handle to logger type.

45.        procedure Attach_FacilityTo API docTo body

46.          (LoggerTo API docTo body   : in out InstanceTo API docTo specTo body;

47.           Facility :        Facilities.HandleTo API docTo spec);

48.        --  Attach a facility to logger instance.

50.        procedure Attach_Default_FacilityTo API docTo body (LoggerTo API docTo body : in out InstanceTo API docTo specTo body);

51.        --  Attach default facility with name Default_Facility_Name to logger

52.        --  instance. If the default facility is already attached do nothing.

54.        procedure Detach_FacilityTo API docTo body

55.          (LoggerTo API docTo body : in out InstanceTo API docTo specTo body;

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.

60.        procedure Detach_Default_FacilityTo API docTo body (LoggerTo API docTo body : in out InstanceTo API docTo specTo body);

61.        --  Detach default facility with name Default_Facility_Name from logger

62.        --  instance. If the default facility is not attached do nothing.

64.        function Facility_CountTo API docTo body (LoggerTo API docTo body : InstanceTo API docTo specTo body) return Natural;

65.        --  Return number of attached facilites.

67.        procedure UpdateTo API docTo body

68.          (LoggerTo API docTo body  : InstanceTo API docTo specTo body;

69.           Name    : String;

70.           Process : not null access

71.             procedure (Facility_Handle : Facilities.HandleTo API docTo spec));

72.        --  Update a specific Facility identified by 'Name'. Call the 'Process'

73.        --  procedure to perform the update operation.

75.        procedure IterateTo API docTo body

76.          (LoggerTo API docTo body  : InstanceTo API docTo specTo body;

77.           Process : not null access

78.             procedure (Facility_Handle : Facilities.HandleTo API docTo spec));

79.        --  Call 'Process' for all attached facilities.

81.        procedure Attach_TransformTo API docTo body

82.          (LoggerTo API docTo body    : in out InstanceTo API docTo specTo body;

83.           Transform :        Transforms.HandleTo API docTo spec);

84.        --  Attach a transform to logger instance.

86.        procedure Detach_TransformTo API docTo body

87.          (LoggerTo API docTo body : in out InstanceTo API docTo specTo body;

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.

92.        function Transform_CountTo API docTo body (LoggerTo API docTo body : InstanceTo API docTo specTo body) return Natural;

93.        --  Return number of attached transforms.

95.        procedure UpdateTo API docTo body

96.          (LoggerTo API docTo body  : InstanceTo API docTo specTo body;

97.           Name    : String;

98.           Process : not null access

99.             procedure (Transform_Handle : Transforms.HandleTo API docTo spec));

100.        --  Update a specific Transform identified by 'Name'. Call the 'Process'

101.        --  procedure to perform the update operation.

103.        procedure IterateTo API docTo body

104.          (LoggerTo API docTo body  : InstanceTo API docTo specTo body;

105.           Process : not null access

106.             procedure (Transform_Handle : Transforms.HandleTo API docTo spec));

107.        --  Call 'Process' for all attached transforms.

109.        procedure ClearTo API docTo body (LTo API docTo body : in out InstanceTo API docTo specTo body);

110.        --  Clear logger instance. Detach and teardown all attached facilities and

111.        --  transforms.

113.        procedure Log_MessageTo API docTo body

114.          (LoggerTo API docTo body : InstanceTo API docTo specTo body;

115.           Source : String := "";

116.           LevelTo API docTo body  : Log_LevelTo API docTo spec;

117.           Msg    : 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.

126.        procedure Free is new Ada.Unchecked_Deallocation

127.          (Object => Facilities.ClassTo API docTo spec,

128.           Name   => Facilities.HandleTo API docTo spec);

129.        --  Free memory allocated by a facility.

131.        procedure Free is new Ada.Unchecked_Deallocation

132.          (Object => Transforms.ClassTo API docTo spec,

133.           Name   => Transforms.HandleTo API docTo spec);

134.        --  Free memory allocated by a transform.

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. .

145.        Default_Facility_Name : constant String := "__Default_Facility";

147.     private

149.        use Ada.Strings.Unbounded;

150.        use Alog.FacilitiesTo API docTo specTo body;

151.        use Alog.TransformsTo API docTo specTo body;

153.        procedure Initialize (Logger : in out InstanceTo API docTo specTo body);

154.        --  Initialize the logger instance.

156.        procedure Finalize (Logger : in out InstanceTo API docTo specTo body);

157.        --  Finalize procedure used to cleanup.

159.        package Map_Of_Transforms_Package is new Alog.Controlled_MapTo API docTo specTo body

160.          (Key_TypeTo API docTo spec       => Unbounded_String,

161.           Element_TypeTo API docTo spec   => Transforms.ClassTo API docTo spec,

162.           Element_HandleTo API docTo spec => Transforms.HandleTo API docTo spec);

164.        package MOTP renames Map_Of_Transforms_Package;

166.        package Map_Of_Facilities_Package is new Alog.Controlled_MapTo API docTo specTo body

167.          (Key_TypeTo API docTo spec       => Unbounded_String,

168.           Element_TypeTo API docTo spec   => Facilities.ClassTo API docTo spec,

169.           Element_HandleTo API docTo spec => Facilities.HandleTo API docTo spec);

171.        package MOFP renames Map_Of_Facilities_Package;

173.        type InstanceTo API docTo spec (Init : Boolean) is new

174.          Ada.Finalization.Limited_Controlled with record

175.           Facilities   : MOFP.MapTo API docTo specTo body;

176.           --  Attached facilities.

178.           Transforms   : MOTP.MapTo API docTo specTo body;

179.           --  Attached transforms.

180.        end record;

182.     end Alog.LoggerTo API docTo specTo body;