View Javadoc

1   /*
2    * Copyright 2004-2009 the Seasar Foundation and the Others.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
13   * either express or implied. See the License for the specific language
14   * governing permissions and limitations under the License.
15   */
16  package org.seasar.cubby.plugin;
17  
18  import java.util.Set;
19  
20  import javax.servlet.ServletContext;
21  
22  import org.seasar.cubby.action.ActionResult;
23  import org.seasar.cubby.spi.Provider;
24  
25  /**
26   * プラグインを表すインターフェイスです。
27   * <p>
28   * プラグインは所属する Web アプリケーションのサーブレットに対する変更の通知を受け取ることができます。
29   * </p>
30   * 
31   * @author baba
32   */
33  public interface Plugin {
34  
35  	// プラグインのライフサイクル
36  
37  	/**
38  	 * このプラグインを初期化します。
39  	 * <p>
40  	 * <code>CubbyFilter</code> がサービスを提供できるようになった時に実行されます。
41  	 * </p>
42  	 * 
43  	 * @param servletContext
44  	 *            呼び出し元が現在実行している {@link ServletContext} への参照
45  	 * @throws Exception
46  	 *             プラグインの初期化に失敗した場合
47  	 * @see javax.servlet.Filter#init(javax.servlet.FilterConfig)
48  	 */
49  	void initialize(ServletContext servletContext) throws Exception;
50  
51  	/**
52  	 * このプラグインが提供するサービスプロバイダを取得します。
53  	 * <p>
54  	 * このプラグインが指定されたサービスを提供しない場合は <code>null</code> を返します。
55  	 * </p>
56  	 * 
57  	 * @param <S>
58  	 *            サービスの型
59  	 * @param service
60  	 *            サービス
61  	 * @return サービスプロバイダ
62  	 */
63  	<S extends Provider> S getProvider(Class<S> service);
64  
65  	/**
66  	 * このプラグインが提供するサービスプロバイダのセットを返します。
67  	 * 
68  	 * @return このプラグインが提供するサービスプロバイダのセット
69  	 */
70  	Set<Class<? extends Provider>> getSupportedServices();
71  
72  	/**
73  	 * このプラグインを準備します。
74  	 * <p>
75  	 * プラグインの準備が完了した時に実行されます。
76  	 * </p>
77  	 * 
78  	 * @throws Exception
79  	 *             プラグインの準備に失敗した場合
80  	 */
81  	void ready() throws Exception;
82  
83  	/**
84  	 * このプラグインを破棄します。
85  	 * <p>
86  	 * <code>CubbyFilter</code> がサービスの提供を停止するときに実行されます。
87  	 * </p>
88  	 * 
89  	 * @see javax.servlet.Filter#destroy()
90  	 */
91  	void destroy();
92  
93  	// サーブレット要求の処理
94  
95  	/**
96  	 * 要求に対する処理を実行します。
97  	 * <p>
98  	 * このメソッドをオーバーライドすることで、要求に対する処理の実行をインターセプトすることができます。
99  	 * </p>
100 	 * <p>
101 	 * このメソッド内で {@link RequestProcessingInvocation#proceed()}
102 	 * メソッドを実行することで、別のプラグインの
103 	 * {@link #invokeRequestProcessing(RequestProcessingInvocation)}
104 	 * または要求に対する処理が実行されます。
105 	 * </p>
106 	 * 
107 	 * @param invocation
108 	 *            要求に対する処理の実行情報
109 	 * @throws Exception
110 	 *             要求に対する処理の実行時に例外が発生した場合
111 	 */
112 	void invokeRequestProcessing(RequestProcessingInvocation invocation)
113 			throws Exception;
114 
115 	/**
116 	 * アクションメソッドを実行します。
117 	 * <p>
118 	 * このメソッドをオーバーライドすることで、アクションメソッドの実行をインターセプトすることができます。
119 	 * </p>
120 	 * <p>
121 	 * このメソッド内で {@link ActionInvocation#proceed()} メソッドを実行することで、別のプラグインの
122 	 * {@link #invokeAction(ActionInvocation)} またはアクションメソッドが実行されます。
123 	 * </p>
124 	 * 
125 	 * @param invocation
126 	 *            アクションメソッドの実行情報
127 	 * @return アクションの実行結果
128 	 * @throws Exception
129 	 *             アクションメソッドの実行時に例外が発生した場合
130 	 */
131 	ActionResult invokeAction(ActionInvocation invocation) throws Exception;
132 
133 	/**
134 	 * アクションの実行結果を実行します。
135 	 * <p>
136 	 * このメソッドをオーバーライドすることで、アクションの実行結果の実行をインターセプトすることができます。
137 	 * </p>
138 	 * <p>
139 	 * このメソッド内で {@link ActionResultInvocation#proceed()} メソッドを実行することで、別のプラグインの
140 	 * {@link #invokeActionResult(ActionResultInvocation)} またはアクションの実行結果が実行されます。
141 	 * </p>
142 	 * 
143 	 * @param invocation
144 	 *            アクションの実行結果の実行情報
145 	 * @throws Exception
146 	 *             アクションの実行結果の実行時に例外が発生した場合
147 	 */
148 	void invokeActionResult(ActionResultInvocation invocation) throws Exception;
149 
150 }