CIB documentServer technical documentation (EN)
Quick Start
Calling CIB Documentserver
In the following you will find descriptions of how you can comfortably integrate the CIB documentServer into JAVA from the client package. This section also contains instructions on how to call the CIB documentServer webservice in Visual basic .net, C# .net and with the JAX-WS framework.
CIB documentServer Framework/JavaCIB documentServer Framework/.net
Calling CIB documentServer web service
Calling the CIB documentServer asynchronous
CIB documentServer Framework/Java
The CIB documentServer framework enables a comfortable integration of the CIB documentServer in Java. Due to the similarity of the concepts of the two platforms as well as of Java and C#, the corresponding section remains short.
With the CIB documentServer framework, Java application developers can generate the job files, analyze the job result files, and retrieve the result documents.
Concept
The order processing is represented by the framework in several levels according to the layer model.
On this level (the lowest in Java), the communication to the native components takes place and process monitoring, locking, internal load balancing and queuing are implemented.
Job and job result files are considered and processed as byte[] and byte[][] respectively.
You can use these classes to achieve a close cooperation with the CIB documentServer if you want to extend the server layer or develop your own server layer.
Integration layer
Predefined classes are available for integration into the various usage variants, such as the servlet for the http interface to the CIB documentServer. This layer will be extended by classes for integration in EJB, JNI and MQSeries.
You will use these classes directly, or replace them completely with your own classes. Talk to us about providing source code.
Application layer
In the application layer as well as in the supply of classes for the integration layer, classes are provided for the convenient creation and execution of job files.
At this level, an order is an object of type de.cib.docserv.job.Request and the order results file of type de.cib.docserv.job.Response. The result documents are made available as streams.
An order is passed to a class that implements the interface de.cib.docserv.DocumentServer, such as de.cib.docserv.UrlDocumentServerImpl, which completely encapsulates the communication with a CIB documentServer via the usage option http.
…
Response t_Response = new UrlDocumentServerImpl(t_Hostname, t_Port).execute(t_Request);
if (!t_Response.hasErrors())
{
JobResult t_JobResult = t_Response.getJobResult();
StepResult t_StepResult = t_JobResult.getStepResult();
String t_ContentType = t_StepResult.getMimeType();
InputStream t_Document = t_StepResult.getStepData();
Packages
The most important packages are listed below.
de.cib.docserv
Together with the subpackages, this package contains the classes required for the usage variants Java, JEE Servlet Container and JEE EJB Container.
Especially the interface classes that implement the interface de.cib.docserv.DocumentServer are listed here. Furthermore, the basic implementation of the CIB documentServer in the form of de.cib.docserv.ServerManager, de.cib.docserv.ServerQueue, as well as the exception and error classes.
de.cib.docserv.job
This package contains, among other things, the auxiliary classes de.cib.docserv.job.Request and de.cib.docserv.job.Response, which are important for you and which can be used to generate and analyze jobs. Additionally, use the class de.cib.xml.dom.Dom.Dom to add your XML with the user data to the job.
de.cib.xml.dom
The class de.cib.xml.dom.Dom, with which other classes of the framework receive XML data, should be emphasized. Therefore pack your XML with the user data into a de.cib.xml.dom.Dom.
The CIB documentServer framework enables the CIB documentServer to be integrated. In the first step, the order file is read in and the request for the CIB documentServer is created from it. In the next step the CIB documentServer is generated and configured to process the request. As a result the CIB documentServer delivers a response which is processed in the last step. The following code snippet shows the integration of a CIB documentServer into a Java application.
//create request for the CIB documentServer
Request request = new RequestXmlParser().parseRequest(new File("Job.xml"));
//create documentServer with following parameters: hostname: remote computer, where
the CIB documentServer servlet is configured; port: port number of servlet.
DocumentServer documentServer = new UrlDocumentServerImpl(“localhost“, 8080);
//get the response from the CIB documentserver
Response response = null;
if (request != null) {
response = documentServer.execute(request);
//check if all jobs were successful
if (response.hasErrors() || response == null {
System.err.println("Response: "+response);
System.out.println("Bytes written: "+0);
response.throwException(); // optional
} else {
//Save the JobResult in a client file
InputStream input = null;
OutputStream output = null;
int bytesWritten = 0;
Set enumStepResults = response.getJobResult().getStepNames();
if (enumStepResults != null) {
Iterator iterator = enumStepResults.iterator();
while (iterator.hasNext()) {
String name = (String) iterator.next();
try {
input = response.getJobResult().
getStepResult(name).getStepData();
if (input.available() <= 0)
continue;
// only one result is available and the
// mimetype is application/pdf
output = new FileOutputStream(new File(request
.getJob().getName() + "-" + name +
".pdf"));
byte[] buffer = new byte[0xffff];
int bytesRead = 0;
while ((bytesRead = input.read(buffer)) >= 0) {
output.write(buffer, 0, bytesRead);
bytesWritten += bytesRead;
}
if (bytesWritten <= 0) {
byte[] text = "Empty Result".getBytes();
output.write(text, 0, text.length);
bytesWritten += text.length;
}
input.close();
output.close();
} catch (IOException e) {
e.printStackTrace();
}
}
}
System.out.println("Bytes written: " + bytesWritten);
}
}
Further examples can be found in the client package under example/de/cib/docserv/samples.
Buiding a job from JAVA
It is also possible to create an XML job using the CIB documentServer framework.
//build new Request
Request request = new Request();
Job job = new Job("testJob");
job.setProperty("OutputMode", "XML");
Step pdfJoinStep = new Step((new CommandFactory()).createCommand(CommandFactory.COMMAND_PDFJOIN), "PdfJoinStep");
//Set the propertys for the request
pdfJoinStep.setProperty("OutputFilename", "ZUGFeRD-invoice.xml");
pdfJoinStep.setProperty("ZUGFeRDDoCheck", "1");
pdfJoinStep.setProperty("OutputFormat", "FormatInfo");
pdfJoinStep.setProperty("FilterInfo", "EmbeddedFilesInfo");
pdfJoinStep.setProperty("EmbeddedFilesInfoFilter", "EmbeddedFiles");
//Set a property with setPropertyMode and “out” value in order to obtain its value in the //response
pdfJoinStep.setPropertyMode("EmbeddedFilesInfo", "out");
pdfJoinStep.setPropertyMode("ModuleName", "out");
//Use setPropertyMode with value “inout”in order to hint, that the value of an input //property will also be obtained in the response.
pdfJoinStep.setProperty("InputFilename", “Test.pdf”);
pdfJoinStep.setPropertyMode("InputFilename", "inout");
job.addStep(pdfJoinStep);
request.addJob(job);
In this example, an order is created with a "PdfJoin" step. A series of properties is declared programmatically for the corresponding order.
It is also possible to retrieve the value of desired properties in the result-response by using the method "setPropertyMode" when setting up the request (from version 1.10.6).
The property values can be retrieved as follows:
JobResult t_JobResult = response.getJobResult();
StepResult t_StepResult = t_JobResult.getStepResult("PdfJoinStep ");
String ModuleName = t_StepResult.getProperty("ModuleName");
String embeddedFilesInfo = t_StepResult.getProperty("EmbeddedFilesInfo");
String inputFilename = t_StepResult.getProperty("InputFilename");
CIB documentServer Framework/.net
Calling CIB documentServer web service
Design a method that calls the CIB documentServer web service.
Register the web service by adding a web resource to your project. Complete the URL at the end with ?wsdl. The web service "CibDocumentServer" should be displayed with a method "generate". Enter the package name from de.cib.docserv.web as "web reference name”.
Generate classes by selecting "Update". To perform this step successfully, you need internet access to www.cib.de.
Calling the web service
Now create instances of the service and request classes as follows:
Dim service As New de.cib.docserv.web.CibDocumentServer Dim request As New de.cib.docserv.web.Request
Add the necessary steps to the request. (See Code examples in Appendix)
Dim mergeStep As New de.cib.docserv.web.StepType Dim mergeProps(4) As de.cib.docserv.web.PropertyType mergeStep.name = "step1" mergeStep.command = "merge" mergeStep.properties = New de.cib.docserv.web.PropertiesType() mergeStep.properties.property = mergeProps mergeStep.properties.property(0) = New de.cib.docserv.web.PropertyType() mergeStep.properties.property(0).name = "-i" mergeStep.properties.property(0).Value = "Test.rtf"
Add your user data to the request. The structure is arbitrary, but needs to match the input template (-i) of the merge step and the option -d.
Dim XmlString As String = "" Dim xmldata As New System.Xml.XmlDocument xmldata.LoadXml(XmlString) request.Data = xmldata.DocumentElement Otto ...
Now call the web service and prepare it to receive the result:
Dim response As de.cib.docserv.web.Response response = service.generate(request)
Processing results
If server errors occur, the above call throws an exception.
If errors occur during document generation, no exceptions are thrown. Instead, you receive a response object. You should retrieve the error code from the job result to decide whether an execution error has occurred. An example of an error message is: "CIB merge error 10: Unknown variable in template"
Dim jobResults As de.cib.docserv.web.JobResultsType
jobResults = CType(response.Comod.Items(0), de.cib.docserv.web.JobResultsType)
If (jobResults.jobresult(0).jobresultcode = 0) Then
' Success
Dim stepData As de.cib.docserv.web.StepDataType
stepData = jobResults.jobresult(0).stepresults(1).stepdata
...
Else
' A step failed
Debug.Print("Error " & jobResults.jobresult(0).jobresultcode & ": " _
& jobResults.jobresult(0).jobresulttext)
Debug.Print("Failed step(s): " _
& jobResults.jobresult(0).failed.name)
...
End If
If successful, you have to retrieve the generated documents from the response. The result is base64-encoded. You must decode it accordingly.
' Extract base64 encoded pdf from stepdata saveDocument(stepData.Value)
Please find the complete VB.net Sourcecode attached to this document.
The corresponding examples of SOAP requests and responses can also be found attached.
If the CIB documentServer is to be called from C#.net as a web service, the procedure is the same as under VB.net. The calls only differ in their syntax. An example code can be found attached. Anhang.
When calling from C#.net using an HTTP connection, there may be communication problems in connection with an application server. In this case it may help to disable the "Expect100Continue" property of the client-server connection (the default value is true).
Example:
webRequest.ServicePoint.Expect100Continue =
false;
CIB documentServer Framework/JAX-WS
The JAX-WS (Java API for XML Web Services) client provides an easy way to call the CIB documentServer webservice. The functionality is integrated in the CibDocumentServer.jar To use JAX-WS at least a JRE 5.0 is required.
Calling CIB job locally (offline)
This section still needs to be revised with regard to JobDocumentServerImpl.
The modular structure of the CIB documentServer allows its installation on the client even without a local server environment like JEE Servlet Container, MTS or .net.
The application passes a request (XML) to the existing components of the CIB documentServer, which generates a corresponding document.
The transfer takes place via call interfaces from Java code or from native code (interfaces Java Call, Native Call). No JEE application server is required for this.
If several threads send requests to a server manager but no web context is available, suitable classes are available to take over the administration of the server manager (de.cib.docserv.LocalDocumentServerImpl).
In normal Java applications that also want to use the CIB documentServer framework instead of JNI, it is not necessary to start multiple socket servers in parallel.
Instead, a single external process is sufficient, which is started automatically by the framework. In addition to the order classes (de.cib.job.Request, de.cib.job.Response), suitable administration classes are also available for this situation (de.cib.docserv.SingleDocumentServerImpl).
Calling the CIB documentServer asynchronous
To execute jobs asynchronously with the CIB documentServer, use the asyncExecute method of the CIB documentServer framework.
When using other CIB documentServer commands from other languages, please set the header field async-action:
Start asyncronous call: async-action: new
Get the result of the asynchronous call with the ID 12345: async-action: 12345
For the XML content exchanged in asynchronous calls, please refer to the technical guide for CIB job in the sections additional settings for asynchronously executed requests and contents of a request result for an asynchronously executed request.