cip_11gr1_developing_java_adapter_and_plug_in.pdf

7/30/2019 cip_11gr1_developing_java_adapter_and_plug_in.pdf

1/22

Oracle WebCenter Sites

Developing a Java Adapter and Plug-Infor Content Integration Platform

11gRelease 1 (11.1.1)

February 2012


2/22

OracleWebCenter Sites: Developing a J ava Adapter and Plug-In for Content Integration Platform,11g Release 1 (11.1.1)

Copyright 2012 Oracle and/or its affiliates. All rights reserved.

Primary Author: Tatiana Kolubayev

Contributor: Valentin Vakar, Chandrashekar Avadhani, Suman Saha

This software and related documentation are provided under a license agreement containing restrictions on

use and disclosure and are protected by intellectual property laws. Except as expressly permitted in yourlicense agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify,license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means.Reverse engineering, disassembly, or decompilation of this software, unless required by law forinteroperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. Ifyou find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it onbehalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technicaldata delivered to U.S. Government customers are "commercial computer software" or "commercial technicaldata" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplementalregulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to therestrictions and license terms set forth in the applicable Government contract, and, to the extent applicable

by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, CommercialComputer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City,CA 94065.

This software or hardware is developed for general use in a variety of information management applications.It is not developed or intended for use in any inherently dangerous applications, including applications thatmay create a risk of personal injury. If you use this software or hardware in dangerous applications, then youshall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure itssafe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of thissoftware or hardware in dangerous applications.

Oracle and J ava are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks oftheir respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks areused under license and are trademarks or registered trademarks of SPARC International, Inc. AMD,Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced

Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products,and services from third parties. Oracle Corporation and its affiliates are not responsible for and expresslydisclaim all warranties of any kind with respect to third-party content, products, and services. OracleCorporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to youraccess to or use of third-party content, products, or services.


3/22

3

Oracle WebCenter Sites: Developing a J ava Adapter and Plug-In for Content Integration Platform

Table of

Contents

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Third-Party Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

1 Integrating with Custom Source Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Customizing WebCenter Sites: Content Integration Platform . . . . . . . . . . . . . . . . . . . . . .8

Content Integration Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

2 Creating Adapters and Plug-Ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12I. Creating a Java Source Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

II. Creating a Java Plug-In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

III. Enabling javafacility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Troubleshooting and Debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20


4/22

Table of Contents4



5/22

5


About This Guide

This guide shows developers how to extend Oracle WebCenter Sites: Content IntegrationPlatform to publish from systems of their own choice to Oracle WebCenter Sites.

Applications discussed in this guide are former FatWire products. Naming conventions arethe following:

Oracle WebCenter Sites is the current name of the product previously known asFatWire Content Server. In this guide,Oracle WebCenter Sites is also calledWebCenter Sites.

Oracle WebCenter Sites: Content Integration Platformis the current name of theapplication previously known asFatWire Content Integration Platform. In this guide,Oracle WebCenter Sites: Content Integration Platformis also calledContentIntegration Platform, or CIP.

Content Integration Platform integrates with Oracle WebCenter Sites according tospecifications in theOracle WebCenter Sites 11g Release 1 (11.1.1.x) Certification Matrix.For additional information, see the release notes for Content Integration Platform. Checkthe WebCenter Sites documentation site regularly for updates to theCertification Matrixand release notes.

Audience

Users of this guide must be Java developers with proficiency in the C++programminglanguage.

Related Documents

For more information, see the following documents:

Oracle WebCenter Sites Administrators Guide for Content Integration Platform forFile Systems and Microsoft SharePoint

Oracle WebCenter Sites Administrators Guide for Content Integration Platform forEMC Documentum


6/22

About This Guide6


Conventions

The following text conventions are used in this guide:

Boldfacetype indicates graphical user interface elements that you select.

Italictype indicates book titles, emphasis, or variables for which you supply particularvalues.

Monospace type indicates file names, URLs, sample code, or text that appears on thescreen.

Monospace bol d type indicates a command.

Third-Party Libraries

Oracle WebCenter Sites and its applications include third-party libraries. For additionalinformation, seeOracle WebCenter Sites 11gR1: Third-Party Licenses.


7/22

7


Chapter 1

Integrating with Custom Source Systems

This chapter outlines methods for extending Oracle WebCenter Sites: Content IntegrationPlatform to support content delivery from custom source systems to Oracle WebCenterSites.

This chapter contains the following sections:

Customizing WebCenter Sites: Content Integration Platform

Content Integration Agent


8/22

Chapter 1. Integrating with Custom Source Systems

Customizing WebCenter Sites: Content Integration Platform8


Customizing WebCenter Sites: Content IntegrationPlatform

Content Integration Platform (CIP), by default, delivers content from file systems,Microsoft SharePoint, and EMC Documentum to Oracle WebCenter Sites. Developers canextend Content Integration Platform to publish from a system of their own choice, such asa database or custom content management system, by writing a Java-basedimplementation consisting of a source adapter and plug-in(s), or just the adapter. Both theadapter and the plug-ins are supported by the Content Integration Agent component(Figure1, on page9).

A Java source adapter must be written for each source system whose content will bedelivered to Oracle WebCenter Sites. The adapter queries the source system to retrieve itsmetadata and binary content. (The adapter must be registered with Content IntegrationAgent by means of a statement in thecat al og. xml file.)

A plug-in is required only if items retrieved by the adapter must be processed before they

are published to WebCenter Sites. Processing could include for example, extractingthumbnails from image files or performing a validation step while publishing. Typically,plug-ins are written to support different file formats or to filter selected items from thepublishing process. Any number of plug-ins can be used withanyadapter. Like theadapter, a plug-in must be registered with the Content Integration Agent (in thet ypes. xml file).

Content Integration Agent

Content Integration Agent is written in C++and provides the following components tosupport Java-based custom connectors and plug-ins:

Solid runtime system. Pluggable interfaces, used to implement Java-based source connectors and plug-ins.

XML files namedcat al og. xml andt ypes. xml , both used to register the customsource adapter and plug-ins.

Native source adapter (j avaconnect or library) and native plug-in (j avapl ugi nlibrary). Both are written in C++. They are used to make calls to Java code.

Facilities, which are construction blocks providing some set of functionality to theAgent runtime. Content Integration Agent hosts the Java Virtual Machine in itsprocess space in order to delegate calls from the C++runtime environment to Javacode. The JVM is enabled by registeringj avaf aci l i t y in f aci l i t i es. xml .

Once the Java-based adapter is created and the JVM is enabled, the C++Agent runtime

system can use the JVM to call Java code via the native adapter (similar process for plug-ins). For system architecture, seeFigure1B, onpage9.

Procedures for creating Java-based connectors and plug-ins are given inchapter 2, alongwith instructions for completing the integration. More information about ContentIntegration Agent can be found in the following guides:

Oracle WebCenter Sites Administrators Guide for Content Integration Platform forFile Systems and Microsoft SharePoint

Oracle WebCenter Sites Administrators Guide for Content Integration Platform forEMC Documentum


9/22


Content Integration Agent9


Figure 1: Content Integration Platform

A. Content Integrat ion Agent

B. Source Adapter and Plug-In

j avaconnect or l i brar y

j avapl ugi n l i brar y


10/22


Content Integration Agent10



11/22

11


Chapter 2

Creating Adapters and Plug-Ins

This chapter provides instructions for creating a complete integration solution to supportcontent delivery from any source system to WebCenter Sites.

This chapter contains the following sections:

Overview

I. Creating a Java Source Adapter

II. Creating a Java Plug-In

III. Enabling javafacility

Troubleshooting and Debugging


12/22

Chapter 2. Creating Adapters and Plug-Ins

Overview12


Overview

Creating an adapter and plug-in involves the following steps:

1. Implementing the pluggable interfaces that are provided within Content IntegrationAgent.

2. Registering the implementation(s) with the Content Integration Agent runtime system.

3. Registeringj avaf aci l i t y in order to enable the Java Virtual Machine to delegatecalls from the C++Agent runtime to Java code.

Before a custom adapter (or plug-in) can be successfully used, the data model for the

publishable objects must exist on the WebCenter Sites system and be mapped to theWebCenter Sites system. The following steps are required:

1. Reproduce the objects metadata in WebCenter Sites by creating a dedicated flexfamily (or re-using an existing flex family) to store the object types, their attributes,and the objects themselves.

2. Map object types and attributes to their respective flex family asset instances (createdin the previous step). The map can be created directly in the adapter implementation,or in themappi ngs. xml file.

Note

A custom plug-in can be used withanyadapter. You can implement and deploy asmany plug-ins as necessary.


13/22


I. Creating a J ava Source Adapter13


I. Creating a Java Source Adapter

Publishing from an unsupported source system to WebCenter Sites requires you to create aJava-based source adapter. (A plug-in is not required unless objects retrieved by the

adapter must be processed before they are published.)

To create a Java source adapter

1. Implement the adapter:

Implement the I Connect or , I Provi der Sessi on, I Reposi t ory, and I I t eminterfaces. You can optionally implement theI nput St r eaminterface if items on your

source system have primary binary content.Figure2shows the relationships among the interfaces. The entry point for theadapters code is a factory class: the I Connect or interface implementation.

Figure 2: Adapter and plug-in class diagram

There are different phases in an adapters lifetime. Depending on the phase, differentmethods are invoked.Figure3shows the sequence of calls during each phase.

Note

If you are using a relational database, implement custom views or custom queries inorder for the adapter to work.


14/22




Figure 3: Source adapter calls sequence

Analyzing Figure 3: Source adapter calls sequence

The ID, which is passed to theget Reposi t or yByI Dfunction, is taken from one ofthe corresponding workspace elements in thecat al og. xml file.

Depending on what you pass to theci pcommander , one of the following functions isinvoked:

- If- source_i t emi d is passed, thenget I t emByI D is invoked passing thei t emi d.

- If- source_i t emi d is omitted, and - sour ce_pat h is specified, then theget I t emByPat h function is invoked.

- If neither - source_i t emi d or - sour ce_pat h is specified, then thegetTopFol der function is invoked. (In this case, the entire repository ispublished.)

Note: DC metadata is Dublin Core metadata(ht t p: / / en. wi ki pedi a. org/ wi ki / Dubl i n_Cor e)


15/22




To ensure uniqueness, maintain a differentver si oni d, i t emi d, andpat h for allitems inside the same repository, and keep the names different for all items inside thesame folder. Thepat h must be in the form: / .

2. Register the adapter:

a. Register theI Connect or interface implementation with Content IntegrationAgent by adding a connect or element tocat al og. xml (located ini nt egr at i on_agent / conf / ):

j avaconnect or

connect or _cl ass_ name

connect or - speci f i c_ par amet er s

b.Enable publishing by adding a new provi der element tocat al og. xml :

pr ovi der - speci f i c _par amet er s

Parameter Description

connect or_i d Any unique identifier.

connect or_descr i pt i ve_name Any descriptive name (does not have to beunique).

connect or_cl ass_name Name of the I Connect or implementationcreated.

connect or- speci f i c_parameters Set of parameters that will be passed toI Connect or . i ni t i al i ze during the call.


provi der_i d Any unique identifier.

provi der_descr i pt i ve_name Any descriptive name (doesnt have to be

unique).connect or_i d Adapters unique identifier.

provi der- speci f i c_par ameters Set of parameters that will be passed toI Connect or . l ogi n during the call.


16/22


II. Creating a J ava Plug-In16


c. Deploy the adapter:

Place the adaptersj ar files into the folder / j ava// l i b, and thecl ass files into/ j ava// cl asses.

Thefolder is located within Content Integration Agent.

On Windows: is

On Unix: is

3. If you require a Java plug-in (to process items retrieved by the adapter), continue tosection II. Creating a Java Plug-In. Otherwise, enablej avaf aci l i t y (to allow the

Java Virtual Machine to delegate calls to Java code from the C++Agent runtime). Forinstructions, seeIII. Enabling javafacility, on page19.

II. Creating a Java Plug-In

A plug-in is not required unless objects retrieved by the adapter must be processed beforethey are published to the WebCenter Sites system. The main purpose of a plug-in is tomodify the metadata of retrieved items, add metadata to retrieved items, and reject items.

Creating a plug-in is similar to creating a adapter. The steps are as follows:

To create a Java plug-in

1. Implement the plug-in by implementing theI Asset Handl er interface (in ContentIntegration Agent).

The entry point for a plug-in is theI Asset Handl er interface.

This is the only interface which is directly used by the runtimesystem. In most casesExt r actMetadata is the only methodyou need to implement.Figure4shows the calls sequence in aplug-ins lifetime.

Note

Adapter classes are loaded by different class loaders to prevent collisionswith different implementations and loading/unloading features. We stronglyadvise placing all adapterj ar andcl ass files into the folder, instead of including them into theCLASSPATHenvironment variable,or thej ava. cl ass. pat h property, or thej r e/ l i b/ ext folder.

Note

A custom plug-in can be used withanyadapter. You can create and deploy asmany plug-ins as necessary.


17/22




Figure 4: Plug-in calls sequence

2. Register the plug-in with Content Integration Agent.

a. Add a new plug-in handl er element to thet ypes. xml file (located in thei nt egr at i on_agent / conf / folder):

j avapl ugi n

pl ugi n- speci f i c_ par amet er s

b. If you are using Content Interation Platform for EMC Documentum, complete this

step. Otherwise, skip tostepc on page18.Enable the handler for the selected handler sets. Which handler set to use isspecified during the publication initiation process. Each handler set contains thelist of handlers, which are invoked during the metadata extraction phase in theContent Integration Agent. Handlers are matched by either MIME type or assettype.

MIME type has the following form: / (i mage/ j peg, for example). There is an option to use '* ' for MIME types. It can


handl er _i d Custom plug-ins unique identifier.

pl ugi n- speci f i cparamet er s

Plugin-specific parameters that are passed when theplug-in is initialized.

C++Native Code IAssetHandler

ExtractMetadataMetadata replication phase

ctor

initialize

connectConnection phase

disconnectDisconnection phase


18/22




be applied either to themi nor part or the whole MIME type. For example, */ *matches all assets, whilet ext/ * matches only text files.

When using the I Connect or Cont ext . guessMI METype function, it will lookintomi met ypes. xml to get the corresponding MIME type for the supplied file

extension. For example the call with "t xt " parameter will produce the "text/pl ai n" result.

Asset types also support the '* ' notation, which matches all asset types.

If more then one handler matches a specific item, then both are invoked in thesame sequence in which they are registered within the handler set used. If any ofthe matching handlers returns the null object from theI I t em. ext r acMet adat acall, then the item is discarded from future processing and not sent to the targetadapter.

c. Enable the custom plug-in for selected object types by adding asset - t ypeelements to thet ypes. xml file. Items for which this plug-in is invoked will befiltered according to MIME type.

ext

d. Deploy the plug-in:

Note

Theasset - t ype element in the context of a plug-in is a MIME typegroup.


MI ME t ype MIME type of the item for which this plug-in will beinvoked. MI MEt ype must be of the form, e.g., t ext / pl ai n.

A wild-card symbol (*) can also be used. For example:

To enable the plug-in for all text files, specify:t ext/ *

To enable the plug-in for all items, specify:*/ *

ext File extension, e.g., . txt for text files. The fileextension does not directly affect the plug-in selectionprocess. However, it is used to guess the MIME typefor those systems where MIME type is not directlyavailable (e.g., file system).

handl er _i d Custom plug-ins unique identifier (specified in thehandl er element, in the previous step).


19/22


III. Enabling javafacility19


Place the plug-insj ar files into the folder / j ava/ /l i b, and thecl ass files into/ j ava/ / cl asses.

Thefolder is located within Content Integration Agent.

On Windows:is

On Unix:is

3. If you created a custom adapter but have not enabledj avaf aci l i t y, continue to thenext section, III. Enabling javafacility.

III. Enabling javafacility

Calling Java code from C++Agent runtime requires a special facility namedj ava to beregistered in f aci l i t i es. xml .

To enable javafacility

1. Verify that f aci l i t i es. xml is not commented (f aci l i t i es. xml is located in thei nt egr at i on_agent / conf / folder).

2. Add the following lines:

j ava

J ava_VM_ar gument

VM_l i br ar y_pat h

Note

Plug-in classes are loaded by different class loaders to prevent collisionswith different implementations and loading/unloading features. We stronglyadvise placing all plug-inj ar andcl ass files into thefolder, instead of including them into theCLASSPATHenvironment variable,or thej ava. cl ass. pat h property, or thej r e/ l i b/ ext folder.


par am_i d Parameters unique id (any unique value). In order to passmultiple arguments to the JVM, construct multiple

parameters with differentpar am_i ds.J ava_VM_argument Java VM argument to be passed to the Java VM created

within the Agent runtime process.

Example:- Xmx256m


20/22


Troubleshooting and Debugging20


Troubleshooting and Debugging

When developing custom components for CIP, it is often helpful to see more than just thedefault logging messages displayed in the production environment. CIP Agent supports

five different logging levels: f at al

error

war ni ng

i nf o

debug

Use the instructions below to debug custom components in CIP.

Escalating the logging level in CIP Agent

CIP is set toerror by default. To increase the logging level, CIP Agent must run as aconsole executable:

1. Stop the CIP Agent system service.

2. Run theci pagent - t debug command.

Debugging Java custom components

To debug custom Java implementations hosted within the Agent runtime, enableremote debugging in CIP Agent. For example, to start the remote debugger on port

7007 and suspend CIP Agent to wait until a debugger attaches, add the following linestoj avaf aci l i t y:

- Xdebug

- Xr unj dwp: t r anspor t =dt _socket ,addr ess=7007, ser ver =y, suspend=y

Escalating the logging level for Sites Agent Services

To get more data about an error in the Sites Agent Services application, set theDEBUGlevel in thecommons- l oggi ng. pr oper t i es file for thecom. f at wi r e. l oggi ng. csagentser vi ces category. We also recommend setting

VM_l i brary_path Full path to the Java VM library (DLL or shared library)within the JRE/J DK installation.

For example, for Sun JDK on Windows,VM_l i brary_pathis either:

%J AVA_HOME%\ j r e\ bi n\ ser ver \ j vm. dl l

- or -

%J AVA_HOME%\ j r e\ bi n\ cl i ent \ j vm. dl l

Note

Do not use the settings shown below on a production system, as they can slow

down the systems performance.



21/22




theDEBUGlogging level in thecommons- l oggi ng. pr oper t i es file for thecom. f at wi r e. l oggi ng. cs. db category.


22/22



Date post:	14-Apr-2018
Category:	Documents
Upload:	onidojo
View:	212 times
Download:	0 times