# Copyright 2006-2008 The FLWOR Foundation.
# 
# 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.
#



Zorba Error Notification Internal API

proposal: Daniel Turcanu @ IPDEVEL 10-july 2007




The error API is the API to be used by the ZORBA xquery engine when it 
needs to generate an error,warning, notification message so on. This API
should be easy to use, flexible and as straightforward as possible for 
the programmer.
One special requirement is of internationalization, the error handling module
should be able to pass the messages to the user in different languages. 
The method of passing the errors to the user is not established yet and is
not discussed here.

What is the interface so far:

The error API is composed of two main classes

class error_messages;///this is actually a base minimal class
class ZorbaErrorAlerts;



Class ZorbaErrorAlerts 



The class ZorbaErrorAlerts is of most interest for the programmer because
it contains the static functions to be called when an alert is needed (such
as error, warning, notification message, ask user to choose something).
This object should be implemented as singleton, because it has static members
and must be constructed with a reference to an instance of error_messages object.

The functions are:

	static void error_alert( const error_messages::errcode,///one of predefined error messages in errors.h 
										///(class error_messages)
					const yy:location loc, ///position in xquery code
					bool is_fatal, ///recoverable (continue execution) ? fatal (throw error)?
					const string param1,///some error specific params
					const string param2
					);

	static void warning_alert( const error_messages::warning_code,///defined in 
					const yy:location loc, 
					const string param1,
					const string param2
					);

	static void notify_event( const error_messages::NotifyEvent_code notif_event,
					const string param1,
					const string param2
					);

	///return the index of the option chosen by user
	static int ask_user( const error_messages::AskUserString ask_string,
				const error_messages::AskUserStringOptions ask_string_options,
				const string param1,
				const string param2
				);


	//errors and trace messages generated by the xquery code itself
	///call to fn:error()
	static void user_error (class qname *err_qname,///optional
					const std::string description,//optional
					const std::vector<class item*> *items);//optional
	///call to fn:trace()
	static void user_trace ( const std::vector<class item*> *items,
					const std::string label);


a) Function error_alert() 

is for generating errors defined in enum error_messages::errcode.
The parameter is_fatal will choose if the execution can go on or must
end immediately. Most of the errors at runtime will be fatal and some
of the errors at compile time will be non-fatal.
The error codes are the ones defined in http://www.w3.org/TR/xquery/#id-errors 
plus maybe some programmer defined internal errors.
The errors will be translated into text form by the object error_messages,
which takes care of the internationalization.
When the programmer defines a new error/warning/... he must define
its ID and textual form in english. The model for doing that is not yet specified.

Parameter yy::location gives the position in xquery source file.

Parameters param1 and param2 are specific for each error code.
They will be used for constructing the textual form of the error in an
yet unspecified way.


b) Function warning_alert()

is for generating warnings defined in enum error_messages::warning_code.
These are by definition non-fatal.
The XQuery spec does not define any warning to be issued, so this remains
entirely on programmer decision.
The external API (to be designed) will have an option to disable warning
generation.

c) Function notify_event()

is for generating informative messages, for example "Optimizer started/ended",
"Compile time xx milisec" and so on.
The external API should provide the mechanism to switch messages off.

d) Function ask_user()

will send a question to the user and a list of options to choose.
I am not sure about the usefullness of this function, but it's better
to be there. Maybe it will be used some times during compilation.


e) Function user_error()

is the error raised by the xquery source code as the fn:error().
This function is solely for being called when processing the 
fn:error() xquery function.

f) Function user_trace()

is the informative message sent by the xquery source code by fn:trace().
This function is solely for being called when processing the 
fn:trace() xquery function.



Class error_messages 

This class defines the enums for identifying alerts.
The translation from the alert IDs into textual form will be done
by classes that are derived from this class and implement the following
virtual functions:

	virtual std::string err_decode(enum errcode);
	virtual std::string warning_decode(enum warning_code);
	virtual std::string notify_event_decode(enum NotifyEvent_code);
	virtual std::string ask_user_decode(enum AskUserString_code);
	virtual std::string ask_user_options_decode(enum AskUserStringOptions_code);

These functions maybe will return more than just one string, maybe there
will be a need for more informations on alerts. At least the string should be UNICODE
and not ASCII. This remains to be determined.


The main derived class is class errors_english.
This class translates all the alerts into english text and it should be provided
with final ZORBA package. This class provides embeded translation, that is, is compiled
inside the ZORBA engine.
The application developer who uses ZORBA might choose to implement a different translator
class, with a different language, following the model of class errors_english. 
At runtime, the programmer must construct on object of that class and pass it 
to class ZorbaErrorAlerts.


Another class derived from error_messages is class errors_string_table.
This class should provide translation from alert ID to textual form based on
a string table file to be given at runtime. 
The format of the string table file is to be determined.





What are the modifications to existing code:

The class errors was renamed to error_messages and the enums 
		enum warning_code
		enum NotifyEvent_code
		enum AskUserString_code
		enum AskUserStringOptions_code
were added to it.

Class error_handler is to be dropped.

Class xqp_exception maybe will be kept but all its derivations are of no use.
The macros XQP_EXCEPTION_MACRO, BAD_ARG_MACRO, NULL_POINTER_MACRO and so on
will be dropped.

The existing code uses the throw xqp_exception as the error generation mechanism.
This will be replaced with appropiate calls to ZorbaErrorAlerts::error_alert() 
or warning_alert() and such.

