应用程序和集群管理

stop [pid_file]

用于停止运行RabbitMQ的Erlang node.如果指定了pid_file，还将等待指定的过程结束。例如：

rabbitmqctl stop

此命令会终止RabbitMQ node的运行.

stop_app

停止RabbitMQ application,但Erlang node会继续运行.此命令主要用于优先执行其它管理操作（这些管理操作需要先停止RabbitMQ application），如. reset.例如：

rabbitmqctl stop_app

start_app

启动RabbitMQ application.

此命令典型用于在执行了其它管理操作之后，重新启动停止的RabbitMQ application。如reset.例如：

rabbitmqctl start_app

此命令来指导RabbitMQ node来启动RabbitMQ application.

wait {pid_file}

等待RabbitMQ application启动.此命令用来等待RabbitMQ application来启动node。它会等待创建pid文件，然后等待pid文件中的特定pid过程启动，最后等待RabbitMQ  application 来启动node. 

pid file是通过rabbitmq-server 脚本来创建的.默认情况下，它存放于Mnesia目录中. 修改RABBITMQ_PID_FILE 环境变量可以改变此位置。如：

rabbitmqctl wait /var/run/rabbitmq/pid

此命令会在RabbitMQ node启动后返回.

reset

将RabbitMQ node还原到最初状态.包括从所在群集中删除此node,从管理数据库中删除所有配置数据，如已配置的用户和虚拟主机，以及删除所有持久化消息.

执行reset和force_reset之前，必须停止RabbitMQ application ,如使用stop_app.

示例:

rabbitmqctl reset

此命令会重设RabbitMQ　node.

force_reset

强制RabbitMQ node还原到最初状态.

不同于reset ， force_reset 命令会无条件地重设node,不论当前管理数据库的状态和集群配置是什么. 它只能在数据库或集群配置已损坏的情况下才可使用。

执行reset和force_reset之前，必须停止RabbitMQ application ,如使用stop_app.

示例:

rabbitmqctl force_reset

此命令会重设RabbitMQnode.

rotate_logs {suffix}

指示RabbitMQ node循环日志文件.

RabbitMQ 中间件会将原来日志文件中的内容追加到原始名称和后辍的日志文件中，然后再将原始日志文件内容复制到新创建的日志上。实际上，当前日志内容会移到以此后辍结尾的文件上。当目标文件不存在时，将会进行创建。如果不指定后辍，则不会发生循环，日志文件只是重新打开。示例：

rabbitmqctl rotate_logs .1

此命令指示RabbitMQ node将日志文件的内容追加到新日志文件（文件名由原日志文件名和.1后辍构成）中。如. rabbit@mymachine.log.1 和 rabbit@mymachine-sasl.log.1. 最后, 日志会在原始位置恢复到新文件中.

集群管理

join_cluster {clusternode} [--ram]

clusternode

加入集群的节点.

[--ram]

如果进行了设置，节点将以RAM节点身份加入集群.

指导节点成为集群中的一员. 在加入集群之前，节点会重置,因此在使用此命令时，必须小心. 这个命令要成功,RabbitMQ应用程序必须先停止,如stop_app.

集群节点可以是两种类型: 磁盘节点(Disc Node) 或 内存节点(RAM Node).磁盘节点会在RAM和磁盘中复制数据, 通过冗余可以防止节点失效事件，并可从断电这种全局事件中进行恢复. RAM节点只在RAM中复制数据(除了队列的内容外，还依赖于队列是否是持久化的或者内容对于内存来说是否过大) ，并主要用于可伸缩性. RAM节点只有当管理资源(如，增加/删除队列,交换机,或绑定)的时候才具有更高的性能.一个集群必须至少有一个磁盘节点，通常来说还不止一个.

默认情况下，节点是磁盘节点.如果你想要创建内存节点,需要提供--ram 标志.

在执行cluster命令之后, 无论何时，当前节点上启动的RabbitMQ 应用程序在节点宕机的情况下，会尝试连接集群中的其它节点。

要脱离集群, 必须重设(reset)节点. 你也可以通过forget_cluster_node 命令来远程删除节点.

更多详情，参考集群指南.

例如:

rabbitmqctl join_cluster hare@elena --ram

此命令用于指示RabbitMQ node以ram节点的形式将 hare@elena 加入集群.

cluster_status

按节点类型来分组展示集群中的所有节点，包括当前运行的节点.

例如:

rabbitmqctl cluster_status

此命令会显示集群中的所有节点.

change_cluster_node_type {disc | ram}

修改集群节点的类型. 要成功执行此操作，必须首先停止节点，要将节点转换为RAM节点，则此节点不能是集群中的唯一disc节点。

例如:

rabbitmqctl change_cluster_node_type disc

此命令会将一个RAM节点转换为disc节点.

forget_cluster_node [--offline]

[--offline]

允许节点从脱机节点中删除. 这只在所有节点都脱机且最后一个掉线节点不能再上线的情况下有用，从而防止整个集群从启动。它不能使用在其它情况下，因为这会导致不一致．

远程删除一个集群节点.要删除的节点必须是脱机的, 而在删除节点期间节点必须是在线的，除非使用了--offline 标志.

当使用--offline 标志时，rabbitmqctl不会尝试正常连接节点;相反，它会临时改变节点以作修改.如果节点不能正常启动的话，这是非常有用的.在这种情况下，节点将变成集群元数据的规范源（例如，队列的存在），即使它不是以前的。因此，如果有可能，你应该在最新的节点上使用这个命令来关闭。

例如:

rabbitmqctl -n hare@mcnulty forget_cluster_node rabbit@stringer

此命令会从节点hare@mcnulty中删除rabbit@stringer节点.

rename_cluster_node {oldnode1} {newnode1} [oldnode2] [newnode2 ...]

支持在本地数据库中重命名集群节点.

此子命令会促使rabbitmqctl临时改变节点以作出修改. 因此本地集群必须是停止的，其它节点可以是在线或离线的．

这个子命令接偶数个参数，成对表示节点的旧名称和新名称.你必须指定节点的旧名称和新名称，因为其它停止的节点也可能在同一时间重命名.

同时停止所有节点来重命名也是可以的(在这种情况下，每个节点都必须给出旧名称和新名称)或一次停止一个节点来重命名(在这种情况下，每个节点只需要被告知其名句是如何变化的).

例如:

rabbitmqctl rename_cluster_node rabbit@misshelpful rabbit@cordelia

此命令来将节点名称rabbit@misshelpful 重命名为rabbit@cordelia.

update_cluster_nodes {clusternode}

clusternode

用于咨询具有最新消息的节点.

指示已集群的节点醒来时联系clusternode.这不同于join_cluster ，因为它不会加入任何集群 - 它会检查节点已经以clusternode的形式存在于集群中了．

需要这个命令的动机是当节点离线时，集群可以变化.考虑这样的情况，节点Ａ和节点Ｂ都在集群里边，这里节点Ａ掉线了，Ｃ又和Ｂ集群了，然后Ｂ又离开了集群．当Ａ醒来的时候，它会尝试联系Ｂ，但这会失败，因为Ｂ已经不在集群中了.update_cluster_nodes -n A C 可解决这种场景．

force_boot

确保节点将在下一次启动，即使它不是最后一个关闭的。通常情况下，当你关闭整个RabbitMQ 集群时，你重启的第一个节点应该是最后一个下线的节点，因为它可以看到其它节点所看不到的事情. 但有时这是不可能的:例如，如果整个集群是失去了电力而所有节点都在想它不是最后一个关闭的．

在这种节点掉线情况下，你可以调用rabbitmqctl force_boot ．这就告诉节点下一次无条件的启动节点.在此节点关闭后，集群的任何变化，它都会丢失．

如果最后一个掉线的节点永久丢失了，那么你需要优先使用rabbitmqctl forget_cluster_node --offline, 因为它可以确保在丢失的节点上掌握的镜像队列得到提升。

例如:

rabbitmqctl force_boot

这可以强制节点下次启动时不用等待其它节点．

sync_queue [-p vhost] {queue}

queue

同步队列的名称

指示未同步slaves上的镜像队列自行同步.同步发生时，队列会阻塞(所有出入队列的发布者和消费者都会阻塞).此命令成功执行后，队列必须是镜像的．

注意，未同步队列中的消息被耗尽后，最终也会变成同步. 此命令主要用于未耗尽的队列。

cancel_sync_queue [-p vhost] {queue}

queue

取消同步的队列名称.

指示同步镜像队列停止同步.

purge_queue [-p vhost] {queue}

queue

要清除队列的名称.

清除队列(删除其中的所有消息).

set_cluster_name {name}

设置集群名称. 集群名称在client连接时，会通报给client,也可用于federation和shovel插件记录消息的来源地. 群集名称默认是来自在群集中的第一个节点的主机名，但可以改变。

例如:

rabbitmqctl set_cluster_name london

设置集群名称为"london".

用户管理

注意rabbitmqctl 管理RabbitMQ 内部用户数据库. 任何来自其它认证后端的用户对于rabbitmqctl来说是不可见的.

add_user {username} {password}

username

要创建的用户名称.

password

设置创建用户登录broker的密码.       

rabbitmqctl add_user tonyg changeit

此命令用于指示RabbitMQ broker 创建一个拥有非管理权限的用户，其名称为tonyg， 初始密码为changeit.

delete_user {username}

username

要删除的用户名称.

例如:

rabbitmqctl delete_user tonyg

此命令用于指示RabbitMQ broker删除名为tonyg的用户

change_password {username} {newpassword}

username

要修改密码的用户名称.

newpassword

用户的新密码.

例如:

rabbitmqctl change_password tonyg newpass

此命令用于指定RabbitMQ broker将tonyg 用户的密码修改为newpass.

clear_password {username}

username

要清除密码的用户名称.

例如:

rabbitmqctl clear_password tonyg

此命令会指示RabbitMQ broker清除名为tonyg的用户密码.现在，此用户不能使用密码登录(但可以通过SASL EXTERNAL登录，如果配置了的话).

authenticate_user {username} {password}

username

用户的名称.

password

用户的密码.

例如:

rabbitmqctl authenticate_user tonyg verifyit

此命令会指示RabbitMQ broker以名称为tonyg， 密码为verifyit来进行验证.

set_user_tags {username} {tag ...}

username

要设置tag的用户名称.

tag

用于设置0个，1个或多个tags.任何现有的tags都将被删除.

例如:

rabbitmqctl set_user_tags tonyg administrator

此命令指示RabbitMQ broker用于确保tonyg 是administrator.当通过AMQP来登录时，这没有什么效果,但用户通过其它的途经来登录时，它可用来管理用户,虚拟主机和权限(如使用管理插件).

rabbitmqctl set_user_tags tonyg

此命令会指示RabbitMQ broker删除tonyg上的任何现有的tag.

list_users

列出用户. 每个结果行都包含用户名，其后紧跟用户的tags.

例如:

rabbitmqctl list_users

此命令指示RabbitMQ broker列出所有用户.

访问控制

注意rabbitmqctl 会管理RabbitMQ的内部用户数据库. 无权限的用户将不能使用rabbitmqctl.

add_vhost {vhost}

vhost

要创建虚拟主机名称.

创建一个虚拟主机.

例如:

rabbitmqctl add_vhost test

此命令指示RabbitMQ broker来创建一个新的名为test的虚拟主机.

delete_vhost {vhost}

vhost

要删除的虚拟主机的名称.

删除一个虚拟主机.

删除一个虚拟主机，同时也会删除所有交换机，队列，绑定，用户权限，参数和策略.

例如:

rabbitmqctl delete_vhost test

此命令指示RabbitMQ broker删除名为test的虚拟主机.

list_vhosts [vhostinfoitem ...]

列出所有虚拟主机.

vhostinfoitem 参数用于标识哪些虚拟主机应该包含在结果集中.结果集中的列顺序会匹配参数的顺序.vhostinfoitem 可接受下面的值：

name

虚拟主机的名称.

tracing

是否对虚拟主机启用追踪.

如果没有指定vhostinfoitem 参数，那么会显示虚拟主机名称.

例如：

rabbitmqctl list_vhosts name tracing

此命令用于指示RabbitMQ broker显示所有虚拟主机.

set_permissions [-p vhost] {user} {conf} {write} {read}

vhost

授予用户可访问的虚拟机名称，默认是/.

user

可访问指定虚拟主机的用户名称.

conf

一个用于匹配用户在哪些资源名称上拥有配置权限的正则表达式

write

一个用于匹配用户在哪些资源名称上拥有写权限的正则表达式.

read

一个用于匹配用户在哪些资源名称上拥有读权限的正则表达式.

设置用户权限.

例如:

rabbitmqctl set_permissions -p /myvhost tonyg "^tonyg-.*" ".*" ".*"

此命令表示RabbitMQ broker授予tonyg 用户可访问 /myvhost虚拟主机,并在资源名称以"tonyg-"开头的所有资源上都具有配置权限，并在所有资源上都拥有读写权限。

clear_permissions [-p vhost] {username}

vhost

用于设置禁止用户访问的虚拟主机名称,默认为/.

username

禁止访问特定虚拟主机的用户名称.

设置用户权限.

例如:

rabbitmqctl clear_permissions -p /myvhost tonyg

此命令用于指示RabbitMQ broker禁止tonyg 用户访问/myvhost虚拟主机.

list_permissions [-p vhost]

vhost

用于指定虚拟主机名称，将会列出所有可访问此虚拟主机的所有用户名称和权限.默认为/.

显示虚拟机上权限.

例如:

rabbitmqctl list_permissions -p /myvhost

此命令指示RabbitMQ broker列出所有已授权访问/myvhost 虚拟主机的用户，同时也会列出这些用户能在虚拟主机资源可操作的权限.注意，空字符串表示没有任何授予的权限。

list_user_permissions {username}

username

要显示权限的用户名称.

列出用户权限.

例如:

rabbitmqctl list_user_permissions tonyg

此命令指示RabbitMQ broker列出tonyg可授权访问的所有虚拟主机名称，以及在这些虚拟主机上的操作.

参数管理

RabbitMQ的某些特性(如联合插件)是动态控制的. 每个参数都是与特定虚拟主机相关的组件名称, name和value构成的. 组件名称和name都是字符串,值是Erlang term. 参数可被设置，清除和显示.通常你可以参考文档来了解如何设置参数.

set_parameter [-p vhost] {component_name} {name} {value}

设置一个参数.

component_name

要设置的组件名称.

name

要设置的参数名称.

value

要设置的参数值，作不JSON项。在多数shells中，你更喜欢将其引起来.

例如:

rabbitmqctl set_parameter federation local_username '"guest"'

此命令用于在默认虚拟主机上设置federation 组件的local_username 参数值"guest".

clear_parameter [-p vhost] {component_name} {key}

清除参数.

component_name

要清除参数的组件名称.

name

要清除的参数名称.

例如:

rabbitmqctl clear_parameter federation local_username

此命令用于清除默认虚拟主机上的federation 组件的local_username 参数值.

list_parameters [-p vhost]

列出虚拟主机上的所有参数.

示例:

rabbitmqctl list_parameters

此命令用于列出默认虚拟主机上的所有参数.

策略管理

策略用于在集群范围的基础上用于控制和修改队列和交换机的行为. 策略应用于虚拟主机,由name, pattern, definition或可选的priority组成. 策略可被设置，清除和列举.

set_policy [-p vhost] [--priority priority] [--apply-to apply-to] {name} {pattern} {definition}

设置策略.

name

策略名称.

pattern

正则表达式, 匹配要应用的资源

definition

策略的定义,JSON形式．在大多数shells中，你很可能需要引用这个

priority

策略的整数优先级. 数字越高则优先级越高.默认是０.

apply-to

策略适用的对象类型，其值可为 "queues", "exchanges" 或 "all".默认是"all".

例如:

rabbitmqctl set_policy federate-me "^amq." '{"federation-upstream-set":"all"}'

此命令在默认虚拟主机上设置策略为federate-me，这样内建的交换器将进行联合.

clear_policy [-p vhost] {name}

清除策略.

name

要清除的策略名称.

例如:

rabbitmqctl clear_policy federate-me

此命令来清除默认虚拟主机上的federate-me 策略.

list_policies [-p vhost]

显示虚拟主机上的所有策略.

例如:

rabbitmqctl list_policies

此命令会显示默认虚拟主机上的所有策略.

服务器状态

服务器状态查询查询服务器返回一个结果以制表符分隔的列表. 某些查询(list_queues, list_exchanges, list_bindings, 和 list_consumers) 接受一个可选的vhost 参数. 如果这个参数出现了，那么它必须指定在查询的后面.

list_queues, list_exchanges and list_bindings 命令接受一个可选的虚拟主机参数以显示其结果．默认值为"/".

list_queues [-p vhost] [queueinfoitem ...]

返回队列的详细信息. 如果无-p标志，将显示／虚拟主机上的队列详情．"-p" 标志可用来覆盖此默认值．

queueinfoitem 参数用于指示哪些队列信息项会包含在结果集中.结果集的列顺序将匹配参数的顺序.queueinfoitem 可以是下面列表中的任何值:

name

非ASCII字符的队列名称.

durable

服务器重启后，队列是否能幸存.

auto_delete

不再使用时，是否需要自动删除队列.

arguments

队列参数.

policy

应用到队列上的策略名称.

pid

关联队列的Erlang进程ID.

owner_pid

表示队列专用所有者的代表连接的Erlang进程ID.如果队列是非专用的，此值将为空．

exclusive

True:如果队列是专用的(即有owner_pid), 反之false

exclusive_consumer_pid

表示此channel的专用消费者订阅到此队列的Erlang进程Id. 如果没有专用消费者，则为空．

exclusive_consumer_tag

专用消费者订阅到此队列的Consumer tag.如果没有专用消费者，则为空.

messages_ready

准备分发给客户端的消息数目.

messages_unacknowledged

分发到客户端但尚未应答的消息数目.

messages

准备分发和未应答消息的总和(队列深度).

messages_ready_ram

驻留在ram中messages_ready的消息数目.

messages_unacknowledged_ram

驻留在ram中messages_unacknowledged的消息数目.

messages_ram

驻留在ram中的消息总数.

messages_persistent

队列中持久化消息的数目(对于瞬时队列总是0).

message_bytes

队列中所有消息体的大小总和.这不包括消息属性(包括headers) 或任何开销(overhead)。

message_bytes_ready

类似于message_bytes ，但只统计准备投递给clients的那些消息．

message_bytes_unacknowledged

类似于message_bytes ，但只统计那些已经投递给clients但还未应答的消息

message_bytes_ram

类似于message_bytes ，但只统计那些在RAM中的消息

message_bytes_persistent

类似于message_bytes ，但只统计那些持久化的消息

head_message_timestamp

如果存在，只显示队列中第１个消息的timestamp属性. 消息的时间戳只出现在分页情况下．

disk_reads

从队列启动开如，已从磁盘上读取该队列的消息总次数.

disk_writes

从队列启动开始，已向磁盘队列写消息总次数.

consumers

消费者数目.

consumer_utilisation

时间分数(0.0与1.0之间)，队列可立即向消费者投递消息. 它可以小于1.0，如果消费者受限于网络堵塞或预提取数量.

memory

与队列相关的Erlang进程消耗的内存字节数,包括栈,堆以及内部结构.

slave_pids

如果队列是镜像的，这里给出的是当前slaves的IDs.

synchronised_slave_pids

如果队列是镜像的，当前slaves的IDs是master同步的- 即它们可在无消息丢失的情况下，接管master.

state

队列状态.正常情况下是'running', 但如果队列正在同步也可能是"{syncing, MsgCount}". 处于集群下的节点如果掉线了，队列状态交显示'down' (大多数queueinfoitems 将不可用).

如果没有指定queueinfoitems，那么将显示队列名称和队列深度．

例如:

rabbitmqctl list_queues -p /myvhost messages consumers

此命令显示了/myvhost虚拟主机中每个队列的深度和消费者数目.

list_exchanges [-p vhost] [exchangeinfoitem ...]

返回交换器细节.如果没有指定"-p"选项，将返回 / 虚拟主机的细节.  "-p" 选项可用来覆盖默认虚拟主机.

exchangeinfoitem 参数用来表示哪些交换器信息要包含在结果中. 结果集中列的顺序将与参数顺序保持一致. exchangeinfoitem 可接受下面的列表中任何值：

name

交换器名称.

type

交换器类型(如[direct, topic, headers, fanout]).

durable

当服务器重启时，交换器是否能复活.

auto_delete

当不再使用时，交换器是否需要自动删除.

internal

交换器是否是内部的，即不能由client直接发布.

arguments

交换器参数

policy

应用到交换器上的策略名称.

如果没有指定exchangeinfoitems，那么将会显示交换器类型和类型

例如:

rabbitmqctl list_exchanges -p /myvhost name type

此命令会显示/myvhost中每个交换器的名称和类型.

rabbitmqctl list_bindings -p /myvhost exchange_name queue_name

rabbitmqctl list_connections send_pend port

rabbitmqctl list_channels connection messages_unacknowledged

rabbitmqctl status

rabbitmqctl report > server_report.txt

rabbitmqctl eval 'node().'

杂项

close_connection {connectionpid} {explanation}

connectionpid

要关闭的与连接相关的Erlang进程ID.

explanation

解释字符串.

指示broker关闭与Erlang进程id相关的连接(可通过list_connections 命令查看), 通过为连接客户端传递解释字符串(作为AMQP连接关闭协议的一部分).

例如:

rabbitmqctl close_connection "<rabbit@tanto.4262.0>" "go away"

此命令指示RabbitMQ broker关闭与Erlang 进程id<rabbit@tanto.4262.0>相关联的连接, 同时向客户端传递go away字符串.

trace_on [-p vhost]

vhost

要开启追踪的虚拟主机的名称.

开启追踪.注意，追踪状态不是持久化的; 如果服务器重启，追踪状态将会丢失.

trace_off [-p vhost]

vhost

要停止追踪的虚拟主机名称.

停止追踪.

set_vm_memory_high_watermark {fraction}

fraction

当一个浮点数大于或等于0时，会触发流量控制新内存阈值部分。

set_vm_memory_high_watermark absolute {memory_limit}

memory_limit

流程控制触发的新内存限制, 以字节来表示大于或等于０的整数或以字符串和内存单位来表示(如 512M或1G). 可用的单位是: k, kiB: kibibytes (2^10 bytes) M, MiB: mebibytes (2^20) G, GiB: gibibytes (2^30) kB: kilobytes (10^3) MB: megabytes (10^6) GB: gigabytes (10^9)

set_disk_free_limit {disk_limit}

disk_limit

以整数或字符串单位的可用磁盘下限限制(查看vm_memory_high_watermark), 如 512M or 1G. 一旦可用磁盘空间达到这个限制，就会设置磁盘报警.

set_disk_free_limit mem_relative {fraction}

fraction

相对于整个可用内存的限制，其值为非负浮点数. 当值小于１.０时是很危险的，应该谨慎使用．

要求

要运行ftp4j library，你需要Java 运行时环境v. 1.4+.

安装

将ftp4j JAR文件添加到你应用程序的classpath中, 然后你就可以自动启用ftp4j类的使用了.

Javadocs

可参考ftp4j javadocs.

快速入门

包中的主类是FTPClient (it.sauronsoftware.ftp4j.FTPClient).

创建一个FTPClient 实例：

FTPClient client = new FTPClient();

连接远程FTP服务:

client.connect("ftp.host.com");

如果服务端口不是标准的21端口 (或 FTPS的990端口)，需要使用port参数进行指定:

client.connect("ftp.host.com", port);

如:

client.connect("ftp.host.com", 8021);

然后进行登录流程:

client.login("carlo", "mypassword");

如果没有抛出任何异常的话，那么你就通过远程服务器的认证了.否则，如果验证失败，你将会收到it.sauronsoftware.ftp4j.FTPException异常.

匿名认证，如果被连接服务认可的话， 可通过发送用户名"anonymous" 和任意密码来完成(注意，有些服务器需要e-mail地址来代替密码):

client.login("anonymous", "ftp4j");

使用远程FTP服务来做任何事情，然后再断开连接:

client.disconnect(true);

这会向远程器发送FTP QUIT命令, 以进行一个合法断开流程.如果你只是想中断连接而不想向服务器发送任何通知，那么可以使用:

client.disconnect(false);

使用代理进行连接

客户端通过连接器（一个继承自it.sauronsoftware.ftp4j.FTPConnector的对象）来连接服务器, 它将返回一个已经打开的连接(一个实现了it.sauronsoftware.ftp4j.FTPConnection 接口的对象).这也是为什么ftp4j 可以支持大量代理的原因.

在连接远程服务器前，客户端实例可以使用setConnector() 方法来设置连接器:

client.setConnector(anyConnectorYouWant);

如果没有设置连接器的话，会使用默认的连接器DirectConnector (it.sauronsoftware.ftp4j.connectors.DirectConnector), 它实现了对远程服务器的直接连接，且不会使用代理。

如果你只能通过代理来连接远程服务器, ftp4j包可以让你在下面的连接器中进行选择:

• HTTPTunnelConnector (it.sauronsoftware.ftp4j.connectors.HTTPTunnelConnector)
  它可以通过HTTP代理来进行连接，并支持CONNECT方法.
• FTPProxyConnector (it.sauronsoftware.ftp4j.connectors.FTPProxyConnector)
  它可以通过FTP代理进行连接,支持SITE和OPEN命令风格的苛刻远程主机连接.其它类型的FTP代理,需要username@remotehost 认证，且可以不使用连接器，因为它们对于客户端来说是透明的。
• SOCKS4Connector (it.sauronsoftware.ftp4j.connectors.SOCKS4Connector)
  它可以通过SOCKS 4/4a代理进行连接.
• SOCKS5Connector (it.sauronsoftware.ftp4j.connectors.SOCKS5Connector)
  它可以通过SOCKS 5代理进行连接.

因为ftp4j的连接器架构设计为可插拔的，因此你可以继承FTPConnector 抽象类来构建自己的连接器.

FTPS/FTPES 安全连接

ftp4j包支持FTPS (隐式基于 TLS/SSL的FTP) 和FTPES (显示基于TLS/SSL的FTP).

setSecurity() 方法可用来打开这种特性:

client.setSecurity(FTPClient.SECURITY_FTPS); // 启用 FTPS

client.setSecurity(FTPClient.SECURITY_FTPES); // 启用 FTPES

两个方法都需要在连接远程服务器前调用.

如果安全协议设置成了SECURITY_FTPS, 则connect() 方法默认使用的端口为990.

默认情况下，客户端对象商讨SSL连接会使用javax.net.ssl.SSLSocketFactory.getDefault()作为其套接字工厂.可通过调用client.setSSLSocketFactory()方法来改变默认套接字工厂. 另外一种SSLSocketFactory, 可用来信任远程服务器颁发的证书(谨慎使用):

import it.sauronsoftware.ftp4j.FTPClient;
 import java.security.KeyManagementException; 
import java.security.NoSuchAlgorithmException;
 import java.security.SecureRandom; 
import java.security.cert.X509Certificate;
 import javax.net.ssl.SSLContext;
 import javax.net.ssl.SSLSocketFactory; 
import javax.net.ssl.TrustManager; 
import javax.net.ssl.X509TrustManager;  
// ...  TrustManager[] trustManager = new TrustManager[] { new X509TrustManager() { 	
public X509Certificate[] getAcceptedIssuers() { 		return null; 	
} 	
public void checkClientTrusted(X509Certificate[] certs, String authType) { 	} 	
public void checkServerTrusted(X509Certificate[] certs, String authType) { 	} } }; 
SSLContext sslContext = null;
try { 	sslContext = SSLContext.getInstance("SSL"); 	
sslContext.init(null, trustManager, new SecureRandom()); 
} catch (NoSuchAlgorithmException e) { 	
e.printStackTrace(); 
} catch (KeyManagementException e) { 
	e.printStackTrace(); 
} 
SSLSocketFactory sslSocketFactory = sslContext.getSocketFactory(); 
FTPClient client = new FTPClient(); 
client.setSSLSocketFactory(sslSocketFactory); 
client.setSecurity(FTPClient.SECURITY_FTPS); 
// or client.setSecurity(FTPClient.SECURITY_FTPES);  // ...

浏览远程站点

获取当前目录的的绝对路径（此目录是FTP服务器的home目录）:

String dir = client.currentDirectory();

改变目录:

client.changeDirectory(newPath);

你可以使用绝对路径和相对路径:

client.changeDirectory("/an/absolute/one"); 
client.changeDirectory("relative");

回到父目录:

client.changeDirectoryUp();

重命名文件和目录

要重命名远程文件或目录:

client.rename("oldname", "newname");

移动文件和文件家

rename() 方法也可以用来从当前位置移动文件或目录到其它位置.

在这个例子子，假设在当前工作目录中，你有一个名为"myfile.txt"的文件,然后你想将其移动到子目录"myfolder"中:

client.rename("myfile.txt", "myfolder/myfile.txt");

删除文件

要删除远程文件，需要调用:

client.deleteFile(relativeOrAbsolutePath);

在这个例子中:

client.deleteFile("useless.txt");

创建、删除目录

如果远程服务给你机会的话，你可以在远程站点上创建新目录:

client.createDirectory("newfolder");

你也可以已存在的目录:

client.deleteDirectory(absoluteOrRelativePath);

在这个例子中:

client.deleteDirectory("oldfolder");

请注意，通常情况下，FTP 服务器只允许删除空目录.

列出文件、目录、连接

FTP 协议并不会提供大量支持方法来获取工作目录的完整信息.通常LIST命令会给你想知道的东西，但不辛的是，每个服务器会使用不同样式的响应. 这意味着某些服务器会返回UNIX样式的目录，有些服务器会返回DOS样式的目录,其它的服务器又会使用别的样式.

ftp4j 包可以处理许多的LIST响应格式, 并将它们构建成统一目录内容的结构对象表示.当前ftp4j可以处理:

• UNIX 样式及其变种(如MAC样式)
• DOS 样式
• NetWare 样式
• EPLF
• MLSD

这可以通过使用可插拔的parsers来完成.包it.sauronsoftware.ftp4j.listparsers包含了用于处理上述样式的对象.大多数时间，这些已经够用了。

要列出当前工作目录下的文件或文件夹，可调用:

FTPFile[] list = client.list();

如果你收到了FTPListParseException (it.sauronsoftware.ftp4j.FTPListParseException) 异常，这就意味着服务器对LIST命令返回了不可理解的样式,即它不是上述列出的样式.因此，你可以尝试使用listNames() 方法， 但它并不如list()方法有优势.。为了弥补这种缺陷，你可以构建你自己的LIST响应解析器,以支持你遇到的样式.你可以实现FTPListParser (it.sauronsoftware.ftp4j.FTPListParser) 接口，然后你可以在client的addListParser()方法使用此实现.

FTPFile (it.sauronsoftware.ftp4j.FTPFile) 对象提供了目录内容的表示，包括文件，子目录和连接. 根据服务器的响应，FTPFile对象的某些字段可以是null 的或者是无意义的.请检查javadocs来了解细节.

在list() 方法中你也可以使用文件过滤参数,如：

FTPFile[] list = client.list("*.jpg");

如果连接服务器明确支持MLSD命令, ftp4j会用其来代替基本的LIST命令。MLSD的响应事实更为标准，准确，更易解析.不幸的是，不是所有服务器都支持这个命令，并且有些服务器支持得非常糟糕.基于这些理由，开发者可以控制ftp4j是否应该使用MLSD命令，即通过调用FTPClient对象的setMLSDPolicy()方法. 合法的值:

• FTPClient.MLSD_IF_SUPPORTED
  client只在服务器明确支持MLSD命令时，才使用MLSD命令. 这是ftp4j默认的行为.

• FTPClient.MLSD_ALWAYS
  client总是会使用MLSD命令, 即便服务器没有明确表明支持MLSD命令.

• FTPClient.MLSD_NEVER
  client绝不使用MLSD命令,即便服务器明确表明支持MLSD命令.

例如：

获取文件、目录的最后修改时间

通常情况下FTPFile对象会告诉你条目的最后修改时间, 但正如上面描述的，这依赖于服务器发回的响应.如果你需要最后的修改时间，但你又不能通过list()方法得到，那么可以尝试这样做：

java.util.Date md = client.modifiedDate("filename.ext");

下载、上传文件

下载远程文件最简单的方式是调用download(String, File) 方法：

client.download("remoteFile.ext", new java.io.File("localFile.ext"));

要上传:

client.upload(new java.io.File("localFile.ext"));

要在已有文件中上传追加内容:

client.append(new java.io.File("localFile.ext"));

这些是阻塞式调用:它们会在传输完成后(或failed, 或 aborted时)才返回. 此外同步锁是否由客户端来实施的，因为在每个时间段内只允许有一个常规的FTP通信.在每个时间段内，你可以处理多个传输器，即使用多个FTPClient 对象,每个都与服务器建立一个私有连接.

你可以使用FTPDataTransferListener (it.sauronsoftware.ftp4j.FTPDataTransferListener)对象来监控传输.你可以自己实现一个:

import it.sauronsoftware.ftp4j.FTPDataTransferListener;  
public class MyTransferListener implements FTPDataTransferListener {  	
public void started() { 		
// Transfer started 	
}  	
public void transferred(int length) { 		
// Yet other length bytes has been transferred since the last time this 		
// method was called 	
}  	
public void completed() { 		
// Transfer completed 	
}  	
public void aborted() { 		
// Transfer aborted 	
}  	
public void failed() { 		
// Transfer failed 	
}  
}

现在像下面这样来下载或上传:

client.download("remoteFile.ext", new java.io.File("localFile.ext"), new MyTransferListener());

client.upload(new java.io.File("localFile.ext"), new MyTransferListener());

client.append(new java.io.File("localFile.ext"), new MyTransferListener());

当client处理下载或上传时，传输器可以被同一个FTPClient对象的不同线程通过调用 abortCurrentDataTransfer() 方法aborted. 此方法还需要一个boolean参数:true表示执行合法的abort过程(即向服务器发送ABOR命令), false表示实然关闭传输器，而不向服务器发送通知:

client.abortCurrentDataTransfer(true); // Sends ABOR

client.abortCurrentDataTransfer(false); // Breaks abruptly

需要注意的是，list()和listNames() 方法暗中包含了数据传输器，因abortCurrentDataTransfer() 方法也可以用来中断其list过程.

当数据传输器在download(), upload(), append(), list() and listNames() 方法中中断时，将会抛出FTPAbortedException (it.sauronsoftware.ftp4j.FTPAbortedException).

下载和上传操作可通过restartAt 参数来重新恢复:

client.download("remoteFile.ext", new java.io.File("localFile.ext"), 1056);

此操作会文件的第1056个字节处继续执行下载操作。第一个传输的字节将是第1057个.

其它 download(), upload() 和append()方法的变种可以让你使用流来替代java.io.File对象.因此你可以在数据库，网络连接或其它流上来传输数据。

Active 、 passive 数据传输模式

客户端和服务器之间的数据传输通道是通过单独的网络连接来建立的. 在传输通道建立期间，服务器可以是active或passive的. 服务器激活数据传输时，工作如下：

1. client向服务器发送其IP地址和端口号.
2. client向服务器发送数据传输请求，并在之前发送的端口上启动监听.
3. 服务器使用客户端提供的地址和端口来连接客房端.
4. 数据传输将在新建立的通道中进行.

active模式需要你的client能够收到来自服务器的连接.如果你的client处于防火墙， 代理或这两者混合之后，那么大部分时间都会出现问题，因为它不能收到来外界的连接. 下面是passive数据传输模式：

1. client要求服务器准备好一个passive数据传输.
2. 服务器使用其IP地址和端口号进行响应.
3. client请求传输和连接.
4. 数据传输将在新建立的通道中进行.

在passive模式中，客户端连接不要求能收到服务器的连接请求.

在ftp4j中，你可以使用下面的调用来切换active、passive模式:

client.setPassive(false); // Active mode

client.setPassive(true); // Passive mode

ftp4j client passive 标志的默认值为true: 如果你没有调用setPassive(false) ，你的客户端在每次传输前，都会向服务器请求passive模式.

当使用 passive文件传输时，服务器会提供一个 IP地址和一个端口号.作为FTP规范的client,需要使用给定的主机号和端口进行连接.在商业环境中，这种行为可能会经常带来问题，因为NAT配置可能会阻止对IP地址的连接.这就是为什么FTP clients通常会忽略服务器返回的任何IP地址，进而在通信线路中使用同样的主机来连接服务器.ftp4j的行为依赖于服务器因素:

• 每个FTPConnector 都有其默认行为.大部分连接器都会忽略服务器返回的IP地址。目前，默认使用返回地址的连接器是FTPProxyConnector.
• 连接器的行为可通过定义名为ftp4j.passiveDataTransfer.useSuggestedAddress的系统属性来覆盖。如果设置为"true", "yes" 或"1",所有连接器都会使用服务器返回的地址，反之，如果将其设置为"false", "no" or "0", 所有服务器都不会使用返回的地址.
• 最后,连接器的默认行为和全局设置都可以在任何连接器实例中进行覆盖。你可通过获取客房端连接器，并调用其setUseSuggestedAddressForDataConnections() 方法来达到目的.

在active传输模式中，可以设置下面的系统属性:

• ftp4j.activeDataTransfer.hostAddress
  主机地址.当服务器请求执行与客户端连接时，client会跳转到给定地址的服务器. 此值应该是一个有效的IPv4地址，如：178.12.34.167. 如果没有提供此值，客户端会自动解析系统地址.但如果client运行于LAN中，为了激活数据传输，将会使用带端口转发的路由器来连接外部服务器,那么自动探测到的地址可能不是正确的. 当系统有多个网络接口时，也可能发生这种情况.通常使用系统属性，可以解决这种问题

• ftp4j.activeDataTransfer.portRange
  连接端口范围. client会在其中挑选一个来进行数据传输.此值 必须是start-stop 形式 ，如6000-7000 表示client只会在给定范围内挑选一个端口来连接服务器.默认情况下没有指定端口范围:这表示client会挑选任何一个可用的端口.

• ftp4j.activeDataTransfer.acceptTimeout
  以毫秒为单位的连接超时时间. 如果服务器不能在给定超时时间内连接client，传输会因FTPDataTransferException异常而中断.0值表示永不超时。默认值30000 (即30秒).

要设置系统属性，你可以:

• 用一个或多个 -Dproperty=value参数来启动JVM.如:

  java -Dftp4j.activeDataTransfer.hostAddress=178.12.34.167      -Dftp4j.activeDataTransfer.portRange=6000-7000      -Dftp4j.activeDataTransfer.acceptTimeout=5000 MyClass

• 直接在代码中设置系统属性，如:

  System.setProperty("ftp4j.activeDataTransfer.hostAddress", "178.12.34.167"); 
  System.setProperty("ftp4j.activeDataTransfer.portRange", "6000-7000"); 
  System.setProperty("ftp4j.activeDataTransfer.acceptTimeout", "5000");

二进制和文本数据传输类型

数据传输的另一个核心概念是binary 和textual 类型.当传传输的文件是二进制文件时，它将视为二进制流，服务器会按原样存储。而文本数据传输会将传输的文件视为字符流,会进行字符集转换. 假设你的client正运行Windows平台上，而服务器运行UNIX上,它们的默认字符集通常是不同的. client以文本类型来发送文件时，client会假设文件是按机器标准字符集来编码的，因此在发送前，它会解码每个字符并将其编码为 中间字符集. 服务器收到流后，在存储前，会解码中间字符集，并将其编码为机器默认的字符集.字节虽然被改变了，但内容是相同的。

你可以调用下面的方法选择你传输的类型:

client.setType(FTPClient.TYPE_TEXTUAL);

client.setType(FTPClient.TYPE_BINARY);

client.setType(FTPClient.TYPE_AUTO);

默认的TYPE_AUTO常量 ,会让client自动来挑选类型:如果文件的扩展名是client能被识别的文本类型标记，那么它会选择文本传输器来执行. 文件扩展名是通过FTPTextualExtensionRecognizer (it.sauronsoftware.ftp4j.FTPTextualExtensionRecognizer) 实例来识别的. 默认扩展识别器是it.sauronsoftware.ftp4j.recognizers.DefaultTextualExtensionRecognizer, 会将下面的视为文本类型:

abc acgi aip asm asp c c cc cc com conf cpp
csh css cxx def el etx f f f77 f90 f90 flx
for for g h h hh hh hlb htc htm html htmls
htt htx idc jav jav java java js ksh list
log lsp lst lsx m m mar mcf p pas php pl pl
pm py rexx rt rt rtf rtx s scm scm sdml sgm
sgm sgml sgml sh shtml shtml spc ssi talk
tcl tcsh text tsv txt uil uni unis uri uris
uu uue vcs wml wmls wsc xml zsh

你可通过实现FTPTextualExtensionRecognizer 接口来实现你自己的识别器，但你可以更喜欢使用 class ParametricTextualExtensionRecognizer(it.sauronsoftware.ftp4j.recognizers.ParametricTextualExtensionRecognizer)便利类.
无论如何，都不要忘记将你的识别器设置在client中:

client.setTextualExtensionRecognizer(myRecognizer);

数据传输压缩

有些服务器支持数据传输压缩特性－MODE Z. 在传输大文件时，此特性可以节省带宽.一旦client连上服务器并通过认证,就可通过调用下面的方法来检查是否支持压缩：

如果服务器端支持压缩,就可通过下面的调用来启用压缩:

在此调用之后，后续的数据传输(下载，上传，列举操作）都被将压缩以节省带宽.

数据传输压缩可通过下面的调用来禁用:

也可以检查标记值:

请注意：压缩数据传输只当压缩支持且启用了的情况下才会发生.

默认情况下，压缩是禁用的，即便是服务器支持压缩. 如果有需要,可以显示地打开.

不做任何事（NOOPing the server）

假设你的client什么事情都不做，因为在等待用户输入. 通常情况下， FTP服务器会自动断开非活跃客户端. 为了避免超时，你可以发送NOOP命令.
此命令不会做任何事情，但它会向服务器说明：客户端仍然还活着，请重围超时计数器.调用如下:

client.noop();

当非活跃超时发生时，客户端也可以自动发送NOOPs. 默认情况下，此特性是禁用的。它可以在 setAutoNoopTimeout() 方法中设置超时时间时启用,并提供一个毫秒为单位的值.如:

client.setAutoNoopTimeout(30000);

使用此值，client会在30秒后发送一个NOOP命令.

NOOP超时可通过设置小于等于0的值来禁用:

client.setAutoNoopTimeout(0);

网站特殊的自定义命令

你可以像下面这样来发送站点特殊命令：

FTPReply reply = client.sendSiteCommand("YOUR COMMAND");

你也可以发送自定义命令:

FTPReply reply = client.sendCustomCommand("YOUR COMMAND");

sendSiteCommand() 和 sendCustomCommand() 都会返回一个FTPReply (it.sauronsoftware.ftp4j.FTPReply)对象.使用此对象，你可以检查服务器的响应代码和消息. 
FTPCodes (it.sauronsoftware.ftp4j.FTPCodes) 接口报告了一些通用的FTP响应代码,因此你可以使用这些包中的某个来进行匹配.

异常处理

ftp4j 包定义了五种类型的异常:

• FTPException (it.sauronsoftware.ftp4.FTPException) 
  依赖于方法，这会报告抛出了一个FTP故障.你可以检查报告的错误码，使用FTPCodes 常量来获取故障原因的详细信息.
• FTPIllegalReplyException (it.sauronsoftware.ftp4.FTPIllegalReplyException)
  这表示远程服务器使用非法方式进行了应答, 这与FTP是不兼容的. 这应该是非常罕见的.
• FTPListParseException (it.sauronsoftware.ftp4.FTPListParseException)
  这通常发生在list()方法，如果服务器发回的响应不能被客户端包中现有解析器进行的话，就会抛出此种异常
• FTPDataTransferException (it.sauronsoftware.ftp4.FTPDataTransferException)
  当数据传输 (download, upload, but also list and listNames) 因网络连接错误失败时，就会抛出此种异常.
• FTPAbortedException (it.sauronsoftware.ftp4.FTPAbortedException)
  当数据传输 (download, upload, but also list and listNames) 因客户端发出中断请求失败时，抛出的异常.