File Checkouts

Sequence

Any Java client application that will perform FCS checkin or checkout operations, must now explicitly reference the FcsClient.jar instead of the eMatrixServletRMI.jar. The following error will occur if the Java client is not referencing the FcsClient.jar:

 <java.lang.NoClassDefFoundError: com/matrixone/client/fcs/InputStreamSource_2>

Before a checkin or checkout operation to or from a store or location, verify that the FCS server defined in the FCS_URL on that store or location is running. If not, the operation will fail. Additionally, you should verify factors that may also affect the operation, like a LAN line being down.

The following diagram illustrates how a checkout operation works:

The client makes a checkout request passing in a BusinessObjectProxy (BOP) object to the checkout(). The BOP contains the object ID, the file formats, and the names of the files to checkout. The 3DSpace Service returns a ticket.

The trigger sequence for a checkout event is:

1. Get the ticket using checkout()
   1. Check trigger is fired.
   2. File is replicated to the destination store/location, if needed.
   3. Override trigger is fired.
   4. Action trigger is fired.
   5. Ticket is sent to FCS.
2. FCS sends the file to the requesting client.

Override Triggers

If a store/location is configured for FCS, and an override trigger is present on the type, FCS will be disabled for that particular operation, allowing the business logic in that trigger to fire. This happens automatically for the Studio Customization Toolkit.

It is not possible to combine FCS with an override trigger since FCS is intended to separate the file operation from the business logic and corresponding meta data access.

Checkout Locations

3DSpace attempts to checkout the requested item as follows:

Use Locations that are part of the checkout person's preferred site. If none of these locations contain the newest copy, then;

Use any location that contains a valid copy of the file. This means that a "sync on demand" is performed - the requested file is copied to the user's preferred location, and then the local file checkout is performed.

Some checkouts allow the location to be overridden.

FCS Zip Support

FCS provides the ability for the client (the JSP page) to specify the download format, which includes the ability to compress the download stream (using Java zip support). This provides the following benefits:

• Multiple files can be downloaded in one archive stream (zip). This allows the current browser to deal with multiple files. (The browser can launch the appropriate zip program, such as WinZip).
• For a single file download, the compression, though optional, reduces the number of bytes that are transferred.

The checkout method of the checkout package allows a Boolean argument (isZip) to indicate use of the Java zip functionality.

Bulk Document Checkout

FCS also lets the client ( the JSP page) download multiple files without compressing them into a single zip file. When you check out multiple files without compressing their contents, the files are checked out via a multi-part HTTP stream containing the uncompressed content of all files requested for check out.

Since multi-part HTTP streams are not supported by all browsers, you can only use this feature with FCS clients.

In the doIt() method of the Checkout class, the parameter zipOutput controls the checkout of multiple files.

• If the parameter zipOutput=true, the files are checked out as a single zip file.
• If the parameter zipOutput=false, the files are checked out as part of a multi-part HTTP stream.

It is your responsibility to correctly parse the multi-part download stream and break it up into multiple files.

For more information on the zipOutput parameter, see Your Own Checkout and Using the com.matrixone.fcs.mcs.

Your Own Checkout

To write a client that performs a checkout, use the doIt() method of the Checkout class passing in various parameters. The Checkout class that you use depends on the kind of client you are writing. These APIs are:

• com.matrixone.fcs.mcs--Use this when the client performing the checkout is located on the 3DSpace Service/FCS server.
• com.matrixone.fcs.http.Http--Use this when the client performing the checkout is a browser client.
• com.matrixone.fcs.fcs--Use this when the client performing the checkout is Java program.

Using the com.matrixone.fcs.mcs

The com.matrixone.fcs.mcs.doIt() method has four variants. All of the versions return a TicketWrapper. Use one of these two methods to do a simple file checkout where no manipulation of the checked out file(s) is required and if the file content is small. Use the second variant if a location override might be needed.

doIt(Context ctx, contextConnect, list)throws MatrixException

doIt(Context ctx, contextConnect, locationOverride, list) 
throws MatrixException

Use one of these methods when you have to perform some additional file manipulation. For example, you want the checkout operation to create a zip file of the content. Use the second variant to allow a location override.

doIt(Context ctx, zipOutput, outFileName, contextConnect, list) 
throws MatrixException

public static TicketWrapper doIt(Context ctx, zipOutput, 
outFileName, contextConnect, locationOverride, ArrayList list) 
throws MatrixException

The arguments include:

Using the com.matrixone.fcs.http Methods

The com.matrixone.fcs.http. doIt() method has four variants, however, two are deprecated. Of the remaining methods, one allows users to override the location of the checkout via the locationOverrride parameter.

• To perform a simple checkout, without a location override, use this doIt() method:

doIt(Context ctx, String[] boids, String[] fileNames, 
String[] formats, String[] locks, String[] paths, boolean 
zipOutput, String outFileName, String errorPage, 
HttpServletRequest req, HttpServletResponse res)

• To enable location overrides, use this doIt() method:

doIt(Context ctx, String[] boids, String[] fileNames, String[] 
formats, String[] locks, String[] paths, boolean zipOutput, 
String outFileName, String errorPage, String locationOverride, 
HttpServletRequest req, HttpServletResponse res)

The following table describes the arguments that must be passed on a checkout operation:

The following table describes what happens when you specify the locationOverride switch:

Sample Checkout Code

The following example illustrates how to write a JSP that allows a location override.

.

.

.

<%

Context ctx = Framework.getFrameContext(session);

String errorPage = "/fcs/errorPage.jsp";

String[] boids = request.getParameterValues("boid");

String[] fileNames = request.getParameterValues("fileName");

String[] formats = request.getParameterValues("format");

String[] locks = request.getParameterValues("lock");

String[] paths = new String[fileNames.length];

boolean useZip = request.getParameter("useZip") != null;

String zipName = null;

if (useZip)

{

    zipName = request.getParameter("zipName");

}

TicketWrapper ticket = HttpCheckout.doIt(ctx, boids, fileNames, 
formats, locks, paths, useZip, zipName, errorPage,  
locationOverride, request, response);

String ticketStr = ticket.getExportString();

String ftaAction = ticket.getActionURL();

%>

<html>

<body>

   <form method="post" name="FcsForm" action="<%=ftaAction%>">

<br>

<input name="<%=McsBase.resolveFcsParam("jobTicket")%>" 
value="<%=ticketStr%>" size="90"><br>

<input name="<%=McsBase.resolveFcsParam("failurePage")%>" 
value="<%=Framework.getFullClientSideURL(request,response,error
Page)%>" size="90"><br>

<input name="<%=McsBase.resolveFcsParam("attachment")%>" 
value="false" size="90"><br>

</form>

<script>

document.forms["FcsForm"].submit();

</script>

</body>

</html>

Using the com.matrixone.fcs.fcs Methods

The com.matrixone.fcs.fcs package has a single doIt() method with this signature:

com.matrixone.fcs.common.JobReceipt doIt(FcsServlet servlet,
FcsContext fcsContext, javax.servlet.http.HttpServletRequest req,
javax.servlet.http.HttpServletResponse resp)