Add SMB examples and move the FTP and SFTP examples off the deprecated APIs - #6420
Open
niveathika wants to merge 6 commits into
Open
Add SMB examples and move the FTP and SFTP examples off the deprecated APIs#6420niveathika wants to merge 6 commits into
niveathika wants to merge 6 commits into
Conversation
Add four Ballerina by Example entries for the `smb` module, mirroring the set that already exists for FTP: sending and receiving a file with an `smb:Client`, and receiving a file and writing one back with an `smb:Listener` service. The `smb` module is not bundled in the distribution, so the samples are registered with `needCentral` and resolved from Ballerina Central.
Name the samples after what they demonstrate rather than a direction of transfer, following the way the HTTP samples are organised. A listener service does not send files, so the former "service - send file" sample becomes "Caller object", which is the concept it was really showing. Use the format specific methods throughout. The client samples write and read a string with `putText` and `getText` and bind JSON to a record with `putJson` and `getJson`, and the service binds the file content to a record through `onFileJson`, instead of moving bytes around. Also address the review feedback: document the Samba user the samples authenticate with, and drop the undocumented local file fixtures by keeping every sample on the share. The tip in each sample now points at a path the sample actually uses.
Every FTP and SFTP sample demonstrated an API the library has since deprecated, so the examples taught the wrong thing. The client samples used `put` and `get`, which are deprecated in favour of the format specific methods, and now use `putText` and `getText`. The service samples used `onFileChange`, which is deprecated in favour of the format specific handlers, along with the `path` and `fileNamePattern` fields of the listener configuration, which are deprecated in favour of `@ftp:ServiceConfig`. They now declare `onFileText` and take the watched directory from the annotation. The `ftp:Caller` sample appends with `putText` rather than the deprecated `append`. Also correct the tip in the service samples, which told the reader to run a client sample that writes to a directory the service does not watch.
A listener service does not send files, so the name described neither what the sample does nor what it teaches. Both samples exist to show the `ftp:Caller`, which is what the HTTP samples call a "Caller object", so name them the same way. The published URLs of the two samples change with this, and a redirect is needed for the previous ones.
SFTP is a protocol of the ftp module, so the type is ftp:Caller. There is no sftp module for the description to name.
niveathika
requested review from
MaryamZi,
NipunaRanasinghe and
gimantha
as code owners
August 12, 2026 07:14
|
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Ports the two examples changes already merged to
2201.13.x— #6418 and #6419 — tomaster.SMB examples (#6418)
Adds the four SMB examples: an SMB service that receives files, the
smb:Caller, and clients that write and read a file. They use the typed API (onFileText,putText,getText) and@smb:ServiceConfigrather than the deprecatedonFileChange/put/getand the deprecated listener config fields.FTP and SFTP examples off the deprecated APIs (#6419)
Every FTP and SFTP sample demonstrated an API the library has since deprecated:
putandget, and now useputTextandgetText.onFileChange, and thepath/fileNamePatternlistener config fields; they now declareonFileTextand take the watched directory from@ftp:ServiceConfig.ftp-service-send-fileandsftp-service-send-fileare renamed toftp-callerandsftp-caller("Caller object", matching the HTTP samples) — a listener service does not send files, and both samples exist to show the caller. The published URLs of these two samples change, so a redirect is needed for the previous ones.verifyBuildistruefor every FTP, SFTP, and SMB sample.The example sources are byte-identical to what is on
2201.13.x.index.jsonkeepsneedCentral: trueon the SMB samples, sinceballerina/smbis not bundled in the distribution;master'sballerina/build.gradledoes not read that flag today (it builds examples online), so it has no effect here, but it stays accurate if the flag is ported forward.