OmniFind Web services overview

OmniFind Enterprise Edition Web services provides access to the product federated search capability through a standardized method, provided by the SOAP protocol. While Java SIAPI can be used to realize J2EE and Java based search applications or to integrate the OmniFind search capabilities in custom applications based on these technologies, OmniFind Web services are useful in developing search applications based on other technologies that support the Web services standard. Figure 1 shows the application interfaces provided by OmniFind:

Web service exposed functions

OmniFind Web service WSDL exposes some functions that are listed at the "WSDL for Web services" page (see Resources for a link). The most relevant function is the search function, used as the basis for the sample code included with this article (see Download).

The search function takes the query information as input and returns a result set containing the search results. The WSDL type used to specify the query information for the search is called SearchRequest. It must be used to specify the search query string but also to configure the query itself (in other words, the query language, the spell correction enablement, the collection ID, and so on).

The WSDL type returned by the search function is called SearchResponse. It contains the items that satisfy the search query and other search information such as the spell corrections suggested, the synonyms, and so on.

Back to top

Getting started

Verify Web services works

OmniFind Web services are deployed as a part of the ESSearchServer application. Therefore, you need an OmniFind Enterprise Edition installation up and running.

The first thing to do is to verify that the OmniFind Web services are installed and work correctly. To do so, you can access the Web services endpoint from a Web browser at the following URL: http://[your_search_server]/ESSearchServer/services/ofsearchBinding.

If the Web service replies with the message "Hi there, this is a Web service!", it's working correctly, and you can go forward to the next step.

Setting up the development environment

If you need to develop, build, and test the Web services from .NET, you need to set up a development environment. It requires a Microsoft Windows® workstation with the Microsoft .NET runtime environment and the Microsoft .NET SDK installed. These are both available for download from the Microsoft Web site.

The Microsoft .NET SDK is all you need to compile a .NET application like the one provided with this document. But if you want to make your life easier in developing and debugging your code, you probably need an IDE (Integrated Development Environment). There are several .NET IDEs available in the market. If you cannot have a Microsoft IDE due to licensing issues, you could use SharpDevelop, a good open source .NET IDE. (See Resources for more information.)

Back to top

Develop a simple .NET search application

The following section describes the main steps to develop a .NET application that performs an enterprise search using OmniFind Web services. The same steps are indicated in the source code provided with this article (see Download).

Generate the proxy client

The first step necessary for developing an OmniFind .NET search application is to generate a .NET proxy client. You can achieve this task using the wsdl.exe tool provided by the .NET SDK.

The wsdl.exe tool must be executed from a command prompt and needs the WSDL URL as an argument. Optionally, you need to also specify the .NET target language for the proxy client (the default is C#).

The following statement, executed from a DOS command prompt, generates a C# OmniFind Web services proxy client:

wsdl.exe http://search_server/ESSearchServer/wsdl/com/ibm/es/ws6/server/search/ofsearch.wsdl

where search_server must to be replaced with the hostname of the server where the OmniFind Enterprise Search application is installed.

Create and initialize the search object

The proxy client class to perform search against OmniFind is called ofsearch. The first thing you need to do is to create an instance of this class and to set it with the Web service endpoint:

//Create and initialize the search object
ofsearch searchObj = new ofsearch();
searchObj.Url = “http:/search_server/ESSearchServer/services/ofsearchBinding";

Create the query request

The OmniFind Web services object to use for query setup is the SearchRequest class. It provides a set of methods and properties to do so, most of which are explained in the following paragraphs.

The Java SIAPI type corresponding to the SearchRequest Web services class is the com.ibm.siapi.search.Query interface. Not all the implementation of the com.ibm.siapi.search.Query interface is provided by the SearchRequest class, but you can refer to the Java SIAPI Javadoc documentation to get more information about the methods and properties provided by the SearchRequest class.

Note: The SIAPI Javadoc documentation is provided with OmniFind at the following location: [ES_INSTALL_ROOT]/docs/api/siapi (where ES_INSTALL_ROOT is the OmniFind installation directory).

Create the request object

Next, create an instance of the object where you can set all the query parameters.

//Create the request object
SearchRequest request = new SearchRequest();

Set the query parameters

The query parameters are used to enable or disable query related functions such as the spell corrector, the synonyms expansion, and so on. To set these parameters, you can use the corresponding fields defined by the SearchRequest class.

//Enable spell corrections
request.spellCorrectionEnabled = true;

Set the returned attributes

You can decide whether an attribute type is returned or not in the result. Some examples of attribute types are the title, the date, and so on. For a complete list of returned attribute types, see the description of the setReturnedAttribute method of the com.ibm.siapi.search.Query interface in the Java SIAPI Javadoc.

Information about returned attribute enablement must be set in the request object using an array of PredefinedAttribute objects where each element of the array contains the configuration of one attribute type. Each PredefinedAttribute object is set with a couple of values: a numeric value that corresponds with the attribute type and a boolean value that specifes if the return of the attribute is enabled or not.

The Java SIAPI defines a set of static variables that represent the attributes type. The list of all the values can be found in the Java SIAPI Javadoc, starting from the description of the com.ibm.siapi.search.BaseQuery interface.

The following sample code sets the fields attributes to be returned in the query results:

//Enable the return of the field attribute (RETURN_RESULT_FIELDS)
PredefinedAttribute returnFields = new PredefinedAttribute ();
returnFields.attribute = -3;
returnFields.returned = true;

attributesList.Add(returnFields);

PredefinedAttribute[] predefinedAttributes;

predefinedAttributes =
    (PredefinedAttribute[])attributesList.ToArray( typeof (PredefinedAttribute) );

request.returnAttribute = predefinedAttributes;

Set the sort parameters

To determine how the results must be ordered by OmniFind, you have to set the sort parameters. In particular, you can use them to set the key and the locale by which the results should be sorted, the sort ordering, and the number of results that should be returned, ordered by the key. For more details about sort keys, see the description of the setSort methods of the com.ibm.siapi.search.Query class in Java SIAPI Javadoc.

To set the sort parameters in a .NET application, you can use the sort properties defined by the SearchRequest class. If sort parameters are not set, the results will be provided ordered by relevance. The code in LIsting 5 sets the sort properties to retrieve all the available query results ordered by date in descending order:

//Set sort parameters

//set the sort key to SORT_KEY_DATE in order to retrieve the results ordered by date
request.sortKey = "date";

//set the sortOrder to SORT_ORDER_DESCENDING
request.sortOrder = -1;

/*
set the sortPoolSize property to SORT_ALL_RESULTS in order
to retrieve all the results ordered by the specified key
*/
request.sortPoolSize = 2147483647;

Set query properties

You can se the query properties in order to control the query processing. The properties available to control the query are listed on the "Setting query properties" page in the Information Center (see Resources for a link). Listing 6 shows how to set the HighlightingMode property in order to obtain the query terms highlighted in several fields returned by OmniFind (the document title, the document URL, and so on):

//set query properties

//Create a Property objects array
Property[] queryProperties = new Property[1];

/*
Create the Property object containing the HighlightingMode property value
in order to obtain extended highlighting
*/
Property highlightingModeProp = new Property();
highlightingModeProp.name = "HighlightingMode";
highlightingModeProp.value = "ExtendedHighlighting";

//Put the highlightingMode property in the properties array
queryProperties[0]=highlightingModeProp;

//Set the properties field with the Property array
request.properties = queryProperties;

Set the parameters for result paging

If you plan to implement a paging mechanism to show the query results, you have to initialize the firstRequestedResult and the numRequestedResults fields of the SearchRequest class in order to obtain only the first page results. If you want to retrieve all the results that satisfy the query criteria, do not set these properties.

//Set parameters to page the first search results
request.firstRequestedResult = firstResult;
request.numRequestedResults = resultPerPage;

Set the query string and launch the search

The last thing to do before launching the query is to set the query string. You can do this by using the queryText properties provided by SearchRequest class.

//set the query text
request.queryText = searchString;

To launch the search, invoke the ofseach.search() method, passing to it the SearchRequest instance created and initialized in the previous steps.

//Perform the search to get the first n results
SearchResponse response = searchObj.search(request);

If the search application implements the paging to present the results, the search method returns the number of results specified by the numRequestedResults properties. In order to retrieve the result for another "page" of results, you have to set the firstRequestedResult and the numRequestedResults fields properly, and call the search method again.

Retrieve the query results

As stated before, the ofsearch.search() method returns an instance of the SearchResponse class. It provides the items returned by the query and all the other information related with the search.

This section describes the result retrieval implemented by the sample application provided with this artice (see Download).

The Java SIAPI type correspondent to the SearchResponse Web services class is com.ibm.siapi.search.ResultSet interface. Refer to the Java SIAPI Javadoc documentation to get more information about the methods and properties provided by the SearchResponse class.

Get suggested spell corrections and synonym expansions

If you enable the spell correction function during the query preparation, the response object provides the suggestions proposed by OmniFind for the query words.

The SearchResponse.spellCorrections property contains an array of SpellCorrection objects, each of which provides the word that OmniFind suggests to substitute and the suggested substitute.

If OmniFind does not have any spell corrections to propose, the spellCorrections property is null.

The same is valid for synonym expansions that are provided by an array of SynonymExpansion objects contained in the SearchResponse.synonymExpansions property.

//Look for proposed spell corrections
SpellCorrection[] spellCorrections = response.spellCorrections;
if (spellCorrections != null){
    foreach (SpellCorrection currentSpellCorrection in spellCorrections){
        foreach (String suggestion in currentSpellCorrection.suggestions){
            Console.WriteLine ("Did you mean: " + suggestion);
        }
    }
}

Get information about the search results

The SearchResponse object provides general information about the search results, such as the number of results made available by OmniFind, the estimated results that satisfy the query exceeding the result pool size, and the messages associated with the search response.

//Print general information about the search results
Console.WriteLine ("-----------------------------------");
Console.WriteLine ("Available results: " + response.availableNumberOfResults);
Console.WriteLine ("Estimated results: " + response.estimatedNumberOfResults);
Console.WriteLine ("-----------------------------------");

Fetch the search results

The results that satisfy the query are contained in the results property of the SearchResponse instance. The results property contains an array of Result objects, each of which provides all the properties of the result. These properties include the standard fields (such as the title, description, date, language, URI, and so on), and, if the result fields attribute has been enabled, the fields specific for the result type (for example, the column value if the result is a database row, or the value of a metadata, if the crawled source is a content management repository like FileNet P8 or IBM Content Manager).

The following C# code (Listing 12) iterates on a Result instance and prints the fields related with the result:

//Show results properties
Result[] foundedResults = response.results;

if (foundedResults != null)
{
    foreach (Result result in foundedResults){
        //Increase the result counter
        resultCounter++;
        Console.WriteLine ("** Result # " + resultCounter + " **");

        NameValuePair[] fields = result.fields;

        foreach (NameValuePair field in fields){
            Console.WriteLine (field.name + ": " + field.value);
        }

        Console.WriteLine ("** End of Result **");
        Console.WriteLine (" ");
    }
}

Back to top

Conclusion

OmniFind Enterprise Edition Web services interface enables the integration of search functionality provided by OmniFind in heterogeneous environments based on any technology that supports Web services and SOAP standards. Using the guidelines provided in this article, you can immediately start to develop a .NET search application and understand how OmniFind Web services works in order to implement applications in other languages that support this standard technology.

Back to top

Download

Information about download methods

Resources

Learn

• OmniFind Enterprise Edition page: Find more information about IBM OmniFind Enterprise Edition.
  
  
• OmniFind Enterprise Edition Information Center: View, browse, and search online information about OmniFind Enterprise Edition. Explore the following topics in the Information Center:
  • Developing search applications
  • Web services for enterprise search
  • WSDL for Web services
  • Setting query properties
  
  
• "C# Tutorial" (C# Station, 2008-2009): Learn the basis of the C# programming language.
  
  
• developerWorks Information Management zone: Learn more about Information Management. Find technical documentation, how-to articles, education, downloads, product information, and more.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  
• Technology bookstore: Browse for books on these and other technical topics.
  
  

Get products and technologies

• SharpDevelop: Download SharpDevelop, a free, open source IDE for C#, VB.NET and Boo projects on Microsoft's .NET platform, from the ic#code Web site.
  
  
• Build your next development project with IBM trial software, available for download directly from developerWorks.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Participate in developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

Massimiliano Carra is an Enterprise Content Management IT specialist at IBM, focused on the IBM FileNet P8 Platform and Discovery solutions. He has over 13 years of experience in various IT professional fields, from system integration using J2EE and SOA technologies to solution design working on Object Oriented-based applications. He also has 10 years of experience on the Linux operating system, and open source products and projects. He joined IBM Software Group in 2005 as a technical sales specialist in the Information Management brand and has direct technical responsibility for customers located in central and southern Italy.

Rate this article

Comments

Back to top

Table of contents

• OmniFind Web services overview
• Getting started
• Develop a simple .NET search application
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

Rational Application Developer features provide the comprehensive Integrated Development Environment (IDE) used to develop J2EE applications requiring Servlets and JavaServer Pages (JSPs).

---

• Try: Try the free Rational Application Developer, which helps developers quickly design, develop, test, analyze, and deploy high-quality Java, Javaserver pages, and J2EE applications.
• Article: Learn how you can deliver accurate, higher-quality J2EE apps with Rational Application Developer, open source JUnit and JUnitEE test frameworks.
• Tutorial: Build a Facebook application using PHP, the Spring framework, and J2EE.
• Demo: This demo shows how to use the new Java EE 5 Java Persistence API (JPA) framework.
• Buy: Rational Application Developer

Dig deeper into Information Management on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers