Package com.chilkatsoft.chilkat2

Class Scp

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Scp
All Implemented Interfaces:
AutoCloseable
public class Scp extends ChilkatObject
<section class="scp-summary">

Transfer files, text, and binary data over SCP using an existing SSH connection.

Chilkat.Scp is the Chilkat class for SCP file transfer over an already-established Chilkat.Ssh connection. It supports local-file upload and download, in-memory binary transfer, encoded binary transfer, text transfer with explicit character sets, BinData transfer, directory-tree synchronization, sync filtering, remote UNIX permission overrides, environment variables, progress scaling, abort support, and asynchronous task integration.

Uses an SSH connection

Attach Scp to an authenticated Chilkat.Ssh session rather than opening a separate network connection.

Upload and download files

Transfer local files to remote paths or download remote files to the local filesystem using SCP.

Memory-based transfers

Upload or download binary data, encoded data, text, or Chilkat.BinData without requiring temporary files.

Directory synchronization

Synchronize directory trees and use filtering options to include or exclude selected files.

Remote file options

Set remote UNIX permissions, pass environment variables, and control transfer-related behavior required by the remote server.

Progress and async support

Monitor progress, scale progress percentages, abort active transfers, and run supported operations as asynchronous tasks.

Common pattern: Connect and authenticate with Chilkat.Ssh, initialize Chilkat.Scp with that SSH connection, then upload, download, or synchronize the desired files or in-memory data. Use Scp for SCP-style transfers over SSH; use Chilkat.SFtp when the remote server expects the SFTP protocol instead.

For an extended overview, see Scp Class Overview.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Scp

      public Scp()
      Creates a new Scp object.

  • Method Details

    • getAbortCurrent

      public boolean getAbortCurrent()
      Set to true to request cancellation of the method currently executing on this object. Long-running network and file-transfer operations check this property periodically; a method that completes quickly may finish before the request is observed.

      Both synchronous and asynchronous operations can be cancelled. To cancel a synchronous call, set this property from another thread on the same Scp object. Chilkat resets the property to false after the cancellation is processed. If no method is running, a previously set value is cleared when the next method begins.

      Cooperative cancellation: This property requests an abort; it does not forcibly terminate a thread. Use the method return value, LastMethodSuccess where applicable, and LastErrorText to determine the final outcome.

      Returns:
      the value of the AbortCurrent property

    • setAbortCurrent

      public void setAbortCurrent​(boolean value)
      Sets the AbortCurrent property; see getAbortCurrent().
      Parameters:
      value - the new value

    • getHeartbeatMs

      public int getHeartbeatMs()
      Specifies the interval, in milliseconds, between AbortCheck event callbacks during supported long-running operations. The callback allows the application to report activity or request cancellation before the operation completes.

      The default value is 0, which disables periodic AbortCheck callbacks.

      Event-callback setting: This property is useful only in programming environments that support Chilkat event callbacks. It is not an SSH keep-alive interval and does not change connection or read timeouts.

      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

      public void setHeartbeatMs​(int value)
      Sets the HeartbeatMs property; see getHeartbeatMs().
      Parameters:
      value - the new value

    • getPercentDoneScale

      public int getPercentDoneScale()
      Specifies the value that represents 100% completion in PercentDone event callbacks. The default is 100, which reports progress in whole-percent units. For example, when the scale is 1000, a callback value of 453 represents 45.3% completion.

      The value is limited to the range 10 through 100000. Increasing the scale provides finer numeric granularity for operations whose progress can be measured.

      Event-callback setting: This property applies only in programming environments that support Chilkat event callbacks. A larger scale changes the meaning and possible granularity of callback values; it does not guarantee that every intermediate value will be reported.

      Returns:
      the value of the PercentDoneScale property

    • setPercentDoneScale

      public void setPercentDoneScale​(int value)
      Sets the PercentDoneScale property; see getPercentDoneScale().
      Parameters:
      value - the new value

    • getSendEnv

      public String getSendEnv()
      Specifies environment variables to send for each SCP upload or download. Set the property to a JSON object whose member names are environment-variable names and whose values are strings. 
      {
   "LCS_PASSWORD": "myPassword",
   "SOME_ENV_VAR": "some_value"
 }

      Server policy controls acceptance: SCP transfers run through SSH channels. The SSH server may accept, reject, or ignore requested environment variables according to its configuration. Do not assume that setting this property guarantees that the remote SCP process receives every variable. Sensitive values: Environment variables can contain secrets, but they are not a substitute for SSH authentication. Avoid exposing sensitive values in application logs or diagnostic output.

      Returns:
      the value of the SendEnv property

    • setSendEnv

      public void setSendEnv​(String value)
      Sets the SendEnv property; see getSendEnv().
      Parameters:
      value - the new value (not null)

    • getSyncMustMatch

      public String getSyncMustMatch()
      Specifies a semicolon-separated list of wildcard patterns for filenames that are eligible for transfer by syncTreeUpload(String, String, int, boolean) and syncTreeDownload(String, String, int, boolean). A file is considered only when its filename matches at least one pattern.

      For example, *.xml;*.txt;*.csv limits synchronization to XML, text, and CSV files. The default empty string imposes no include restriction.

      Pattern scope: Patterns are matched against the final filename, not the full local or remote path. Directory traversal is controlled separately by getSyncMustMatchDir() and getSyncMustNotMatchDir().

      Returns:
      the value of the SyncMustMatch property

    • setSyncMustMatch

      public void setSyncMustMatch​(String value)
      Sets the SyncMustMatch property; see getSyncMustMatch().
      Parameters:
      value - the new value (not null)

    • getSyncMustMatchDir

      public String getSyncMustMatchDir()
      Specifies a semicolon-separated list of wildcard patterns for directory names that may be traversed by syncTreeUpload(String, String, int, boolean) and syncTreeDownload(String, String, int, boolean). When this property is nonempty, synchronization descends only into directories whose names match at least one pattern.

      For example, a*;b*;c* permits traversal into directories whose names begin with a, b, or c. The default empty string permits traversal into all directories, subject to getSyncMustNotMatchDir().

      Pattern scope: Each pattern is matched against the directory name itself, not its complete path. This property affects traversal; it does not directly select individual files.

      Returns:
      the value of the SyncMustMatchDir property

    • setSyncMustMatchDir

      public void setSyncMustMatchDir​(String value)
      Sets the SyncMustMatchDir property; see getSyncMustMatchDir().
      Parameters:
      value - the new value (not null)

    • getSyncMustNotMatch

      public String getSyncMustNotMatch()
      Specifies a semicolon-separated list of wildcard patterns for filenames that must be skipped by syncTreeUpload(String, String, int, boolean) and syncTreeDownload(String, String, int, boolean).

      For example, *.tmp;*.bak;*.log excludes temporary, backup, and log files. The default empty string excludes no files.

      Pattern scope: Patterns are matched against the final filename, not the full path. Use getSyncMustNotMatchDir() to prevent synchronization from entering selected directories and their subtrees.

      Returns:
      the value of the SyncMustNotMatch property

    • setSyncMustNotMatch

      public void setSyncMustNotMatch​(String value)
      Sets the SyncMustNotMatch property; see getSyncMustNotMatch().
      Parameters:
      value - the new value (not null)

    • getSyncMustNotMatchDir

      public String getSyncMustNotMatchDir()
      Specifies a semicolon-separated list of wildcard patterns for directory names that must not be traversed by syncTreeUpload(String, String, int, boolean) and syncTreeDownload(String, String, int, boolean). A matching directory and everything below it are skipped.

      For example, temp*;cache*;.git prevents traversal into temporary, cache, and Git metadata directories. The default empty string excludes no directories.

      Pattern scope: Each pattern is matched against the directory name itself, not its complete path. This setting is especially useful during recursive synchronization because excluding a directory avoids scanning its entire subtree.

      Returns:
      the value of the SyncMustNotMatchDir property

    • setSyncMustNotMatchDir

      public void setSyncMustNotMatchDir​(String value)
      Sets the SyncMustNotMatchDir property; see getSyncMustNotMatchDir().
      Parameters:
      value - the new value (not null)

    • getSyncedFiles

      public String getSyncedFiles()
      Contains the local paths of the files transferred by the most recent call to syncTreeUpload(String, String, int, boolean) or syncTreeDownload(String, String, int, boolean). Paths are listed one per line.
      • After an upload, each line is the full local path of a source file that was uploaded.
      • After a download, each line is the full local path of a destination file that was downloaded.

      Local paths only: This property reports local filesystem paths, not remote paths. It lists files actually transferred by the last synchronization operation, rather than every file examined during comparison.

      Returns:
      the value of the SyncedFiles property

    • setSyncedFiles

      public void setSyncedFiles​(String value)
      Sets the SyncedFiles property; see getSyncedFiles().
      Parameters:
      value - the new value (not null)

    • getUncommonOptions

      public String getUncommonOptions()
      Provides a comma-separated list of specialized compatibility options. The default is the empty string, which is appropriate for normal SCP transfers.

      Keyword Behavior

      FilenameOnly Uses only the filename, rather than the complete target path, in the remote scp -t command. This option exists for compatibility with systems such as certain LANCOM routers.

      ProtectFromVpn On Android, attempts to route the SCP connection outside an installed or active VPN.

      Leave empty unless needed: These options alter uncommon platform or server compatibility behavior. Enable a keyword only when a Chilkat example, release note, or support response identifies it as necessary for the target environment.

      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • getUnixPermOverride

      public String getUnixPermOverride()
      Specifies an octal UNIX permission mode to apply to files uploaded by SCP, overriding the permissions derived from the local source file. For example, set this property to 0644 to grant read/write permission to the owner and read-only permission to the group and others.

      The default is the empty string, which causes the uploaded file's remote permissions to be based on the local file's permissions.

      UNIX permission notation: Supply the mode as a string containing octal digits, such as 0600, 0644, or 0755. The remote SSH account must still have permission to create or replace the file, and server-side policy may restrict the final mode.

      Returns:
      the value of the UnixPermOverride property

    • setUnixPermOverride

      public void setUnixPermOverride​(String value)
      Sets the UnixPermOverride property; see getUnixPermOverride().
      Parameters:
      value - the new value (not null)

    • downloadBd

      public void downloadBd​(String remotePath, BinData bd)
      Downloads the file at remotePath and appends its exact bytes to the existing contents of the BinData object in bd.

      An absolute remote path begins with /. A relative path is interpreted relative to the authenticated SSH user's home directory.

      Append behavior: This method does not clear bd before downloading. Clear the BinData object first when the downloaded file should replace, rather than follow, its current contents.

      Parameters:
      remotePath - the remotePath argument (not null)
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • downloadBinaryEncoded

      public String downloadBinaryEncoded​(String remotePath, String encoding)
      Downloads the file at remotePath and returns its bytes encoded as text using the binary encoding named by encoding, such as base64 or hex.

      An absolute remote path begins with /. A relative path is interpreted relative to the authenticated SSH user's home directory.

      Binary encoding versus charset: encoding selects a text representation of arbitrary bytes; it is not a character set and does not decode the remote file as text. Use downloadString(String, String) when the remote file contains text that must be decoded with a charset. Memory use: The complete file and its encoded representation are held in memory. Encodings such as Base64 also increase the amount of data returned.

      Parameters:
      remotePath - the remotePath argument (not null)
      encoding - the encoding argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • downloadFile

      public void downloadFile​(String remotePath, String localPath)
      Downloads the file at remotePath from the SSH server and writes its bytes to the local filesystem path in localPath.

      An absolute remote path begins with /. A relative remote path is interpreted relative to the authenticated SSH user's home directory. The application must have permission to create or replace the local destination file.

      Streaming transfer: This method is the preferred download method for large files because the data is written to disk rather than returned as one in-memory byte array or string.

      Parameters:
      remotePath - the remotePath argument (not null)
      localPath - the localPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • downloadString

      public String downloadString​(String remotePath, String charset)
      Downloads the file at remotePath, decodes its bytes using the character encoding named by charset, and returns the resulting text.

      An absolute remote path begins with /. A relative path is interpreted relative to the authenticated SSH user's home directory.

      Charset matters: charset describes how the remote file’s bytes represent characters, for example utf-8, windows-1252, or iso-8859-1. Using the wrong charset can produce incorrect characters. Use a binary download method for files that are not text.

      Parameters:
      remotePath - the remotePath argument (not null)
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • syncTreeDownload

      public void syncTreeDownload​(String remoteRoot, String localRoot, int mode, boolean bRecurse)
      Synchronizes files from the remote directory tree rooted at remoteRoot to the local directory rooted at localRoot. bRecurse controls recursion: set it to true to descend into subdirectories, or false to process only files directly in the root directory.

      An absolute remote root begins with /; a relative remote root is interpreted relative to the authenticated SSH user's home directory. A relative local root is interpreted relative to the application's current working directory.

      Mode Files transferred

      0 Download every eligible file.

      1 Download files that do not already exist locally.

      2 Download files that are missing locally or whose remote last-modified time is newer than the local file.

      3 Download only files whose remote last-modified time is newer. A remote file that has no local counterpart is not downloaded.

      5 Download files that are missing locally or whose size differs from the local file.

      6 Download files that are missing locally, differ in size, or have a newer remote last-modified time.

      The filename and directory filters in getSyncMustMatch(), getSyncMustNotMatch(), getSyncMustMatchDir(), and getSyncMustNotMatchDir() are applied during traversal. After completion, getSyncedFiles() lists the full local paths of files actually downloaded.

      Timestamp-based modes: Modes 2, 3, and 6 compare last-modified times. Incorrect server timestamps or clock differences between systems can affect which file is considered newer.

      Parameters:
      remoteRoot - the remoteRoot argument (not null)
      localRoot - the localRoot argument (not null)
      mode - the mode argument
      bRecurse - the bRecurse argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • syncTreeUpload

      public void syncTreeUpload​(String localBaseDir, String remoteBaseDir, int mode, boolean bRecurse)
      Synchronizes files from the local directory tree rooted at localBaseDir to the remote directory rooted at remoteBaseDir. bRecurse controls recursion: set it to true to descend into subdirectories, or false to process only files directly in the local base directory.

      A relative local base directory is interpreted relative to the application's current working directory. An absolute remote base directory begins with /; a relative remote base directory is interpreted relative to the authenticated SSH user's home directory.

      Mode Files transferred

      0 Upload every eligible file.

      1 Upload files that do not already exist on the remote server.

      2 Upload files that are missing remotely or whose local last-modified time is newer than the remote file.

      3 Upload only files whose local last-modified time is newer. A local file that has no remote counterpart is not uploaded.

      4 Upload files that are missing remotely or whose size differs from the remote file.

      5 Upload files that are missing remotely, differ in size, or have a newer local last-modified time.

      The filename and directory filters in getSyncMustMatch(), getSyncMustNotMatch(), getSyncMustMatchDir(), and getSyncMustNotMatchDir() are applied during traversal. After completion, getSyncedFiles() lists the full local paths of files actually uploaded.

      Timestamp-based modes: Modes 2, 3, and 5 compare last-modified times. Incorrect server timestamps or clock differences between systems can affect which file is considered newer.

      Parameters:
      localBaseDir - the localBaseDir argument (not null)
      remoteBaseDir - the remoteBaseDir argument (not null)
      mode - the mode argument
      bRecurse - the bRecurse argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uploadBd

      public void uploadBd​(String remotePath, BinData bd)
      Uploads all bytes currently contained in the BinData object in bd to the remote file at remotePath. The data is transferred without character decoding or other transformation.

      An absolute remote path begins with /. A relative path is interpreted relative to the authenticated SSH user's home directory. The remote parent directory must already exist.

      Source object: The upload reads the current contents of bd and does not remove or modify those bytes.

      Parameters:
      remotePath - the remotePath argument (not null)
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uploadBinaryEncoded

      public void uploadBinaryEncoded​(String remotePath, String encodedData, String encoding)
      Decodes the text in encodedData using the binary encoding named by encoding, then uploads the resulting bytes to the remote file at remotePath. Typical encoding names include base64 and hex.

      An absolute remote path begins with /. A relative path is interpreted relative to the authenticated SSH user's home directory. The remote parent directory must already exist.

      The encoded text is not uploaded literally: For example, when encoding is base64, Chilkat Base64-decodes encodedData and transfers the decoded binary bytes. This method is for encoded binary representations, not character-set conversion.

      Parameters:
      remotePath - the remotePath argument (not null)
      encodedData - the encodedData argument (not null)
      encoding - the encoding argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uploadFile

      public void uploadFile​(String localPath, String remotePath)
      Uploads the local filesystem file at localPath to the remote path in remotePath. The file is transferred as raw bytes.

      An absolute remote path begins with /. A relative remote path is interpreted relative to the authenticated SSH user's home directory. The remote parent directory must already exist, and the SSH account must have permission to create or replace the destination file.

      Remote permissions are normally derived from the local file. Set getUnixPermOverride() when a specific remote UNIX mode is required.

      SCP is not FTP: There is no ASCII or binary transfer mode. UploadFile copies the file bytes without line-ending or character-set conversion.

      Parameters:
      localPath - the localPath argument (not null)
      remotePath - the remotePath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uploadString

      public void uploadString​(String remotePath, String textData, String charset)
      Encodes the text in textData using the character encoding named by charset, then uploads the resulting bytes to the remote file at remotePath.

      An absolute remote path begins with /. A relative path is interpreted relative to the authenticated SSH user's home directory. The remote parent directory must already exist.

      Text encoding: charset controls how characters are converted to bytes, for example utf-8, windows-1252, or iso-8859-1. SCP itself has no text mode; any line-ending characters already present in textData are encoded and transferred as part of the text.

      Parameters:
      remotePath - the remotePath argument (not null)
      textData - the textData argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • useSsh

      public void useSsh​(Ssh sshConnection)
      Associates this Scp object with the connected and authenticated Ssh object in sshConnection. Subsequent SCP operations use that existing SSH session rather than opening a separate network connection.

      Connection, proxy, timeout, host-key verification, algorithm, logging, and other transport-related settings belong to the Ssh object and therefore apply to the SCP operations performed through it. Keep the SSH object connected and available for as long as the Scp object is using it.

      SCP and SFTP are different protocols: Scp performs SCP-style transfers over SSH and requires compatible SCP support on the remote system. Use Chilkat.SFtp when the server expects the SSH File Transfer Protocol subsystem or when directory listing and remote file-management features are needed.

      Parameters:
      sshConnection - the sshConnection argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setProgressListener

      public void setProgressListener​(ProgressListener listener)
      Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
      Parameters:
      listener - the listener, or null
      Throws:
      IllegalStateException - if called from inside one of this object's own callbacks

    • getProgressListener

      public ProgressListener getProgressListener()
      Returns the installed listener, or null.
      Returns:
      the listener installed with setProgressListener(ProgressListener) or one of the on... methods

    • onAbortCheck

      public void onAbortCheck​(BooleanSupplier callback)
      Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onPercentDone

      public void onPercentDone​(IntPredicate callback)
      Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onProgressInfo

      public void onProgressInfo​(BiConsumer<String,​String> callback)
      Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener