Message DSL

From OS.bee documentation
Jump to: navigation, search

Purpose

The Message DSL contains all defined message outputs that either will be shown in the application as reponses and notifications (eg. Pop-Up Dialog), or redirected instead as console output (later also possibly persisted in log-files) with a selected list of severity level reports; both resulting of user interactions with the application.

Message Model Files

The Message DSL model unifies the content of all possible output messages and makes them available for other DSL models such as Action DSL. These messages are defined in text files with the file extension .message.

Message model files are made up of the following sections:

  • Package declaration: The message model file must have a unique fully qualified name that can be specified with the keyword package at the beginning of the file.
  • Category section: The category section allows you to group a set of messages and in so forth defines different batches or categories (groups) of different set of messages.
  • Message section: The message section contains the body and content of each message.

package

With the keyword package followed by a qualified name, you define the root element that contains all the other elements. A model can contain multiple packages.

Syntax:

package <package name>[{
	category <category name> {

		message <message name> {
			[ parameter { <parameter-list>	} ]
			[ severity  { <severity-option-list> } ]

			output {<output-option> message text}
		}

		message <another message name> { ... }
		message <another message name> { ... }
		message <another message name> { ... }
	}

	category <another category name> { ... }
} ]


category

With the keyword category followed by an identifier name, you are able to define a group of messages, which can be referenced in other DSL’s via its fully qualified name. It is the first reference level before accessing the messages themselves.


Syntax:

package <package name>[{
	category <category name> { ... }

	category <one category name> { ... }

	category <another category name> { ... }
} ]


Example:

package net.osbee.sample.foodmart.messages {
	category Guest { ... }

	category Employee { ... }

	category Cars { ... } 

	category Guest { ... }

	category Information { ... }
}

Please note that at least one category has to be defined in order to create and/or show messages.

message

With the keyword message followed by a message name identifier you are able to define the basic message structure itself within a group of messages (message category).

Syntax:

package <package name>[{
	category <category name> {

		message <message name> {
			[ parameter { <parameter-list>	} ]
			[ severity  { <severity-option-list> } ]

			output {<output-option> message text}
		}

		message <one message name> { ... }
		message <another message name> { ... }
		message <and another message name> { ... }
	}

	category <another category name> { ... }
} ]

In order to create messages, you must define their output{…} block, which specifies the content of the message that has to be shown in the application, and if needed can also be logged to the console.

output

Syntax:

package <package name>[{
	category <category name> {

		message <message name> {
			[ parameter { <parameter-list>	} ]
			[ severity  { <severity-option-list> } ]

			output {<output-option> message text}
		}

		message <one message name> { ... }
		message <another message name> { ... }
		message <and another message name> { ... }
	}

	category <another category name> { ... }
} ]

Currently output blocks can be defined with either 2 options:

  • all: defines a message and console text
  • show: defines a message text with an optional different console text


all

With the output option all followed by a string containing the message text, you define a message, which will be shown to the user not just as a pop-up notification but also as information text inside the console log.

Syntax:

message <message name> {
	output {
		all message text
	}
}


Example:

package net.osbee.sample.foodmart.messages {
	category Guest {
		message Welcome {
			output {
				all A very OS.bee Welcome!
			}
		}
		message Goodbye {
			output {
				all See you next time!
			}
		}
	}

	category Employee {
		message Promoted {
			output {
				all "You are promoted!"
			}
		}
		message FireNotAllowed {
			output {
				all "You can't fire female employees"
			}
		}
		message Fired {
			output {
				all "You successfully fired this employee"
			}
		}
		message FireStarted {
			output {
				all "Fire process started"
		}
	}
}
show

With the output-option show followed by a string containing the message text, you define a pop-up notification that will be show to the user.

Syntax:

message <message name> {
	output {
		show message text
	}
}


Example:

package net.osbee.sample.foodmart.messages {
	category Guest {
		message Welcome {
			output {
				show A very OS.bee Welcome!
			}
		}

		message Goodbye {
			output {
				show See you next time!
			}
		}
	}

	category Employee {
		message Promoted {
			output {
				show "You are promoted!"
			}
		}
		message FireNotAllowed {
			output {
				show "You can't fire female employees"
			}
		}
		message Fired {
			output {
				show "You successfully fired this employee"
			}
		}
		message FireStarted {
			output {
				show "Fire process started"
		}
	}
}

With the optional keyword log followed by a string containing a text you define a String to be shown in the console log. A log entry declaration has always to be followed by a show entry declaration. You may set a different output text with this option in contrast to the use of an all entry.

log

Syntax:

message <message name> {
	output {
		log log text
		show message text
	}
}


Example:

package net.osbee.sample.foodmart.messages {
	category Guest {
		message Welcome {
			output {
				log welcome-msg shown to the user
				show A very OS.bee Welcome!
			}
		}

		message Goodbye {
			output {
				log goodbye-msg shown to the user
				show See you next time!
			}
		}
	}

	category Employee {
		message Promoted {
			output {
				show "You are promoted!"
			}
		}
		message FireNotAllowed {
			output {
				log user action not allowed  Fire female employee
				show "You can't fire female employees"
			}
		}
		message Fired {
			output {
				log user action allowed  employee fired
				show "You successfully fired this employee"
			}
		}
		message FireStarted {
			output {
				log user action allowed  employee termination in process
				show "Fire process started"
		}
	}
}

parameter

By defining a parameter{…} block you are able to define a list of parameter, whose values can be incorporated and used inside message texts, in order to create more detailed and complex messages.

Syntax:

message <message name> {
	parameter { [parameter-type <parameter name> ]* }

	output { all | { [ log log text ] | show message text } }
}

Currently the available parameter types are the following:

  • Boolean to refer or define a parameter of type Boolean
  • Class to refer or define a parameter of type Class
  • double to refer or define a parameter of type double (floating point value)
  • Exception to refer or define an exception parameter
  • Int to refer or define a number parameter
  • Object to refer or define an object parameter
  • String to refer or define a String parameter


Example:

package net.osbee.sample.foodmart.messages {
	category Guest {
		message Welcome {
			parameter {
				String name
			}

			output {
				log welcome-msg shown to the user
				show A very OS.bee Welcome to %%name%%!
			}
		}
	}

	category Employee {
		message Fired {

			parameter {
				int personalID
				String date
			}

			output {
				log user action allowed  employee fired
				show "You successfully fired this employee"
			}
		}
		message FireStarted {
			output {
				log user action allowed  employee termination in process
				show "Fire process started"
		}
	}
}

severity

By setting a severity {…} block you are able to enumerate the list of severity levels (error, info, warning) that have to be either shown only in the console output or in a log file, or even both. This helps you categorize and filter the type of (available) output, you would like to consider or persist into a log file.

There are currently eight severity levels available:

Syntax:

message <message name> {
        severity { [log-debug | log-error | log-info | log-trace | log-warn | show-error | show-info | show-warning]* }
        output { all | { [ log log text ] | show message text } }
}


Example:

package net.osbee.sample.foodmart.messages {
        category Guest {
               message Welcome {
                       parameter {
                               String name
                       }
                       severity {
                               log-debug log-error log-trace log-warn
                       }
                       output {
                               log welcome-msg shown to the user
                               show A very OS.bee Welcome to %%name%%!
                       }
               }

        }
        category Employee {
               message Fired {
                       parameter {
                               int personalID
                               String date
                       }
                       severity {
                               show-error show-info log-debug log-trace log-warn
                       }
                       output {
                               log user action allowed  employee fired
                               show "You successfully fired this employee"
                       }
               }
               message FireStarted {
                       severity {
                               log-debug log-error log-trace log-warn show-info
                       }
                       output {
                               log user action allowed  employee termination in process
                               show "Fire process started"

                       }

               }

        }

}

Copyright Notice

All rights are reserved by Compex Systemhaus GmbH. In particular, duplications, translations, microfilming, saving and processing in electronic systems are protected by copyright. Use of this manual is only authorized with the permission of Compex Systemhaus GmbH. Infringements of the law shall be punished in accordance with civil and penal laws. We have taken utmost care in putting together texts and images. Nevertheless, the possibility of errors cannot be completely ruled out. The Figures and information in this manual are only given as approximations unless expressly indicated as binding. Amendments to the manual due to amendments to the standard software remain reserved. Please note that the latest amendments to the manual can be accessed through our helpdesk at any time. The contractually agreed regulations of the licensing and maintenance of the standard software shall apply with regard to liability for any errors in the documentation. Guarantees, particularly guarantees of quality or durability can only be assumed for the manual insofar as its quality or durability are expressly stipulated as guaranteed. If you would like to make a suggestion, the Compex Team would be very pleased to hear from you.

(c) 2018 Compex Systemhaus GmbH