= MessageService
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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.

Allows domain objects to raise information, warning or error messages.

These messages can either be simple strings, or can be translated.

== API

[source,java]
.MessageService.java
----
interface MessageService {
  void informUser(String message)     // <.>
  String informUser(TranslatableString message, Class<?> contextClass, String contextMethod)     // <.>
  String informUser(TranslatableString message, TranslationContext translationContext)     // <.>
  void warnUser(String message)     // <.>
  String warnUser(TranslatableString message, Class<?> contextClass, String contextMethod)     // <.>
  String warnUser(TranslatableString message, TranslationContext translationContext)     // <.>
  void raiseError(String message)     // <.>
  String raiseError(TranslatableString message, Class<?> contextClass, String contextMethod)     // <.>
  String raiseError(TranslatableString message, TranslationContext translationContext)     // <.>
  void setError(String message)     // <.>
}
----

<.> xref:#informUser_String[informUser(String)]
+
--
Make the specified message available to the user, intended to be useful but optional information, for a viewer to display typically in a transitory manner.
--
<.> xref:#informUser_TranslatableString_Class_String[informUser(TranslatableString, Class, String)]
+
--
As _#informUser(String)_ , but with the message translated (if possible) to user's _java.util.Locale_ .
--
<.> xref:#informUser_TranslatableString_TranslationContext[informUser(TranslatableString, TranslationContext)]
+
--
Override of _MessageService#informUser(TranslatableString, Class, String)_ , but with an arbitrary translation context (rather than inferred from the context class and method).
--
<.> xref:#warnUser_String[warnUser(String)]
+
--
Warn the user about a situation with the specified message.
--
<.> xref:#warnUser_TranslatableString_Class_String[warnUser(TranslatableString, Class, String)]
+
--
As _#warnUser(String)_ , but with the message translated (if possible) to user's _java.util.Locale_ .
--
<.> xref:#warnUser_TranslatableString_TranslationContext[warnUser(TranslatableString, TranslationContext)]
+
--
Override of _MessageService#warnUser(TranslatableString, Class, String)_ , but with an arbitrary translation context (rather than inferred from the context class and method).
--
<.> xref:#raiseError_String[raiseError(String)]
+
--
Notify the user of an application error with the specified message.
--
<.> xref:#raiseError_TranslatableString_Class_String[raiseError(TranslatableString, Class, String)]
+
--
As _#raiseError(String)_ , but with the message translated (if possible) to user's _java.util.Locale_ .
--
<.> xref:#raiseError_TranslatableString_TranslationContext[raiseError(TranslatableString, TranslationContext)]
+
--
Override of _MessageService#raiseError(TranslatableString, Class, String)_ , but with an arbitrary translation context (rather than inferred from the context class and method).
--
<.> xref:#setError_String[setError(String)]
+
--
Sets a new application error message. Similar to _#raiseError(String)_ , but without throwing a xref:refguide:applib:index/exceptions/RecoverableException.adoc[RecoverableException] .
--

== Members

[#informUser_String]
=== informUser(String)

Make the specified message available to the user, intended to be useful but optional information, for a viewer to display typically in a transitory manner.

In the Wicket viewer this is implemented as a "toast" message that automatically disappears after a period of time.

[#informUser_TranslatableString_Class_String]
=== informUser(TranslatableString, Class, String)

As _#informUser(String)_ , but with the message translated (if possible) to user's _java.util.Locale_ .

More precisely, the locale is as provided by the configured _org.apache.isis.applib.services.i18n.LanguageProvider_ service. This should be the _java.util.Locale_ of the user making the current request.

[#informUser_TranslatableString_TranslationContext]
=== informUser(TranslatableString, TranslationContext)

Override of _MessageService#informUser(TranslatableString, Class, String)_ , but with an arbitrary translation context (rather than inferred from the context class and method).

[#warnUser_String]
=== warnUser(String)

Warn the user about a situation with the specified message.

The viewer should guarantee to display this warning to the user, and will typically require acknowledgement.

In the Wicket viewer this is implemented as a "toast" message that must be explicitly closed by the user.

[#warnUser_TranslatableString_Class_String]
=== warnUser(TranslatableString, Class, String)

As _#warnUser(String)_ , but with the message translated (if possible) to user's _java.util.Locale_ .

More precisely, the locale is as provided by the configured _org.apache.isis.applib.services.i18n.LanguageProvider_ service. This should be the _java.util.Locale_ of the user making the current request.

[#warnUser_TranslatableString_TranslationContext]
=== warnUser(TranslatableString, TranslationContext)

Override of _MessageService#warnUser(TranslatableString, Class, String)_ , but with an arbitrary translation context (rather than inferred from the context class and method).

[#raiseError_String]
=== raiseError(String)

Notify the user of an application error with the specified message.

Note this will probably be displayed in an prominent fashion, so is only suitable for errors. The user will typically be required to perform additional steps after the error..

In the Wicket viewer this is implemented as a toast (with a different colour) that must be closed by the end-user.

[#raiseError_TranslatableString_Class_String]
=== raiseError(TranslatableString, Class, String)

As _#raiseError(String)_ , but with the message translated (if possible) to user's _java.util.Locale_ .

More precisely, the locale is as provided by the configured _org.apache.isis.applib.services.i18n.LanguageProvider_ service. This should be the _java.util.Locale_ of the user making the current request.

[#raiseError_TranslatableString_TranslationContext]
=== raiseError(TranslatableString, TranslationContext)

Override of _MessageService#raiseError(TranslatableString, Class, String)_ , but with an arbitrary translation context (rather than inferred from the context class and method).

[#setError_String]
=== setError(String)

Sets a new application error message. Similar to _#raiseError(String)_ , but without throwing a xref:refguide:applib:index/exceptions/RecoverableException.adoc[RecoverableException] .

include::hooks/MessageService_010-implementation.adoc[]

include::hooks/MessageService_020-examples-and-usage.adoc[]
