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.io;
017
018import org.opengion.fukurou.system.OgRuntimeException ;         // 6.4.2.0 (2016/01/29)
019
020import org.opengion.hayabusa.db.ColumnActionListener;           // 6.2.2.0 (2015/03/27)
021
022/**
023 * 指定の区切り記号(初期値:タブ区切り)ファイルの読み取りクラスです。
024 *
025 * 名前,データの入力部のみオーバーライドすれば,各種入力フォーマットに合わせた
026 * サブクラスを実現する事が可能です。
027 *
028 * @og.group ファイル入力
029 *
030 * @version  4.0
031 * @author   Kazuhiko Hasegawa
032 * @since    JDK5.0,
033 */
034public abstract class AbstractTableReader implements TableReader {
035        /** このプログラムのVERSION文字列を設定します。   {@value} */
036        private static final String VERSION = "8.0.0.0 (2021/08/20)" ;
037
038        /** システムの改行コードを設定します。*/
039
040        /** 区切り文字列 */
041        protected String        separator       = TAB_SEPARATOR;        // 6.2.0.0 (2015/02/27) 項目区切り文字。protected化
042
043        private   ColumnActionListener  listener        ;               // 6.2.2.0 (2015/03/27)
044
045        // 3.5.4.5 (2004/01/23) カラム名の外部指定を出来る様にする。
046        /** カラム名 */
047        protected String        columns         ;                       // 外部指定のカラム名 ( 4.3.4.7 (2009/01/22) protectedに変更 )
048        // 6.1.0.0 (2014/12/26) 読み取り対象外のカラム列を、外部(タグ)より指定する。
049
050        private boolean   useNumber             = true;         // 3.7.0.5 (2005/04/11)
051
052        private int               skipRowCount  ;                       // 5.1.6.0 (2010/05/01) データの読み飛ばし設定
053
054        // 5.2.1.0 (2010/10/01) コードリソース毎のラベル逆引きマップ
055
056        // 6.2.0.0 (2015/02/27) TableReader クラスの呼び出し元メソッドの共通化(EXCEL,TEXT)
057        /** シート名 */
058        protected String  sheetName             ;               // 3.5.4.2 (2003/12/15)
059        /** シート番号 */
060        protected String  sheetNos              ;               // 5.5.7.2 (2012/10/09)
061        /** カラム名(CSV形式) */
062        protected String  constKeys             ;               // 5.5.8.2 (2012/11/09) 固定値となるカラム名(CSV形式)
063        /** 固定値となるアドレス */
064        protected String  constAdrs             ;               // 5.5.8.2 (2012/11/09) 固定値となるアドレス(行-列,行-列,・・・)
065        /** BREAK条件 */
066        protected String  nullBreakClm  ;               // 5.5.8.2 (2012/11/09) 取込み条件/Sheet BREAK条件
067        /** 行読み飛ばし */
068        protected String  nullSkipClm   ;               // 6.2.3.0 (2015/05/01) 行読み飛ばし
069
070        private boolean   useDebug              ;               // 5.5.7.2 (2012/10/09) デバッグ情報の出力するかどうか
071
072        /**
073         * デフォルトコンストラクター
074         *
075         * @og.rev 6.4.2.0 (2016/01/29) PMD refactoring. Each class should declare at least one constructor.
076         */
077        protected AbstractTableReader() { super(); }            // これも、自動的に呼ばれるが、空のメソッドを作成すると警告されるので、明示的にしておきます。
078
079        /**
080         * DBColumn オブジェクトをDBTable に設定します。
081         *
082         * ここでは、omitNames 属性を加味した、カラム名を作成します。
083         * その際、ゼロ文字列のカラム名は、omit します。
084         * 戻り値は、新しいカラム数(omitNames を加味、ゼロ文字列のカラムも除去)です。
085         *
086         * ※ 6.1.0.0 (2014/12/26) で、omitNames 属性を追加します。
087         *    これに伴い、従来は、EXCELのみ、#NAME で、ゼロ文字列のカラム名や
088         *    columns 指定で、a,b,,,,,,x のようなカラム名指定で、カラム飛ばしを
089         *    実装していましたが、その他の Reader でも、対応します。
090         *    これは、互換性に影響しますので、ご注意ください。
091         *    (読み込んでも、カラム名が無いので、使えなかったと思いますけど…)
092         *
093         * @og.rev 3.5.4.2 (2003/12/15) private を protected に変更。
094         * @og.rev 3.5.4.5 (2004/01/23) DBColumn 配列に値をセットします。
095         * @og.rev 5.2.1.0 (2010/10/01) useRenderer対応(コードリソース毎のラベル逆引き)
096         * @og.rev 6.1.0.0 (2014/12/26) omitNames 属性を追加
097         * @og.rev 6.2.1.0 (2015/03/13) ロングラベルから、コード値を見つける機能を、廃止します。
098         * @og.rev 6.2.2.0 (2015/03/27) ColumnActionListener 対応。
099         * @og.rev 6.3.9.0 (2015/11/06) コンストラクタで初期化されていないフィールドを null チェックなしで利用している(findbugs)
100         *
101         * @param names カラム名配列
102         * @return 新しいカラム数(omitNames を加味、ゼロ文字列のカラムも除去)
103         */
104        protected int setTableDBColumn( final String[] names ) {
105                // 6.3.9.0 (2015/11/06) コンストラクタで初期化されていないフィールドを null チェックなしで利用している(findbugs)
106                if( listener == null ) {
107                        final String errMsg = "#setColumnActionListener(ColumnActionListener)を先に実行しておいてください。" ;
108                        throw new OgRuntimeException( errMsg );
109                }
110
111                listener.columnNames( names );                  // 6.2.2.0 (2015/03/27)
112
113                return names == null ? 0 : names.length;
114        }
115
116        /**
117         * #NAME のオリジナルカラム名配列がそろった段階で、イベントが発生します。
118         *
119         * @og.rev 7.3.1.3 (2021/03/09) #NAMEのオリジナルを取得できるようにします。
120         * @og.rev 8.0.0.0 (2021/08/20) spotbugs:Bug kind and pattern: UwF - UWF_FIELD_NOT_INITIALIZED_IN_CONSTRUCTOR
121         *
122         * @param   names  カラム名配列
123         */
124        protected void setOriginalNames( final String[] names ) {
125                // 8.0.0.0 (2021/08/20) コンストラクタで初期化されていないフィールドを null チェックなしで利用している(spotbugs)
126                if( listener == null ) {
127                        final String errMsg = "#setColumnActionListener(ColumnActionListener)を先に実行しておいてください。" ;
128                        throw new OgRuntimeException( errMsg );
129                }
130
131                listener.originalNames( names );
132        }
133
134        /**
135         * DBTableModelオブジェクトに、1行分のデータを追加します。
136         * これ自体は、メソッドの共通化による 拡張をしやすくするために用意しました。
137         *
138         * @og.rev 5.2.1.0 (2010/10/01) 新規作成
139         * @og.rev 6.2.0.0 (2015/02/27) コードリソースの逆引き処理の前に、Key:Val 分解を実行する。
140         * @og.rev 6.2.1.0 (2015/03/13) ロングラベルから、コード値を見つける機能を、廃止します。
141         * @og.rev 6.2.2.0 (2015/03/27) ColumnActionListener 対応。
142         * @og.rev 6.3.9.0 (2015/11/06) コンストラクタで初期化されていないフィールドを null チェックなしで利用している(findbugs)
143         *
144         * @param values 1行分のデータ配列
145         * @param rowNo  行番号
146         */
147        protected void setTableColumnValues( final String[] values, final int rowNo ) {
148                // 6.3.9.0 (2015/11/06) コンストラクタで初期化されていないフィールドを null チェックなしで利用している(findbugs)
149                if( listener == null ) {
150                        final String errMsg = "#setColumnActionListener(ColumnActionListener)を先に実行しておいてください。" ;
151                        throw new OgRuntimeException( errMsg );
152                }
153
154                listener.values( values,rowNo );                                        // 6.2.2.0 (2015/03/27)
155        }
156
157        /**
158         * 新しくEXCELのシートを処理する際に、シート名をセットするときに呼び出されます。
159         * EXCEL関係の処理の場合のみ呼び出されます。
160         *
161         * @og.rev 7.3.1.1 (2021/02/25) 現在実行中のシート名をセットする
162         *
163         * @param   sheetName   現在実行中のシート名
164         */
165        protected void shtName( final String sheetName ) {
166                // 6.3.9.0 (2015/11/06) コンストラクタで初期化されていないフィールドを null チェックなしで利用している(findbugs)
167                if( listener == null ) {
168                        final String errMsg = "#setColumnActionListener(ColumnActionListener)を先に実行しておいてください。" ;
169                        throw new OgRuntimeException( errMsg );
170                }
171
172                listener.shtName( sheetName );
173        }
174
175        /**
176         * データを読み込む場合の,区切り文字をセットします。
177         *
178         * なお,このメソッドは,サブクラスによっては,使用しない場合があります。
179         * もし,使用しないサブクラスを作成する場合は, UnsupportedOperationException
180         * を throw するように,サブクラスで実装して下さい。
181         *
182         * @og.rev 3.1.1.0 (2003/03/28) 同期メソッド(synchronized付き)を非同期に変更する。
183         *
184         * @param   sep 区切り文字
185         */
186        public void setSeparator( final String sep ) {
187                if( sep != null ) { this.separator = sep; }
188        }
189
190        /**
191         * DBTableModelのデータとしてEXCELファイルを読み込むときのシート名を設定します。
192         * これにより、複数の形式の異なるデータを順次読み込むことや、シートを指定して
193         * 読み取ることが可能になります。
194         * sheetNos と sheetName が同時に指定された場合は、sheetNos が優先されます。エラーにはならないのでご注意ください。
195         * のでご注意ください。
196         * このメソッドは、isExcel() == true の場合のみ利用されます。
197         *
198         * ※ このクラスでは実装されていません。
199         *
200         * @og.rev 3.5.4.2 (2003/12/15) 新規追加
201         * @og.rev 6.2.0.0 (2015/02/27) TableReader クラスの呼び出し元メソッドの共通化(EXCEL,TEXT)
202         *
203         * @param   sheetName シート名
204         */
205        public void setSheetName( final String sheetName ) {
206                this.sheetName = sheetName;
207        }
208
209        /**
210         * EXCELファイルを読み込むときのシート番号を指定します(初期値:0)。
211         *
212         * EXCEL読み込み時に複数シートをマージして取り込みます。
213         * シート番号は、0 から始まる数字で表します。
214         * ヘッダーは、最初のシートのカラム位置に合わせます。(ヘッダータイトルの自動認識はありません。)
215         * よって、指定するシートは、すべて同一レイアウトでないと取り込み時にカラムのずれが発生します。
216         *
217         * シート番号の指定は、CSV形式で、複数指定できます。また、N-M の様にハイフンで繋げることで、
218         * N 番から、M 番のシート範囲を一括指定可能です。また、"*" による、全シート指定が可能です。
219         * これらの組み合わせも可能です。( 0,1,3,5-8,10-* )
220         * ただし、"*" に関しては例外的に、一文字だけで、すべてのシートを表すか、N-* を最後に指定するかの
221         * どちらかです。途中には、"*" は、現れません。
222         * シート番号は、重複(1,1,2,2)、逆転(3,2,1) での指定が可能です。これは、その指定順で、読み込まれます。
223         * sheetNos と sheetName が同時に指定された場合は、sheetNos が優先されます。エラーにはならないのでご注意ください。
224         * このメソッドは、isExcel() == true の場合のみ利用されます。
225         *
226         * 初期値は、0(第一シート) です。
227         *
228         * ※ このクラスでは実装されていません。
229         *
230         * @og.rev 5.5.7.2 (2012/10/09) 新規追加
231         * @og.rev 6.2.0.0 (2015/02/27) TableReader クラスの呼び出し元メソッドの共通化(EXCEL,TEXT)
232         *
233         * @param   sheetNos EXCELファイルのシート番号(0から始まる)
234         * @see         #setSheetName( String )
235         */
236        public void setSheetNos( final String sheetNos ) {
237                this.sheetNos = sheetNos;
238        }
239
240        /**
241         * 固定値となるカラム名(CSV形式)と、constAdrs 固定値となるアドレス(行-列,行-列,・・・)を設定します。
242         *
243         * アドレスは、EXCEL上の行-列をCSV形式で指定します。
244         * 行列は、EXCELオブジェクトに準拠するため、0から始まる整数です。
245         * 0-0 ⇒ A1 , 1-0 ⇒ A2 , 0-1 ⇒ B1 になります。
246         * これにより、シートの一か所に書かれている情報を、DBTableModel のカラムに固定値として
247         * 設定することができます。
248         * 例として、DB定義書で、テーブル名をシートの全レコードに設定したい場合などに使います。
249         * このメソッドは、isExcel() == true の場合のみ利用されます。
250         *
251         * 5.7.6.3 (2014/05/23) より、
252         *   ①EXCEL表記に準拠した、A1,A2,B1 の記述も処理できるように対応します。
253         *     なお、A1,A2,B1 の記述は、必ず、英字1文字+数字 にしてください。(A~Zまで)
254         *   ②処理中のEXCELシート名をカラムに割り当てるために、"SHEET" という記号に対応します。
255         * 例えば、sheetConstKeys="CLM,LANG,NAME" とし、sheetConstAdrs="0-0,A2,SHEET" とすると、
256         * NAMEカラムには、シート名を読み込むことができます。
257         * これは、内部処理の簡素化のためです。
258         *
259         * 例として、DB定義書で、テーブル名をシートの全レコードに設定したい場合などに使います。
260         * このメソッドは、isExcel() == true の場合のみ利用されます。
261         *
262         * @og.rev 5.5.8.2 (2012/11/09) 新規追加
263         *
264         * @param   constKeys 固定値となるカラム名(CSV形式)
265         * @param   constAdrs 固定値となるアドレス(行-列,行-列,・・・)
266         */
267        public void setSheetConstData( final String constKeys,final String constAdrs ) {
268                this.constKeys = constKeys;
269                this.constAdrs = constAdrs;
270        }
271
272        /**
273         * ここに指定されたカラム列に NULL が現れた時点で読み取りを中止します。
274         *
275         * これは、指定のカラムは必須という事を条件に、そのレコードだけを読み取る処理を行います。
276         * 複数Sheetの場合は、次のSheetを読みます。
277         * 現時点では、Excel の場合のみ有効です。
278         *
279         * @og.rev 5.5.8.2 (2012/11/09) 新規追加
280         * @og.rev 6.2.0.0 (2015/02/27) TableReader クラスの呼び出し元メソッドの共通化(EXCEL,TEXT)
281         *
282         * @param   clm カラム列
283         */
284        public void setNullBreakClm( final String clm ) {
285                nullBreakClm = clm;
286        }
287
288        /**
289         * ここに指定されたカラム列に NULL が現れたレコードは読み飛ばします。
290         *
291         * 例えば、更新対象カラムで、null の場合は、何もしない、などのケースで使用できます。
292         * 複数カラムの場合は、AND条件やOR条件などが、考えられるため、
293         * カラムを一つにまとめて、指定してください。
294         *
295         * @og.rev 6.2.3.0 (2015/05/01) 行読み飛ばし nullSkipClm追加
296         *
297         * @param   clm カラム列
298         */
299        public void setNullSkipClm( final String clm ) {
300                nullSkipClm = clm;
301        }
302
303        /**
304         * 読み取り元ファイルのカラム列を、外部(タグ)より指定します。
305         * ファイルに記述された #NAME より優先して使用されます。
306         *
307         * @og.rev 3.5.4.5 (2004/01/23) 新規作成
308         *
309         * @param   clms 読み取り元ファイルのカラム列(CSV形式)
310         */
311        public void setColumns( final String clms ) {
312                columns = clms ;
313        }
314
315        /**
316         * 行番号情報を指定[true:使用している/false:していない]します(初期値:true)。
317         *
318         * 通常のフォーマットでは、各行の先頭に行番号が出力されています。
319         * 読み取り時に、#NAME 属性を使用する場合は、この行番号を無視しています。
320         * #NAME 属性を使用せず、columns 属性でカラム名を指定する場合(他システムの
321         * 出力ファイルを読み取るケース等)では、行番号も存在しないケースがあり、
322         * その様な場合に、useNumber="false" を指定すれば、データの最初から読み取り始めます。
323         * この場合、出力データのカラムの並び順が変更された場合、columns 属性も
324         * 指定しなおす必要がありますので、できるだけ、#NAME 属性を使用するように
325         * してください。
326         * なお、EXCEL 入力には、この設定は適用されません。(暫定対応)
327         * 初期値は、true(使用する) です。
328         *
329         * @og.rev 3.7.0.5 (2005/04/11) 新規追加
330         *
331         * @param       useNumber       行番号情報  [true:使用する/false:使用しない]
332         */
333        public void setUseNumber( final boolean useNumber ) {
334                this.useNumber = useNumber ;
335        }
336
337        /**
338         * データの読み始めの初期値を取得します。
339         *
340         * TAB区切りテキストやEXCEL等のデータの読み始めの初期値を指定します。
341         * ファイルの先頭行が、0行としてカウントしますので、設定値は、読み飛ばす
342         * 件数になります。(1と指定すると、1件読み飛ばし、2行目から読み込みます。)
343         * 読み飛ばしは、コメント行などは、無視しますので、実際の行数分読み飛ばします。
344         * #NAME属性や、columns 属性は、有効です。
345         *
346         * @og.rev 5.1.6.0 (2010/05/01) 新規作成
347         *
348         * @return      読み始めの初期値
349         */
350        public int getSkipRowCount() {
351                return skipRowCount ;
352        }
353
354        /**
355         * データの読み飛ばし件数を設定します。
356         *
357         * TAB区切りテキストやEXCEL等のデータの読み始めの初期値を指定します。
358         * ファイルの先頭行が、0行としてカウントしますので、設定値は、読み飛ばす
359         * 件数になります。(1と指定すると、1件読み飛ばし、2行目から読み込みます。)
360         * 読み飛ばしは、コメント行などは、無視しますので、実際の行数分読み飛ばします。
361         * #NAME属性や、columns 属性は、有効です。
362         *
363         * @og.rev 5.1.6.0 (2010/05/01) 新規作成
364         *
365         * @param       count 読み始めの初期値
366         */
367        public void setSkipRowCount( final int count ) {
368                skipRowCount = count;
369        }
370
371        /**
372         * 行番号情報を、使用している(true)/していない(false)を返します。
373         *
374         * 通常のフォーマットでは、各行の先頭に行番号が出力されています。
375         * 読み取り時に、#NAME 属性を使用する場合は、この行番号を無視しています。
376         * #NAME 属性を使用せず、columns 属性でカラム名を指定する場合(他システムの
377         * 出力ファイルを読み取るケース等)では、行番号も存在しないケースがあり、
378         * その様な場合に、useNumber="false" を指定すれば、データの最初から読み取り始めます。
379         * この場合、出力データのカラムの並び順が変更された場合、columns 属性も
380         * 指定しなおす必要がありますので、できるだけ、#NAME 属性を使用するように
381         * してください。
382         * なお、EXCEL 入力には、この設定は適用されません。(暫定対応)
383         * 初期値は、true(使用する) です。
384         *
385         * @og.rev 3.7.0.5 (2005/04/11) 新規追加
386         * @og.rev 4.0.0.0 (2007/07/20) メソッド名変更(getUseNumber() ⇒  isUseNumber())
387         *
388         * @return      行番号情報を、使用している(true)/していない(false)を指定
389         */
390        protected boolean isUseNumber() {
391                return useNumber ;
392        }
393
394        /**
395         * ColumnActionListenerオブジェクトを設定します。
396         *
397         * ColumnActionListenerオブジェクトは、カラム名配列設定時と、それに対応する値配列設定時に
398         * 呼ばれるイベントリスナーです。
399         * 具体的なテーブル処理は、このイベントを使用して書き込みを行います。
400         *
401         * @og.rev 6.2.2.0 (2015/03/27) 新規作成
402         *
403         * @param       listener        ColumnActionListenerオブジェクト
404         */
405        public void setColumnActionListener( final ColumnActionListener listener ) {
406                this.listener = listener;
407        }
408
409        /**
410         * デバッグ情報を出力するかどうか[true:する/false:しない]を指定します。
411         *
412         * EXCELなどを読み取る場合、シートマージで読み取ると、エラー時の行番号が、連番になるため、
413         * どのシートなのか、判らなくなります。
414         * そこで、どうしてもわからなくなった場合に備えて、デバッグ情報を出力できるようにします。
415         * 通常は使用しませんので、設定を無視します。
416         * 初期値は、false:デバッグ情報を出力しない です。
417         *
418         * @og.rev 5.5.7.2 (2012/10/09) 新規作成
419         *
420         * @param       useDebug        デバッグ出力するか [true:する/false:しない]
421         */
422        public void setDebug( final boolean useDebug ) {
423                this.useDebug = useDebug;
424        }
425
426        /**
427         * デバッグ情報を出力するかどうか[true:する/false:しない]を取得します。
428         *
429         * EXCELなどを読み取る場合、シートマージで読み取ると、エラー時の行番号が、連番になるため、
430         * どのシートなのか、判らなくなります。
431         * そこで、どうしてもわからなくなった場合に備えて、デバッグ情報を出力できるようにします。
432         *
433         * @og.rev 5.5.7.2 (2012/10/09) 新規作成
434         *
435         * @return      デバッグ出力 [true:する/false:しない]
436         */
437        protected boolean isDebug() {
438                return useDebug ;
439        }
440}