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.routing.PathInfo;
24  import org.seasar.cubby.spi.Provider;
25  
26  /**
27   * プラグインを表すインターフェイスです。
28   * <p>
29   * プラグインは所属する Web アプリケーションのサーブレットに対する変更の通知を受け取ることができます。
30   * </p>
31   * 
32   * @author baba
33   */
34  public interface Plugin {
35  
36  	// プラグインのライフサイクル
37  
38  	/**
39  	 * このプラグインを初期化します。
40  	 * <p>
41  	 * <code>CubbyFilter</code> がサービスを提供できるようになった時に実行されます。
42  	 * </p>
43  	 * 
44  	 * @param servletContext
45  	 *            呼び出し元が現在実行している {@link ServletContext} への参照
46  	 * @throws Exception
47  	 *             プラグインの初期化に失敗した場合
48  	 * @see javax.servlet.Filter#init(javax.servlet.FilterConfig)
49  	 */
50  	void initialize(ServletContext servletContext) throws Exception;
51  
52  	/**
53  	 * このプラグインが提供するサービスプロバイダを取得します。
54  	 * <p>
55  	 * このプラグインが指定されたサービスを提供しない場合は <code>null</code> を返します。
56  	 * </p>
57  	 * 
58  	 * @param <S>
59  	 *            サービスの型
60  	 * @param service
61  	 *            サービス
62  	 * @return サービスプロバイダ
63  	 */
64  	<S extends Provider> S getProvider(Class<S> service);
65  
66  	/**
67  	 * このプラグインが提供するサービスプロバイダのセットを返します。
68  	 * 
69  	 * @return このプラグインが提供するサービスプロバイダのセット
70  	 */
71  	Set<Class<? extends Provider>> getSupportedServices();
72  
73  	/**
74  	 * このプラグインを準備します。
75  	 * <p>
76  	 * プラグインの準備が完了した時に実行されます。
77  	 * </p>
78  	 * 
79  	 * @throws Exception
80  	 *             プラグインの準備に失敗した場合
81  	 */
82  	void ready() throws Exception;
83  
84  	/**
85  	 * このプラグインを破棄します。
86  	 * <p>
87  	 * <code>CubbyFilter</code> がサービスの提供を停止するときに実行されます。
88  	 * </p>
89  	 * 
90  	 * @see javax.servlet.Filter#destroy()
91  	 */
92  	void destroy();
93  
94  	// サーブレット要求の処理
95  
96  	/**
97  	 * ルーティングを実行して要求されたパスの情報を取得します。
98  	 * <p>
99  	 * このメソッドをオーバーライドすることで、ルーティングの実行をインターセプトすることができます。
100 	 * </p>
101 	 * <p>
102 	 * このメソッド内で {@link RoutingInvocation#proceed()} メソッドを実行することで、別のプラグインの
103 	 * {@link #invokeRouting(RoutingInvocation)} またはルーティングが実行されます。
104 	 * </p>
105 	 * 
106 	 * @param invocation
107 	 *            ルーティングの実行情報
108 	 * @throws Exception
109 	 *             ルーティングの実行時に例外が発生した場合
110 	 */
111 	PathInfo invokeRouting(RoutingInvocation invocation) throws Exception;
112 
113 	/**
114 	 * 要求に対する処理を実行します。
115 	 * <p>
116 	 * このメソッドをオーバーライドすることで、要求に対する処理の実行をインターセプトすることができます。
117 	 * </p>
118 	 * <p>
119 	 * このメソッド内で {@link RequestProcessingInvocation#proceed()}
120 	 * メソッドを実行することで、別のプラグインの
121 	 * {@link #invokeRequestProcessing(RequestProcessingInvocation)}
122 	 * または要求に対する処理が実行されます。
123 	 * </p>
124 	 * 
125 	 * @param invocation
126 	 *            要求に対する処理の実行情報
127 	 * @throws Exception
128 	 *             要求に対する処理の実行時に例外が発生した場合
129 	 */
130 	void invokeRequestProcessing(RequestProcessingInvocation invocation)
131 			throws Exception;
132 
133 	/**
134 	 * アクションメソッドを実行します。
135 	 * <p>
136 	 * このメソッドをオーバーライドすることで、アクションメソッドの実行をインターセプトすることができます。
137 	 * </p>
138 	 * <p>
139 	 * このメソッド内で {@link ActionInvocation#proceed()} メソッドを実行することで、別のプラグインの
140 	 * {@link #invokeAction(ActionInvocation)} またはアクションメソッドが実行されます。
141 	 * </p>
142 	 * 
143 	 * @param invocation
144 	 *            アクションメソッドの実行情報
145 	 * @return アクションの実行結果
146 	 * @throws Exception
147 	 *             アクションメソッドの実行時に例外が発生した場合
148 	 */
149 	ActionResult invokeAction(ActionInvocation invocation) throws Exception;
150 
151 	/**
152 	 * アクションの実行結果を実行します。
153 	 * <p>
154 	 * このメソッドをオーバーライドすることで、アクションの実行結果の実行をインターセプトすることができます。
155 	 * </p>
156 	 * <p>
157 	 * このメソッド内で {@link ActionResultInvocation#proceed()} メソッドを実行することで、別のプラグインの
158 	 * {@link #invokeActionResult(ActionResultInvocation)} またはアクションの実行結果が実行されます。
159 	 * </p>
160 	 * 
161 	 * @param invocation
162 	 *            アクションの実行結果の実行情報
163 	 * @throws Exception
164 	 *             アクションの実行結果の実行時に例外が発生した場合
165 	 */
166 	void invokeActionResult(ActionResultInvocation invocation) throws Exception;
167 
168 }