Java Unified API
Requirements
Please see the readme.txt
file that accompanies Instream for Instream requirements information.
Persons with knowledge of Java and Instream can also help.
Running the Java Demo
-
Go to Instream’s API\AllProductsAPISampleJava or API\JavaSample directory and compile the
.java
files by runningBuild.bat
orBuild.sh.
These two files are present:JavaApIDemo.class
yourMsgClass.class
-
Run the demonstration by running
RunJavaSample.bat
orRunJavaSample.sh
. This file contains several examples. -
Go to the Output directory of Instream to see the files created:
Paths and Environment Variables
Path include the Bin directory of Instream in your path.
classpath include the Instream Java directory.
-classpath "%InStreamRoot%\Java\instreamapi.jar."
To set up the environment variable classpath, see this example in RunJavaSample.bat
:
java -classpath ".;%InStreamRoot%\Java\instreamapi.jar" JavaApIDemo
Within the quotation marks, the location of JavaAPIDemo.class is identified as “.” – in other words, the current directory from which the batch file is being run.
The separator (;) is followed by the path and filename of the TIBCO Foresight jar file.
It then gives the name of the class file being run.
Environment Variable - If you are using an Instream API, use the FS_INSTREAMUIDDIR environment variable to point to a directory where you have write permission.
Files
Instream’s API\AllProductsAPISampleJava or API\JavaSample directory |
|
|
Source code that you can edit and then compile into a |
|
Batch file that compiles |
|
Batch file that sets up and executes |
|
Example of how to read a detailed and summary record from memory and then notify Instream that validation should continue. |
Instream’s Java directory |
|
|
TIBCO Foresight jar file for the unified Java API. |
Instream’s Java\docs\com\foresight\jInStreamAPI directory |
|
|
Additional documentation for jNHVInStream class. |
The other directories under the API directory of Instream are for the C++, C#, and VB APIs.
If you plan to change the sample code, copy the project to a different directory. Sample files are reinstalled with each release.
Class jNHVInStream
Import the TIBCO Foresight Java interface at the beginning of your program, like this:
import com.foresight.jinstreamapi.*;
Call or Member | Description | ||||||
---|---|---|---|---|---|---|---|
avoidENV |
For “document-only” validation - when the data does not have ISA or GS enveloping, or when the enveloping is to be ignored. Lists the segment, element, and composite separators. It must appear BEFORE avoidENV. Separators can be in any of these formats: Integer example: 29,30,31 hexadecimal example: 0x1E,0x1F,0x1D character example: ~!* avoidENV=”NONE” |
||||||
Example:
|
|||||||
DocumentType |
Specifies that the data is XML. Otherwise, a value of “X12” is assumed – which includes all types of EDI that can be validated by Instream. (XML is Windows only) |
||||||
Example:
|
|||||||
DS_EdiOutputOpt |
Specifies that the Docsplitter valid and invalid files are to be output to memory. The only setting is: OUTPUTBYMEMORY OUTPUTBYFILE |
||||||
Example:
|
|||||||
DS_Options |
Docsplitter options controlling contents of the report, or disabling the report; one of these: DS_ReportValidOnly DS_ReportInvalidOnly DS_ReportBoth DS_ReportDisable DS_ReportInvalidFile Gives the path and filename of the Docsplitter invalid EDI file. DS_ReportValidFile Gives the path and filename of the Docsplitter valid EDI file. |
||||||
Example:
|
|||||||
DS_profile | Path and filename to a Docsplitter INI file. | ||||||
Example:
|
|||||||
DS_ReportDebugOpt |
TIBCO Foresight internal use only 0 turns off debug Docsplitter messages 1 turns on debug Docsplitter messages |
||||||
Example:
|
|||||||
DS_ReportFile |
(file output only) Gives the path and filename of the Docsplitter report. It will contain XML if the filename ends with |
||||||
Example:
|
|||||||
DS_reportdebug | Set to y or n to turn Docsplitter debug messages on or off. | ||||||
DS_TradingPartnerAutomation |
Path and filename of a trading partner automation setup (.csv) file that will select a Docsplitter INI file (see TIB_fsp-instream_<n.n>_tpa.pdf). If the Docsplitter INI file contains content splitting information, you will also need to call Doc_getNextInValidDocument() or Doc_getNextValidDocument()) to get all Docsplitter output files. See example 10 in JavaApIDemo.java. |
||||||
Example:
|
|||||||
updatemessage |
This contains information about each split created during content-based Docsplitting:
|
||||||
Example: Assume that Docsplitter split input data into three parts: ISA-IEA - valid ISA-IEA - valid ISA-IEA - invalid You will get three UpdateMessages: 1, data in first ISA-IEA, 1(the last value shows this is the 1st valid split) 1, data in second ISA-IEA, 2 (the last value shows this is the 2nd valid split) 2, data in third ISA-IEA, 1(the last value shows this is the 1st invalid split) |
|||||||
Doc_getNextInValidDocument() Doc_getNextValidDocument()) | Gets all valid and invalid files created by content-based splitting. | ||||||
Example:
|
|||||||
DS_InValidEdiOutputStr | (memory output only) Memory buffer for the Docsplitter invalid EDI output. | ||||||
Example:
|
|||||||
DS_ReportFormat |
(Required for memory output; not used for file output) Specifies the format of the Docsplitter report, one of these: XMLFormat (default) DelimitedFormat XMLGenericFormat The XML format slows performance more than the CSV format. |
||||||
Example:
|
|||||||
DS_ReportOutputOpt |
Required for Docsplitter Specifies that the Docsplitter report is to be output to memory or file. Settings can be: OUTPUTBYFILE OUTPUTBYMEMORY |
||||||
Example:
|
|||||||
DS_ReportOutputStr |
(memory output only) Memory buffer for the Docsplitter report. |
||||||
Example:
|
|||||||
DX_EDIInputSourceOption |
Sets Dataswapper EDI input to memory or file; used when Docsplitter is being used in the mode that calls Instream. Currently, Dataswapper can output to file, but not to memory. It can input from memory if it calls Instream, but not if it accepts validation detail results as input. This can be set to: INPUTBYMEMORY INPUTBYFILE |
||||||
Example:
|
|||||||
DX_EDIOutputFile | Points to Dataswapper’s EDI output file. | ||||||
Example:
|
|||||||
DX_EDIOutputOption |
Sets Dataswapper’s EDI output option. This can be set to: OUTPUTBYMEMORY |
||||||
Example:
|
|||||||
getDX_output | Requests Dataswapper’s EDI output be returned in memory. | ||||||
Example:
|
|||||||
getDXReport | Requests Dataswapper’s report output be returned in memory. | ||||||
Example:
|
|||||||
DX_Profile | Points to Dataswapper’s setup file. | ||||||
Example:
|
|||||||
DX_ReportFile | Points to Dataswapper’s report output file. | ||||||
Example:
|
|||||||
flag |
Describes whether the input and output is by memory or file. Set this flag before you call fshvi(). INPUTBYFILE - The inputFile parameter contains a file name. OUTPUTBYFILE - The outputFile parameter contains a file name. INPUTBYMEMORY – (Instream validation only) the input EDI data is located in memory. The inputMemBuf parameter must also be set to point to the input buffer as described below. OUTPUTBYMEMORY - (Instream validation only) The detail and summary output are to go to memory. In addition to setting this option, the routines updatedataDetail and updatedataSummary must be overridden to perform the actual update to memory. |
||||||
Example:
One input and one output flag may be combined via an "or", as in:
|
|||||||
RG_TradingPartnerAutomation |
Path and filename of a trading partner automation setup (.csv) file that will select a Docsplitter INI file (see TIB_fsp-instream_<n.n>_tpa.pdf). If the Docsplitter INI file contains content splitting information, you will also need to call Doc_getNextInValidDocument() or Doc_getNextValidDocument()) to get all Docsplitter output files. See example 12 in JavaApIDemo.java |
||||||
Example:
|
|||||||
FSDOCUMENTONLY |
This says that the EDI has no enveloping, or its enveloping should be ignored. It will be processed with the ISA and GS definitions specified in: envlopISA envGS FSDOCUMENTONLY, envlopISA, and envGS must all be present if you want the enveloping to be processed this way. Another method for document-only processing is to use avoidENV and separator (see page Java Unified API). |
||||||
|
|||||||
FSINSTREAMINI |
By default, the Instream Java API will read MAINDIR from registry ([HKEY_LOCAL_MACHINE, "SOFTWARE\\Foresight\\Instream"]) as Instream’s root directory. It then reads But, you also can use the environment variable "FSINSTREAMINI" to overwrite the root directory. Ensure FSINSTREAMINI points to the folder where the (Windows only) |
||||||
Example:
|
|||||||
fsInStream | Java native interface that calls jHVInStream.dll. |
||||||
Example:
|
|||||||
fshvi |
The procedure that actually runs validation, Docsplitter, Response Generator and/or Docsplitter, based on the settings in HVINSTREAM_PROCEDURE (below). Return codes are listed in the user manual for each program (e.g. TIBCO Foresight® Instream® Response Generator etc.). If a code is returned indicating an error, the function getErrorMessage can be used to get a detailed description of the error. |
||||||
Example:
|
|||||||
fs997Report fs999Report fs824Report fs277ReportfsContrlReport (EDIFACT only) fsTA1Report fsTextReport |
(memory output only) If set to true, these create the specific types of Response Generator output in memory. The names of the Response Generator memory buffers are set with OutputBufxxx (see page Java Unified API). |
||||||
Example:
Since fs824Report is set to true, this example creates 824 output in memory. It does not create TA1 output. |
|||||||
FSUSINGFSERVER | TIBCO Foresight internal use only. | ||||||
getVersion | Returns the version of Instream being used. Example: 9.2.0 | ||||||
Example:
|
|||||||
InStream_partnerautomation |
Sets the TPA path for validation. See example 12 in JavaApIDemo.java. If TPA fails due to a missing GS01 or GS08, Instream creates a TA1 file. If an output file name was specified, the TA1 file is named accordingly (e.g., filename.txt.TA1). If memory output is specified, use the OutputBufTA1 call to access the information. |
||||||
Example:
|
|||||||
HVINSTREAM_PROCEDURE |
Specifies whether fshvi will run Instream validation, Docsplitter, Response Generator and/or Dataswapper INSTREAM_ONLY Run Instream validation only INSTREAM_SPLITTER Run Instream validation and then Docsplitter SPLITTER_ONLY Run Docsplitter only INSTREAM_RESPGEN Run Instream validation and then Response Generator RESPGEN_ONLY Run Response Generator only DATASUBSTITUTE_ONLY Run Dataswapper only INSTREAM_ DATASUBSTITUTE Run Instream validation and then Dataswapper FSHV_ALL Run Instream validation, Docsplitter, Response Generator and Dataswapper void_init Reset all variables to the default settings. StopValidationWhenENVHasError Specifies if processing should continue (set to false) or stop (set to true) if an ENV (ISA/GS UNB/UNG) error is encountered. The error is reported in the DTL output in either case. |
||||||
Example:
or
|
|||||||
getErrorMessage | Returns the text of the last error encountered by Instream validation. | ||||||
Example:
|
|||||||
getETYPE_type |
Returns count of errors of a particular type: TypeZeroCount SyntaxCount TypeTwoCount SituationCount CodeSetCount ProductCount PayerCount PartnerCount |
||||||
Example:
|
|||||||
getSVRTY_severity |
(File-based output only) Returns count of errors of a particular severity: IgnoreCount InfoCount WarningCount ErrorCount FatalCount User1Count User2Count |
||||||
Example:
|
|||||||
guideline |
Gives the name of the guideline to be used for validation or input into another program such as Docsplitter. If omitted, Instream uses the first guideline encountered that matches the data’s Version/Release Identifier code (Segment GS Element 08). If you are using Docsplitter, be sure it is a GuidelinePlus or is based on a GuidelinePlus (one that starts with PD). |
||||||
Example:
|
|||||||
GuidelineBuffer |
Used to pass a guideline directly in memory. GuidelineBuffer is an input parameter pointing to a memory buffer (byte[] array) where the guideline can be found. This member can also be used to set up or change the guideline in the UpdateAnalysis routine as described in Automatically Choosing a Guideline and APF |
||||||
Example:
|
|||||||
inputFile |
When using INPUTBYFILE, this gives the full path and name of the EDI data file that will be validated. When using INPUTBYMEMORY, this gives a name or title for the data to be output in the Start Message. |
||||||
Example:
|
|||||||
inputMemBuf | Input parameter pointing to memory buffer where input EDI data is to be found. This parameter is required when INPUTBYMEMORY is specified in the flag parameter, and ignored otherwise. | ||||||
Example:
|
|||||||
inputMemBufbyteArray | Input parameter pointing to a byte[] array memory buffer where input EDI data is to be found. Either this parameter or the inputMemBuf parameter is required when INPUTBYMEMORY is specified in the 'flag' parameter, and ignored otherwise. | ||||||
Example:
|
|||||||
InStreamOutputXmlFormat |
Set to “true” if you want an XML-format validation report. Set to “false” if you want a delimited format validation report. |
||||||
origFileInfo | Specifies the month, day, year, hour, minute, second, size, and path of the original EDI file. | ||||||
Example:
|
|||||||
OutputBuf997 OutputBuf999 OutputBuf277 OutputBuf824 OutputBufTA1 OutputBufCus Get997Report Get999Report GetContrlReport (EDIFACT only) |
(Response Generator memory output only) These are the buffer names for the Response Generator output. |
||||||
Example:
|
|||||||
OutputXmlFormat | TIBCO Foresight Internal use only | ||||||
profileOptions |
Gives the name of the validation profile file. Defaults to |
||||||
Example:
|
|||||||
PROFILEUPDATED | TIBCO Foresight internal use only | ||||||
respGenOutputFlag |
Specifies that Response Generator output goes to memory or to a file: OUTPUTBYMEMORY OUTPUTBYFILE |
||||||
Example:
|
|||||||
RG_Contrl | Directs RG_Contrl output to memory or to a file. | ||||||
File output :
Memory Output :
|
|||||||
RG_Options | Response Generator options, which can include any options mentioned in TIBCO Foresight® Instream® Response Generator, except -TPA. | ||||||
Example:
This example specifies that group enveloping is to be included in the response documents and that Response Generator can overwrite files if they already exist. Note: When specifying Response Generator options via the API, leave no space between the option and its value. For example, use -er3 instead of -er 3. Spaces may cause the API response generator call to fail.
|
|||||||
RG_Rep277 RG_Rep824 RG_Rep997 RG_Rep999 RG_TA1 |
Gives the name of the EDI file(s) to be created by Response Generator. | ||||||
Example:
|
|||||||
RG_repText RG_Reptemp |
RG_repText gives the name of a custom text report to be created by Response Generator. RG_Reptemp gives the name of the template that controls the format of the custom text report. If you use one of these, use both. |
||||||
Example:
|
|||||||
separator |
For “document-only” validation - when the data does not have ISA or GS enveloping, or when the enveloping is to be ignored. Lists the segment, element, and composite separators. It must appear BEFORE avoidENV. Separators can be in any of these formats: Integer example: 29,30,31 hexadecimal example: 0x1E,0x1F,0x1D character example: ~!* avoidENV=”NONE” TIBCO Foresight internal use only This specifies that validation is to ignore ISA and GS enveloping and use the separators provided with separator. Another method for document-only processing is to use FSDOCUMENTONLY (see page Java Unified API). |
||||||
Example:
|
|||||||
updatedataDetail |
This procedure writes detailed validation output to memory when the OUTPUTBYMEMORY flag is set. This is done one record at a time. You must override this routine to perform the actual output as desired. The default version of this routine just sends the detailed message to standard output. You can then have your application evaluate the record and either terminate validation or continue validation. If you want to terminate validation, return the constant STOPHVINSTREAM (or 500). If you want to continue validation, return the constant CONTHVINSTREAM (or 510). |
||||||
Example: public int updatedataDetail(String detail){
|
|||||||
updatedataSummary |
This procedure writes summary validation output to memory when the OUTPUTBYMEMORY flag is set. This is done each time a transaction set ends in the detail output. You must override this routine to perform the actual output as desired. The default version of this routine just sends the detail message to standard output. You can then have your application evaluate the output and either terminate validation or continue validation. If you want to terminate validation, return the constant STOPHVINSTREAM (or 500). If you want to continue validation, return the constant CONTHVINSTREAM (or 510). |
||||||
Example:
|
|||||||
updateMessage |
This procedure is responsible for writing Document Splitter and Data Exchange values output to memory. Where type = <n> 1 - Memory output, value1 = DocSplitter Valid document, value2 = Content name for Content-Based splitting. 2 - Memory output, value1 = DocSplitter InValid document, value2=Content name for Content-Based splitting. 3 - Memory output, value1 = DocSplitter Report, value2 = Not used. 4 - Memory output, value1 = Data exchange output, value2 = Not used. 5 - Memory output, value1 = Data exchange Report, value2 = Not used. 6 - File output, value1 = Content-Based splitting valid document name, value2 = Not used. 7 - File output, value1 = Content-Based splitting invalid document name, value2 = Not used. |
||||||
Example:
|
|||||||
userMessage |
Inserts your free-form text in a validation detail file GEN record with number 15078. Example GEN record (assume your text was "Sock 2"):
This is for your own use. TIBCO Foresight® Transaction Insight® can display it. |
||||||
UseUpdateAnalysis |
This lets the calling program pick the guideline and validation profile. You will need to do two things to set this up:
|
||||||
Example:
|
Automatically Choosing a Guideline and APF
This feature lets you choose a guideline, and optionally a profile, based on the contents of the data.
UseUpdateAnalysis
For an example, please see yourMsgClass.java in TIBCO Foresight’s API\AllProductsAPISampleJava directory.
X12 - values in ISA or GS
To make the guideline and profile decision for X12 data, based on values in the ISA or GS:
-
Do not specify a guideline.
-
Set the UseUpdateAnalysis flag to true.
-
At each GS, the calling program will receive UpdateAnalysis with the <interchange> and <FunctionalGroup> data shown below.
The <Version> tag will contain the X12 version.
-
The calling program sends back this.guideline and this.profileOptions variables:
this.guideline = "B41A837I"; retVal |= this.STANDARDUPDATED; /*** Set apf file to use *****/ this.profileOptions = "XXXX.apf"; retVal |= this.PROFILEUPDATED;
Note: It is also possible to use the GuidelineBuffer parameter to pass a pointer to a byte array containing a guideline in memory instead of passing a guideline filename in the guideline parameter. In this case, set the .STANDARDUPDATEDINMEMORY flag instead of the .STANDARDUPDATED flag.
Flat File, XML and X12 transaction set data
To make the guideline and profile decision for XML or flat file data, or for X12 data in the transaction set rather than in the enveloping:
-
Use guideline to specify a content-based guideline (see TIB_fsp-instream_<n.n>_tpa.pdf). This will contain an IdentifierLookup business rule and a DSR mark to show locations where a guideline or profile switch may occur.
-
Set the UseUpdateAnalysis flag to true.
-
During validation, at each DSR location, the calling program will receive UpdateAnalysis containing the <Variables> element information shown below. The <Interchange> and <FunctionalGroup> elements will be empty.
The <Version> tag will contain Flat or XML .
-
The calling program sends back this.guideline and this.profileOptions variables:
this.guideline = "B41A837I"; retVal |= this.STANDARDUPDATED; this.profileOptions = "XXXX.apf"; retVal |= this.PROFILEUPDATED;
Note: It is also possible to use the GuidelineBuffer parameter to pass a pointer to a byte array containing a guideline in memory instead of passing a guideline filename in the guideline parameter. In this case, set the .STANDARDUPDATEDINMEMORY flag instead of the .STANDARDUPDATED flag.
Example XML sent to calling program by UpdateAnalysis
<?xml version="1.0" encoding="UTF-8"?> <Info> <Interchange> <SenderQualifier>01</SenderQualifier> <Sender>9012345720000</Sender> <ReceiverQualifier>01</ReceiverQualifier> <Receiver>9088877320000</Receiver> <Date>020111</Date> <Time>1212</Time> <CtlNo>000000001</CtlNo> </Interchange> <FunctionalGroup> <ID>HC</ID> <Sender>901234572000</Sender> <Receiver>908887732000</Receiver> <Date>20020111</Date> <Time>1615</Time> <CtlNo>1</CtlNo> <Version>004010X096A1</Version> </FunctionalGroup> </Info> <Variables> <variable index="1" segment="CS" element="5">Topcat Co.</variable> <variable index="2" segment="" element=""></variable> </Variables> </Info>
Binary Segment Handling
UpdateAnalysis is also called when Instream validation encounters a binary segment and the ValidateBinarySegs option, found in the APF file, is not set to 0 (zero). For more information refer to TIB_fsp-instream_n.n.n_APF.pdf.
When the Guideline and APF cannot be Identified
With userMessage, you can handle several trading partner automation conditions where the guideline and APF cannot be identified from the values in the enveloping.
The userMessage provides an error number that Instream uses to:
-
Identify the envelope condition that caused the partner automation to fail
-
Send text that you specified
-
Send return code 191
-
For some error numbers, create TA1, 997, or 999 response documents
The format is:
userMessage ="error_code, message"
;Where:
error_code
One of the error codes in the Error Messages Table below. This will determine whether Instream creates TA1, 997, or 999 response documents, and what error message is returned.message
An error message worded by you.Example
userMessage = "10039, Interchange version is found but no receiver qualifier and ID matches";
Referring to the given table, we see that error number 10039 automatically creates a TA1 containing 022. The specified text is returned ( "Interchange version is found but no receiver qualifier and ID matches"), along with return code 191.
Please see Example 12. Trading Partner Automation in javaAPIDemo.java, in Instream’s
API\AllProductsAPISampleJava
directory.Error Messages Table Error code
Meaning
Responses created
10037
Interchange version is not found
None
10038
Interchange version is found but the sender ID/Qualifier pair is not found for any partner with that interchange version
None
10039
Interchange version is found but receiver ID/Qualifier pair is not found for any trading partner with that interchange version
TA1 with 022
10040
Interchange version and ID/Qual for both sender and receiver are found, but the interchange segment has other validation errors
TA1 with 016
10041
Group version is not found
TA1 accept
10042
Group version is found but the sender-receiver pair is not found
TA1 accept
997/999 reject
10043
Group version, group sender, and group receiver are all found, but the group segment contains other errors
TA1 accept
997/999 reject
10044
Transaction version is not found
TA1 accept
997/999 reject
RunJavaSample.bat Annotation
This file sets up paths and runs JavaApIDemo.class.
From File |
Explanation |
---|---|
set InStreamRoot=C:\Program Files\HIPAA Validator InStream |
InStreamRoot points to a high-level Instream directory. |
set
set OutputDir=%InStreamRoot%\Output |
InputDir and OutputDir are directories under InStreamRoot. |
rem Instream Bin directory must be in path in order for Java to find rem If it is not at the path, we add it here echo>__tmp__ %PATH% find>nul: /I "%InStreamRoot%\Bin" __tmp__ if ERRORLEVEL 1 set PATH=%PATH%;%InStreamRoot%\Bin del>nul: __tmp__ |
If Instream’s Bin directory is not in the path, it is located and added to the path. |
@echo Using Java to run 835-DEMO1.TXT data through Instream... java -classpath The dot just after the opening quotation mark says the path to JavaApIDemo.class is the same directory as the batch file. The semi-colon after it is a separator. |
Run
|
@echo. @echo Finished - Results can be found in pause |
Displays a message about where to find output. |