Ice手册:Ice服务 - IcePatch2

IcePatch2 is the Ice solution for securereplication of a directory tree.

icePatch2 是一个容易配置和使用的高效的文件补丁服务。它包括以下组件：

1.      IcePatch 服务器(icepatch2server)

2.      一个基于文本的IcePatch客户端(icepatch2client)

3.      一个基于文本的压缩和计算校验和的工具(icepatch2calc)

4.      一个用于开发客户化IcePatch2客户端的sliceAPI和C++开发库。

As with all Ice services, IcePatch2 can beconfigured to use Ice facilities such as Glacier2 for firewall support andIceSSL for secure communication.

IcePatch服务能够将一个文件系统目录（the data directory）包括其中的文件和子目录分发到各个客户端。使用icepatch2calc命令压缩这些文件和产生一个包含每个文件的校验和的索引。服务器传送压缩文件给客户端，这些文件将会在客户端恢复为数据目录和内容，修补任何被在之前运行的被修改过的文件。

IcePatch2 is efficient: transfer rates forfiles are comparable to what you would get using ftp.

 

IcePatch2 addresses a requirement common toboth development and deployment scenarios: the safe, secure, and efficientreplication of a directory tree. The IcePatch2 server is easy to configure andefficient. For simple uses, IcePatch2 provides a client that can be used topatch directory hierarchies from the command line. With the C++ utilitylibrary, you can also create custom patch clients if you require betterintegration of the client with your application.

Using icepatch2calc

准备文件

假设我们在服务器数据目录下拥有如下图的文件目录结构。

An_example_data_directory

假设名字为emptyFile的文件是空文件，其他的都是包含数据的文件。

 

服务器要准备传输这些目录，你必须首先运行命令icepatch2calc。

$ icepatch2calc .

运行完这个命令，数据目录的内容将会变成如下图所示。

Contents_of_data_directory_after_running_icepatch2calc

注意到icepatch2calc将数据目录中的文件压缩（除了emptyfile，它没有被压缩）。同时注意到icepatch2calc创建了附加的文件--icepatch2.sum.这个文件的内容如下所示：

3a52ce780950d4d969792a2559cd519d7ee8c727-1

/binbd362140a3074eb3edb5e4657561e029092c3d91 -1

/bin/hello77b11db586a1f20aab8553284241bb3cd532b3d5 70

/emptyFile082c37fc2641db68d195df83844168f8a464eada 0

/nonEmptyFileaec7301c408e6ce184ae5a34e0ea46e0f0563746 72

校验和文件中的内容包含了每个没有被压缩的文件名或者目录名，校验和，和字节数。目录的字节数为-1，没有被压缩的文件字节数为0，被压缩的文件字节数为压缩后文件大小。每一行是按路径名字母顺序来排序。

    如果你从数据目录中添加，删除，修改了文件，你必须停止服务器，重新运行icepatch2calc来更新IcePatch2.sum这个校验和文件，然后重启服务器。

icepatch2calc 命令行选项

 icepatch2calc 使用如下句法

icepatch2calc [option] data_dir [file...]

    一般来说，你会简单指定一个数据目录来运行icepatch2calc，这样程序就会在数据目录中压缩所有的文件，和在创建的校验和文件为每一个文件或者目录创建一条记录。

    你同样可以在命令行中指定文件和目录，在这种情况下，icepatch2calc仅为指定的文件或者目录压缩和计算校验和。这对你拥有非常大的文件树而只对其中做了很小一部分更新时非常有用(In this case, the program does not traverse the entire datadirectory and, therefore, will also not detect any updated, added, or deletedfiles, except in any of the specified directories.)。你指定的文件名或者目录名必须是相对于数据目录，如果你使用绝对路径，路径名必须使用数据目录作为前缀。

    命令支持以下选项：

1.      --h,  --help

2.      --v,  --version

3.      --z,  --compress

   通常，icepatch2calc仅仅在文件没有压缩版本存在或者文件压缩版本的修改时间早于没有没有压缩版本才扫描数据目录和压缩一个文件。如果你指定--z，这个工组将会重新扫描和压缩整个数据目录而不管文件的时间戳，这对怀疑数据目录的时间戳可能出错的情况下很有用。

4.      --Z,  --no-compress

   这个选项允许你创建一个客户端校验和文件。不要使用这个选项为服务器创建校验和文件。这个选项是为创建客户端 IcePatch.sum文件，用来在分发版本中更新软件。

5.      --i,  --case-insensitive

   这个选项仅对禁用文件名不同，

6.      --V,  --verbose

   这个选项将输出每个被压缩和计算校验和的消息

 

运行服务器Running the IcePatch2 Server

Starting icepatch2server

一旦你在数据目录上行了icepatch2calc命令，你可以启动icepatch2server了。

$ icepatch2server .

服务器期待数据目录作为唯一的命令行参数，如果你忽略指定目录，服务器将使用配置文件中IcePatch2.directory属性值来决定使用哪个目录。

你必须也指定服务器侦听的端点，设置IcePatch2.Endpoints属性。

 

icepatch2server Command Line Options

Regardless of whether you run the serverunder Windows or a Unix-like operating system, it provides the followingoptions:

•-h, --help

 Displays a help message.

•-v, --version

 Displays a version number.

 

Additional command line options aresupported, including those that allow the server to run as a Windows service orUnix daemon.

运行客户端Running the IcePatch2 Client

Patching with icepatch2client

    一旦服务器运行起来，你可以使用icepatch2client命令来从服务器维护的数据目录中取得一份拷贝。

例如：

$ icepatch2client--IcePatch2Client.Proxy="IcePatch2Server/server:tcp -h somehost.com -p10000" .

    客户端期望数据目录作为它唯一的命令行参数。像服务器一样，你必须指定IcePatch2.Endpints属性，使得客户端知道去哪里找服务器。

    如果你之前没有运行过客户端，他会问你是否想彻底更新，你必须回答yes（或者使用-t参数运行客户端），客户端将会执行如下步骤：

1.      它遍历本地数据目录，创建本地IcePatch2.sum校验和文件。

2.      它从服务器获得相关的校验和文件队列，与本地的校验和文件队列比较。

1)        '客户端删除在本地校验和文件出现而没有在服务器检验和文件出现的文件。

2)        '客户端恢复在本地校验和文件没有出现而存在于服务器校验和文件中的文件。

3)        '客户端为每个客户端与服务端不相同文件修补。

    客户端完成后，客户端内容与服务器内容相同，但是客户端只创建了没有压缩的文件，而服务端存储了压缩版本，这样简单的避免在客户端每次恢复时重复压缩文件

On the initial patch, any files that existin the client's data directory are deleted or, if they have the same name as afile on the server, will be overwritten with the corresponding file as itexists on the server.

 

使用icepatch2client进行局部更新

    一旦你已经运行了客户端，在客户端数据目录下就包含了IcePatch2.sum文件，它体现了数据目录中的内容。如果你第二次运行icepatch2client，那么程序就会拿着客户端的IcePatch2.sum与服务器中的比较它们中每一行记录。如果文件内容不一样，客户端就会更新对应的文件，下载服务器有而客户端没有的文件，删掉服务器没有而客户端有的文件。  如果你编辑一个客户端文件，更改了其中的内容，icepatch2client不会意识到文件的改变，因此不会去同步服务器文件内容。这是因为客户端不会自动为一个文件重新计算校验和来判断当前Icepatch2.sum中的存储的校验和是否与实际内容的校验和相符。

 

   同样，如果你随意在客户端创建了一个文件，但是这个文件既没有在客户端也没有在服务器端的校验和文件中记录，那么这个文件将简单的放在一边。换句话说，一个正常的修补操作是依据在客户端和服务器的校验和发生改变，而不是依据文件系统去检查文件内容的发生变化。

 

    如果你创建了与发布包无关的本地文件或者你在本地修改了一些文件，而且你想这些修改能在服务器端体现，你必须运行使用命令行选项-t来彻底修补。这样将会强制客户端遍历本地数据目录和为每个文件重新计算校验和，然后与服务器端比较这些校验和。结果，如果你编辑本地一个文件使之与服务器不同，那么它会被强制更新，同样，你在客户端新增一个文件，如果服务器端没有的话，它将被删除。也就是说在客户端任何修改都不会对服务器有影响，可以通过完全更新干掉客户端的不同步。

阻止删除本地文件Preventing Deletion of Local Files

    默认情况下，如果服务器没有的文件，而在客户端有，那么完全更新时文件将会删掉。如果你不想这样，你可以将IcePatch2.Remove属性设值为0（默认为1），这样客户端文件就不会被删除了，无论是一般更新还是完全更新。

媒介安装的补丁分发

    假设你分发你的程序采用DVD碟泉庄客户端。DVD可能是过期的，安装后安装脚本需要执行一个补丁程序，以更新到最新版本。脚本可以调用一个详细的补丁程序完成，但是对于大文件集来说，这种办法代价较高，他需要重新计算分发报的每个文件的校验和值。

 

    要避免这个问题，你可以将所有文件放置到一个目录，然后在这个目录上执行icepatch2calc -Z。使用-Z选项，icepatch2calc创建一个校验和文件，其中每个文件的有正确的校验和值，但文件的大小为0。也就是说，-Z选项忽略了压缩文件（和相关的文件）。一旦你使用这种创建了新的IcePatch2.sum的文件，你可以将它们包含到DVD碟的文件中。

To avoid this cost, you can place all thefiles for the distribution into a directory on the server and run icepatch2calc-Z on that directory. With the -Z option, icepatch2calc creates a checksum filewith the correct checksums, but with a file size of 0 for each file, that is,the -Z option omits compressing the files (and the considerable cost associatedwith that). Once you have created the new IcePatch2.sum file in this way, youcan include it on the DVD and install it on the client along with all the otherfiles.

 

    这个保证了客户端校验和文件和实际安装的文件是一致的，因此，足够安装脚本去生成一个正常的patch去更新分发程序，从而避免了重新计算每个文件的校验和的代价。

This guarantees that the checksum file onthe client is in agreement with the actual files that were just installed and,therefore, it is sufficient for the install script to do a normal patch toupdate the distribution and so avoid the cost of recomputing the checksum forevery file.

Setting Transfer Size for icepatch2client

You can set the IcePatch2Client.ChunkSize property to control the number of bytes that the client fetches perrequest. The default value is 100 kilobytes.

icepatch2client Command Line Options

The client supports the following options:

l  -h, --help

 Displays a help message.

l  -v, --version

 Displays a version number.

l  -t, --thorough

 Do athorough patch, recomputing all checksums.

IcePatch2 Object Identities

    一个IcePatch2服务托管理在一个公开对象，该对象实现IcePatch2::FileServer接口，并有个默认的标识IcePatch2/server。如果程序需要使用多个IcePatch2服务，好主意就是给公开对象配置一个唯一的标识，使用不同的IcePatch2.InstanceName属性值，如下例所示

$ icepatch2server --IcePatch2.InstanceName=PublicFiles ...

这个属性改变了服务器对象的标识的目录，标识变成PublicFiles/server。

IcePatch2客户端实用工具库IcePatch2 Client Utility Library

    IcePatch2包括了一对C++类，简化了你编写patch客户端的任务，接下来的MFC的例子演示了如何去使用这些类。你可在Ice安装的目录下demo/IcePatch2/MFC的目录找到这个例子。

    本节接下来开始讨论这些类。为了在定制的patch客户端使用这些类，你需要引入头文件IcePatch2/ClientUtil.h并link到Ice库。

执行patch

Patcher类封装了所有客户端需要的patching逻辑。

C++                                                                 

namespace IcePatch2 {

class Patcher :...{

public:

 

   Patcher(const Ice::CommunicatorPtr& communicator,

           constPatcherFeedbackPtr& feedback);

 

   Patcher(const FileServerPrx& server,

           const PatcherFeedbackPtr&feedback,

           const std::string& dataDir,bool thorough,

           Ice::Int chunkSize, Ice::Int remove);

 

    bool prepare();

 

    bool patch(const std::string& dir);

 

    void finish();

};

typedef IceUtil::Handle<Patcher> PatcherPtr;

}

 

构造一个补丁包

    构造器提供了两种方法配置一个Patcher实例。第一个方式获取下列属性，在通信器提供的IcePatch2Client的配置属性中：

l  IcePatch2Client.Proxy

l  IcePatch2Client.Directory

l  IcePatch2Client.Thorough

l  IcePatch2Client.ChunkSize

l  IcePatch2Client.Remove

    第二个通过传递参数设置对应每个属性的值。

 

    两种方式都接收一个PatcherFeedback对象，以监控patch的进度。

Executing the Patch

Patcher实例提供3个方法执行patch，也体现了patching的3个阶段。

1.  boolprepare()

    第一阶段：读取checksum文件内容（如果有的话），获取文件信息从服务器，检查本地需要更新的文件列表。PatcherFeedback对象可以得到每个本地任务的通知，并可选择随时终止patch。准备工作完成返回true，否则PatcherFeedback对象终止了patch时返回false。如果发生错误，prepare将引发一个带有std::string类型的问题描述的异常到客户端。

2.  boolpatch(const std::string& dir)

    第二阶段，更新本地数据目录中的文件。如果数据目录是空字符串或“.”patch将更新整个目录。否则patch只更细那些dir指定的目录中的文件。对每fe 要更新的文件，Patcher从服务器上下载压缩数据并写到本地数据目录中。PatcherFeedback对象可以得到每个文件的进度通知，就像prepare阶段一样，可终止patch，如果必要的话。所有不定完成返回true，否则PatcherFeedback对象终止了patch时返回false。如果发生错误，patch将引发一个带有std::string类型的问题描述的异常到客户端。

3.  voidfinish()

    最后的阶段：写客户端的checksum文件。如果发生错误，finish将引发一个带有std::string类型的问题描述的异常到客户端。

下面的代码演示了一个简单的patch客户端：

C++                                                                 

#include <IcePatch2/ClientUtil.h>

...

Ice::CommunicatorPtrcommunicator =...;

IcePatch2::PatcherFeedbackPtrfeedback =newMyPatcherFeedbackI;

IcePatch2::PatcherPtr patcher=

    new IcePatch2::Patcher(communicator, feedback);

 

try{

    bool aborted =!patcher->prepare();

    if(!aborted)

       aborted =!patcher->patch("");

    if(!aborted)

       patcher->finish();

    if(aborted)

       cerr <<"Patch aborted"<< endl;

}catch(const string& reason){

   cerr <<"Patch error: "<< reason << endl;

}

For a moresophisticated example, see demo/IcePatch2/MFC in your Icedistribution.

 

监控Patch进度

The class PatcherFeedback is an abstract base class that allows you to monitor the progressof a Patcher object. The class declaration is shown below:

C++                                                                 

namespace IcePatch2 {

class PatcherFeedback :...{

public:

 

    virtualbool noFileSummary(const std::string& reason)=0;

 

    virtualbool checksumStart()=0;

    virtualbool checksumProgress(const std::string& path)=0;

    virtualbool checksumEnd()=0;

 

    virtualbool fileListStart()=0;

    virtualbool fileListProgress(Ice::Int percent)=0;

    virtualbool fileListEnd()=0;

 

    virtualbool patchStart(

       const std::string& path, Ice::Long size,

       Ice::Long updated, Ice::Long total)=0;

    virtualbool patchProgress(

       Ice::Long pos, Ice::Long size,

       Ice::Long updated, Ice::Long total)=0;

    virtualbool patchEnd()=0;

};

typedef IceUtil::Handle<PatcherFeedback>PatcherFeedbackPtr;

}

每个方法都返回一个布尔值：

l true allows Patcher tocontinue

l false directs Patcher to abort the patch.

方法说明：

l bool noFileSummary(const std::string&reason)

    在找不到本地checksum文件时调用。返回true引发一个thorough patch,如果返回false导致Patcher::prepare返回false.

l bool checksumStart()

bool checksumProgress(const std::string& path)

bool checksumEnd()

    Patcher::prepare在a thoroughpatch期间调用. 方法checksumProgress在每个文件checksum 被计算后调用.

l bool fileListStart()

bool fileListProgress(Ice::Int percent)

bool fileListEnd()

Patcher::prepare在收集更新文件列表时调用.fileListProgress方法的参数percent表明收集过程进度。

l bool patchStart(const std::string&path, Ice::Long size, Ice::Long updated, Ice::Long total)

bool patchProgress(Ice::Long pos, Ice::Long size, Ice::Long updated,Ice::Long total)

bool patchEnd()

对每个组要更新的文件Patcher::patch调用patchStart表明patch开始，patchProgress在每个chunk下载并写到本地后调用，patchEnd表示文件patch结束。

参数 path 提供了文件的路径名，参数 size 提供了文件的压缩后的大小。 pos 参数表示写入的累积字节数， The pos argumentdenotes the number of bytes written so far, while updated and total representthe cumulative number of bytes updated so far and the total number of bytes tobe updated, respectively, of the entire patch operation.