From 7feca9dd4e7fb36c1cd12ea770940ab0d3a9936c Mon Sep 17 00:00:00 2001 From: Robin Stuart Date: Sun, 12 Apr 2015 20:57:08 +0100 Subject: [PATCH] Add symbol descriptions for JavaDoc --- .../okapibarcode/backend/AustraliaPost.java | 70 +++++++- .../org/okapibarcode/backend/AztecCode.java | 163 +++++++++++++++++- .../org/okapibarcode/backend/AztecRune.java | 3 + .../org/okapibarcode/backend/ChannelCode.java | 7 + .../uk/org/okapibarcode/backend/Codabar.java | 8 +- .../org/okapibarcode/backend/CodablockF.java | 7 +- .../uk/org/okapibarcode/backend/Code11.java | 3 + .../uk/org/okapibarcode/backend/Code128.java | 16 +- .../uk/org/okapibarcode/backend/Code16k.java | 5 +- .../uk/org/okapibarcode/backend/Code2Of5.java | 38 +++- .../uk/org/okapibarcode/backend/Code32.java | 6 +- .../uk/org/okapibarcode/backend/Code3Of9.java | 10 ++ .../backend/Code3Of9Extended.java | 9 + .../uk/org/okapibarcode/backend/Code49.java | 3 + .../uk/org/okapibarcode/backend/Code93.java | 2 + .../uk/org/okapibarcode/backend/CodeOne.java | 15 +- .../uk/org/okapibarcode/backend/Symbol.java | 54 +++++- 17 files changed, 403 insertions(+), 16 deletions(-) diff --git a/src/main/java/uk/org/okapibarcode/backend/AustraliaPost.java b/src/main/java/uk/org/okapibarcode/backend/AustraliaPost.java index d92dc311..1e8dabb6 100644 --- a/src/main/java/uk/org/okapibarcode/backend/AustraliaPost.java +++ b/src/main/java/uk/org/okapibarcode/backend/AustraliaPost.java @@ -20,7 +20,7 @@ /** * Implements the Australia Post 4-State barcode. - * + * * @author Robin Stuart */ public class AustraliaPost extends Symbol{ @@ -62,18 +62,86 @@ public AustraliaPost() { mode = ausMode.AUSPOST; } + /** + * Specify encoding of Australia Post Standard Customer Barcode, + * Customer Barcode 2 or Customer Barcode 3 (37-bar, 52-bar and 67-bar + * symbols) depending on input data length. Valid data characters are 0-9, + * A-Z, a-z, space and hash (#). A Format Control Code (FCC) is added and + * should not be included in the input data. + *

+ * Input data should include a 8-digit Deliver Point ID + * (DPID) optionally followed by customer information as shown below. + * + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Input Length

Required Input Format

Symbol Length

FCC

Encoding Table

8

99999999

37-bar

11

None

13

99999999AAAAA

52-bar

59

C

16

9999999999999999

52-bar

59

N

18

99999999AAAAAAAAAA

67-bar

62

C

23

99999999999999999999999

67-bar

62

N

+ */ public void setPostMode() { mode = ausMode.AUSPOST; } + /** + * Specify encoding of a Reply Paid version of the Australia Post + * 4-State Barcode (FCC 45) which requires an 8-digit DPID input. + */ public void setReplyMode() { mode = ausMode.AUSREPLY; } + /** + * Specify encoding of a Routing version of the Australia Post 4-State + * Barcode (FCC 87) which requires an 8-digit DPID input. + */ public void setRouteMode() { mode = ausMode.AUSROUTE; } + /** + * Specify encoding of a Redirection version of the Australia Post 4-State + * Barcode (FCC 92) which requires an 8-digit DPID input. + */ public void setRedirectMode() { mode = ausMode.AUSREDIRECT; } diff --git a/src/main/java/uk/org/okapibarcode/backend/AztecCode.java b/src/main/java/uk/org/okapibarcode/backend/AztecCode.java index 9f1cb02c..01805708 100644 --- a/src/main/java/uk/org/okapibarcode/backend/AztecCode.java +++ b/src/main/java/uk/org/okapibarcode/backend/AztecCode.java @@ -18,19 +18,180 @@ /** * Implements Aztec Code bar code symbology * According to ISO/IEC 24778:2008 - * + *

+ * Aztec Code can encode 8-bit ISO 8859-1 (Latin-1) data (except 0x00 Null + * characters) up to a maximum length of approximately 3800 numeric characters, + * 3000 alphabetic characters or 1900 bytes of data in a two-dimensional + * matrix symbol. + * * @author Robin Stuart */ public class AztecCode extends Symbol { private int preferredSize = 0; + /** + * Sets a preferred symbol size. This value may be ignored if + * data string is too large to fit in the specified symbol size. + * Values correspond to symbol sizes as shown in the following + * table: + * + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Input

Symbol Size

Input

Symbol Size

1

15 x 15*

19

79 x 79

2

19 x 19*

20

83 x 83

3

23 x 23*

21

87 x 87

4

27 x 27*

22

91 x 91

5

19 x 19

23

95 x 95

6

23 x 23

24

101 x 101

7

27 x 27

25

105 x 105

8

31 x 31

26

109 x 109

9

37 x 37

27

113 x 113

10

41 x 41

28

117 x 117

11

45 x 45

29

121 x 121

12

49 x 49

30

125 x 125

13

53 x 53

31

131 x 131

14

57 x 57

32

135 x 135

15

61 x 61

33

139 x 139

16

67 x 67

34

143 x 143

17

71 x 71

35

147 x 147

18

75 x 75

36

151 x 151

+ * @param size An integer in the range 1 - 36 + */ public void setPreferredSize(int size) { preferredSize = size; } private int preferredEccLevel = -1; + /** + * Sets the preferred minimum amount of symbol space dedicated to + * error correction. This value will be ignored if a symbol size has been + * set by setPreferredSize Valid options + * are: + * + + + + + + + + + + + + + + + + + + + + + + +

Mode

Error Correction Capacity

1

>10% + 3 codewords

2

>23% + 3 codewords

3

>36% + 3 codewords

4

>50% + 3 codewords

+ * @param eccLevel An integer in the range 1 - 4 + */ public void setPreferredEccLevel (int eccLevel) { preferredEccLevel = eccLevel; } diff --git a/src/main/java/uk/org/okapibarcode/backend/AztecRune.java b/src/main/java/uk/org/okapibarcode/backend/AztecRune.java index 6a18b05d..50351228 100644 --- a/src/main/java/uk/org/okapibarcode/backend/AztecRune.java +++ b/src/main/java/uk/org/okapibarcode/backend/AztecRune.java @@ -18,6 +18,9 @@ /** * Implements Aztec Runes bar code symbology * According to ISO/IEC 24778:2008 Annex A + *

+ * Aztec Runes is a fixed-size matrix symbology which can encode whole + * integer values between 0 and 255. * * @author Robin Stuart */ diff --git a/src/main/java/uk/org/okapibarcode/backend/ChannelCode.java b/src/main/java/uk/org/okapibarcode/backend/ChannelCode.java index 09426961..c1296f79 100644 --- a/src/main/java/uk/org/okapibarcode/backend/ChannelCode.java +++ b/src/main/java/uk/org/okapibarcode/backend/ChannelCode.java @@ -18,6 +18,8 @@ /** * Implements Channel Code * According to ANSI/AIM BC12-1998 + *

+ * Channel code encodes whole integer values between 0 and 7,742,862. * * @author Robin Stuart */ @@ -29,6 +31,11 @@ public class ChannelCode extends Symbol { private String horizontalSpacing; private int requestedNumberOfChannels = 0; + /** + * Set the number of channels used to encode data. This setting will be + * ignored if the value to be encoded requires more channels. + * @param channels Number of channels in range 3 - 8 + */ public void setNumberOfChannels(int channels) { if ((channels >= 3) && (channels <= 7)) { requestedNumberOfChannels = channels; diff --git a/src/main/java/uk/org/okapibarcode/backend/Codabar.java b/src/main/java/uk/org/okapibarcode/backend/Codabar.java index b7de8aa2..e59d9728 100644 --- a/src/main/java/uk/org/okapibarcode/backend/Codabar.java +++ b/src/main/java/uk/org/okapibarcode/backend/Codabar.java @@ -17,8 +17,14 @@ /** - * Implements Codabar + * Implements Codabar barcode symbology * According to BS EN 798:1996 + *

+ * Also known as NW-7, Monarch, ABC Codabar, USD-4, Ames Code and Code 27. + * Codabar can encode any length string starting and ending with the letters + * A-D and containing between these letters the numbers 0-9, dash (-), dollar + * ($), colon (:), slash (/), full stop (.) or plus (+). No check digit is + * generated. * * @author Robert Elliott */ diff --git a/src/main/java/uk/org/okapibarcode/backend/CodablockF.java b/src/main/java/uk/org/okapibarcode/backend/CodablockF.java index 6239983b..d2e4b126 100644 --- a/src/main/java/uk/org/okapibarcode/backend/CodablockF.java +++ b/src/main/java/uk/org/okapibarcode/backend/CodablockF.java @@ -19,7 +19,12 @@ import java.io.UnsupportedEncodingException; /** - * Implements Codablock-F + * Implements Codablock-F according to AIM Europe "Uniform Symbology + * Specification - Codablock F", 1995 + *

+ * Codablock F is a multi-row symbology using Code 128 encoding. It can + * encode any 8-bit ISO 8859-1 (Latin-1) data up to approximately 1000 + * alpha-numeric characters or 2000 numeric digits in length. * * @author Robin Stuart */ diff --git a/src/main/java/uk/org/okapibarcode/backend/Code11.java b/src/main/java/uk/org/okapibarcode/backend/Code11.java index e5bc23e2..cf27c026 100644 --- a/src/main/java/uk/org/okapibarcode/backend/Code11.java +++ b/src/main/java/uk/org/okapibarcode/backend/Code11.java @@ -18,6 +18,9 @@ /** * Implements Code 11 bar code symbology. + *

+ * Code 11 can encode any length string consisting of the digits 0-9 and the + * dash character (-). One modulo-11 check digit is calculated. * * @author Robin Stuart */ diff --git a/src/main/java/uk/org/okapibarcode/backend/Code128.java b/src/main/java/uk/org/okapibarcode/backend/Code128.java index 09cd9040..bbe2b6dd 100644 --- a/src/main/java/uk/org/okapibarcode/backend/Code128.java +++ b/src/main/java/uk/org/okapibarcode/backend/Code128.java @@ -20,6 +20,9 @@ /** * Implements Code 128 bar code symbology * According to ISO/IEC 15417:2007 + *

+ * Code 128 supports encoding of 8-bit ISO 8859-1 (Latin-1) characters. + * Setting GS1 mode allows encoding in GS1-128 (also known as UPC/EAN-128). * * @author Robin Stuart */ @@ -63,23 +66,30 @@ public Code128() { compositeMode = Composite.OFF; } + /** + * Allow the use of subset C (numeric compression) in encoding (default). + */ public void useModeC() { modeCSupression = false; } + /** + * Disallow the use of subset C (numeric compression) in encoding. + * Numeric values will be encoded using subset B. + */ public void stopModeC() { modeCSupression = true; } - public void setCca() { + protected void setCca() { compositeMode = Composite.CCA; } - public void setCcb() { + protected void setCcb() { compositeMode = Composite.CCB; } - public void setCcc() { + protected void setCcc() { compositeMode = Composite.CCC; } diff --git a/src/main/java/uk/org/okapibarcode/backend/Code16k.java b/src/main/java/uk/org/okapibarcode/backend/Code16k.java index 44036f47..53e8b5ef 100644 --- a/src/main/java/uk/org/okapibarcode/backend/Code16k.java +++ b/src/main/java/uk/org/okapibarcode/backend/Code16k.java @@ -21,7 +21,10 @@ /** * Implements Code 16K symbology * According to BS EN 12323:2005 - * + *

+ * Encodes using a stacked symbology based on Code 128. Supports encoding + * of any 8-bit ISO 8859-1 (Latin-1) data with a maximum data capacity of 77 + * alpha-numeric characters or 154 numerical digits. * @author Robin Stuart */ public class Code16k extends Symbol { diff --git a/src/main/java/uk/org/okapibarcode/backend/Code2Of5.java b/src/main/java/uk/org/okapibarcode/backend/Code2Of5.java index 690364f7..c080e891 100644 --- a/src/main/java/uk/org/okapibarcode/backend/Code2Of5.java +++ b/src/main/java/uk/org/okapibarcode/backend/Code2Of5.java @@ -18,7 +18,8 @@ import java.awt.Rectangle; /** - * + * Implements the Code 2 of 5 family of barcode standards. + * * @author Robert Elliott */ public class Code2Of5 extends Symbol { @@ -42,34 +43,69 @@ public Code2Of5() { mode = tof_mode.MATRIX; } + /** + * Select Standard Code 2 of 5 mode, also known as Code 2 of 5 Matrix. (default) + * Encodes any length numeric input (digits 0-9). + */ public void setMatrixMode() { mode = tof_mode.MATRIX; } + /** + * Select Industrial Code 2 of 5 which can encode any length numeric input + * (digits 0-9) and does not include a check digit. + */ public void setIndustrialMode() { mode = tof_mode.INDUSTRIAL; } + /** + * Select International Air Transport Agency variation of Code 2 of 5. + * Encodes any length numeric input (digits 0-9) and does not include + * a check digit. + */ public void setIATAMode() { mode = tof_mode.IATA; } + /** + * Select Code 2 of 5 Data Logic. Encodes any length numeric input + * (digits 0-9) and does not include a check digit. + */ public void setDataLogicMode() { mode = tof_mode.DATA_LOGIC; } + /** + * Select Interleaved Code 2 of 5. encodes pairs of numbers, and so can + * only encode an even number of digits (0-9). If an odd number of digits + * is entered a leading zero is added. No check digit is calculated. + */ public void setInterleavedMode() { mode = tof_mode.INTERLEAVED; } + /** + * Select ITF-14, also known as UPC Shipping Container Symbol or Case Code. + * Requires a 13 digit numeric input (digits 0-9). One modulo-10 check + * digit is calculated. + */ public void setITF14Mode() { mode = tof_mode.ITF14; } + /** + * Select Deutsche Post Leitcode. Requires a 13-digit numerical input. + * Check digit is calculated. + */ public void setDPLeitMode() { mode = tof_mode.DPLEIT; } + /** + * Select Deutsche Post Identcode. Requires an 11-digit numerical input. + * Check digit is calculated. + */ public void setDPIdentMode() { mode = tof_mode.DPIDENT; } diff --git a/src/main/java/uk/org/okapibarcode/backend/Code32.java b/src/main/java/uk/org/okapibarcode/backend/Code32.java index 37fd9d5f..2effc6da 100644 --- a/src/main/java/uk/org/okapibarcode/backend/Code32.java +++ b/src/main/java/uk/org/okapibarcode/backend/Code32.java @@ -16,7 +16,11 @@ package uk.org.okapibarcode.backend; /** - * Implements Code 32 (AKA Italian Pharmacode) + * Implements Code 32, also known as Italian Pharmacode, A variation of Code + * 39 used by the Italian Ministry of Health ("Ministero della Sanità") + *

+ * Requires a numeric input up to 8 digits in length. Check digit is + * calculated. * * @author Robin Stuart */ diff --git a/src/main/java/uk/org/okapibarcode/backend/Code3Of9.java b/src/main/java/uk/org/okapibarcode/backend/Code3Of9.java index f459ba96..5c738346 100644 --- a/src/main/java/uk/org/okapibarcode/backend/Code3Of9.java +++ b/src/main/java/uk/org/okapibarcode/backend/Code3Of9.java @@ -18,6 +18,11 @@ /** * Implements Code 39 bar code symbology * According to ISO/IEC 16388:2007 + *

+ * Input data can be of any length and supports the characters 0-9, AZ, dash + * (-), full stop (.), space, asterisk (*), dollar ($), slash (/), plus (+) + * and percent (%). The standard does not require a check digit but a + * modulo-43 check digit can be added if required. * * @author Robin Stuart */ @@ -33,6 +38,11 @@ public Code3Of9() { checkOption = CheckDigit.NONE; } + /** + * Select addition of optional Modulo-43 check digit or encoding without + * check digit. + * @param checkMode Check digit option. + */ public void setCheckDigit(CheckDigit checkMode) { checkOption = checkMode; } diff --git a/src/main/java/uk/org/okapibarcode/backend/Code3Of9Extended.java b/src/main/java/uk/org/okapibarcode/backend/Code3Of9Extended.java index 8fe0eb17..67f984a9 100644 --- a/src/main/java/uk/org/okapibarcode/backend/Code3Of9Extended.java +++ b/src/main/java/uk/org/okapibarcode/backend/Code3Of9Extended.java @@ -16,6 +16,10 @@ package uk.org.okapibarcode.backend; /** + * Implements Code 3 of 9 Extended, also known as Code 39e and Code39+ + *

+ * Supports encoding of all characters in the 7-bit ASCII table. A + * modulo-43 check digit can be added if required. * * @author Robin Stuart */ @@ -45,6 +49,11 @@ public Code3Of9Extended() { checkOption = CheckDigit.NONE; } + /** + * Select addition of optional Modulo-43 check digit or encoding without + * check digit. + * @param checkMode Check digit option + */ public void setCheckDigit(CheckDigit checkMode) { checkOption = checkMode; } diff --git a/src/main/java/uk/org/okapibarcode/backend/Code49.java b/src/main/java/uk/org/okapibarcode/backend/Code49.java index 2d9ae222..174b444a 100644 --- a/src/main/java/uk/org/okapibarcode/backend/Code49.java +++ b/src/main/java/uk/org/okapibarcode/backend/Code49.java @@ -20,6 +20,9 @@ /** * Implements Code 49 * According to ANSI/AIM-BC6-2000 + *

+ * Encoding supports full 7-bit ASCII input up to a maximum of 49 characters + * or 81 numeric digits. GS1 data encoding is also supported. * * @author Robin Stuart */ diff --git a/src/main/java/uk/org/okapibarcode/backend/Code93.java b/src/main/java/uk/org/okapibarcode/backend/Code93.java index 227815c7..8aeb7eaa 100644 --- a/src/main/java/uk/org/okapibarcode/backend/Code93.java +++ b/src/main/java/uk/org/okapibarcode/backend/Code93.java @@ -18,6 +18,8 @@ /** * Implements Code 93. + *

+ * Supports encoding of 7-bit ASCII text. Two check digits are added. * * @author Robin Stuart * @author Daniel Gredler diff --git a/src/main/java/uk/org/okapibarcode/backend/CodeOne.java b/src/main/java/uk/org/okapibarcode/backend/CodeOne.java index 64079f62..2c80e8e6 100644 --- a/src/main/java/uk/org/okapibarcode/backend/CodeOne.java +++ b/src/main/java/uk/org/okapibarcode/backend/CodeOne.java @@ -18,7 +18,14 @@ import java.io.UnsupportedEncodingException; import java.math.BigInteger; /** - * Implements Code 1 + * Implements Code One + *

+ * Code One is able to encode the ISO 8859-1 (Latin-1) character set or GS1 + * data. There are two types of Code One symbol - variable height symbols + * which are roughly square (versions A thought to H) and fixed-height + * versions (version S and T). Version S symbols can only encode numeric data. + * The width of version S and version T symbols is determined by the length + * of the input data. * * @author Robin Stuart */ @@ -103,6 +110,12 @@ public enum Version { private Version preferredVersion = Version.NONE; + /** + * Set symbol size by "version". Versions A to H are square symbols. + * This value may be ignored if the input data does not fit in the + * specified version. Version S and T are fixed height symbols. + * @param version + */ public void setPreferredVersion (Version version) { preferredVersion = version; } diff --git a/src/main/java/uk/org/okapibarcode/backend/Symbol.java b/src/main/java/uk/org/okapibarcode/backend/Symbol.java index d99c0922..5a4d3415 100644 --- a/src/main/java/uk/org/okapibarcode/backend/Symbol.java +++ b/src/main/java/uk/org/okapibarcode/backend/Symbol.java @@ -59,28 +59,66 @@ public Symbol() { unsetReaderInit(); } + /** + * Sets the type of input data. This setting influences what + * pre-processing is done on data before encoding in the symbol. + * For example: for GS1 mode the AI data will be used to + * calculate the position of 'FNC1' characters. + * Valid values are: + *

+ * @param dataType A DataType value which specifies the type of data + */ public void setDataType(DataType dataType) { inputDataType = dataType; } + /** + * Prefixes symbol data with a "Reader Initialisation" or "Reader + * Programming" instruction. + */ public final void setReaderInit() { readerInit = true; } + /** + * Removes "Reader Initialisation" or "Reader Programming" instruction + * from symbol data. + */ public final void unsetReaderInit() { readerInit = false; } + /** + * Gets the width of the encoded symbol as a multiple of the + * x-dimension. + * @return an integer specifying the width of the symbol + */ public int getWidth() { return symbol_width; } + /** + * Gets a human readable summary of the decisions made by the encoder + * when creating a symbol. + * @return a String containing encoding information + */ public String getEncodeInfo() { return encodeInfo; } // TODO: surely we'll need something better than this to account for the height // of the human readable aspect of different bar codes + /** + * Gets the height of the encoded symbol as a multiple of the + * x-dimension. + * @return an integer specifying the height of the symbol + */ public int getHeight() { if (txt.isEmpty()) { return symbol_height; @@ -89,7 +127,7 @@ public int getHeight() { } } - public int positionOf(char thischar, char[] LookUp) { + protected int positionOf(char thischar, char[] LookUp) { int i, outval = 0; for (i = 0; i < LookUp.length; i++) { @@ -100,7 +138,7 @@ public int positionOf(char thischar, char[] LookUp) { return outval; } - public String bin2pat(String bin) { + protected String bin2pat(String bin) { boolean black; int i, l; String pat = ""; @@ -131,6 +169,12 @@ public String bin2pat(String bin) { return pat; } + /** + * Set the data to be encoded. Input data will be assumed to be of + * the type set by setDataType. + * @param input_data A String containing the data to encode + * @throws OkapiException If no data or data is invalid + */ public void setContent(String input_data) { int i; @@ -169,7 +213,7 @@ public void setContent(String input_data) { abstract boolean encode(); - public void plotSymbol() { + protected void plotSymbol() { int xBlock, yBlock; int x, y, w, h; boolean black; @@ -215,7 +259,7 @@ public void plotSymbol() { } } - public String gs1SanityCheck(String source) { + protected String gs1SanityCheck(String source) { // Enforce compliance with GS1 General Specification // http://www.gs1.org/docs/gsmp/barcodes/GS1_General_Specifications.pdf @@ -484,7 +528,7 @@ public String gs1SanityCheck(String source) { return reduced; } - public String hibcProcess(String source) { + protected String hibcProcess(String source) { char[] hibcCharTable = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J',