eTrust Directory

Developer Guide
r8.1

Second Edition
This documentation (the “Documentation”) and related computer software program (the “Software”) (hereinafter
collectively referred to as the “Product”) is for the end user’s informational purposes only and is subject to change
or withdrawal by CA at any time.

This Product may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part,
without the prior written consent of CA. This Product is proprietary information of CA and protected by the
copyright laws of the United States and international treaties.

Notwithstanding the foregoing, licensed users may print a reasonable number of copies of the Documentation for
their own internal use, and may make one copy of the Software as reasonably required for back-up and disaster
recovery purposes, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only
authorized employees, consultants, or agents of the user who are bound by the provisions of the license for the
Software are permitted to have access to such copies.

The right to print copies of the Documentation and to make a copy of the Software is limited to the period during
which the license for the Product remains in full force and effect. Should the license terminate for any reason, it
shall be the user’s responsibility to certify in writing to CA that all copies and partial copies of the Product have
been returned to CA or destroyed.

EXCEPT AS OTHERWISE STATED IN THE APPLICABLE LICENSE AGREEMENT, TO THE EXTENT PERMITTED BY
APPLICABLE LAW, CA PROVIDES THIS PRODUCT “AS IS” WITHOUT WARRANTY OF ANY KIND, INCLUDING
WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR ANY
LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS PRODUCT, INCLUDING WITHOUT LIMITATION,
LOST PROFITS, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED OF
SUCH LOSS OR DAMAGE.

The use of this Product and any product referenced in the Documentation is governed by the end user’s applicable
license agreement.

The manufacturer of this Product is CA.

This Product is provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government
is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS
Section 252.227-7013(c)(1)(ii), as applicable, or their successors.

All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

Copyright © 2005 CA. All rights reserved.

Contents

Chapter 1: Introduction 1
Documentation ..................................................................................................................... 1
Formatting Conventions ......................................................................................................... 3
CA Product References........................................................................................................... 3

Chapter 2: Customizing JXplorer 5

About JXplorer...................................................................................................................... 5
Customize Tree Icons ............................................................................................................ 7
Create HTML Viewing Templates.............................................................................................. 9
Customize HTML Forms........................................................................................................ 12
Add Custom HTML Pages...................................................................................................... 17
Internationalize JXplorer ...................................................................................................... 18
Supply Customized Files....................................................................................................... 22

Chapter 3: Extending JXplorer 25

Pluggable Attribute Editors ................................................................................................... 25
Pluggable Entry Editors ........................................................................................................ 35
Plug-ins with Data Listeners.................................................................................................. 39
Plug-ins with Threads .......................................................................................................... 43
Localize JXplorer Plug-ins ..................................................................................................... 48
Add Help Files to Plug-ins ..................................................................................................... 49

Chapter 4: The DUA Command Set 51

What Is the DUA? ............................................................................................................... 51
Connecting and Disconnecting............................................................................................... 52
Inquire Services.................................................................................................................. 55
Update Services.................................................................................................................. 62
Common Arguments............................................................................................................ 69
Aliases .............................................................................................................................. 74

Chapter 5: The UDDI Server 77

Configuring the UDDI Server ................................................................................................ 77
Comparing the eTrust Directory UDDI Server with the UDDI Specifications .................................. 79

Contents iii
Chapter 1: Introduction
This guide describes how to extend some components of eTrust Directory.

eTrust Directory offers a number of APIs and other extension mechanisms for
programmers who want to customize eTrust Directory applications and
functions for their specific needs.

This section contains the following topics:

Documentation (see page 1)

Formatting Conventions (see page 3)
CA Product References (see page 3)
Contact Customer Support (see page 3)

Documentation
eTrust Directory comes with documentation to help you get the most out of it.

Use this section to find out which documents are designed to help you in which
circumstances.

Release Information

The following release information comes with eTrust Directory:

Readme

The Readme lists the supported platforms and system requirements,

known issues, and any last-minute notices. Use the Readme to find out if
any known issues affect areas of eTrust Directory that you plan to use.

Release Notes

The Release Notes list the issues that have been fixed in this release, with
the associated STAR or LabTrack numbers. Use the Release Notes to track
when the issues you are interested in are fixed.

Release Summary (a PDF guide)

The eTrust Directory Release Summary briefly describes new features and
enhancement sin this release. Use this guide to find out what's new. You
can then find out more in the eTrust Directory Administrator Guide.

Introduction 1
Documentation

PDF Guides

The following PDF guides come with eTrust Directory:

Administrator Guide

The eTrust Directory Administrator Guide is a PDF guide that includes

detailed descriptions of how eTrust Directory works, and how to use it. Use
this guide if you need to understand a feature or learn how to use it.

Reference Guide

The eTrust Directory Reference Guide is a PDF guide that includes lists of
commands, settings, files, and so on. This guide is useful if you already
understand a feature and just need to be reminded.

Getting Started

The eTrust Directory Getting Started is a PDF guide that includes a brief
description of how to install eTrust Directory, and some short tutorials on
how to use some of the components. This guide is useful for getting to
know eTrust Directory.

User Guide

The eTrust Directory User Guide gives instructions for implementing some
of the features described in the eTrust Directory Administrator Guide.

Developer Guide

The eTrust Directory Developer Guide describes how to extend eTrust

Directory. It describes how to customize JXplorer, how to use the DUA
commands for batch operations, and how to extend the UDDI Server.

Online Help

The following online help comes with eTrust Directory clients:

JXplorer online help

The JXplorer online help describes how to use JXplorer. Use the online help
when you want to know how to do a task. Use the eTrust Directory
Administrator Guide to find out how JXplorer works.

JXweb online help

The JXweb online help describes how to use JXweb. Use the online help
when you want to know how to do a task. Use the eTrust Directory
Administrator Guide to find out how JXweb works.

2 Developer Guide
 Formatting Conventions

Formatting Conventions
In this guide, commands are shown in a different font from the main text, as
in this example:

get dynamic-group;

If a command includes a variable that you must replace, that variable appears
in italic text. In this example, you must replace the text assoc-number with
the actual association number:

abort user assoc-number;

If you must enter only one of a list of options, the options are shown
separated by the pipe character |. In this example, you should choose either
true or false:

set access-controls = true | false;

CA Product References
This document references the following Computer Associates International,
Inc. (CA) products:

eTrust® Embedded IAM (eIAM)

eTrust® Single Sign-On (eTrust SSO)

Ingres

Contact Customer Support

For online technical assistance and a complete list of locations, primary service
hours, and telephone numbers, contact Customer Support at
[Link]

Introduction 3
Chapter 2: Customizing JXplorer
This section contains the following topics:

About JXplorer (see page 5)

Customize Tree Icons (see page 7)
Create HTML Viewing Templates (see page 9)
Customize HTML Forms (see page 12)
Add Custom HTML Pages (see page 17)
Internationalize JXplorer (see page 18)
Supply Customized Files (see page 22)

About JXplorer
JXplorer is an open source Java application that allows you to browse and
search any LDAP directory.

It displays the structure of the directory data as a tree view in the left panel,
and the data of any particular entry in the directory in the right hand pane.

JXplorer includes a number of directory-related utility functions, such as

secure SSL connectivity, LDIF file reading and writing, graphical cut, copy,
paste, and delete, and the Unicode international character set.

JXplorer has advanced security integration and support for the more difficult
and obscure parts of the LDAP and DSML protocols.

Customizing JXplorer 5
About JXplorer

Requirements and Supported Platforms

JXplorer has been tested and run on Windows, Solaris, Linux, OS390, and
Macintosh OSX.

Because JXplorer is a Java client, it can also be run on any platform that
supports Java. This is up to developers to test for themselves.

JXplorer uses Java 1.4.2. To check what version you are running, go to a
command prompt and type:

java -version

Supported Specifications

JXplorer supports the following LDAP specifications:

RFC 2251: Core LDAP description

RFC 2252: Attribute syntax

RFC 2253: UTF-8 distinguished names

RFC 2254: Search Filters

RFC 2255: LDAP URLs

RFC 2256: Default LDAP user schema

RFC 2849: LDIF file format

JXplorer also supports the DSML 2.0 specification: Directory Services Markup
Language v2.0.

Why Customize the JXplorer Interface?

You do not have to customize JXplorer if you do not want to. JXplorer already
works with any LDAP directory.

You can already use JXplorer to modify the structure of your directory with the
tree view (cut/copy/paste/delete of entries and sub-trees), and you can edit
individual entry attribute values using the table editor.

However, you might want to customize JXplorer:

To change the JXplorer interface

To change the way JXplorer behaves, to provide more advanced

functionality.

6 Developer Guide
 Customize Tree Icons

Customize Tree Icons

You can add or modify the icons that JXplorer displays in the tree in the left
pane.

A small set of icons is included in the standard release.

The icons displayed in the JXplorer tree are stored in the icons sub-directory.

The browser reads the icons used in the directory display tree from the /icons
subdirectory of the JXplorer home directory. The icons are 16-pixel-square
images in the form:

object_class_name.gif

You can easily replace the icons.

Customizing JXplorer 7
Customize Tree Icons

Add a Custom Icon

To make sure the browser recognizes the new icons, you must restart it.

To add a new icon

1. Create a 16 x 16 pixel GIF file of the icon.

2. Give the icon the same name as the naming attribute you want the icon to
appear next to.
For example, you could create an icon named [Link], which would appear
next to entries that use cn as their naming attribute.

3. Save the GIF file in the jxplorer\icons directory

The next time you start JXplorer, the new icon will be used.

Display Entry-Specific Icons

The icons are linked with entries using the object class of the entry, or the
LDAP naming attribute in the lowest RDN of the entry.

For example, this means that an entry with a name

ou=R&D,o=acmecorp,c=us will be labeled with the icon
[Link], or if that doesn't exist, with [Link]. The
[Link] icon is shown as a gray org tree symbol in the tree
above.

8 Developer Guide
 Create HTML Viewing Templates

Create HTML Viewing Templates

You can create HTML templates and place them in a file directory hierarchy
under the /templates subdirectory of the JXplorer root directory. When a
shared template directory exists on the file system, you can configure JXplorer
to use that directory instead by editing the [Link] configuration file in the
JXplorer directory.

Place templates in file directories corresponding to object class names. Within

these file directories, the templates can have any name (although names that
include spaces are not recommended). Templates placed directly in the
/templates directory are common to all object classes. For example, the
following file directory structure provides a general template, two templates
for person, and a default template for organizationalUnit:
/templates/

[Link]

/templates/person

[Link]

[Link]

/templates/organizationalUnit

[Link]

You can add any number of new HTML templates, including templates for
newly defined object classes by creating (if necessary) the appropriate
subdirectory under the /templates directory and placing the new HTML files in
that subdirectory. After you add new files, you may need to restart the
browser to recognize them.

HTML Tag Extensions

The HTML language is extended using a modification to the HTML <comment>

tag to set placeholders where attribute values can be filled in.

These extension tags:

Position individual attribute names and values in the page

List of all attribute names and values to be set with a single tag

Provide a variety of tabulated formatting options, such as HTML tables and

lists

See the JXplorer online help for more information.

Customizing JXplorer 9
Create HTML Viewing Templates

HTML Forms

You can also use standard HTML forms; however, you must give each form
element a name value that corresponds to an attribute, for example, title.
JXplorer will display existing values and make updates to the directory when
you click Submit.

Important! JXplorer submits the changes to the directory, not to a Web

server.

A number of example HTML forms are in the templates sub-directory. For

more information, see Customize HTML Forms (see page 12).

Example: Customized JXplorer GUIs

There are a number of reasons you might want to change the GUI, including:

Corporate Branding - providing a distinct look and feel for a client or a

product.

Simpler Interface - providing tools to do commonly used activities quickly.

Providing Extended Help - you may want to provide more information to

the user.

Data Specific Display - you may want special icons for some types of data,
or special displays for specific entry types.

10 Developer Guide
 Create HTML Viewing Templates

Corporate Branding Example

The following example shows JXplorer with custom icons (see page 7) and
corporate-specific graphics. These graphics were incorporated using a simple
extended version (see page 17) of HTML

Customizing JXplorer 11
Customize HTML Forms

Data Entry Example

If you were using JXplorer in a help desk or data entry environment, it is

straight-forward to build custom HTML forms that only allow data entry for a
handful of attributes, and possibly restrict the allowed values, or provide more
on screen help information.

Customize HTML Forms

You can use HTML forms to enter data into the directory. Unlike the HTML
page display, you do not need any custom tags at all; it is possible to use plain
HTML forms.

The Java HTML component does not support any active scripting. It works with
plain HTML only.

It is quite legitimate to combine the special DXAttribute tag of the previous

chapter with these custom forms.

Be careful not to include extra fields containing attributes that don't exist in
the directory. If you do this, and a user attempts to enter data into the field,
the directory will show an 'unknown attribute' error. This is not particularly
serious, but it will confuse your users.

Form elements that have a 'value=""' clause will (where possible) have this
value filled in by the existing entry value. This is not done for non-text
components however.

12 Developer Guide
 Customize HTML Forms

Example: Customized HTML

Showing the value of description:

<dxtemplate:get-attribute name="description"/>

Showing all addresses in an HTML list:

<dxtemplate:get-attribute name="address" style="list"/>

Showing all attribute values in a table:

<dxtemplate:get-all-attributes style="table"/>

Listing all available data in the entry, without needing to explicitly name the
various attributes:

Customizing JXplorer 13
Customize HTML Forms

Sample Templates

The above page for viewing 'person' data was saved under /templates/person/
. Look at the existing subdirectories under templates to see some examples.

If you have a template that you want to be available for all entries, regardless
of object class, place it at the base 'templates' subdirectory level, and it will
always appear as an option.

Name the Buttons

Anything with a 'name' tag is parsed as an attribute. This means that form
submission buttons and so on will be treated as attributes if they are given
names.

To avoid this, don't give your Submit buttons specific names, unless you have
a special reason to do this.

While you shouldn't give buttons a 'name' clause, you can certainly give them
a 'value' clause, to get the button to display something other than 'submit'.

Name the Form Elements

The form elements must be named after the attribute they are to modify. For
example, to modify a description attribute, you could use the following form
HTML

<input type="text" name="description" size=20 value="">

This gives a normal text input field that modifies the description attribute
when the user clicks the Submit button.

14 Developer Guide
 Customize HTML Forms

Example Customized HTML Forms

Any form component can be used, although the data returned may not always
be appropriate for a particular attribute type.

Example: organizationUnit HTML Form

The organizationUnit example HTML file shows how to use the description field
above as well as a pull-down list:

You must use the normal HTML form syntax, including a submission URL.
However, the form does not get submitted to that URL - JXplorer intercepts
the submission event and parses the data itself.

Customizing JXplorer 15
Customize HTML Forms

Example: Script to Create HTML Form

The following code is the script used to generate the directory-enabled HTML
form shown above. It is a complete HTML page, including both an attribute tag
and a form.

<html>
<head><title>First Template</title></head>
<body bgcolor="#DDFFDD">
<h1>Organisational Unit Data Set</h1>
<h2><dxtemplate:get-attribute name="ou" style="list"/></h2>
<p>
<h1> Please Update Entry </h1>
<table width=200 border=3 bgcolor="#DDDDFF">
<tr>
<td>
<form name="temp" action="[Link] method=get>
<h3>Description</h3>
<input type="text" name="description" size=20 value="">
<h3>Business Category</h3>
<select name="businessCategory">
<option value="Quality Assurance">Quality Assurance
<option value="Documentation">Documentation
<option value="Marketing">Marketing
<option value="Software Development">Software
Development</select>
<p>
<input type="submit">
</form>
</td>
</tr>
</table>
</body>
</html>

16 Developer Guide
 Add Custom HTML Pages

Add Custom HTML Pages

JXplorer loads HTML pages into the HTML view panel based on the object
class(s) of the entry being viewed. For example, when viewing a 'person'
entry, it looks for a 'person' subdirectory under the 'templates' subdirectory,
and lists all the available html files within that person subdirectory as options
to the user.

Within these HTML files, an 'extended' HTML tag is used to allow the display of
entry data. Within the HTML code, the following tag may be used:

<dxtemplate:get-attribute name="[attribute name]" style="[display type]"/>.

[Attribute name] is the exact name of the attribute to display values of. The
optional

[display type] is one of either 'list', 'table', or 'plain', which sets how multiple
values will be displayed. To show a list of all available attributes. To display all
the attributes and their values a similar tag is used:

<dxtemplate:get-all-attributes style="[display type]"/>

You can insert hyperlinks in your HTML pages. For example, you could link to
extended help, or further resources.

However, that the Java HTML component does not support Javascript or VB
script, and is not as robust as a commercial web browser.

Customizing JXplorer 17
Internationalize JXplorer

Internationalize JXplorer
It is easy to add new languages to JXplorer. You can choose what parts of
JXplorer you internationalize.

You can internationalize the following:

The HTML templates

This means that the text strings on each JXplorer page appears in the new
language.

The Welcome page

The online help

Translate HTML Templates

To internationalize an HTML template

1. Create the new templates in UTF8, 16 bit UNICODE, or a local encoding

(such as Shift-JIS in Japan).
UTF8 is preferable, because local encodings won't work outside computers
set to that locale.

2. If you want to check your work in an English-language browser, make sure

you use the correct HTML meta header. For example:

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

18 Developer Guide
 Internationalize JXplorer

Translate Help Files

The online help system for JXplorer uses the JavaHelp 1.1.3 format. The online
help is supplied as a helpset.

To internationalize the JXplorer online help

1. Create an new version of the help in a different language.

2. Give the root '[Link]' file a country-specific name of 'JXplorerHelp_[my

language].hs'. For example, the Chinese helpset would be named
JXplorerHelp_ch.hs.

3. Allow JXplorer to see the translated helpset. You can do either of the
following:

Make a ZIP file of the translated helpset, then place it in the /plugins
directory.

Add it to the JXplorer class path.

For information about the JavaHelp format, see

[Link]
([Link]

For information about internationalizing JavaHelp, see the JavaHelp User

Guide. Look in the Localizing Help Information section.

Translate the Welcome Page

You can internationalize the Welcome page that appears when JXplorer starts.

To do this, replace the /htmldocs/[Link] file with language specific files of

the form 'start_[language code].html'.For example, for Japanese, this file
would be start_ja.html.

Make sure that these new files are written in UTF8, Unicode, or the default
local encoding.

Customizing JXplorer 19
Internationalize JXplorer

Files Used in Translation

JXplorer is written using English strings. It then uses resource files to map the
English strings to the translated strings. These resource files are located in the
/language subdirectory.

Each resource file is made up of lines of words and phrases. Each line has a
word or phrase on the left, an equals sign, and the translation on the right. For
example, a map file for German might contain the following two lines:

Help = Hilfe
Welcome to JXplorer = Wilkommen du JXplorer

Any symbol on the left of the equals sign (including another equals sign) may
be escaped with a backslash, but for most strings this is not necessary.

Use the Template Map File

JXplorer comes with a template translation file named [Link]. This

file provides a list of strings on the left side, with the translations on the right
side remaining blank.

To use this template file

1. Fill in the translated strings on the right side of each line.

2. Save the file in UTF8 format if possible.

You can also use 16-bit Unicode, local character encoding, or Java Unicode
escape format.

3. Name the file according to the following format: JX[_country

abbreviation][_dialect].properties.
For example, a Japanese translation file should be named
/language/JX_ja.properties, where ja is the standard two letter internet
code for Japanese.
In another example, a French Canadian translation file should be named
/language/JX_fr_CA.

4. Place the file in the /language directory.

20 Developer Guide
 Internationalize JXplorer

Test Your Translation

To test your translation file

1. Back up the existing files in the /languages directory.

2. Add the translated strings to the translation files.

3. Run JXplorer

If you are on an English platform and you made changes to the right side
translations in the file [Link], you will see those changes the next
time JXplorer runs.

If you are in a non-English locale, copy the [Link] file to a JX_[my

language].properties file, and start making changes there. These changes
will be visible the next time you run JXplorer.

For more information, see the Sun documentation on Java resource bundles
([Link]

File Formats

Many products have very restrictive rules about what file formats they will
accept non-English text in. JXplorer prefers files to use UTF-8 or 16 bit
unicode, but local character encodings (such as Japanese 'Shift-JIS' or Chinese
'Big-5') will usually work as well.

If your file might be used outside your locale, or if you need to include multiple
languages, you should use Unicode (either UTF-8 or 16 bit). This is because
locale-specific formats will only work on computers that are set to that locale.
That is, 'Shift-JIS' only works on computers that are set to the Japanese
region setting.

Unicode is used internally throughout JXplorer.

Occasionally you may see text of the form '...\u30AF\u309A...'. This is Java-
escaped Unicode format. You can use this format, but most word processors
will not save to this format, and it is not recommended.

Fonts

While many fonts may exist on a system, Java does not automatically pick
them up.

If you need to install new fonts, use this Sun document for instructions:
[Link]
([Link]

Customizing JXplorer 21
Supply Customized Files

Supply Customized Files

Depending on how much customization you've done, you may have new icon
files, HTML forms, HTML templates, and images.

If you are writing your own Java plug-in, and you need to use external data
files, you can access them using normal java zip handling methods. In addition
a utility class '/com/cai/od/cbutil/[Link]' is available (see the API
documentation) and can be imported by your plug-in.

To supply the changed files in a ZIP file:

1. Put the changed files in a ZIP file.

2. Send the ZIP file to the end users.

3. Ask the users to place the ZIP file in the plugins directory.

JXplorer automatically scans the plug-ins directory for .zip and .jar files when
JXplorer is started. It reads the indexes of the zip files, and afterwards treats
any HTML templates, icons, and plug-ins in a ZIP file as being part of the
normal class path.

Automatic loading of tree icons and plug-ins is available in JXplorer 1.2.

Automatic loading of HTML templates from ZIP files is available in JXplorer 1.3.

Supply the Changed Files Directly

If you have customized only a small number of files, you can send your end
users the files directly, with instructions or a batch file to place them in the
correct directory.

Supply the Changed Files in a ZIP File

1. If you have a large number of files, you may need to make changes to the
/icons and /plugins directory, and create new subdirectories in the
/templates directory. To supply the changed files in a ZIP file:

2. Put the changed files in a ZIP file.

3. Send the ZIP file to the end users.

4. Ask the users to place the ZIP file in the plugins directory.

JXplorer automatically scans the plugins directory for .zip and .jar files when
JXplorer is started. It reads the indexes of the zip files, and afterwards treats
any HTML templates, icons, and plugins in a ZIP file as being part of the
normal class path.

22 Developer Guide
 Supply Customized Files

Structure of the ZIP File

If you use a ZIP file to supply the changed files to your users, the ZIP file must
have the same structure as the external directories.

That is, templates must be in the ZIP file under a /templates directory, icons
under a /icons directory, and so on. For example:

Customizing JXplorer 23
Chapter 3: Extending JXplorer
JXplorer can be extended to load small Java programs, similar to Web applets,
based on an entry's object class.

This section contains the following topics:

Pluggable Attribute Editors (see page 25)

Pluggable Entry Editors (see page 35)
Plug-ins with Data Listeners (see page 39)
Plug-ins with Threads (see page 43)
Localize JXplorer Plug-ins (see page 48)
Add Help Files to Plug-ins (see page 49)

Pluggable Attribute Editors

LDAP is primarily a string handling protocol and many attribute values are
simple text strings. However, it is often necessary to load other types of data,
for example, certificates and images.

eTrust Directory can be used to store many types of non-string data types,
including graphics formats, audio formats, cryptography formats, and
application-specific data types.

JXplorer allows you to load binary files to some attributes, such as

userPKCS12.

The general-purpose JXplorer cannot be used to modify binary data, but you
can create your own binary editor for a particular data type.

The browser also supports custom binary editors (written in Java using a
provided minimal API) that dynamically loads at run time. You key such binary
editor extensions to a particular object class. This would let you write, for
example, an editor for a custom certificate object class.

These editors will only work for binary value data attributes and no other data
types.

Standard editors are provided for X.509 certificates, and a number of standard
image and audio formats.

Extending JXplorer 25
Pluggable Attribute Editors

Ways to Edit Binary Attributes

To create a pluggable attribute editor takes time, and you may not need to do
it. JXplorer comes with two binary editors, or you can use a Windows editor.

Using a Windows Editor

You can choose to use a Windows editor instead of creating a pluggable

attribute editor. To do this, save the file, then edit it, then load it again.

However, if you do this, your application may not be able to run on a non-
Windows platform. A possible path out of this is to check the operating system
in the pluggable attribute editor, and issue an appropriate native command
depending on the OS.

Using the File Launching Feature

To modify binary data, you can use the default binary editor to save the data
to disk, use your normal tool to manipulate the data, and load it back into the
default binary editor.

The binary editor is very limited. JXplorer lets you edit the attributes in the
odMultimedia schema, which lets you save and launch files of the following
formats:

Format Attribute Type

.avi odMovieAVI

.doc odDocumentDOC

.mid odMusicMID

.wav odSoundWAV

.xls odSpreadSheetXLS

26 Developer Guide
 Pluggable Attribute Editors

To use the attribute types in odMultimedia in the Table Editor, add the
odMultimedia object class to an entry.

You can then add binary files to that entry, and launch those files from the
Table Editor view of the entry.

For more information, see Launch Binary Files in the JXplorer online help.

Foreign Languages Do Not Require a Pluggable Editor

You don't need to write a pluggable editor to use different languages with
JXplorer.

JXplorer has been successfully tested with European and Asian languages on
correctly installed localized platforms.

Java's normal string handling of Unicode automatically translates between the

locale-specific character encoding and the Unicode format used internally in
the browser. The Unicode is read from and written to the directory in a
transformation format called UTF-8, but this is invisible to the user.

For information about internationalizing JXplorer, see Internationalize JXplorer

(see page 18).

Extending JXplorer 27
Pluggable Attribute Editors

Writing a Pluggable Attribute Editor

Writing a pluggable editor simply involves writing a Java class that does one of
the following:

Implements the [Link]

interface

Extends the [Link] class

The class must be given the name of the attribute type, in lower case, with the
suffix editor.

For example, if you create an editor for the attribute ocspRSAPrivateKey, you
must name the final class ocsprsaprivatekeyeditor.

Extending the abstractbinaryeditor class

The abstractbinaryeditor interface has only one method: public void

setValue(editablebinary editMe). This passes an editablebinary object, which is
a data object used to store a byte array. The editablebinary object has two
methods, public byte getValue() and public void setValue(bytebytes), used
respectively to read and write to the object.

When an attribute value of the appropriate type is found by JXplorer, and a

user wishes to edit it (by clicking on the value cell in the editor pane) JXplorer
will run the pluggable editor, passing the byte array to it using the setValue
method of abstractbinaryeditor. That Editor can then manipulate the object as
it wishes (usually by creating a GUI and allowing the user to edit the data in
some way). As long as the editablebinary object is updated with the final
value, when the user click the Submit button in JXplorer, the new value is
entered into the directory.

Extending DefaultBinaryEditor

The class defaultbinaryeditor is a default implementation of

abstractbinaryeditor using a swing JFileChooser. For some purposes it may be
easier to extend it, rather than implement a GUI from scratch and using
abstractbinaryeditor directly.

28 Developer Guide
 Pluggable Attribute Editors

Example: Handling Masked Binary Password Data

The following is an example of a pluggable editor that could be used to handle

masked, binary password data. Almost all of this code is simply setting up the
GUI.

/**
* All pluggable editors must be in this package
*/
package [Link];

import [Link].*; // custom version of JPanel

import [Link];

import [Link].*;
import [Link].*;
import [Link].*;
import [Link].*;

/**
* Password Editor.
* Allows user to enter a masked binary password. The dialog contains two
* password fields. The first is for displaying the password that is stored in
* the directory. The second is to confirm that the first has been entered
* correctly. To change the password the user needs to click on the change
* button. Both password fields are then cleared (we don't want the user to edit
* the encoded password). When the user clicks the save button a check is done.
* If the user hasn't changed the password, it gets stored. Otherwise if the user
* did change it, the two password fields must match before it is saved (a
* warning message is displayed if they don't match).
*

Extending JXplorer 29
Pluggable Attribute Editors

*/
public class userpasswordeditor extends JDialog
implements abstractbinaryeditor
{
protected JPasswordField oldPwd, newPwd;
protected CBButton btnOK, btnCancel, btnHelp;
protected EditableBinary editMe = null;
protected CBPanel display;
protected JLabel oldLabel, newLabel;
protected boolean firstClick = true;

/**
* Constructor - sets up the gui.
*/

public userpasswordeditor(Frame owner)

{
super(owner);

setModal(true);
setTitle([Link]("User Password"));

display = new CBPanel();

oldPwd = new JPasswordField();

[Link](new MouseListener()
{
public void mouseClicked(MouseEvent e) { }
public void mouseEntered(MouseEvent e) { }
public void mouseExited(MouseEvent e) { }
public void mouseReleased(MouseEvent e) { }
public void mousePressed(MouseEvent e)
{
if (firstClick)
{
[Link]("");
firstClick = false;
}
}
});

newPwd = new JPasswordField();

oldLabel = new JLabel([Link]("Enter Password:"));

newLabel = new JLabel([Link]("Re-enter Password:"));

btnOK = new CBButton([Link]("OK"), [Link]("Click here to

save the changes (remember to click Submit in the table editor)."));
[Link](new ActionListener()

30 Developer Guide
 Pluggable Attribute Editors

{
public void actionPerformed(ActionEvent e)
{
load();
}
});

btnCancel = new CBButton([Link]("Cancel"), [Link]("Click

here to exit."));
[Link](new ActionListener()
{
public void actionPerformed(ActionEvent e)
{
quit();
}
});

btnHelp = new CBButton([Link]("Help"), [Link]("Click here

for Help."));
[Link](btnHelp, "[Link]");

[Link]();
[Link](oldLabel);
[Link](oldPwd);
[Link](new JLabel(" "));
[Link](newLabel);
[Link](newPwd);
[Link]();

JPanel buttonPanel = new JPanel();

[Link](btnOK);
[Link](btnCancel);
[Link](btnHelp);
[Link](buttonPanel);
[Link](JComponent.WHEN_IN_FOCUSED_WINDOW).put([Link]
("ENTER"), "enter");

[Link](JComponent.WHEN_IN_FOCUSED_WINDOW).put([Link]
("ESCAPE"), "escape");
[Link]().put("enter", new MyAction([Link]));
[Link]().put("escape", new MyAction([Link]));

setSize(300, 170);
[Link](this, owner); //Centres the window.
setTitle([Link]("User Password Data"));
getContentPane().add(display);
}

Extending JXplorer 31
Pluggable Attribute Editors

/**
* Apparently it is better to use key bindings rather than adding a
* KeyListener... "for reacting in a special way to particular keys, you
* usually should use key bindings instead of a key listener".
* This class lets the user set the key as an int. If a key is pressed and
* it matches the assigned int, a check is done for if it is an escape or
* enter key.
* (27 or 10). If escape, the quit method is called. If enter, the apply
* method is called.
* Bug 4646.
*/
private class MyAction extends CBAction
{
/**
* Calls super constructor.
* @param key
*/
public MyAction(int key)
{
super(key);
}

/**
* quit is called if the Esc key pressed,
* load is called if Enter key is pressed.
* @param e never used.
*/
public void actionPerformed(ActionEvent e)
{
if (getKey() == ESCAPE)
quit();
else if (getKey() == ENTER)
load();
}
}

32 Developer Guide
 Pluggable Attribute Editors

/**
* This is the abstractbinaryeditor interface method which is
* called when the user wants to edit the password
*/
public void setValue(editablebinary editMe)
{
[Link] = editMe;
[Link](stringEncode([Link]()));
}

/**
* converts between text and a byte array
*/
protected byte[] stringDecode(String s)
{
if (s == null)
return (new byte[0]);
else
try
{
return [Link]("UTF-8");
}
catch (UnsupportedEncodingException e)
{
[Link]("Unexpected error encoding password " + e);
[Link]();
return new byte[0];
}
}

/**
* converts between a byte array and text
*/
protected String stringEncode(byte[] b)
{
if (b == null || [Link] == 0)
return new String();
else
try
{
return new String(b, "UTF-8");
}
catch (UnsupportedEncodingException e)
{
[Link]("Unexpected error decoding password " + e);
[Link]();
return new String(b);
}
}

Extending JXplorer 33
Pluggable Attribute Editors

/**
* sets the value of the editablebinary object with whatever the
* user has entered into the password text field.
*/
protected void load()
{
if (passwordConfirm())
{
[Link](stringDecode(new String([Link]())));
quit();
}
}

/**
* Does some checks on the password.
* @return True - if the two password fields match.
* False - if the new password field is empty (an error message is
* displayed).
* False - if the password fields don't match (an error message is
* displayed).
*/
protected boolean passwordConfirm()
{
if (new String([Link]()).equals(new
String([Link]()))) //if the two password fields match carry on
saving the password.
{
return true;
}
else if (new String([Link]()).equals("")) //if the new
password field is empty display error message.
{
[Link](display, [Link]("Empty password
field, please fill in both fields"), [Link]("Warning message"),
JOptionPane.INFORMATION_MESSAGE);
[Link]("");
return false;
}
else //if the password fields don't match display error message.
{
[Link](display, [Link]("Password typed
incorrectly, please try again"), [Link]("Warning message"),
JOptionPane.INFORMATION_MESSAGE);
[Link]("");
return false;
}
}

34 Developer Guide
 Pluggable Entry Editors

/**
* Shuts down the gui.
*/
protected void quit()
{
setVisible(false);
dispose();
}
}

Pluggable Entry Editors

Pluggable entry editors are similar to pluggable attribute editors, except that
they are triggered on an entire entry, rather than just an attribute of an entry.
They take up the entire right-hand editing pane, and can suppress the normal
HTML and table display if desired, giving a 'custom application' look.

There may be no need to write a pluggable editor. If all you need to do is give
a custom look-and-feel to your data, you may find it easier to use the HTML
templates and forms. But, if you need to do any complex client-side
processing such as wizards or form validation, it may be useful to write your
own editors.

Editor Names and Locations

The name of the editor must be the same as the object class of the type of
entry it is to be used for. So if the editor is to be used for 'people', the name of
the class is simply '[Link]'.

Entry editors must be completely in lower case, and there is no suffix.

The classes made need to be packaged into the [Link] file in the
directory C:\Program Files\CA\eTrust Directory\jxplorer\jars and they need to
be added into the [Link] file with the correct path:
com\ca\directory\jxplorer\viewer.

For example, if the [Link] file is created it needs to be packaged and

have the path name: com\ca\directory\jxplorer\viewer\[Link]

Extending JXplorer 35
Pluggable Entry Editors

The PluggableEditor Interface

The Pluggable Editor interface defines a number of methods that let the
Pluggable Editor take control of the entirety of JXplorer. Most of the time you
will only want to use a handful of these. For more information, see the
JXplorer API Reference (../jxplorer/api/[Link]) that was installed with
JXplorer.

The DataSink Interface

The DataSink interface is used internally in JXplorer for transferring data to

data consumers. Since the Pluggable Editor class does this, a pluggable editor
must also implement the DataSink interface (which has only two methods).

36 Developer Guide
 Pluggable Entry Editors

Extending BasicPluggableEditor

Most editor writers will probably simply extend BasicPluggableEditor, which

has default implementations of all the required methods. The class
BasicPluggableEditor simply displays the entry passed to it as text in a JPanel.
The following shows a trivial extension of BasicPluggableEditor (which in fact
does exactly the same thing - simply displays the entry in a text pane).

package [Link];
import [Link].*;
import [Link].*;
import [Link].*;
import [Link].*;
import [Link];
import [Link];
import [Link];

public class person extends BasicPluggableEditor

{
JEditorPane basicDisplay;
JScrollPane scrollPane;

/**
* The Constructor sets up the JEditorPane GUI
*/
public person()
{
basicDisplay = new JEditorPane("text/plain","");
scrollPane = new JScrollPane(basicDisplay);
}

/**
* This method is called by JXplorer when a new 'person' entry
* needs to be displayed.
*/
public void displayEntry(DXEntry entry, DataSource ds)
{
[Link]([Link]());
}

/**
* This method returns a GUI component to JXplorer to display
* in the right hand pane.
*/
public JComponent getDisplayComponent()
{
return scrollPane;
}
}

Extending JXplorer 37
Pluggable Entry Editors

This results in the following editor pane:

This is all that is required for your own pluggable editor - a GUI and some
code to handle the 'displayEntry(..)' method. Check the API for the methods of
the DXEntry object - it is an extension of the standard JNDI 'Attributes' object
and supports all its methods, as well as a large number of utility extension
methods (such as the [Link]() method).

Sending Changes to the Directory

When your user has registered changes in your custom pluggable editor GUI,
you'll need to submit them to the directory. The core pluggable editor method
is public void displayEntry(DXEntry entry, DataSource ds). The entry
parameter is the data to display, while the DataSource parameter is a link to a
data source (usually a directory) that you can use to submit changes. The
simplest call in DataSource is modifyEntry(..), which takes the original entry
and the new entry, and makes the necessary calls to the directory to
efficiently convert the old entry to its new state.

There are a large number of other data related operations you might want to
make with the directory, ranging from reading more data, searching,
modifying the directory tree structure, and reading schema details.

DataSource is actually the front end to a queued, multi-threaded directory

connection. As a pluggable Editor writer you shouldn't normally need to worry
about that; it just means that your GUI won't freeze up when you make a
directory request! However if you need to know the result of a directory
operation you'll need to know about the data event model. When a directory
operation is completed (successfully or otherwise) your editor can find out by
registering itself as a 'DataListener' (this metaphor will be familiar to Java
programmers who have worked with GUI listeners). The details of doing this
are covered in the Plug-ins with Data Listeners (see page 39) section.

38 Developer Guide
 Plug-ins with Data Listeners

Plug-ins with Data Listeners

Directory operations occur over networks, which can be slow, and may require
processing on a busy directory server, which may also be slow. If your
application is waiting on the results of a directory operation, it can 'freeze up'.
The GUI doesn't respond to mouse clicks, or may not repaint properly. The
user will assume the program has crashed, and may kill it manually. The worst
that can occur is when the directory server crashes or your network dies, and
the browser freezes until the connection times out.

The JXplorer Threading Model

Fortunately it is relatively easy to make a Java application multi-threaded, so,

as an editor writer, it would not be much work to put your directory code in a
different thread. However this isn't necessary using JXplorer's pluggable
editors, since JX is already multi-threaded. In fact, pluggable editors written
using the techniques of the last chapter are already multi-threaded, and will
not hang.

Problems arise when you need to write code that is conditional on the results
of a directory operation. For example, you may want to create a particular
entry if it doesn't exist, or modify it if it does. The way to do this in a
pluggable entry editor is to either use the 'DataListener' interface (for simple
operations), or to pass an extended 'DataQuery' object (for more complex
tasks).

This section shows you how to use the simpler DataListener interface, and the
Plug-ins with Threads (see page 43) section how to use the general purpose
'DataQuery' method to run arbitrary code.

Extending JXplorer 39
Plug-ins with Data Listeners

Using the DataListener Interface

The displayEntry() method of DataSink contains the entry to display, and a

'DataSource'. The DataSource can be used to carry out various directory
operations, such as getEntry() or copyTree(). However, since these operations
occur in another thread, rather than returning data or a success code
immediately, they return a 'DataQuery' object.

The DataQuery object is used to communicate with the connection thread. If

you need to know what happens to the operation (and you may not - for
example the results of a 'copyTree()' operation, or any errors, will be displayed
by the browser without any intervention) you can use the DataQuery object.
This is done by registering a 'DataListener' with the DataQuery object, in the
same way as an 'ActionListener' might be registered with a button. When the
DataQuery has completed (either successfully, or with an error) your
DataListener will be called with the result.

The DataListener only has one method returning one object - the original
DataQuery! However in this method you are guaranteed that the DataQuery
has finished, and is ready for reading. So within the DataListener method you
can use all the DataQuery methods such as hasException() or getResult().

This may seem a bit of effort to go to, but is in fact fairly straightforward.

Important! Attempting to read the DataQuery object immediately can be very

dangerous - in the best possible case it will block the current thread until the
data is ready, in the worst case it will attempt to block the thread making the
directory connection and will throw an exception in order to avoid thread
'deadlock'.

The following code snippet (using an anonymous inner class) is a quick

example of how to use a DataListener:

40 Developer Guide
 Plug-ins with Data Listeners

public class MyPluggableEditor extends BasicPluggableEditor

{
...
...

public void displayEntry(DXEntry entry, DataSource myDataSource)

{
...
...
DataQuery readQuery = [Link](
new DN("cn=fred,ou=R&amp;D,o=CA"));
...
__
[Link](new DataListener()
{
public void dataReady(DataQuery query)
{
if ([Link]())
{
[Link]("couldn't read entry " +
[Link]()+"\nexception= "+[Link]());
__ // prevent the browser also displaying the error.</font>
__ [Link]();

}
else
{
[Link]("read entry " + [Link]());
}
}
});
__ ...
}
...
}

Other DataListeners

Your pluggable editor isn't the only Data Listener. The JXplorer browser tree is
another, and it will respond to any data operations that occur, showing error
messages or changing the tree as appropriate.

Most of the time this is what you want. However, if you'd prefer to keep your
operations private (maybe you're handling your own exceptions, or you're
hiding a sub-level of the directory from the user) you can 'squelch()' the
query, preventing any other listeners from processing the query.

Extending JXplorer 41
Plug-ins with Data Listeners

Complex Directory Interactions

Sometimes this still isn't enough - you need to make a directory request in
your pluggable editor, and then, depending on the result, you need to make
further requests.

There are a number of ways of doing this. One method is to use the
getBroker() DataQuery method. This gives you raw access to the directory
connection methods.

This method falls down if the initial directory action is non-standard, and may
also be a little clumsy if you have a single unit of work to do, that could be
nicely executed in one place. In this case, the best thing to do may be to
extend the DataQuery class itself, and pass an 'extended DataQuery' to the
DataSource, using DataSource's 'extendedRequest()' method. How to do this
is covered in the Plug-ins with Threads (see page 43) section.

42 Developer Guide
 Plug-ins with Threads

Plug-ins with Threads

If you have a complex piece of directory logic to execute, the preceding
methods may be a bit clumsy. For example, consider the following action:
"check if this entry exists, if it doesn't exist, create the following sub-tree,
otherwise, check that all these components exist, and if they don't exist,
create them, and finally copy the whole tree into a backup branch directory".

This could be done using the previous technique by doing the first query (an
existence check) and then putting the rest of the code in the DataListener,
while using the DataQueries 'getBroker()' method.

Bundling Complex Directory Code

Instead, you can bundle all the code up in one place, and use an 'extended
data query'. The method is simply to extend the DataQuery class by
implementing the 'doExtendedRequest()' method, and then pass the resulting
query to the connection thread using the broker's 'extendedQuery()' method.

Extending JXplorer 43
Plug-ins with Threads

Example: Reading an Entry and Printing It Out

The code in the Plug-ins with Data Listeners (see page 39) section, which read
an entry and printed it out, could be rewritten as:

public class MyPluggableEditor extends BasicPluggableEditor

{
...
...
public void displayEntry(DXEntry entry, DataSource myDataSource)
{
...
...
[Link](new DataQuery
{
public void doExtendedRequest(Broker myBroker)
{
DXEntry myEntry = [Link](
new DN("cn=fred,ou=R&amp;D,o=CA"));
if ([Link]() != null)
{
[Link]("couldn't read entry " + [Link]() +
"\nexception was: " + [Link]());
}
else
{
[Link]("read entry " + [Link]());
}
}
}
...
}
}

Note: There is no need to 'squelch()' anything, because no listeners (except

any that you might register) pay attention to extended queries.

44 Developer Guide
 Plug-ins with Threads

Unthreaded Broker Methods

Since the DataQuery is being run in the connection thread, it should use the
'unthreaded' broker methods to access the directory.

These methods are:

unthreadedExists

unthreadedReadEntry

unthreadedCopy

unthreadeList

unthreadedModify

unthreadedSearch
unthreadedGetAllOCs

unthreadedGetRecOCs

For more information, see the JXplorer API Reference

(../jxplorer/api/[Link]) that was installed with JXplorer.

Important! Do not use of the threaded methods such as doEntryQuery()

instead of unthreadedRead(). The threaded methods place a query on the
connection thread queue. Since the extended request is being run by this
same connection thread, if eTrust Directory tries to read the result of one of
these threaded operations, the connection thread will immediately deadlock.

Extending JXplorer 45
Plug-ins with Threads

Example: Check for Existence, Create, and Copy to Backup Branch

As a more elaborate example, let's try the scenario outlined previously:

1. Check the existence of an entry.

2. If it doesn't exist, create it and a subtree.

3. If it does exist, check that the subtree exists and create it if it doesn't.

4. Copy everything to a backup branch.

46 Developer Guide
 Plug-ins with Threads

public class MyPluggableEditor extends BasicPluggableEditor

{
...
...
public void displayEntry(DXEntry entry, DataSource myDataSource)
{
...
... /**
* Define a new 'ExtendedDataQuery' class.
* (XXX error checking not implemented)
*/

class ExtendedDataQuery extends DataQuery

{
Broker currentBroker = null;
public void doExtendedRequest(Broker myBroker)
{
currentBroker = myBroker;
boolean exists = [Link](new DN("cn=top,o=CA"));
if (exists == false)
{
writeTop();
writeTree();
}
else
{
if (checkTree() == false)
writeTree()
}
[Link](new DN("cn=top,o=CA"),
new DN("cn=top,cn=backup,o=CA"));
}
void writeTop()
{
DXEntry top = new DXEntry("cn=top,o=CA");
[Link]("objectClass", "TopEntry");
[Link](null, top);
}
void writeTree()
{
DXEntry[] nodes = new DXEntry[5];
DXEntry[0] = new DXEntry("cn=node A,cn=top,o=CA");
DXEntry[1] = new DXEntry("cn=node B,cn=top,o=CA");
DXEntry[2] = new DXEntry("cn=node C,cn=top,o=CA");
DXEntry[3] = new DXEntry("cn=node D,cn=top,o=CA");
DXEntry[4] = new DXEntry("cn=node E,cn=top,o=CA");
for (int i=0; i&lt;5; i++)
{
DXEntry[i].put("objectClass", "TreeEntry");

Extending JXplorer 47
Localize JXplorer Plug-ins

[Link](null, DXEntry[i]);
}
}
boolean checkTree()
{
DXNamingEnumeration list =
[Link]("cn=top,o=CA");
return (list != null &amp;&amp; [Link]() == 5);
}
}
...
// Create and run our extended query.
[Link](new ExtendedDataQuery())
...
}
}

Localize JXplorer Plug-ins

Plug-ins may also require their own translation files and help files. JX makes it
easy to add plug-in-specific files to JX at run-time.

This is easily done using a single method call. If your plug-in is extending from
BasicPluggableEditor, the call is:

addLanguageBundle("myBundleName");

If you are implementing the PluggableEditor interface, you can make the
equivalent call using the code:

[Link]("myBundleName", getClass().getClassLoader());

In both these instances, replace the string "myBundleName" with the name of
your particular plug-in's resource bundle.

If your plug-in needed to translate the word 'help' into German for display in
the German locale, you would create a file called myPlugin_de.properties, and
have in it the single line:

help = hilfe

Place the 'myPlugin_de.properties' file in your plugin zip file (at the top level),
and make the call 'addLanguageBundle("myPlugin");' in the constructor of
your plug-in, and a later call to '[Link]("help")' should return the string
"hilfe". You could use this in a label definition: JLabel myLabel = new
JLabel([Link]("help"));

48 Developer Guide
 Add Help Files to Plug-ins

Add Help Files to Plug-ins

Plug-ins can also add their help files to the main JXplorer help. This requires
the creation of a plug-in help set (similar to the JXplorer help). When your
help set is created (including foreign language version if required), the
resulting help files should be added to the plug-in zip file (or equivalently,
copied unzipped to the plug-ins directory.

If your plug-in is extending from BasicPluggableEditor, the call is:

addHelpSet("myHelpSet");

If you are implementing the PluggableEditor interface, you can make the
equivalent call using the code:

[Link]("myHelpSet", getClass().getClassLoader());

In both these instances the string "myHelpSet" is replaced with the name of
your particular plug-in's help set.

Extending JXplorer 49
Chapter 4: The DUA Command Set
This section contains the following topics:

What Is the DUA? (see page 51)

Connecting and Disconnecting (see page 52)
Inquire Services (see page 55)
Update Services (see page 62)
Common Arguments (see page 69)
Aliases (see page 74)

What Is the DUA?

For most operations on the directory, use the GUI applications, including
JXplorer.

For large administration tasks, you can use the DUA to run batch operations
and tests on the DSA.

The commands described here fully implement every aspect of every X.500
service and form the basis for testing DXserver. You can consult the test
scripts released with DXserver for various examples of any given service.

This chapter briefly explains each X.500 service. See the X.500 standards
documentation for full details of the services. The X.500 service commands
covered are:

bind-req

unbind-req
abort-req

read-req

search-req

compare-req

abandon-req

list-req

add-entry-req

mod-entry-req

rem-entry-req
mod-dn-req

The DUA Command Set 51

Connecting and Disconnecting

Connecting and Disconnecting

From the management console or remote DUA command line, you must first
connect to the DSA using the bind service. A bind remains active until it is:

Released by the user using the unbind service

Aborted as the result of a network failure

Shut down by the DSA (if a time limit expired)

Shut down by the system administrator (using abort users)

Shut down as a result of the DSA being shut down

Connecting with the Management Console

When you enter the bind command at the management console, the system
treats it as if it had come from a remote DUA. You can have a command as
simple as an anonymous login using the command:

bind-req;

After you enter the command, the dsa> prompt returns immediately, and a
short time later the BIND CONFIRM message appears. The console interface is
asynchronous (that is, you can enter commands at any time, and the
responses return whenever they complete).

When you enable authentication, you must also supply the user and password
fields as part of the command. For example:

bind-req
user = <countryName “AU”>
<organizationName “Democorp”>
<organizationalUnitName “Services”>
<organizationalUnitName “Networks”>
<commonName “Brendan RANDALL”>
password = “ “

The user field supplies the DN of the user initiating the bind. You cannot have
aliases in the DN (see the X.500 standard). Enter the password as a string.

The DSA checks both the name and password, so you must supply a password
when you supply a name.

52 Developer Guide
 Connecting and Disconnecting

Configuring the Scripting DUA

DXserver comes with a number of utilities, one of which is the scripting DUA.
The following file initializes the DUA and connects it to the DSA specified by
remote-addr in the bind request.

When using the scripting DUA utility, the prompt is dua>.

# DXcli Startup Script Sample

#open-log "[Link]" ; # keep a record of session
#echo-on # output commands to log

# Include schema definitions.

source "../schema/[Link]"; # schema rules

# Automatically log on, for convenience

bind-req
user = <countryName “AU”>
<organizationName “Democorp”>
<organizationalUnitName “Services”>
<organizationalUnitName “Networks”>
<commonName “Brendan RANDALL”
password = "Asterix"
remote-addr = {
psap = ""
nsap = rfc1006 "[Link]" port 19389
} ;
wait;
if-reply bind-refuse then quit;
# List root entries, to show we’re online
list-req
entry = < > ;

The DUA Command Set 53

Connecting and Disconnecting

Disconnecting From the DSA

You can disconnect from the DSA using one of the following methods:

Unbinding from the DSA

Aborting the connection

Unbind Request

You can issue an unbind request command at any time. The system discards
any unfinished operations on the association, and closes the connection.

unbind-req;

Because the management console supports multiple associations (for every

bind request it creates a new pseudo user), an unbind request reverts to the
previous user. This is similar to the way you can superimpose UNIX shells over
the top of one another.

Abort Request

You can also issue an abort request; this drops all communication
immediately, regardless of what is in progress.

abort-req;

54 Developer Guide
 Inquire Services

Inquire Services
The operations used for retrieving or comparing information are:

Read

Extracts information from a given entry

Compare

Compares a supplied value against the values stored in an entry

List

Lists the immediately subordinate entries of a given entry

Search

Searches a portion of the DIT for entries of interest

Abandon

Abandons one of the previous operations

You can use each of the inquire services (read, compare, list, and search) to
resolve aliases (see Aliases (see page 74)), and you can give each a time
limit.

All the examples have string values delimited by double quotes (whether
required or not) to help distinguish between attributes and their values.

The DUA Command Set 55

Inquire Services

Read Service

You can return all or selected information from a single entry using the read
service.

Example: Read Service

To read an entry:

read-req
entry = <c “AU”><organizationName “Democorp”>;

The command returns all attributes and values, for example:

Entry:
<countryName “AU”>
<organizationName “Democorp”>
Contents:
(telephoneNumber “03 9727 9922”)
(facsimileTelephoneNumber “03 9726-5300”)
(postalAddress “PO Box 383, Mooroolbark”)
(postalCode “3138”)

You can use the attr-only option, the attrs = .... option, or both to return
selective information.

See the test scripts for more examples.

Compare Service

The DSA uses the compare service for password checks, but you can use them
for comparing any provided information with the contents of a directory entry.

Example: Compare Service

To compare a telephone number:

compare-req
entry = <c “AU”><organizationName “Democorp”>
<organizationalUnitName “Corporate”>
assertion = telephoneNumber “03 9727 9942”;

When the DSA finds the attribute and value provided by the compare request
in the entry, the compare service returns an assertion TRUE. When it does not
find them, the compare service returns an assertion FALSE.

When the DSA does not find the entry or the attribute, a compare-refused
message is returned. See the test scripts for more examples.

56 Developer Guide
 Inquire Services

List Service

You can use the list service to obtain a list of immediate subordinates for an
entry.

Example: List Service

To list from the root:

list-req
entry = <>;

List from organizational unit Corporate under organization Democorp:

list-req
entry = <countryName “AU”>
<organizationName “Democorp”>
<organizationalUnitName “Corporate”>;

The list result returns the relative distinguished names of the objects
immediately under the list object.

When the DSA has knowledge references to other DSAs, the list makes these
references visible. For example, when the domain of the DSA is AU/Democorp
and you define a remote DSA US/OpenDirectory, a list at the root returns both
AU and US and a list under US returns OpenDirectory. (See Knowledge
References in the chapter “Distribution and DSP” for more information.)

See the test scripts for more examples.

The DUA Command Set 57

Inquire Services

Search Service

The search service lets you locate entries of interest on a portion of the DIT.

A search is either as simple as locating a base object or as complex as

selecting objects in a portion of the DIT that satisfy a complex search filter
involving checking for the existence of multiple attributes and values in a
particular combination.

The search (and list) services can return many objects, but if you reach a size
limit or time limit or if you receive an abandon request, you can interrupt the
services. In this case, they may return partial results (the objects they
collected before interruption).

A search is successful when it can find its base object (where to begin the
search). The system ignores invalid aliases or attributes, or other problems
encountered while filtering entries. A search returns no information when none
of the entries matches the given filter.

Search is a very powerful service, and the following are examples

demonstrating a variety of capabilities.

Example: Search Service for One Entry

Simulate a read and retrieve all attributes and values of an entry using search:

search-req
base-object = <countryName “AU”>
<organizationName “Democorp”>;

The default scope of a search is base-object-only.

Example: Search Service for Single Level

Simulate a list and retrieve the names of all objects from one level under
Democorp using search:

search-req
base-object = <countryName “AU”>
<organizationName “Democorp”>
one-level-only
no-info-return;

58 Developer Guide
 Inquire Services

Example: Search Service for Subtree

Search all objects under (and including) Democorp, retrieving all objects that
contain an attribute surname with a value of Smith, and retrieve all
information contained in those entries:

search-req
base-object = <countryName “AU”>
<organizationName “Democorp”>
whole-subtree
filter = { attr = surname value = “Smith” };

Example: Search Service for Local Directory Tree

Search the local directory tree, retrieving all objects that contain a surname
attribute with a value of Smith and a title attribute with a value of Manager
and a telephoneNumber attribute. You retrieve only the commonName,
surname, and telephoneNumber attributes of the objects matching the search
filter.

search-req
base-object = <>
whole-subtree
filter = { and {attr = surname value = “Smith”,
attr = title substrings [ any “Manager”],
attr = telephoneNumber present}
}
attrs = commonName, surname, telephoneNumber
common-args = { local-scope };

You can turn off the resolution of aliases during a search by setting the dont-
search-aliases flag in the search service.

You can receive selected information for each entry that matches the search
filter using attr-only and attrs = ...

LDAP-only examples

These commands are supported by the LDUA, which is the LDAP version of the
DUA. Because the LDUA uses the LDAP protocol, it has access to LDAP
controls, which permit operations to be modified. For example, the search
command can include server-side sorting and paged results.

The DUA Command Set 59

Inquire Services

Example: Search and Sort Results

Search all objects under Democorp, retrieving all objects with common name
beginning with H, and sort the objects in reverse order by description:

search-req
base-object=<o Democorp>
whole-subtree
filter = { attr = commonName substrings [ initial h ] }
attrs = commonName,description
controls = { server-side-sort description reverse critical };

Example: Search and Page Results

Search all objects under Democorp, retrieving all objects that contain an
attribute common name beginning with H, and page the results:

search-req base-object=<o Democorp> whole-subtree

filter = { attr = commonName substrings [ initial h ] }
attrs = commonName,description
controls = { simple-paged-results size = 20 critical };

Example: Search and Sort and Page Results

These LDUA commands can be used together. The following example searches
all objects under Democorp, retrieves all objects that contain an attribute
common name beginning with H, and sorts and pages the results:

search-req base-object=<o Democorp> whole-subtree

filter = { attr = commonName substrings [ initial h ] }
attrs = commonName,description
controls = { server-side-sort commonName
simple-paged-results size = 20 position = 20 };

60 Developer Guide
 Inquire Services

Abandon Service

You can stop an inquire service in process by using the abandon service.

Abandon stops the request having the specified invoke-id (or the last request
if no invoke-id is given) and returns any partial results up to the time of the
abandon request, for example:

abandon-req

invoke-id-to-abandon = 1234;

An abandon confirmed message is returned when you abandon the operation.

If the operation completes or you cannot abandon it, then an abandon refuse
message is returned.

The DUA Command Set 61

Update Services

Update Services
Services that update the DIT are:

Add

Adds a leaf entry

Remove

Deletes a leaf entry

Modify

Adds or removes attributes or attribute values (not distinguished values)

of any entry

Modify-DN

Changes the name of any entry

None of these services returns any data—only a confirmation or an error

message is returned. The format of the confirmation or error message
returned to the management console depends on the tracing modules
activated at the time.

For all update services:

The DSA does not resolve aliases; the system ignores the dont-deref-
aliases common argument.

Size limit is not relevant because no results return; the system ignores the
size-limit common argument.

You cannot abandon them.

See the X.500 standards for details.

The remove service must occur at a leaf entry (the entry at the end of a
branch of the DIT).

You can delete a subtree only by deleting leaves recursively.

62 Developer Guide
 Update Services

Add Service

You can add entries under any existing entry (or root, if it is a first-level DSA).
The entry you add must obey the name-binding rules in force and the
attributes in the entry must obey the object-class rules of that entry.

All attribute types in an add request must be unique.

Example: Add Service for Single Entry

To add an entry:

add-entry-req
entry = <countryName “AU”>
<organizationName “Democorp”>
<organizationalUnitName “Sales”>
contents = {
( objectClass organizationalUnit )
( postalAddress “222–268 Maroondah Highway”.
“Mooroolbark"."Victoria” )
( postalCode “3138” )
( telephoneNumber “(03) 9727-8900”.
“(03) 9727-8901” )
( facsimileTelephoneNumber “(03) 9727-3491” )
};

Multivalue attributes let you record more than one value in a single attribute.
The telephoneNumber attribute in the example contains two values.

You can define some attributes with schema as single-valued (for example,
postalCode).

The postalAddress is a multi-line attribute with each new line separated by a

period in the grammar.

The naming attribute and its value—<organizationalUnitName "Sales"> in the

example—do not occur in the contents of the entry when performing an add
request. You add them implicitly.

In the next example, a multivalue attribute commonName has the value John
Smith used for naming. The commonName attribute must be present in the
contents of the add request so that you can add the value J SMITH.

The DUA Command Set 63

Update Services

Example: Add Service for Multivalue Naming Attribute

To add an entry with a multivalue naming attribute:

add-entry-req
entry = <countryName “AU”>
<organizationName “Democorp”>
<commonName “John Smith”>
contents = {
( objectClass organizationalPerson )
( surname “Smith” )
( commonName “J SMITH” )
};

In the previous examples, the object-class values are depicted as strings. We

can just as easily use the equivalent object-class identifiers (for example,
[Link]).

See the test scripts for more examples.

64 Developer Guide
 Update Services

Remove Service

You can remove leaf entries from the directory.

Example: Remove Service for Organizational Unit

To remove an organizational unit Sales from under organization Democorp:

rem-entry-req
entry = <countryName “AU”>
<organizationName “Democorp”>
<organizationalUnitName “Sales”>;

Example: Remove Service for Organization

To remove the organization OpenDirectory from under root:

rem-entry-req
entry = <organizationName “OpenDirectory”>;

See the test scripts for more examples.

The DUA Command Set 65

Update Services

Modify Service

The modify service lets you add or remove attributes and values.

Example: Modify Service to Add Attributes

To add a fax number (attribute and value) to organizational unit Corporate

under organization Democorp:

mod-entry-req
entry = <countryName “AU”>
<organizationName “Democorp”>
<organizationalUnitName “Corporate” >
add-attr {facsimileTelephoneNumber “03-9727-9722” };

Example: Modify Service to Add and Remove Attributes

To add another phone number (value) for John Smith under organization
Democorp under country AU, while removing one of his common names (the
nondistinguished value—J SMITH):

mod-entry-req
entry = <countryName “AU”>
<organizationName “Democorp”>
<commonName “John Smith”>
rem-values { commonName “J SMITH” },
add-values { telephoneNumber “03 9727 9111” };

An attribute (in an entry) must have at least one value present. Removing the
last value automatically removes the attribute. You cannot remove mandatory
attributes.

When an attribute already exists, you cannot add the same attribute a second
time. You can add additional (multi-) values to an existing attribute. Thus, the
order in which you add or remove entries within one modify service is
important.

Note: Some attributes are single-value attributes. Attempting to add a second

value to a single-value attribute results in an error.

See the test scripts for more examples.

66 Developer Guide
 Update Services

Modify-DN Service

The modify-DN service lets you rename an entry. Renaming a non-leaf entry
changes the distinguished name of all entries under it.

In the modify-DN service, the system supplies a new RDN along with an option
to delete the old RDN. If you do not delete the old RDN, it becomes part of the
normal attribute (its values are no longer distinguished).

Example: Modify-DN Service for Entry

To change the name of the organizational unit R&D (under organization

Democorp) to Research & Development::

mod-dn-req
entry = <countryName “AU”>
<organizationName “Democorp”>
<organizationalUnitName “R&D” >
new-rdn = <organizationalUnitName “Research & Development”>
delete-old;

You can now move an entry and all of its subordinates to a different place in
the tree, using this option:

new-superior = <DN>

The following example moves the R&D entry and all of its subordinates from
AU,Democorp to under the entry AU, Democorp, Corporate.

Example: Modify-DN Service to Move the Entry and Any Sub-Entries

mod-dn-req
entry = <countryName “AU”>
<organizationName “Democorp”>
<organizationalUnitName “R&D” >
new-rdn = <organizationalUnitName “Research & Development”>
delete-old
new-superior = <countryName “AU”>
<organizationName “Democorp”>
<organizationalUnitName Corporate>;

You can change the case of a value (for example, Democorp to DEMOCORP)
using the modify-DN service if you set the delete-old option. Although the
matching rules treat the two values as identical, their raw values are different,
which prevents a duplicate value error from occurring.

The DUA Command Set 67

Update Services

Example: Modify-DN Service to Change Case of a Value

To change the case of a value:

mod-dn-req
entry = <countryName “AU”>
<organizationName “Democorp”>
new-rdn = <organizationName “DEMOCORP”>
delete-old;

See the test scripts for more examples.

68 Developer Guide
 Common Arguments

Common Arguments
The size-limit service control is only applicable to list and search operations. It
indicates the maximum number of objects returned.

search-req
base-object = <countryName “AU”>
...
...
common-args { size-limit = 20 };

When you reach a size limit, the service returns that number of objects and
the qualifier:

Partial Outcome: Size Limit Exceeded

Also refer to the administrative limit max-op-size, usually set in the

configuration file, which can conditionally override this service control.

Time Limit

The time-limit service control is only applicable to read, compare, list, and
search operations. It indicates the maximum number of seconds that a service
takes for execution.

The time limit has a granularity of one second. However, a time limit of zero
can still result in a successful operation, because the DSA may process the
operation in less than one second.

search-req
base-object = <countryName “AU”>
...
...
common-args { time-limit = 10 };

In some cases, when a time limit expires, partial results may not return. For
example, when a list takes three seconds to return 100 subordinates, then a
time limit of one or two seconds can result in an error with no subordinates
returned:

Partial Outcome: Time Limit Exceeded

For more information, see set max-op-time Command in the eTrust Directory
Reference Guide. This command is usually set in the configuration file, and it
can override this service control.

The DUA Command Set 69

Common Arguments

Other Controls

The system provides support for all other X.500 common arguments. These
include service control flags:

prefer-chaining

chaining-prohibited

local-scope

dont-use-copy

dont-deref-aliases

and the service modifiers:

priority
scope-of-referral

See the test scripts for more details.

70 Developer Guide
 Common Arguments

Entry Information Selection

You can control the amount of entry information returned by read and search
operations by using attr-only or attr-and-vals options.

Example: EIS for Attribute Types

To read all attribute types only:

read-req
entry = <c “AU”><o “Democorp”>
attr-only;

The command returns all attributes but no values, for example:

Entry:
<countryName “AU”>
<organizationName “Democorp”>
Contents:
objectClass
organizationName
telephoneNumber

Note: Returning both attributes and values is the default setting for returning
entry information.

You can select which attributes to return. The read service returns an error if it
does not find attributes in the entry.

Example: EIS for Attributes and Values

To read selected attributes and values:

read-req
entry = <c “AU”><o “Democorp”><ou “Corporate”>
attrs = facsimileTelephoneNumber, telephoneNumber;

The command returns attributes and values of the requested attributes:

Entry:
<countryname “AU”>
<organizationName “Democorp”>
<organizationalUnitName “Corporate”>
Contents:
(facsimileTelephoneNumber “(03) 9727 9722”)
(telephoneNumber “(03) 9727 9942”)

Note: The default for returning entry information is all attributes.

The DUA Command Set 71

Common Arguments

Operational Attributes

In addition to the entry information selection controls, you can possibly receive
extra entry information with the read and search operations. This information
is the operational attributes associated with each entry. Using the all-extra-
attrs or extra-attrs options returns the operational attributes.

Example: OpAttrs for All Attributes

To read an entry returning all operational attributes:

read-req
entry = <c “AU”><o “Democorp”>
all-extra-attrs;

The command returns all attributes of the entry, including all operational
attributes, for example:

Entry:
<countryName “AU”>
<organizationName “Democorp”>
Contents:
(objectClass organization)
(organizationName “Democorp”)
(telephoneNumber “(03) 9727 8900”)
(creatorsName
<countryName “AU”>
<organizationName “Democorp”>
<commonName “DSA Administrator”>
)
(createTimestamp 19980712035245Z)
(modifiersName
<countryName “AU”>
<organizationName “Democorp”>
<organizationalUnitName “Services”
<commonName “John Smith”>
)
(modifyTimestamp 19980718062137Z)
(dseType (any)3,2,16)

You can select particular operational attributes.

72 Developer Guide
 Common Arguments

Example: OpAttrs for Selected Attributes

To read an entry returning selected operational attributes:

read-req
entry = <c “AU”><o “Democorp”><ou “Corporate”>
extra-attrs = modifyTimestamp;

The command returns attributes and values of the entry, plus the requested
operational attributes:

Entry:
<countryname “AU”>
<organizationName “Democorp”>
<organizationalUnitName “Corporate”>
Contents:
(objectClass organizationalUnit)
(organizationalUnitName “Corporate”)
(facsimileTelephoneNumber “(03) 9727 9722”)
(telephoneNumber “(03) 9727 9942”)
(modifyTimestamp 19980718062137Z)

When you enable the op-attrs operational control, operational attributes are
added to an entry automatically when it is created or modified:

set op-attrs = true;

The DUA Command Set 73

Aliases

Aliases
Some entries at the leaves of the DIT are alias entries, while all other entries
are object entries. Alias entries point to object entries or other alias entries
and thus provide an alternative name for the corresponding object. The
DXserver DSA resolves alias entries to the distinguished name of the object
entry to which they point (the actual object).

Aliases interplay with many aspects of a DSA. For more information, see the
following sections for more details:

Name bindings and aliases

See the chapter Schema Definition in the eTrust Directory Administrator

Guide.
Access controls and aliases

See Access Controls and Aliases in the chapter Security in the eTrust
Directory Administrator Guide.

Reading an Alias

Aliases resolve during navigation (the starting point for any service). This
means that the alias object is transparent to the user. When you make a read
request of an alias, the object read is the object to which the alias points.

To let a user read the alias object (as opposed to what it points to), you need
a mechanism. You can turn off alias resolution during navigation with the
X.500 service control dont-deref-aliases.

Example: Reading an Alias

To read an alias object:

read-req
entry = <countryName “AU”>
<organizationName “Democorp”>
common-args = {dont-deref-aliases } ;

74 Developer Guide
 Aliases

Adding an Alias

Adding an alias uses the normal add entry request. You must supply the object
class alias and the attribute aliasedObjectName. Any attribute that satisfies
the name binding between the alias and its parent can name the alias.

Example: Add an Alias

To add an alias:

add-entry-req
entry = <countryname “AU”>
<organizationName “Democorp”>
<commonName “Brendan Randall”>
contents = {
(objectClass alias)
(aliasedObjectName
<countryname “AU”>
<organizationName “Democorp”>
<organizationalUnitName “Services”>
<organizationalUnitName “Networks”>
<commonName “Brendan Randall”> )
};

Important! When the DSA has alias integrity enabled and you add an alias,
the object to which the alias points must exist within the domain of the DSA,
and the DSA must be able to navigate to the object entry.

Deleting an Alias

You can delete aliases using the normal remove-entry request.

Example: Deleting an Alias

To delete an alias:

rem-entry-req
entry = <countryName “AU”>
<organizationName “Democorp”>
<commonName “Brendan Randall”>;

When the DSA has alias integrity enabled and you delete an object entry with
an alias entry pointing to it, both the object entry and the alias entry are
deleted.

The DUA Command Set 75

Aliases

Modifying an Alias

You can modify alias entries using the normal modify request. When you
change the aliasedObjectName attribute, the alias points to a different entry.

Example: Modify an Alias

To modify an alias:

mod-entry-req
entry = <countryName “AU”>
<organizationName “Democorp”>
<commonName “Brendan Randall”>
rem-values {
(aliasedObjectName
<countryName “AU”>
<organizationName “Democorp”>
<organizationalUnitName “Services”>
<organizationalUnitName “Networks”>
<commonName “Brendan Randall”> )
},
add-values {
(aliasedObjectName
<countryName “AU”>
<organizationName “Democorp”>
<organizationalUnitName “Services”>
<organizationalUnitName “Networks”>
<commonName “System Manager”>
};

Even though the DSA permits modification of the object class attribute, you
cannot make a non-alias entry an alias entry. To perform such a modification,
first delete the entire entry and then re-add it as an alias (see the X.500
standard).

Important! When the DSA has alias integrity enabled and you modify an alias
entry so that it points to a new object entry, the DSA must be able to navigate
to the new object entry for the modify to succeed.

76 Developer Guide
Chapter 5: The UDDI Server
This section contains the following topics:

Configuring the UDDI Server (see page 77)

Comparing the eTrust Directory UDDI Server with the UDDI Specifications
(see page 79)

Configuring the UDDI Server

The UDDI server’s configuration is stored in a file called [Link]. This
file is located in the folder that holds the various elements of the UDDI server,
which is, by default:

…/dxwebserver/webapps/uddi

If this file is not present, the server uses the default configuration, which is
what is normally installed.

The settings that can be used in the configuration file are:

Name Default Value Description

baseDN o=CA The root DN for the UDDI repository.

We recommend that you do not alter this setting.

directoryUrl ldap://localhost:31389 The location of the DSA to be used as the UDDI

repository.

keyTranslationFile [Link] The file holding pairs of Version 2 and Version 3

ties keys that map to the same thing, for those keys
where the V2 key is not a standard transformation
of the V3 key.

We recommend that you do not alter this setting.

operator [Link] The name of the UDDI repository operator

The baseDN Setting

This setting contains the root DN for the UDDI repository.

Important! This is a directory-specific setting. Do not alter this setting unless

you have a good understanding of eTrust Directory.

The UDDI Server 77

Configuring the UDDI Server

The directoryUrl Setting

This is the URL used to locate the directory server that is the UDDI server’s
data store. This data store is normally located on the same machine as the
UDDI server, and addressed as localhost. This means that you can configure
the DSA to respond only to queries from the local machine, which increases
security.

You can configure the UDDI server to use a DSA on another machine, but this
is less secure than the default setup in two ways:

The DSA must be configured to respond to requests from outside the local
machine – make sure you protect access to the machine running the DSA.

The traffic to the DSA is vulnerable, because it runs between two

machines. We recommend that you use the default setup.

If you install two UDDI servers on the same machine, you have to configure
the second UDDI server to use a non-standard DSA port, and you could do this
by altering the directoryUrl setting. This is not the only setting you would need
to alter – this is not an easy task.

The keyTranslationFile Setting

Important! Do not alter this setting unless you have a good understanding of
UDDI keys.

This is the name of a file that contains a list of key pairs, with one being a
UDDI Version 3 key, and the other a UDDI Version 2 key. This is a list of
exceptions – being those Version 3 keys whose matching Version 2 key is not
the one obtained by running the Version 3 key through the standard
translation algorithm, as documented in the UDDI Version 3 Specification.

Normally this file will only contain the keys which have been accorded special
treatment because their Version 2 keys were defined in the UDDI Version 2
Specification, and their Version 3 keys were defined after the Version 2 keys
were already set. These keys are canonical tModels, such as the
categorization:types tModel.

You may have defined some useful tModels using Version 2, and you may have
given them more meaningful names in Version 3, but wish to retain their
Version 2 keys for consistency. You can do this by adding them to the list of
keys in this file. You should make a copy of this file, add your keys, save it
with a different name, and alter this setting to point to your file – that would
avoid having your file over-written during an upgrade or re-installation of the
software.

78 Developer Guide
 Comparing the eTrust Directory UDDI Server with the UDDI Specifications

The operator Setting

This setting is the string that you wish to see presented in the operator
attribute of each UDDI response.

This string is only included in responses to queries in the UDDI V1 and V2

formats — it is not a part of UDDI V3 responses.

Comparing the eTrust Directory UDDI Server with the UDDI

Specifications
The UDDI server is a multi-version server, responding to requests in Version
1, Version 2, and Version 3 formats. There are some restrictions on this
implementation, and this section attempts to outline what those restrictions
are.

UDDI V1 UDDI V2 UDDI V3

Inquiry API Yes Yes Yes

Publishing API Yes Yes Yes

Security API n/a n/a Yes

Subscription API n/a n/a Not yet

Custody Transfer n/a n/a Not yet

API

Replication API n/a No No

The UDDI Server 79

Comparing the eTrust Directory UDDI Server with the UDDI Specifications

The UDDI Version 1 Specification

The UDDI Version 1 specification is the least well-defined, and most likely to
prove a source of problems.

The UDDI Server support of Version 1 is limited to the query interface – you
cannot publish entries in this server using the Version 1 publishing interface.

APIs Implemented APIs Not Implemented

find_binding Sorting of results

find_business Requests without XML namespace

find_service

find_tModel

get_bindingDetail

get_businessDetail

get_serviceDetail

get_tModelDetail

80 Developer Guide
 Comparing the eTrust Directory UDDI Server with the UDDI Specifications

UDDI Version 2

The UDDI Server includes implementations of all of the inquiry and publishing
APIs.

APIs Implemented APIs Not Implemented

find_binding Complete verification and validation of keyed references

find_business Sorting of results

find_relatedBusinesses Service projections

find_service Filtering of returned serviceInfo on a subset query

find_tModel Special handling of the canonical tModel generalKeywords

get_bindingDetail As for find_tModel

get_businessDetail

get_serviceDetail

get_tModelDetail

add_publisherAssertions

delete_binding

delete_business

delete_publisherAssertions

delete_service

delete_tModel

discard_authToken

get_assertionStatusReport

get_authToken

get_publisherAssertions

get_registerInfo

save_binding

save_business

save_service

save_tModel

set_publisherAssertions

The UDDI Server 81

Comparing the eTrust Directory UDDI Server with the UDDI Specifications

UDDI Version 3

The UDDI Server includes implementations of all of the inquiry and publishing
APIs, plus the security APIs.

APIs Implemented APIs Not Implemented

find_binding Embedded queries (eg: find_tModel inside a find_business

query)

find_business Complete verification and validation of keyed references

find_relatedBusinesses Sorting of results

find_service Diacritic insensitive queries

find_tModel Service projections

get_bindingDetail Filtering of returned serviceInfo on a subset query

get_businessDetail Validation of keys against keyGenerator tModels

get_serviceDetail Special handling of some canonical tModels:

get_tModelDetail isReplacedBy
add_publisherAssertions ValidatedBy
delete_binding DerivedFrom
delete_business generalKeywords
delete_publisherAssertions entityKeyValues
delete_service

delete_tModel

get_assertionStatusReport

get_publisherAssertions

get_registerInfo

save_binding

save_business

save_service

save_tModel

set_publisherAssertions

discard_authToken

get_authToken

82 Developer Guide
 Comparing the eTrust Directory UDDI Server with the UDDI Specifications

Subscription

The UDDI Server does not support the subscription APIs. This functionality
may be included in a future release.

Custody Transfer

The UDDI Server does not include the custody transfer APIs.

The intra-node functionality is planned for a future release, but there is no

plan to implement inter-node transfer, because this is intended to be a single-
node implementation of UDDI.

Replication

This server does not implement the UDDI replication APIs because this is
intended to be a single-node implementation of UDDI.

Instead, you can use the mature replication and distribution functionality in
eTrust Directory to replicate or distribute the underlying data store, and install
the UDDI server layer in multiple locations

The UDDI Server 83