Section X: PostObject Transaction

The PostObject transaction is used to upload structured informaation related to known system entities. This transaction supports two formats: a single-file format, allowing the client to send one file as a MIME type, and a multipart format, allowing the client to send multiple files along with more information. If the server exposes this transaction, it MUST support at least the single-file format.

Before a client tries to upload an object, it SHOULD check for the presence of the Object resource and its UPLOAD update type. If that update exists, the clent SHOULD check all its validation expressions, supplying file characteristics as values of the known fields of the Object table. [See the Object Resource chapter for more info].

X.1 Single-file PostObject transaction

The request MUST be sent using POST method.

X.1.1 Required client request header fields

In addition to the Required client request header fields specified in section 3.4, the header of any single-file message MUST contain the following fields:

ID is a value from the KeyField of the Resource for which the object is to be uploaded.

Order is the order number of an object within the ID. It corresponds to the Object-ID argument for the GetObject transaction. In case of DELETE, the message body is empty. In all other cases, the body of the request is the file being uploaded.

In case of ADD, the uploaded file becomes a new ‘Type’ object for the ‘resource-entity’ record. If obects are ordered, the newly added one becomes the last one.

In case of INSERT and REPLACE, the order number must be used (this was named object-id in previous versions of the RETS specs). The uploaded object assumes appropriate position in the list of existing objects, replacing the original object in case of REPLACE, or shifting all objects numbered “order” and higher by one place. If no object existed at this order, the uploaded object becomes the last one in the list.

In case of DELETE, the order number MUST be used, and MUST be either an order number of an existing object, or asterisk(*) if all objects of given type for given resource-id should be deleted.

X.1.2 Optional client request header fields

Description

FileName

The Description is kept for backward compatibility reasons. However, servers which want to keep additional data with objects, SHOULD expose an Object resource, and clients SHOULD update a table in that resource to set/modify description or other data of an object.

The FileName MAY be used to pass the name of the file being uploaded, as it apears on the client computer.

X.1.3 Server Reply

Server replies the standard RETS way, with Reply code from the table X.1.

Optional Server response arguments

If the object is not immediately accessible, the server SHOULD send a date when it is supposed to be activated. The server MAY also send a description of the reason why the activation is delayed.

The reply code MUST be zero (success) even if the object is accepted for testing only. However, if the server knows in the time of the transaction that the object will be refused, it should reply with an error reply code (eg. 20408).

X.2 Multiple-file PostObject Transaction

Required client request header fields

In addition to the Required client request header fields specified in section 3.4, the header of any multiple-file message MUST contain the following fields:

X.2.2 Client request body

In multiple-file PostObject transaction, the body of the message is multipart as described in 5.11 for GetObject responses. Each part consists of headers, which include header fields described in the single-part PostObject transaction description (X.1.1 and X.1.2), and a body containing the file to be uploaded.

X.2.3 Server response body format

<RETS ReplyCode=ReplyCode ReplyText=ReplyText>
<COLUMNS>columns</COLUMNS>
1*(<DATA>data</DATA>)
</RETS>

Server MUST return one line of data for every requested file. The data contain following items:

Table X.1 Standard Reply Codes

Y.1 Object Resource

The server MAY expose a resource named Object. If it does, this resource MUST complain with the following description.

Any class within the Object resource MUST have Standard name of one of the Object types exposed in the Object metadata. Some types of objects MAY not be classes in the Object resource.

Any class within the Object resource MAY expose well-known fields from the following table. Any class MUST expose fields shown in bold.

Searching for objects: The Object resource is searchable as any other resource.

Updating objects: The server MAY expose updates for the Object resource. However, the data MUST stay consistent with the object files, so eg. the system must not allow changing the WidthPix field unless it is able to crop the underlying image file.

The system MUST NOT expose an ADD update for the Object resource, since objects will be added via the PostObject transaction. The system MAY expose DELETE update, which will have similar effect as PostObject transaction with the Type=DELETE (namely, it will remove a record from the Object table AND delete the object file).

The system MAY expose a UPLOAD update. Clients SHOULD NOT use this update explicitely; if they do, server MUST refuse it. This update type is used to hook up validation expressions and update help to the PostObject transaction. If this upload exists, both client and server SHOULD use it to check data sent via the PostObject transaction. The UPLOAD update’s validation expressions may put constraints on any field defined in the Object table, thus specifying acceptable file characteristics.