Skip to content

Migration

Jump to bottom
Christian Appl edited this page Mar 16, 2023 · 66 revisions

Version 9.0.0 redesigned, restructured and renamed many methods, classes and packages of this library, you should be aware of those changes before migrating.

Let´s discuss those changes, in the order you will most likely encounter them in your implementation.
(For a complete implementation example, please have a look at Usage.)

SessionFactory:

You will most likely start with a line, that should look something like this:

try (SomeSessionType<SOME_DOCUMENT_TYPE> session = SessionFactory.createInstance(
  WebServiceProtocol.SOME_PROTOCOL, new URL("http://localhost:8080/webPDF/"))
) {

The SessionFactory still is your entry point and you will still call createInstance() to acquire a wsclient Session. But it´s parameters have changed:

try (SomeSessionType<SOME_DOCUMENT_TYPE> session = SessionFactory.createInstance(sessionContext, authProvider)) {

SessionContext:

The SessionContext bundles the configuration of the WebServiceProtocol, server URL, TLSContext and ProxyConfiguration to a common object:

SessionContext sessionContext = new SessionContext(WebServiceProtocol.SOAP,"https://localhost:8043/webPDF/")
   .setTlsContext(new TLSContext(TLSProtocol.TLSV1_3, true, new File("AKeystore.file"), "keystorePassword"))
   .setProxy(new ProxyConfiguration("localhost", 8888));

It is no longer allowed to set/alter the TLSContext or ProxyConfiguration of a running Session, instead both must be known when the session is initialized. The WebserviceProtocol, the required server URL and the ProxyConfiguration are exactly the same as in prior version, but the TLSContext changed.

TLSContext:

Previously you will probably have used setters like these:

TLSContext tlsContext = new TLSContext();
tlsContext.setAllowSelfSigned(selfSigned);
tlsContext.setTrustStore(keystoreFile, "");

The TLSContext no longer allows to iteratively set the different parameters, instead it comes with a number of overloaded constructors, that limit and define the possible, valid combinations:

TLSContext tlsContext = new TLSContext(tlsProtocol, allowSelfSigned, trustStore, trustStorePassword);
tlsContext = new TLSContext(tlsProtocol, allowSelfSigned));
// etc.

The parameters have remained the same, but it shall be mentioned, that TLSProtocol now supports TLSv1.3

AuthProvider:

In previous versions you had to set credentials for your session.

session.setCredentials(credentials);

In wsclient version 9.0.0 you instead set an AuthProvider during the session creation:

try (SoapSession<SoapDocument> session = SessionFactory.createInstance(sessionContext,
   new UserAuthProvider(
      testServer.getLocalUser(), testServer.getLocalPassword())
)) {

You find the AuthProviders described here: User-Authentication. And especially the new OAuth2Providers here: OAuth2-Authorization. The old "Credentials" based logic does no longer exist and the setters have been removed.

REST login:

After establishing a REST session you would have to login in previous versions:

session.login();

This call has been removed and is no longer required. The selected AuthProvider shall organize the session authorization/authentication - Should an authentication be required at all. (i.e. OAuth2 JWT tokens already provide authorization and don´t require authentication.)

Webservice API:

The "WebserviceFactory" itself does still exist and it´s parameters and methods did not change. The following call is still valid:

WebServiceFactory.createInstance(session, WebServiceType.CONVERTER);

Alternatively you can now also use a session based shortcut for the webservice interface creation:

session.createWebServiceInstance(WebServiceType.CONVERTER);

However, Both statements above are correct and have identical results.

Setting the SourceDocument:

After having created your session and webservice interface, you would most likely set a source document now:

webService.setDocument(sourceDocument);

This setter has been removed, instead you now pass the sourceDocument (SoapDocument/RestDocument) to the process(sourceDocument) method directly

REST Document upload:

For REST you still have to upload your documents to the server using the DocumentManager:

session.getDocumentManager().uploadDocument(inputstream, resourceName);

Alternatively via the new shortcut:

session.uploadDocument(inputstream, resourceName);

SOAP Document creation:

SOAP documents no longer require to set the output target during initialization:

SoapDocument soapDocument = new SoapWebserviceDocument(inputStream);

Parameterization:

The logic of parameterizing your webservice has remained exactly the same for SOAP sessions:

// SOAP:
webService.getOperationParameters().setPages("1-4");
webService.getOperationParameters().setEmbedFonts(true);

PdfaType pdfa = new PdfaType();
webService.getOperationParameters().setPdfa(pdfa);
PdfaType.Convert convertPdfa = new PdfaType.Convert();
pdfa.setConvert(convertPdfa);
convertPdfa.setLevel(PdfaLevelType.LEVEL_3B);
convertPdfa.setErrorReport(PdfaErrorReportType.MESSAGE);

With the only difference, that Rest now uses different (OpenAPI) based types found in package "net.webpdf.wsclient.openapi.*" for which only the generation method differs, while the content is (mostly) identical to SOAP.

// REST:
webService.getOperationParameters().setPages("1-4");
webService.getOperationParameters().setEmbedFonts(true);

OperationPdfa pdfa = new OperationPdfa();
webService.getOperationParameters().setPdfa(pdfa);
OperationConvertPdfa convertPdfa = new OperationConvertPdfa();
pdfa.setConvert(convertPdfa);
convertPdfa.setLevel(OperationConvertPdfa.LevelEnum._3B);
convertPdfa.setErrorReport(OperationConvertPdfa.ErrorReportEnum.MESSAGE);

executing the Webservice call / process:

As already stated - to execute a webservice call you now need to provide the source document as a parameter to the process method:

SomeDocumentType target = webservice.process(sourceDocument);

For REST webservice calls, this is some "RestDocument" handle of a previously uploaded document. For SOAP this is a "SoapWebserviceDocument" you instantiated.

In case a webservice does not require a source document (currently this is only valid for the URL_CONVERTER), you should call the parameterless process() method.

Handling the result document:

For SOAP you can use the writeResult methods to write your resulting document to a file or Outputstream:

soapDocument.writeResult(targetFile);

For REST you can either download the document via the DocumentManager:

session.getDocumentManager().downloadDocument(document, outputStream);

Or use the new shortcut:

restDocument.downloadDocument(outputStream);

Closing SOAP documents:

In examples of previous wsclient versions we never explicitly mentioned this, but our examples used try-with-resources statements, implicitly implying it. It shall now be stated clearly: You should always close created SoapDocuments when you are finished. You might risk resource leaks of the underlying data handlers, should you not close them.

Access to new and old additional parameter structures:

New shortcuts to special parameter segments have been added to the WebService interface. You can now directly call "getPassword()" and "getBilling()" at you WebService instance, without having to search the OperationData yourself.

The new webservice independent settings and profiles can be requested via "getSettings()" at any WebService instance.

Why REST is preferable:

Finally this guide shall close with a recommendation: Switch to the REST interface, if you are free to do so.

REST already is providing more advanced and extended options, webservices and interfaces.

For example REST provides access to the webPDF "DocumentManager" and the document history - both features which are already integrated in the new REST wsclient and never will be available for SOAP. You can also find a placeholder for the "AdministrationManager", which will allow access to the webPDF 9.0.0 server administration API.

Further REST exclusive features can be expected in the future. It is highly recommended to switch to the REST API for your client implementation, to have those features available should you ever need them.

Clone this wiki locally