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 インターフェースを継承したデータベース情報をTableModel情報にマッピングするのに利用します。
022 *
023 * @og.group テーブル管理
024 *
025 * @version  4.0
026 * @author   Kazuhiko Hasegawa
027 * @since    JDK5.0,
028 */
029public interface DBTableModel extends DataModel<String> {
030
031        /**
032         * 行指定の書込み許可を与えます。
033         * 具体的には,チェックボックスの表示/非表示を指定します。
034         * これが true の場合は,書込み許可です。(チェックボックスを表示)
035         * false の場合は,書込み不許可(チェックボックスは表示されません。)
036         * 行毎に書込み許可/不許可を指定する場合は,1カラム目に writable
037         * カラムを用意して true/false を指定します。
038         * この writable カラムとの論理積により最終的にチェックボックスの
039         * 表示の ON/OFF が決まります。
040         *
041         * このデフォルト値は、true に設定されています。
042         *
043         */
044        static final boolean DEFAULT_WRITABLE = true;
045
046        /**
047         * 行指定用のチェックボックスに対して初期値を 選択済みにするか、
048         * 非選択済みにするかのデフォルト値を指定します。
049         *
050         * このデフォルト値は、false に設定されています。
051         *
052         */
053        static final boolean DEFAULT_CHECKED = false;
054
055        /**
056         * 変更されたタイプ(追加)
057         */
058        static final String INSERT_TYPE = "A";
059
060        /**
061         * 変更されたタイプ(変更)
062         */
063        static final String UPDATE_TYPE = "C";
064
065        /**
066         * 変更されたタイプ(削除)
067         */
068        static final String DELETE_TYPE = "D";
069
070        /**
071         * このオブジェクトを初期化します。
072         * 指定の引数分の内部配列を作成します。
073         * 具体的には,DBColumn の数を指定することになります。
074         *
075         * @param   columnCount カラム数
076         */
077        void init( int columnCount ) ;
078
079        /**
080         * このオブジェクトをヘッダー部分をコピーし、データを初期化します。
081         * これは、カラムなどヘッダー系の情報は、元と同じオブジェクトを共有し、
082         * データ部のみ空にした DBTableModel を作成することを意味します。
083         * この際、consistencyKey も複写しますので、整合性は崩れないように、
084         * データ登録を行う必要があります。
085         *
086         * @og.rev 4.0.0.0 (2007/06/28) 新規作成
087         *
088         * @return  DBTableModelオブジェクト
089         */
090        DBTableModel newModel();
091
092        /**
093         * カラムのラベル名を返します。
094         * カラムの項目名に対して,見える形の文字列を返します。
095         * 一般には,リソースバンドルと組合せて,各国ロケール毎にラベルを
096         * 切替えます。
097         * セットされた DBColumn#getLabel( int ) の値が返されます。
098         *
099         * @param   column カラム番号
100         *
101         * @return  カラムのラベル名
102         */
103        String getColumnLabel( int column ) ;
104
105        /**
106         * row および column にあるセルの属性値をStringに変換して返します。
107         *
108         * @param   row     値が参照される行
109         * @param   column  値が参照される列
110         *
111         * @return  指定されたセルの値 String
112         *
113         */
114//      String getValue(int row, int column) ;
115
116        /**
117         * row および columnName にあるセルの属性値をStringに変換して返します。
118         *
119         * @param   aRow       値が参照される行
120         * @param   columnName 値が参照されるカラム名
121         *
122         * @return  指定されたセルの値 String
123         * @see #getValue( int , int )
124         */
125        String getValue( final int aRow, final String columnName );
126
127        /**
128         * row にあるセルの属性値を配列で返します。
129         *
130         * @param   row     値が参照される行
131         *
132         * @return  指定されたセルの属性値 String[]
133         *
134         */
135//      String[] getValues( int row ) ;
136
137        /**
138         * カラム名配列を返します。
139         *
140         * @og.rev 3.0.0.0 (2002/12/25) カラム名配列を取得するメソッドを追加する。
141         *
142         * @return   nm String[]
143         */
144//      String[] getNames() ;
145
146        /**
147         * カラム(列)にカラムオブジェクトを割り当てます。
148         * カラムオブジェクトは,ラベルやネームなど,そのカラム情報を
149         * 保持したオブジェクトです。
150         *
151         * @param   dbColumn  カラムオブジェクト
152         * @param   clm       ヘッダーを適応するカラム(列)
153         */
154        void setDBColumn( int dbColumn, DBColumn clm ) ;
155
156        /**
157         * カラム(列)のカラムオブジェクトを返します。
158         * カラムオブジェクトは,ラベルやネームなど,そのカラム情報を
159         * 保持したオブジェクトです。
160         *
161         * @param       clm     ヘッダーを適応するカラム(列)
162         *
163         * @return      DBColumnカラムオブジェクト
164         */
165        DBColumn getDBColumn( int clm ) ;
166
167        /**
168         * カラムオブジェクト配列を返します。
169         * カラムオブジェクトは,ラベルやネームなど,そのカラム情報を
170         * 保持したオブジェクトです。
171         *
172         * @og.rev 4.0.0.0 (2005/12/31) 新規追加
173         *
174         * @return      カラムオブジェクト配列
175         */
176        DBColumn[] getDBColumns() ;
177
178        /**
179         * カラム名をもとに、そのカラム番号を返します。
180         * カラム名が存在しない場合は、 HybsSystemException を throw します。
181         *
182         * @param   columnName   カラム名
183         *
184         * @return  カラム番号
185         */
186//      int getColumnNo( String columnName ) ;
187
188        /**
189         * カラム名をもとに、そのカラム番号を返します。
190         * useThrow が、true の場合は、カラム名が存在しない場合は、 HybsSystemException を
191         * throw します。useThrow が、false の場合は、カラム名が存在しない場合は、 -1 を返します。
192         *
193         * @og.rev 4.0.0.0 (2005/12/31) 新規追加
194         *
195         * @param   columnName   カラム名
196         * @param   useThrow     カラム名が存在しない場合に、Exception を throw するかどうか
197         *
198         * @return  カラム番号
199         */
200        int getColumnNo( final String columnName,final boolean useThrow ) ;
201
202        /**
203         * 変更済みフラグを元に戻します。
204         *
205         * 一般には,データベースにテーブルモデルを登録するタイミングで、
206         * 変更済みフラグを元に戻します。
207         *
208         */
209        void resetModify() ;
210
211        /**
212         * 変更データを初期値(元の取り込んだ状態)に戻します。
213         *
214         * 変更タイプ(追加/変更/削除)に応じて、処理されます。
215         * 追加時は、追加された行を削除します。
216         * 変更時は、変更された行を元に戻します。
217         * 削除時は、削除フラグを解除します。
218         * それ以外の場合(変更されていない場合)は、なにもしません。
219         *
220         * @param   row  処理を戻す(取り消す)行
221         */
222        void resetRow( int row ) ;
223
224        /**
225         * row 単位に変更されたタイプ(追加/変更/削除)を返します。
226         *
227         * @param   row     値が参照される行
228         *
229         * @return  変更されたタイプの値 String
230         *
231         */
232        String getModifyType(int row) ;
233
234        /**
235         * row 単位に変更タイプ(追加/変更/削除)をセットします。
236         * このメソッドでは、データのバックアップは取りません。
237         * タイプは始めに一度登録するとそれ以降に変更はかかりません。
238         * なにも変更されていない場合は, ""(ゼロストリング)の状態です。
239         *
240         * @param   row      値が参照される行
241         * @param   modType  変更タイプ(追加/変更/削除)
242         *
243         */
244        void setModifyType( int row,String modType ) ;
245
246        /**
247         * 書込み許可を返します。
248         *
249         * @param   aRow     値が参照される行
250         *
251         * @return  書込み可能(true)/不可能(false)
252         */
253        boolean isRowWritable( int aRow ) ;
254
255        /**
256         * 書き込み可能な行(rowWritable == true)のチェックボックスに対して
257         * 初期値を 選択済みか、非選択済みかを返します。
258         *
259         * @param   row      値が参照される行
260         *
261         * @return      初期値チェックON(true)/チェックOFF(false)
262         */
263        boolean isRowChecked( int row ) ;
264
265        /**
266         * 検索結果が オーバーフローしたかどうかをチェックします。
267         * Query で検索した場合に、DB_MAX_ROW_COUNT または、Query.setMaxRowCount( int maxRowCount )
268         * で指定された値よりも検索結果が多い場合に、DBTableModel は、先の設定値までの
269         * データを取り込みます。そのときに、オーバーフローフラグを立てておくことで、最大件数を
270         * オーバーしたかどうかを判断します。
271         *
272         * @return   オーバーフロー(true)/正常(false)
273         */
274        boolean isOverflow() ;
275
276        /**
277         * 検索されたDBTableModelが登録時に同一かどうかを判断する為の 整合性キーを取得します。
278         *
279         * ここでの整合性は、同一セッション(ユーザー)毎にユニークかどうかで対応します。
280         * 分散環境(複数のセッション間)での整合性は、確保できません。
281         * 整合性キー は、オブジェクト作成時刻としますが、将来変更される可能性があります。
282         *
283         * @og.rev 3.5.5.5 (2004/04/23) 新規追加
284         *
285         * @return   整合性キー(オブジェクトの作成時刻)
286         */
287        String getConsistencyKey() ;
288
289        // =======================================================================
290        //
291        // TableModel Interface と共有していたメソッドを、独自に再定義します。
292        //
293        // =======================================================================
294
295        /**
296         * データテーブル内の行の数を返します。
297         *
298         * @og.rev 3.5.3.1 (2003/10/31) インターフェースの見直しにより、追加
299         *
300         * @return  モデルの行数
301         */
302        int getRowCount() ;
303
304        /**
305         * データテーブル内の列の数を返します。
306         *
307         * @og.rev 3.5.3.1 (2003/10/31) インターフェースの見直しにより、追加
308         *
309         * @return  モデルの列数
310         */
311        int getColumnCount() ;
312
313        /**
314         * カラム名を取得します。
315         *
316         * @og.rev 3.5.3.1 (2003/10/31) インターフェースの見直しにより、追加
317         *
318         * @param   column  最初のカラムは 0、2番目のカラムは 1、などとする。
319         *
320         * @return  カラム名
321         */
322        String getColumnName(int column) ;
323
324        // =======================================================================
325        //
326        // DBTableModelImpl.java で定義されている public メソッド残り全て
327        //
328        // =======================================================================
329
330        /**
331         * column に対応した 値を登録します。
332         * column には、番号ではなく、ラベルを指定します。
333         *
334         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
335         *
336         * @param   aRow    値が変更される行
337         * @param   columnName    値が変更されるカラム名
338         * @param   value   新しい値。null も可
339         *
340         */
341        void setValue( int aRow, String columnName, String value ) ;
342
343        /**
344         * column および row にあるセルのオブジェクト値を設定します。
345         * value は新しい値です。このメソッドは、tableChanged() 通知を生成します。
346         *
347         * @og.rev 3.1.0.0 (2003/03/20) 同期メソッド(synchronized付き)を非同期に変更する。
348         * @og.rev 3.5.3.1 (2003/10/31) インターフェースの見直しにより、private 化する。
349         * @og.rev 4.0.0.0 (2007/05/24) インターフェースの見直しにより、public 化する。
350         *
351         * @param   value   新しい値。null も可
352         * @param   aRow    値が変更される行
353         * @param   aColumn 値が変更される列
354         */
355        void setValueAt( String value, int aRow, int aColumn ) ;
356
357        /**
358         * 行を削除します。
359         * 物理削除ではなく、論理削除です。
360         * データを取り込むことは可能です。
361         *
362         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
363         *
364         * @param   aRow    論理削除される行
365         *
366         */
367        void rowDelete( int aRow ) ;
368
369        /**
370         * row にあるセルのオブジェクト値を置き換えて、行を削除します。
371         * 物理削除ではなく、論理削除です。
372         * 値を置き換えたデータを取り込むことが可能です。
373         *
374         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
375         *
376         * @param   values  新しい配列値。
377         * @param   aRow    論理削除される行
378         *
379         */
380        void rowDelete( String[] values, int aRow ) ;
381
382        /**
383         * 行を物理削除します。
384         * メモリ上で編集する場合に使用しますが,一般アプリケーションからの
385         * 使用は、物理削除の為,お勧めいたしません。
386         *
387         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
388         *
389         * @param   aRow    物理削除される行
390         *
391         */
392        void removeValue( int aRow ) ;
393
394        /**
395         * row の下に属性値配列を追加登録します。
396         *
397         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
398         *
399         * @param   values  属性値配列
400         * @param   aRow    値が参照される行
401         *
402         */
403        void addValues( String[] values ,int aRow ) ;
404
405        /**
406         * row の下に属性値配列を追加登録します。
407         * isWritableをfalseにした場合、編集不可能な状態で追加されます。
408         *
409         * @og.rev 4.3.1.0 (2008/09/04) interface に新規登録
410         *
411         * @param   values  属性値配列
412         * @param   aRow    値が参照される行
413         * @param   isWritable 編集不可能な状態で追加するか
414         *
415         */
416        void addValues( String[] values ,int aRow, boolean isWritable ) ;
417
418        /**
419         * row あるセルの属性値配列を追加登録します。
420         * これは,初期登録時のみに使用します。
421         *
422         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
423         *
424         * @param   values  属性値配列
425         *
426         */
427        void addColumnValues( String[] values ) ;
428
429        /**
430         * row にあるセルのオブジェクト値を置き換えます。
431         *
432         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
433         *
434         * @param   values  新しい配列値。
435         * @param   aRow    値が変更される行
436         *
437         */
438        void setValues( String[] values, int aRow ) ;
439
440        /**
441         * 変更済みフラグを元に戻します。
442         *
443         * 一般には,データベースにテーブルモデルを登録するタイミングで、
444         * 変更済みフラグを元に戻します。
445         *
446         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
447         *
448         * @param   aRow     値が参照される行
449         */
450        void resetModify( int aRow ) ;
451
452        /**
453         * 行が書き込み可能かどうかをセットします。
454         * デフォルト/およびなにも設定しない場合は, DEFAULT_WRITABLE が
455         * 与えられています。
456         * これが true の場合は,書込み許可です。(チェックボックスを表示)
457         * false の場合は,書込み不許可(チェックボックスは表示されません。)
458         *
459         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
460         *
461         * @param   aRow     値が参照される行
462         * @param   rw 書込み可能(true)/不可能(false)
463         */
464        void setRowWritable( int aRow ,boolean rw ) ;
465
466        /**
467         * 書き込み可能な行(rowWritable == true)のチェックボックスに対して
468         * 初期値を 選択済みにするか、非選択済みにするかを指定します。
469         *
470         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
471         *
472         * @param   aRow      値が参照される行
473         * @param   rw チェックON(true)/チェックOFF(false)
474         */
475        void setRowChecked( int aRow ,boolean rw ) ;
476
477        /**
478         * 行指定の書込み許可を与えます。
479         * 具体的には,チェックボックスの表示/非表示を指定します。
480         * これが true の場合は,書込み許可です。(チェックボックスを表示)
481         * false の場合は,書込み不許可(チェックボックスは表示されません。)
482         * 行毎に書込み許可/不許可を指定する場合は,1カラム目に writable
483         * カラムを用意して true/false を指定します。
484         * この writable カラムとの論理積により最終的にチェックボックスの
485         * 表示の ON/OFF が決まります。
486         * なにも設定しない場合は, ViewForm.DEFAULT_WRITABLE が設定されます。
487         *
488         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
489         *
490         * @param   rw 書込み可能(true)/不可能(false)
491         */
492        void setDefaultRowWritable( boolean rw ) ;
493
494        /**
495         * 書き込み可能な行(rowWritable == true)のチェックボックスに対して
496         * 初期値を 選択済みにするか、非選択済みにするかを指定します。
497         *
498         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
499         *
500         * @param   rw 選択状態(true)/非選択状態(false)
501         */
502        void setDefaultRowChecked( boolean rw ) ;
503
504        /**
505         * 検索結果が オーバーフローしたかどうかを設定します。
506         * Query で検索した場合に、DB_MAX_ROW_COUNT または、Query.setMaxRowCount( int maxRowCount )
507         * で指定された値よりも検索結果が多い場合に、DBTableModel は、先の設定値までの
508         * データを取り込みます。そのときに、オーバーフローフラグを立てておくことで、最大件数を
509         * オーバーしたかどうかを判断します。
510         *
511         * @og.rev 3.5.6.4 (2004/07/16) interface に新規登録
512         *
513         * @param   of オーバーフロー(true)/正常(false)
514         */
515        void setOverflow( boolean of ) ;
516
517        /**
518         * カラム(列)にmustタイプ値を割り当てます。
519         * この値は、columnCheck 時の nullCheck や mustAnyCheck の
520         * チェック対象カラムとして認識されます。
521         *
522         * @og.rev 4.1.2.1 (2008/03/13) interface に新規登録
523         *
524         * @param   dbColumn  カラムオブジェクト
525         * @param   type      mustタイプ(must,mustAny)
526         */
527        void addMustType( int dbColumn, String type ) ;
528
529        /**
530         * mustType="must"時のカラム名を、カンマ区切り文字列として返します。
531         * この値は、columnCheck 時の nullCheck のチェック対象カラムとして
532         * 認識されます。
533         * カラム名配列は、ソート済みです。
534         *
535         * @og.rev 4.1.2.1 (2008/03/13) interface に新規登録
536         *
537         * @return  mustType="must"時のカラム名配列(ソート済み)
538         */
539        String[] getMustArray();
540
541        /**
542         * mustType="mustAny" 他のカラム名を、カンマ区切り文字列として返します。
543         * この値は、columnCheck 時の mustAnyCheck のチェック対象カラムとして
544         * 認識されます。
545         * カラム名配列は、ソート済みです。
546         *
547         * @og.rev 4.1.2.1 (2008/03/13) interface に新規登録
548         *
549         * @return  mustType="mustAny"時のカラム名配列(ソート済み)
550         */
551        String[] getMustAnyArray();
552}