com.ibm.portal.services.url
Interface UrlResourceService

public interface UrlResourceService

The UrlResourceService provides a means to query, add, update, and delete URL Resource definitions within the WebSphere Application Server's configuration repository, encapsulating the logic necessary for interacting with its administrative interface. URL Resources are used to record universal resource locators (URLs) for accessing servers. URL Resources also allow the URLs to be given a descriptive name, category, and JNDI name for looking up the URL itself within an application running within WebSphere Application Server. Like other resources maintained by the configuration repository, there is a notion of scope (cell, node, server, or cluster) for the URL Resource, controlling its visibility to applications running within the same cell as the configuration repository owning the URL Resource definition. This service allows the user to specify this scope when working with URL Resources. The typical user of this service will query all available URL Resource definitions, allowing the application end-user or administrator to select from the available URL Resources when configuring the application. The application should then save the JNDI name reference as part of its configuration, not the URL value itself. This allows the URL Resource definition to be modified, such as if the URL value itself must change, without requiring that all applications using that URL be updated. Applications would look up the actual URL based on the URL Resource's JNDI name, like so:

  java.net.URL serverURL = null;
  try
  {
    java.naming.Context initialContext = new java.naming.InitialContext();
    serverURL = (java.net.URL) initialContext.lookup(urlJndiName); 
  }
  catch (javax.naming.NamingException e)
  {
    e.printStackTrace(System.out);
  }
 

The service also supports creating, updating, and deleting URL Resources for those applications or administrative interfaces where such operations are required. For instance, an application may allow the end-user or administrator to specify a URL explicitly, especially if a suitable URL does not exist, and then after gathering additional meta data about the URL may use this service to store the URL value within a new URL Resource object for reuse by other applications. URL Resource definitions also have the ability to have a category assigned to it. This category can be used to group URL Resources by purpose or nature. For instance, there might be a category of URL Resources for locating mail servers. When searching for available URL Resources, the category may be specified to filter the list to include only those URL Resources matching that category. Use the ServiceManager to load an instance of this service:

 Context initialContext = new InitialContext();
 UrlResourceService urlService = (UrlResourceService) initialContext.lookup("portal:service/UrlResourceService");
 

Since:

6.0.1

Field Summary

static java.lang.String	ATTRIBUTE_CATEGORY ATTRIBUTE_CATEGORY represents the URL Resource category attribute, which can optionally be used to associate this URL Resource to some arbitrary category.
static java.lang.String	ATTRIBUTE_DESC ATTRIBUTE_DESC represents the URL Resource description attribute, which can optionally be used to describe the nature of this URL Resource.
static java.lang.String	ATTRIBUTE_JNDI_NAME ATTRIBUTE_JNDI_NAME represents the URL Resource jndiName attribute, which uniquely identifies this URL Resource within a specific scope.
static java.lang.String	ATTRIBUTE_NAME ATTRIBUTE_NAME represents the URL Resource administrative name attribute, which can have any string value and does not have to be unique within the same scope in the configuration repository.
static java.lang.String	ATTRIBUTE_URL ATTRIBUTE_URL represents the URL Resource url "spec" attribute, whose string value must be a valid URL format using either HTTP, HTTPS, FILE, or FTP protocols.

Method Summary

boolean	createUrlResource(javax.management.AttributeList createAttributes, ScopeConstants scope) Creates a new URL Resource object within the configuration registry with the specified attributes at the specified scope.
boolean	deleteUrlResource(javax.management.AttributeList deleteAttributes, ScopeConstants scope) Deletes an existing URL Resource object within the configuration registry identified by the specified attributes at the specified scope.
java.util.List	getUrlList(java.lang.String category, ScopeConstants scope) Returns a List of AttributeList objects.
boolean	updateUrlResource(javax.management.AttributeList updateAttributes, ScopeConstants scope) Updates an existing URL Resource object within the configuration registry with the specified attributes at the specified scope.

Field Detail

ATTRIBUTE_NAME

static final java.lang.String ATTRIBUTE_NAME

ATTRIBUTE_NAME represents the URL Resource administrative name attribute, which can have any string value and does not have to be unique within the same scope in the configuration repository.

See Also:

Constant Field Values

ATTRIBUTE_URL

static final java.lang.String ATTRIBUTE_URL

ATTRIBUTE_URL represents the URL Resource url "spec" attribute, whose string value must be a valid URL format using either HTTP, HTTPS, FILE, or FTP protocols. It does not have to be unique within the same scope in the configuration repository.

See Also:

Constant Field Values

ATTRIBUTE_DESC

static final java.lang.String ATTRIBUTE_DESC

ATTRIBUTE_DESC represents the URL Resource description attribute, which can optionally be used to describe the nature of this URL Resource.

See Also:

Constant Field Values

ATTRIBUTE_CATEGORY

static final java.lang.String ATTRIBUTE_CATEGORY

ATTRIBUTE_CATEGORY represents the URL Resource category attribute, which can optionally be used to associate this URL Resource to some arbitrary category. The category attribute can be used to help refine searches for URL Resources, limiting the results to only those URL Resources matching the specified category.

See Also:

Constant Field Values

ATTRIBUTE_JNDI_NAME

static final java.lang.String ATTRIBUTE_JNDI_NAME

ATTRIBUTE_JNDI_NAME represents the URL Resource jndiName attribute, which uniquely identifies this URL Resource within a specific scope. Users of this service should remember the JNDI name and use it to look up the URL Resource for runtime use.

See Also:

getUrlList, Constant Field Values

Method Detail

getUrlList

java.util.List getUrlList(java.lang.String category,
                          ScopeConstants scope)
                          throws java.lang.IllegalArgumentException,
                                 java.lang.reflect.InvocationTargetException

Returns a List of AttributeList objects. Each AttributeList object in the array represents the list of attributes for a single URL Resource object from within the WebSphere Application Server's configuration repository, matching the specified category and contained within the specified scope. Example use:

  List urlObjects = urlService.getUrlList(null, SCOPE_CELL);
  // iterate through all URL Resource object attribute lists in the array
  for (int i=0; i < urlObjects.size(); i++)
  {
    AttributeList attList = (AttributeList)urls.get(i) ;
    // iterate through all the attributes in this AttributeList instance
    Iterator e = attList.iterator();
    while (e.hasNext()) {
      Attribute att = (Attribute)e.next();
      // Do something with this attribute, such as building a viewable list from which a selection is made
      if (att.getName().equals("jndiName"))
      {
        // Remember that the JNDI name is the attribute you need to save to refer to when getting the actual URL
      }
    }
  }
 

Parameters:

category - The string value that represents a category with which to restrict the search for available URL Resources; only those URL Resources that have the same category value specified will be returned. Use null to mean "no category specified".

scope - The scope with which to restrict the search for available URL Resource objects. Use one of the SCOPE_* type constants from UrlResourceServiceConstants.

Returns:

List of AttributeList objects. Each AttributeList represents the attributes of a single URL Resource object. If no URL Resource objects available with the given category and scope, an empty List is returned.

Throws:

java.lang.IllegalArgumentException - Thrown when an illegal parameter is passed into the method, such as scope.

java.lang.reflect.InvocationTargetException - Thrown when an error occurred calling the underlying management APIs that interface with WebSphere Application Server. Use the getTargetException() method to get the actual underlying exception.

See Also:

AttributeList

createUrlResource

boolean createUrlResource(javax.management.AttributeList createAttributes,
                          ScopeConstants scope)
                          throws java.lang.IllegalArgumentException,
                                 java.lang.reflect.InvocationTargetException

Creates a new URL Resource object within the configuration registry with the specified attributes at the specified scope. Example use:

      AttributeList createAttrs = new AttributeList();
      createAttrs.add(new Attribute(ATTRIBUTE_NAME, "Sample URL"));
      createAttrs.add(new Attribute(ATTRIBUTE_JNDI_NAME, "mysample"));
      createAttrs.add(new Attribute(ATTRIBUTE_CATEGORY, "samples"));
      createAttrs.add(new Attribute(ATTRIBUTE_URL, "http://myserver.myco.com"));
      createAttrs.add(new Attribute(ATTRIBUTE_DESC, "This is a sample URL that can be looked up using the JNDI name mysample."));

      urlService.createUrlResource(createAttrs, SCOPE_NODE);
 

Note that the JNDI name must be unique within the specified scope. All other attribute values may be non-unique.

Parameters:

createAttributes - The attributes making up the new URL Resource object. See the ATTRIBUTE_* public static variables for more information.

scope - The scope with which to restrict the search for available URL Resource objects. Use one of the SCOPE_* type constants from UrlResourceServiceConstants.

Returns:

boolean Indicates whether the creation was successful or not.

Throws:

java.lang.IllegalArgumentException - Thrown when an illegal parameter is passed into the method, such as scope.

java.lang.reflect.InvocationTargetException - Thrown when an error occurred calling the underlying management APIs that interface with WebSphere Application Server. Use the getTargetException() method to get the actual underlying exception.

See Also:

AttributeList

updateUrlResource

boolean updateUrlResource(javax.management.AttributeList updateAttributes,
                          ScopeConstants scope)
                          throws java.lang.IllegalArgumentException,
                                 java.lang.reflect.InvocationTargetException

Updates an existing URL Resource object within the configuration registry with the specified attributes at the specified scope. Example use:

      AttributeList updateAttrs = new AttributeList();
      updateAttrs.add(new Attribute(ATTRIBUTE_NAME, "Sample URL"));
      updateAttrs.add(new Attribute(ATTRIBUTE_JNDI_NAME, "mysample"));
      updateAttrs.add(new Attribute(ATTRIBUTE_CATEGORY, "samples"));
      updateAttrs.add(new Attribute(ATTRIBUTE_URL, "http://myserver.myco.com"));
      updateAttrs.add(new Attribute(ATTRIBUTE_DESC, "This is a sample URL that can be looked up using the JNDI name mysample."));

      urlService.updateUrlResource(updateAttrs, SCOPE_NODE);
 

Note that the JNDI name must be unique within the specified scope and must identify the URL Resource to update. All other attributes are optional.

Parameters:

updateAttributes - The attributes used to update an existing URL Resource object. The ATTRIBUTE_JNDI_NAME attribute must be specified in order to locate the correct URL Resource to modify. See the ATTRIBUTE_* public static variables for more information.

scope - The scope with which to restrict the search for available URL Resource objects. Use one of the SCOPE_* type constants from UrlResourceServiceConstants.

Returns:

boolean Indicates whether the update was successful or not.

Throws:

java.lang.IllegalArgumentException - Thrown when an illegal parameter is passed into the method, such as scope.

java.lang.reflect.InvocationTargetException - Thrown when an error occurred calling the underlying management APIs that interface with WebSphere Application Server. Use the getTargetException() method to get the actual underlying exception.

See Also:

AttributeList

deleteUrlResource

boolean deleteUrlResource(javax.management.AttributeList deleteAttributes,
                          ScopeConstants scope)
                          throws java.lang.IllegalArgumentException,
                                 java.lang.reflect.InvocationTargetException

Deletes an existing URL Resource object within the configuration registry identified by the specified attributes at the specified scope. Example use:

      AttributeList deleteAttrs = new AttributeList();
      updateAttrs.add(new Attribute(ATTRIBUTE_JNDI_NAME, "mysample"));

      urlService.deleteUrlResource(deleteAttrs, SCOPE_NODE);
 

Note that the JNDI name must be unique within the specified scope and must identify the URL Resource to delete. It is the only attribute which must be specified when deleting a URL Resource object.

Parameters:

deleteAttributes - The attributes used to locate an existing URL Resource object to delete. The ATTRIBUTE_JNDI_NAME attribute must be specified in order to locate the correct URL Resource. See the ATTRIBUTE_* public static variables for more information.

scope - The scope with which to restrict the search for available URL Resource objects. Use one of the SCOPE_* type constants from UrlResourceServiceConstants.

Returns:

boolean Indicates whether the delete was successful or not.

Throws:

java.lang.IllegalArgumentException - Thrown when an illegal parameter is passed into the method, such as scope.

java.lang.reflect.InvocationTargetException - Thrown when an error occurred calling the underlying management APIs that interface with WebSphere Application Server. Use the getTargetException() method to get the actual underlying exception.

See Also:

AttributeList