001/*
002 * Copyright (c) 2009 The openGion Project.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
013 * either express or implied. See the License for the specific language
014 * governing permissions and limitations under the License.
015 */
016package org.opengion.hayabusa.db;
017
018import org.opengion.fukurou.model.DataModel;
019
020/**
021 * javax.swing.table.TableModel インターフェースを継承したデータベース情報を
022 * TableModel情報にマッピングするのに利用します。
023 * DataModel<String> インターフェースを継承しています。
024 *
025 * @og.group テーブル管理
026 *
027 * @version  4.0
028 * @author   Kazuhiko Hasegawa
029 * @since    JDK5.0,
030 */
031public interface DBTableModel extends DataModel<String> {
032
033        /**
034         * 行指定の書込み許可を与えます。
035         * 具体的には,チェックボックスの表示/非表示を指定します。
036         * これが true の場合は,書込み許可です。(チェックボックスを表示)
037         * false の場合は,書込み不許可(チェックボックスは表示されません。)
038         * 行毎に書込み許可/不許可を指定する場合は,1カラム目に writable
039         * カラムを用意して true/false を指定します。
040         * この writable カラムとの論理積により最終的にチェックボックスの
041         * 表示の ON/OFF が決まります。
042         *
043         * このデフォルト値は、true に設定されています。
044         *
045         */
046        boolean DEFAULT_WRITABLE = true;
047
048        /**
049         * 行指定用のチェックボックスに対して初期値を 選択済みにするか、
050         * 非選択済みにするかのデフォルト値を指定します。
051         *
052         * このデフォルト値は、false に設定されています。
053         *
054         */
055        boolean DEFAULT_CHECKED = false;
056
057        /**
058         * このオブジェクトを初期化します。
059         * 指定の引数分の内部配列を作成します。
060         * 具体的には,DBColumn の数を指定することになります。
061         *
062         * @param   columnCount カラム数
063         */
064        void init( int columnCount ) ;
065
066        /**
067         * このオブジェクトをヘッダー部分をコピーし、データを初期化します。
068         * これは、カラムなどヘッダー系の情報は、元と同じオブジェクトを共有し、
069         * データ部のみ空にした DBTableModel を作成することを意味します。
070         * この際、consistencyKey も複写しますので、整合性は崩れないように、
071         * データ登録を行う必要があります。
072         *
073         * @og.rev 4.0.0.0 (2007/06/28) 新規作成
074         *
075         * @return  DBTableModelオブジェクト
076         */
077        DBTableModel newModel();
078
079        /**
080         * カラムのラベル名を返します。
081         * カラムの項目名に対して,見える形の文字列を返します。
082         * 一般には,リソースバンドルと組合せて,各国ロケール毎にラベルを
083         * 切替えます。
084         * セットされた DBColumn#getLabel( int ) の値が返されます。
085         *
086         * @param   column カラム番号
087         *
088         * @return  カラムのラベル名
089         */
090        String getColumnLabel( int column ) ;
091
092        /**
093         * row および columnName にあるセルの属性値をStringに変換して返します。
094         *
095         * @param   aRow       値が参照される行
096         * @param   columnName 値が参照されるカラム名
097         *
098         * @return  指定されたセルの値 String
099         * @see #getValue( int , int )
100         */
101        String getValue( final int aRow, final String columnName );
102
103        /**
104         * カラム(列)にカラムオブジェクトを割り当てます。
105         * カラムオブジェクトは,ラベルやネームなど,そのカラム情報を
106         * 保持したオブジェクトです。
107         *
108         * @param   dbColumn  カラムオブジェクト
109         * @param   clm       ヘッダーを適応するカラム(列)
110         */
111        void setDBColumn( int dbColumn, DBColumn clm ) ;
112
113        /**
114         * カラム(列)のカラムオブジェクトを返します。
115         * カラムオブジェクトは,ラベルやネームなど,そのカラム情報を
116         * 保持したオブジェクトです。
117         *
118         * @param       clm     ヘッダーを適応するカラム(列)
119         *
120         * @return      DBColumnカラムオブジェクト
121         */
122        DBColumn getDBColumn( int clm ) ;
123
124        /**
125         * カラムオブジェクト配列を返します。
126         * カラムオブジェクトは,ラベルやネームなど,そのカラム情報を
127         * 保持したオブジェクトです。
128         *
129         * @og.rev 4.0.0.0 (2005/12/31) 新規追加
130         *
131         * @return      カラムオブジェクト配列
132         */
133        DBColumn[] getDBColumns() ;
134
135        /**
136         * カラム名をもとに、そのカラム番号を返します。
137         * useThrow が、true の場合は、カラム名が存在しない場合は、 HybsSystemException を
138         * throw します。useThrow が、false の場合は、カラム名が存在しない場合は、 -1 を返します。
139         *
140         * @og.rev 4.0.0.0 (2005/12/31) 新規追加
141         *
142         * @param   columnName   カラム名
143         * @param   useThrow     カラム名が存在しない場合に、Exception を throw するかどうか
144         *
145         * @return  カラム番号
146         */
147        int getColumnNo( final String columnName,final boolean useThrow ) ;
148
149        /**
150         * 変更済みフラグを元に戻します。
151         *
152         * 一般には,データベースにテーブルモデルを登録するタイミングで、
153         * 変更済みフラグを元に戻します。
154         *
155         */
156        void resetModify() ;
157
158        /**
159         * 変更データを初期値(元の取り込んだ状態)に戻します。
160         *
161         * 変更タイプ(追加/変更/削除)に応じて、処理されます。
162         * 追加時は、追加された行を削除します。
163         * 変更時は、変更された行を元に戻します。
164         * 削除時は、削除フラグを解除します。
165         * それ以外の場合(変更されていない場合)は、なにもしません。
166         *
167         * @param   row  処理を戻す(取り消す)行
168         */
169        void resetRow( int row ) ;
170
171        /**
172         * 書込み許可を返します。
173         *
174         * @param   aRow     値が参照される行
175         *
176         * @return  書込み可能(true)/不可能(false)
177         */
178        boolean isRowWritable( int aRow ) ;
179
180        /**
181         * 書き込み可能な行(rowWritable == true)のチェックボックスに対して
182         * 初期値を 選択済みか、非選択済みかを返します。
183         *
184         * @param   row      値が参照される行
185         *
186         * @return      初期値チェックON(true)/チェックOFF(false)
187         */
188        boolean isRowChecked( int row ) ;
189
190        /**
191         * 検索結果が オーバーフローしたかどうかをチェックします。
192         * Query で検索した場合に、DB_MAX_ROW_COUNT または、Query.setMaxRowCount( int maxRowCount )
193         * で指定された値よりも検索結果が多い場合に、DBTableModel は、先の設定値までの
194         * データを取り込みます。そのときに、オーバーフローフラグを立てておくことで、最大件数を
195         * オーバーしたかどうかを判断します。
196         *
197         * @return   オーバーフロー(true)/正常(false)
198         */
199        boolean isOverflow() ;
200
201        /**
202         * 検索されたDBTableModelが登録時に同一かどうかを判断する為の 整合性キーを取得します。
203         *
204         * ここでの整合性は、同一セッション(ユーザー)毎にユニークかどうかで対応します。
205         * 分散環境(複数のセッション間)での整合性は、確保できません。
206         * 整合性キー は、オブジェクト作成時刻としますが、将来変更される可能性があります。
207         *
208         * @og.rev 3.5.5.5 (2004/04/23) 新規追加
209         *
210         * @return   整合性キー(オブジェクトの作成時刻)
211         */
212        String getConsistencyKey() ;
213
214        // =======================================================================
215        //
216        // TableModel Interface と共有していたメソッドを、独自に再定義します。
217        //
218        // =======================================================================
219
220        /**
221         * データテーブル内の列の数を返します。
222         *
223         * @og.rev 3.5.3.1 (2003/10/31) インターフェースの見直しにより、追加
224         *
225         * @return  モデルの列数
226         */
227        int getColumnCount() ;
228
229        /**
230         * カラム名を取得します。
231         *
232         * @og.rev 3.5.3.1 (2003/10/31) インターフェースの見直しにより、追加
233         *
234         * @param   column  最初のカラムは 0、2番目のカラムは 1、などとする。
235         *
236         * @return  カラム名
237         */
238        String getColumnName(int column) ;
239
240        // =======================================================================
241        //
242        // DBTableModelImpl.java で定義されている public メソッド残り全て
243        //
244        // =======================================================================
245
246        /**
247         * column に対応した 値を登録します。
248         * column には、番号ではなく、ラベルを指定します。
249         *
250         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
251         *
252         * @param   aRow    値が変更される行
253         * @param   columnName    値が変更されるカラム名
254         * @param   value   新しい値。null も可
255         *
256         */
257        void setValue( int aRow, String columnName, String value ) ;
258
259        /**
260         * column および row にあるセルのオブジェクト値を設定します。
261         * value は新しい値です。このメソッドは、tableChanged() 通知を生成します。
262         *
263         * @og.rev 3.1.0.0 (2003/03/20) 同期メソッド(synchronized付き)を非同期に変更する。
264         * @og.rev 3.5.3.1 (2003/10/31) インターフェースの見直しにより、private 化する。
265         * @og.rev 4.0.0.0 (2007/05/24) インターフェースの見直しにより、public 化する。
266         *
267         * @param   value   新しい値。null も可
268         * @param   aRow    値が変更される行
269         * @param   aColumn 値が変更される列
270         */
271        void setValueAt( String value, int aRow, int aColumn ) ;
272
273        /**
274         * 行を削除します。
275         * 物理削除ではなく、論理削除です。
276         * データを取り込むことは可能です。
277         *
278         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
279         *
280         * @param   aRow    論理削除される行
281         *
282         */
283        void rowDelete( int aRow ) ;
284
285        /**
286         * row にあるセルのオブジェクト値を置き換えて、行を削除します。
287         * 物理削除ではなく、論理削除です。
288         * 値を置き換えたデータを取り込むことが可能です。
289         *
290         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
291         *
292         * @param   values  新しい配列値。
293         * @param   aRow    論理削除される行
294         *
295         */
296        void rowDelete( String[] values, int aRow ) ;
297
298        /**
299         * 行を物理削除します。
300         * メモリ上で編集する場合に使用しますが,一般アプリケーションからの
301         * 使用は、物理削除の為,お勧めいたしません。
302         *
303         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
304         *
305         * @param   aRow    物理削除される行
306         *
307         */
308        void removeValue( int aRow ) ;
309
310        /**
311         * row の下に属性値配列を追加登録します。
312         *
313         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
314         *
315         * @param   values  属性値配列
316         * @param   aRow    値が参照される行
317         *
318         */
319        void addValues( String[] values ,int aRow ) ;
320
321        /**
322         * row の下に属性値配列を追加登録します。
323         * isWritableをfalseにした場合、編集不可能な状態で追加されます。
324         *
325         * @og.rev 4.3.1.0 (2008/09/04) interface に新規登録
326         *
327         * @param   values  属性値配列
328         * @param   aRow    値が参照される行
329         * @param   isWritable 編集不可能な状態で追加するか
330         *
331         */
332        void addValues( String[] values ,int aRow, boolean isWritable ) ;
333
334        /**
335         * row あるセルの属性値配列を追加登録します。
336         * これは,初期登録時のみに使用します。
337         *
338         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
339         *
340         * @param   values  属性値配列
341         */
342        void addColumnValues( String[] values ) ;
343
344        /**
345         * row あるセルの属性値配列を追加登録します。
346         * これは,初期登録時のみに使用します。
347         * このメソッドでは、同時に、変更タイプ と、書込み許可を指定できます。
348         *
349         * @og.rev 6.2.2.0 (2015/03/27) interface に変更タイプ と、書込み許可を追加
350         *
351         * @param   values   属性値配列
352         * @param   modType  変更タイプ(追加/変更/削除)
353         * @param   rw 書込み可能(true)/不可能(false)
354         */
355        void addColumnValues( String[] values , String modType , boolean rw ) ;
356
357        /**
358         * 変更済みフラグを元に戻します。
359         *
360         * 一般には,データベースにテーブルモデルを登録するタイミングで、
361         * 変更済みフラグを元に戻します。
362         *
363         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
364         *
365         * @param   aRow     値が参照される行
366         */
367        void resetModify( int aRow ) ;
368
369        /**
370         * 行が書き込み可能かどうかをセットします。
371         * デフォルト/およびなにも設定しない場合は, DEFAULT_WRITABLE が
372         * 与えられています。
373         * これが true の場合は,書込み許可です。(チェックボックスを表示)
374         * false の場合は,書込み不許可(チェックボックスは表示されません。)
375         *
376         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
377         *
378         * @param   aRow     値が参照される行
379         * @param   rw 書込み可能(true)/不可能(false)
380         */
381        void setRowWritable( int aRow ,boolean rw ) ;
382
383        /**
384         * 書き込み可能な行(rowWritable == true)のチェックボックスに対して
385         * 初期値を 選択済みにするか、非選択済みにするかを指定します。
386         *
387         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
388         *
389         * @param   aRow      値が参照される行
390         * @param   rw チェックON(true)/チェックOFF(false)
391         */
392        void setRowChecked( int aRow ,boolean rw ) ;
393
394        /**
395         * 行指定の書込み許可を与えます。
396         * 具体的には,チェックボックスの表示/非表示を指定します。
397         * これが true の場合は,書込み許可です。(チェックボックスを表示)
398         * false の場合は,書込み不許可(チェックボックスは表示されません。)
399         * 行毎に書込み許可/不許可を指定する場合は,1カラム目に writable
400         * カラムを用意して true/false を指定します。
401         * この writable カラムとの論理積により最終的にチェックボックスの
402         * 表示の ON/OFF が決まります。
403         * なにも設定しない場合は, ViewForm.DEFAULT_WRITABLE が設定されます。
404         *
405         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
406         *
407         * @param   rw 書込み可能(true)/不可能(false)
408         */
409        void setDefaultRowWritable( boolean rw ) ;
410
411        /**
412         * 書き込み可能な行(rowWritable == true)のチェックボックスに対して
413         * 初期値を 選択済みにするか、非選択済みにするかを指定します。
414         *
415         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
416         *
417         * @param   rw 選択状態(true)/非選択状態(false)
418         */
419        void setDefaultRowChecked( boolean rw ) ;
420
421        /**
422         * 検索結果が オーバーフローしたかどうかを設定します。
423         * Query で検索した場合に、DB_MAX_ROW_COUNT または、Query.setMaxRowCount( int maxRowCount )
424         * で指定された値よりも検索結果が多い場合に、DBTableModel は、先の設定値までの
425         * データを取り込みます。そのときに、オーバーフローフラグを立てておくことで、最大件数を
426         * オーバーしたかどうかを判断します。
427         *
428         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
429         *
430         * @param   of オーバーフロー(true)/正常(false)
431         */
432        void setOverflow( boolean of ) ;
433
434        /**
435         * カラム(列)にmustタイプ値を割り当てます。
436         * この値は、columnCheck 時の nullCheck や mustAnyCheck の
437         * チェック対象カラムとして認識されます。
438         *
439         * @og.rev 4.1.2.1 (2008/03/13) interface に新規登録
440         *
441         * @param   dbColumn  カラムオブジェクト
442         * @param   type      mustタイプ(must,mustAny)
443         */
444        void addMustType( int dbColumn, String type ) ;
445
446        /**
447         * mustType="must"時のカラム名を、CSV形式として返します。
448         * この値は、columnCheck 時の nullCheck のチェック対象カラムとして
449         * 認識されます。
450         * カラム名配列は、ソート済みです。
451         *
452         * @og.rev 4.1.2.1 (2008/03/13) interface に新規登録
453         *
454         * @return  mustType="must"時のカラム名配列(ソート済み)
455         */
456        String[] getMustArray();
457
458        /**
459         * mustType="mustAny" 他のカラム名を、CSV形式として返します。
460         * この値は、columnCheck 時の mustAnyCheck のチェック対象カラムとして
461         * 認識されます。
462         * カラム名配列は、ソート済みです。
463         *
464         * @og.rev 4.1.2.1 (2008/03/13) interface に新規登録
465         *
466         * @return  mustType="mustAny"時のカラム名配列(ソート済み)
467         */
468        String[] getMustAnyArray();
469}