Ep130 en Col62 Fv Part a4

EP130 SAP Knowledge Management and Collaboration Development SAP NetWeaver Information Integration

Date Training Center Instructors Education Website

Participant Handbook Course Version: 2006 Q2 Course Duration: 3 Day(s) Material Number: 50082815

An SAP course - use it to learn, reference it for work

Copyright Copyright © 2006 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors.

Trademarks •

Microsoft®, WINDOWS®, NT®, EXCEL®, Word®, PowerPoint® and SQL Server® are registered trademarks of Microsoft Corporation.

•

IBM®, DB2®, OS/2®, DB2/6000®, Parallel Sysplex®, MVS/ESA®, RS/6000®, AIX®, S/390®, AS/400®, OS/390®, and OS/400® are registered trademarks of IBM Corporation.

•

ORACLE® is a registered trademark of ORACLE Corporation.

•

INFORMIX®-OnLine for SAP and INFORMIX® Dynamic ServerTM are registered trademarks of Informix Software Incorporated.

•

UNIX®, X/Open®, OSF/1®, and Motif® are registered trademarks of the Open Group.

•

Citrix®, the Citrix logo, ICA®, Program Neighborhood®, MetaFrame®, WinFrame®, VideoFrame®, MultiWin® and other Citrix product names referenced herein are trademarks of Citrix Systems, Inc.

•

HTML, DHTML, XML, XHTML are trademarks or registered trademarks of W3C®, World Wide Web Consortium, Massachusetts Institute of Technology.

•

JAVA® is a registered trademark of Sun Microsystems, Inc.

•

JAVASCRIPT® is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape.

•

SAP, SAP Logo, R/2, RIVA, R/3, SAP ArchiveLink, SAP Business Workflow, WebFlow, SAP EarlyWatch, BAPI, SAPPHIRE, Management Cockpit, mySAP.com Logo and mySAP.com are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other products mentioned are trademarks or registered trademarks of their respective companies.

Disclaimer THESE MATERIALS ARE PROVIDED BY SAP ON AN "AS IS" BASIS, AND SAP EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES, EXPRESS OR APPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THESE MATERIALS AND THE SERVICE, INFORMATION, TEXT, GRAPHICS, LINKS, OR ANY OTHER MATERIALS AND PRODUCTS CONTAINED HEREIN. IN NO EVENT SHALL SAP BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES OF ANY KIND WHATSOEVER, INCLUDING WITHOUT LIMITATION LOST REVENUES OR LOST PROFITS, WHICH MAY RESULT FROM THE USE OF THESE MATERIALS OR INCLUDED SOFTWARE COMPONENTS.

g2007264334

About This Handbook This handbook is intended to complement the instructor-led presentation of this course, and serve as a source of reference. It is not suitable for self-study.

Typographic Conventions American English is the standard used in this handbook. The following typographic conventions are also used. Type Style

Description

Example text

Words or characters that appear on the screen. These include field names, screen titles, pushbuttons as well as menu names, paths, and options. Also used for cross-references to other documentation both internal (in this documentation) and external (in other locations, such as SAPNet).

2006/Q2

Example text

Emphasized words or phrases in body text, titles of graphics, and tables

EXAMPLE TEXT

Names of elements in the system. These include report names, program names, transaction codes, table names, and individual key words of a programming language, when surrounded by body text, for example SELECT and INCLUDE.

Example text

Screen output. This includes file and directory names and their paths, messages, names of variables and parameters, and passages of the source text of a program.

Example text

Exact user entry. These are words and characters that you enter in the system exactly as they appear in the documentation.

Variable user entry. Pointed brackets indicate that you replace these words and characters with appropriate entries.

© 2006 SAP AG. All rights reserved.

iii

About This Handbook

EP130

Icons in Body Text The following icons are used in this handbook. Icon

Meaning For more information, tips, or background Note or further explanation of previous point Exception or caution Procedures

Indicates that the item is displayed in the instructor's presentation.

iv


2006/Q2

Contents Course Overview ......................................................... vii Course Goals ...........................................................vii Course Objectives .................................................... viii

Unit 1: Overview............................................................ 1 Overview .................................................................2

Unit 2: Getting Started ...................................................11 Getting Started ........................................................ 12

Unit 3: Repository Framework Concepts .......................... 33 Repository Framework Concepts ................................... 34

Unit 4: Repository Filters .............................................. 65 Repository Filters ..................................................... 66

Unit 5: Repository Managers.......................................... 77 Repository Manager Concepts ...................................... 79 Development Tools ................................................... 88 Implementing the Repository Manager ............................ 98 Mandatory Aspects ..................................................103 Mutable Extensions.................................................. 110 Using the Security Checker......................................... 118

Unit 6: KM Services .................................................... 125 KM Services Overview ..............................................126 Reporting..............................................................134 Application Properties Service .....................................144 Publishing Pipeline...................................................149

Unit 7: Flexible UI ....................................................... 159 Architecture ...........................................................160 Components ..........................................................168 Debugging ............................................................189

Unit 8: Search and Classification ................................... 197 Using the Indexmanagement API..................................198 Integrating a Search Engine ........................................210

2006/Q2


v

Contents

EP130

Enhancing the KM Search iView...................................224

Unit 9: Collaboration Room Infrastructure........................ 245 Collaboration Room Infrastructure.................................246

Unit 10: Collaboration Room ......................................... 253 Collaboration Rooms ................................................254

Unit 11: Extensions..................................................... 267 Extensions ............................................................268

Unit 12: Collaboration Services ..................................... 289 Collaboration Services..............................................290

vi


2006/Q2

Course Overview With its knowledge management capabilities, the SAP NetWeaver Portal provides a central, role-specific point of entry to unstructured information from various data sources. This course covers development using the Knowledge Management and Collaboration (KMC) application programming interfaces (APIs). The basic concepts behind using the API, including KMC architecture and the associated tools, are discussed in the first lessons. After that, each of the main functional areas of KMC is covered from a development perspective, with exercises to support the lessons learned.

Target Audience This course is intended for the following audiences: •

Developers with a significant amount of Java development experience who need to understand the tools available for extending and using the KMC API from within custom applications

Course Prerequisites Required Knowledge • • • •

Strong Java development skills Development knowledge of SAP NetWeaver Application Server SAP NetWeaver Portal development experience Familiarity with NetWeaver Developer Studio or Eclipse

Recommended Knowledge •

2006/Q2

Some familiarity with the basic functionality of SAP NetWeaver Knowledge Management and Collaboration


vii

Course Overview

EP130

Course Goals This course will prepare you to: • • • • • • • • • •

Explain the basics of KMC architecture Set up a development environment for development of custom KMC components Use the repository framework to store and retrieve structured and unstructured data Use repository filters to manipulate information for end users Define requirements for custom repository managers in realistic situations Write reports using the knowledge management reporting API Customize the knowledge management user interface using Flex UI Develop custom search components and integrate third-party search engines into the knowledge management search concept Use the collaboration room API for custom development tasks Develop collaboration room extensions and services

Course Objectives After completing this course, you will be able to: • • • • • • • • •

Identify which JAR files are relevant for custom development tasks Correctly use the KMC Wizards delivered as part of NetWeaver Developer Studio Use properties to store structured data Define what property, namespace and content filters are used for Develop a simple repository manager and identify requirements and estimate effort for larger repository manager development projects Define what components are available to you for customization in the Flex UI Debug Flex UI configurations Use the collaboration room API to automate room functions such as creation, deletion and invitation Develop room extensions to integrate backend systems with collaboration rooms

SAP Software Component Information The information in this course pertains to the following SAP Software Components and releases:

viii


2006/Q2

Unit 1 Overview Unit Overview This unit gives a functional overview of the Knowledge Management and Collaboration capabilities of SAP NetWeaver Portal. A basic introduction to the KMC architectural stack is included.

Unit Objectives After completing this unit, you will be able to: • • •

Describe the positioning and functional purpose of Knowledge Management within SAP NetWeaver List the components of Knowledge Management in SAP NetWeaver Explain the basic architecture of Knowledge Management

Unit Contents Lesson: Overview..................................................................2

2006/Q2


1

Unit 1: Overview

EP130

Lesson: Overview Lesson Overview This unit gives a functional overview of the Knowledge Management and Collaboration (KMC) capabilities of SAP NetWeaver Portal. A basic introduction to the architectural stack of KMC is included.

Lesson Objectives After completing this lesson, you will be able to: • • •

Describe the positioning and functional purpose of Knowledge Management within SAP NetWeaver List the components of Knowledge Management in SAP NetWeaver Explain the basic architecture of Knowledge Management

Business Example The concepts discussed in this lesson provide a foundation for the full set of features of Knowledge Management in the SAP NetWeaver Portal. All custom development within KM requires an understanding of these concepts.

SAP NetWeaver Knowledge Management Capabilities With its Knowledge Management capabilities, SAP NetWeaver provides a central, role-specific point of entry to unstructured information from various data sources. This unstructured information can exist in different formats, such as text documents, presentations, or HTML files. Employees in an organization can access information from different sources, such as file servers, their intranet, or the World Wide Web. A generic framework integrates these data sources and provides access to the information contained in them through the portal. The Knowledge Management capabilities support you in structuring information and making it available to the correct target audience. You can use the different functions on all content of integrated data sources, as long as the technical conditions are met. Knowledge Management comprises the following functions.

2


2006/Q2

EP130

Lesson: Overview

Function

Description

Repository integration

Unstructured information is stored in various types of repositories, such as file servers or document management systems. You can use preconfigured repository managers to integrate repositories and make their content accessible through a central entry point in the portal. APIs allow customers and partners to develop repository managers for other storage systems. You can also store documents in one of KM’s own repositories.

Folder navigation

Portal users can navigate in the folders of all integrated repositories and access the documents they contain. Access to folders and documents is controlled using permissions. The user interface for navigating in folders can be configured flexibly and modified to suit various roles. Portal users can personalize the presentation of the user interface. Open interfaces allow you to extend the user interface by integrating your own functions into the standard system.

Search

The search function finds documents in all integrated repositories. The system displays only documents for which the current user has read permission in the results list. You can also include Web site content in your indexes by using Web crawlers. This information is then also available through the search function in your portal.

2006/Q2


3

Unit 1: Overview

EP130

Taxonomies and classification

A taxonomy is a hierarchical structure of categories in which you classify documents according to content, organization, or other criteria. Documents that are stored in different repositories can be included in the same category. Taxonomies allow portal users to navigate in a uniform structure throughout an organization, even if information is stored in heterogeneous storage locations. After initial configuration, the system automatically carries out classification of new and changed documents.

Knowledge Management services

Knowledge Management services are functions that you can use on the content of all connected repositories as long as technical conditions are met. These services include subscriptions, ratings, public reviews, feedback, and personal notes. You can also import documents into KM repositories from external sources by using the content exchange service.

Document creation and publishing

Every portal user can create information in the portal, provided he or she has the necessary permissions. You can upload documents that you created using a PC application directly to a KM folder. You can also use forms to create information directly in the Web browser. The publishing process is supported by various functions, such as the approval workflow. You can assign metadata to documents and other objects to make the knowledge more usable.

4


2006/Q2

EP130

Lesson: Overview

Collaboration

Collaboration provides a set of features that allow users to collaborate on the creation and maintenance of documents within KM. This set of features includes •

•

•

• •

virtual rooms, whose members can access shared data and services independent of their location groupware integration, which allows the integration of e-mail and scheduling services used within a corporation asynchronous collaboration, including online discussions, online management of tasks, sessions, or documents, and online entry of feedback, ratings and comments application sharing and instant messaging the ability to integrate third-party services such as WebEx

The following figure gives a more technical view of how these functional components are implemented. Note: Users access Knowledge Management functionality via the SAP NetWeaver Portal. A successful portal installation is a prerequisite to using Knowledge Management; that is, KM functionality is an extension of portal functionality.

2006/Q2


5

Unit 1: Overview

EP130

Figure 1: Basic Knowledge Management Components

A set of applications built around the unstructured data stored within KM exposes functionality to the KM end user and allows them to collaborate on existing data or to create new data (documents). More basic functionality (building blocks for KM applications) is generally provided by repository or global services. Finally, the repository framework layer is responsible for managing the storage of and access to the data in question, which may be stored in a variety of back-end systems. The following architectural view of the KMC technical stack gives more detail on each of the individual units that comprise KMC.

6


2006/Q2

EP130

Lesson: Overview

Figure 2: Architectural View of KMC

The lowest layer is the repository framework (RF) layer. It offers a framework for various types of extensions. The Knowledge Management (KM) layer uses the repository framework and adds further extensions that implement functions for document management that are visible to the user (for example, repository managers such as the Web repository manager, repository services such as the subscription repository service, and global services such as the attachment service). The next layer, built upon the KM layer, is the Collaboration layer. It contains applications that allow users to collaborate within the portal, chat, share their documents, and so on. Like the KM layer, it brings its own extensions, which implement the collaborative functions into the repository framework, as well as some extensions for the flexible UI (such as the team room renderer). An application on top of the Collaboration layer can use any of the APIs offered by the layers below, either by usage (that is, implementing an application that retrieves all the documents in a given directory) or by extending them (for example, by implementing a repository manager or a flexible UI renderer).

2006/Q2


7

Unit 1: Overview

EP130

Lesson Summary You should now be able to: • Describe the positioning and functional purpose of Knowledge Management within SAP NetWeaver • List the components of Knowledge Management in SAP NetWeaver • Explain the basic architecture of Knowledge Management

8


2006/Q2

EP130

Unit Summary

Unit Summary You should now be able to: • Describe the positioning and functional purpose of Knowledge Management within SAP NetWeaver • List the components of Knowledge Management in SAP NetWeaver • Explain the basic architecture of Knowledge Management

2006/Q2


9

Unit Summary

10

EP130


2006/Q2

Unit 2 Getting Started Unit Overview This unit covers the basics of setting up your development environment. You will need this information if you wish to develop your own custom KMC component or application.

Unit Objectives After completing this unit, you will be able to: • • • • •

Explain the basics of the KMC framework and development environment Set up a KMC development environment for yourself Explain the relationship between portal and KMC projects Create a simple KMC component Deploy KMC components

Unit Contents Lesson: Getting Started......................................................... 12 Procedure: Example: Creating a KM Namespace Filter ............... 20 Exercise 1: KMC Project Setup............................................ 27

2006/Q2


11

Unit 2: Getting Started

EP130

Lesson: Getting Started Lesson Overview In this lesson, we will discuss setting up a development environment for development using the KMC framework.

Lesson Objectives After completing this lesson, you will be able to: • • • • •

Explain the basics of the KMC framework and development environment Set up a KMC development environment for yourself Explain the relationship between portal and KMC projects Create a simple KMC component Deploy KMC components

Business Example Your company has asked you to enhance the behavior of the Knowledge Management features of NetWeaver Portal by allowing corporate end users to only see documents and folders that are assigned to their business unit. You have decided that the best way to implement these requirements is by using a combination of document metadata and namespace filters, which requires custom development in Java. In order to complete these development activities, you need to set up a fully functional development environment.

Software Installation and Basic Setup Custom development of features within KMC will often require Java development. SAP NetWeaver Developer Studio is the development environment supplied by SAP for the purpose of developing custom Java components. NetWeaver Developer Studio is based on the open-source integrated development environment (IDE) Eclipse, and consists of a basic Eclipse installation plus a set of plug-ins or extensions delivered by SAP. These plug-ins support development tasks that are specific to SAP NetWeaver, including a set of plugins for NetWeaver Portal and KMC development, which will be discussed here.

12


2006/Q2

EP130

Lesson: Getting Started

Software Requirements •

•

Install a local Java Development Kit (JDK). Version 1.4.2 is recommended and available from http://java.sun.com/j2se/1.4.2/download.html. Check the Developer Studio Installation Guide (see below) to ensure you install the correct version, as this may change depending on your target platform version. Install a local SAP NetWeaver Developer Studio –

•

You can find this at the SAP Service Marketplace Software Distribution Center: http://service.sap.com/swdc. From the Software Distribution Center home page, select Search for all Categories on the left-hand side, then search for “developer studio”. Choose the appropriate version from the result set. – The installation guide is available under http://service.sap.com/instguidesNW04 → Installation → Installation Guide → SAP NetWeaverDeveloper Studio. You will need a remote or local SAP Enterprise Portal with KMC.

Basic Setup Once you have installed SAP NetWeaver Developer Studio, you will need to set it up for KMC development. The first step is to activate the SAP Enterprise Portal perspective in Developer Studio. Do this by clicking on the icon labeled “EP” in the perspective toolbar. If this is not accessible, you can also choose Open Perspective from the Window menu and then pick the Enterprise Portal option from the list of perspectives, as shown in the screenshot below.

Figure 3: Activate the SAP Enterprise Portal Perspective

2006/Q2


13


EP130

Next, make sure that the appropriate EP and KM icons are visible in the toolbar.

Figure 4: Customize the Toolbar

The buttons in the EP plug-ins menu are used to create a basic SAP NetWeaver Portal project. Creating such a project is a prerequisite for KMC development; the KMC-specific plug-ins require an existing portal project to operate. The buttons on the KM plug-ins toolbar are used to create the actual KMC components. Once the Enterprise Portal perspective is set up correctly, the final step is to search for and copy the KMC development Java archives (JARs) to the local development environment. Caution: Make sure that you always take the relevant library JAR files from your NetWeaver Portal installation and not from your local SAP NetWeaver Developer Studio installation. Also be sure that the JAR files that you compile against in Developer Studio correspond to the server version (for example, SAP NetWeaver 2004, Support Package 19 or SAP NetWeaver 2004s, Support Package 10) that you are developing for. You can find the JAR files by searching for the following file patterns in your portal installation: • • •

14

km*_api.jar (KM application JARs) coll*_api.jar (collaboration/room extension JARs) bc*_api.jar (repository framework JARs)


2006/Q2

EP130


Search for the given patterns under :\usr\sap\\JCXX\j2ee\cluster\server0\apps\sap.com\irj\servlet_jsp\irj\root\WEB-INF\portal\portalapps on a portal installation. Note: This is a Windows path. The path on a UNIX installation will be structured in the same way. Copy these JARs to a single directory on your local PC, even if you are using a local NetWeaver Portal installation.

Portal Project and KMC Component Structures The portal plug-ins are used to create an empty portal application project with: • • •

Source development folders for API and core coding A file system structure for PAR file creation A deployment descriptor file (portalapp.xml)

The KMC plug-ins work on top of the structure of a portal application project. They: • • •

Create source code skeletons for KM components Create configuration entries (XML files) for the configuration framework Create wrapper classes for registration of the developed component with the CrtClassLoaderRegistry. The CrtClassLoaderRegistry is the internal component responsible for registering new components with the internal mechanism for loading classes in order to make them available at runtime.

There are a number of KM components that are supported by NetWeaver Developer Studio KM plug-ins. The KM plug-ins will help you create: • • • • •

2006/Q2

Global services Repository services Filters Scheduler tasks Repository managers


15


EP130

The basic steps required to create any of these KM components are: 1. 2. 3. 4. 5.

Create a new portal application project. Create a new portal application object (KM component). Select the portal application project in which you want to create the KM component . Choose RF Component Wizard to generate a KM component. Specify technical data:

6. 7.

• KM component ID • Java package name • Options used by KM component (optional) Finalize project. Integrate the (relevant) KM JAR files.

Portal Applications • •

•

• •

Portal applications are bundles of portal components and portal services. Portal applications are packaged as PAR (Portal Application ARchive) files – the format accepted by the Portal Runtime for deployment of portal applications. A PAR file is an archive file/standard JAR file (ZIP format) containing a portal application with an XML-based portal application deployment descriptor (DD) called portalapp.xml. A deployment descriptor describes the portal application itself and provides information required at runtime. Portal applications contain two types of resources: –

Web resources • Accessible via HTTP(s) requests to a Web server • All files are not under PORTAL-INF (WEB-INF)

–

Non-Web resources • Not accessible via an HTTP(s) request • All files under PORTAL-INF (WEB-INF)

•

•

16

A Portal application can contain: – Several portal components and several portal services – Only 1-n portal components – Only 1-n portal services Each portal Component can be accessed by .


2006/Q2

EP130


Create a new Portal Application Project by either choosing File → New → Other → Portal Application → Create a Portal Application Project or by using the button available on the toolbar (see figure below).

Figure 5: Creating a New Portal Application Project

Figure 6: Enter Project Name

2006/Q2


17


EP130

Figure 7: Creating a New Portal Application Project (3)

Creating a KMC Component At this point, you have created a portal application project. The next step is to use the wizard to create the basic structure for the type of component that you will be developing. There are several ways to create a KMC project: 1. 2.

From the Developer Studio toolbar. From the context menu of the selected project:

3.

• Right-click on a Developer Studio project. • Select the corresponding wizard. From within the portal application plug-in: • • • • • •

4.

Choose File → New → Other... Select the plug-in portal application. Select Create a new Portal Application Object and then choose Next. Select the portal project Select RF Component Wizard… and then choose Next. Select one of the wizards listed on the left-hand side and then choose Next. Within the repository framework plug-in: • • •

18

Choose New → File → Other.... Select the Repository Framework… plug-in. Select one of the wizards listed on the left-hand side and then choose Next.


2006/Q2

EP130


Referencing KM Libraries You should now add the JARs to the build path of your portal application project. Choose Project → Properties → Java Build Path → Libraries → Add External Jars and then select the JARs that you need to develop your component. You should include only the subset of JARs that you actually need for your project (and not all JARs) to avoid unnecessary overhead. Keep in mind that you may need to revisit this step to either add or remove libraries as you develop your KMC component.

2006/Q2


19


EP130

Example: Creating a KM Namespace Filter 1.

Create a portal application project using the toolbar button on the “EP Plugins” toolbar. Give your project a name. In this example, we will use the name “MyFirstNamespaceFilter”.

Figure 8: Toolbar

2.

Create a portal application object using the portal application object button on the same toolbar. It's next to the portal application project button. When prompted, select your project (“MyFirstNamespaceFilter”) and select “Next”.

3.

Select “RF Component Wizard”. Hit Next.

4.

Select “Repository Filter Wizard”. Hit Next.

5.

Fill in the information required to create the filter. • • • •

•

•

Config Framework Version: NW04 Uncheck “Generate project classpath with BC libraries from plugin” Class Name: this is the name of the Java class that will be generated. In our example, we will use “MyFirstNamespaceFilter”. Package: this is the name of the Java package that will be generated. The class will reside in this package. As an example, we will use “com.mycompany.kmc.filters”. Name: you may leave this blank, or you may choose a name for your filter. If you leave it blank, the class name is used as the name of the filter. This is the name that will be shown to administrators in the KM Configuration UI. Types: we are developing a namespace filter, so pick “Namespace” here

6.

Hit “Finish”

7.

Examine the code that was generated in your project, which now contains the skeleton code for the namespace filter, the classes used to register the deployable component with the portal runtime, and the configuration information for the namespace filter.

Details and Inner Workings of the Project Structure Registering PARs with the CrtClassLoader Registry KMC plug-ins generate a set of classes that are responsible for registering the deployable unit (PAR) with the KMC runtime. These classes implement a portal service. Since there are a variety KMC components that can be deployed, and

20


2006/Q2

EP130


many of them do not require direct user interaction to run (unlike a simple portal iView), this registration process is required to allow the components to function properly. Each deployable unit has a unique key associated with it that identifies the PAR deployable unit to the KMC runtime. To avoid conflicts, modifying this key and making it unique should always be the first step in developing a KMC component . The source code below shows the contents of the class com.sap.netweaver.rf.wrapper.IRFServiceWrapper after running a KMC wizard. The value of the variable KEY is the key that identifies the deployable unit, and must be set to a unique value. The naming convention for this string is to use “.”, where “” is the PAR file name. This is a recommended naming convention, but is not required for KMC component development. You may use any value you wish, as long as it is unique to your deployable unit.

KEY Variable for Deployment package com.sap.netweaver.rf.wrapper; import com.sapportals.portal.prt.service.IService;

public interface IRFServiceWrapper extends IService { public static final String KEY = "/* To be inserted */"; }

Caution: A common mistake is to leave the value of the KEY variable unmodified. This can lead to runtime errors if other components are developed and deployed with an unmodified key. When a PAR containing a KMC component is deployed, it replaces any KMC deployable unit already on the server with the same key value. Registration of the deployable unit is handled by the second generated class in the same package, RFServiceWrapper, which implements the interface shown above. This class contains a call to CrtClassLoaderRegistry.addClassLoader(), which registers the PAR using the key value.

Registration of Classloader with CrtClassLoaderRegistry public class RFServiceWrapper implements IRFServiceWrapper { public void init( IServiceContext serviceContext ) {

2006/Q2


21


EP130

mm_serviceContext = serviceContext; CrtClassLoaderRegistry.addClassLoader( this.getKey(), this.getClass().getClassLoader() ); } }

This code is mandatory for each deployable unit (PAR file). The call to CrtClassLoaderRegistry.addClassLoader() is triggered during either deployment or portal startup because it is in a class registered as a portal service. This registration is in the portalapp.xml file in the dist/PORTAL-INF directory. The following diagram shows the basic entries in the portalapp.xml file that are relevant to KMC development. These entries are all generated after use of the wizards. The SharingReference entry allows the developed portal application to use the portal applications deployed on your portal installation that contain KMC functionality. The services block of XML is responsible for triggering the registration of your deployable unit with the runtime.

Figure 9: Portal Service Configuration: Create / check

Configuration Framework Every KM component implementation needs to be registered as a configurable object in the configuration framework. This allows the repository framework to access the configuration for the KM component (for example, a repository filter) and pass it to the implementation. The KMC wizards output the basic file and folder structure required to handle this registration in the src.config folder.

22


2006/Q2

EP130


The configuration information is split into two sets: 1.

2.

The meta information, or “class definition” describes the property structure to which every instance of the newly developed component will adhere. This is found in the src.config/install/meta/expanded/cm/ folder after the KMC wizard has been run. The files in this folder have the extension .cc.xml. Data or instance information gives concrete values to the properties described in the meta information. Instance information is found in the src.config/install/data/cm/ folder. The files in this folder have the extension .co.xml.

For example, after using the KMC Wizard to create the skeleton for a namespace filter, a class definition for the filter would be located under src.config/install/meta/expanded/cm/repository_filters/com.test.MyNamespaceFilter.cc.xml (this corresponds to a filter created with a name “MyNamespaceFilter” and in a package “com.test”. In addition to this class definition, the KMC Wizard will create an instance definition under src.config/install/data/cm/repository_filters/com.test.MyNamespaceFilter.co.xml. The difference between these two sets of files is much like the difference between a class and an instance of a class in Java. The class definition for a Java class describes the member variables of that class. An instance of a Java class, or object, assigns specific values to those variables. Just as in Java, it is possible to have multiple instances, but not multiple class definitions. The configuration information can be extended by the developer to allow custom configuration of components. Within the class definition, you can specify additional properties using the attribute tag. The configuration information can be changed after deployment using the standard KM configuration iView from within the portal. All deployable units are configured here, but the exact location within the menu tree depends on the type of component being developed. Finally, the configuration information can be accessed from within the developed component at runtime. The method of access will vary slightly depending on what type of KM component is being developed. In our example, the namespace filter is accessed in the startUpImpl() method of the namespace filter manager class.

2006/Q2


23


EP130

Offline Deployment and Deployment Using PAR Export Wizards There are two methods to deploy KMC components you have developed to a NetWeaver Portal installation: 1.

2.

Deploy by placing a generated PAR file into the portal's file system and restart the portal. This is the safest method of deployment. Generated PAR files can be placed under apps\sap.com\irj\servlet_jsp\irj\root\WEB-INF\deployment\pcd on a node's file system. Deploy to a running portal using either the deployment iView in the portal or the PAR Export Wizard in SAP NetWeaver Developer Studio. This is known as “hot deployment” and has associated risks (see SAP Note 894884). Specifically, repeated hot deployments can lead to an OutOfMemoryError on the server. Hot deployments can be done only in development environments (not production environments) at the customer's own risk.

To generate a PAR file needed for either deployment method, use the PAR Export Wizard available from the Portal toolbar in SAP NetWeaver Developer Studio. The toolbar also includes buttons to create a new portal application or portal application object.

Figure 10: Generating a PAR File for Export

After pressing the button and choosing the project for which you want to generate a PAR file, an option screen appears that shows where the PAR file will be output. This screen also allows the deployment of the PAR file to a running portal if the Deploy PAR checkbox is selected.

24


2006/Q2

EP130


If you have not yet set up a portal to which to deploy, you can do so on this screen after selecting the Deploy PAR checkbox by pressing the Configure server settings... button and filling out the information for your portal instance. You can also perform this configuration by choosing Window → Preferences → SAP Enterprise Portal.

Figure 11: Setting Up a Portal Entry for Deployment

Note that for logon, you specify a portal user who has authorization for deployment of PAR files. This can, for example, be a user with the system administrator role. Later, when you deploy files to the portal, you need to enter the password for this user.

2006/Q2


25


26

EP130


2006/Q2

EP130


Exercise 1: KMC Project Setup Exercise Objectives After completing this exercise, you will be able to: • Create new KMC project in SAP NetWeaver Developer Studio • Identify required libraries

Business Example These basic steps are necessary every time you need to implement KM applications or logic based on the KM API.

Task 1: Opening the Enterprise Portal perspective in SAP NetWeaver Developer Studio 1.

Start the SAP NetWeaver Developer Studio.

2.

Open the Enterprise Portal perspective.

Task 2: Create a portal application project 1.

Create a portal application project.

2.

Name the portal application project.

Task 3: Add a NamespaceFilter object 1.

Add a NamespaceFilter object.

Task 4: Check project consistency 1.

2006/Q2

Check project consistency.


27


EP130

Solution 1: KMC Project Setup Task 1: Opening the Enterprise Portal perspective in SAP NetWeaver Developer Studio 1.

Start the SAP NetWeaver Developer Studio. a)

2.

Click the link on your desktop.

Open the Enterprise Portal perspective. a)

Choose Window → Open Perspective → Enterprise Portal.

Task 2: Create a portal application project 1.

Create a portal application project. a)

2.

Choose File → New → Create new Portal Application Project.

Name the portal application project. a)

Enter CollectionNamespaceFilter as Project name and press the Finish button.

Task 3: Add a NamespaceFilter object 1.

Add a NamespaceFilter object. a)

Choose File → New → Create new Portal Application Object.

b)

Select the newly created portal application project, “CollectionNamespaceFilter.”

c)

Choose the RF Component wizard.

d)

Choose the Repository Filter wizard.

e)

Deselect the option Generate project classpath with BC libraries from plugin.

f)

Enter CollectionNamespaceFilter as Class name.

g)

Enter com.sap.training as Package name.

h)

Choose Namespace in the Types selection box and press the Finish button.

Continued on next page

28


2006/Q2

EP130


Task 4: Check project consistency 1.

2006/Q2

Check project consistency. a)

Browse to the src.api folder and check if a class IRFServiceWrapper exists.

b)

Change the static final key variable to “com.sap.training.CollectionNamespaceFilter.”

c)

Goto the portalapps.xml file and set the Startup property in the service config area to .

d)

Save the project.


29


EP130

Lesson Summary You should now be able to: • Explain the basics of the KMC framework and development environment • Set up a KMC development environment for yourself • Explain the relationship between portal and KMC projects • Create a simple KMC component • Deploy KMC components

30


2006/Q2

EP130

Unit Summary

Unit Summary You should now be able to: • Explain the basics of the KMC framework and development environment • Set up a KMC development environment for yourself • Explain the relationship between portal and KMC projects • Create a simple KMC component • Deploy KMC components

2006/Q2


31

Unit Summary

32

EP130


2006/Q2

Unit 3 Repository Framework Concepts Unit Overview This unit discusses the basics of the repository framework. This layer is a central component of the KMC stack of functionality.

Unit Objectives After completing this unit, you will be able to: • • •

Explain the role and function of the repository framework layer within the KM architecture stack List the components that make up the repository framework layer Describe how information is structured in KM

Unit Contents Lesson: Repository Framework Concepts.................................... 34 Exercise 2: Using the Repository Framework API from Within an iView........................................................................... 55

2006/Q2


33

Unit 3: Repository Framework Concepts

EP130

Lesson: Repository Framework Concepts Lesson Overview This unit discusses the repository framework, a central component of the KMC stack of functionality. It outlines the relationship of the repository framework to the other components of KMC. The individual components that make up the repository framework layer are covered in detail, as well as the basics of storing and retrieving content and metadata using the API. We will also discuss the eventing mechanism. Finally, advanced concepts such as locking and ID mapping are briefly outlined.

Lesson Objectives After completing this lesson, you will be able to: • • •

Explain the role and function of the repository framework layer within the KM architecture stack List the components that make up the repository framework layer Describe how information is structured in KM

Business Example Your system administrator has asked you to develop a simple iView that shows all properties (metadata) for a given document (resource) in KM in order to help debug the system. You use the repository framework to access this information in KM and then display it in the iView.

The Repository Framework Layer The repository framework is an extensible framework that offers unified access to objects provided by various information sources.

34


2006/Q2

EP130

Lesson: Repository Framework Concepts

Figure 12: Positioning of the Repository Framework Layer

An information source (or repository) can be a store (for example, a document management system or a file system) that typically stores unstructured data such as text or graphics. It might also be a back-end system (for example, a database or an ERP system) that typically contains structured data, such as data records or business objects. A repository is connected to the repository framework using its repository manager. The repository manager is responsible for converting the repository’s internal representation of the stored information into the unified aspects of the repository framework, and vice versa. Unified access eases application development, because application developers do not need to pay attention to the specifics of interacting with different information sources. For example, a workflow application based on the repository framework will instantly be extended to any other kind of document or business objects as soon as the repository framework is extended with a new repository – without requiring changes to any code in the workflow application. In turn, objects from information sources benefit from the applications on top of the repository framework. For example, when the repository framework is extended with a new repository, all objects exposed to this new repository can instantly be searched using the generic search engine – without the need to re-implement such functionality in the repository itself.

2006/Q2


35


EP130

Figure 13: Review of KM Architectural Layers

In the figure above, the lowest layer is the repository framework layer. It offers an extensible framework for various types of extensions. The Knowledge Management (KM) layer uses the repository framework and adds further extensions that implement the functions for document management that are visible to the user (for example, repository managers such as the Web repository manager, repository services such as the subscription repository service, and global services such as the attachment service). The next layer, built upon the KM layer, is the collaboration layer. It offers applications that allow users to collaborate within the portal, chat, share their documents, and so on. Like the KM layer, it brings its own extensions that implement collaborative functions into the repository framework, as well as some extensions for the flexible UI (such as the team room renderer). An application on top of these layers can use any of the APIs offered by these layers, by usage (that is, implementing an application that retrieves all the documents in a given directory) or by extending them (for example, by implementing a repository manager or an flexible UI renderer).

36


2006/Q2

EP130


Figure 14: Inside the Repository Framework

2006/Q2


37


EP130

The following types of repository framework extensions are distinguished: •

Repository managers handle the mapping between repository framework objects and the back-end system (information source). For example, the File System repository manager maps files and directories of the file system to resources and collections.

•

Repository filters allow the manipulation of repository framework objects as they are passed through the repository framework. For example, the HTML Stylesheet filter applies a CSS to resources with content type text/html.

•

Repository services offer additional unified aspects for the resources of a specific repository. For example the Application Properties service offers additional properties to be stored along with a resource, which an application might use to save additional data for that resource, such as a timestamp that indicates the application-specific lifetime of a resource.

•

Global services offer additional unified aspects for all repository framework resources. For example, the Relation service allows storage and retrieval of relations between resources, which an application might use to save interdependency information about resources, such as “document X is attached to document Y.”

•

Semantic object: represent some special aspects of the resource objects. For example, a resource might be converted into the semantic object “Team Room.”

38


2006/Q2

EP130


Figure 15: Layers That Build on the Repository Framework

KM software components and their interfaces can be grouped into two main layers: • •

The repository framework layer The Knowledge Management application layer

The framework layer provides the fundamental components that enable the integration of repositories, the basic handling of resources, and the construction of applications on top of the framework. In contrast, the application layer provides ready-made components that run on top of the framework. These components are called services and offer useful modules of functionality that can be re-used and modified for different environments. The functionality is exposed by the API, which can be used to implement new variants of the services or to integrate the existing implementation into other applications. The application layer also includes a flexible UI feature. This allows navigation through repositories to be customized. A user accesses items in a repository with a Browse iView.

2006/Q2


39


EP130

Figure 16: Repository Framework Concepts

The Collaboration Room 6.0 framework combines different functional aspects of both the portal and the KM platform into one consistent application. The Rooms API provides an abstraction from this heterogeneous system landscape and therefore offers scenario-oriented access to the functionality of the rooms. Three main parts of SAP Enterprise Portal and KM framework are used to store rooms and room-related information: • • •

40

Portal Content Directory (PCD) User management Repository framework


2006/Q2

EP130


Figure 17: Unified and Semantic Views

The characteristics of the repository framework’s unified objects (called resources and collections) are as follows: •

•

• • • •

2006/Q2

Each resource represents a unified data object within the repository framework, such as a file or directory in the file system or a WebDAV resource). A collection is a special kind of resource that contains other resources (much like a directory contains files or subdirectories in the file system, or like a WebDAV collection resource). Each resource has a unique, hierarchical name (like a file has a file name or like a WebDAV resource has a URI). Each resource may contain unstructured data (content), even though a collection does not usually have content. Each resource may contain structured data (attributes or properties). Each resource may be converted to or from a business object (also called a semantic object in the repository framework).


41


EP130

Figure 18: Resource Identifiers (RIDs)

A Resource Identifier (RID) is something like a hybrid between a relative Unified Resource Identifier (URI), – but without a net_path component – and a file name – but with an URI-like query component. A more formal definition of the RID syntax is: ::= empty | [ ‘?’ ] ::= [ ‘/’ ] ::= any text, not containing ‘/’ and ‘?’ ::= empty | [ ‘&’ ] ::= [ ‘=’ ] ::= any text, not containing ‘=’ and ‘&’ ::= any text, not containing ‘&’

The root resource (denoted by ‘/’) is reserved for the repository framework itself.

42


2006/Q2

EP130


Basic Actions using the Repository Framework API

Figure 19: Class Dependencies in the Repository Framework

IResource represents an repository framework object (resource). ICollection represents a collection and extends IResource. IResource itself extends ITypeCast, which represent a semantic object. The following source code shows how to use the main entry point to the repository framework (IResourceFactory) to retrieve a resource.

// user retrieval not shown, since this is dependent // on context of code IUser user = …;

IResourceFactory factory = ResourceFactory.getInstance(); RID rid = RID.getRID(“/etc”); IResourceContext context = new ResourceContext(user);

IResource resource = factory.getResource(rid, context);

2006/Q2


43


EP130

An instance of IResourceFactory can be retrieved by calling the static method ResourceFactory.getInstance(). The class …util.uri.RID represents an RID. This class offers the static factory method RID.getRID(), which is used to create a RID from a string. IResourceContext represents a resource context. ResourceContext is the repository framework’s implementation of this interface. To create a ResourceContext, a user must be supplied. A resource’s RID and resource context can be retrieved with getRID() and getContext(). A collection is retrieved in the same way. The returned object should be checked to ensure that it is a collection. Following a successful check, it can then simply be typecasted to ICollection. A collection’s children are retrieved with its getChildren() method.

if(resource.isCollection()) { ICollection collection = (ICollection)resource; IResourceList children = collection.getChildren(); }

Figure 20: Basic Actions in the Repository Framework

Resources can only be created in a collection. Resources can be copied to another RID, which duplicates the data of the resource copied in a new resource for the given RID.

44


2006/Q2

EP130


Resources can be deleted. Once a resource is deleted, it is no longer accessible. Renaming a resource only changes its name. It does not change the parent-child relationship; the resource remains in its parent collection. Moving a resource changes the RID of this resource. Moving is like copying the resource to a new resource RID and then deleting the resource with the old RID. A link is just a reference to a real resource: the link target. The following example retrieves the /documents folder and creates an empty resource (without properties or content) called /documents/file.

IResourceFactory factory =

ResourceFactory.getInstance();

IResourceContext context = new ResourceContext(user); ICollection parent = (ICollection)factory.getResource(“/documents”, context); IResource resource = parent.createResource(“file”, null, null);

The following example retrieves the /documents folder and creates an empty collection, /documents/folder, without properties.

IResourceFactory factory =

ResourceFactory.getInstance();

IResourceContext context = new ResourceContext(user);

ICollection parent = (ICollection)factory.getResource(“/documents”, context); ICollection collection =

parent.createCollection(“folder”, null);

The operations for copying, deleting, moving and renaming are available through the IResource interface:

IResource copied = resource.copy(“/documents/copy”, null); IResource moved = copied.move(“/documents/folder”, null);

IResource renamed = moved.rename(“renamed_copy”); renamed.delete();

2006/Q2


45


•

• • •

EP130

copy() expects the destination RID and an optional ICopyParameter. This parameter is a descriptor, which might supply additional parameters (for example, if children should also be copied recursively). delete() deletes the resource, collection, or link itself. When a collection is deleted, all its children will also be deleted. move() expects the same parameters as the copy method. rename() just expects the new name of the resource.

Links are not represented by a dedicated class; the relevant operations are assigned to the IResource interface. Internal and external link types are identified by appropriate enum.LinkType values. Depending on the LinkType, the link’s target is either returned as an URL (for external links) or as an IResource (for internal links). Since methods, which differ only in their return value, may not be overloaded, the appropriate getTargetURL() or getTargetResource() method has to be called.

if(LinkType.EXTERNAL.equals(resource.getLinkType())){ // external link to an URL URL target = resource.getTargetURL(); } else if (LinkType.INTERNAL.equals(resource.getLinkType())) { // internal link to another resource IResource target = resource.getTargetResource(); } else { // not a link }

Setting the content is either done during creation of a resource or by using IResource.updateContent(). IResource.getContent() is used to retrieve the content of a resource .

String out = new String(“my content”);

ByteArrayInputStream data = new ByteArrayInputStream(out.getBytes()); IContent newContent = new Content(data, “text/plain”, data.available()); resource.updateContent(newContent);

// simple content retrieval

46


2006/Q2

EP130


IContent theContent = resource.getContent();

Figure 21: Class Diagram for Metadata Handling

A property’s read-only operations are assigned to IProperty. The corresponding implementation is Property. The write operations are assigned to IMutableProperty, with MutableProperty as corresponding implementation. The name of a property is modeled as IPropertyName, with PropertyName as implementing class. IPropertyName is derived from …util.name.IName, which holds the tuple (two-pair) of (namespace, name). The property’s attributes are modelled as java.util.Properties.

String namespace = “http://sample.com/xmlns/sample”; String name = “property”; IPropertyName propertyName = new PropertyName(namespace, name); IProperty property =

resource.getProperty(propertyName);

if( property != null ) { // property exists String value = property.getValueAsString(); }

2006/Q2


47


EP130

The Eventing Mechanism

Figure 22: Synchronous Eventing in the Repository Framework

The event receiver is called back while a operation is performed for a resource. The event that indicates the operation is sent as a pre- and a post-event. The pre-event is sent before the operation is performed, and the post-event is sent when the operation has been performed successfully. Synchronous event receivers must take performance into account, since the repository blocks any other operation on the resource while the operation (and the processing of the events) is in progress.

Figure 23: Asynchronous Eventing in the Repository Framework

The event receiver is called back from a separate thread that buffers events in an event queue.

48


2006/Q2

EP130


The event receiver might perform lengthy operations when receiving an event for an operation, because the repository is able to finish processing the operation without waiting for the event receiver to return from the call. On the other hand, the event receiver cannot rely on pre-events, because they might be received after the operation has been performed. •

Retrieval

•

– get, getChildren Content and Property

•

– set, setProperty, getProperty, deleteProperty Namespace

•

– createChild, createCollection, createLink, delete, move, copy, rename Locking

•

– lock, unlock Versioning –

checkin, checkout, undocheckout, enableVersioning

Events are sent as pre-events before an operation starts, and as post-events after the operation has been completed. If the operation fails, no post-event is sent. To identify events that belong together (for example, pairs of pre- and post-events), events can provide a correlation ID. As well as its type, which defines the operation causing the event, the event contains the resource to which the operation was applied.

IResourceEventSender sender = … IResourceEventBroker broker =

resource.getRepositoryManager().getEventBroker();

broker.register(sender); broker.send(ResourceEvent.GET ,sender);

An instance of the EventSender class must be registered with a repository's event broker.

public class MyEventReceiver implements IResourceEventReceiver { public MyEventReceiver() { IResourceEventBroker broker = resource.getRepositoryManager().getEventBroker(); broker.register(this, IResourceEvent.RENAME_EVENT , IEventBroker.PRIO_MIN, true); }

2006/Q2


49


EP130

public void received(IEvent event) { if( event instanceof IResourceEvent ) { IResourceEvent resourceEvent = (IResourceEvent)event; IResource resource = resourceEvent.getResource(); ... } }

An application must implement the manager.IResourceEventReceiver interface in order to receive events.

Advanced Concepts TODO: ...

Security To prevent sensitive information being shown to unauthorized users, some kind of security mechanism has to be made available. The concrete implementation of a security mechanism is provided by the repository manager and implements the com.sapportals.wcm.repository.manager.ISecurityManager interface. The security manager is therefore accessed via the repository manager's interface, IRepositoryManager, which in turn can be retrieved from the resource object. The following code sample illustrates the basic retrieval of the security manager as well as a check for read access to a resource.

// rid and context objects have been previously defined IResource theResource = ResourceFactory.getInstance().getResource( rid, context); IRepositoryManager theRM = IReptheResource.getRepositoryManager(); ISecurityManager

theSM = theRM.getSecurityManager();

// this checks to see if the user 'userA' has permission to read the content of the // resource 'theResource' theSM.isAllowed( theResource, userA, theSM.getPermission(IPermission.PERMISSION_READ_CONTENT));

Other permissions that can be checked (and assigned to users) are: resource creation and deletion, directory listing, content, and property retrieval, and content and property write permissions.

50


2006/Q2

EP130


Beyond these basic permission operations, retrieval and manipulation of ACLs of a resource are possible using the IAclSecurityManager interface, which provides access to the IResourceAclManager interface. This interface allows manipulation and retrieval of ACLs of resources, represented as IResourceAcl objects.

if( theSM instanceof IAclSecurityManager ) { IAclSecurityManager theASM = (IAclSecurityManager)theSM; IResourceAclManager theRASM = theASM.getAclManager(); // retrieving an ACL IResourceAcl acl = theRASM.getInheritedAcl(res); // creating a new ACL IResourceAcl iracl = irm.createAcl(resource); }

Note: The IResourceAclManager object provides two methods to access the ACL of a resource: getAcl( IResource ) and getInheritedAcl( IResource ), both of which may return null if no ACL has been assigned to that resource. Additionally, getAcl() only returns the ACL assigned directly to the resource in question, and does not provide access to ACLs that apply to a resource due to inheritance. getInheritedAcl() provides this functionality. Finally, permissions may be assigned to resource / user pairs in the following way.

// get ACLPermission IAclPermission aclperm = irm.getPermission( IAclPermission.ACL_PERMISSION_READ ); // create ACL entry IResourceAclEntry iraclentry = irm.createAclEntry( user, false, aclperm, 1 ); // add ACL entry to ACL iracl.addEntry(iraclentry);

Locking The repository framework offers locks in order to achieve serialization. An application issues a lock request for a resource and user. If there is no other blocking lock (for another user) on this resource, the application can obtain the

2006/Q2


51


EP130

lock. If a blocking lock already exists for the resource (that is, for another user), the request is denied. Furthermore, access of a particular kind (write or read) is only allowed for users who obtain the relevant lock. A simple locking scenario is illustrated by the following code block.

IResource res = ... ; ILockInfo theLockInfo = null; try { theLockInfo = res.lock(); // process locked resource here // ... } finally { if( res.isLocked() ) { res.unlock( theLockInfo ); } }

Note: the lock/unlock operation is protected by a try / finally block to avoid leaving resources in a locked state in case the program flow is interrupted by an exception after the resource has been locked. Not using a try / finally block is a common mistake and will result in resources remaining locked after program execution. A catch block may be added here to handle individual errors, but the finally block is key to avoid this problem. More fine-grained control over the locking of resources can be achieved by using the IResource.lock( ILockProperties ) method. The ILockProperties object allows the specification of parameters that are used by the underlying locking mechanism. For example, the following code sample illustrates how obtain an exclusive write lock on a resource. A timeout of 300 seconds has been given, after which the lock will expire if not released through a call to IResource.unlock().

IResource res = ...; ILockInfo theLockInfo = null; try { ILockProperties theLockProperties = new LockProperties(LockType.WRITE, LockScope.EXCLUSIVE, LockDepth.SHALLOW, 300 ); theLockInfo = res.lock(theLockProperties);

52


2006/Q2

EP130


// process locked resource here // ... } finally { if( res.isLocked() ) { res.unlock( theLockInfo ); } }

Versioning The repository framework layer provides versioning functionality for resources (but not collections). Versioning can be enabled or disabled on a per-collection basis in KM. If a user is working without versioning enabled, then only the current version of a resource exists in the portal. Any changes to the document will overwrite the old version of the document, which can then no longer be retrieved. When versioning is enabled, each version of the document is retained in the system. The user can access the entire version history of a document to display and restore old document versions. At the API level, version information is accessed via three main methods on the IResource interface: • • • •

IResource.isVersioned(), which returns true if a resource has versioning enabled IResource.isRevision(), which returns true if the resource in question is a revision within a version history IResource.getRevisionID(), which returns a revision identifier (String) for the resource IResource.getVersionHistory(), which returns an IVersionHistory object that allows access to the resource's version history.

The following code sample shows how to enable versioning programatically, as well as how to retrieve basic version information and how to create a new version by checking out a resource.

// Enable versioning in root collection root.enableVersioning(true); IResource res = ResourceFactory.getInstance().getResource(new RID("/pre/test.txt“), context); res.getRevisionID(); // Returns 1 // Create a new version of the resource - Check out

2006/Q2


53


EP130

res.checkOut();

The content of the resource can be updated during check-in by passing a new IContent object to the IResource.checkIn() method. Notice also that the RID for a revision of a resource is distinct from the RID of the main resource (or current revision).

Content content = new Content( new ByteArrayInputStream("new content".toBytes()), "text/plain", -1L); res.checkIn(content, null); // Version history IVersionHistory hist = res.getVersionHistory(); hist.size(); // returns 2 hist.getRevision("2").getContent(); // New content hist.getRevision("2").getRID(); // New RID, like this: // /pre/test.txt/~versions~/2.

Hint: The RFExplorer tool is a good way to browse the low-level information available in a repository. Using this tool will also help you understand some of the concepts here. You can find this tool on SDN by searching for “RFExplorer”. Please read the article that explains its installation and use.

54


2006/Q2

EP130


Exercise 2: Using the Repository Framework API from Within an iView Exercise Objectives After completing this exercise, you will be able to: • Perform basic operations on repository objects using the Repository Framework API

Business Example Your system administrator has asked you to develop a set of basic iViews to help debug and maintain the system. You do this by creating a set of iViews that make direct use of the functionality provided by the Repository Framework API.

Task: When approaching new development tasks in KM, it is often helpful to first implement the logic in an iView in order to test subunits of the new component, rather than attempting to create a complete component without testing the individual parts. An example of this might be the creation of a new namespace or content filter (covered in later lessons). Debugging filters can be difficult, since they are faceless components and do not easily allow interaction with a testing user. Setting up some simple iViews allow for this direct interaction.

2006/Q2

1.

Display a directory listing of a directory given as a URL parameter (one iView).

2.

Display all available properties of a resource given as a URL parameter (one iView).

3.

Display the version history of a resource if it has versioning enabled. Show the display name property and version number for each version.

4.

Check to see if a resource is a link. If it is an internal link, check if the link target exists. Also check if the link points to a parent of itself and show a warning if it does.


55


EP130

Solution 2: Using the Repository Framework API from Within an iView Task: When approaching new development tasks in KM, it is often helpful to first implement the logic in an iView in order to test subunits of the new component, rather than attempting to create a complete component without testing the individual parts. An example of this might be the creation of a new namespace or content filter (covered in later lessons). Debugging filters can be difficult, since they are faceless components and do not easily allow interaction with a testing user. Setting up some simple iViews allow for this direct interaction. 1.

Display a directory listing of a directory given as a URL parameter (one iView). a)

public class ShowDirectoryListing extends AbstractPortalComponent { private IPortalComponentResponse response;

public void doContent( IPortalComponentRequest request, IPortalComponentResponse response) { this.response = response; try { IResourceContext ctx = getContext(request); String s = request.getParameter("rid"); if (s == null) { response.write("URL parameter 'rid' is required"); return; }

RID rid = RID.getRID(s); IResource resource = ResourceFactory.getInstance().getResource(rid, ctx); if (resource.isCollection()) { ICollection col = (ICollection) resource;


56


2006/Q2

EP130


for (IResourceListIterator i = col.getChildren().listIterator(); i.hasNext(); ) { IResource r = i.next(); // Show just the display name of the resource - if this is not // set, then the RID name is used (boolean argument to method cal // put HTML < br > in output for new line response.write(r.getDisplayName(true) + "
"); } } else { response.write( "Resource " + rid + " is not a directory. Directory listing not possible."); return; } } catch (Exception e) { reportError(e); } } private void reportError(Exception e) { response.write( "An error occurred processing the request. Technical info: " + e.getClass().getName() + ": " + e.getMessage()); } private IResourceContext getContext(IPortalComponentRequest request) throws UserManagementException { IUser ep5user = WPUMFactory.getUserFactory().getEP5User(request.getUser()); ResourceContext ctx = new ResourceContext(ep5user); return ctx; }


2006/Q2


57


EP130

}


58


2006/Q2

EP130


2.

Display all available properties of a resource given as a URL parameter (one iView). a)

Using the same skeleton and helper methods as the iView above, a method to dump the properties of a resource could be implemented in the following way.

public void showProperties( IPortalComponentRequest request, IPortalComponentResponse response) { this.response = response; try { IResourceContext ctx = getContext(request); String s = request.getParameter("rid"); if (s == null) { response.write("URL parameter 'rid' is required"); return; } RID rid = RID.getRID(s); IResource resource = ResourceFactory.getInstance().getResource(rid, ctx); IPropertyMap map = resource.getProperties();

response.write("
Properties of" + rid + "

"); for( IPropertyIterator i = map.iterator(); i.hasNext() ;

)

{ IProperty p = i.next(); response.write(

p.getPropertyName().toString() + ": ");

response.write( p.getValueAsString() + "
"); } } catch (Exception e) { reportError(e); } }

3.

Display the version history of a resource if it has versioning enabled. Show the display name property and version number for each version. Continued on next page

2006/Q2


59


a)

EP130

Using the same skeleton and helper methods as the iView above, a method to show the version history of a resource could be implemented in the following way.

private void showVersionHistory( IPortalComponentRequest request, IPortalComponentResponse response) { this.response = response; try { IResourceContext ctx = getContext(request); String s = request.getParameter("rid"); if (s == null) { response.write("URL parameter 'rid' is required"); return; }

RID rid = RID.getRID(s); IResource resource = ResourceFactory.getInstance().getResource(rid, ctx); if (resource.isVersioned()) {

IVersionHistory history = resource.getVersionHistory(); for (IResourceListIterator i = history.listIterator(); i.hasNext(); ) { IResource r = i.next(); String name = r.getDisplayName(true); String id = r.getRevisionID(); response.write(name + " " + id + HTML_BR); } } else { response.write("Resource " + rid + " is not versioned."); } } catch (Exception e) { reportError(e);


60


2006/Q2

EP130


}

}

4.

Check to see if a resource is a link. If it is an internal link, check if the link target exists. Also check if the link points to a parent of itself and show a warning if it does. a)

Using the same skeleton and helper methods as the iView above, a method to show link information could be implemented in the following way.

private void checkLinkStatus( IPortalComponentRequest request, IPortalComponentResponse response) { this.response = response; try { IResourceContext ctx = getContext(request); String s = request.getParameter("rid"); if (s == null) { response.write("URL parameter 'rid' is required"); return; } RID rid = RID.getRID(s); IResource resource = ResourceFactory.getInstance().getResource(rid, ctx); if( resource == null ) { response.write("Resource " + rid + " does not exist."); return; } if ( LinkType.NONE.equals( resource.getLinkType() )) { response.write("Resource " + rid + " is not a link." + HTML_BR ); } else if ( LinkType.EXTERNAL.equals( resource.getLinkType() )) { response.write("Resource "


2006/Q2


61


EP130

+ rid + " is an external link." + HTML_BR); } else if ( LinkType.INTERNAL.equals( resource.getLinkType() )) { response.write("Resource " + rid + " is an internal link." + HTML_BR); IResource target = resource.getTargetResource(); if( target != null ) { RID targetRID = target.getRID(); if( targetRID.isAncestorOf( resource.getRID() ) ) { response.write("Link points to ancestor of itself. This is potentially dangerous."); } else { response.write("Link target exists."); } } else { response.write("Target resource of link does not exist."); } } } catch (Exception e) { reportError(e); } }

62


2006/Q2

EP130


Lesson Summary You should now be able to: • Explain the role and function of the repository framework layer within the KM architecture stack • List the components that make up the repository framework layer • Describe how information is structured in KM

2006/Q2


63

Unit Summary

EP130

Unit Summary You should now be able to: • Explain the role and function of the repository framework layer within the KM architecture stack • List the components that make up the repository framework layer • Describe how information is structured in KM

64


2006/Q2

Unit 4 Repository Filters Unit Overview Repository filters play a central role in extending the functionality of KMC. They are flexible and powerful, and understanding them is critical to a well-behaving and well-performing system. This unit covers the basics of the three types of repository filters that are made available via the KMC API.

Unit Objectives After completing this unit, you will be able to: •

Develop new custom filters

Unit Contents Lesson: Repository Filters ...................................................... 66 Exercise 3: Developing a Namespace Filter ............................. 71

2006/Q2


65

Unit 4: Repository Filters

EP130

Lesson: Repository Filters Lesson Overview In this lesson, we will discuss the three basic types of repository filters and their modes of operation. We will also show an example of a namespace filter.

Lesson Objectives After completing this lesson, you will be able to: •

Develop new custom filters

Business Example You have been asked to develop logic in KM that hides all resources that have a name that begin with an underscore (“_”) from all users except users belonging to a certain group. You decide that setting permissions on these resources to hide them isn't appropriate, since everyone should still be able to access the files, and they are in many different locations in the hierarchy. You decide that the best way to do this is to write a simple namespace filter that checks the calling user's group membership and hides these resources as appropriate.

Repository Filters Repository filters are a very powerful tool that can be used to accomplish various types of basic tasks within KM. At the same time, misusing or implementing a filter poorly can have serious consequences on performance and accessibility of information stored in KM. Therefore it is important to thoroughly understand filters before implementing one. Repository filters function in one of two basic modes: read or write. Read filters are triggered during read operations (for example, content retrieval, directory listing, or property retrieval) and change what the end user sees without affecting the content or structure in KM. Write filters are triggered during write operations (for example, saving content or properties of resources) and generally change the content or structure of data in KM when they run.

66


2006/Q2

EP130

Lesson: Repository Filters

In addition to these two modes of operation, there are three basic types of filters in KM: •

Namespace filters –

•

Hide existing resources from the hierarchy; namespace filters function only in read mode Property filters –

•

Hide or modify existing properties of resources, or add virtual properties to resources Content filters –

Modify a resource's content during either content retrieval (reading the content of a resource) or during a save operation

Note that content and property filters function in either read or write mode, but that namespace filters can function only in read mode.

Figure 24: Filter Architecture

Filters are applied sequentially. When a client requests a read operation (this can be content or property retrieval, or a directory listing), the repository framework retrieves the specified resource data from the repository manager. It then retrieves the last filter to apply from the read filter manager by requesting the filter from that manager. The filter logic is then applied by calling the appropriate method on the filter. The filter processes the request by invoking the corresponding method on its predecessor filter. Finally the filtered data is returned to the client.

Filters and Filter Managers After running the filter creation wizard, you have two class skeletons to work with: the main filter class and the filter manager class.

2006/Q2


67


EP130

Figure 25: Filter Invocation: Sequence Diagram

The repository filter manager decides when to apply a filter. When the repository framework requests the filters to be applied from the repository filter manager, it uses getFilterForRead() when a read request's data has to be filtered, and getFilterForWrite() when a write request's data is to be filtered. The filter's predecessor in the filter chain is passed as a parameter to the getFilterFor…() method. The filter manager should then decide (based on the resource returned by the predecessor's filter getResource() method) whether to apply its filter or not. If the filter is to be applied, the filter manager should return its own filter. If the filter should not be applied, it must return the predecessor as passed to the getFilter…() method. The filter manager must not return null. For property and namespace filters, the main processing occurs in the filter() method on the filter class. This method is called by the framework when applying the filter to a certain resource. Because a filter cascade could be applied (filters are invoked in a chain, as discussed above), it is necessary to retrieve the result from the predecessor's filter() method and use this as a basis for further processing. For a namespace filter, the filter() method returns an IResourceList. For a property filter, this method will return an IPropertyMap object. Content filters are slightly different in this regard, since they do not have a filter() method. Instead, the content of the predecessor is manipulated using the getInputStream() method. Additionally, the content length, content type and encoding of the content can also be modified using the appropriate access methods (getContentLength(), getContentType(), getEncoding()).

68


2006/Q2

EP130

Lesson: Repository Filters

Caution: Because filters are called on a per-user-request basis, it's important to implement filters to perform according to strict performance guidelines. Inefficiencies in filters will cause a higher than necessary load on the system. As usual, attaining good performance means paying particular attention to the algorithms and order of operations used.

Example: Namespace filter • • •

Affects the visibility of resources and is applied to collections Implements INamespaceFilter The filter's getCollection() method returns the collection to which the filter is to be applied The filter's filter() method returns the filtered list of child resources for the collection

•

A filter component consists of a filter manager class, which controls the filter itself, and a filter implementation.

Sample coding for a Namespace filter manager public MyNamespaceFilterManager extends AbstractNamespaceFilterManager { public INamespaceFilter getFilterForRead( INamespaceFilter impPreFilter, NamespaceFilterMode mode) throws WcmException{ if (mode.equals(NamespaceFilterMode.GET_CHILDREN) ||mode.equals(NamespaceFilterMode.GET_RESOURCE) ) { return new CollectionFilter(impPreFilter); } return impPreFilter; } ... }

Caution: Like many components in KMC development, repository filters can be difficult to debug, since they are faceless and interaction with them is indirect and triggered through interacting with repositories. For this reason, is it strongly recommended that you use the Logging and Tracing API for basic tracing and debugging tasks as you get started with your filters. For clarity, tracing code is omitted from the code samples in this lesson.

2006/Q2


69


EP130

This sample of a Namespace filter manager shows a manager that returns a custom filter object to the framework when the filter mode is either GET_CHILDREN or GET_RESOURCE. If the mode is not either of these values, the predecessor filter from the filter chain is returned; that is, the custom filter CollectionFilter is skipped.

Sample coding for a Namespace filter public MyNamespaceFilter implements INamespaceFilter { public I

Ep130 en Col62 Fv Part a4

Recommend Documents