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. 

...

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.

...

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.

...

• 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:

...