Tickets and Receipts

The FCS uses tickets and receipts as container vehicles to describe and move metadata.

For debugging purposes, FCS tickets do not contain serialized objects. Tickets define:

  • The file operation. The operation for the FCS to perform for the client.
  • Common data. Defined by the schema/DTD for the ticket.
  • One or more requests for files. The files the FCS performs the file operations on. For example, one ticket might contain a checkin request, common data for the checkin request, and five individual requests for files.

Valid file operations supported by the tickets are:

  • Checkout
  • Checkin
  • Copy. The ticket created for a copy operation contains an embedded checkout ticket which is used by the destination FCS to perform a checkout operation on the source FCS.
  • Delete. The delete operation is handled by a background thread. After a transaction completes, the delete operation remains in a job cue and completes later.
    Note: when a ticket is returned, this operation is delayed until the ticket has expired so that you can use it before the deletion.

When the FCS receives a ticket, it processes the data. If the file operation is a checkin or a copy, it generates a receipt, which contains the information about file format, whether to append the data or not, what kind of lock to use during the operation, the override, the file name, and the file size. The FCS then sends the receipt to the 3DSpace Service to begin the file operation.

Once the 3DSpace Service receives the receipt, it processes and commits the information. The transaction is considered completed once the 3DSpace Service update completes. If the receipt processing on the 3DSpace Service encounters an error, the system rolls back the 3DSpace Service file operation. A rollback occurs when the 3DSpace Service cleans up the files managed by the FCS. The FCS is stateless so it has no notion of success or failure on the 3DSpace Service side.

If the checkin or copy operation fails while the FCS is writing it to disk, the FCS:

  • Performs a cleanup operation.
  • Does not generate a receipt.
  • Generates an error condition.
  • Determines the client type based on the caller that creates the initial request via the Ticket. The API determines the client type:
    • Browser-based clients use these APIs: com.matrixone.fcs.http.HttpCheckin/ HttpCheckout class
    • HTTP clients use these APIs: com.matrixone.fcs.mcs.Checkin*/Checkout
  • Depending on the client type, the FCS does the following:
    • For browser-based clients, the FCS redirects to an error page.
    • For HTTP clients such as Java, and .NET, the FCS returns an HTTP error code.

Tickets and receipts provide additional security because they are:

  • Single use
  • Encrypted
  • Time sensitive. They expire after 10 minutes. When multiple machines are involved in the network, it is possible that the FCS and 3DSpace Service clock settings differ. To avoid this problem, the FCS does a callback operation to synchronize time differences so the ticket expiration is accurate.

Tickets are timestamped.

Each ticket contains an MCS timestamp, which is used to verify the expiration of the ticket. The first time the FCS receives a ticket from the MCS, the FCS sends a time request to the MCS to get its system time. The MCS time is then cached and used in the lifetime of the process. If the MCS and FCS clocks deviate significantly from each other, the cached time is refreshed. This causes a side effect to be added to the Fcs About page. By visiting this page, MCS times are refreshed (resending a time request to the MCS). On the other hand, if the MCS and FCS clocks are always synchronized (such as when using a time server), you may want to turn off the time request mechanism (by setting MX_FCSINIT_OFF=true). In this case, the MCS is assumed to have no time difference from the FCS.