`` とその配下の要素が実行される。
| ``th:classappend`` 属性は設定した値をもとからある ``class`` 属性の値に追加するもので、ここでは可変であるメッセージタイプを設定している。
| この ``class`` 属性と ``th:classappend`` 属性によって、出力されるHTMLにおける ``class`` 属性が構築される。
* - | (3)
- | 属性名が"resultMessages"のオブジェクトに格納された ``message`` 変数を、Thymeleafのメッセージ式 ``#messages`` を使用して繰り返し取得し、出力する。
ブラウザで表示すると、以下のように出力される。
.. figure:: ./images_MessageManagement/message-management-resultmessage-basic.png
:width: 40%
出力されるHTMLを、以下に示す(説明しやすくするために整形している)。
.. code-block:: html
- There are inconsistencies in the data.
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | メッセージタイプに対応して"alert-error"クラスが付与されている。デフォルトでは\ ``
``\ タグのclassに"alert alert-[メッセージタイプ]"が付与される。
* - | (2)
- | 結果メッセージのリストが\ ``
``\ タグで出力される。
* - | (3)
- | メッセージIDに対応するメッセージが\ ``MessageSource``\ から解決される。
出力されるメッセージはclassが付けられているにすぎないため、その見栄えは出力されたclassに合わせてCSSでカスタマイズする必要がある(後述する)。
.. note::
\ ``ResultMessages.error().add(ResultMessage.fromText("There are inconsistencies in the data."));``\ というように、メッセージの本文をハードコードすることもできるが、保守性を高めるため、メッセージIDを使用して\ ``ResultMessage``\ オブジェクトを作成し、メッセージ本文はプロパティファイルから取得することを推奨する。
|
プレースホルダーを使用した結果メッセージの設定方法
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
以下のように、メッセージにプレースホルダーを指定することができる。
.. code-block:: properties
e.xx.yy.8001=Cannot upload, Because the file size must be less than {0}MB.
メッセージのプレースホルダに値を埋める場合は、次のように\ ``add``\ メソッドの第二引数以降に設定する。
.. code-block:: java
ResultMessages messages = ResultMessages.error().add("e.xx.yy.8001", 1024);
model.addAttribute(messages);
この場合、以下のようなHTMLが出力される。
.. code-block:: html
- Cannot upload, Because the file size must be less than 1,024MB.
.. note::
\ ``ResourceBundleMessageSource``\ はメッセージを生成する際に\ ``java.text.MessageFormat``\ を使用するため、\ ``1024``\ は
カンマ区切りで\ ``1,024``\ と表示される。カンマが不要な場合は、プロパティファイルには以下のように設定する。
.. code-block:: properties
e.xx.yy.8001=Cannot upload, Because the file size must be less than {0,number,#}MB.
詳細は、\ `Javadoc `_\ を参照されたい。
|
複数の結果メッセージの設定方法
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
以下のように、複数の結果メッセージを設定することもできる。
.. code-block:: java
ResultMessages messages = ResultMessages.error()
.add("e.xx.yy.9001")
.add("e.xx.yy.8001", 1024);
model.addAttribute(messages);
この場合は、次のようなHTMLが出力される(テンプレートHTMLの変更は、不要である)。
.. code-block:: html
- There are inconsistencies in the data.
- Cannot upload, Because the file size must be less than 1,024MB.
|
メッセージタイプの変更方法
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
| 標準では、以下のメッセージタイプが用意されている。
| 標準のメッセージタイプはCSSフレームワークである\ `Bootstrap `_\ の\ `Alertsコンポーネント `_\ に対応しており、\ ````\ のデフォルト設定で利用できる。
.. tabularcolumns:: |p{0.15\linewidth}|p{0.30\linewidth}|p{0.25\linewidth}|p{0.30\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 25 25 10 30
* - メッセージタイプ
- \ ``ResultMessages``\ オブジェクトの作成
- デフォルトで出力されるclass名
- 分類
- 使い分け（例）
* - | success
- | ``ResultMessages.success()``\
- | alert alert-success
- | info
- | 成功メッセージやポジティブな通知。
* - | info
- | \ ``ResultMessages.info()``\
- | alert alert-info
- | info
- | 一般的な情報提供。
* - | primary
- | \ ``ResultMessages.primary()``\
- | alert alert-primary
- | info
- | 主要な情報や重要な通知。
* - | secondary
- | \ ``ResultMessages.secondary()``\
- | alert alert-secondary
- | info
- | 補助的な情報やそれほど重要ではない通知。
* - | warning
- | \ ``ResultMessages.warning()``\
- | alert alert-warning
- | warning
- | 注意喚起や警告メッセージ。
* - | light
- | \ ``ResultMessages.light()``\
- | alert alert-light
- | warning
- | 軽いトーンの通知やメッセージ。
* - | dark
- | \ ``ResultMessages.dark()``\
- | alert alert-dark
- | warning
- | 重いトーンの通知やメッセージ。
* - | danger
- | \ ``ResultMessages.danger()``\
- | alert alert-danger
- | error
- | 深刻なエラーメッセージや重要な警告。
* - | error
- | \ ``ResultMessages.error()``\
- | alert alert-error
- | error
- | 深刻なエラーメッセージや重要な警告。
| errorはBootstrapのAlertsコンポーネントには含まれていない。
メッセージタイプに応じてCSSを定義されたい。以下に、CSSを適用した場合の例を示す。
.. code-block:: css
.alert {
margin-bottom: 15px;
padding: 10px;
border: 1px solid;
border-radius: 4px;
text-shadow: 0 1px 0 #ffffff;
}
.alert-info {
background: #ebf7fd;
color: #2d7091;
border-color: rgba(45, 112, 145, 0.3);
}
.alert-warning {
background: #fffceb;
color: #e28327;
border-color: rgba(226, 131, 39, 0.3);
}
.alert-error {
background: #fff1f0;
color: #d85030;
border-color: rgba(216, 80, 48, 0.3);
}
* \ ``ResultMessages.error().add("e.xx.yy.9001")``\ を出力した例
.. figure:: ./images_MessageManagement/message-management-resultmessage-error.jpg
:width: 100%
* \ ``ResultMessages.warning().add("w.xx.yy.2001")``\ を出力した例
.. figure:: ./images_MessageManagement/message-management-resultmessage-warn.jpg
:width: 100%
* \ ``ResultMessages.info().add("i.xx.yy.0001", "XXXX")``\ を出力した例
.. figure:: ./images_MessageManagement/message-management-resultmessage-info.jpg
:width: 100%
.. caution::
本例では、メッセージIDをハードコードで設定しているが、保守性を高めるためにも、メッセージIDは定数クラスにまとめることを推奨する。
\ :ref:`message-management-messagekeysgen`\ を参照されたい。
|
結果メッセージの属性名指定
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
| \ ``ResultMessages``\ をModelに追加する場合、属性名を省略することが出来る。
| ただし、\ ``ResultMessages``\ は一つのメッセージタイプしか表現できないため、1画面に異なるメッセージタイプの\ ``ResultMessages``\ を同時に表示したい場合は、明示的に属性名を指定してModelに設定する必要がある。
* Controller
.. code-block:: java
@RequestMapping(value = "showMessages", method = RequestMethod.GET)
public String showMessages(Model model) {
model.addAttribute("messages1", ResultMessages.warning().add("w.xx.yy.2001")); // (1)
model.addAttribute("messages2", ResultMessages.error().add("e.xx.yy.9001")); // (2)
return "message/showMessages";
}
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | メッセージタイプが"warning"である\ ``ResultMessages``\ を、属性名"messages1"でModelに追加する。
* - | (2)
- | メッセージタイプが"info"である\ ``ResultMessages``\ を、属性名"messages2"でModelに追加する。
* テンプレートHTML (WEB-INF/views/message/showMessages.html)
.. code-block:: html
Result Message
Messages1
Messages2
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | 属性名が"messages1"である\ ``ResultMessages``\ を表示する。
* - | (2)
- | 属性名が"messages2"である\ ``ResultMessages``\ を表示する。
ブラウザで表示すると、以下のように出力される。
.. figure:: ./images_MessageManagement/message-management-multiple-messages.jpg
:width: 80%
|
業務例外メッセージの表示
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
| \ ``org.terasoluna.gfw.common.exception.BusinessException``\ と\ ``org.terasoluna.gfw.common.exception.ResourceNotFoundException``\ は
| 内部で\ ``ResultMessages``\ を保持している。
| 業務例外メッセージを表示する場合は、Serviceクラスで\ ``ResultMessages``\ を設定した\ ``BusinessException``\ をスローすること。
| Controllerクラスでは\ ``BusinessException``\ をキャッチし、例外中の結果メッセージをModelに追加する。
* Serviceクラス
.. code-block:: java
@Service
@Transactional
public class UserServiceImpl implements UserService {
// omitted
public void create(...) {
// omitted...
if (...) {
// illegal state!
ResultMessages messages = ResultMessages.error().add("e.ex.an.9001"); // (1)
throw new BusinessException(messages);
}
}
}
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | エラーメッセージを\ ``ResultMessages``\ で作成し、\ ``BusinessException``\ に設定する。
* Controllerクラス
.. code-block:: java
@RequestMapping(value = "create", method = RequestMethod.POST)
public String create(@Validated UserForm form, BindingResult result, Model model) {
// omitted
try {
userService.create(user);
} catch (BusinessException e) {
ResultMessages messages = e.getResultMessages(); // (1)
model.addAttribute(messages);
return "user/createForm";
}
// omitted
}
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | \ ``BusinessException``\ が保持する\ ``ResultMessages``\ を取得し、Modelに追加する。
通常は、用意されているメッセージタイプのみで十分であるが、採用しているCSSライブラリによってはメッセージタイプを追加したい場合がある。例えば"notice"というメッセージタイプを追加する場合を説明する。
|
How to extend
--------------------------------------------------------------------------------
独自メッセージタイプを作成する
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| メッセージタイプを追加したい場合の、独自メッセージタイプ作成方法について説明する。
| 通常は、用意されているメッセージタイプのみで十分であるが、採用しているCSSライブラリによっては
| メッセージタイプを追加したい場合がある。例えば"notice"というメッセージタイプを追加する場合を説明する。
| まず、以下のように\ ``org.terasoluna.gfw.common.message.ResultMessageType``\ インタフェースを実装した
| 独自メッセージタイプクラスを作成する。
.. code-block:: java
import org.terasoluna.gfw.common.message.ResultMessageType;
public enum ResultMessageTypes implements ResultMessageType { // (1)
NOTICE("notice");
private ResultMessageTypes(String type) {
this.type = type;
}
private final String type;
@Override
public String getType() { // (2)
return this.type;
}
@Override
public String toString() {
return this.type;
}
}
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | \ ``ResultMessageType``\ インタフェースを実装したEnumを定義する。定数オブジェクトで作成してもよいが、Enumで作成することを推奨する。
* - | (2)
- | \ ``getType``\ の返り値が出力されるCSSのclass名に対応する。
| このメッセージタイプを使用して以下のように\ ``ResultMessages``\ を作成する。
.. code-block:: java
ResultMessages messages = new ResultMessages(ResultMessageTypes.NOTICE) // (1)
.add("w.xx.yy.2001");
model.addAttribute(messages);
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | \ ``ResultMessages``\ のコンストラクタに対象の\ ``ResultMessageType``\ を指定する。
この場合、以下のようなHTMLが出力される。
.. code-block:: html
- The recommended change interval has passed password. Please change your password.
.. tip::
拡張方法は、\ `org.terasoluna.gfw.common.message.StandardResultMessageType `_\ が参考になる。
|
Appendix
--------------------------------------------------------------------------------
.. _message-management-messagepanel-attribute:
ResultMessagesを使用しない結果メッセージの表示
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``ResultMessages``\ オブジェクト以外にも、フレームワークがリクエストスコープに設定した文字列(エラーメッセージなど)を表示することができる。
| 例えば、Spring Securityは認証エラー時に、"SPRING_SECURITY_LAST_EXCEPTION"という属性名で発生した例外クラスを
| リクエストスコープに設定する。
| この例外メッセージを、 ``ResultMessages`` を使用したときとと同様に出力したい場合は、以下のように設定すればよい。
.. code-block:: html
Login
.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
:header-rows: 1
:widths: 10 90
* - 項番
- 説明
* - | (1)
- | スタンダードダイアレクトが提供する属性を使用したとき、EclipseなどのIDEでの警告を抑止するため、ネームスペースを付与する。
* - | (2)
- | 結果メッセージ表示用のCSSを再掲する。実際はCSSファイルに記述することを強く推奨する。
* - | (3)
- | ``Exception`` オブジェクトが格納されている属性名をThymeleafの変数式 ``${}`` に指定する。
| また、 ``ResultMessages`` オブジェクトとは異なり、メッセージタイプの情報をもたないため、 ``class`` 属性で ``alert alert-error`` を明示的に指定している。
認証エラー時に出力されるHTMLは
.. code-block:: html
であり、ブラウザでは以下のように出力される。
.. figure:: ./images_MessageManagement/message-management-login-error.jpg
:width: 60%
\
.. tip::
ログイン用のテンプレートHTMLの内容については、\ :doc:`../../Security/Authentication`\ を参照されたい。
.. _message-management-messagekeysgen:
メッセージID定数クラスの自動生成ツール
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| これまでの例ではメッセージIDを文字列のハードコードで設定していたが、
| メッセージIDは定数クラスにまとめることを推奨する。
| ここでは、簡易ツールとして、propertiesファイルからメッセージID定数クラスを
| 自動生成するプログラムおよび使用方法を紹介する。必要に応じてカスタマイズして利用されたい。
.. raw:: latex
\newpage
#. メッセージID定数クラスの作成
まず空のメッセージID定数クラスを作成する。ここでは\ ``com.example.common.message.MessageIds``\ とする。
.. code-block:: java
package com.example.common.message;
public class MessageKeys {
}
#. 自動生成クラスの作成
次に\ ``MessageKeys``\ クラスと同じパッケージに\ ``MessageKeysGen``\ クラスを作成し、以下のように記述する。
.. code-block:: java
package com.example.common.message;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.PrintWriter;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import org.springframework.core.io.ClassPathResource;
public class MessageIdsGen {
public static void main(String[] args) throws IOException {
// message properties file
Class targetClazz = MessageIds.class;
Path output = Paths.get("src/main/java", targetClazz.getName().replace(".", "/") + ".java");
try (InputStream inputStream =
new ClassPathResource("i18n/application-messages-msmn.properties").getInputStream();
BufferedReader bufferedReader =
new BufferedReader(new InputStreamReader(inputStream));
PrintWriter pw = new PrintWriter(Files.newBufferedWriter(output))) {
pw.println("package " + targetClazz.getPackage().getName() + ";");
pw.println("");
pw.println("/**");
pw.println(" * Message Id");
pw.println(" */");
pw.println("public class " + targetClazz.getSimpleName() + " {");
String line = null;
while ((line = bufferedReader.readLine()) != null) {
String[] vals = line.split("=", 2);
if (vals.length > 1) {
String id = vals[0].trim();
String value = vals[1].trim();
pw.println(" /** " + id + "=" + value + " */");
pw.println(" public static final String "
+ id.toUpperCase().replace(".", "_").replace("-", "_") + " = \"" + id
+ "\";");
}
}
pw.println("");
pw.println(" private " + targetClazz.getSimpleName() + "() {}");
pw.println("}");
}
}
}
#. メッセージプロパティファイルの用意
src/main/resource/i18m/application-messages.propertiesにメッセージを定義する。ここでは例として、以下のように設定する。
.. code-block:: properties
i.xx.yy.0001={0} upload completed.
w.xx.yy.2001=The recommended change interval has passed password. Please change your password.
e.xx.yy.8001=Cannot upload, Because the file size must be less than {0}MB.
e.xx.yy.9001=There are inconsistencies in the data.
#. 自動生成クラスの実行
.. figure:: ./images_MessageManagement/message-management-messagekeysgen.png
:width: 60%
\ ``MessageIds``\ クラスが、以下のように上書きされる。
.. code-block:: java
package com.example.common.message;
/**
* Message Id
*/
public class MessageIds {
/** i.xx.yy.0001={0} upload completed. */
public static final String I_XX_YY_0001 = "i.xx.yy.0001";
/** w.xx.yy.2001=The recommended change interval has passed password. Please change your password. */
public static final String W_XX_YY_2001 = "w.xx.yy.2001";
/** e.xx.yy.8001=Cannot upload, Because the file size must be less than {0}MB. */
public static final String E_XX_YY_8001 = "e.xx.yy.8001";
/** e.xx.yy.9001=There are inconsistencies in the data. */
public static final String E_XX_YY_9001 = "e.xx.yy.9001";
}
.. raw:: latex
\newpage