Struktura pliku konfiguracyjnego

Do poprawnego działania PlusBarcodeReader potrzebuje pliku konfiguracyjnego, który jest podawany przy wywołaniu programu. Plik ten jest w formacie INI. Kodowanie pliku konfiguracyjnego powinno być ustawione na UTF-8 bez BOM lub ANSI. Plik składa się z trzech części: ogólnych ustawień konfiguracji przetwarzania poszczególnych katalogów oraz konfiguracji logów.

Ustawienia ogólne

Sekcja TempDir

• tempDirectory - Parametr wskazujący, gdzie przechowywać tymczasowe dane o przetwarzanych plikach przez pdfbox. Jeżeli nie podamy katalogu, wszystkie dane będą przechowywane w pamięci, co przy bardzo dużych plikach (>500 stron) może powodować wyczerpywanie się pamięci.Dla bezpieczeństwa należy zapewnić około 5GB wolnego miejsca w tym katalogu.
  

Sekcja ResizeFiles

Konfiguracja ResizeFiles odpowiada za zamianę rozmiaru pliku pdf. Niezbędne jest wcześniejsze ustalenie parametru tempDirectory.

• OnSuccess - Parametr określa, czy zmiana rozmiaru pliku ma być wykonywana, gdy pomyślnie został odczytany kod i plik został umieszczony w odpowiednim katalogu.

• OnError - Parametr określa, czy zmiana rozmiaru pliku ma być wykonywana, gdy nie został odczytany kod i następuje przekopiowanie pliku do katalogu z błędnymi plikami.

• Scale - Parametr określa zmianę rozdzielczości w skali procentowej. Parametr ten jest obowiązkowy.

• Compression - Parametr określa poziom kompresji podczas generowania nowego pdf'a. Im wyższa wartość, tym lepsza jakość, ale też większy rozmiar pliku. Wartości mogą być z zakresu 0.1 - 1.0. Dla innych wartości ustawiane będzie domyślnie 0.75. Parametr ten jest opcjonalny. Domyślna wartość to 0.75.

• Method - Parametr określa metodę skalowania obrazu. Metody dające lepsze wyniki są wolniejsze. Możliwe wartości to: AUTO, SPEED, BALANCED, QUALITY, ULTRA. Domyślnie ustawiana jest wartość ULTRA.

Sekcja Directories_IDs

W sekcji tej definiowane są identyfikatory konfiguracji związane z przetwarzaniem wybranego katalogu. Podajemy tutaj nazwę identyfikatora wraz z wartością true lub false, która określa czy dana konfiguracja jest aktywna (przetwarzana w momencie uruchomienia programu), czy też nie np. 

Umowy=true

Faktury=true

Korespondencja=false

Podane nazwy są w dalszej części pliku konfiguracyjnego wykorzystywane jako przedrostek do konfiguracji przetwarzania konkretnego katalogu. Dzięki temu istnieje możliwość zdefiniowania przetwarzania kilku katalogów w jednym pliku konfiguracyjnym, które będą uruchamiane kolejno przy pojedynczym uruchomieniu PlusBarcodeReader.

Ustawienia przetwarzania danego katalogu

Ta część umożliwia skonfigurowanie przetwarzania wybranego katalogu, którego identyfikator został zdefiniowany w sekcji Directories_IDs. W tej dokumentacji identyfikatory te będą oznaczane jako %ID%.

Sekcja %ID%

Sekcja definiująca jakie czynności mają być wykonane przy przetwarzaniu katalogu. Obecnie możliwe opcje do wyboru to: ProcessDirectory i RunAppAfterProcess. Możliwe wartości tych parametrów to: true lub false określają czy dana operacja ma być wykonana.

• ProcessDirectory - określa czy wykonać przetwarzanie plików znajdujące się w powiązanym katalogu.
• RunAppAfterProcess - określa czy po wykonaniu przetwarzania wywołać dodatkową metodę wybranego obiektu JAVY lub wybrane polecenie systemowe.

Sekcja %ID%_ProcessDirectory

Sekcja zawiera ogólne parametry dotyczące przetwarzania plików w wybranym katalogu.

• SourceDirectory - określa katalog źródłowy, z którego pliki będą przetwarzane przez PlusBarcodeReader.
• ReadSubDirectories - określa czy mają być przetwarzana podkatalogi wskazanego katalogu. Możliwe wartości to: true lub false.
• OrgFileNamePattern - parametr zawierający wyrażenie regularne, do którego dopasowywane są nazwy plików (wraz z rozszerzeniem). Przetwarzane są tylko te pliki, które pasują do podanego wzorca.
• OrgFileNameMask - parametr określający maskę do podanego wyrażenia regularnego, według której przekształcana jest oryginalna nazwa pliku. Istotny w przypadku sortowania plików po nazwie.
• ImageType - określa format obrazów w plikach pdf. Możliwe wartości to: TYPE_BYTE_BINARY, TYPE_BYTE_GRAY, TYPE_3BYTE_BGR, TYPE_4BYTE_ABGR, TYPE_4BYTE_ABGR_PRE, TYPE_BYTE_INDEXED, TYPE_CUSTOM, TYPE_INT_ARGB, TYPE_INT_ARGB_PRE, TYPE_INT_BGR, TYPE_USHORT_555_RGB, TYPE_USHORT_565_RGB, TYPE_USHORT_GRAY (opis typów tutaj).
• ImageDPI - określa rozdzielczość obrazów w plikach pdf. Wartość podawana w DPI.
• ProcessFilesSeparetly - parametr przyjmuje wartości true lub false. Gdy wartość równa true, to każdy plik przetwarzany jest osobno. Gdy wartość równa false, wszystkie pliki w katalogu traktowane są jako jedna całość - pliki są sortowane zgodnie z parametrem OrderBy i według tej kolejności przetwarzane tak jakby stanowiły jeden plik.
• OrderBy - określa sposób sortowania plików. Parametr istotny w przypadku gdy pliki traktowane są jako jedna całość (ProcessFilesSeparetly=false). Możliwe wartości: FileDate - sortowanie po dacie modyfikacji; FileName - sortowanie po nazwie pliku przetworzonej przez wyrażenie regularne. Domyślnie sortowanie jest po dacie.
• ClassifiedAllPages - parametr określający czy każda strona musi być przydzielona do jakiejś klasy. Jeśli wartość równa true to w przypadku wystąpienia stron nie przydzielonych występuje wyjątek i przetwarzanie kończy się jako błędne. Jeśli wartość równa false to strony nieprzydzielone są ignorowane i przetwarzanie traktowane jako zakończone sukcesem.
• EachPageInOnlyOneClass parametr określa czy dana strona może być przydzielona do więcej niż jednej klasy. Gdy wartość równa false dana strona może występować w wielu klasach. Jeśli wartość równa true to w przypadku gdy dana strona został już przydzielona do jednej klasy, a z definicji innej klasy wynika, że strona ma być również do niej przydzielona, to ta klasa jest usuwana (pozostaje tylko pierwsza klasa).
• OnSuccess - określa co zrobić z oryginalnymi plikami w przypadku prawidłowego ich przetworzenia. Możliwe wartości to: None - plik pozostaje bez zmian; Copy - plik jest kopiowany; Move - plik jest przenoszony; Delete - plik jest usuwany.
• SuccessDirectory - określa katalog docelowy dla oryginalnych plików w przypadku przetwarzania zakończonego powodzeniem.
• OnError - określa co zrobić z oryginalnymi plikami w przypadku wystąpienia wyjątku przy przetwarzaniu. Możliwe wartości to: None - plik pozostaje bez zmian; Copy - plik jest kopiowany; Move - plik jest przenoszony; Delete - plik jest usuwany.
• ErrorDirectory - określa katalog docelowy dla oryginalnych plików w przypadku przetwarzania zakończonego błędem.

Sekcja %ID%_Barcodes

Sekcja definiuje identyfikatory kodów kreskowych, które będą wyszukiwane w plikach. Mogą one przybierać wartość true (przy przetwarzaniu następuje próba wyszukania kodu zdefiniowanego pod tym identyfikatorem) lub false (przy przetwarzaniu wyszukiwanie tego kodu jest pomijane) np.

Kod_faktury=true

Kod_zalacznika=false

W dalszej części dokumentacji identyfikatory te będą oznaczane jako %Barcode_1%, %Barcode_2% itp..

Sekcja %ID%_%Barcode_1%

Sekcja definiuje kod kreskowy, którego identyfikator został podany w sekcji %ID%_Barcodes.

• BarcodeTypes - określa typ kodu kreskowego. Możliwe wartości to: 
  • AZTEC
  • CODABAR
  • CODE_128
  • CODE_39
  • CODE_93
  • DATA_MATRIX
  • EAN_13
  • EAN_8
  • ITF 
  • MAXICODE
  • PDF_417 
  • QR_CODE
  • RSS_14
  • RSS_EXPANDED
  • UPC_A
  • UPC_E
  • UPC_EAN_EXTENSION
• BarcodePattern - określa wyrażenie regularne, do którego będzie dopasowywana wartość kodu kreskowego. Jeśli rozpoznany kod kreskowy nie pasuje do podanego wzorca jest on ignorowany.
  
• SkipNextIdenticalBarcode - parametr określa czy kod kreskowy będzie ignorowany (wartość parametru true) w przypadku, gdy poprzedni rozpoznany kod kreskowy ma taką samą wartość. Jeśli wartość równa false, to wartości kolejnych kodów mogą się powtarzać.

Sekcja %ID%_Classes

 Sekcja zawiera identyfikatory klas dokumentów do jakich mają być przydzielony wybrane strony z przetwarzanych plików. Możliwe wartości przy identyfikatorach to true i false określające czy dana klasa ma być uwzględniana przy przetwarzaniu. W dalszej części dokumentacji identyfikatory te będą oznaczane jako %Class%.

Sekcja %ID%_%Class%

W sekcji tej określa się parametry definiujące klasę dokumentu.

• Start - parametr określający, w odniesieniu do znalezionych kodów kreskowych w pliku, początek występowania danej klasy. Jako wartość przyjmuje identyfikatory kodów kreskowych z sekcji %ID%_Barcodes. Może przyjmować wiele wartości rozdzielonych po średniku. Dana klasa rozpoczyna się na każdej stronie, na której znajdują się podane po średniku kody kreskowe. Istnieje możliwość dodania przesunięcia do kodu kreskowego ze znakiem + i - , które określa ile stron do przodu lub do tyłu od podanego kodu ma rozpocząć się dana klasa. Parametr przyjmuje też specjalną wartość: first_page, która określa pierwszą stronę pliku. Przykład:

Start=%Barcode_1%+1;first_page;%Barcode_2%

• Stop - parametr określający, w odniesieniu do znalezionych kodów kreskowych w pliku, koniec występowania danej klasy. Jako wartość przyjmuje identyfikatory kodów kreskowych z sekcji %ID%_Barcodes. Może przyjmować wiele wartości rozdzielonych po średniku. Dana klasa kończy się na każdej stronie, na której znajdują się podane po średniku kody kreskowe. Istnieje możliwość dodania przesunięcia do kodu kreskowego ze znakiem + i - , które określa ile stron do przodu lub do tyłu od podanego kodu ma kończyć się dana klasa. Parametr przyjmuje też specjalną wartość: last_page, która określa ostatnią stronę pliku. Przykład:

Stop=last_page;%Barcode_1%;%Barcode_2%-3

• SplitEachPage - jeśli wartość parametru jest równa false, to klasa zapisywana jest do jednego pliku. Jeśli wartość wynosi true, każda strona zapisywana jest w osobnym pliku. W tym wypadku wymagany parametr $Num$ w nazwie pliku, inaczej pliki będa nadpisywane.
• Indicies - określa liczbę indeksów, które będą zdefiniowane dla tej klasy. Za indeks przyjmuje się wartość kodu kreskowego, która może być przetworzona przez wyrażenie regularne i zapisana w nazwie pliku dla tej klasy. Kolejne parametry określające konfigurację poszczególnych indeksów muszą zaczynać się od "IndexN", gdzie N określa kolejny numer indeksu i jest mniejsze lub równe wartości parametru Indicies.
• IndexN - parametr jako wartości przyjmuje identyfikatory kodów kreskowych zdefiniowane w sekcji %ID%_Barcodes. Określa on która wartość kodu kreskowego ma być przypisana do indeksu. W przypadku gdy danego kodu kreskowego nie uda się zidentyfikować w tej klasie ustawiana jest wartość NULL.
• IndexNRange - parametr określa zakres, w obrębie którego wyszukiwane są kody danego typu. Możliwe wartości: Class - wyszukiwanie kodu w obrębie stron przypisanych do danej klasy; Batch - wyszukiwanie kodu w obrębie zestawu dokumentów zdefiniowanego w sekcji %ID%_Batch
• IndexNMultipleValue - gdy parametr równy true wszystkie wartości kodów są przypisywane do indeksu. Wartości rozdzielane są po średniku. Gdy parametr jest równy false do indeksu przypisywane jest pierwsza znaleziona wartość kodu kreskowego.
• IndexNRegExp - wyrażenie regularne dopasowywane do wartości indeksu. W przypadku gdy wartość nie jest dopasowana do wyrażenia, indeks przyjmuje wartość "" (znak pusty). Dla parametru IndexNMultipleValue=true, dopasowywanie odbywa się do każdej wartości rozdzielonej średnikiem osobno.
• IndexNRegMask - określa maskę w celu przekształcenia wartości indeksu dopasowanego do wyrażenia regularnego IndexNRegExp.
• DestinationDirectory - ścieżka do katalogu, do którego będą zapisywane plik dopasowane do danej klasy dokumentów.
• FileName - nazwa plik jaka będzie nadawana dokumentom z tej klasy. W nazwie tej można zaszyć wartości indeksów poprzez dodanie wyrażenia $IndexN$, gdzie N jest numerem indeksu. Dodatkowo można dodać parametr $OrgFileName$, który podstawia do nazwy oryginalną nazwę pliku, w którym występuje klasa. W przypadku gdy przetwarzana jest paczka plików (ProcessFilesSeparetly=false) nazwa brana jest z pierwszego pliku. Istnieje równie możliwość dodania licznika plików w przypadku plików z tą samą nazwą. Odbywa się to przez dodanie wyrażenia $Num$. Na początku przypisywana jest wartość 1 i w przypadku gdy plik z taką nazwą już istnieje licznik jest zwiększany o jeden, aż do znalezienia nazwy, która nie występuje w katalogu. Brak tego wyrażenia może powodować, że pliki z tą samą nazwą będą nadpisywane.
• FileNameRegExp oraz FileNameRegMask - parametry opcjonalne, dzięki którym można dodatkowo przekształcić nazwę pliku według podanego wyrażenia regularnego (FileNameRegExp) oraz maski (FileNameRegMask).

Sekcja %ID%_Batch

W sekcji tej definiowany jest zakres występowania zestawu dokumentów, który może być wykorzystany do przypisania indeksów do klas, które nie zawierają w sobie danego kodu kreskowego (np. do zaindeksowania załącznika do faktury kodem występującym na powiązanej fakturze).

• Start - parametr określający początek występowania zestawu dokumentów. Zdefiniowany na podobnej zasadzie jak parametr start z %ID%_%CLASS%.
• Stop - parametr określający koniec występowania zestawu dokumentów. Zdefiniowany na podobnej zasadzie jak parametr stop z %ID%_%CLASS%.

Sekcja %ID%_RunAppAfterProcess

W sekcji tej definiowane są akcje, które mają być wykonane po przetworzeniu katalogu.

• Type - określa typ akcji. Możliwe wartości: Java - wywołanie metody z obiektu Javy; Shell - wywołanie polecenia systemowego.
• Class - parametr istotny w przypadku gdy Type=Java, zawierający nazwę klasy obiektu, której metoda ma być wywołana.
• Method - nazwa metody do wywołania w przypadku Type=Java. Metoda ta może przyjmować tylko jeden parametr, który jest typu String.
• Param - wartość parametru przekazywana do metody określonej w parametrze Method.
• Command - polecenie systemowe, które będzie wywołane w przypadku gdy Type=Shell.

Konfiguracja logów

Plik konfiguracyjny jest przy starcie programu wykorzystywany przy konfiguracji logów log4j. Konfiguracja taka powinna być umieszczona w sekcji [Logger] i powinna być zgodna ze standardem konfiguracji log4j. Przykładowa konfiguracja:

log4j.appender.PlusBarcodeReader = org.apache.log4j.DailyRollingFileAppender
log4j.appender.PlusBarcodeReader.Threshold = DEBUG
log4j.appender.PlusBarcodeReader.File = d:/Log/PlusBarcodeReader.log
log4j.appender.PlusBarcodeReader.DatePattern = '.'yyyyMMdd
log4j.appender.PlusBarcodeReader.layout = org.apache.log4j.PatternLayout
log4j.appender.PlusBarcodeReader.layout.ConversionPattern = %-12t%d{yy-MM-dd HH:mm:ss,SSS} %-5p%23C{1}:%-6L-%x- %m%n
log4j.logger.com.suncode.barcodereader=DEBUG,PlusBarcodeReader