From b64e37973e97564b765e428e9286459152424c63 Mon Sep 17 00:00:00 2001 From: Gregory Bragg Date: Sun, 8 May 2022 18:28:16 -0400 Subject: [PATCH] Add documentation for SMB Support * Updated, polished documentation prior to PR review * Updated after PR review comments, changed Adapter verbiage to Support * Add `SmbMessageHandler(SmbRemoteFileTemplate)` ctors * Clean up `smb.adoc` for extra redundant interim headlines --- .../smb/outbound/SmbMessageHandler.java | 31 ++-- src/reference/asciidoc/endpoint-summary.adoc | 6 + src/reference/asciidoc/index-single.adoc | 2 + src/reference/asciidoc/index.adoc | 1 + src/reference/asciidoc/smb.adoc | 144 ++++++++++++++++++ src/reference/asciidoc/whats-new.adoc | 6 + 6 files changed, 177 insertions(+), 13 deletions(-) create mode 100644 src/reference/asciidoc/smb.adoc diff --git a/spring-integration-smb/src/main/java/org/springframework/integration/smb/outbound/SmbMessageHandler.java b/spring-integration-smb/src/main/java/org/springframework/integration/smb/outbound/SmbMessageHandler.java index 99fe57780a..06fcad0bdc 100644 --- a/spring-integration-smb/src/main/java/org/springframework/integration/smb/outbound/SmbMessageHandler.java +++ b/spring-integration-smb/src/main/java/org/springframework/integration/smb/outbound/SmbMessageHandler.java @@ -22,26 +22,31 @@ import org.springframework.integration.file.support.FileExistsMode; import org.springframework.integration.smb.session.SmbRemoteFileTemplate; import jcifs.smb.SmbFile; +import reactor.core.publisher.Mono; /** -* The SMB specific {@link FileTransferringMessageHandler} extension. Based on the -* {@link SmbRemoteFileTemplate}. -* -* @author Gregory Bragg -* @author Artem Bilan -* -* @since 6.0 -* -* @see SmbRemoteFileTemplate -*/ + * The SMB specific {@link FileTransferringMessageHandler} extension. Based on the + * {@link SmbRemoteFileTemplate}. + * + * @author Gregory Bragg + * @author Artem Bilan + * + * @since 6.0 + * + * @see SmbRemoteFileTemplate + */ public class SmbMessageHandler extends FileTransferringMessageHandler { public SmbMessageHandler(SessionFactory sessionFactory) { - this(sessionFactory, FileExistsMode.REPLACE); + this(new SmbRemoteFileTemplate(sessionFactory)); } - public SmbMessageHandler(SessionFactory sessionFactory, FileExistsMode mode) { - super(new SmbRemoteFileTemplate(sessionFactory), mode); + public SmbMessageHandler(SmbRemoteFileTemplate remoteFileTemplate) { + super(remoteFileTemplate); + } + + public SmbMessageHandler(SmbRemoteFileTemplate remoteFileTemplate, FileExistsMode mode) { + super(remoteFileTemplate, mode); } } diff --git a/src/reference/asciidoc/endpoint-summary.adoc b/src/reference/asciidoc/endpoint-summary.adoc index f0cfa5a413..d45ff1c05e 100644 --- a/src/reference/asciidoc/endpoint-summary.adoc +++ b/src/reference/asciidoc/endpoint-summary.adoc @@ -174,6 +174,12 @@ The following table summarizes the various endpoints with quick links to the app | N | <<./sftp.adoc#sftp-outbound-gateway,SFTP Outbound Gateway>> +| *SMB* +| <<./smb.adoc#smb-inbound,SMB Inbound Channel Adapter>> +| <<./smb.adoc#smb-outbound,SMB Outbound Channel Adapter>> +| N +| N + | *STOMP* | <<./stomp.adoc#stomp-inbound-adapter,STOMP Inbound Channel Adapter>> | <<./stomp.adoc#stomp-outbound-adapter,STOMP Outbound Channel Adapter>> diff --git a/src/reference/asciidoc/index-single.adoc b/src/reference/asciidoc/index-single.adoc index 65643c562c..03c09e9582 100644 --- a/src/reference/asciidoc/index-single.adoc +++ b/src/reference/asciidoc/index-single.adoc @@ -71,6 +71,8 @@ include::./rsocket.adoc[] include::./sftp.adoc[] +include::./smb.adoc[] + include::./stomp.adoc[] include::./stream.adoc[] diff --git a/src/reference/asciidoc/index.adoc b/src/reference/asciidoc/index.adoc index b8c3a83432..0ddd689d90 100644 --- a/src/reference/asciidoc/index.adoc +++ b/src/reference/asciidoc/index.adoc @@ -45,6 +45,7 @@ This documentation is also available as single searchable link:index-single.html <<./resource.adoc#resource,Resource Support>> :: <<./rsocket.adoc#rsocket,RSocket Support>> :: <<./sftp.adoc#sftp,SFTP Adapters>> :: +<<./smb.adoc#smb,SMB Support>> :: <<./stomp.adoc#stomp,STOMP Support>> :: <<./stream.adoc#stream,Stream Support>> :: <<./syslog.adoc#syslog,Syslog Support>> :: diff --git a/src/reference/asciidoc/smb.adoc b/src/reference/asciidoc/smb.adoc new file mode 100644 index 0000000000..0f5eb611e3 --- /dev/null +++ b/src/reference/asciidoc/smb.adoc @@ -0,0 +1,144 @@ +[[smb]] +== SMB Support + +Spring Integration provides support for file transfer operations with SMB. + +The https://en.wikipedia.org/wiki/Server_Message_Block[Server Message Block] (SMB) is a simple network protocol that lets you transfer files to a shared file server. + +You need to include this dependency into your project: + +==== +[source, xml, subs="normal", role="primary"] +.Maven +---- + + org.springframework.integration + spring-integration-smb + {project-version} + +---- +[source, groovy, subs="normal", role="secondary"] +.Gradle +---- +compile "org.springframework.integration:spring-integration-smb:{project-version}" +---- +==== + +=== Overview + +The https://github.com/codelibs/jcifs[Java CIFS] Client Library has been chosen as a Java implementation for the CIFS/SMB networking protocol. +Its `SmbFile` abstraction is simply wrapped to the Spring Integration "Remote File" foundations like `SmbSession`, `SmbRemoteFileTemplate`, etc. + +The SMB Channel Adapters and support classes implementations are fully similar to existing components for (S)FTP or AWS S3 protocols. +So, if you familiar with those components it is pretty straightforward to use. + +[[smb-session-factory]] +=== SMB Session Factory + +Before configuring the SMB adapter, you must configure an SMB session factory. +You can configure the SMB session factory with a regular bean definition, as the following examples show: + +The `SmbSessionFactory` exposes options to set the SMB protocol with Min/Max versions. +For example, supporting a minimum version of SMB 2.1 and a maximum version of the SMB 3.1.1: + +[source,java] +---- +@Bean +public SmbSessionFactory smbSessionFactory() { + SmbSessionFactory smbSession = new SmbSessionFactory(); + smbSession.setHost("myHost"); + smbSession.setPort(445); + smbSession.setDomain("myDomain"); + smbSession.setUsername("myUser"); + smbSession.setPassword("myPassword"); + smbSession.setShareAndDir("myShareAndDir"); + smbSession.setSmbMinVersion(DialectVersion.SMB210); + smbSession.setSmbMaxVersion(DialectVersion.SMB311); + return smbSession; +} +---- + +The `SmbSessionFactory` can be initialized with a custom `jcifs.CIFSContext`. + +NOTE: Setting of the SMB protocol Min/Max versions must be done in your implementation of `jcifs.CIFSContext`. + +[source,java] +---- +@Bean +public SmbSessionFactory smbSessionFactory() { + SmbSessionFactory smbSession = new SmbSessionFactory(new MyCIFSContext()); + smbSession.setHost("myHost"); + smbSession.setPort(445); + smbSession.setDomain("myDomain"); + smbSession.setUsername("myUser"); + smbSession.setPassword("myPassword"); + smbSession.setShareAndDir("myShareAndDir"); + return smbSession; +} +---- + +[[smb-inbound]] +=== SMB Inbound Channel Adapter + +To download SMB files locally the `SmbInboundFileSynchronizingMessageSource` is provided. +It is simple extension of the `AbstractInboundFileSynchronizingMessageSource` which requires `SmbInboundFileSynchronizer` injection. +For filtering remote files you still can use any existing `FileListFilter` implementations, but particular `SmbRegexPatternFileListFilter` and `SmbSimplePatternFileListFilter` are provided. + +[source,java] +---- +@Bean +public SmbInboundFileSynchronizer smbInboundFileSynchronizer() { + SmbInboundFileSynchronizer fileSynchronizer = + new SmbInboundFileSynchronizer(smbSessionFactory()); + fileSynchronizer.setFilter(compositeFileListFilter()); + fileSynchronizer.setRemoteDirectory("mySharedDirectoryPath"); + fileSynchronizer.setDeleteRemoteFiles(true); + return fileSynchronizer; +} + +@Bean +public CompositeFileListFilter compositeFileListFilter() { + CompositeFileListFilter filters = new CompositeFileListFilter<>(); + filters.addFilter(new SmbRegexPatternFileListFilter("^(?i).+((\\.txt))$")); + return filters; +} + +@Bean +public MessageChannel smbFileInputChannel() { + return new DirectChannel(); +} + +@Bean +@InboundChannelAdapter(value = "smbFileInputChannel", + poller = @Poller(fixedDelay = "2000")) +public MessageSource smbMessageSource() { + SmbInboundFileSynchronizingMessageSource messageSource = + new SmbInboundFileSynchronizingMessageSource(smbInboundFileSynchronizer()); + messageSource.setLocalDirectory(new File("myLocalDirectoryPath")); + messageSource.setAutoCreateLocalDirectory(true); + return messageSource; +} +---- + +For XML configuration the `` component is provided. + +[[smb-outbound]] +=== SMB Outbound Channel Adapter + +For writing files to an SMB share, and for XML `` component we use the `SmbMessageHandler`. +In case of Java configuration a `SmbMessageHandler` should be supplied with the `SmbSessionFactory` (or `SmbRemoteFileTemplate`). + +[source,java] +---- +@Bean +@ServiceActivator(inputChannel = "storeToSmbShare") +public MessageHandler smbMessageHandler(SmbSessionFactory smbSessionFactory) { + SmbMessageHandler handler = new SmbMessageHandler(smbSessionFactory); + handler.setRemoteDirectoryExpression( + new LiteralExpression("remote-target-dir")); + handler.setFileNameGenerator(m -> + m.getHeaders().get(FileHeaders.FILENAME, String.class) + ".test"); + handler.setAutoCreateDirectory(true); + return handler; +} +---- diff --git a/src/reference/asciidoc/whats-new.adoc b/src/reference/asciidoc/whats-new.adoc index 54b7ec8088..e397c062e8 100644 --- a/src/reference/asciidoc/whats-new.adoc +++ b/src/reference/asciidoc/whats-new.adoc @@ -23,6 +23,12 @@ In general the project has been moved to Java 17 baseline and migrated from Java The GraphQL support has been added. See <<./graphql.adoc#graphql,GraphQL Support>> for more information. +[[x6.0-smb]] +=== SMB Support + +SMB support has been added from the Spring Integration Extensions project. +See <<./smb.adoc#smb,SMB Support>> for more information. + [[x6.0-general]] === General Changes