Oracle Internet File System Developer's Guide Release 1.1 Part Number A75172-04 |
|
This chapter covers the following topics:
Overrides belong to the category of Oracle Internet File System customization, which includes:
Of these four types of customization, overrides present a significant leap in complexity. Except for renderers, the other types of customization take place on the client, or "bean-side." These more common types of customization use the extensive classes found in the oracle.ifs.beans
package. With overrides, we tackle "server-side" processing, using a more limited published API.
An override is a method that allows an application program to intervene in a predefined way with the standard repository operations:
Note: For the 1.1 release of Oracle iFS, overrides are applicable only to Insert, Update, and Free operations. No overrides are available for other database operations, such as copy, add item to folder, or remove item from folder. This functionality is planned for future releases of the product.
The Pre- overrides work by allowing you to interrupt the standard flow of processing on the server side at certain predefined points. At these points, you can specify custom processing to occur before one or more of the standard database operations takes place. For example, your custom validation routine might be incorporated into both PreInsert and PreUpdate overrides.
The behavior of the actual Insert, Update, and Free operations is complex, and to override the actual operations risks producing unintended and unwanted results.
However, in almost every circumstance, application requirements can be met quite safely by using Pre- methods to interact with the repository immediately before the specified operation. Because the Pre- overrides are the most frequently used, the balance of this chapter focuses on Pre- overrides.
The following table presents an example of how each override method might be used.
Because working with overrides is a complex task, we recommend that you postpone tackling overrides until you have had considerable experience with Oracle iFS and its Java API. Specifically, we suggest that your background should include knowledge and hands-on experience in the following areas:
Providing this range of information is beyond the scope of this Guide. To gain the experience required to tackle overrides, we suggest beginning with several less-complex Oracle iFS applications. This hands-on experience, combined with attendance at Oracle iFS training, will provide the needed familiarity with the Oracle iFS objects and the way they work together.
If you have created Oracle iFS objects using the classes of the Oracle iFS API, you will recall the two-phase method of object creation:
For example, for a document, you would first create a DocumentDefinition object, then pass that object as an argument to the LibrarySession.createPublicObject() method. For more information, see "Creating a New Document" in Chapter 3, "Working with Documents".
In the Oracle iFS Java class hierarchy each Oracle iFS object has two representations:
When you work with overrides, you are working with objects in the Oracle iFS repository. In this context, you use the S_ classes, such as S_Document, rather than the familiar bean-side classes, such as Document.
The function of the Definition object is to specify the object's attributes. When you create a DocumentDefinition object, you set two types of information:
Attributes can also be divided into two categories based on their origin:
User-set attributes are attributes that are set by and can be updated by the user, such as the object Name and Description.
You can set all the user-set attributes using the bean-side Definition object.
Derived attributes are attributes that are set by and can only be updated by the system, such as Creator. These attributes are derived from a source other than the user. For example, Creator is derived from the current logon ID.
To handle the derived attributes, you must use the server-side class,
S_DocumentDefinition.
The override methods provide pre-processing for the standard database operations:
Because overrides by their nature take place on the server-side, all the override methods are located in the S_LibraryObject class and its subclasses. Just as oracle.ifs.beans.LibraryObject provides a bean-side Java representation for all the objects that end users manipulate directly (such as documents and folders), oracle.ifs.server.S_LibraryObject provides the server-side Java representation for these same objects.
To plan an override, first decide which operation or operations you want to override (Insert, Update, or Free).
To write an override, follow these steps:
Assume you have already created a bean-side custom class called PurchaseOrder that extends the Document class. Now you decide you want to add some special validation checks via a PreInsert override.
First you create a server-side Java class, S_PurchaseOrder, to represent your custom class in the server. S_PurchaseOrder extends S_TieDocument. Tie classes allow you to "tie" into the class hierarchy at any level, letting you customize without changing the way the class hierarchy is structured. For more information, see "Tie Classes" in Chapter 2, "API Overview".
Put this class into a new custom package, such as MyCompany.MyApp.server.
(Do not add this class to the oracle.ifs.server
package).
public class S_PurchaseOrder extends S_TieDocument
Every override class must implement two constructors:
public S_PurchaseOrder(S_LibrarySession session, S_LibraryObjectData data)
throws IfsException
Parameters | Datatype | Description |
---|---|---|
|
S_LibrarySession |
Current LibrarySession. |
|
S_LibraryObjectData |
Data component |
public S_PurchaseOrder(S_LibrarySession session, java.lang.Long classID)
throws IfsException
Parameters | Datatype | Description |
---|---|---|
|
S_LibrarySession |
Current LibrarySession. |
|
Long |
Class ID for the object that is in the process of being created. |
The S_PublicObject class provides Pre- methods for the standard database operations. For a complete list, see "Override Methods".
The following table describes the parameters of the Override methods.
public void extendedPreInsert(OperationState opState,
S_LibraryObjectDefinition def) throws IfsException { super.extendedPreInsert(opState, def); //Add your validation code here. }
The first call after the method begins should be to "super." This call implements processing from the superclass of this object. In this case, it allows both the
S_Document class and the S_PublicObject class to perform processing.
After that, add any specific validation code that your application requires. For example, in the custom bean-side class for Purchase Order, you may have added a setApprover() method. Before you insert the PurchaseOrder object into the database, you may want to check the value of that Approver, and perform one of the following actions:
The following sample code provides a brief example of using a PreInsert override to add server-side validation. Note the following three lines shown in bold, where placeholders are used that must be replaced with appropriate code for your application:
// S_PurchaseOrder.java package mypackage; import oracle.ifs.common.AttributeValue; import oracle.ifs.common.IfsException; import oracle.ifs.server.S_DirectoryUser; import oracle.ifs.server.S_LibraryObjectData; import oracle.ifs.server.S_LibraryObjectDefinition; import oracle.ifs.server.S_LibrarySession; import oracle.ifs.server.OperationState; import oracle.ifs.server.S_TieDocument; // server side PurchaseOrder class example public class S_PurchaseOrder extends S_TieDocument { // constructors public S_PurchaseOrder(S_LibrarySession session, S_LibraryObjectData data) throws IfsException { super(session, data); } public S_PurchaseOrder(S_LibrarySession session, Long classId) throws IfsException { super(session, classId); } // override Pre Insert Operation public void extendedPreInsert(S_LibraryObjectDefinition def, OperationState opState) throws IfsException { // ALWAYS call super super.extendedPreInsert(opState, def); // get our session S_LibrarySession session = getSession(); // get the approver attribute so we can check it AttributeValue av1 = def.getAttribute("APPROVER"); S_DirectoryUser approver = (av1 == null) ? null: (S_DirectoryUser) av1.getDirectoryObject(session); //validate the approver if (! <valid> ) { // this will rollback the operation throw new IfsException( <your custom error code>, this ); } // otherwise, set the APPROVED bit to true. // the APPROVED bit is not settable or updateable // by users, but the server can set it thusly AttributeValue av2 = AttributeValue.newAttributeValue(true); def.setSystemSetAttribute("APPROVED", av2); } }