| 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:
| Update | ::= | ADD | INSERT | REPLACE | DELETE |
| Content-type | ::= | <mime-type as defined in table 11.9> |
| Content-length | ::= | <length of the posted data> |
| Type | ::= | <object type as defined in table 11.9> |
| Resource | ::= | <standard name of a resource as defined in table 11.2> |
| ID | ::= | resource-id |
| Order | ::= | 1*5DIGIT |
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
| UID | ::= | <The unique ID assigned to the uploaded object by the server.> |
| ActivationDate | ::= | date [; reason] |
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:
| Type | : | MULTIPART |
| Content-type | : | multipart/parallel; boundary=boundary |
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:
| Resource | |
| ObjectType | |
| ResourceEntity | |
| ObjectId | |
| UID | |
| Type | |
| ReplyCode | |
| ActivationDate | Empty if ReplyCode != 0 or activated immediately |
| Reason | Empty if ReplyCode != 0 or activated immediately |
Table X.1 Standard Reply Codes
| 0 | Upload successful |
| 20400 | Unknown resource |
| 20401 | Invalid update type |
| 20402 | Invalid identifier |
| 20403 | No object found (for DELETE) |
| 20406 | Unsupported MIME type |
| 20407 | Unauthorized |
| 20408 | Refused: object does not meet business rules |
| 20410 | Server does not support Multipart Type |
| 20411 | Timeout |
| 20412 | Too many outstanding requests |
| 20413 | Miscelanous error |
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.
| ObjectID | Unique ID within the Object Resource |
| ResourceName | Standard name of the resource this object belongs to |
| ResourceID | Value of the Key Field identifying a record within the resource described by ResourceName |
| Order | Ordinal number of this object within all obects belonging to the record identified by ResourceName andResourceID |
| IsDefault | 1 if this object is the default one (sent when 0 was requsted) |
| MimeType | MimeType of the object |
| Description | Description of the object |
| FileSize | Size, in bytes, of the object |
| WidthPix | Width of an image, in pixels |
| HeightPix | Height of an image, in pixels |
| Length | Length of a movie, in seconds |
| WidthInch | Width of an image, in inches |
| HeightInch | Height of an image, in inches |
| Ö | Other well-known fields will be defined later |
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. |