Overview of the EDIFACT Message Library

This topic provides an overview of the EDIFACT Message Library as well as its support for EDIFACT directory versions, SEF file versions, validation, and the UNA segment. It includes the following topics:

• About the EDIFACT Message Library

• References

• Character Encoding

• UN/EDIFACT Directory Support

• SEF File Support

• UN/EDIFACT Validation Support

• UNA Segment Support

• On Demand Parsing

• Errors and Exceptions

About the EDIFACT Message Library

The United Nations/Electronic Data Interchange (UN/EDIFACT) for Administration, Commerce and Transport protocol was developed for the electronic exchange of machine-readable information between businesses. The UN/EDIFACT Working Group (EWG) develops, maintains, interprets, and promotes the use of the UN/EDIFACT standard. UN/EDIFACT messages are structured according to very strict rules. Messages are in ASCII format. The standard defines all these message elements, their sequence, and also their grouping. UN/EDIFACT publishes the messages for each version separately from the envelopes (header and trailer segments) that are used with those messages.

The messages are available online at http://www.gefeg.com/en/standard/edifact/edifact.htm.

The envelopes are available online at http://www.gefeg.com/jswg/.

New versions of UN/EDIFACT messages are released several times a year, containing most of the messages in the previous version plus any new messages that have been approved by the standards organization. The envelopes are updated with a new version infrequently.

UN/EDIFACT messages have a specific message structure that indicates how data elements are organized and related to each other for a particular EDI transaction. In Java CAPS, the message structures are defined in an Object Type Definition (OTD), which consists of the following:

• Physical hierarchy: The predefined way in which envelopes, segments, and data elements are organized to describe a particular UN/EDIFACT EDI transaction.

• Delimiters: The specific predefined characters that are used to mark the beginning and end of envelopes, segments, and data elements.

• Properties: The characteristics of a data element, such as the length of each element, default values, and indicators that specify attributes of a data element—for example, whether it is required, optional, or repeating.

The message level structure of an invoice that is sent from one trading partner to another defines the header, trailer, segments, and data elements required by invoice transactions. The UN/EDIFACT OTD Library for a specific version includes message level structures for each of the transactions available in that version. You can use these structures as provided, or customize them to suit your business needs.

The Oracle Java CAPS Enterprise Service uses message libraries based on UN/EDIFACT message structures to verify that the data in the messages coming in or going out is in the correct format. There is a message structure for each UN/EDIFACT transaction and the list of transactions provided is different for each version of UN/EDIFACT.

References

The following resources provide additional information about the UN/EDIFACT protocol:

• The United Nations Economic Commission of Europe (UN/ECE) is one of the five regional commissions of the United Nations. The UN/ECE Web site contains technical information concerning rules, standards, recent UN/EDIFACT directories, syntax, and so on.

  http://www.unece.org/trade/untdid/welcome.htm

• UN/EDIFACT publishes the messages for each version separately from the envelopes (header and trailer segments) that are used with those messages.

  The messages are published at:

  http://www.gefeg.com/en/standard/edifact/edifact.htm

  The envelopes are published at:

  http://www.gefeg.com/jswg/

Character Encoding

The EDIFACT OTDs expect the input for unmarshalling to be a String/text when using the unmarshalFromString method, or to be a UTF-8 encoded byte array when using the unmarshalFromBytes method. If you use the File Adapter to read the content of a file as a byte array, make sure that the byte array is UTF-8 encoded by explicitly setting the encoding to UTF-8. For example, the following returns a UTF-8 encoded byte array for the File Adapter client named fileClient:

byte[] content = fileClient.getText().getBytes( "UTF-8" );

UN/EDIFACT Directory Support

The EDIFACT Message Library provides message structures for the following UN/EDIFACT directories, both syntax versions 3 and 4:

• D.03A

• D.01A and B

• D.00A and B

• D.99A and B

• D.98A and B

• D.97A and B

• D.96A and B

• D.95A and B

SEF File Support

The EDIFACT Message Library support SEF versions 1.5 and 1.6 when the SEF OTD wizard is used to build custom object type definitions (OTDs). The SEF OTD wizard does not handle the following information and sections:

• In the .SEMREFS section, semantic rules with its type of the “exit routine” are ignored as per SEF specification. An exit routine specifies an external routine (such as a COM-enabled server program supporting OLE automation) to run for translators or EDI data analyzers.

• The .TEXT sections (including subsections such as .TEXT,SETS, .TEXT,SEGS, .TEXT,COMS, .TEXT,ELMS, .TEXT,SEGS) are ignored due to the fact that these sections store information about changes in a standard’s text, such as notes, comments, names, purposes, descriptions, titles, semantic notes, explanations, and definitions.

UN/EDIFACT Validation Support

Within each EDIFACT OTD are Java methods and Java bean nodes for handling validation (see performValidation). The marshal and unmarshal methods of the envelope structures handle enveloping and de-enveloping (see marshal and unmarshal). No pre-built translations are supplied with the message libraries; these can be built in the Java Collaboration Editor.

EDIFACT OTDs have validations and translations, but a validation does not generate an acknowledgment transaction. Instead, it generates a string.

The output String of the validation (see check and checkAll) is in XML format conforming to the EDFOTDErrors.xsd file. Refer to Contents of the EDFOTDErrors.xsd File for more information. For a sample of the validation output XML, refer to Sample Validation Output XML.

UNA Segment Support

All UN/EDIFACT messages have a UNA segment (service string advice). It is used to send delimiter and indicator characters. The UNA segment is optional per the UN/EDIFACT specification. The string has a mandatory fixed length of 9 characters. The first three are “UNA,” immediately followed by the 6 characters as defined in ISO 9735. The UNA segment template is of fixed length with segment ID = UNA, followed by 6 one-byte fields. Each field specifies a separator or other service character. For more information, refer to Setting Delimiters and Indicators.

• If any delimiter values are set through UNA segment object, UNA segment data is included in the output message regardless of default or non-default delimiters are used.

• If non-default delimiters are used and no values are set through UNA segment object, UNA segment data is included in the output message.

• If default delimiters are used and no values are set through UNA segment object, UNA segment data is not included in the output message.

On Demand Parsing

For performance enhancement reasons, the unmarshal() method does not unmarshal the entire message. Instead, it does the following:

• Unmarshals the incoming message at the segment and composite level. In other words, the message library checks for all relevant segments and composites and reports any missing or extra segments or composites.

• Reports trailing delimiter for elements and composites.

This is also referred to as “parse on demand,” meaning that elements within a segment or composite are not unmarshaled until an element in that segment or composite is accessed in the Collaboration using a getxxx() method. The OTD may assign unmarshaled segments and composites to a pool that is ready to be freed from memory by the Java Virtual Machine (JVM). Once these segments or composites are freed from memory, they become unparsed. If the element within segment or composite is accessed again, the message library reparses the segment or composite.

By default, UN/EDIFACT message libraries set no limit of parsed segments or composites held in memory. You can specify a limit for parsed and freed segments or composite using the following methods at the message library root levels:

• setMaxParsedSegsComsNum method

• setMaxFreedSegsComsNum method

You can use these methods to set and control the runtime memory use of the unmarshaling process.

Errors and Exceptions

For all UN/EDIFACT message libraries, including the envelope libraries, if the incoming message cannot be parsed (for example, if the library cannot find the UNB segment), then the unmarshal() method generates a com.stc.otd.runtime.UnmarshalException.

You can also use the isUnmarshalComplete() method to learn whether unmarshal() ran without reporting any errors. Successful completion does not guarantee that the message library instance is free of unmarshal exceptions within segments, however, since elements are not unmarshaled until the first getElementXxxx() method of a segment is encountered (see On Demand Parsing). Encountering the unmarshal exception triggers an automatic background unmarshal of the entire segment. Note that the value returned by isUnmarshalComplete() is not influenced by the outcome of the automatic background unmarshal; instead, its value reflects what was set by the explicit invocation of the unmarshal() method.