This chapter describes the Repository Extensibility Framework (REX) architecture and discusses how to enable the OpenAPI and consume the WSDL.
This chapter includes the following sections:
REX is a web services API for programmatic integration into Oracle Enterprise Repository. It is based on accepted industry standards, and designed with a focus on interoperability and platform independence. REX uses Remote Procedure Call (RPC) web services described by the Web Services Description Language (WSDL v1.1). This enables clients to interact with Oracle Enterprise Repository using any platform and any implementation language that supports web services. For example, while Oracle Enterprise Repository is a J2EE application, REX enables programmatic interaction with a .NET client.
Note:
Instances of "flashline" and "registry" appear in this documentation, particularly in the java package structure and in the REX class names.If your Oracle Enterprise Repository is or will be configured to be secured by Siteminder, you must configure the policy server to ignore (or unprotect) the following URL to allow OpenAPI integration to function properly:
http://appserver.example.com/oer/services/
Note:
The examples provided in the documentation are for illustrative purposes and will not necessarily compile due to package structure differences between versions of the Oracle Enterprise Repository WSDL. You must change the package structure to appropriately target your version of Oracle Enterprise Repository.For more information about REX, see the REX Javadoc at Oracle Fusion Middleware Extensibility Framework (REX) for Oracle Enterprise Repository.
Figure 4-1 describes the REX architecture.
The high-level architecture of Oracle Enterprise Repository and REX is designed with several high-level goals in mind:
Flexibility
Any client platform that conforms to accepted industry standards, such as SOAP, WSDL, and HTTP, can interact with Oracle Enterprise Repository through the REX interface. Proper functioning of the API with the most common client platforms has been validated.
Extensibility
Oracle Enterprise Repository's layered architecture simplifies the process of adding subsystems to provide access to new features as they are added to Oracle Enterprise Repository. For more information, see Section 4.2.4, "Versioning Considerations for the Oracle Enterprise Repository REX".
Simplicity
End users find it easy to take advantage of the extensive feature set available in REX.
Oracle Enterprise Repository's REX provides access to a variety of subsystems. These subsystems loosely group system functionality into logical categories roughly equivalent to the type of entity on which they operate. Much of this document is organized into sections related to these subsystems.
REX methods are named using a scheme based on the various subsystems. For more information about the description of the algorithm used in this process, see Section 4.2.2, "CRUD-Q Naming Convention". The subsystems defined in REX include:
acceptableValue
asset
assetType
authToken
categorization
catergorizationType
department
extraction
import/export
project
relationship
role
user
vendor
The scheme used in naming the Open API methods is based on the CRUD-Q mnemonic. CRUD-Q represents five operations:
C - Create
R - Read
U - Update
D - Delete
Q - Query
Each method starts with the name of the subsystem to which it belongs, followed by a description of the operation to be performed within that subsystem, as in the following example:
<subsystem><Operation>
For example, the method to perform a create operation in the asset subsystem would be:
assetCreate(...)
This naming convention would also produce:
assetRead(...) assetUpdate(...) assetDelete(...) assetQuery(...)
Subsystems are likely to have operations beyond the CRUD-Q set, and may not include all of CRUD-Q. For example, since it is impossible to delete a user, there is no userDelete method. There is, however, a userDeactivate method. Table 4-1 provides a detailed list of the detailed operations that the subsystem can have apart from the CRUD-Q operations.
Table 4-1 Subsystems and CRUD-Q Convention Relationship
Create | Read | Update | Delete | Query | Other Features | |
---|---|---|---|---|---|---|
Acceptable Value List |
Yes |
Yes |
Yes |
Yes |
Yes |
Accept, Activate, Assign, Deactivate, Register, Retire, Submit, Unaccept, Unassign, Unregister, Unsubmit, Modify Custom Access Settings |
Asset |
Yes |
Yes |
Yes |
Yes |
Yes |
|
Asset Type |
Yes |
Yes |
Yes |
Yes |
Yes |
|
Categorization Type |
Yes |
Yes |
Yes |
Yes |
Yes |
|
Department |
Yes |
Yes |
Yes |
No |
Yes |
|
Extraction |
Yes |
Yes |
Yes |
No |
Yes |
|
Project |
Yes |
Yes |
Yes |
Yes |
Yes |
Close, Open, Reassign extractions, Remove user |
Relationship |
Yes |
Yes |
Yes |
No |
Yes |
|
Role |
Yes |
Yes |
Yes |
Yes |
Yes |
|
User |
Yes |
Yes |
Yes |
No |
Yes |
Activate, Deactivate, Lockout, Unapprove |
Vendor |
Yes |
Yes |
Yes |
Yes |
Yes |
|
Contact |
Yes |
Yes |
Yes |
Yes |
Yes |
Unless otherwise noted, every call to REX is atomic. That is, each call either succeeds completely, or fails completely.
For example, one version of the categorizationUpdate
method takes as an argument an array of categorization updates. In this case, if one categorization update fails, all categorization updates fail.
REX uses the following fundamental WSDL data types, in addition to the complex types defined in the WSDL.
Arrays of any of these types can be returned:
xsd:int
xsd:long
xsd:string
xsd:boolean
xsd:dateTime
You can dynamically generate API Stubs by consuming the REX WSDL by pointing its IDEs or web services toolkits at the following URL:
http://appserver/oer/services/FlashlineRegistry?WSDL
If you are creating custom integrations with OER from Oracle BPM 11g, use the following URL instead:
http://appserver/oer/services/RexAPI?wsdl
Java stubs for the Oracle Enterprise Repository REX WSDL can be created using the AXIS WSDL2java utility:
java -cp .;axis.jar; xerces.jar; commons-discovery.jar; commons-logging.jar; jaxen-full.jar; jaxrpc.jar; saaj.jar;wsdl4j.jar; xalan.jar org.apache.axis.wsdl.WSDL2Java
The JAR files required to complete this conversion process are:
axis.jar
xerces.jar
commons-discovery.jar
commons-logging.jar
jaxen-full.jar
jaxrpc.jar
saaj.jar
wsdl4j.jar
xalan.jar
Note:
Replace "appserver" in the URL with the name of the server on which Oracle Enterprise Repository is installed.The evolution of the Oracle Enterprise Repository REX parallels the evolution of Oracle Enterprise Repository. As a result of this process, incompatibilities may emerge between older and newer versions of REX. While full version compatibility is our goal, backward compatibility is subject to unpredictable and therefore potentially unavoidable limitations. Oracle Enterprise Repository REX includes the following backward compatible enhancements:
Addition of new methods to the Oracle Enterprise Repository web service.
Definition of new complex types in the WSDL.
With regard to these backward compatible changes, the regeneration of client proxies is necessary only when the need arises to take advantage of new features and functionality.
The namespace of the service changes only when incompatible changes are unavoidable. Examples of such a change would include the modification of an existing complex type, or a change in the signature of a method in the service. In this event, client proxy regeneration is necessary, as are the minimal code changes. Client proxies generated from prior versions of REX are unable to connect to the new service.
The namespace of complex types never changes.
This section describes the basic concepts of REX such as getting started with enabling the OpenAPI and consuming the WSDL.
The procedure is performed on the Oracle Enterprise Repository Admin screen.
Click System Settings.
Enter the property cmee.extframework.enabled in the Enable New System Setting text box.
Click Enable. The Open API section is displayed.
Ensure the cmee.extframework.enabled property is set to True
.
Click Save. REX is now enabled within your instance of Oracle Enterprise Repository.
The first step in using REX is to generate the client-side stubs necessary to communicate with the Oracle Enterprise Repository server. This is generally accomplished using the automated tools provided by the specific Web services toolkit in use. This section describes how to generate client stubs using a variety of integrated development environments and toolkits.
Authentication and Authorization
The first step in using REX is authenticating with the server. Authentication is performed using the authTokenCreate method. This method takes a user ID and password as arguments to be used in authenticating with Oracle Enterprise Repository. If the ID and password are successfully authenticated, an authentication token is returned. This token must be used in every subsequent call to REX.
If a valid AuthToken is not included for every REX method, an OpenAPIException is thrown. The applies to all methods except authTokenCreate and authTokenDelete.
The following example shows how to retrieve an AuthToken and use it in subsequent REX calls.
Example 4-1 How to Retrieve an AuthToken and use in REX Calls
package com.example.flashlineclient; //The imports below are assumed for any of the included examples import javax.xml.rpc.ServiceException; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Asset; public class FlexTest { public FlexTest () { } public static void main(String[] pArgs)throws OpenAPIException, RemoteException, ServiceException { try { FlashlineRegistry lRegistry = null; AuthToken lAuthToken = null; URL lURL = null; lURL = new URL("http://www.example.com/appname/services/FlashlineRegistry"); //"www.example.com" should be your server address //"appname" is the application name of the location that the Registry is running on //These two things must be changed to the proper values in every example lRegistry = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); lAuthToken = lRegistry.authTokenCreate("username", "password"); System.out.println(lAuthToken.getToken()); //displaying the authtoken as a string to the screen Asset lAsset = lRegistry.assetRead(lAuthToken, 559); //reading asset number 559 System.out.println(lAsset.getName()); //displaying the name of asset 559 to the screen } catch(OpenAPIException lEx) { System.out.println("ServerCode = "+ lEx.getServerErrorCode()); System.out.println("Message = "+ lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } System.out.println("execution completed"); System.exit(0); } }
Authorization
REX enforces the same authorization rules as the Oracle Enterprise Repository application. The user ID and password used to authenticate determines the privileges available to the user through REX. For example, if the authenticated user does not have EDIT privileges assigned for projects, and attempts to create a project using the projectCreate REX method, an OpenAPIException is thrown.
Open API communicates server errors to the client through a SOAP Fault. The manner in which SOAP Faults are handled varies according the language and SOAP toolkit in use.
This section suggests ways to detect and deal with exceptions generated by the Open API within client code, using the most common platform/toolkit combinations.
Exceptions thrown by the Open API are transferred as SOAP Faults, and then deserialized by the AXIS client toolkit as Java Exceptions. That is, AXIS makes an attempt to map the SOAP Fault to a corresponding client-side OpenAPIException class. Server-side errors are represented to the client as com.flashline.registry.openapi.OpenAPIException
instances. Consequently, client code can catch exceptions with the code listed below which is from the code above:
try { lAsset = lRegistry.assetCreate(..); } catch(OpenAPIException lEx) { System.out.println("ServerCode = "+ lEx.getServerErrorCode()); System.out.println("Message = "+ lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); }
When attempting to save an entity in Oracle Enterprise Repository, the system attempts to validate the input. Any missing or invalid data causes the server to throw an OpenAPIException containing a list of fields and their respective errors.
For more information, see "Exception Handling".
The criteria object model is currently moving to a more flexible representation of terms and grouping. As they occur, these changes affects the availability of certain API features when executing a query using a criteria object. The subsystems only directly evaluate their corresponding criteria objects, and do not make use of the extended capabilities of the underlying SearchTermGroup, unless otherwise noted in this documentation.
Sending Binary Data (Attachments)
Various REX methods require sending or receiving potentially large sets of binary data between the client and server. For example, the import/export subsystem provides methods for sending a payload from which to import, and methods for retrieving a payload representing a set of exported assets.
Typically, binary data is transferred through Web services RPC invocations through Dynamic Internet Message Exchange (DIME); SOAP with Attachments (SwA); or Base-64 Encoding. Each has its advantages and disadvantages, but few client toolkits directly support all three.
The Oracle Enterprise Repository OpenAPI supports all three mechanisms for transferring binary data. Details are provided in the following sections. Any method that provides for the binary transfer of data has three versions, each one supporting a different transfer mechanism. For example, to retrieve the results of an export, a user can select any one of the following methods:
importGetResultsB64
Retrieve results of export in base-64 encoded format. This is the lowest common denominator, and can be used on any platform, provided that the client can encode/decode base-64 data.
importGetResultsDIME
Retrieve export results as an attached file, using the DIME protocol. This is the preferred option for most .NET clients.
importGetResultsSwA
Retrieve export results as an attached file, using the SOAP with Attachments (SwA) protocol (MIME-based)
Using DIME attachments with .NET and the Microsoft Web Services Enhancement (WSE) Kit
Microsoft provides an extension to the standard .Net Web service toolkit. The Microsoft Web Services Enhancement (WSE) kit provides advanced functionality, such as sending and receiving attachments through Web services using the Dynamic Internet Messaging Exchange (DIME) protocol.
The following code snippet gives an example of sending data through a DIME attachment:
Example 4-2 Example of Sending Data Through a DIME Attachment
// relax the requirement for the server to understand ALL headers. This MUST be // done, or the call with the attachment fails. After the call, if you wish, // you can set this back to "true" registry.RequestSoapContext.Path.EncodedMustUnderstand= "false"; // clear the attachments queue registry.RequestSoapContext.Attachments.Clear(); registry.RequestSoapContext.Attachments.Add( new Microsoft.Web.Services.Dime.DimeAttachment("0", "application/zip", Microsoft.Web.Services.Dime.TypeFormatEnum.MediaType, "c:\\tmp\\import.zip")); // start an import running on the server registry.importExecute(lAuthToken, "flashline", null, "FEA Flashpack Import", null); // do some polling (calls to importStatus) to monitor the import progress, // if you wish
The following code snippet gives an example of receiving data through a DIME attachment:
Example 4-3 Example of Receiving Data Through a DIME Attachment
// relax the requirement for the server to understand ALL headers. This MUST be // done, or the call with the attachment fails. After the call, if you wish, // you can set this back to "true" registry.RequestSoapContext.Path.EncodedMustUnderstand= "false"; // clear the attachments queue registry.RequestSoapContext.Attachments.Clear(); // start an export flashline.ImpExpJob lJob = registry.exportExecute(lAuthToken, "flashline", null, "Complete Export", "flashline", "<entitytypes> <entitytype type=\"acceptableValueList\"> <entities> <entity id=\"100\"/> </entities> </entitytype> </entitytypes>"); // do some polling (calls to exportStatus) to watch the progress of the // export, if you wish... // this call blocks until either the method returns (or an exception is thrown), // or the call times out. registry.exportGetResultsDIME(lAuthToken, lJob); // check to see if the call resulted in attachments being returned... if(registry.ResponseSoapContext.Attachments.Count > 0) { Stream lStream = registry.ResponseSoapContext.Attachments[0].Stream; // write the data out somewhere... }
Using SOAP with Attachments and Java AXIS clients
The Axis client provides functions to handle SOAP attachments in Java. For more information, see http://www-106.ibm.com/developerworks/webservices/library/ws-soapatt/
The following code snippet gives an example of receiving data:
byte[] lResults = null; ImpExpJob lExportJob = mFlashlineRegistrySrc.exportExecute(mAuthTokenSrc,"flashline",null, "Export Assets","default", createAssetQuery().toString()); lExportJob = mFlashlineRegistrySrc.exportStatus(mAuthTokenSrc, lExportJob); lResults = mFlashlineRegistrySrc.exportGetResultsB64(mAuthTokenSrc, lExportJob); // write the results out to disk in a temp file File lFile = null; String lTempDirectory = System.getProperty("java.io.tmpdir"); lFile = new File(lTempDirectory + File.separator + "impexp.zip"); FileOutputStream lOS = new FileOutputStream(lFile); BufferedOutputStream lBOS = new BufferedOutputStream(lOS); lBOS.write(lResults); lBOS.flush(); lBOS.close(); lOS.close();
The following code snippet gives an example of sending data through a DIME attachment:
// open file and attach as data source InputStream lIS = new FileInputStream(lFile); ((Stub)mFlashlineRegistryDest)._setProperty (Call.ATTACHMENT_ENCAPSULATION_FORMAT, Call.ATTACHMENT_ENCAPSULATION_FORMAT_DIME); ByteArrayDataSource lDataSource = new ByteArrayDataSource(lIS, "application/x-zip-compressed"); DataHandler lDH = new DataHandler(lDataSource); // add the attachment ((Stub)mFlashlineRegistryDest).addAttachment(lDH); ImpExpJob lJob = mFlashlineRegistryDest.importExecute(mAuthTokenDest, "flashline", null, "Import Assets Test", null);
This section describes and provides use cases for the REX API.
This section provides a use case for the ArtifactStore API that describes how to create a missing ArtifactStore in Oracle Enterprise Repository.
The ArtifactStore subsystem provides a web services-based mechanism that is used to query and create Oracle Enterprise Repository ArtifactStores.
This use case describes how to create a missing artifactstore.
Example 4-4 Use Case: Create Missing ArtifactStore
package com.flashline.sample.artifactstoreapi; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.ArtifactStoreBean; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.query.ArtifactStoreCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ArtifactStores { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------------- // query for an artifact store ArtifactStoreCriteria lArtifactStoreCriteria = null; ArtifactStoreBean[] lArtifactStoreBeans = null; ArtifactStoreBean lArtifactStoreBean = null; lArtifactStoreCriteria = new ArtifactStoreCriteria(); lArtifactStoreCriteria.setHostCriteria("existing-artifact-store.com"); lArtifactStoreCriteria.setBasepathCriteria("/"); lArtifactStoreBeans = repository.artifactStoreQuery(authToken, lArtifactStoreCriteria, false); // create a missing artifact store if missing and based on the criteria lArtifactStoreCriteria = new ArtifactStoreCriteria(); lArtifactStoreCriteria.setHostCriteria("missing-artifact-store.com"); lArtifactStoreCriteria.setBasepathCriteria("/"); // a new artifact store is created lArtifactStoreBeans = repository.artifactStoreQuery(authToken, lArtifactStoreCriteria, true); lArtifactStoreBean = lArtifactStoreBeans[0]; } catch(Exception e) { throw new RuntimeException(e.getMessage()); } } }
This section provides use cases for the AcceptableValueLists API that describe how to create a new acceptable value list and enter it into Oracle Enterprise Repository and populate an asset's single or multiple selection lists with acceptable values.
Acceptable Value Lists are used in single- and multiple-selection drop-down box metadata elements.
When creating or editing an asset type, Acceptable Value Lists are used as metadata elements. These metadata elements are referenced by ID in the editor and viewer XML for the asset type/compliance template.
When creating or editing assets, values contained in Acceptable Value Lists are used as options for the metadata elements defined for the particular asset type/compliance template. To use the acceptable values for an Acceptable Value List, the custom data for the asset (Asset.GetCustomData()) is modified to reference the ID of the acceptable value.
Create a new acceptable value list and enter it into Oracle Enterprise Repository.
Example 4-5 Use Case: Create and Edit an Acceptable Value List
package com.flashline.sample.acceptablevaluelists; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AcceptableValue; import com.flashline.registry.openapi.entity.AcceptableValueList; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CreateAndEditAcceptableValueList { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ////////////////////////////// // Build an array of acceptable values for the list. // ////////////////////////////// String newAcceptableValueListName = "My AcceptableValueList "+Calendar.getInstance().getTimeInMillis(); AcceptableValue[] acceptableValues = new AcceptableValue[3]; acceptableValues[0] = new AcceptableValue(); acceptableValues[0].setValue("My Value"); acceptableValues[1] = new AcceptableValue(); acceptableValues[1].setValue("My Next Value"); acceptableValues[2] = new AcceptableValue(); acceptableValues[2].setValue("My Last Value"); // ////////////////////////////// // Create the AcceptableValueList in Repository // ////////////////////////////// AcceptableValueList newAcceptableValueList = repository .acceptableValueListCreate(authToken, newAcceptableValueListName, acceptableValues); System.out.println("The new acceptableValueList id =\"" + newAcceptableValueList.getID() + "\""); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Populate an asset's single or multiple selection lists with acceptable values.
Example 4-6 Use Case: Populate Lists with Acceptable Values
package com.flashline.sample.acceptablevaluelists; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AcceptableValue; import com.flashline.registry.openapi.entity.AcceptableValueList; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.query.AcceptableValueListCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class FindAcceptableValueListAndUseInAsset { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ////////////////////////////// // Find the AcceptableValueList // ////////////////////////////// AcceptableValueListCriteria criteria = new AcceptableValueListCriteria(); criteria.setNameCriteria("My AcceptableValueList"); AcceptableValueList[] acceptableValueLists = repository .acceptableValueListQuery(authToken, criteria); AcceptableValueList myAcceptableValueList = acceptableValueLists[0]; AcceptableValue[] acceptableValues = myAcceptableValueList .getAcceptableValues(); // ////////////////////////////// // Find one value within the AcceptableValueList // ////////////////////////////// AcceptableValue myAcceptableValue = null; for (int i = 0; i < acceptableValues.length; i++) { if (acceptableValues[i].getValue().equals("My Value")) { myAcceptableValue = acceptableValues[i]; break; } } long myAcceptableValueID = myAcceptableValue.getID(); Asset myAsset = repository.assetRead(authToken, 561); String customData = myAsset.getCustomData(); // ////////////////////////////// // Modify customData to use myAcceptableValueID. // ////////////////////////////// String modifiedCustomData = customData; // ... // ////////////////////////////// // save modified custom data // ////////////////////////////// myAsset.setCustomData(modifiedCustomData); repository.assetUpdate(authToken, myAsset); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
This section describes the Asset API and provides use cases for the Asset API that describe how to create or modify an asset, build an asset search, and work with asset status and asset tabs.
Assets are the core entities in the Oracle Enterprise Repository. This document covers the Asset subsystem actions Create, Read, Update, Delete, and Query. It also covers the modification of:
Asset active status:
Activate
Deactivate
Retire
Asset registration status:
Submit
Accept
Register
Unsubmit
Unaccept
Unregister
Asset assignment status:
Assign
Unassign
Several issues must be taken into consideration when working with assets in Oracle Enterprise Repository using REX. Trade-offs in memory consumption and performance should be carefully weighed.
Memory Consumption
Assets and their metadata consume a significant amount of memory on both the REX server and on the client software using REX. When searching Oracle Enterprise Repository using REX, it is possible that a large number of assets may be returned. To avoid Denial of Service interruptions to the system, administrators can limit the maximum number of results that can be returned in a call to the REX method assetQuery. The system setting cmee.extframework.assets.max controls the maximum number of search results that can be returned as a result of a query. If the number of results matching a query exceeds the maximum, an exception is generated by REX.
In cases where it is expected that a potentially large number of assets matches a query, the assetQuerySummary method is recommended. This alternative method of querying Oracle Enterprise Repository matches exactly the same assets as a call to assetQuery, but returns lightweight asset summary objects, rather than the full asset objects. These summary objects consume a nominal amount of memory, and the possibility of exhausting resources as a result of a query is consequently negligible.
After a summary query has been performed, the full asset objects can be retrieved for assets of interest using either assetRead, or assetReadArrayFromSummary. If multiple assets are desired, use of the assetReadArrayFromSummary method is recommended. See the API documentation for details on using this method.
Performance
REX is based on standard web services technology, which provides many significant advantages in flexibility and portability. However, as with any web services-based technology, performance can be challenging, particularly in high data volume situations (for example, large numbers of assets being manipulated). REX provides options that allow developers to avoid potential performance problems.
Iterative Reads
The primary overhead in web services technology is incurred in the serialization and de-serialization of data using XML, combined with network transfer. Much of this overhead can be avoided in situations where a number of assets are to be read. For example, if 50 assets are to be retrieved from Oracle Enterprise Repository using REX, the developer could perform 50 assetRead calls. A better approach, however, would be to use the assetReadArray method, passing the IDs of the desired assets as a single argument. This would retrieve all 50 assets in one call, dramatically improving performance.
Listing Operations
Often data is retrieved from REX for the purpose of displaying a listing to an end user, who then is expected to select an asset for closer inspection. In cases like these, the full extent of asset metadata is not required to generate a summary list. As discussed in the section on memory above, consider using the summary methods provided in REX.
Access Control
Which assets a user of REX can see, and to some extent the information in those assets, is controlled by access settings. The same access restrictions that exist for a user accessing the system through the web GUI also apply to the REX asset subsystem.
Query restrictions - users can only retrieve assets in a call to assetQuery or assetRead for which they have view permission.
Update restrictions - users can only update assets for which they have edit permission.
File restrictions - users can only view the files for which they have download permissions as set in the File type Custom Access Settings applied to each individual file. This means that a user might be able to view an asset, but might not be able to view any of the asset's files. Each file can have it's own permissions, different from the asset's permissions. If specific File type permissions are not applied to a file, these permissions are inherited from the asset's permissions to which the files belong.
This section provides the following definitions:
ID and UUID
ID is an internal unique identifier (numeric) used to identify an asset uniquely within a single Oracle Enterprise Repository instance.
UUID is a universally unique identifier (128-bit numeric represented as a hexidecimal string) used to identify an asset uniquely across any instance of Oracle Enterprise Repository. Each asset's UUID is exposed primarily for purposes of reading and searching. Oracle strongly advises not modifying this field using REX. However, if an administrator does choose to modify an asset's UUID, then the format must be consistent (00000000-0000-0000-0000-000000000000) and the UUID must be unique within the target Oracle Enterprise Repository instance; otherwise, the change operation fails.
Name and Version
String fields that combine to uniquely identify an asset.
Custom Data
Customizable metadata for an asset is stored in an XML structure within this string. The sample code describes the custom data methods effectively.
Example 4-7 Sample Code for Custom Data Methods
package com.flashline.sample.assetapi; import java.io.StringReader; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.text.Format; import java.text.SimpleDateFormat; import java.util.Date; import java.util.List; import javax.xml.rpc.ServiceException; import org.jdom.Document; import org.jdom.Element; import org.jdom.input.SAXBuilder; import org.jdom.output.XMLOutputter; import org.jdom.xpath.XPath; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class UpdateCustomData { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); //////////////////////////////////////////////////////////// // Login to OER //////////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); ////////////////////////////////////////// // assetUpdateCustomDataString ////////////////////////////////////////// // Find and Modify a custom data field value with a value supplied on the command line Long currentLicenses = new Long(repository.assetReadCustomDataString(authToken, 589, "/ _-total-licenses-owned")); currentLicenses = new Long(currentLicenses.intValue() + 1); // save the modifications // NOTICE: A leading slash is required to specify the appropriate path to the element being updated. repository.assetUpdateCustomDataString(authToken, 589, "/ _-total-licenses-owned", currentLicenses.toString()); ////////////////////////////////////////// // assetUpdateCustomDataStringArray ////////////////////////////////////////// // Add a custom data field value with a value supplied on the command line Format formatter = new SimpleDateFormat("yyyyMMdd"); String dateFormat = formatter.format(new Date()); // NOTICE: for the following method, there is no leading slash for the elements being updated. String[] versionHistory = {"version-history/version-history/version-number", "version-history/version-history/production-date-yyyymmdd-", "version-history/version-history/comments"}; String[] versionHistoryValues = {currentLicenses.toString(), dateFormat, "Updated version History: " + dateFormat}; // save the modifications repository.assetUpdateCustomDataStringArray(authToken, 589, versionHistory, versionHistoryValues); ////////////////////////////////////////// // assetUpdateCustomDataNode ////////////////////////////////////////// //The following updates a specific custom data element called "document-name" that is a child of "document", //which is a child of "documentation" XPath lXPath = null; List lElms = null; //First read the Node "documentation" of the specific asset String lXMLDocumentation = repository.assetReadCustomDataNode(authToken, 589, "documentation"); //Using DOM, convert the XML to a Document Document lDoc = null; SAXBuilder lBuilder = new SAXBuilder(); StringReader lReader = null; lReader = new StringReader(lXMLDocumentation); lBuilder.setValidation(false); lBuilder.setIgnoringElementContentWhitespace(true); lDoc = lBuilder.build(lReader); lXPath = XPath.newInstance("documentation/document"); lElms = lXPath.selectNodes(lDoc); //Cycle through the "document" elements until we find the one we want. Then update it. for (int i=0;i<lElms.size();i++) { Element lElm = (Element)lElms.get(i); List lChildElms = lElm.getChildElements(); for (int x=0;x<lChildElms.size();x++) { Element lChildElm = (Element)lChildElms.get(x); if (lChildElm.getName().equals("document-name") && lChildElm.getValue().equals("API")) { lChildElm.setText("API KHAN"); } else { lChildElm.setText(lChildElm.getValue()); } } } //Convert the Document back to an XML string and update the asset's custom data. repository.assetUpdateCustomDataNode(authToken, 589, "documentation", new XMLOutputter().outputString(lDoc)); ////////////////////////////////////////// // assetUpdateCustomDataNodeArray ////////////////////////////////////////// try { //The following updates multiple custom data elements. One is called "document-name" that is a child of "document", //which is a child of "documentation" //The other is the element called "also-known-as" lXPath = null; lElms = null; //First read the Node "documentation" of the specific asset lXMLDocumentation = repository.assetReadCustomDataNode(authToken, 589, "documentation"); //Using DOM, convert the XML to a Document lDoc = null; lBuilder = new SAXBuilder(); lReader = null; lReader = new StringReader(lXMLDocumentation); lBuilder.setValidation(false); lBuilder.setIgnoringElementContentWhitespace(true); lDoc = lBuilder.build(lReader); lXPath = XPath.newInstance("documentation/document"); lElms = lXPath.selectNodes(lDoc); //Cycle through the "document" elements until we find the one we want. Then update it. for (int i=0;i<lElms.size();i++) { Element lElm = (Element)lElms.get(i); List lChildElms = lElm.getChildElements(); for (int x=0;x<lChildElms.size();x++) { Element lChildElm = (Element)lChildElms.get(x); if (lChildElm.getName().equals("document-name") && lChildElm.getValue().equals("API")) { lChildElm.setText("API KHAN"); } else { lChildElm.setText(lChildElm.getValue()); } } } String lDoc1 = new XMLOutputter().outputString(lDoc); //Get the next element lXMLDocumentation = repository.assetReadCustomDataNode(authToken, 589, "also-known-as"); lDoc = null; lBuilder = new SAXBuilder(); lReader = null; lReader = new StringReader(lXMLDocumentation); lBuilder.setValidation(false); lBuilder.setIgnoringElementContentWhitespace(true); lDoc = lBuilder.build(lReader); lXPath = XPath.newInstance("also-known-as"); lElms = lXPath.selectNodes(lDoc); //Get the also-known-as element for (int i=0;i<lElms.size();i++) { Element lElm = (Element)lElms.get(i); lElm.setText("Modified Alias"); } String lDoc2 = new XMLOutputter().outputString(lDoc); //Convert the Document back to an XML string and update the asset's custom data. repository.assetUpdateCustomDataNodeFromStringArray(authToken, 589, new String[] {"documentation", "also-known-as"}, new String[] {lDoc1, lDoc2}); } catch (Exception e) { e.printStackTrace(); } } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } catch (Exception e) { e.printStackTrace(); } } }
This sections describes the following related subsystems that are used with the Asset API:
AssetType
All assets need an active and valid asset type. This asset type defines the metadata that can be stored in the custom data for the asset.
Vendor
If desired, an asset may be linked to a vendor. This linking is done by the vendor ID.
AcceptableValueLists
When creating or editing assets, acceptable values contained in acceptable value lists are used to as options for the metadata elements that were defined for the asset type. To use the acceptable values for an acceptable value list, modify the custom data for the asset (Asset.GetCustomData()) to have it reference the ID of the acceptable value.
RelationshipType
Relationship types define the kinds of relationships that can exist between assets.
Categorization Types
Categorization types are top-level groups of categorizations added to asset types. Categorizations describe an asset.
Projects
Assets can be produced by projects. The producing projects for an asset are stored in an array of ID's.
Users
Users can be assigned to assets. They are the person who is responsible for working up the metadata.
This section describes the use cases using the Asset API. It includes the following topics:
Section 4.4.3.2.2, "Use Case: Creating a New Asset from XML"
Section 4.4.3.2.8, "Use Case: Apply and Remove Compliance Templates from a Project"
Section 4.4.3.2.9, "Use Case: Creating the New Version of an Asset and Retiring the Old Version"
Section 4.4.3.2.11, "Use Case: Finding Assets and Updating Custom-Data"
Section 4.4.3.2.13, "Use Case: Retrieve An Asset's Tab Based on TabType"
Section 4.4.3.2.14, "Use Case: Approving and Unapproving a Tab"
Section 4.4.3.2.15, "Use Case: Reading an Asset's Metadata for a Given Tab"
Create a new asset and enter it into Oracle Enterprise Repository.
Example 4-8 Use Case: Creating a New Asset
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CreateNewAsset { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); /////////////////////////////////// // Login to OER /////////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); /////////////////////////////////// // Create new asset /////////////////////////////////// Asset myAsset = repository.assetCreate(authToken, "My Asset Name108", "My Version "+Calendar.getInstance().getTimeInMillis(), 144); //////////////////////////////////////////// //The following demonstrates how to modify a custom data Date element on an asset. //This date must be in a specific format and the name of the element must by known. //In this example, the name of the element is "testdate". This element must have been created in the //asset type as a Date element //Update the testdate field to January 1, 2007 //Note: the format of the date should match the system setting for Short Date. repository.assetUpdateCustomDataString(authToken, myAsset.getID(), "testdate", "2007-1-1"); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
It is also possible to create a new asset from an XML representation of the asset. Schemas are used to validate the asset XML before creation. The schema for an asset type is available through the Open API as can be seen in Example 4-9.
It is not necessary to do validation yourself, the asset XML is validated internally before the create happens. If you do want to do your own validation, then you must find a validating XML parser such as Xerces 2.0.
Example 4-9 Use Case: Creating a New Asset from XML
package com.flashline.sample.assetapi; import java.io.IOException; import java.io.StringReader; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.parsers.ParserConfigurationException; import javax.xml.parsers.SAXParser; import javax.xml.parsers.SAXParserFactory; import javax.xml.rpc.ServiceException; import org.xml.sax.InputSource; import org.xml.sax.SAXException; import org.xml.sax.SAXParseException; import org.xml.sax.helpers.DefaultHandler; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CreateNewAssetFromXML { public static void main(String pArgs[]) throws ServiceException, ParserConfigurationException, SAXException, IOException { String SCHEMA_LANGUAGE = "http://java.sun.com/xml/jaxp/properties/schemaLanguage"; String XML_SCHEMA = "http://www.w3.org/2001/XMLSchema"; String SCHEMA_SOURCE = "http://java.sun.com/xml/jaxp/properties/schemaSource"; SAXParserFactory lSaxParserFactory = null; SAXParser lSaxParser = null; try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); /////////////////////////////////// // Login to OER /////////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1],pArgs[2]); // Anonymous class to handle validation errors DefaultHandler lDefaultHandler = new DefaultHandler() { public void error(SAXParseException exception) throws SAXException { throw exception; } public void fatalError(SAXParseException exception) throws SAXException { throw exception; } }; ////////////////////////////////////////////////////////////////////// // Define the asset you want to create in XML ////////////////////////////////////////////////////////////////////// // This is the XML of the asset we're creating. Typically it would // come from a GUI or other asset creation mechanism. It is hard // coded for this example. ///////////////////////////////////////////////////////////////////// String assetXML = "<asset id=\"0\">" + " <asset-type id=\"145\" icon=\"component.gif\" lastSavedDate=\"17 Jul 2007 12:00:00 AM\">Component</asset-type>" + " <mandatory-data>" + " <name>NewComponent</name>" + " <version>"+Calendar.getInstance().getTimeInMillis()+"</version>" + " <description><![CDATA[My Description]]></description>" + " <keywords/>" + " <notification-email/>" + " <applied-policies/>" + " <vendor id=\"0\"/>" + " <file-informations/>" + " <hash-informations/>" + " <producing-projects/>" + " <submission-files/>" + " <applied-compliance-templates/>" + " <contacts/>" + " <relationships/>" + " <categorization-types/>" + " </mandatory-data>" + " <admin-data>" + " </admin-data>" + " </asset>"; ////////////////////////////////////////////////////////////////////// // This returns the Schema for the asset type of the asset we're // creating ////////////////////////////////////////////////////////////////////// String schema = repository.assetTypeSchemaRead(authToken, 144); ////////////////////////////////////////////////////////////////////// // This block of code shows validating the asset XML against // the schema ////////////////////////////////////////////////////////////////////// lSaxParserFactory = SAXParserFactory.newInstance(); lSaxParserFactory.setNamespaceAware(true); lSaxParserFactory.setValidating(true); lSaxParser = lSaxParserFactory.newSAXParser(); lSaxParser.setProperty(SCHEMA_LANGUAGE, XML_SCHEMA); lSaxParser.setProperty(SCHEMA_SOURCE, new InputSource(new StringReader( schema))); lSaxParser.parse(new InputSource(new StringReader(assetXML)), lDefaultHandler); ////////////////////////////////////////////////////////////////////// // If no exception was thrown the asset XML validates and // the creation should not fail due to XML formatting errors. ////////////////////////////////////////////////////////////////////// repository.assetCreateFromXML(authToken, assetXML); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Modify the metadata for an existing asset.
Example 4-10 Use Case: Modifying an Asset
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Categorization; import com.flashline.registry.openapi.entity.CategorizationType; import com.flashline.registry.openapi.query.CategorizationTypeCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ModifyExistingAsset { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); //////////////////////////////////////////////////////////// // Login to OER //////////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); //////////////////////////////////////////////////////////// // Read the asset you want to modify //////////////////////////////////////////////////////////// Asset myAsset = repository.assetRead(authToken, 559); // 559 is the example asset number //////////////////////////////////////////////////////////// // Modify the name, version, description, and notification // email //////////////////////////////////////////////////////////// myAsset.setName("New Name"); myAsset.setVersion("New Version"); myAsset.setDescription("New Description"); myAsset.setNotificationEmail("user@example.com"); //////////////////////////////////////////////////////////// // Modify Categorizations on the asset //////////////////////////////////////////////////////////// // Setup arrays used for assigning categorizations CategorizationType[] lAllCatTypes = null; Categorization[] lAllCats = null; CategorizationType[] lCatTypes = new CategorizationType[1]; Categorization[] lCats = new Categorization[1]; //////////////////////////////////////////////////////////// // Search for all categorizations that are asset assignable //////////////////////////////////////////////////////////// CategorizationTypeCriteria categorizationTypeCriteria = new CategorizationTypeCriteria(); categorizationTypeCriteria.setNameCriteria(""); lAllCatTypes = repository.categorizationTypeQuery(authToken, categorizationTypeCriteria); //////////////////////////////////////////////////////////// // Find all the categorizations to be assigned to the asset //////////////////////////////////////////////////////////// for (int i = 0; i < lAllCatTypes.length; i++) { CategorizationType lCatType = repository.categorizationTypeRead( authToken, lAllCatTypes[i].getID()); lAllCats = repository.categorizationReadByType(authToken, lCatType, true, true); if (lAllCats.length > 0) { lCatTypes[0] = lCatType; // when we find the first one, use it break; } } lCats[0] = lAllCats[0]; //////////////////////////////////////////////////////////// // Modify the asset to use the categorizations //////////////////////////////////////////////////////////// myAsset.setCategorizations(lCats); myAsset.setCategorizationTypes(lCatTypes); //////////////////////////////////////////////////////////// // Modify the custom access settings for the asset //////////////////////////////////////////////////////////// String[] lCasTypes = repository.customAccessSettingTypesGet(authToken); String[] lCustomAccessSettings = null; if (lCasTypes!=null && lCasTypes.length>0) { lCustomAccessSettings = repository.customAccessSettingNamesGet(authToken, lCasTypes[0]); } if (lCustomAccessSettings!=null && lCustomAccessSettings.length>0) { String[] myCustomAccessSettings = { lCustomAccessSettings[0] }; myAsset.setCustomAccessSettings(myCustomAccessSettings); } //////////////////////////////////////////////////////////// // Add producing projects to the asset //////////////////////////////////////////////////////////// long[] producingProjectsIDs = new long[1]; producingProjectsIDs[0] = 50000; myAsset.setProducingProjectsIDs(producingProjectsIDs); //////////////////////////////////////////////////////////// // save the modifications //////////////////////////////////////////////////////////// repository.assetUpdate(authToken, myAsset); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Multiple users can be assigned to an asset.
Example 4-11 Use Case: Assigning Users to an Asset
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AssignedUser; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.query.UserCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class AssignUsers { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); ////////////////////////////////////////////////////////// // Login to OER ////////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); ////////////////////////////////////////////////////////// // Retrieve desired asset ////////////////////////////////////////////////////////// Asset myAsset = repository.assetRead(authToken, 559); // 559 is the example asset number ////////////////////////////////////////////////////////// // Create array of AssignedUser objects ////////////////////////////////////////////////////////// AssignedUser[] lUsers = new AssignedUser[3]; ////////////////////////////////////////////////////////// // NOTE: // // The AssignedUser object has two methods: // setUserID(long) // setAssignedDate(Calendar). // (Specifies the date the user was assigned to the // asset. If no date is specified, the current date // is used.) ////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////// // Add AssignedUser objects to the array ////////////////////////////////////////////////////////// AssignedUser lUser = new AssignedUser(); lUser.setUserID(99); // 99 is the admin user id lUsers[0] = lUser; lUser = new AssignedUser(); RegistryUser lRegistryUser1 = createRegistryUser(repository, authToken); lUser.setUserID(lRegistryUser1.getID()); lUsers[1] = lUser; lUser = new AssignedUser(); RegistryUser lRegistryUser2 = createRegistryUser(repository, authToken); lUser.setUserID(lRegistryUser2.getID()); lUsers[2] = lUser; ////////////////////////////////////////////////////////// // Add array to the asset that is being updated ////////////////////////////////////////////////////////// myAsset.setAssignedUsers(lUsers); ////////////////////////////////////////////////////////// // save the modifications ////////////////////////////////////////////////////////// repository.assetUpdate(authToken, myAsset); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } protected static RegistryUser createRegistryUser(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { RegistryUser lRet = null; String lUserName = "user"+Calendar.getInstance().getTimeInMillis(); lRet = repository.userCreate(authToken, lUserName, "", lUserName, lUserName+"@example.com", lUserName, false, false, false); return lRet; } }
Finding all assets that meet certain criteria.
Example 4-12 Use Case: Building an Asset Search
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AssetSummary; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.query.AssetCriteria; import com.flashline.registry.openapi.query.DateRangeSearchTerm; import com.flashline.registry.openapi.query.SearchTerm; import com.flashline.registry.openapi.query.TabStatusSearchTerm; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class FindAssets { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); //////////////////////////////////////////////////////////// // Login to OER //////////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); //////////////////////////////////////////////////////////// // Search for all assets //////////////////////////////////////////////////////////// AssetCriteria criteria = new AssetCriteria(); AssetSummary[] assets = repository.assetQuerySummary(authToken, criteria); //////////////////////////////////////////////////////////// // try a general search which includes Name, version, // description, and keywords //////////////////////////////////////////////////////////// criteria = new AssetCriteria(); criteria.setGeneralCriteria("My Asset"); assets = repository.assetQuerySummary(authToken, criteria); //////////////////////////////////////////////////////////// // Search for assets that contain a specific search string // in one particular field. //////////////////////////////////////////////////////////// criteria = new AssetCriteria(); criteria.setNameCriteria("My Name"); criteria.setVersionCriteria("My version"); criteria.setDescriptionCriteria("My Description"); assets = repository.assetQuerySummary(authToken, criteria); //////////////////////////////////////////////////////////// // Implementing a Search through the AssetCriteria Object // -------------------------------------------------- // If no operator is specified when implementing a search // using the setSearchTerms method in the AssetCriteria // object, the system defaults to the operator EQUALS. // The operator LIKE must be specified if required for the // search. //////////////////////////////////////////////////////////// criteria = new AssetCriteria(); SearchTerm lSearchTerm = new SearchTerm(); lSearchTerm.setKey("name"); lSearchTerm.setOperator("LIKE"); lSearchTerm.setValue("Test"); SearchTerm[] lTerms = new SearchTerm[1]; lTerms[0] = lSearchTerm; criteria.setSearchTerms(lTerms); assets = repository.assetQuerySummary(authToken, criteria); //Search for assets where a specific DATETIME field is a given age ////////////////////////////////////////////////////////////////// criteria = new AssetCriteria(); //Not specifying an operator defaults to 'equals'. DateRangeSearchTerm lTerm = new DateRangeSearchTerm(); ///////////////////////// //date-range is the query key. registereddate is the date field we are searching on //Allowable fields to search on: //submitteddate //registereddate //accepteddate //createddate //updateddate //To do a search for all assets that were registered more than 5 days ago lTerm.setKey("date-range"); //Set the value to a day 5 days older than the current date. Assume today's date is 1/10/2007 //The format defaults to OER's system setting for Short Date Format. //The format can be set to any valid date format using setDateFormat() and passing the date format. lTerm.setDateFormat("yyyy-MM-dd"); lTerm.setBeginDate("2007-1-5"); lTerm.setBeginOperator("lt"); lTerm.setDateField("registereddate"); lTerms = new SearchTerm[1]; lTerms[0] = lTerm; criteria.setSearchTerms(lTerms); assets = repository.assetQuerySummary(authToken, criteria); //Search for assets where a given date field is within a date range ////////////////////////////////////////////////////////////////// criteria = new AssetCriteria(); lTerm = new DateRangeSearchTerm(); ///////////////////////// //date-range is the query key. registereddate is the date field we are searching on //Allowable fields to search on: //submitteddate //registereddate //accepteddate //createddate //updateddate //The following SearchTerm translates to "Assets where the registereddate is greater than or equal to Jan. 1, 2007 lTerm.setKey("date-range"); //The format defaults to OER's system setting for Short Date Format. //The format can be set to any valid date format using setDateFormat() and passing the date format. lTerm.setDateField("registereddate"); lTerm.setDateFormat("yyyy-MM-yy"); lTerm.setBeginDate("2007-01-01"); lTerm.setBeginOperator("gte"); lTerm.setEndDate("2007-01-10"); lTerm.setEndOperator("lte"); //The following SearchTerm translates to "Assets where the registereddate is less than or equal to Jan. 10, 2007 criteria.setSearchTerms(new SearchTerm[] {lTerm}); //This query returns all assets that were registered between January 1 and January 10, including those days. assets = repository.assetQuerySummary(authToken, criteria); //Search for assets where a given tab has been approved or unapproved ////////////////////////////////////////////////////////////////// criteria = new AssetCriteria(); TabStatusSearchTerm lTabTerm = new TabStatusSearchTerm(); //tabstatus is the type of search we want to do. overview is the name of the tab we want to search on lTabTerm.setKey("tabstatus"); lTabTerm.setTabNames(new String[] {"overview"}); lTabTerm.setApproved(true); criteria.setSearchTerms(new SearchTerm[] {lTabTerm}); //This query returns all assets with the Overview tab being approved assets = repository.assetQuerySummary(authToken, criteria); //You may also search by a date range. lTabTerm.setKey("tabstatus"); lTabTerm.setTabNames(new String[] {"overview"}); lTabTerm.setApproved(false); lTabTerm.setBeginDate("2007-1-01"); lTabTerm.setBeginOperator("lte"); criteria.setSearchTerms(new SearchTerm[] {lTabTerm}); //The following returns all assets that have the Overview tab unapproved since or before January 1, 2007 assets = repository.assetQuerySummary(authToken, criteria); //Search for assets where a custom field date has a specific value. //This test returns all assets that have a testdate of January 1, 2007. //The testdate field is a custom data date element. ////////////////////////////////////////////////////////////////// criteria = new AssetCriteria(); DateRangeSearchTerm lDateRangeTerm = new DateRangeSearchTerm(); //Test Equals lDateRangeTerm.setKey("/asset/custom-data/testdate"); lDateRangeTerm.setBeginDate("2007-01-1"); lDateRangeTerm.setBeginOperator("eq"); criteria.setSearchTerms(new SearchTerm[] {lDateRangeTerm}); assets = repository.assetQuerySummary(authToken, criteria); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Stepping an asset through status levels, from Unsubmitted to Submitted to Accepted to Registered.
Example 4-13 Use Case: Upgrading Asset Status
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.KeyValuePair; import com.flashline.registry.openapi.query.AssetCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class PromoteAsset { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); /////////////////////////////////////////////////////////// // Login to OER /////////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); long lAssetID = 559; // ------------------------------------------------------- // asset with id 559 would have to be unsubmitted for this to work AssetCriteria lAssetCriteria = new AssetCriteria(); lAssetCriteria.setIDCriteria(lAssetID); KeyValuePair lKeyValuePair = repository.assetEvaluate(authToken, lAssetCriteria, "Registration Status"); if (!lKeyValuePair.getValue().equalsIgnoreCase("unsubmitted")) { unregisterAsset(repository, authToken, lAssetID); } /////////////////////////////////////////////////////////// // promote the asset from unsubmitted to submitted /////////////////////////////////////////////////////////// repository.assetSubmit(authToken, lAssetID); // asset 559 would have to be unsubmitted for this to work /////////////////////////////////////////////////////////// // promote the asset from submitted to accepted /////////////////////////////////////////////////////////// repository.assetAccept(authToken, lAssetID); // asset 561 would have to be submitted for this to work /////////////////////////////////////////////////////////// // promote the asset from accepted to registered /////////////////////////////////////////////////////////// repository.assetRegister(authToken, lAssetID); // asset 563 would have to be accepted for this to work } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } protected static void unregisterAsset(FlashlineRegistry repository, AuthToken authToken, long pAssetID) { try { repository.assetUnRegister(authToken, pAssetID); } catch (Exception e) { } try { repository.assetUnAccept(authToken, pAssetID); } catch (Exception e) { } try { repository.assetUnSubmit(authToken, pAssetID); } catch (Exception e) { } } }
The reverse of the previous use case, stepping an asset through status levels, from Registered to Accepted to Submitted to Unsubmitted.
Example 4-14 Use Case: Downgrading Asset Status
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.KeyValuePair; import com.flashline.registry.openapi.query.AssetCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class DemoteAsset { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); /////////////////////////////////////////////////////////// // Login to OER /////////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); long lAssetID = 559; // ------------------------------------------------------- // asset with id 559 would have to be registered for this to work AssetCriteria lAssetCriteria = new AssetCriteria(); lAssetCriteria.setIDCriteria(lAssetID); KeyValuePair lKeyValuePair = repository.assetEvaluate(authToken, lAssetCriteria, "Registration Status"); if (!lKeyValuePair.getValue().equalsIgnoreCase("registered")) { registerAsset(repository, authToken, lAssetID); } /////////////////////////////////////////////////////////// // demote the asset from registered to accepted /////////////////////////////////////////////////////////// repository.assetUnRegister(authToken, lAssetID); /////////////////////////////////////////////////////////// // demote the asset from accepted to submitted /////////////////////////////////////////////////////////// repository.assetUnAccept(authToken, lAssetID); /////////////////////////////////////////////////////////// // demote the asset from submitted to unsubmitted /////////////////////////////////////////////////////////// repository.assetUnSubmit(authToken, lAssetID); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } protected static void registerAsset(FlashlineRegistry repository, AuthToken authToken, long pAssetID) { try { repository.assetSubmit(authToken, pAssetID); } catch (Exception e) { } try { repository.assetAccept(authToken, pAssetID); } catch (Exception e) { } try { repository.assetRegister(authToken, pAssetID); } catch (Exception e) { } } }
Compliance Templates can be added and removed from multiple projects.
Note:
An OpenAPIException occurs if an asset is applied to a project and that asset is NOT a Compliance Template.Example 4-15 Use Case: Applying and Removing Compliance Templates from a Project
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AssetType; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.query.AssetCriteria; import com.flashline.registry.openapi.query.AssetTypeCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class AddRemoveTemplate { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { URL lURL = null; lURL = new URL(pArgs[0]); /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); /////////////////////////////////////////////////////////// // Login to OER /////////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); /////////////////////////////////////////////////////////// // Read or Create a Compliance Template Type and Asset /////////////////////////////////////////////////////////// AssetType ctType = null; AssetTypeCriteria lAssetTypeCriteria = new AssetTypeCriteria(); lAssetTypeCriteria.setArcheTypeCriteria("Compliance Template Type"); AssetType[] lAssetTypes = repository.assetTypeQuery(authToken, lAssetTypeCriteria); if (lAssetTypes!=null && lAssetTypes.length>0) { ctType = lAssetTypes[0]; } else { ctType = repository.assetTypeCreateComplianceTemplate(authToken, "My Compliance Template Type"+Calendar.getInstance().getTimeInMillis()); } Asset lComplianceTemplateAsset = null; AssetCriteria lAssetCriteria = new AssetCriteria(); lAssetCriteria.setAssetTypeCriteria(ctType.getID()); Asset[] lAssets = repository.assetQuery(authToken, lAssetCriteria); if (lAssets!=null && lAssets.length>0) { lComplianceTemplateAsset = lAssets[0]; } else { lComplianceTemplateAsset = repository.assetCreate(authToken, "My Compliance Template", ""+Calendar.getInstance().getTimeInMillis(), ctType.getID()); } /////////////////////////////////////////////////////////// // Create a String array of Project IDs that the Compliance // Template is applied to. /////////////////////////////////////////////////////////// String[] lProjectIDs = { "50000" }; // ///////////////////////////////////////////////////////// // Apply template to the projects. // ///////////////////////////////////////////////////////// repository.assetApplyToProjects(authToken, lProjectIDs, lComplianceTemplateAsset); /////////////////////////////////////////////////////////// // Retrieve an array of Projects that this template is // applied to. /////////////////////////////////////////////////////////// Project[] lProjects = repository.assetReadAppliedToProjects( authToken, lComplianceTemplateAsset); String lMsg = "Compliance Template '" + lComplianceTemplateAsset.getName(); lMsg += "' applied to Project(s): "; for (int i=0; lProjects!=null && i<lProjects.length; i++) { lMsg += ""+lProjects[i].getName()+(i+1==lProjects.length ? "." : ", "); } System.out.println(lMsg); /////////////////////////////////////////////////////////// // Create a String array of Project IDs that the Compliance // Template is removed from. /////////////////////////////////////////////////////////// String[] lRemoveProjectIDs = { "50000" }; /////////////////////////////////////////////////////////// // Remove template from the projects. /////////////////////////////////////////////////////////// repository.assetRemoveAppliedToProjects(authToken, lRemoveProjectIDs, lComplianceTemplateAsset); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Update the repository to reflect the availability of a new version of an asset, and the retirement of the asset's previous version.
Example 4-16 Use Case: Creating a New Version of an Asset
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.RelationshipType; import com.flashline.registry.openapi.query.RelationshipTypeCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CreateNewVersionOfAsset { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); /////////////////////////////////////////////////////////// // Login to OER /////////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); /////////////////////////////////////////////////////////// // Read old asset. // Update metadata as necessary. // Save as new asset. /////////////////////////////////////////////////////////// Asset myAsset = repository.assetRead(authToken, 561); /////////////////////////////////////////////////////////// // Find the "next-version" relationship for the asset /////////////////////////////////////////////////////////// RelationshipType[] allRelationshipTypes = getAllRelationshipTypes(repository, authToken); for (int i = 0; i < allRelationshipTypes.length; i++) { if (allRelationshipTypes[i].getName().equals("next-version")) { /////////////////////////////////////////////////////////// // This is the relationship type, modify the assets that are related // using it /////////////////////////////////////////////////////////// RelationshipType myRelationshipType = allRelationshipTypes[i]; /////////////////////////////////////////////////////////// // Add the old version to list of previous versions of the // newly created asset /////////////////////////////////////////////////////////// long[] oldSecondaryIDs = myRelationshipType.getSecondaryIDs(); long[] newSecondaryIDs = new long[oldSecondaryIDs.length + 1]; for (int j = 0; j < oldSecondaryIDs.length; j++) { newSecondaryIDs[j] = oldSecondaryIDs[j]; } newSecondaryIDs[newSecondaryIDs.length - 1] = 561; myRelationshipType.setSecondaryIDs(newSecondaryIDs); } } Asset myNewAsset = repository.assetCreate(authToken, myAsset.getName(), ""+Calendar.getInstance().getTimeInMillis(), myAsset.getTypeID()); myNewAsset.setRelationshipTypes(allRelationshipTypes); /////////////////////////////////////////////////////////// // Update the new asset /////////////////////////////////////////////////////////// myNewAsset = repository.assetUpdate(authToken, myNewAsset); /////////////////////////////////////////////////////////// // retire the old asset /////////////////////////////////////////////////////////// repository.assetRetire(authToken, 561); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } /** * This method returns every relationship type in the repository * @param repository * @param authToken * @return * @throws RemoteException */ public static RelationshipType[] getAllRelationshipTypes(FlashlineRegistry repository, AuthToken authToken) throws RemoteException { //Create an empty relationship type criteria object RelationshipTypeCriteria criteria = new RelationshipTypeCriteria(); criteria.setNameCriteria(""); RelationshipType[] allRelationshipTypes = repository.relationshipTypeQuery(authToken, criteria); return allRelationshipTypes; } }
Deleting groups of assets that no longer belong in the repository.
Example 4-17 Use Case: Deleting Unneeded Assets from the Repository
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.query.AssetCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class DeleteAssets { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); /////////////////////////////////////////////////////////// // Login to OER /////////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); /////////////////////////////////////////////////////////// // find the assets to delete /////////////////////////////////////////////////////////// AssetCriteria criteria = new AssetCriteria(); criteria.setGeneralCriteria("delete me"); Asset[] assets = repository.assetQuery(authToken, criteria); /////////////////////////////////////////////////////////// // Iterate through assets, deleting them one at a time. /////////////////////////////////////////////////////////// for (int i = 0; i < assets.length; i++) { repository.assetDelete(authToken, assets[i].getID()); } } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Asset deletion is permanent. The OpenAPI provides no method for restoring deleted assets.
The following methods serve no purpose in the context of the OpenAPI, and should therefore be avoided:
setAcceptedByID
setAcceptedByName
setAcceptedByDate
setActiveStatus
setAssigned
setAssignedToID
setAssignedDate
setCategorizationTypes
setCreatedByID
setCreatedByName
setCreatedByDate
setDeleted
setEntityType
setExtractable
setFullAsset
setInactive
setKey
setLoadedDate
setLongName
setNotifyUpdatedRelationships
setRegisteredByID
setRegisteredByName
setRegisteredDate
setRegistrationStatus
setRegistrationStatusBaseName
setRegistrationStatusRegistered
setRegistrationStatusRejected
setRegistrationStatusSubmittedPendingReview
setRegistrationStatusSubmittedUnderReview
setRegistrationStatusUnsubmitted
setRejectionReason
setRetired
setSubmittedByID
setSubmittedByName
setSubmittedDate
setTypeIcon
setTypeName
setUpdatedDate
setVendorName
setVisible
Rules for Assets
The Asset must be assigned to an active and valid Asset Type.
An Asset's name/version strings must be a unique pair.
A new Asset's ID must be 0.
A new Asset's active status must be 'active'.
Helper methods for modifying customData
Additional validation
When saving an asset, Oracle Enterprise Repository currently validates that:
The Asset type is valid and active
# The Name/Version is unique
When creating an asset, that the active status is valid
When updating an asset, that the asset already exists
Contacts are not duplicated
Categorizations are valid
Future versions of the repository validates that:
CustomData is well formed XML
CustomData contains XML that is valid based on the asset type
Perform a search for all assets with a specific custom-data value, and update some custom-data for each of those assets. Note: The asset is automatically saved when using the assetUpdateCustomDataNode method.
Example 4-18 Use Case: Finding Assets and Updating Common-Data
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AssetSummary; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.query.AssetCriteria; import com.flashline.registry.openapi.query.SearchTerm; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class UpdateAssetTestResults { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); /////////////////////////////////////////////////////////// // Login to OER /////////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); /////////////////////////////////////////////////////////// // create a criteria object searching for all assets with a // custom-data element for test-frequency equal to 'DAILY' /////////////////////////////////////////////////////////// SearchTerm[] searchTermArray = new SearchTerm[1]; SearchTerm term = new SearchTerm(); term.setKey("/asset/custom-data/test-frequency"); term.setValue("DAILY"); searchTermArray[0] = term; AssetCriteria criteria = new AssetCriteria(); criteria.setSearchTerms(searchTermArray); /////////////////////////////////////////////////////////// // perform search, getting back summary objects. loop through // objects and perform an action on each one /////////////////////////////////////////////////////////// AssetSummary[] assets = repository.assetQuerySummary(authToken, criteria); /////////////////////////////////////////////////////////// // Loop through search results /////////////////////////////////////////////////////////// for (int i = 0; i < assets.length; i++) { long assetID = assets[i].getID(); String testResult = null; /////////////////////////////////////////////////////////// // Update value in the asset /////////////////////////////////////////////////////////// repository.assetUpdateCustomDataNode( authToken, assetID, "/asset/custom-data/test-result", testResult); } } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Read the tabs of an asset.
Example 4-19 Use Case: Reading an Asset's Tabs
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.TabBean; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class AssetReadTabs { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); TabBean[] lTabBeans = null; /////////////////////////////////// // Login to OER /////////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1],pArgs[2]); /////////////////////////////////// // read an asset's tabs /////////////////////////////////// lTabBeans = repository.assetTabsRead(authToken, 559); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Get a specific asset tab by tabtype.
Example 4-20 Use Case: Retrieving an Asset's Tab Based on Tab Type
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.TabBean; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class AssetGetTabByType { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); Asset lAsset = null; TabBean lTabBean = null; /////////////////////////////////// // Login to OER /////////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1],pArgs[2]); /////////////////////////////////// // read an asset /////////////////////////////////// lAsset = repository.assetRead(authToken, 559); /////////////////////////////////// // get an asset's tab by tabbeantype /////////////////////////////////// lTabBean = repository.assetTabRead(authToken, lAsset.getID(), 458); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Approve or unapprove an asset's tab.
Example 4-21 Use Case: Approving and Unapproving a Tab
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ApproveUnapproveTab { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); /////////////////////////////////// // Login to OER /////////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1],pArgs[2]); /////////////////////////////////// // approve an asset tab /////////////////////////////////// repository.assetTabApprove(authToken, 559, 1864); /////////////////////////////////// // unapprove an asset tab /////////////////////////////////// repository.assetTabUnapprove(authToken, 559, 1864); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Read the metadata of an asset based on the given tab.
Example 4-22 Use Case: Reading an Asset's Metadata for a Given Tab
package com.flashline.sample.assetapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AssetMetadataElement; import com.flashline.registry.openapi.entity.AssetMetadataTableElement; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class AssetGetMetadataByTab { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); Asset lAsset = null; /////////////////////////////////// // Login to OER /////////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1],pArgs[2]); /////////////////////////////////// // read an asset /////////////////////////////////// lAsset = repository.assetRead(authToken, 589); /////////////////////////////////// // Get the metadata elements based // on the asset ID and the tab name /////////////////////////////////// AssetMetadataElement[] lElements = repository.assetReadTabMetadata(authToken, lAsset.getID(), "Overview"); //An AssetMetadataElement represents a custom or mandatory data element of an asset for (AssetMetadataElement lElement : lElements) { //This represents a TABLE element type if (lElement.getValue() instanceof AssetMetadataTableElement) { AssetMetadataTableElement lTable = (AssetMetadataTableElement)lElement.getValue(); System.out.println(lElement.getDisplayName()); //A TABLE can have multiple elements for (AssetMetadataElement lTableElement : lTable.getElements()) { //An element of a TABLE can be another TABLE if (lTableElement.getValue() instanceofAssetMetadataTableElement) { System.out.println(((AssetMetadataTableElement)lTableElement.getValue()).getDisplayName()); for (AssetMetadataElement lChildElement : ((AssetMetadataTableElement)lTableElement.getValue()).getElements()) { System.out.println(lChildElement.getDisplayName() + " : " + lChildElement.getValue()); } } else { //Or an element of a TABLE can be a regular value System.out.println(lTableElement.getDisplayName() + " : " + lTableElement.getValue()); } } //This represents a MULTIPLE ITEM LIST } else if (lElement.getValue() instanceof String[]) { System.out.println(lElement.getDisplayName()); for (String lString : (String[])lElement.getValue()) { System.out.println(lString); } //This represents a SINGLE ITEM } else { System.out.println(lElement.getDisplayName() + " : " + lElement.getValue()); } } } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
This section provides use cases for the AssetType API that describe how to add a new type to the repository, create a new compliance template type, locate a type, retrieve the list of tabs available for an asset type, and retrieve all asset type tabs within the Oracle Enterprise Repository.
Types (Asset Types and Compliance Templates) define the structure of assets. Types consist of two main parts:
Editor
Defines the metadata that is stored for the assets and determines how metadata elements are organized in the Asset Editor.
Viewer
Defines how the metadata elements are displayed in the asset detail in Oracle Enterprise Repository.
When creating or editing a Type, acceptable value lists and categorization types are used as metadata elements. These metadata elements are referenced by ID in the Editor and Viewer XML for the Type.When creating or editing assets, Types define the metadata elements that are used in the custom data for the asset (Asset.GetCustomData()).
Note:
While the code examples in this section refer to Asset Types, be aware that the processes described in the use cases are used to create both Asset Types and Compliance Templates. For more information about Compliance Templates, see Oracle Fusion Middleware Administrator's Guide for Oracle Enterprise Repository.
Editor and viewer metadata is represented as CDATA escaped XML. Consequently, if a large number of AssetTypes are returned through a call to assetTypeQuery, it is possible that some XML parsers may exceed their entity expansion limit. On some popular parsers, the default entity expansion limit is set to 64,000. If this limit is exceeded, it can be increased on JAXP compliant processors by passing a command-line parameter called entityExpansionLimit. For example, passing the following parameter to the JVM increases the entity expansion limit to 5 MB:
java -DentityExpansionLimit=5242880 com.example.MyApp
This section describes the use cases using the Asset Type API. It contains the following topics:
Adding a new Type to the repository.
Example 4-23 Use Case: Create and Edit a New Type
package com.flashline.sample.assettypeapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AssetType; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CreateNewAssetType { public static void main(String pArgs[]) throws RemoteException, OpenAPIException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ////////////////////////////// // Select an existing Type on which to base the new one // ////////////////////////////// String newAssetTypeName = "My AssetType"; long baseAssetTypeID = 151; AssetType newAssetType = repository.assetTypeCreateClone( authToken, baseAssetTypeID, newAssetTypeName); System.out.println("The new Asset Type id =\"" + newAssetType.getID() + "\""); // ////////////////////////////// // Manipulate xml strings // ////////////////////////////// String lEditorXML = newAssetType.getEditorXML(); String lViewerXML = newAssetType.getViewerXML(); // Perform XML manipulation on the editor and viewer definitions... // ////////////////////////////// // Set the new editor/viewer definitions on the asset type, and save the // type back to OER // ////////////////////////////// newAssetType.setEditorXML(lEditorXML); newAssetType.setViewerXML(lViewerXML); repository.assetTypeUpdate(authToken, newAssetType); // ---------------------------------------- // clean up sample repository.assetTypeDelete(authToken, newAssetType.getID()); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Adding a new Compliance Template Type to the repository.
Example 4-24 Use Case: Create a Compliance Template Type
package com.flashline.sample.assettypeapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AssetType; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CreateNewComplianceTemplateType { public static void main(String pArgs[]) throws RemoteException, OpenAPIException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL( pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ////////////////////////////// // Create a new compliance template. // ////////////////////////////// String newAssetTypeName = "My Compliance Template"+Calendar.getInstance().getTimeInMillis(); AssetType newAssetType = repository .assetTypeCreateComplianceTemplate(authToken, newAssetTypeName); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Locating a Type in the repository.
Example 4-25 Use Case: Locate a Type
package com.flashline.sample.assettypeapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AssetType; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.query.AssetTypeCriteria; import com.flashline.registry.openapi.query.SearchTerm; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class FindAssetType { public static void main(String pArgs[]) throws RemoteException, OpenAPIException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ////////////////////////////// // Create SearchTerms and set them on the AssetSearchCriteria // ////////////////////////////// AssetTypeCriteria assetTypeCriteria = new AssetTypeCriteria(); SearchTerm[] searchTerms = new SearchTerm[1]; searchTerms[0] = new SearchTerm(); searchTerms[0].setKey("name"); searchTerms[0].setValue("Component"); assetTypeCriteria.setSearchTerms(searchTerms); // ////////////////////////////// // Perform the search using the specified criteria // ////////////////////////////// AssetType[] assetTypes = repository.assetTypeQuery(authToken, assetTypeCriteria); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
setIcon
setID
Retrieve the list of tabs available for an asset type.
Example 4-26 Use Case: Retrieve a List of Tabs for an Asset Type
package com.flashline.sample.assettypeapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.TabTypeBean; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ReadTabTypes { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); TabTypeBean[] lTabTypeBeans = null; /////////////////////////////////// // Login to OER /////////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1],pArgs[2]); /////////////////////////////////// // read the tab types of an assettype /////////////////////////////////// lTabTypeBeans = repository.assetTypeTabsRead(authToken, 100); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Retrieves all asset type tabs within the Oracle Enterprise Repository.
Example 4-27 Use Case: Retrieve All Asset Type Tabs
package com.flashline.sample.assettypeapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.TabTypeBean; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ReadTabTypes { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); TabTypeBean[] lTabTypeBeans = null; /////////////////////////////////// // Login to OER /////////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1],pArgs[2]); /////////////////////////////////// // read the tab types of an assettype /////////////////////////////////// lTabTypeBeans = repository.assetTypeTabsRead(authToken, 100); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Example of the RelationshipTypeQuery
try { RelationshipTypeCriteria rCriteria = new RelationshipTypeCriteria(); RelationshipType[] allRelationshipTypes = FlashlineRegistry.relationshipQuery(lAuthToken, rCriteria); } catch (OpenAPIException e) { e.printStackTrace(); } catch (RemoteException re) { re.printStackTrace(); }
This section provides use cases for the Categorization Types and Categorizations API that describe how to create a categorization type, manipulate categorizations, and manipulate categorization types.
It is important to understand the difference between Categorizations and Categorization Types.
Categorization Types provide the means to define custom taxonomies. Categorizations are subsets of Categorization Types, and are assigned to assets. For example, a Categorization Type called Technology might contain Java, .NET and COBOL as its assignable Categorizations. Additionally, sub-categorizations under Java might include Servlet and Applet. So an asset in Oracle Enterprise Repository might be assigned to the Java Categorization, or it might be more specifically assigned to the Servlet Sub-categorization.
The Categorizations to which a particular asset may be assigned are determined by the Categorization Types defined for that asset's Type. As in the example above, if the Technology Categorization Type is defined for Asset Type XYZ, assets of type XYZ may be assigned to the Java, .NET, or COBOL, Categorizations, or to the Sub-categorizations Servlet or Applet. This taxonomy structure enables assets to be grouped and viewed in a variety of ways within Oracle Enterprise Repository.
Categorization types can also be associated with projects (if Oracle Enterprise Repository is configured for that feature). Any project-assignable Categorization Type is available to all projects. As with assets, a project can be associated with any of the Categorizations available within its assigned Categorization Type(s).
Rules for Categorization Types and Categorizations include:
The Repository can contain 0 to n Categorization Types with each Categorization Type containing 0 to n Categorizations.
Each Categorization can contain 0 to n Sub-categorizations.
Each Categorization Type must have a unique name. This name cannot contain spaces or special characters.
As an option, Categorizations within a given Categorization Type may be made mutually exclusive. That is, when a list of Categorizations is presented, only one may be selected.
When the Mutually Exclusive option is selected for a Categorization Type, Oracle Enterprise Repository enforces the rule for future usage only. Existing references to multiple selected categorizations within the Type are unchanged.
When so configured, Categorization Types can be assigned to projects. This enables projects in Oracle Enterprise Repository to be organized by Categorization Type/Categorization.
If the configuration of a specific Categorization Type is changed to prevent its assignment to Projects, the change affects only subsequent Project assignment. The change does not affect the Categorization Type's assignment to existing Projects.
Categorization Types may be deleted from Oracle Enterprise Repository. However, doing so also deletes all categorizations within the deleted Categorization Type. Exercise caution when performing this task.
Categorizations may be deactivated. Deactivation prevents future use of the Categorization (and all sub-categorizations) but does not delete it from Oracle Enterprise Repository. Existing references to a Categorization are unaffected by deactivation.
Deactivated Categorizations may be reactivated, reversing the aforementioned process.
Within a given Categorization Type, all Categorizations must be uniquely named. However, the same name may be shared by multiple Categorizations residing in different Categorization Types.
The following methods provide the ability to create, update, list, query, and delete categorization types.
This section describes the use cases using the Categorization Types and Categorizations API. It includes the following topics:
The element name given to a newly created Categorization Type cannot contain special characters or spaces. There are no restrictions on the characters used for singular and plural display names. The pExclusiveAssign Boolean determines whether one or multiple Categorizations can be assigned within the Categorization Type. The pExclusiveAssign Boolean determines if the Categorization Type is project-assigned. The method prevents duplication of existing Categorizations, and returns the created Categorization Type.
Example 4-28 Use Case: Create a Categorization Type
package com.flashline.sample.categorizationtypesandapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.CategorizationType; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CreateCategorizationType { public static void main(String pArgs[]) throws java.rmi.RemoteException, OpenAPIException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ////////////////////////////// // Create the categorization type // ////////////////////////////// String pName = "Name"; String pSingularDisplay = "SingularDisplay"; String pPluralDisplay = "PluralDisplay"; boolean pExclusiveAssign = true; boolean pProjectAssign = true; CategorizationType lCategorizationType = repository.categorizationTypeCreate(authToken, pName, pSingularDisplay, pPluralDisplay, pExclusiveAssign, pProjectAssign); // ---------------------------------------- // clean up repository.categorizationTypeDelete(authToken, lCategorizationType); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
The following operations are demonstrated in the example below:
Retrieve Categorization Types by ID
Update a Categorization Type
Delete a Categorization Type
Exercise Caution! This method deletes the entire Categorization Type and all Categorizations contained therein.
Query a Categorization Type
Use various terms, including name, type, and if a Categorization Type is assigned to projects.
Retrieve all Categorization Types
Example 4-29 Use Case: Manipulate Categorization Types
package com.flashline.sample.categorizationtypesandapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Categorization; import com.flashline.registry.openapi.entity.CategorizationType; import com.flashline.registry.openapi.query.CategorizationTypeCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CategorizationExamples { public static void main(String pArgs[]) throws ServiceException, RemoteException, OpenAPIException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ////////////////////////////// // Create a Categorization Type // ////////////////////////////// CategorizationType categorizationType = repository .categorizationTypeCreate(authToken, "exampleType", "Example Type", "Example Types", false, true); // ////////////////////////////// // Find and update a categorization type // ////////////////////////////// CategorizationTypeCriteria categorizationTypeCriteria = new CategorizationTypeCriteria(); boolean projectAssign = true; categorizationTypeCriteria.setProjectAssignCriteria(projectAssign + ""); CategorizationType[] categorizationTypes = repository .categorizationTypeQuery(authToken, categorizationTypeCriteria); // Set plural display name categorizationType.setDisplayPlural("Updated Example Types"); // Set singular display name categorizationType.setDisplaySingular("Updated Example Type"); // Set Categorization Type name categorizationType.setName("updatedExampleType"); // Set Categorization Type exclusive assign categorizationType.setExclusiveAssign(true); // Set Categorization Type project Assignable categorizationType.setProjectAssignable(false); // Update Categorization Type categorizationType = repository.categorizationTypeUpdate( authToken, categorizationType); // Read a Categorization Type CategorizationType categorizationTypeRead = repository .categorizationTypeRead(authToken, categorizationType.getID()); // ////////////////////////////// // Create a Categorization within a Categorization Type // ////////////////////////////// Categorization categorization = repository.categorizationCreate( authToken, "Example Categorization", categorizationType); // ////////////////////////////// // Create a Categorization within a Categorization (a.k.a. a // sub-categorization or child categorization) // // method validates that: // - no child categorization with the same name exists within the // parent categorization. // - the categorization type is valid // - the parent categorization is valid. // ////////////////////////////// Categorization childCategorization = repository .categorizationChildCreate(authToken, "Example Child Categorization", categorizationType, categorization); childCategorization.setName("Updated Example Child Categorization"); childCategorization = repository.categorizationUpdate(authToken, childCategorization, categorizationType); // ////////////////////////////// // Observe various properties of a categorization. Note that the // properties are not being assigned to local variables in // the interest of brevity... // ////////////////////////////// Categorization categorizationRead = repository.categorizationRead( authToken, childCategorization.getID()); // Get Categorization parent id //categorizationRead.getParentID(); // Get Categorization active status categorizationRead.getActiveStatus(); // Get Categorization ID categorizationRead.getID(); // Get Categorization name categorizationRead.getName(); // Get Categorization recursive name categorizationRead.getRecursiveName(); // Get Categorization Categorization Type ID categorizationRead.getTypeID(); // ////////////////////////////// // Retrieve the full tree of categorizations for a Categorization Type. // This means that the Categorization entity returned has children // which contain their children (if any), and so on. // ////////////////////////////// // Get active Categorizations full tree boolean active = true; boolean fullTree = true; Categorization[] categorizationArray = repository.categorizationReadByType( authToken, categorizationType, active, fullTree); // Get children categorizations for categorization Categorization[] childCategorizations = repository.categorizationChildRead(authToken, categorizationType, categorization, active); // ////////////////////////////// // Deactivate a Categorization // ////////////////////////////// categorization = repository.categorizationDeactivate(authToken, categorization, categorizationType); // pActive is set to "true" so that the method returns // only active categorizations Categorization[] activeCategorizations = repository .categorizationChildRead(authToken, categorizationType, categorization, true); // Get inactive child Categorizations Categorization[] inactiveCategorizations = repository.categorizationChildRead(authToken, categorizationType, categorization, false); // ///////////////////////////// // Reactivate Categorizations // ///////////////////////////// for(int i=0; i<inactiveCategorizations.length; i++){ categorization = repository.categorizationReactivate(authToken, inactiveCategorizations[i], categorizationType); } // ////////////////////////////// // Delete a Categorization Type // ////////////////////////////// repository.categorizationTypeDelete(authToken, categorizationType); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
The methods listed below are for internal Oracle Enterprise Repository use only. Incorrect use of these methods may disrupt the functionality of Categorization Types (though permanent damage is unlikely). The functionality provided by these methods is incorporated in the Oracle Enterprise Repository CategorizationType methods.
getActiveStatus() int - CategorizationType
getCategorizations() Categorizations[] - CategorizationType
GetEntityType() String - CategorizationType
getKey() String - CategorizationType
getTypeDesc() TypeDesc - CategorizationType
hashCode() int - CategorizationType
isCustom() boolean - CategorizationType
isFlat() boolean - CategorizationType
isSystemOnly() boolean - CategorizationType
setActiveStatus(int activeStatus) void - CategorizationType
setAssetAssignable(boolean assetAssignable) void - CategorizationType
setCategorizations(Categorizations[] categorizations) void - CategorizationType
setCustom(boolean custom) void - CategorizationType
setEntityType(String entityType) void - CategorizationType
setFlat(boolean flat) void - CategorizationType
setID(long ID) void - CategorizationType
setKey(String key) void - CategorizationType
setSystemOnly(boolean systemOnly) void - CategorizationType
The following code sample illustrates creation, updating, listing, and deactivation/reactivation of Categorizations. As stated above, Categorizations are subordinate to Categorization Types. That is, a Categorization belongs to a Categorization Type.
Example 4-30 Use Case: Manipulate Categorizations
package com.flashline.sample.categorizationtypesandapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Categorization; import com.flashline.registry.openapi.entity.CategorizationType; import com.flashline.registry.openapi.query.CategorizationTypeCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CategorizationExamples { public static void main(String pArgs[]) throws ServiceException, RemoteException, OpenAPIException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ////////////////////////////// // Create a Categorization Type // ////////////////////////////// CategorizationType categorizationType = repository .categorizationTypeCreate(authToken, "exampleType", "Example Type", "Example Types", false, true); // ////////////////////////////// // Find and update a categorization type // ////////////////////////////// CategorizationTypeCriteria categorizationTypeCriteria = new CategorizationTypeCriteria(); boolean projectAssign = true; categorizationTypeCriteria.setProjectAssignCriteria(projectAssign + ""); CategorizationType[] categorizationTypes = repository .categorizationTypeQuery(authToken, categorizationTypeCriteria); // Set plural display name categorizationType.setDisplayPlural("Updated Example Types"); // Set singular display name categorizationType.setDisplaySingular("Updated Example Type"); // Set Categorization Type name categorizationType.setName("updatedExampleType"); // Set Categorization Type exclusive assign categorizationType.setExclusiveAssign(true); // Set Categorization Type project Assignable categorizationType.setProjectAssignable(false); // Update Categorization Type categorizationType = repository.categorizationTypeUpdate( authToken, categorizationType); // Read a Categorization Type CategorizationType categorizationTypeRead = repository .categorizationTypeRead(authToken, categorizationType.getID()); // ////////////////////////////// // Create a Categorization within a Categorization Type // ////////////////////////////// Categorization categorization = repository.categorizationCreate( authToken, "Example Categorization", categorizationType); // ////////////////////////////// // Create a Categorization within a Categorization (a.k.a. a // sub-categorization or child categorization) // // method validates that: // - no child categorization with the same name exists within the // parent categorization. // - the categorization type is valid // - the parent categorization is valid. // ////////////////////////////// Categorization childCategorization = repository .categorizationChildCreate(authToken, "Example Child Categorization", categorizationType, categorization); childCategorization.setName("Updated Example Child Categorization"); childCategorization = repository.categorizationUpdate(authToken, childCategorization, categorizationType); // ////////////////////////////// // Observe various properties of a categorization. Note that the // properties are not being assigned to local variables in // the interest of brevity... // ////////////////////////////// Categorization categorizationRead = repository.categorizationRead( authToken, childCategorization.getID()); // Get Categorization parent id //categorizationRead.getParentID(); // Get Categorization active status categorizationRead.getActiveStatus(); // Get Categorization ID categorizationRead.getID(); // Get Categorization name categorizationRead.getName(); // Get Categorization recursive name categorizationRead.getRecursiveName(); // Get Categorization Categorization Type ID categorizationRead.getTypeID(); // ////////////////////////////// // Retrieve the full tree of categorizations for a Categorization Type. // This means that the Categorization entity returned has children // which contain their children (if any), and so on. // ////////////////////////////// // Get active Categorizations full tree boolean active = true; boolean fullTree = true; Categorization[] categorizationArray = repository.categorizationReadByType( authToken, categorizationType, active, fullTree); // Get children categorizations for categorization Categorization[] childCategorizations = repository.categorizationChildRead(authToken, categorizationType, categorization, active); // ////////////////////////////// // Deactivate a Categorization // ////////////////////////////// categorization = repository.categorizationDeactivate(authToken, categorization, categorizationType); // pActive is set to "true" so that the method returns // only active categorizations Categorization[] activeCategorizations = repository .categorizationChildRead(authToken, categorizationType, categorization, true); // Get inactive child Categorizations Categorization[] inactiveCategorizations = repository.categorizationChildRead(authToken, categorizationType, categorization, false); // ///////////////////////////// // Reactivate Categorizations // ///////////////////////////// for(int i=0; i<inactiveCategorizations.length; i++){ categorization = repository.categorizationReactivate(authToken, inactiveCategorizations[i], categorizationType); } // ////////////////////////////// // Delete a Categorization Type // ////////////////////////////// repository.categorizationTypeDelete(authToken, categorizationType); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
The methods listed below are for internal Oracle Enterprise Repository use only and should not be used. Incorrect use of these methods could cause improper functioning of categorizations. The functions provided by these methods provide are incorporated in the Oracle Enterprise Repository categorization methods.
getDescription() String - Categorization
GetEntityType() String - Categorization
getKey() String - Categorization
getLevel() long - Categorization
getType() CategorizationType - Categorization
getTypeDesc() TypeDesc - Categorization
hashCode() int - Categorization
set_super(Categorization _super) void - Categorization
setActiveStatus(int activeStatus) void - Categorization
setDeleted(boolean deleted) void - Categorization
setDescription(String description) void - Categorization
setEntityType(String entityType) void - Categorization
setID(long ID) void - Categorization
setKey(String key) void - Categorization
setRecursiveName(String recursiveName) void - Categorization
setType(CategorizationType type) void - Categorization
setTypeID(long ID) void - Categorization
This section provides a use case for the CMF Entry Type API and describes how to add a new CMF entry type to Oracle Enterprise Repository and assign an existing CMF entry type to an asset.
CMF Entry Types describe metadata that may be attached to assets. CMF Entry Types are identified by an ID and a single name string.
Validation - When saving a CMF Entry Type, Oracle Enterprise Repository currently validates that:
The CMF Entry Type name length is in bounds
The CMF Entry Type name is unique
When updating a CMF Entry Type, a CMF Entry Type ID is present
A CMF Entry is linked to an asset from the perspective of the asset. CMF Entry Types define parameters for these entries.
import com.flashline.registry.openapi.entity.MetadataEntryTypeSummary; import com.flashline.registry.openapi.query.MetadataEntryTypeCriteria;
This section describes the use case using the CMF Entry Type API.
Adding a new CMF Entry Type to Oracle Enterprise Repository.
Assigning an existing CMF Entry Type to an asset.
Example 4-31 Use Case: Manipulate CMF Entry Types
package com.flashline.sample.metadataentrytypeapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.MetadataEntryTypeSummary; import com.flashline.registry.openapi.query.MetadataEntryTypeCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class MetadataEntryTypes { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1],pArgs[2]); // ----------------------------------------- // Create a new CMF Entry Type String newMetadataEntryTypeName = "Sample MetadataEntryType"; MetadataEntryTypeSummary newMetadataEntryType = repository.metadataEntryTypeCreate(authToken, newMetadataEntryTypeName); System.out.println("The new MetadataEntryType id =\"" + newMetadataEntryType.getID() + "\""); // ----------------------------------------- // Find a CMF Entry Type MetadataEntryTypeCriteria criteria = new MetadataEntryTypeCriteria(); criteria.setNameCriteria("Sample"); MetadataEntryTypeSummary[] metadataEntryTypes = repository.metadataEntryTypeQuery(authToken, criteria); long myMetadataEntryTypeID = metadataEntryTypes[0].getID(); // ----------------------------------------- // Read a CMF Entry Type MetadataEntryTypeSummary readMetadataEntryType = repository.metadataEntryTypeRead(authToken, myMetadataEntryTypeID); System.out.println("The MetadataEntryType name =\"" + readMetadataEntryType.getName() + "\""); // ----------------------------------------- // Delete a CMF Entry Type repository.metadataEntryTypeDelete(authToken, myMetadataEntryTypeID); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
This section provides use cases for the Custom Access Settings API and describes how to retrieve the list of custom access settings types and retrieve the list of default custom access settings of a particular type in the Oracle Enterprise Repository.
The Custom Access Settings subsystem is used to provide a web services-based mechanism to retrieve Oracle Enterprise Repository Custom Access Settings (CAS). Example 4-32 describes a sample Custom Access Settings code.
Example 4-32 Example of Custom Access Settings Code
Working code for Custom Access Settings Open API methods.
package com.flashline.sample.customaccesssettingsapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CustomAccesssettings { public static void main(String pArgs[]) throws java.rmi.RemoteException, OpenAPIException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); // //////////////////////////////////////////////////////////// // Retrieve a List of Custom Access Setting Types // //////////////////////////////////////////////////////////// String[] lRoleContextTypes = null; lRoleContextTypes = repository .customAccessSettingTypesGet(authToken); // //////////////////////////////////////////////////////////// // Get Custom Access Setting Names // //////////////////////////////////////////////////////////// String[] lCustomAccessSettingNames = null; lCustomAccessSettingNames = repository .customAccessSettingNamesGet(authToken, "asset"); // //////////////////////////////////////////////////////////// // Retrieve an array of Custom Access Setting Names of type "asset". // //////////////////////////////////////////////////////////// String[] rCustomAccessSettingNames = null; rCustomAccessSettingNames = repository .customAccessSettingDefaultNamesGet(authToken, "asset"); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
This method is used to retrieve the list of Custom Access Settings Types as available in Oracle Enterprise Repository.
1. String[] lCustomAccessSettingNames = null; 2. lCustomAccessSettingNames = mFlashlineRegistry.customAccessSettingNamesGet (mAuthToken, "asset");
Line 2 - Retrieve an array of Custom Access Setting Names of type "asset".
This method is used to retrieve the list of Default Custom Access Settings of a particular type. An asset default Custom Access Setting is applied to all new assets, just as a file default Custom Access setting is applied to all new files, and so on.
1. String[] lCustomAccessSettingNames = null; 2. lCustomAccessSettingNames = mFlashlineRegistry.customAccessSettingDefault NamesGet(mAuthToken, "asset");
Line 2 - Retrieve an array of default Custom Access Setting Names of type "asset".
This section provides a use case for the Department API that describes how to create, update, query, and delete departments in Oracle Enterprise Repository.
Departments can be created, read, queried for, and modified. These operations are described below. Bear in mind that after a Department is created, it cannot be deleted. Only two Department attributes are meaningful to a user: name and description.
import com.flashline.registry.openapi.entity.Department;
The following sample code illustrates typical tasks involving the manipulation of departments in Oracle Enterprise Repository. This includes creation, updating, querying, and deleting.
Example 4-33 Use Case: Manipulate Departments
package com.flashline.sample.departmentapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Department; import com.flashline.registry.openapi.query.DepartmentCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class Departments { public static void main(String pArgs[]) throws java.rmi.RemoteException, OpenAPIException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ////////////////////////////// // Create a new department // Each Department requires a unique name. Descriptions are optional. // ////////////////////////////// Department dept = repository.departmentCreate(authToken, "My Dept "+Calendar.getInstance().getTimeInMillis(), "A New Department"); // ////////////////////////////// // Read a department // To read a Department you must have the Department name. // ////////////////////////////// Department dept2 = repository.departmentRead(authToken, "ADepartment"); // ////////////////////////////// // Query for a department // // To query for a Department you must fill out a // DepartmentCriteria object with an array of SearchTerms. A SearchTerm // is a key/value pair. Currently the only valid key is "name". // // A query for name is a match if the value for the name term // occurs anywhere in the name of the department. For example, // a search for fred matches fred, alfred, and fredrick. // ////////////////////////////// DepartmentCriteria criteria = new DepartmentCriteria(); criteria.setNameCriteria("DepartmentName"); Department[] depts = repository.departmentQuery(authToken, criteria); // ////////////////////////////// // Update a department // // To update a Department you need only to modify a Department // reference and call departmentUpdate... // ////////////////////////////// String lOldName = dept.getName(); String lNewName = "New " + dept.getName(); Department dept3 = repository.departmentRead(authToken, lOldName); dept3.setName(lNewName); repository.departmentUpdate(authToken, dept3); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
This section provides use cases for the Extraction API that describe how to extract an asset, read an extraction, and update an extraction in Oracle Enterprise Repository.
As part of the Use - Download (extraction) process the user is asked to associate the selected asset with a particular project. These instances of usage, along with surveys (which are included in usage updates) are the primary drivers for metrics within Oracle Enterprise Repository.
Note:
In earlier product releases the term Extraction was used to describe the act of downloading or otherwise accessing an asset's payload. The term Extraction has since been replaced by the phrase Use - Download. Note, however, that within the context of this Extraction API document, most instances of use of the term Extraction (particularly in code examples) were left intact to simplify the use of REX API.State
State refers to the usage status of an asset that has been selected for use/download. There are four possible states:
IN PROCESS
ACCEPTED
REJECTED
DEPLOYED (DEPLOYED is covered under Projects).
Extraction Download
Contains the file info associated with the extracted asset. Values for an extraction download can be 0 or 1.
File Info
Information and URL links to the actual files associated with the asset make up the File Info as contained in an extraction download. File Info values for an extraction download can be 0 to n.
Related Asset
Within Oracle Enterprise Repository, a given asset can be associated with others through a number of pre-defined and/or custom-configured relationships. An asset can contain 0 to n related assets.
AssetSubsystem
ProjectSubsystem
CategorizationTypeSubsystem
SurveySubsystem
This section describes the use cases using the Extraction API. It includes the following topics:
An Extraction is created when an asset is associated for use in a project by the user. A list of related assets is also made available for extraction during this process. In this case the user can simultaneously extract both the primary asset and any related assets. A unique extraction is then recorded for each asset. Creating an extraction results in an array containing 0 to n extraction downloads. The file info value for each download can be 0 to n. The file info contains information about the file. This information is used to create a link to the file.
To extract an asset the following conditions must be met:
The user must be a member of the project to which the asset is to be extracted.
The user must be assigned the appropriate role type(s).
The project must be open.
The asset(s) must be registered and active.
If Custom Access Settings are enabled, the user performing the extraction must have appropriate access rights to the specified asset(s).
If Custom Access Settings are enabled, the user performing the extraction receives file info only for those files to which the user has the appropriate permissions.
These conditions are checked by the appropriate methods in which they are used. Exceptions are thrown if the conditions are not met.
Example 4-34 Use Case: Extract an Asset
package com.flashline.sample.extractionapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.ArrayList; import java.util.Iterator; import java.util.List; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Extraction; import com.flashline.registry.openapi.entity.ExtractionDownload; import com.flashline.registry.openapi.entity.FileInfo; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ExtractAsset { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1], pArgs[2]); long ASSET_ID_1 = 589; // must be a valid asset id in OER long ASSET_ID_2 = 569; // must be a valid asset id in OER long PROJECT_ID = 50000; // must be a valid project id in OER long EXTRACTION_ID = 0; // ---------------------------------------- // Create a new extraction long[] lAssetIDs = { ASSET_ID_1, ASSET_ID_2 }; ExtractionDownload[] extractionDownloads = repository.extractionCreate(authToken, PROJECT_ID, lAssetIDs); System.out.println("Number of new extraction downloads created: " + extractionDownloads.length); // ---------------------------------------- // Read an extraction by project and asset Extraction extraction = repository.extractionReadByProjectAndAsset(authToken, PROJECT_ID, ASSET_ID_1); EXTRACTION_ID = extraction.getID(); // ---------------------------------------- // Read an extraction by ID Extraction extractionByID = repository.extractionRead(authToken, EXTRACTION _ID); System.out.println("The extraction '"+extractionByID.getDisplayName()+"' was read by id ("+EXTRACTION_ID+")"); // ---------------------------------------- // Read asset extractions Extraction[] assetExtractions = repository.extractionReadAssetExtractions(authToken, PROJECT_ID, ASSET_ID_1, true); System.out.println("The number of extractions for this asset is: "+(assetExtractions==null ? 0 : assetExtractions.length)); // ---------------------------------------- // Read project extractions Extraction[] projectExtractions = repository.extractionReadProjectExtractions(authToken, PROJECT_ID, true); System.out.println("The number of extractions for this project is: "+(projectExtractions==null ? 0 : projectExtractions.length)); // ---------------------------------------- // Read related assets Asset[] relatedAssets = repository.extractionReadRelatedAssets(authToken, ASSET_ID_2); System.out.println("The number of related assets is: "+relatedAssets==null ? 0 : relatedAssets.length); // ---------------------------------------- // Read File-Info for an extraction List fileInfosList = new ArrayList(); if (projectExtractions != null) { for (int i = 0; i < projectExtractions.length; i++) { extraction = repository.extractionRead(authToken, projectExtractions[i].getID()); fileInfosList.add(repository.extractionReadFileInfos(authToken, extraction)); } } // ---------------------------------------- // Get File List fileInfoList = new ArrayList(); Iterator fileInfosListIter = fileInfosList.iterator(); while (fileInfosListIter.hasNext()) { FileInfo[] fileInfos = (FileInfo[]) fileInfosListIter.next(); for (int i = 0; i < fileInfos.length; i++) { fileInfoList.add(fileInfos[i]); } } String[] fileLinks = new String[fileInfoList.size()]; for (int i = 0; i < fileInfoList.size(); i++) { FileInfo fileInfo = (FileInfo) fileInfoList.get(i); fileLinks[i] = repository.repositoryFileTranslator(authToken, fileInfo); System.out.println("Project extraction file-info link: "+fileLinks[i]); } // ----------------------------------- // revert extractions repository.extractionResetDatabase(); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
FileInfo objects represent individual files associated with the extracted asset. The physical location of the file may be obtained by the two following methods.
Using the downloadURI property on the FileInfo object itself, for example, fileInfo.getDownloadURI().
Using the OpenAPI method repositoryFileTranslator passing the FileInfo object, for example, flashlineRegistry.repositoryFileTranslator(authToken, fileInfo).
Note:
DO NOT use the URI property on the FileInfo object which represents an Oracle Enterprise Repository specific path.Several methods beyond those covered in the Extract an Asset use case is used to read extractions. Extractions can be grouped by asset, project, or user. The specific grouping of extractions determines the method to be used.
To read an extraction the following conditions must be met:
The project must be open.
The asset(s) must be registered and active.
The extraction must be active.
These conditions are checked by the appropriate methods in which they are used. Exceptions are thrown if the conditions are not met.
Example 4-35 Use Case: Read an Extraction
package com.flashline.sample.extractionapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Extraction; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ExtractRead { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); long PROJECT_ID = 50000; // must be a valid project id in the OER long ASSET_ID = 569; // must be a valid asset id in the OER // ---------------------------------------- // Read project extractions Extraction[] projectExtractions = repository .extractionReadProjectExtractions(authToken, PROJECT_ID, true); // ---------------------------------------- // Read asset extractions Extraction[] assetExtractions = repository .extractionReadAssetExtractions(authToken, PROJECT_ID, ASSET_ID, true); // ---------------------------------------- // Read user extractions Extraction[] userExtractions = repository .extractionReadUserExtractions(authToken, true); // ---------------------------------------- // Read related assets Asset[] assets = repository.extractionReadRelatedAssets(authToken, ASSET_ID); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
An extraction record is updated when the state of the asset is changed or when the consumer of the asset completes an asset survey. A state change or survey completion can be separate transactions or performed in tandem.
To update an extraction the following conditions must be met:
The project must be open.
The asset must be registered and active.
The extraction must be active.
The survey taken must be active.
These conditions are checked by the appropriate methods in which they are used. Exceptions are thrown if the conditions are not met.
Example 4-36 Use Case: Update an Extraction
package com.flashline.sample.extractionapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Answer; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Categorization; import com.flashline.registry.openapi.entity.Choice; import com.flashline.registry.openapi.entity.ChoiceList; import com.flashline.registry.openapi.entity.Extraction; import com.flashline.registry.openapi.entity.ExtractionDownload; import com.flashline.registry.openapi.entity.IExtraction; import com.flashline.registry.openapi.entity.Question; import com.flashline.registry.openapi.entity.SurveyTaken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ExtractUpdate { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); long PROJECT_ID = 50000; // must be a valid project id in the OER long ASSET_ID = 569; // must be a valid asset id in the OER // ---------------------------------------- // Create a new extraction long[] lAssetIDs = { ASSET_ID }; ExtractionDownload[] extractionDownloads = repository.extractionCreate(authToken, PROJECT_ID, lAssetIDs); Extraction[] assetExtractions = repository .extractionReadAssetExtractions(authToken, PROJECT_ID, ASSET_ID, true); /////////////////////////////////////////////////////////////////////////// // this assumes that there is at least 1 extraction and the first one is // used /////////////////////////////////////////////////////////////////////////// IExtraction iExtraction = repository .extractionReadExtractionStates(authToken); Extraction extraction = repository.extractionRead(authToken, assetExtractions[0].getID()); /////////////////////////////////////////////////////////////////////////// // can set the status of the extraction to 'Deployed', 'Rejected', or 'In // Process'. /////////////////////////////////////////////////////////////////////////// assetExtractions[0].setStatus("In Process"); extraction = repository.extractionTentativelyAccept(authToken, extraction); SurveyTaken surveyTaken = repository.surveyTakenRead(authToken, extraction); extraction = repository.extractionUpdateSurvey(authToken, extraction, surveyTaken); extraction.setStatus(iExtraction.getInProcess()); surveyTaken = repository.surveyTakenRead(authToken, extraction); extraction = repository.extractionUpdateSurvey(authToken, extraction, surveyTaken); Categorization[] rejectionReasons = repository .extractionReadRejectionReasons(authToken); surveyTaken = repository.surveyTakenRead(authToken, extraction); extraction = repository.extractionUpdateSurvey(authToken, extraction, surveyTaken); surveyTaken = repository.surveyTakenRead(authToken, extraction); Question[] questions = repository.surveyReadQuestions(authToken); ChoiceList choiceList = null; Choice[] choices = null; Answer[] answers = new Answer[4]; for (int i = 0; i < answers.length; i++) { answers[i] = new Answer(); } answers[0].setQuestionId(questions[0].getId()); choiceList = questions[0].getChoiceList(); choices = choiceList.getChoices(); answers[0].setChoiceId(choices[0].getId()); answers[0].setValue(choices[0].getValue()); answers[1].setQuestionId(questions[1].getId()); answers[1].setChoiceId(0); answers[1].setValue("100"); answers[2].setQuestionId(questions[2].getId()); answers[2].setChoiceId(0); answers[2].setValue("200"); answers[3].setQuestionId(questions[3].getId()); choiceList = questions[3].getChoiceList(); choices = choiceList.getChoices(); answers[3].setChoiceId(choices[3].getId()); answers[3].setValue(choices[3].getValue()); surveyTaken.setAnswers(answers); surveyTaken = repository.surveyTakenUpdate(authToken, surveyTaken); // ----------------------------------- // revert extractions repository.extractionResetDatabase(); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Bear in mind that a state change or a survey taken is a two-step process. The first step is to change the state or take the survey. The second step is to update the extraction status using the extractionUpdateStatus method. A state change or survey taken can be separate transactions or performed in tandem. If performed in tandem only a single extractionUpdateStatus method call is required.
The extractionUpdateStatus method requires a SurveyTaken. This is true regardless of whether a survey was taken at the time the extractionUpdateStatus method is called (as in a state change, for example). This survey is retrieved using the surveyTakenRead method. If a survey has not been taken for this extraction, then one is created by the surveyTakenRead method.
The current survey in Oracle Enterprise Repository consists of four questions. When a survey is taken an array is created storing answers for the four questions. Each answer must contain three pieces of information to be valid:
The value (the user response to the question)
The question ID
The choice ID
Questions 2 and 3 are single answer questions, so the choice ID here is always set to 0. Questions 1 and 4, however, are multiple-choice. The multiple choices are retrieved using the surveyReadChoiceList method.
The following objects are used in the Extraction and Survey subsystems:
Extraction
ExtractionDownload
FileInfo
SurveyTaken
Question
ChoiceList
Choice
Answer
The use of any of the get methods within these objects is acceptable. All the remaining methods - especially the set methods - should be avoided. The events provided by these remaining methods are covered by the methods in the Extraction and Survey subsystems.
This section provides use cases for the localization of REX clients that describe how to create localized messages from REX Exceptions and REX Audit Messages in Oracle Enterprise Repository.
Statuses are passed back to a REX client as either an OpenAPIException or AuditMsg object. OpenAPIException objects are used for exceptions, whereas, AuditMsg objects are used for processes that run asynchronously. Both of these objects return a text error message to the REX client.
The interface of both objects has been expanded to include an error code and a list of message arguments so that REX clients can display error or status messages in another language. Clients can continue to use the standard error messages or they can ignore the message and use the error code and the message arguments to construct their own error message.
For example, if you want to localize an application that uses REX, you would first get the properties file listing all the possible error messages. The messages look something like this:
ERR_9008 = Error updating project with ID = [{0}].
Then you must translate all the messages as necessary:
ERR_9008 = Errorway updatingay ojectpray ithway IDway = [{0}].
If the client code tries to modify a project with ID=123, and that modification fails, then your end-users get an exception with this error message:
Error updating project with ID = [123].
If you want to display that error in a local language (such as, Pig Latin), you would take the error code, 9008, and look it up in your translated file to get the string "Errorway updatingay ojectpray ithway IDway = [{0}]." Then you would use the message arguments to replace the tokens. In this case, there is only one string, "123", so you should be able to find one message argument.
You can then construct a custom error message for your end-users:
Errorway updatingay ojectpray ithway IDway = [123].
From the OpenAPIException get the server error code and the message arguments
Get the resource bundle for the OpenAPIExceptions appropriate for the client locale
Get the string associated with the error code and replace the token with the message arguments
Example 4-37 Use Case: Creating Localized Messages from REX Exceptions
package com.flashline.sample.localization; import java.net.URL; import java.text.MessageFormat; import java.util.ResourceBundle; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class SyncTest { private static final int INVALID_PROJECT_ID = 8672609; public static void main(String[] args) throws Exception { URL lURL = new URL("http://localhost:9080/registry/services/FlashlineRegistry"); FlashlineRegistry reg = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); AuthToken token = reg.authTokenCreate("admin", "n0pa55w0rd"); try { Project project = reg.projectRead(token,INVALID_PROJECT_ID); } catch (OpenAPIException ex) { String msg = createMessage(ex.getServerErrorCode(),ex.getMessageArguments()); System.out.println(msg); } } private static String createMessage(int pServerErrorCode, Object[] pArgs) { ResourceBundle mResourceBundle = ResourceBundle.getBundle("com.flashline.sample.localization.sync_error _messages"); return MessageFormat.format(mResourceBundle.getString("ERR _"+pServerErrorCode), pArgs); } }
From the AuditMsg and the ImpExpJob get the server error code and the message arguments from the AuditMsg
Get the resource bundle for audit messages appropriate for the client locale
Get the string associated with the error code and replace the token with the message arguments
Example 4-38 Use Case: Creating Localized Messages from REX Audit Messages
package com.flashline.sample.localization; import java.io.File; import java.io.FileInputStream; import java.io.FileNotFoundException; import java.io.IOException; import java.io.InputStream; import java.io.InputStreamReader; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.text.MessageFormat; import java.util.ResourceBundle; import javax.activation.DataHandler; import javax.xml.rpc.ServiceException; import org.apache.axis.client.Stub; import org.apache.soap.util.mime.ByteArrayDataSource; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.ImpExpJob; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class AsyncTest { public void run() throws MalformedURLException, ServiceException, OpenAPIException, RemoteException{ URL lURL = new URL("http://localhost:9080/registry/services/FlashlineRegistry"); FlashlineRegistry reg = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); AuthToken token = reg.authTokenCreate("admin", "n0pa55w0rd"); try { File lFile = new File("samples/com/flashline/sample/localization/asynctest.zip"); //Import the file and save to db InputStream lIS = new FileInputStream(lFile); ByteArrayDataSource lDataSource = new ByteArrayDataSource(lIS, "application/x-zip-compressed"); DataHandler lDH = new DataHandler(lDataSource); // add the attachment ((Stub)reg).addAttachment(lDH); ImpExpJob lJob = reg.importExecute(token, "flashline", null, "Import Assets Test", null); boolean lPassed = false; for(int i=0; i<1000; i++){ lJob = reg.importStatus(token, lJob); System.out.println("Import Job ["+lJob.getID()+"] - State: "+lJob.getState()); String msg = createMessage(lJob.getAuditMsg().getSummaryID(),lJob.getAuditMsg().getSummaryArgs ()); System.out.println(msg); if( lJob.getState().equals("completed")){ lPassed = true; break; } try { Thread.sleep(1000); } catch (InterruptedException e) { e.printStackTrace(); } } if (lPassed){ System.out.println("Import Completed"); } } catch (OpenAPIException ex) { String msg = createMessage(ex.getServerErrorCode(),ex.getMessageArguments()); System.out.println(msg); } catch (FileNotFoundException e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (IOException e) { // TODO Auto-generated catch block e.printStackTrace(); } } /** * @param args * @throws ServiceException * @throws RemoteException * @throws MalformedURLException * @throws OpenAPIException */ public static void main(String[] args) throws OpenAPIException, MalformedURLException, RemoteException, ServiceException { AsyncTest test = new AsyncTest(); test.run(); } private static String createMessage(int pServerErrorCode, Object[] pArgs) { ResourceBundle mResourceBundle = ResourceBundle.getBundle("com.flashline.sample.localization.async_error _messages"); return MessageFormat.format(mResourceBundle.getString("ERR _"+pServerErrorCode), pArgs); } private String readZip(String pFileName) throws IOException { int lNumRead = 0; char[] lBuf = new char[2048]; StringBuffer lQuery = new StringBuffer(); InputStreamReader lReader = new InputStreamReader(getClass().getResourceAsStream(pFileName)); while( (lNumRead=lReader.read(lBuf)) != -1){ lQuery.append(lBuf, 0, lNumRead); } return lQuery.toString(); } }
This section provides a use case for the Notification API that describes how to create a new read notification substitution list and how to create an Oracle Enterprise Repository notification.
The Notification subsystem provides a web services-based mechanism that is used to create Oracle Enterprise Repository notifications.
To create a read notification substitution list and create an Oracle Enterprise Repository notification.
Example 4-39 Use Case: Create a Read Notification Substitution List and Create a Notification
String[] lSubstitutions = null; String[] lRecipients = null; String lTemplateType = "asset_registered"; NameValue[] lNameValues = null; lRecipients = new String[] {"recipient@xyz.com"}; try { ////////////////////////// // read the existing substitutions based on the given template lSubstitutions = mFlashlineRegistry.notificationSubstitutionsRead(mAuthToken, lTemplateType); ////////////////////////// // create an array of namevalue pairs; a namevalue pair for each required substitution lNameValues = new NameValue[lSubstitutions.length]; // populate the namevalues for(int i=0; i<lSubstitutions.length; i++) { lNameValues[i] = new NameValue(); lNameValues[i].setName(lSubstitutions[i]); lNameValues[i].setValue("valueof-"+lSubstitutions[i]); } //////////////////////////////////////////// // create the notification mFlashlineRegistry.notificationCreate(mAuthToken, lTemplateType, lRecipients, lNameValues); } catch(Exception e) { fail(e.getMessage()); }
This section provides use cases for the Policy API that describe how to create a new policy, get all policies, get or set policy assertions, obtain policies applied to an asset, and determine an asset's compliance against all applied policies or specific policies.
REX now supports the following functions against Policies
Query Policy:
Status of the Policy (pass/fail) on an Asset
Status of the collection of Policies on an Asset
Obtain XML from the Policy Assertion Technical Description Field
Assets that the Policy is applied too
Viewer
Maintain list of individual Policy Assertions on a Policy
Set status of individual Policy Assertions for an Asset.
Apply and remove Policy from assets
Additional Import(s) Required (Some may not be used in all examples.)
import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.PolicyAssertion; import com.flashline.registry.openapi.entity.PolicyAssertionResult;
Note:
Policies in Oracle Enterprise Repository are a specific type of asset, based on the Policy Type. Refer to the Asset API use cases for information related to the creation, modification and removal of a Policy.
Assertions
An assertion is a policy statement added to a policy asset.
AssertionResult
When a Policy has been applied to an asset, each assertion within the policy can be evaluated for the asset. The Assertion Result is pass, fail or unknown for any asset and assertion pair.
There are four new methods available with the FlashlineRegistry service
assetReadAppliedPolicies()
assetUpdateAppliedPolicies()
assetEvaluateAgainstPolicy()
assetEvaluateAgainstAllPolicies()
This section describes the use cases using the Policy API. It contains the following topics:
Section 4.4.12.2.4, "Use Case: Get Policies That Have Been Applied To An Asset"
Section 4.4.12.2.5, "Use Case: Set Which Policies Are Applied To An Asset"
To create a new policy, create a new asset based on the Policy Type (102).
Example 4-40 Use Case: Create a Policy
package com.flashline.sample.policies; import java.net.URL; import java.rmi.RemoteException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AssetType; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.PolicyAssertion; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CreatePolicySample { private static final String POLICY_TYPE_NAME_PREFIX = "Policies-Test Policy Type"; private static final long ASSET_POLICY_ARCHETYPE = 102; private static final String POLICY_NAME_PREFIX = "Policies-Test Policy"; private static final String POLICY_VERSION = "1.0"; private static FlashlineRegistry mRepository = null; private static AssetType mPolicyAssetType = null; private AuthToken mAuthToken = null; public CreatePolicySample(String[] pArgs) { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); mRepository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// mAuthToken = mRepository.authTokenCreate(pArgs[1], pArgs[2]); mPolicyAssetType = createPolicyAssetType(); } catch(Exception e) { } } public static void main(String[] pArgs) { try { CreatePolicySample lCreatePolicySample = new CreatePolicySample(pArgs); // --------------------------- // create a new policy object Asset lPolicy = lCreatePolicySample.createPolicy(); } catch(Exception e) { e.printStackTrace(); } } /** * Creates an asset policy with a unique name */ private Asset createPolicy() throws RemoteException { String lPolicyName = POLICY_NAME_PREFIX + " " + System.currentTimeMillis(); // --------------------------- // create a policy (an asset whose assettype's archtype is "102" (policy) Asset lPolicy = mRepository.assetCreate(mAuthToken, lPolicyName, POLICY _VERSION, mPolicyAssetType.getID()); lPolicy.setCustomData("<custom-data></custom-data>"); // --------------------------- // set some polcy assertions lPolicy.setPolicyAssertions(generateSampleAssertions()); return mRepository.assetUpdate(mAuthToken, lPolicy); } /** * Returns several sample policy assertions for use in testing. * Located in a function to be shared between test calls. * * @return Array of policy assertions */ private PolicyAssertion[] generateSampleAssertions() { PolicyAssertion[] lPolicyAssertions = new PolicyAssertion[3]; String[] lPolicyAssertionNames = {"First", "Second", "Third"}; for (int i=0; i<lPolicyAssertionNames.length; i++) { String lPolicyAssertionName = "My " + lPolicyAssertionNames[i] + " Assertion"; lPolicyAssertions[i] = new PolicyAssertion(); lPolicyAssertions[i].setName(lPolicyAssertionName); lPolicyAssertions[i].setDescription(lPolicyAssertionName + " Description"); lPolicyAssertions[i].setTechnicalDefinition(lPolicyAssertionName + " Technical Definition"); } return lPolicyAssertions; } /** * Creates an asset policy asset type with a unique name */ private AssetType createPolicyAssetType() throws RemoteException { String lPolicyTypeName = POLICY_TYPE_NAME_PREFIX + " " + System.currentTimeMillis(); // --------------------------- // create a new asset type AssetType lPolicyType = mRepository.assetTypeCreate(mAuthToken, lPolicyTypeName); // --------------------------- // update the asset type to be a policy asset type by settings the archtype = 102 lPolicyType.setArcheTypeIDs(new long[] {ASSET_POLICY_ARCHETYPE}); return mRepository.assetTypeUpdate(mAuthToken, lPolicyType); } }
To get all policies, find all assets whose asset type's archetype is a policy archetype (102).
Example 4-41 Use Case: Get All Policies
package com.flashline.sample.policies; import java.net.URL; import java.util.Arrays; import java.util.LinkedList; import java.util.List; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AssetType; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.query.AssetCriteria; import com.flashline.registry.openapi.query.AssetTypeCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class FindPoliciesSample { private static FlashlineRegistry mRepository = null; private static AuthToken mAuthToken = null; public FindPoliciesSample(String[] pArgs) { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); mRepository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// mAuthToken = mRepository.authTokenCreate(pArgs[1], pArgs[2]); } catch(Exception e) { } } public static void main(String[] pArgs) { try { FindPoliciesSample lFindPoliciesSample = new FindPoliciesSample(pArgs); AssetType[] lPolicyAssetTypes = null; Asset[] lPolicies = null; AssetTypeCriteria lAssetTypeCriteria = null; AssetCriteria lAssetCritera = null; List lListPolicies = new LinkedList(); // ----------------------- // search for all asset types that have the policy (102) archetype lAssetTypeCriteria = new AssetTypeCriteria(); lAssetTypeCriteria.setArcheTypeCriteria("102"); lPolicyAssetTypes = mRepository.assetTypeQuery(mAuthToken, lAssetTypeCriteria); for(int i=0; i<lPolicyAssetTypes.length; i++) { // ----------------------- // for each policy assettype, search for all assets that are of policy assettype lAssetCritera = new AssetCriteria(); lAssetCritera.setAssetTypeCriteria(lPolicyAssetTypes[i].getID()); lPolicies = mRepository.assetQuery(mAuthToken, lAssetCritera); // ----------------------- // add polices to list lListPolicies.addAll(Arrays.asList(lPolicies)); } } catch(Exception e) { e.printStackTrace(); } } }
To get policy assertions, call getPolicyAssertions
. To set policy assertions, call setPolicyAssertions
, then update the policy.
Example 4-42 Use Case: Get/Set Policy Assertions
package com.flashline.sample.policies; import java.net.URL; import java.util.Arrays; import java.util.LinkedList; import java.util.List; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AssetType; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.PolicyAssertion; import com.flashline.registry.openapi.query.AssetCriteria; import com.flashline.registry.openapi.query.AssetTypeCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class GetSetPolicyAssertionsSample { private static FlashlineRegistry mRepository = null; private static AuthToken mAuthToken = null; public GetSetPolicyAssertionsSample(String[] pArgs) { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); mRepository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// mAuthToken = mRepository.authTokenCreate(pArgs[1], pArgs[2]); } catch(Exception e) { } } public static void main(String[] pArgs) { try { GetSetPolicyAssertionsSample lGetSetPolicyAssertionsSample = new GetSetPolicyAssertionsSample(pArgs); AssetType[] lPolicyAssetTypes = null; Asset[] lPolicies = null; AssetTypeCriteria lAssetTypeCriteria = null; AssetCriteria lAssetCritera = null; List lListPolicies = new LinkedList(); // ----------------------- // search for all asset types that have the policy (102) archetype lAssetTypeCriteria = new AssetTypeCriteria(); lAssetTypeCriteria.setArcheTypeCriteria("102"); lPolicyAssetTypes = mRepository.assetTypeQuery(mAuthToken, lAssetTypeCriteria); for(int i=0; i<lPolicyAssetTypes.length; i++) { // ----------------------- // for each policy assettype, search for all assets that are of policy assettype lAssetCritera = new AssetCriteria(); lAssetCritera.setAssetTypeCriteria(lPolicyAssetTypes[i].getID()); lPolicies = mRepository.assetQuery(mAuthToken, lAssetCritera); // ----------------------- // add polices to list lListPolicies.addAll(Arrays.asList(lPolicies)); } if(lListPolicies.size() > 0) { // ----------------------- // get the first policy Asset lPolicy = (Asset)lListPolicies.get(0); // ----------------------- // get the policy assertions PolicyAssertion[] lPolicyAssetions = lPolicy.getPolicyAssertions(); // ----------------------- // print out the policy assertions for(int i=0; i<lPolicyAssetions.length; i++) { lPolicyAssetions[i].toString(); } // ----------------------- // set different policy assertions lPolicy.setPolicyAssertions(generateNewAssertions()); // ----------------------- // update the asset with new assertions mRepository.assetUpdate(mAuthToken, lPolicy); } else { System.out.println("No policies were found in OER."); } } catch(Exception e) { e.printStackTrace(); } } /** * Returns several sample policy assertions for use in testing. * Located in a function to be shared between test calls. * * @return Array of policy assertions */ private static PolicyAssertion[] generateNewAssertions() { PolicyAssertion[] lPolicyAssertions = new PolicyAssertion[3]; String[] lPolicyAssertionNames = {"NEW-First", "NEW-Second", "NEW-Third"}; for (int i=0; i<lPolicyAssertionNames.length; i++) { String lPolicyAssertionName = "My " + lPolicyAssertionNames[i] + " Assertion"; lPolicyAssertions[i] = new PolicyAssertion(); lPolicyAssertions[i].setName(lPolicyAssertionName); lPolicyAssertions[i].setDescription(lPolicyAssertionName + " Description"); lPolicyAssertions[i].setTechnicalDefinition(lPolicyAssertionName + " Technical Definition"); } return lPolicyAssertions; } }
Call assetReadAppliedPolicies
to obtain policies applied to an asset.
Example 4-43 Use Case: Get Policies That Have Been Applied to an Asset
package com.flashline.sample.policies; import java.net.URL; import java.util.Arrays; import java.util.LinkedList; import java.util.List; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AssetType; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.PolicyAssertion; import com.flashline.registry.openapi.query.AssetCriteria; import com.flashline.registry.openapi.query.AssetTypeCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class GetAppliedPoliciesSample { private static FlashlineRegistry mRepository = null; private static AuthToken mAuthToken = null; public GetAppliedPoliciesSample(String[] pArgs) { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); mRepository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// mAuthToken = mRepository.authTokenCreate(pArgs[1], pArgs[2]); } catch(Exception e) { } } public static void main(String[] pArgs) { try { GetAppliedPoliciesSample lGetAppliedPoliciesSample = new GetAppliedPoliciesSample(pArgs); long lAssetId = 50000; // --------------- // read the policed appled to asset 50000 Asset[] lAppliedPolicies = mRepository.assetReadAppliedPolicies(mAuthToken, lAssetId); } catch(Exception e) { e.printStackTrace(); } } }
Call assetUpdateAppliedPolicies
to update policies that have been applied to an asset.
Example 4-44 Use Case: Update Policies Applied to an Asset
package com.flashline.sample.policies; import java.net.URL; import java.util.Arrays; import java.util.LinkedList; import java.util.List; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AssetType; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.PolicyAssertion; import com.flashline.registry.openapi.query.AssetCriteria; import com.flashline.registry.openapi.query.AssetTypeCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ApplyPoliciesSample { private static FlashlineRegistry mRepository = null; private static AuthToken mAuthToken = null; public ApplyPoliciesSample(String pArgs[]) { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); mRepository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// mAuthToken = mRepository.authTokenCreate(pArgs[1], pArgs[2]); } catch(Exception e) { } } public static void main(String[] pArgs) { try { ApplyPoliciesSample lApplyPoliciesSample = new ApplyPoliciesSample(pArgs); long lAssetId = 50000; long[] lPolicyIds = {50000, 50001, 50002}; mRepository.assetUpdateAppliedPolicies(mAuthToken, lAssetId, lPolicyIds); } catch(Exception e) { e.printStackTrace(); } } }
Use assetEvaluateAgainstPolicy
to determine an asset's compliance with a specified policy. Use assetEvaluateAgainstAllPolicies
to determine an asset's compliance against all applied policies.
Example 4-45 Use Case: Evaluate Asset Compliance
package com.flashline.sample.policies; import java.net.URL; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class PolicyEvaluationSample { private static FlashlineRegistry mRepository = null; private static AuthToken mAuthToken = null; public PolicyEvaluationSample(String[] pArgs) { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); mRepository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// mAuthToken = mRepository.authTokenCreate(pArgs[1], pArgs[2]); } catch(Exception e) { } } public static void main(String[] pArgs) { try { PolicyEvaluationSample lPolicyEvalSamp = new PolicyEvaluationSample(pArgs); long lAssetId = 50000; long lPolicyId = 50001; String lEvaluationResult = null; // -------------------- // evaluate asset id 50000 against policy id 50001 // the return is one of the following values "pass", "fail", "unknown" lEvaluationResult = mRepository.assetEvaluateAgainstPolicy(mAuthToken, lAssetId, lPolicyId); // -------------------- // evaluate asset id 50000 against all polices applied to the asset // the return is one of the following values "pass", "fail", "unknown" lEvaluationResult = mRepository.assetEvaluateAgainstAllPolicies(mAuthToken, lAssetId); } catch(Exception e) { e.printStackTrace(); } } }
This section provides use cases for the Projects API that describe how to create, read, update, query, and validate projects, work with project assets, and make changes to project users in oracle Enterprise Repository.
This section covers projects, providing information covering create, read, update, query, and validate. Several entities are attached to Projects: related projects, users, consumed assets, and produced assets. The addition and removal of these entities is also covered in this section.
Additional Import(s) Required (Some may not be used in all examples.)
import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.query.ProjectCriteria; import com.flashline.registry.openapi.entity.KeyValuePair; import com.flashline.registry.openapi.entity.Results; import java.text.SimpleDateFormat; import com.flashline.registry.openapi.decision.ExtractionReassignmentDecision; import com.flashline.registry.openapi.entity.ProjectEntities;
This section describes the use cases using the Projects API. It includes the following topics:
Section 4.4.13.2.5, "Use Case: Update a Project's Produced Assets"
Section 4.4.13.2.6, "Use Case: Remove Produced Assets from a Project"
Section 4.4.13.2.7, "Use Case: Update a Project's Asset Usage"
Section 4.4.13.2.8, "Use Case: Closing a Project with Hidden Assets"
Section 4.4.13.2.9, "Use Case: Add Users and Related Projects to a Project"
Section 4.4.13.2.10, "Use Case: Remove Related Projects and Users from a Project"
Section 4.4.13.2.14, "Use Case: Read the Value-Provided for a Project and Asset"
This method creates a project, assigns users, and assigns related projects.
Rules for projects:
The project must have an assigned project leader.
A project's name must be unique and cannot be null.
A project must be assigned to a department.
A project's estimated hours must be a whole number, 0 or greater.
Example 4-46 Use Case: Create a New Project
package com.flashline.sample.projectapi; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CreateNewProject { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); Project lProject = null; ProjectEntities lProjectEntities = null; String[] lLeaderIds = null; // --------------------------------------------------------------------------------- -- lProject = new Project(); lProjectEntities = new ProjectEntities(); // ----------------------------------------------------------------------------------- // set the name of project lProject.setName("NEW_PROJECT_NAME"); // --------------------------------------------------------------------------------- -- // set the name of the project's department lProject.setDepartmentID(50000); // a department with id 50000 must // already exist // --------------------------------------------------------------------------------- -- // set the userids of the project leaders lLeaderIds = new String[] { "99" }; lProjectEntities.setLeaderIDs(lLeaderIds); // --------------------------------------------------------------------------------- -- repository.projectCreate(authToken, lProject, lProjectEntities); } catch (OpenAPIException oapie) { System.out.println("\t --- ServerCode = " + oapie.getServerErrorCode()); System.out.println("\t --- Message = " + oapie.getMessage()); } catch (Exception e) { System.out.println("\t --- ErrorMessage = " + e.getMessage()); } } }
Searches for a project and reads its extractions, produced assets, users, and related projects.
Example 4-47 Use Case: Read a Project
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Extraction; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.query.ProjectCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ReadProject { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------- // Read a project ProjectCriteria projectCriteria = new ProjectCriteria(); projectCriteria.setNameCriteria("Project A"); Project[] projects = repository.projectQuery(authToken, projectCriteria); if (projects.length > 0) { try { Project projectRead = (Project) projects[0]; Extraction[] lExtractions = repository.projectReadExtractions( authToken, projectRead); Asset[] lAssets = repository.projectReadProducedAssets( authToken, projectRead); Project[] childProjects = repository.projectReadChildProjects( authToken, projectRead); Project[] parentProjects = repository .projectReadParentProjects(authToken, projectRead); RegistryUser[] members = repository.projectReadMembers( authToken, projectRead); RegistryUser[] leaders = repository.projectReadLeaders( authToken, projectRead); } catch (OpenAPIException ex) { ex.printStackTrace(); } } else { System.out.println("No projects found"); } } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Validating a project enables the user to catch any validation errors before a project save is attempted.
Example 4-48 Use Case: Validate a Project
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Department; import com.flashline.registry.openapi.entity.KeyValuePair; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.entity.Results; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ValidateProject { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); Project lProject = new Project(); Results lResults = new Results(); String[] lLeaders = { "100" }; Department department = repository.departmentRead(authToken, "Department Name"); ProjectEntities lProjectEntities = new ProjectEntities(); // ----------------------------------- // set the project data lProjectEntities.setLeaderIDs(lLeaders); lProject.setName("Project Name"); lProject.setDepartmentName("DEPARTMENT_NAME"); // ----------------------------------- // Validate a project lResults = repository.projectValidate(authToken, lProject, lProjectEntities); KeyValuePair[] lPairs = lResults.getErrors(); for (int i = 0; i < lPairs.length; i++) { KeyValuePair lPair = lPairs[i]; System.out.println(lPair.getValue()); } } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Update the information and data associated with a specific project.
Example 4-49 Use Case: Update a Project
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.text.SimpleDateFormat; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Department; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class UpdateProject { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); Project lProject = new Project(); Department department = new Department(); ProjectEntities lProjectEntities = new ProjectEntities(); // ----------------------------------- // creating a new temporary project for sample Project lSampleProject = createProject(repository, authToken); // ----------------------------------- // read an existing project try { lProject = repository.projectRead(authToken, lSampleProject.getID()); } catch (OpenAPIException ex) { throw ex; } // ----------------------------------- // change project data lProject.setName("Update "+lProject.getName()); lProject.setDescription("Updated Description"); try { department = repository.departmentRead(authToken, "Different Department"); if (department==null) { System.out.println("dept is null"); department = repository.departmentCreate(authToken, "Different Department", "Different Department description..."); } } catch (OpenAPIException ex) { throw ex; } lProject.setDepartmentID(department.getID()); lProject.setAddByDefault(true); lProject.setEstimatedHours(50); java.util.Calendar lCal = new java.util.GregorianCalendar(); SimpleDateFormat sdf = new SimpleDateFormat("M/d/yy"); lCal.setTime(sdf.parse("1/1/04")); lProject.setStartDate(lCal); // ----------------------------------- // Update the project lProject = (Project) repository.projectUpdate(authToken, lProject, lProjectEntities); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } catch (Exception e) { } } protected static Project createProject(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { Project lProject = new Project(); ProjectEntities lProjectEntities = new ProjectEntities(); lProject.setName("Project "+Calendar.getInstance().getTimeInMillis()); lProject.setDepartmentID(50000); // a department with id 50000 must String[] lLeaderIds = new String[] { "99" }; lProjectEntities.setLeaderIDs(lLeaderIds); lProject = repository.projectCreate(authToken, lProject, lProjectEntities); return lProject; } }
Enables the user to perform a single database transaction to set the produced assets of a project.
Example 4-50 Use Case: Update a Project's Produced Assets
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.APIValidationException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class UpdateProjectProducedAssets { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); ProjectEntities lProjectEntities = new ProjectEntities(); Asset lSampleAsset1 = createAsset(repository, authToken); Asset lSampleAsset2 = createAsset(repository, authToken); String[] assetIds = { ""+lSampleAsset1.getID(), ""+lSampleAsset2.getID() }; try { // ----------------------------------- // read an existing project Project projectRead = repository.projectRead(authToken, 50000); // ----------------------------------- // set the produced asset ids lProjectEntities.setAssetIDs(assetIds); // ----------------------------------- // update the project repository.projectUpdate(authToken, projectRead, lProjectEntities); } catch (APIValidationException ex) { ex.printStackTrace(); } } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } protected static Asset createAsset(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { Asset myAsset = repository.assetCreate(authToken, "My Produced Asset", ""+Calendar.getInstance().getTimeInMillis(), 144); return myAsset; } }
Remove produced assets from a project.
Example 4-51 Use Case: Remove Produced Assets from a Project
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.APIValidationException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class RemoveProducedAssetsFromProject { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); ProjectEntities lProjectEntities = new ProjectEntities(); String[] assetIds = { "569", "589" }; try { // ----------------------------------- // read an existing project Project projectRead = repository.projectRead(authToken, 50000); // ----------------------------------- // set the remove assets ids lProjectEntities.setRemovedAssetIDs(assetIds); // ----------------------------------- // update the project repository.projectUpdate(authToken, projectRead, lProjectEntities); } catch (APIValidationException ex) { ex.printStackTrace(); } // ----------------------------------- // revert extractions repository.extractionResetDatabase(); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } } As an alternative, produced assets may be removed by specifying the assets that are to remain on the project. Sample Code: package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class RemoveProducedAssetsFromProject2 { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------- // An alternate way of removing produced assets is to specify which assets // you wish to remain on the project. String[] assetIDs = { "569" }; ProjectEntities lEntities = new ProjectEntities(); Project projectRead = new Project(); try { // ----------------------------------- // read an existing project projectRead = repository.projectRead(authToken, 50000); // ----------------------------------- // set the entities of the produced assets lEntities.setAssetIDs(assetIDs); // ----------------------------------- // update the project repository.projectUpdate(authToken, projectRead, lEntities); } catch (OpenAPIException ex) { ex.printStackTrace(); } // ----------------------------------- // revert extractions repository.extractionResetDatabase(); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Enables the user to reject extractions that are associated with a project.
Example 4-52 Use Case: Update a Project's Asset Usage
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.List; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Extraction; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectAsset; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class UpdateProjectExtractions { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------- // Update a project's extractions ProjectEntities lProjectEntities = null; try { // ----------------------------------- // read an existing project Project projectRead = repository.projectRead(authToken, 50000); // ----------------------------------- // get an extraction or create one long lExtractionID = 0; ProjectAsset[] lProjectAssets = projectRead.getAssets(); if (lProjectAssets!=null && lProjectAssets.length>0) { lProjectAssets[0].getStatus(); lExtractionID = lProjectAssets[0].getID(); } else { lProjectEntities = new ProjectEntities(); lExtractionID = repository.assetRead(authToken, 569).getID(); String[] lAssetIDs = { ""+lExtractionID }; lProjectEntities.setAssetIDs(lAssetIDs); repository.projectUpdate(authToken, projectRead, lProjectEntities); } // ----------------------------------- // set the rejected assets ids String[] rejectedIds = null; projectRead = repository.projectRead(authToken, 50000); // reload modified project Extraction[] lExtractions = repository.projectReadExtractions(authToken, projectRead); rejectedIds = new String[lExtractions.length]; for (int i=0; lExtractions!=null && i<lExtractions.length; i++) { rejectedIds[i] = ""+lExtractions[i].getID(); } lProjectEntities = new ProjectEntities(); lProjectEntities.setRejectedIDs(rejectedIds); // ----------------------------------- // update the project repository.projectUpdate(authToken, projectRead, lProjectEntities); } catch (OpenAPIException ex) { ex.printStackTrace(); } // ----------------------------------- // revert extractions repository.extractionResetDatabase(); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
When closing a project, the project lead is required to update the usage status of assets consumed in the project that have not already been designated as DEPLOYED
or REJECTED
.
However, certain Advanced Role Based Access Control (RBAC) settings in AquaLogic Enterprise Repository may prevent the project lead from seeing all assets consumed by the project.
If the project is closed, any hidden assets not already rejected are automatically designated as DEPLOYED
.
When using AquaLogic Enterprise Repository, the project lead in this situation is notified that the project contains hidden assets, and is provided with the opportunity to contact users who have the necessary access to update the usage status of the hidden assets and to complete an asset value survey. After the project lead is confident that the appropriate users have taken the necessary action, he/she can close the project.
The following example demonstrates a programmatic FLEX mechanism for handling the status update of assets that are hidden from the project lead at project closure.
Example 4-53 Use Case: Closing a Project with Hidden Assets
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.List; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Extraction; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectAsset; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class UpdateProjectExtractions { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------- // Update a project's extractions ProjectEntities lProjectEntities = null; try { // ----------------------------------- // read an existing project Project projectRead = repository.projectRead(authToken, 50000); // ----------------------------------- // get an extraction or create one long lExtractionID = 0; ProjectAsset[] lProjectAssets = projectRead.getAssets(); if (lProjectAssets!=null && lProjectAssets.length>0) { lProjectAssets[0].getStatus(); lExtractionID = lProjectAssets[0].getID(); } else { lProjectEntities = new ProjectEntities(); lExtractionID = repository.assetRead(authToken, 569).getID(); String[] lAssetIDs = { ""+lExtractionID }; lProjectEntities.setAssetIDs(lAssetIDs); repository.projectUpdate(authToken, projectRead, lProjectEntities); } // ----------------------------------- // set the rejected assets ids String[] rejectedIds = null; projectRead = repository.projectRead(authToken, 50000); // reload modified project Extraction[] lExtractions = repository.projectReadExtractions(authToken, projectRead); rejectedIds = new String[lExtractions.length]; for (int i=0; lExtractions!=null && i<lExtractions.length; i++) { rejectedIds[i] = ""+lExtractions[i].getID(); } lProjectEntities = new ProjectEntities(); lProjectEntities.setRejectedIDs(rejectedIds); // ----------------------------------- // update the project repository.projectUpdate(authToken, projectRead, lProjectEntities); } catch (OpenAPIException ex) { ex.printStackTrace(); } // ----------------------------------- // revert extractions repository.extractionResetDatabase(); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
The process of adding users to project is similar to the process of adding related projects.
Example 4-54 Use Case: Add Users and Related Projects to a Project
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.APIValidationException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class AddUsersAndRelatedProjectsToProject { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------- // Add users and related projects to a project Project projectRead = new Project(); String[] newLeaderIDs = { "99" }; ProjectEntities lEntities = new ProjectEntities(); try { // ----------------------------------- // read an existing project projectRead = repository.projectRead(authToken, 50000); // ----------------------------------- // create two new projects Project lParentProject = createNewProject(repository, authToken, "My Parent Project"); Project lChildProject = createNewProject(repository, authToken, "My Child Project"); String[] newParentIDs = { ""+lParentProject.getID() }; String[] newChildIDs = { ""+lChildProject.getID() }; // ----------------------------------- // create two new users RegistryUser lUserOne = createNewUser(repository, authToken, "one"); RegistryUser lUserTwo = createNewUser(repository, authToken, "two"); String[] newMemberIDs = { ""+lUserOne.getID(), ""+lUserTwo.getID() }; // ----------------------------------- // set the added leader ids lEntities.setAddedLeaderIDs(newLeaderIDs); // ----------------------------------- // set the added member ids lEntities.setAddedMemberIDs(newMemberIDs); // ----------------------------------- // set the added children project ids lEntities.setAddedChildIDs(newChildIDs); // ----------------------------------- // set the added parent project ids lEntities.setAddedParentIDs(newParentIDs); // ----------------------------------- // update the project repository.projectUpdate(authToken, projectRead, lEntities); } catch (OpenAPIException ex) { throw ex; } } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } protected static Project createNewProject(FlashlineRegistry repository, AuthToken authToken, String pName) throws APIValidationException, RemoteException { Project lProject = new Project(); ProjectEntities lProjectEntities = new ProjectEntities(); lProject.setName(pName+" "+Calendar.getInstance().getTimeInMillis()); // force uniqueness lProject.setDepartmentID(50000); // a department with id 50000 must already exist String[] lLeaderIds = new String[] { "99" }; lProjectEntities.setLeaderIDs(lLeaderIds); lProject = repository.projectCreate(authToken, lProject, lProjectEntities); return lProject; } protected static RegistryUser createNewUser(FlashlineRegistry repository, AuthToken authToken, String pUserName) throws APIValidationException, RemoteException { String lUserName = pUserName + Calendar.getInstance().getTimeInMillis(); // force uniqueness RegistryUser lRegistryUser = repository.userCreate(authToken, lUserName, "First", pUserName, pUserName+"@example.com", pUserName, false, false, false); return lRegistryUser; } }
The following example presents an alternate way of adding users and related projects. In this example, the added users/projects are the ONLY users/projects assigned to the project. Any users/projects not included in the String Array of IDs are removed from the project. This option combines adding and removing users into one step.
Example 4-55 Use Case: Add and Remove Users for a Project
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.APIValidationException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class AddUsersAndRelatedProjectsToProject2 { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------- // The following example presents an alternate way of adding users and // related projects. // In this example the added users/projects are the ONLY // users/projects assigned to the project. // Any users/projects not included in the String Array of IDs are // removed from the project. // This option combines adding and removing users into one step. Project projectRead = new Project(); String[] newLeaderIDs = { "50003" }; ProjectEntities lEntities = new ProjectEntities(); try { // ----------------------------------- // read an existing project projectRead = repository.projectRead(authToken, 50000); // ----------------------------------- // create two new projects Project lParentProject = createNewProject(repository, authToken, "My Parent Project"); Project lChildProject = createNewProject(repository, authToken, "My Child Project"); String[] newParentIDs = { ""+lParentProject.getID() }; String[] newChildIDs = { ""+lChildProject.getID() }; // ----------------------------------- // create two new users RegistryUser lUserOne = createNewUser(repository, authToken, "one"); RegistryUser lUserTwo = createNewUser(repository, authToken, "two"); String[] newMemberIDs = { ""+lUserOne.getID(), ""+lUserTwo.getID() }; // ----------------------------------- // set the leader ids lEntities.setLeaderIDs(newLeaderIDs); // ----------------------------------- // set the member ids lEntities.setMemberIDs(newMemberIDs); // ----------------------------------- // set the children project ids lEntities.setChildIDs(newChildIDs); // ----------------------------------- // set the parent project ids lEntities.setParentIDs(newParentIDs); // ----------------------------------- // update the project repository.projectUpdate(authToken, projectRead, lEntities); } catch (OpenAPIException ex) { throw ex; } } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } protected static Project createNewProject(FlashlineRegistry repository, AuthToken authToken, String pName) throws APIValidationException, RemoteException { Project lProject = new Project(); ProjectEntities lProjectEntities = new ProjectEntities(); lProject.setName(pName+" "+Calendar.getInstance().getTimeInMillis()); // force uniqueness lProject.setDepartmentID(50000); // a department with id 50000 must already exist String[] lLeaderIds = new String[] { "99" }; lProjectEntities.setLeaderIDs(lLeaderIds); lProject = repository.projectCreate(authToken, lProject, lProjectEntities); return lProject; } protected static RegistryUser createNewUser(FlashlineRegistry repository, AuthToken authToken, String pUserName) throws APIValidationException, RemoteException { String lUserName = pUserName + Calendar.getInstance().getTimeInMillis(); // force uniqueness RegistryUser lRegistryUser = repository.userCreate(authToken, lUserName, "First", pUserName, pUserName+"@example.com", pUserName, false, false, false); return lRegistryUser; } }
The process of removing users from a project is similar to the process of removing related projects.
Example 4-56 Use Case: Remove Related Projects and Users from a Project
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.decision.ExtractionReassignmentDecision; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class RemoveRelatedProjectsAndUsersFromProject { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); long lParentProjectID = createProject(repository, authToken).getID(); long lChildProject1ID = createProject(repository, authToken).getID(); long lChildProject2ID = createProject(repository, authToken).getID(); long lUser1ID = createUser(repository, authToken).getID(); long lUser2ID = createUser(repository, authToken).getID(); long lUser3ID = createUser(repository, authToken).getID(); long lUser4ID = createUser(repository, authToken).getID(); long lUser5ID = createUser(repository, authToken).getID(); long lUser6ID = createUser(repository, authToken).getID(); // ----------------------------------- // Remove related projects and users from a project Project projectRead = new Project(); String[] removedParentProjectIDs = { ""+lParentProjectID }; String[] removedChildProjectIDs = { ""+lChildProject1ID, ""+lChildProject2ID }; String[] removedLeaderIDs = { ""+lUser1ID }; String[] removedMemberIDs = { ""+lUser2ID }; ProjectEntities lEntities = new ProjectEntities(); try { projectRead = repository.projectRead(authToken, 50000); } catch (OpenAPIException ex) { throw ex; } try { // ----------------------------------- // set the removed parent project ids lEntities.setRemovedParentIDs(removedParentProjectIDs); // ----------------------------------- // set the removed children project ids lEntities.setRemovedChildIDs(removedChildProjectIDs); // ----------------------------------- // set the remove leader ids lEntities.setRemovedLeaderIDs(removedLeaderIDs); // ----------------------------------- // set the removed member ids lEntities.setRemovedMemberIDs(removedMemberIDs); // ----------------------------------- // set the exraction reassignment decisions ExtractionReassignmentDecision[] decisions = new ExtractionReassignmentDecision[2]; ExtractionReassignmentDecision decision = new ExtractionReassignmentDecision(); decision.setUserID(lUser3ID); decision.setReassignUserID(lUser4ID); decisions[0] = decision; decision = new ExtractionReassignmentDecision(); decision.setUserID(lUser5ID); decision.setReassignUserID(lUser6ID); decisions[1] = decision; // ----------------------------------- // set the userid for the reassigned extracions lEntities.setReassignIDs(decisions); // ----------------------------------- // update the project repository.projectUpdate(authToken, projectRead, lEntities); } catch (OpenAPIException ex) { throw ex; } // ----------------------------------- // revert extractions repository.extractionResetDatabase(); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } protected static Project createProject(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { Project lProject = new Project(); ProjectEntities lProjectEntities = new ProjectEntities(); lProject.setName("Project "+Calendar.getInstance().getTimeInMillis()); lProject.setDepartmentID(50000); // a department with id 50000 must String[] lLeaderIds = new String[] { "99" }; lProjectEntities.setLeaderIDs(lLeaderIds); lProject = repository.projectCreate(authToken, lProject, lProjectEntities); return lProject; } protected static RegistryUser createUser(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { String lUserName = "user"+Calendar.getInstance().getTimeInMillis(); return repository.userCreate(authToken, lUserName, "First", "User", "user@example.com", "user", false, false, false); } }
As an alternative, the following example tells the system which users/projects to keep, rather than telling it which ones to remove.
Example 4-57 Use Case: Keep Specific Users and Projects in a Project
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.decision.ExtractionReassignmentDecision; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class RemoveRelatedProjectsAndUsersFromProject2 { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------- // As an alternative, the following example tells the system which // users/projects to keep, // rather than telling it which ones to remove. Project projectRead = new Project(); String[] lParentProjectIDs = { "50003" }; String[] lChildProjectIDs = { "50002", "50001" }; String[] lLeaderIDs = { "50001" }; String[] lMemberIDs = { "50005" }; ProjectEntities lEntities = new ProjectEntities(); try { projectRead = repository.projectRead(authToken, 50000); } catch (OpenAPIException ex) { throw ex; } try { // ----------------------------------- // set the parent project ids lEntities.setParentIDs(lParentProjectIDs); // ----------------------------------- // set the children project ids lEntities.setChildIDs(lChildProjectIDs); // ----------------------------------- // set the leader ids lEntities.setLeaderIDs(lLeaderIDs); // ----------------------------------- // set the member ids lEntities.setMemberIDs(lMemberIDs); // ----------------------------------- // set the extraction reassignment decisions ExtractionReassignmentDecision[] decisions = new ExtractionReassignmentDecision[2]; ExtractionReassignmentDecision decision = new ExtractionReassignmentDecision(); decision.setUserID(50011); decision.setReassignUserID(50001); decisions[0] = decision; decision = new ExtractionReassignmentDecision(); decision.setUserID(50012); decision.setReassignUserID(50005); decisions[1] = decision; // ----------------------------------- // set the userid for the reassigned extracions lEntities.setReassignIDs(decisions); // ----------------------------------- // update the project repository.projectUpdate(authToken, projectRead, lEntities); } catch (OpenAPIException ex) { throw ex; } // ----------------------------------- // revert extractions repository.extractionResetDatabase(); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Extractions can be reassigned from one user to another. The user receiving the reassigned extractions can be on the same or a different project.
Example 4-58 Use Case: Update a Project's Extractions
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.decision.ExtractionReassignmentDecision; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class UpdateProjectExtractionswithReassign { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); Project lProject = null; long currentProjectID = 50000; // an existing project with id 50000 must // exist long someProjectID = 0; // an existing project with id 50001 must // exist where re-extractions are being // assigned to long extractionID = 50002; // the id of the extraction being reassigned long reassignUserID = 0; // the id of the user being assigned to this // extraction // ----------------------------------- // Update a project's extractions - reassign extractions to a different // user on the same or different project // ----------------------------------- // read a project, get a sample project lProject = repository.projectRead(authToken, currentProjectID); someProjectID = createProject(repository, authToken).getID(); // ----------------------------------- // get a member of the project to reassign Project lReassignProject = repository.projectRead(authToken, someProjectID); String[] memberIDs = repository.projectReadMemberIDs(authToken, lReassignProject); if (memberIDs!=null && memberIDs.length>0) { reassignUserID = Long.parseLong(memberIDs[0]); } // ----------------------------------- // if no members exist, create a user and add them if (reassignUserID==0) { ProjectEntities lProjectEntities = new ProjectEntities(); reassignUserID = createUser(repository, authToken).getID(); String[] newMemberIDs = { ""+reassignUserID }; lProjectEntities.setAddedMemberIDs(newMemberIDs); repository.projectUpdate(authToken, lReassignProject, lProjectEntities); } // ----------------------------------- // set the extraction reassignment decision ExtractionReassignmentDecision[] lDecisions = new ExtractionReassignmentDecision[1]; ExtractionReassignmentDecision lDecision = new ExtractionReassignmentDecision(); // ----------------------------------- // set the reassigned project id lDecision.setProjectID(someProjectID); // ----------------------------------- // specify which extraction (by id) lDecision.setExtractionID(extractionID); // ----------------------------------- // set the reassigned user id lDecision.setReassignUserID(reassignUserID); lDecisions[0] = lDecision; // ----------------------------------- // reassign project extractions repository.projectReassignExtractions(authToken, lProject, lDecisions); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } protected static Project createProject(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { Project lProject = new Project(); ProjectEntities lProjectEntities = new ProjectEntities(); lProject.setName("Project "+Calendar.getInstance().getTimeInMillis()); lProject.setDepartmentID(50000); // a department with id 50000 must String[] lLeaderIds = new String[] { "99" }; lProjectEntities.setLeaderIDs(lLeaderIds); lProject = repository.projectCreate(authToken, lProject, lProjectEntities); return lProject; } protected static RegistryUser createUser(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { String lUserName = "user"+Calendar.getInstance().getTimeInMillis(); return repository.userCreate(authToken, lUserName, "First", "User", "user@example.com", "user", false, false, false); } }
Reassign a user and his/her extractions to another project.
Example 4-59 Use Case: Reassign Project User and User's Extraction to Another Project
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.decision.ExtractionReassignmentDecision; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class UpdateProjectExtractionswithReassign { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); Project lProject = null; long currentProjectID = 50000; // an existing project with id 50000 must // exist long someProjectID = 0; // an existing project with id 50001 must // exist where re-extractions are being // assigned to long extractionID = 50002; // the id of the extraction being reassigned long reassignUserID = 0; // the id of the user being assigned to this // extraction // ----------------------------------- // Update a project's extractions - reassign extractions to a different // user on the same or different project // ----------------------------------- // read a project, get a sample project lProject = repository.projectRead(authToken, currentProjectID); someProjectID = createProject(repository, authToken).getID(); // ----------------------------------- // get a member of the project to reassign Project lReassignProject = repository.projectRead(authToken, someProjectID); String[] memberIDs = repository.projectReadMemberIDs(authToken, lReassignProject); if (memberIDs!=null && memberIDs.length>0) { reassignUserID = Long.parseLong(memberIDs[0]); } // ----------------------------------- // if no members exist, create a user and add them if (reassignUserID==0) { ProjectEntities lProjectEntities = new ProjectEntities(); reassignUserID = createUser(repository, authToken).getID(); String[] newMemberIDs = { ""+reassignUserID }; lProjectEntities.setAddedMemberIDs(newMemberIDs); repository.projectUpdate(authToken, lReassignProject, lProjectEntities); } // ----------------------------------- // set the extraction reassignment decision ExtractionReassignmentDecision[] lDecisions = new ExtractionReassignmentDecision[1]; ExtractionReassignmentDecision lDecision = new ExtractionReassignmentDecision(); // ----------------------------------- // set the reassigned project id lDecision.setProjectID(someProjectID); // ----------------------------------- // specify which extraction (by id) lDecision.setExtractionID(extractionID); // ----------------------------------- // set the reassigned user id lDecision.setReassignUserID(reassignUserID); lDecisions[0] = lDecision; // ----------------------------------- // reassign project extractions repository.projectReassignExtractions(authToken, lProject, lDecisions); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } protected static Project createProject(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { Project lProject = new Project(); ProjectEntities lProjectEntities = new ProjectEntities(); lProject.setName("Project "+Calendar.getInstance().getTimeInMillis()); lProject.setDepartmentID(50000); // a department with id 50000 must String[] lLeaderIds = new String[] { "99" }; lProjectEntities.setLeaderIDs(lLeaderIds); lProject = repository.projectCreate(authToken, lProject, lProjectEntities); return lProject; } protected static RegistryUser createUser(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { String lUserName = "user"+Calendar.getInstance().getTimeInMillis(); return repository.userCreate(authToken, lUserName, "First", "User", "user@example.com", "user", false, false, false); } }
Users can be reassigned from one project to another. If the user is to be moved without his/her extractions, the extractions must first be reassigned to another project member before the user is reassigned.
Example 4-60 Use Case: Reassign User Only to Another Project
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.decision.ExtractionReassignmentDecision; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Extraction; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.entity.ProjectUserType; import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class UpdateProjectUserWithReassign2 { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); Project lProject = null; Project someProject = null; // the id the other project Project reassignProject = null; // the id of the project being reassigned long currentProjectID = 50000; // the id of the current project long extractionID = 0; // the id of the extraction long extractionReassignUserID = 0; // the id of the user being // reassigned long projectReassignUserID = 0; // the id of the user being reassigned // ----------------------------------- // Update a project's user - reassign only the user (not their // extractions) to another project // ----------------------------------- // read a project lProject = repository.projectRead(authToken, currentProjectID); // ----------------------------------- // create some projects someProject = createProject(repository, authToken); reassignProject = createProject(repository, authToken); // ----------------------------------- // get a member of the project to reassign String[] memberIDs = repository.projectReadMemberIDs(authToken, lProject); if (memberIDs!=null && memberIDs.length>0) { extractionReassignUserID = Long.parseLong(memberIDs[0]); if (memberIDs.length>1) { projectReassignUserID = Long.parseLong(memberIDs[0]); } } // ----------------------------------- // if no members exist, create users and add them if (extractionReassignUserID==0) { ProjectEntities lProjectEntities = new ProjectEntities(); extractionReassignUserID = createUser(repository, authToken).getID(); lProjectEntities.setAddedMemberIDs(new String[]{ ""+extractionReassignUserID }); repository.projectUpdate(authToken, lProject, lProjectEntities); } if (projectReassignUserID==0) { ProjectEntities lProjectEntities = new ProjectEntities(); projectReassignUserID = createUser(repository, authToken).getID(); lProjectEntities.setAddedMemberIDs(new String[]{ ""+projectReassignUserID }); repository.projectUpdate(authToken, lProject, lProjectEntities); } // get extraction for user or create one Extraction[] lAssetExtractions = repository.projectReadExtractions(authToken, lProject); if (lAssetExtractions!=null && lAssetExtractions.length>0) { extractionID = lAssetExtractions[0].getID(); } if (extractionID==0) { // create new extraction ProjectEntities lProjectEntities = new ProjectEntities(); Asset lAsset = repository.assetRead(authToken, 569); lProjectEntities.setAssetIDs(new String[]{ ""+lAsset.getID() }); repository.projectUpdate(authToken, lProject, lProjectEntities); } // ----------------------------------- // add users to reassign project (if they aren't already) { Project lReassignProject = repository.projectRead(authToken, reassignProject.getID()); boolean isMemberExtraction = false, isMemberProject = false; String[] reassignMemberIDs = repository.projectReadMemberIDs(authToken, lReassignProject); for (int i=0; reassignMemberIDs!=null && i<reassignMemberIDs.length; i++) { if (Long.parseLong(reassignMemberIDs[i].trim())==extractionReassignUserID) isMemberExtraction = true; if (Long.parseLong(reassignMemberIDs[i].trim())==projectReassignUserID) isMemberProject = true; } if (!isMemberExtraction) { ProjectEntities lProjectEntities = new ProjectEntities(); lProjectEntities.setAddedMemberIDs(new String[]{ ""+extractionReassignUserID }); repository.projectUpdate(authToken, lReassignProject, lProjectEntities); } if (!isMemberProject) { ProjectEntities lProjectEntities = new ProjectEntities(); lProjectEntities.setAddedMemberIDs(new String[]{ ""+projectReassignUserID }); repository.projectUpdate(authToken, lReassignProject, lProjectEntities); } } // ----------------------------------- // add users to some project (if they aren't already) { Project lSomeProject = repository.projectRead(authToken, someProject.getID()); boolean isMemberExtraction = false, isMemberProject = false; String[] SomeMemberIDs = repository.projectReadMemberIDs(authToken, lSomeProject); for (int i=0; SomeMemberIDs!=null && i<SomeMemberIDs.length; i++) { if (Long.parseLong(SomeMemberIDs[i].trim())==extractionReassignUserID) isMemberExtraction = true; if (Long.parseLong(SomeMemberIDs[i].trim())==projectReassignUserID) isMemberProject = true; } if (!isMemberExtraction) { ProjectEntities lProjectEntities = new ProjectEntities(); lProjectEntities.setAddedMemberIDs(new String[]{ ""+extractionReassignUserID }); repository.projectUpdate(authToken, lSomeProject, lProjectEntities); } if (!isMemberProject) { ProjectEntities lProjectEntities = new ProjectEntities(); lProjectEntities.setAddedMemberIDs(new String[]{ ""+projectReassignUserID }); repository.projectUpdate(authToken, lSomeProject, lProjectEntities); } } // ----------------------------------- // set extraction reassignment decision ExtractionReassignmentDecision[] lDecisions = new ExtractionReassignmentDecision[1]; ExtractionReassignmentDecision lDecision = new ExtractionReassignmentDecision(); // set the reassign decision's project id lDecision.setProjectID(someProject.getID()); // set the reassign decision's extraction id lDecision.setExtractionID(extractionID); // set the reassign decision's reassigned user ids lDecision.setReassignUserID(extractionReassignUserID); lDecisions[0] = lDecision; // reassign project extractions repository.projectReassignExtractions(authToken, lProject, lDecisions); // verify reassignment lProject = repository.projectRead(authToken, currentProjectID); ProjectUserType userType = repository .projectReadUserTypes(authToken); lDecisions = new ExtractionReassignmentDecision[1]; lDecision = new ExtractionReassignmentDecision(); lDecision.setProjectID(reassignProject.getID()); lDecision.setReassignUserID(projectReassignUserID); lDecision.setReassignType(userType.getUserTypeLeader()); lDecisions[0] = lDecision; repository.projectReassignUsers(authToken, lProject, lDecisions); // ----------------------------------- // revert extractions repository.extractionResetDatabase(); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } protected static Project createProject(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { Project lProject = new Project(); ProjectEntities lProjectEntities = new ProjectEntities(); lProject.setName("Project "+Calendar.getInstance().getTimeInMillis()); lProject.setDepartmentID(50000); // a department with id 50000 must String[] lLeaderIds = new String[] { "99" }; lProjectEntities.setLeaderIDs(lLeaderIds); lProject = repository.projectCreate(authToken, lProject, lProjectEntities); return lProject; } protected static RegistryUser createUser(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { String lUserName = "user"+Calendar.getInstance().getTimeInMillis(); return repository.userCreate(authToken, lUserName, "First", "User", "user@example.com", "user", false, false, false); } }
Reads the value-provided detail for a project and asset.
Example 4-61 Use Case: Read the Value-Provided for a Project and Asset
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Answer; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Choice; import com.flashline.registry.openapi.entity.ChoiceList; import com.flashline.registry.openapi.entity.Extraction; import com.flashline.registry.openapi.entity.ExtractionDownload; import com.flashline.registry.openapi.entity.ProjectAssetValue; import com.flashline.registry.openapi.entity.Question; import com.flashline.registry.openapi.entity.SurveyTaken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ReadValueProvidedForProjectAndAsset { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------- // Read the value provided for a project and asset long projectid = 50000; // the id of the project long assetid = 569; // the id of the asset // ----------------------------------- // Make sure the project has an extraction long[] lAssetIDs = { assetid }; ExtractionDownload[] extractionDownload = repository.extractionCreate(authToken, projectid, lAssetIDs); Extraction extraction = repository.extractionReadByProjectAndAsset(authToken, projectid, assetid); // ----------------------------------- // take survey and update SurveyTaken surveyTaken = takeSurvey(repository, authToken, extraction); surveyTaken = repository.surveyTakenUpdate(authToken, surveyTaken); extraction = repository.extractionUpdateSurvey(authToken, extraction, surveyTaken); // ----------------------------------- // read project asset values ProjectAssetValue[] projectAssetValues = repository .projectAssetValueRead(authToken, projectid, assetid); if (projectAssetValues != null) { for (int i = 0; i < projectAssetValues.length; i++) { ProjectAssetValue projectAssetValue = projectAssetValues[i]; projectAssetValue.getUserInfo().getUserName(); projectAssetValue.getExtractionDate(); projectAssetValue.getExtractionStatus(); projectAssetValue.getPredictedValue(); projectAssetValue.isPredictedValueSelected(); projectAssetValue.getConsumerFoundValue(); projectAssetValue.getConsumerUsage(); projectAssetValue.getConsumerValue(); projectAssetValue.isConsumerValueSelected(); projectAssetValue.getProjectLeadUsage(); projectAssetValue.getProjectLeadValue(); projectAssetValue.isProjectLeadValueSelected(); projectAssetValue.getAssetUsage(); projectAssetValue.getAssetValue(); projectAssetValue.getAssetValueSource(); } } // ----------------------------------- // revert extractions repository.extractionResetDatabase(); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } protected static SurveyTaken takeSurvey(FlashlineRegistry repository, AuthToken authToken, Extraction extraction) throws OpenAPIException, RemoteException { // ----------------------------------- // take survey SurveyTaken surveyTaken = repository.surveyTakenRead(authToken, extraction); Question[] questions = repository.surveyReadQuestions(authToken); ChoiceList choiceList = null; Choice[] choices = null; Answer[] answers = new Answer[4]; for(int i=0; i<answers.length; i++){ answers[i] = new Answer(); } // ----------------------------------- //Sort questions Question[] sortedQuestions = new Question[4]; for (int i=0;i<questions.length;i++) { if (questions[i].getId()==100) { sortedQuestions[0] = questions[i]; } if (questions[i].getId()==101) { sortedQuestions[1] = questions[i]; } if (questions[i].getId()==102) { sortedQuestions[2] = questions[i]; } if (questions[i].getId()==103) { sortedQuestions[3] = questions[i]; } } answers[0].setQuestionId(sortedQuestions[0].getId()); choiceList = sortedQuestions[0].getChoiceList(); choices = choiceList.getChoices(); answers[0].setChoiceId(choices[0].getId()); answers[0].setValue(choices[0].getValue()); answers[1].setQuestionId(sortedQuestions[1].getId()); answers[1].setChoiceId(0); answers[1].setValue("100"); answers[2].setQuestionId(sortedQuestions[2].getId()); answers[2].setChoiceId(0); answers[2].setValue("200"); answers[3].setQuestionId(sortedQuestions[3].getId()); choiceList = sortedQuestions[3].getChoiceList(); choices = choiceList.getChoices(); answers[3].setChoiceId(choices[3].getId()); answers[3].setValue(choices[3].getValue()); surveyTaken.setAnswers(answers); return surveyTaken; } }
Uses the predicted value to update the value-provided for a project and asset.
Example 4-62 Use Case: Update the Value Provided for a Project and Asset - Use Predicted Value
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Answer; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Choice; import com.flashline.registry.openapi.entity.ChoiceList; import com.flashline.registry.openapi.entity.Extraction; import com.flashline.registry.openapi.entity.ExtractionDownload; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectAssetValue; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.entity.Question; import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.entity.SurveyTaken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class UpdateValueProvidedForProjectAndUserWithPredictedValue { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL( pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------- // Update the value provided for a project and asset - use predicted value long userid = repository.userReadByAuthToken(authToken).getID(); // the id of the user long projectid = 50000; // the id of the project long assetid = 569; // the id of the asset repository.testExtractionResetDatabaseForProject(projectid); // for sample *only* Project lProject = repository.projectRead(authToken, projectid); // ----------------------------------- // if no user id exists, create a user if (userid==0) { userid = createUser(repository, authToken).getID(); } ProjectEntities lProjectEntities = new ProjectEntities(); lProjectEntities.setAddedLeaderIDs(new String[]{ ""+userid }); repository.projectUpdate(authToken, lProject, lProjectEntities); // ----------------------------------- // Get a RegistryUser for a user RegistryUser user = repository.userRead(authToken, userid); // ----------------------------------- // Make sure the project has an extraction long[] lAssetIDs = { assetid }; ExtractionDownload[] extractionDownload = repository.extractionCreate(authToken, projectid, lAssetIDs); Extraction extraction = repository.extractionReadByProjectAndAsset(authToken, projectid, assetid); // ----------------------------------- // take survey SurveyTaken surveyTaken = repository.surveyTakenRead(authToken, extraction); Question[] questions = repository.surveyReadQuestions(authToken); ChoiceList choiceList = null; Choice[] choices = null; Answer[] answers = new Answer[4]; for(int i=0; i<answers.length; i++){ answers[i] = new Answer(); } // ----------------------------------- //Sort questions Question[] sortedQuestions = new Question[4]; for (int i=0;i<questions.length;i++) { if (questions[i].getId()==100) { sortedQuestions[0] = questions[i]; } if (questions[i].getId()==101) { sortedQuestions[1] = questions[i]; } if (questions[i].getId()==102) { sortedQuestions[2] = questions[i]; } if (questions[i].getId()==103) { sortedQuestions[3] = questions[i]; } } answers[0].setQuestionId(sortedQuestions[0].getId()); choiceList = sortedQuestions[0].getChoiceList(); choices = choiceList.getChoices(); answers[0].setChoiceId(choices[0].getId()); answers[0].setValue(choices[0].getValue()); answers[1].setQuestionId(sortedQuestions[1].getId()); answers[1].setChoiceId(0); answers[1].setValue("100"); answers[2].setQuestionId(sortedQuestions[2].getId()); answers[2].setChoiceId(0); answers[2].setValue("200"); answers[3].setQuestionId(sortedQuestions[3].getId()); choiceList = sortedQuestions[3].getChoiceList(); choices = choiceList.getChoices(); answers[3].setChoiceId(choices[3].getId()); answers[3].setValue(choices[3].getValue()); surveyTaken.setAnswers(answers); // ----------------------------------- // update survey surveyTaken = repository.surveyTakenUpdate(authToken, surveyTaken); extraction = repository.extractionUpdateSurvey(authToken, extraction, surveyTaken); // ----------------------------------- // Get a ProjectAssetValue for a project asset and user. ProjectAssetValue projectAssetValue = repository .projectAssetValueReadForUser(authToken, projectid, assetid, user); if (projectAssetValue != null) { // ----------------------------------- // update the project asset value projectAssetValue = repository.projectAssetValueUpdate( authToken, projectAssetValue, "predicted_selected"); } // ----------------------------------- // revert extractions repository.extractionResetDatabase(); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } protected static RegistryUser createUser(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { String lUserName = "user"+Calendar.getInstance().getTimeInMillis(); return repository.userCreate(authToken, lUserName, "First", "User", "user@example.com", "user", false, false, false); } }
Uses the consumer value to update the value-provided for a project and asset.
Example 4-63 Use Case: Update the Value Provided for a Project and Asset - Use Consumer Value
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Answer; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Choice; import com.flashline.registry.openapi.entity.ChoiceList; import com.flashline.registry.openapi.entity.Extraction; import com.flashline.registry.openapi.entity.ExtractionDownload; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectAssetValue; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.entity.Question; import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.entity.SurveyTaken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class UpdateValueProvidedForProjectAndUserWithConsumerValue { public static void main(String[] pArgs) { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL( pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------- // Update the value-provided for a project and asset - use consumer value long userID = repository.userReadByAuthToken(authToken).getID(); // ID of the user being read long projectID = 50000; // ID of project being updated long assetID = 569; // ID of asset repository.testExtractionResetDatabaseForProject(projectID); // for sample *only* Project lProject = repository.projectRead(authToken, projectID); // ----------------------------------- // if no user id exists, create a user if (userID==0) { userID = createUser(repository, authToken).getID(); } ProjectEntities lProjectEntities = new ProjectEntities(); lProjectEntities.setAddedLeaderIDs(new String[]{ ""+userID }); repository.projectUpdate(authToken, lProject, lProjectEntities); // ----------------------------------- // Get the user RegistryUser user = repository.userRead(authToken, userID); // ----------------------------------- // Make sure the project has an extraction long[] lAssetIDs = { assetID }; ExtractionDownload[] extractionDownload = repository.extractionCreate(authToken, projectID, lAssetIDs); Extraction extraction = repository.extractionReadByProjectAndAsset(authToken, projectID, assetID); // ----------------------------------- // take survey SurveyTaken surveyTaken = repository.surveyTakenRead(authToken, extraction); Question[] questions = repository.surveyReadQuestions(authToken); ChoiceList choiceList = null; Choice[] choices = null; Answer[] answers = new Answer[4]; for(int i=0; i<answers.length; i++){ answers[i] = new Answer(); } // ----------------------------------- //Sort questions Question[] sortedQuestions = new Question[4]; for (int i=0;i<questions.length;i++) { if (questions[i].getId()==100) { sortedQuestions[0] = questions[i]; } if (questions[i].getId()==101) { sortedQuestions[1] = questions[i]; } if (questions[i].getId()==102) { sortedQuestions[2] = questions[i]; } if (questions[i].getId()==103) { sortedQuestions[3] = questions[i]; } } answers[0].setQuestionId(sortedQuestions[0].getId()); choiceList = sortedQuestions[0].getChoiceList(); choices = choiceList.getChoices(); answers[0].setChoiceId(choices[0].getId()); answers[0].setValue(choices[0].getValue()); answers[1].setQuestionId(sortedQuestions[1].getId()); answers[1].setChoiceId(0); answers[1].setValue("100"); answers[2].setQuestionId(sortedQuestions[2].getId()); answers[2].setChoiceId(0); answers[2].setValue("200"); answers[3].setQuestionId(sortedQuestions[3].getId()); choiceList = sortedQuestions[3].getChoiceList(); choices = choiceList.getChoices(); answers[3].setChoiceId(choices[3].getId()); answers[3].setValue(choices[3].getValue()); surveyTaken.setAnswers(answers); // ----------------------------------- // update survey surveyTaken = repository.surveyTakenUpdate(authToken, surveyTaken); extraction = repository.extractionUpdateSurvey(authToken, extraction, surveyTaken); // ----------------------------------- // Get a ProjectAssetValue for a project asset and user. ProjectAssetValue projectAssetValue = repository .projectAssetValueReadForUser(authToken, projectID, assetID, user); if (projectAssetValue != null) { // If a ProjectAssetValue does not exist for this project, asset, and // user combination a null value is returned. ProjectAssetValue projectAssetValueSelection = new ProjectAssetValue(); projectAssetValue = repository.projectAssetValueUpdate( authToken, projectAssetValue, "consumer_selected"); } } catch (OpenAPIException oapie) { System.out.println("ServerCode = " + oapie.getServerErrorCode()); System.out.println("Message = " + oapie.getMessage()); System.out.println("StackTrace:"); oapie.printStackTrace(); } catch (RemoteException re) { re.printStackTrace(); } catch (ServiceException se) { se.printStackTrace(); } catch (MalformedURLException mue) { mue.printStackTrace(); } } protected static RegistryUser createUser(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { String lUserName = "user"+Calendar.getInstance().getTimeInMillis(); return repository.userCreate(authToken, lUserName, "First", "User", "user@example.com", "user", false, false, false); } }
Uses the project lead value to update the value-provided for a project and asset.
Example 4-64 Use Case: Update the Value Provided for a Project and Asset - Use Project Lead Value
package com.flashline.sample.projectapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Answer; import com.flashline.registry.openapi.entity.AssetUsageType; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Choice; import com.flashline.registry.openapi.entity.ChoiceList; import com.flashline.registry.openapi.entity.Extraction; import com.flashline.registry.openapi.entity.ExtractionDownload; import com.flashline.registry.openapi.entity.Project; import com.flashline.registry.openapi.entity.ProjectAssetValue; import com.flashline.registry.openapi.entity.ProjectEntities; import com.flashline.registry.openapi.entity.Question; import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.entity.SurveyTaken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class UpdateValueProvidedForProjectAndUserWithLeadValue { public static void main(String[] pArgs) { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL( pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------- // Update the value provided for a project and asset - use project lead value long userID = repository.userReadByAuthToken(authToken).getID(); // ID of the user being read long projectID = 50000; // ID of project being updated long assetID = 569; // ID of asset float newValue = 50.0f; // Project asset value repository.testExtractionResetDatabaseForProject(projectID); // for sample *only* Project lProject = repository.projectRead(authToken, projectID); // ----------------------------------- // if no user id exists, create a user if (userID==0) { userID = createUser(repository, authToken).getID(); } ProjectEntities lProjectEntities = new ProjectEntities(); lProjectEntities.setAddedLeaderIDs(new String[]{ ""+userID }); repository.projectUpdate(authToken, lProject, lProjectEntities); // ----------------------------------- // Get a RegistryUser for a user. RegistryUser user = repository.userRead(authToken, userID); // ----------------------------------- // Make sure the project has an extraction long[] lAssetIDs = { assetID }; ExtractionDownload[] extractionDownload = repository.extractionCreate(authToken, projectID, lAssetIDs); Extraction extraction = repository.extractionReadByProjectAndAsset(authToken, projectID, assetID); // ----------------------------------- // take survey SurveyTaken surveyTaken = repository.surveyTakenRead(authToken, extraction); Question[] questions = repository.surveyReadQuestions(authToken); ChoiceList choiceList = null; Choice[] choices = null; Answer[] answers = new Answer[4]; for(int i=0; i<answers.length; i++){ answers[i] = new Answer(); } // ----------------------------------- //Sort questions Question[] sortedQuestions = new Question[4]; for (int i=0;i<questions.length;i++) { if (questions[i].getId()==100) { sortedQuestions[0] = questions[i]; } if (questions[i].getId()==101) { sortedQuestions[1] = questions[i]; } if (questions[i].getId()==102) { sortedQuestions[2] = questions[i]; } if (questions[i].getId()==103) { sortedQuestions[3] = questions[i]; } } answers[0].setQuestionId(sortedQuestions[0].getId()); choiceList = sortedQuestions[0].getChoiceList(); choices = choiceList.getChoices(); answers[0].setChoiceId(choices[0].getId()); answers[0].setValue(choices[0].getValue()); answers[1].setQuestionId(sortedQuestions[1].getId()); answers[1].setChoiceId(0); answers[1].setValue("100"); answers[2].setQuestionId(sortedQuestions[2].getId()); answers[2].setChoiceId(0); answers[2].setValue("200"); answers[3].setQuestionId(sortedQuestions[3].getId()); choiceList = sortedQuestions[3].getChoiceList(); choices = choiceList.getChoices(); answers[3].setChoiceId(choices[3].getId()); answers[3].setValue(choices[3].getValue()); surveyTaken.setAnswers(answers); // ----------------------------------- // update survey surveyTaken = repository.surveyTakenUpdate(authToken, surveyTaken); extraction = repository.extractionUpdateSurvey(authToken, extraction, surveyTaken); // ----------------------------------- // Get a ~ProjectAssetValue for a project asset and user. ProjectAssetValue projectAssetValue = repository .projectAssetValueReadForUser(authToken, projectID, assetID, user); if (projectAssetValue != null) { // A null value is returned if no If a ProjectAssetValue does not exists // for this project, asset, and user combination. // ----------------------------------- // Get an ~AssetUsageType array. AssetUsageType[] usageTypes = repository .projectAssetValueReadTypes(authToken); projectAssetValue.setProjectLeadUsage(usageTypes[1].getName()); // Set the projectAssetValue to a AssetUsageType value. projectAssetValue.setProjectLeadValue(newValue); // Set to a new value. ProjectAssetValue projectAssetValueSelection = new ProjectAssetValue(); projectAssetValue = repository.projectAssetValueUpdate( authToken, projectAssetValue, "predicted_selected"); } } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } protected static RegistryUser createUser(FlashlineRegistry repository, AuthToken authToken) throws OpenAPIException, RemoteException { String lUserName = "user"+Calendar.getInstance().getTimeInMillis(); return repository.userCreate(authToken, lUserName, "First", "User", "user@example.com", "user", false, false, false); } }
This section provides use cases for the Relationship Types API that describe how to create a new relationship type and modify or query related assets in Oracle Enterprise Repository.
The Relationship Type defines the structure of a relationship that is used to associate two assets.
When creating or editing assets, Relationship Types are used to define or modify the relationships that exist between assets.
This section describes the use cases using the Relationship Types API. It includes the following topics:
Creating a new type of relationship to be used between assets.
Example 4-65 Use Case: Create a New Relationship Type
package com.flashline.sample.relationshiptypeapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.RelationshipType; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CreateNewRelationshipType { public static void main(String pArgs[]) throws java.rmi.RemoteException, OpenAPIException { try{ /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository =new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------------- // create the new relationship type String newRelationshipTypeName ="My-NewRelationshipTypeName"; //Relationship Type name must contain only alpha characters or hyphens RelationshipType newRelationshipType = repository.relationshipTypeCreate(authToken, newRelationshipTypeName); System.out.println("The new relationshipType id = "+newRelationshipType.getID()+" "); // ----------------------------------------- // set the direction definition and the display text describing the relationship type //// Two-way = "BIDIRECTIONAL" //// Two-way, order matters = "ORDERED-BIDIRECTIONAL" //// One-way = "UNIDIRECTIONAL" newRelationshipType.setDirection("ORDERED-BIDIRECTIONAL"); newRelationshipType.setDisplayPrimary("Contained In"); // Source Asset - 'Contained In' - Target Asset newRelationshipType.setDisplaySecondary("Contains"); // Target Asset - 'Contains' - Source Asset newRelationshipType = repository.relationshipTypeUpdate(authToken, newRelationshipType); // ----------------------------------------- // delete the new relationship type repository.relationshipTypeDelete(authToken, newRelationshipType.getID()); }catch(OpenAPIException lEx) { System.out.println("ServerCode = "+ lEx.getServerErrorCode()); System.out.println("Message = "+ lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
A target asset is related to other assets using My RelationshipType. Using this same relationship type, establish a relationship to an additional asset.
Example 4-66 Use Case: Modify Related Assets
package com.flashline.sample.relationshiptypeapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.RelationshipType; import com.flashline.registry.openapi.query.RelationshipTypeCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class FindRelationshipTypeAndUseInAsset { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try{ /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository =new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); Asset myAsset = repository.assetRead(authToken, 563); //MY_OTHER_ASSET_ID should be an integer and should be the id of an asset in the repository RelationshipType[] allRelationshipTypes = getAllRelationshipTypes(repository, authToken); for (int i = 0; i < allRelationshipTypes.length; i++) { if (allRelationshipTypes[i].getName().equals("MyRelationshipType2")) { //This is the relationship type, modify the assets that are related // using it RelationshipType myRelationshipType = allRelationshipTypes[i]; Asset otherAsset = repository.assetRead(authToken, 569); //569= MY_OTHER_ASSET_ID //MY_OTHER_ASSET_ID should be an integer and should be the id of an asset in the repository //add this asset to the list of related assets long[] oldSecondaryIDs = myRelationshipType.getSecondaryIDs(); long[] newSecondaryIDs = new long[oldSecondaryIDs.length + 1]; for (int j = 0; j < oldSecondaryIDs.length; j++) { newSecondaryIDs[j] = oldSecondaryIDs[j]; } newSecondaryIDs[newSecondaryIDs.length - 1] = otherAsset.getID(); myRelationshipType.setSecondaryIDs(newSecondaryIDs); } } myAsset.setRelationshipTypes(allRelationshipTypes); repository.assetUpdate(authToken, myAsset); }catch(OpenAPIException lEx) { System.out.println("ServerCode = "+ lEx.getServerErrorCode()); System.out.println("Message = "+ lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } /** * This method returns every relationship type in the repository * @param repository * @param authToken * @return * @throws RemoteException */ public static RelationshipType[] getAllRelationshipTypes(FlashlineRegistry repository, AuthToken authToken) throws RemoteException { //Create an empty relationship type criteria object RelationshipTypeCriteria criteria = new RelationshipTypeCriteria(); criteria.setNameCriteria(""); RelationshipType[] allRelationshipTypes = repository.relationshipTypeQuery(authToken, criteria); return allRelationshipTypes; } }
Note:
Methods to Avoid - SetPromptNotifySecondary()Querying for related asset types.
Example 4-67 Use Case: Query Related Assets
package com.flashline.sample.relationshiptypeapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.RelationshipType; import com.flashline.registry.openapi.query.RelationshipTypeCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class FindRelationshipTypeAndUseInAsset { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try{ /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository =new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); Asset myAsset = repository.assetRead(authToken, 563); //MY_OTHER_ASSET_ID should be an integer and should be the id of an asset in the repository RelationshipType[] allRelationshipTypes = getAllRelationshipTypes(repository, authToken); for (int i = 0; i < allRelationshipTypes.length; i++) { if (allRelationshipTypes[i].getName().equals("MyRelationshipType2")) { //This is the relationship type, modify the assets that are related // using it RelationshipType myRelationshipType = allRelationshipTypes[i]; Asset otherAsset = repository.assetRead(authToken, 569); //569= MY_OTHER_ASSET_ID //MY_OTHER_ASSET_ID should be an integer and should be the id of an asset in the repository //add this asset to the list of related assets long[] oldSecondaryIDs = myRelationshipType.getSecondaryIDs(); long[] newSecondaryIDs = new long[oldSecondaryIDs.length + 1]; for (int j = 0; j < oldSecondaryIDs.length; j++) { newSecondaryIDs[j] = oldSecondaryIDs[j]; } newSecondaryIDs[newSecondaryIDs.length - 1] = otherAsset.getID(); myRelationshipType.setSecondaryIDs(newSecondaryIDs); } } myAsset.setRelationshipTypes(allRelationshipTypes); repository.assetUpdate(authToken, myAsset); }catch(OpenAPIException lEx) { System.out.println("ServerCode = "+ lEx.getServerErrorCode()); System.out.println("Message = "+ lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } /** * This method returns every relationship type in the repository * @param repository * @param authToken * @return * @throws RemoteException */ public static RelationshipType[] getAllRelationshipTypes(FlashlineRegistry repository, AuthToken authToken) throws RemoteException { //Create an empty relationship type criteria object RelationshipTypeCriteria criteria = new RelationshipTypeCriteria(); criteria.setNameCriteria(""); RelationshipType[] allRelationshipTypes = repository.relationshipTypeQuery(authToken, criteria); return allRelationshipTypes; } }
Example of the RelationshipTypeQuery
try { RelationshipTypeCriteria rCriteria = new RelationshipTypeCriteria(); RelationshipType[] allRelationshipTypes = FlashlineRegistry.relationshipQuery(lAuthToken, rCriteria); } catch (OpenAPIException e) { e.printStackTrace(); } catch (RemoteException re) { re.printStackTrace(); }
This section provides a use case for the Role API that describes how to create, read, update, delete, or query a role in Oracle Enterprise Repository.
The Role Subsystem provides a Web Services-based mechanism that is used to create, read, update, query, and otherwise manipulate Oracle Enterprise Repository Roles.
For more information, see Section 4.4.18, "User API".
import com.flashline.registry.openapi.entity.Role; import com.flashline.registry.openapi.query.RoleCriteria;
Create a new role
Read a role
Update a role
Delete a role
Query for roles
Example 4-68 Use Case: Manipulate Roles
package com.flashline.sample.roleapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Role; import com.flashline.registry.openapi.query.RoleCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class Roles { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------------- // Create a new role String lName = "new_role_type_name"; String lDesc = "new_role_type_desc"; boolean lDeafultForNewUser = true; Role lRole = null; lRole = repository.roleCreate(authToken, lName, lDesc, lDeafultForNewUser); // ----------------------------------------- // Read a Role String lRoleName = lName; Role lRole2 = null; lRole2 = repository.roleRead(authToken, lRoleName); // ----------------------------------------- // Update a Role String lRoleName3 = lName; Role lRole3 = null; lRole3 = repository.roleRead(authToken, lRoleName3); lRole3.setName("user_modified"); lRole3.setStatus(20); lRole3 = repository.roleUpdate(authToken, lRole); // ----------------------------------------- // Delete a Role String lRoleName4 = "user_modified"; // role name must exist in OER Role lRole4 = repository.roleRead(authToken, lRoleName4); if (lRole4==null) { lRole4 = repository.roleRead(authToken, lName); } if (lRole4!=null) { try { repository.roleDelete(authToken, lRole4.getName()); } catch (OpenAPIException e) { e.printStackTrace(); } } // ----------------------------------------- // This method is used to query for roles. Role[] lRoles = null; RoleCriteria lRoleCriteria = null; lRoleCriteria = new RoleCriteria(); lRoleCriteria.setNameCriteria("user"); lRoles = repository.roleQuery(authToken, lRoleCriteria); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
This section provides use cases for the Subscriptions API that describe how to create, read, or delete subscriptions to assets and how to read users subscribed to an asset in Oracle Enterprise Repository.
The Subscriptions API provides a mechanism for users to manage the assets to which a user is subscribed. Subscription, in this context, refers specifically to email subscriptions. Subscriptions created through this API are the equivalent of users clicking the Subscribe button on the asset detail page. After a user subscribes to an asset, they are notified through email of events occurring on the asset. For a list of events for which subscribed users are notified, see the "Email Templates" section in Oracle Enterprise Repository.
Using the Subscriptions API of REX, developers can create, delete, and inspect subscriptions to lists of assets. The operations are always performed for the user identified in the authentication token passed as an argument to the various subscription methods.
This section describes the use cases using the Subscriptions API. It includes the following topics:
Section 4.4.16.1.2, "Use Case: Create Subscription to Assets"
Section 4.4.16.1.3, "Use Case: Delete Subscription to Assets"
Section 4.4.16.1.4, "Use Case: Read Subscriptions for Assets"
Section 4.4.16.1.5, "Use Case: Read Users Subscribed to an Asset"
Authenticate with REX.
Read a list of asset summaries through a query.
Subscribe to the matched assets.
Example 4-69 Use Case: Create a Subscription to Assets
package com.flashline.sample.subscriptionapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AssetSummary; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.query.AssetCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class CreateSubscription { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { // ///////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository // ///////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ///////////////////////////////////////////////////////// // Login to OER // ///////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ///////////////////////////////////////////////////////// // find the assets to which to subscribe // ///////////////////////////////////////////////////////// AssetCriteria criteria = new AssetCriteria(); criteria.setNameCriteria("%"); AssetSummary[] lAssetSummaries = repository.assetQuerySummary(authToken, criteria); // ///////////////////////////////////////////////////////// // Iterate through assets, pulling out the ids and adding // to the array of longs // ///////////////////////////////////////////////////////// long[] lAssetIDs = new long[lAssetSummaries.length]; for (int i = 0; i < lAssetSummaries.length; i++) { lAssetIDs[i] = lAssetSummaries[i].getID(); } // ///////////////////////////////////////////////////////// // Create the subscriptions. The value of "false" for the // parameter pFailOnAnyError, causes the operation to NOT // fail for any asset to which the user does not have VIEW // privileges, or for which the asset is not subscribable. // // If this value is not "false", the operation throws // an exception if any asset in the array of asset IDs is // not subscribable or viewable by the user, and NONE of the // subscriptions are recorded in the repository. // ///////////////////////////////////////////////////////// repository.subscriptionCreate(authToken, lAssetIDs, false); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Authenticate with REX.
Read a list of asset summaries through a query.
Delete any subscriptions that may exist for the matched assets.
Example 4-70 Use Case: Delete a Subscription to Assets
package com.flashline.sample.subscriptionapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AssetSummary; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.query.AssetCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class DeleteSubscription { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); /////////////////////////////////////////////////////////// // Login to OER /////////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); /////////////////////////////////////////////////////////// // find the assets for which to delete subscriptions /////////////////////////////////////////////////////////// AssetCriteria criteria = new AssetCriteria(); criteria.setNameCriteria("%"); AssetSummary[] lAssetSummaries = repository.assetQuerySummary(authToken, criteria); /////////////////////////////////////////////////////////// // Iterate through assets, pulling out the ids and adding // to the array of longs /////////////////////////////////////////////////////////// long[] lAssetIDs = new long[lAssetSummaries.length]; for (int i = 0; i < lAssetSummaries.length; i++) { lAssetIDs[i] = lAssetSummaries[i].getID(); } /////////////////////////////////////////////////////////// // Delete the subscriptions on the list of assets. /////////////////////////////////////////////////////////// repository.subscriptionDelete(authToken, lAssetIDs); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Authenticate with REX.
Read the list of subscribed assets for the authenticated user.
Example 4-71 Use Case: Read Subscriptions for Assets
package com.flashline.sample.subscriptionapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ReadSubscriptions { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); /////////////////////////////////////////////////////////// // Login to OER /////////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); ////////////////////////////////////////////////////////// // Read all of the assets to which the user is subscribed. ////////////////////////////////////////////////////////// long[] lSubscribedAssets = repository.subscriptionReadSubscribedAssets(authToken); ////////////////////////////////////////////////////////// // Print out the assets to which the user is subscribed ////////////////////////////////////////////////////////// Asset[] lAssets = repository.assetReadArray(authToken, lSubscribedAssets); System.out.println("Subscribed Assets for user "+pArgs[1]); for(int i=0; i<lAssets.length; i++){ System.out.println(" -> "+lAssets[i].getLongName()); } } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
Authenticate with REX.
Read the list of users subscribed to a particular asset.
Example 4-72 Use Case: Read Users Subscribed to an Asset
package com.flashline.sample.subscriptionapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AssetSummary; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.query.AssetCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class ReadSubscribersToAsset { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); /////////////////////////////////////////////////////////// // Login to OER /////////////////////////////////////////////////////////// AuthToken authToken = repository.authTokenCreate( pArgs[1],pArgs[2]); ////////////////////////////////////////////////////////// // Assume that this query returns some number of assets... ////////////////////////////////////////////////////////// AssetCriteria lCriteria = new AssetCriteria(); lCriteria.setNameCriteria("%"); AssetSummary[] lAssetSummaries = repository.assetQuerySummary(authToken, lCriteria); ////////////////////////////////////////////////////////// // Read the users that are subscribed to the first asset ////////////////////////////////////////////////////////// RegistryUser[] lSubscribedUsers = repository.subscriptionReadUsersSubscribedToAsset(authToken, lAssetSummaries[0].getID()); for (int i=0; i<lSubscribedUsers.length; i++){ System.out.println("Subscribed Users: "+lSubscribedUsers[i].getUserName()); } } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
This section provides a use case for the System Settings API that describes how to query for system settings in Oracle Enterprise Repository.
Within the Oracle Enterprise Repository's System Settings section administrators can configure the basic operations and enable/disable specific features. The System Settings API provides a mechanism to query these system settings.
Note:
Users are allowed only to query the system settings for values, the system settings cannot be set or modified through REX.To query the system settings, the following package import(s) are required:
import com.flashline.registry.openapi.entity.SettingValue; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.query.SystemSettingsCriteria;
The systemSettingsAddBundle
method is reserved for future use and is not intended for general use.
Query for system settings in REX.
Example 4-73 Use Case: Query for System Settings
package com.flashline.sample.systemsettingsapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.SettingValue; import com.flashline.registry.openapi.query.SystemSettingsCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class SystemSettings { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1],pArgs[2]); // ////////////////////////////// // Set Application Token on AuthToken object. This is supplied by OER //authToken.setApplicationToken("TokenString"); // ////////////////////////////////////// //Read all available system settings //Create an empty Criteria object. No criteria returns all settings. SystemSettingsCriteria lCriteria = new SystemSettingsCriteria(); lCriteria.setNameCriteria("enterprise.defaults.displayname.field"); SettingValue[] lValues = repository.systemSettingsQuery(authToken, lCriteria); for (int i=0;i<lValues.length;i++) { SettingValue lValue = lValues[i]; System.out.println("Setting Name: " + lValue.getDescriptor().getName()); System.out.println("Setting Value: " + lValue.getValue()); } // ///////////////////////////////////// //Read a specific setting lCriteria.setNameCriteria("cmee.server.companyname"); lValues = repository.systemSettingsQuery(authToken, lCriteria); for (int i=0;i<lValues.length;i++) { SettingValue lValue = lValues[i]; System.out.println("Setting Name: " + lValue.getDescriptor().getName()); System.out.println("Setting Value: " + lValue.getValue()); } // ///////////////////////////////////// //Read a specific section lCriteria.setSectionCriteria("general"); lValues = repository.systemSettingsQuery(authToken, lCriteria); for (int i=0;i<lValues.length;i++) { SettingValue lValue = lValues[i]; System.out.println("Setting Name: " + lValue.getDescriptor().getName()); System.out.println("Setting Value: " + lValue.getValue()); } } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
This section provides a use case for the User API that describes how to create, retrieve, update, and deactivate users or query for users.
The User Subsystem provides a web services-based mechanism that is used to create, read, update, query, and otherwise manipulate Oracle Enterprise Repository User accounts.
For more information, see Section 4.4.15, "Role API".
import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.query.UserCriteria;
Create a new user.
Retrieve an existing user.
Update a user.
Deactivate a user.
Query for users.
Example 4-74 Use Case: Manipulate User
package com.flashline.sample.userapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import java.util.Calendar; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.RegistryUser; import com.flashline.registry.openapi.query.UserCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class Users { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator() .getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]); // ----------------------------------------- // Create a new user String lUserName = "testUserCreate _"+Calendar.getInstance().getTimeInMillis(); String lFirstName = "testUserCreate_FirstName"; String lLastName = "testUserCreate_LastName"; String lEmail = lUserName+"@example.com"; String lPassword = "testUserCreate_Password"; boolean lMustChangePassword = false; boolean lPasswordNeverExpires = false; boolean lAssignDefafultRoles = true; RegistryUser RbacRegistrySecUser = repository.userCreate( authToken, lUserName, lFirstName, lLastName, lEmail, lPassword, lMustChangePassword, lPasswordNeverExpires, lAssignDefafultRoles); // ----------------------------------------- // Read a User long lId = 50000; // user id must exist in OER RegistryUser lUser1 = repository.userRead(authToken, lId); // ----------------------------------------- // Update a User lUser1.setActiveStatus(10); lUser1.setUserName("xxx"); lUser1.setPhoneNumber("412-521-4914"); lUser1.setMustChangePassword(true); lUser1.setPasswordNeverExpires(false); lUser1.setPassword("changed_password"); lUser1.setEmail("newaddress@bea.com"); try { lUser1 = repository.userUpdate(authToken, lUser1); } catch (OpenAPIException e) { e.printStackTrace(); } // ----------------------------------------- // Deactivate a User RegistryUser lUser2 = null; try { lUser2 = repository.userDeactivate(authToken, lId); } catch (OpenAPIException e) { e.printStackTrace(); } // ----------------------------------------- // Query for Users RegistryUser lUsers[] = null; UserCriteria lUserCriteria = null; lUserCriteria = new UserCriteria(); lUserCriteria.setNameCriteria("testname"); lUsers = repository.userQuery(authToken, lUserCriteria); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }
This section provides a use case for the Vendor API that describes how to add or assign vendors in Oracle Enterprise Repository.
Vendors are the original source of assets, and are responsible for their support. Vendors are identified by a single name string.
Validation - When saving a Vendor, Oracle Enterprise Repository currently validates that:
The Vendor name has to be less than 250 characters
The Vendor name is unique
There is a one to many relationship between assets and vendors (for example, multiple assets can be linked to the same vendor, but an asset can only have one vendor). When creating or editing assets the Vendor ID metadata element linking the Vendor to the asset can also be modified.
import com.flashline.registry.openapi.entity.Vendor; import com.flashline.registry.openapi.query.VendorCriteria;
Adding a new Vendor to Oracle Enterprise Repository.
Assigning an existing Vendor to an asset.
Example 4-75 Use Case: Add or Assign Vendors
package com.flashline.sample.vendorapi; import java.net.MalformedURLException; import java.net.URL; import java.rmi.RemoteException; import javax.xml.rpc.ServiceException; import com.flashline.registry.openapi.base.OpenAPIException; import com.flashline.registry.openapi.entity.Asset; import com.flashline.registry.openapi.entity.AuthToken; import com.flashline.registry.openapi.entity.Vendor; import com.flashline.registry.openapi.query.VendorCriteria; import com.flashline.registry.openapi.service.v300.FlashlineRegistry; import com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator; public class Vendors { public static void main(String pArgs[]) throws OpenAPIException, RemoteException, ServiceException { try { /////////////////////////////////////////////////////////// // Connect to Oracle Enterprise Repository /////////////////////////////////////////////////////////// URL lURL = null; lURL = new URL(pArgs[0]); FlashlineRegistry repository = new FlashlineRegistryServiceLocator().getFlashlineRegistry(lURL); // ////////////////////////////// // Authenticate with OER // ////////////////////////////// AuthToken authToken = repository.authTokenCreate(pArgs[1],pArgs[2]); // ----------------------------------------- // Create a new vendor String newVendorName = "My Vendor"; Vendor newVendor = repository.vendorCreate(authToken, newVendorName); System.out.println("The new vendor id =\"" + newVendor.getID() + "\""); // ----------------------------------------- // Find a vendor and update an asset to use it VendorCriteria criteria = new VendorCriteria(); criteria.setNameCriteria(newVendorName); Vendor[] vendors = repository.vendorQuery(authToken, criteria); long myVendorID = vendors[0].getID(); long MY_ASSET_ID = 569; Asset myAsset = repository.assetRead(authToken, MY_ASSET_ID); // MY_ASSET_ID must be the asset id of an asset in the repository myAsset.setVendorID(myVendorID); repository.assetUpdate(authToken, myAsset); // ---------------------------------------- // clean up myAsset.setVendorID(0); repository.vendorDelete(authToken, newVendor.getID()); } catch (OpenAPIException lEx) { System.out.println("ServerCode = " + lEx.getServerErrorCode()); System.out.println("Message = " + lEx.getMessage()); System.out.println("StackTrace:"); lEx.printStackTrace(); } catch (RemoteException lEx) { lEx.printStackTrace(); } catch (ServiceException lEx) { lEx.printStackTrace(); } catch (MalformedURLException lEx) { lEx.printStackTrace(); } } }