com.sapportals.wcm.service.urlgenerator
Interface IURLGeneratorService

[contained in: com.sap.netweaver.bc.rf.service.par - bc.rf.global.service.urlgenerator_api.jar]

All Superinterfaces:

IService

public interface IURLGeneratorService

extends IService

Offers methods to get relative or absolute URIs pointing to certain resources of the CM system like iViews or repositories.

The URL generator service provides methods to get relative URIs (containing absolute paths without protocol and server) to certain resources like the explorer page or details page. It's recommended to use only these relative URIs as long as possible. For example, it's sufficient to use a relative URI for setting a link from one page to another page on the same server (see example below)

The interface also offers the possibility to generate absolute URIs (containing protocol and server). This feature is need, e.g., for integrating URIs into emails to allow a direct link into the CM system (see example below)

To obtain a valid instance of an URL generator, proceed as follows:

   IURLGeneratorService ug = (IURLGeneratorService)ResourceFactory
     .getInstance()
     .getServiceFactory()
     .getService(IServiceTypesConst.URLGENERATOR_SERVICE);
 

To set a link from one page to another on the same server, we only need a relative URI; proceed as follows:

   RID rid = ;
   IUriReference uriRef = ug.getResourcePageUri(PathKey.DETAILS_PAGE, rid,null);

   com.sapportals.htmlb.Link  link = new Link("detail", "Details");
   link.setReference( uriRef.toString() );
 

To include a link to a page in an email, we need an absolute URI; proceed as follows:

   RID rid = ;
   IUriReference uriRef = ug.getResourcePageUri(PathKey.DETAILS_PAGE, rid,null);
   IHierarchicalUri uri = ug.createAbsoluteUri(uriRef);
   String  uriString = uri.toExternalForm();

   // put  into an email
 

Copyright (c) SAP AG

Field Summary

static java.lang.String	FOLDER_USER_BRIEFCASE
static java.lang.String	FOLDER_USER_CLIPBOARD
static java.lang.String	FOLDER_USER_FAVORITES
static java.lang.String	FOLDER_USER_INBOX
static java.lang.String	FOLDER_USER_LINKS
static java.lang.String	FOLDER_USER_QUERIES
static java.lang.String	FOLDER_USER_TEMP
static java.lang.String	MIME_TYPE_PHOTO
static java.lang.String	MIME_TYPE_RDF
static java.lang.String	MIME_TYPE_VCARD

Method Summary

IHierarchicalUri	createAbsoluteUri(IUriReference relativeUri) Creates an absolute URI out of the specified relative URI (containing an absolute path) by prepending the configured protocol, server and port.
IHierarchicalUri	createAlternativeAbsoluteUri(IUriReference relativeUri) Creates an absolute URI out of the specified relative URI (containing an absolute path) by prepending the configured (alternative) protocol, server and port.
void	deregisterPlaceholderResolver(IPlaceholderResolver resolver) Deregisters resolver from this IURLGeneratorService .
void	deregisterUriMapper(IUriMapper mapper) Deregisters mapper from this IURLGeneratorService .
IHierarchicalUri	getAbsoluteUri(PathKey key) Gets the absolute URI of the path referred by key .
IHierarchicalUri	getAlternativeAbsoluteUri(PathKey key) Gets the absolute URI of the path referred by key .
IUriReference	getBusinessCardUri(java.lang.String userId) Deprecated. As of Netweaver '04 SP6, replaced by getBusinessCardUri(String, IResourceContext)
IUriReference	getBusinessCardUri(java.lang.String userId, IResourceContext context) Gets the relative URI for bringing up the business card of the user specified by userId .
RID	getGroupResourceRID(com.sapportals.portal.security.usermanagement.IGroup group) Gets the RID of a collection representing the specified group.
RID	getGroupResourceRID(java.lang.String groupId) Gets the RID of a collection representing the specified group.
IUriReference	getImageUri(java.lang.String filename) Gets the relative URI of the image filename .
java.lang.String	getNameOfConfigfile() Returns the name of the XML file which is set as default in the CM configuration and used for the wdf-navigation.
IRidSet	getPrincipalCollectionRidSet() Gets a set of RIDs of all collections representing principals (user, groups, roles).
IUriReference	getRelativeUri(PathKey key) Gets the relative URI of the path referred by key .
IUriReference	getResourcePageUri(PathKey key, RID resourceRID, RID startRID) Gets the relative URI for bringing up a page handling the resource specified by resourceRID .
RID	getRoleResourceRID(com.sapportals.portal.security.usermanagement.IRole role) Gets the RID of a collection representing the specified role.
RID	getRoleResourceRID(java.lang.String roleId) Gets the RID of a collection representing the specified role.
IUriReference	getServicePageUri(java.util.List queryParameters) Gets the relative URI for bringing up a service which may immediately carry out some instructions (e.g. delete a resource or display a dialog).
RID	getUserFolderRID(com.sapportals.portal.security.usermanagement.IUser user, java.lang.String folder) Gets the RID of the specified subfolder of the user's home folder.
RID	getUserHomeRID(com.sapportals.portal.security.usermanagement.IUser user) Gets the RID of the user's home folder.
IUriReference	getUsermappingPageUri(java.lang.String systemId, java.lang.String successUrl, java.lang.String failureUrl, java.lang.String cancelUrl) Gets the relative URI of the usermapping maintenance servlet.
RID	getUserResourceRID(com.sapportals.portal.security.usermanagement.IUser user) Gets the RID of a resource representing the specified user.
RID	getUserResourceRID(com.sapportals.portal.security.usermanagement.IUser user, java.lang.String format) Gets the RID of a resource in the specified format representing the specified user.
RID	getUserResourceRID(java.lang.String userId) Gets the RID of a resource representing the specified user.
RID	getUserResourceRID(java.lang.String userId, java.lang.String format) Gets the RID of a resource in the specified format representing the specified user.
IUri	mapRID(RID rid) Gets the URI of the CM resource (e.g. http resource) represented by the given RID.
RID	mapUri(IUri uri) Gets the RID of the CM resource which represents the given URI (e.g. http resource).
void	registerPlaceholderResolver(IPlaceholderResolver resolver) Registers resolver to this IURLGeneratorService .
void	registerUriMapper(IUriMapper mapper) Registers mapper to this IURLGeneratorService .
java.lang.String	resolvePlaceholders(java.lang.String uri, IResource resource) Resolves all placeholders contained in uri by their corresponding values.
java.lang.String	resolvePlaceholders(java.lang.String uri, IResourceContext context) Resolves all placeholders contained in uri by their corresponding values.
void	setUMRidGenerator(IUserManagementRidGenerator ridGenerator) Sets ridGenerator as the new IUserManagementRidGenerator . used by some of the methods in this interface to get RIDs of resources representing principals (users. groups, roles) or information about them.

Methods inherited from interface com.sapportals.wcm.service.IService

getDescription, getDescription, getID

Field Detail

FOLDER_USER_BRIEFCASE

public static final java.lang.String FOLDER_USER_BRIEFCASE

FOLDER_USER_CLIPBOARD

public static final java.lang.String FOLDER_USER_CLIPBOARD

FOLDER_USER_FAVORITES

public static final java.lang.String FOLDER_USER_FAVORITES

FOLDER_USER_INBOX

public static final java.lang.String FOLDER_USER_INBOX

FOLDER_USER_LINKS

public static final java.lang.String FOLDER_USER_LINKS

FOLDER_USER_QUERIES

public static final java.lang.String FOLDER_USER_QUERIES

FOLDER_USER_TEMP

public static final java.lang.String FOLDER_USER_TEMP

MIME_TYPE_RDF

public static final java.lang.String MIME_TYPE_RDF

MIME_TYPE_VCARD

public static final java.lang.String MIME_TYPE_VCARD

MIME_TYPE_PHOTO

public static final java.lang.String MIME_TYPE_PHOTO

Method Detail

getRelativeUri

public IUriReference getRelativeUri(PathKey key)
                             throws WcmException

Gets the relative URI of the path referred by key . The returned IUriReference will not contain a protocol or authority.
For example, for getting the path of the explorer serlvet, just call

   getRelativeUri(PathKey.EXPLORER_SERVLET) -> /wcm/apps/explorer
 

Parameters:

key - the key of the path in question

Returns:

the relative URI of the path referred by key

Throws:

WcmException - if the requested path is not configured

getAbsoluteUri

public IHierarchicalUri getAbsoluteUri(PathKey key)
                                throws WcmException

Gets the absolute URI of the path referred by key . The absolute URI will consist of the configured protocol, server and port concatenated with the path in question.
For example, for getting the URI of the explorer servlet, just call

   getAbsoluteUri(PathKey.EXPLORER_SERVLET) -> http://localhost:8080/wcm/apps/explorer
 

Parameters:

key - the key of the path in question

Returns:

the absoulte URI of the path referred by key

Throws:

WcmException - if the requested path is not configured

getAlternativeAbsoluteUri

public IHierarchicalUri getAlternativeAbsoluteUri(PathKey key)
                                           throws WcmException

Gets the absolute URI of the path referred by key . The absolute URI will consist of the configured (alternative) protocol, server and port concatenated with the path in question.
For example, for getting the alternative URI of the explorer servlet, just call

   getAlternativeAbsoluteUri(PathKey.EXPLORER_SERVLET) -> http://server2:8080/wcm/apps/explorer
 

Parameters:

key - the key of the path in question

Returns:

the absoulte URI of the path referred by key

Throws:

WcmException - if the requested path is not configured

createAbsoluteUri

public IHierarchicalUri createAbsoluteUri(IUriReference relativeUri)
                                   throws WcmException

Creates an absolute URI out of the specified relative URI (containing an absolute path) by prepending the configured protocol, server and port.
For example, for getting the absolute URI of the business card of the user 'admin', just call

   IUriReference uriRef = urlGenerator.getBusinessCardUri("admin", resourceContext);
   IHierarchicalUri uri = urlGenerator.createAbsoluteUri(uriRef);
 

Parameters:

relativeUri - the relative URI to be transformed into an absolute one (must contain an absolute path)

Returns:

the absolute URI representation of the specified relative URI

Throws:

WcmException - Exception raised in failure situation

createAlternativeAbsoluteUri

public IHierarchicalUri createAlternativeAbsoluteUri(IUriReference relativeUri)
                                              throws WcmException

Creates an absolute URI out of the specified relative URI (containing an absolute path) by prepending the configured (alternative) protocol, server and port.
For example, for getting the alternative absolute URI of the business card of the user 'admin', just call

   IUriReference uriRef = urlGenerator.getBusinessCardUri("admin", resourceContext);
   IHierarchicalUri uri = urlGenerator.createAlternativeAbsoluteUri(uriRef);
 

Parameters:

relativeUri - the relative URI to be transformed into an absolute one (must contain an absolute path)

Returns:

the absolute URI representation of the specified relative URI

Throws:

WcmException - Exception raised in failure situation

getNameOfConfigfile

public java.lang.String getNameOfConfigfile()
                                     throws WcmException

Returns the name of the XML file which is set as default in the CM configuration and used for the wdf-navigation.

Returns:

the name of the XML file in question

Throws:

WcmException - if the default configuration file is not configured

getImageUri

public IUriReference getImageUri(java.lang.String filename)
                          throws WcmException

Gets the relative URI of the image filename .

Parameters:

filename - the name of the image file (without path)

Returns:

the (relative) URI of the image file

Throws:

WcmException - if the image path is not configured

getBusinessCardUri

public IUriReference getBusinessCardUri(java.lang.String userId)
                                 throws WcmException

Deprecated. As of Netweaver '04 SP6, replaced by getBusinessCardUri(String, IResourceContext)

Gets the relative URI for bringing up the business card of the user specified by userId .

Parameters:

userId - the identifier of the user whose business card being questioned

Returns:

the (relative) URI of the user's business card

Throws:

WcmException - if the path of the businesscard is not configured

getBusinessCardUri

public IUriReference getBusinessCardUri(java.lang.String userId,
                                        IResourceContext context)
                                 throws WcmException

Gets the relative URI for bringing up the business card of the user specified by userId .

Parameters:

userId - the identifier of the user whose business card being questioned

context - a resource context containing an authenticated user

Returns:

the (relative) URI of the user's business card

Throws:

WcmException - if the path of the businesscard is not configured

getResourcePageUri

public IUriReference getResourcePageUri(PathKey key,
                                        RID resourceRID,
                                        RID startRID)
                                 throws WcmException

Gets the relative URI for bringing up a page handling the resource specified by resourceRID . The additional parameter startRID has to be a parent RID of the given resource RID. It forbids navigation to any element being a root for the given resource RID.

Parameters:

resourceRID - the RID of the resource in question

startRID -

key - TBD: Description of the incoming method parameter

Returns:

the (relative) URI of the page handling the resource

Throws:

WcmException - if the requested path is not configured

getServicePageUri

public IUriReference getServicePageUri(java.util.List queryParameters)
                                throws WcmException

Gets the relative URI for bringing up a service which may immediately carry out some instructions (e.g. delete a resource or display a dialog). The parameter properties must contain parameters identifying the service to be started and the instructions to be performed.

The interface IWcmConst holds a set of parameters starting with SERVICE_SERVLET which can be used as keys or default values for the parameter properties . You can also use "free" key-value pairs, but you have to make sure, that the receiving service knows about these keys.

Example:

   Properties props = new Properties();
   props.setProperty(IWcmConst.SERVICE_SERVLET_PARAMETER_RESOURCE,  rid.toExternalForm());
   props.setProperty(IWcmConst.SERVICE_SERVLET_PARAMETER_STARTPAGE, "WcmExplorerPage");
   props.setProperty(IWcmConst.SERVICE_SERVLET_PARAMETER_XML_FILE,  "WcmController.xml");

   IUriReference uriRef = urlGenerator.getServletCallUri(props);
 

Parameters:

queryParameters - TBD: Description of the incoming method parameter

Returns:

the (relative) URI to call the service page

Throws:

WcmException - if the path to the service page is not configured

getUsermappingPageUri

public IUriReference getUsermappingPageUri(java.lang.String systemId,
                                           java.lang.String successUrl,
                                           java.lang.String failureUrl,
                                           java.lang.String cancelUrl)
                                    throws WcmException

Gets the relative URI of the usermapping maintenance servlet.

Parameters:

systemId - the identifier of the system in the system landscape

successUrl -

failureUrl -

cancelUrl -

Returns:

the (relative) URI of the usermapping maintenance servlet

Throws:

WcmException - if the path to the usermapping page is not configured

getUserHomeRID

public RID getUserHomeRID(com.sapportals.portal.security.usermanagement.IUser user)
                   throws WcmException

Gets the RID of the user's home folder.

Parameters:

user - the user whose home folder in question

Returns:

the RID of the user's home folder

Throws:

WcmException - Exception raised in failure situation

getUserFolderRID

public RID getUserFolderRID(com.sapportals.portal.security.usermanagement.IUser user,
                            java.lang.String folder)
                     throws WcmException

Gets the RID of the specified subfolder of the user's home folder.

Parameters:

user - the user in question

folder - the desired subfolder of the user's home folder

Returns:

the RID of the user's subfolder (one of the constants FOLDER_* )

Throws:

WcmException - Exception raised in failure situation

setUMRidGenerator

public void setUMRidGenerator(IUserManagementRidGenerator ridGenerator)

Sets ridGenerator as the new IUserManagementRidGenerator . used by some of the methods in this interface to get RIDs of resources representing principals (users. groups, roles) or information about them.

Parameters:

ridGenerator - the RID generator to be set

See Also:

getGroupResourceRID(String), getRoleResourceRID(String), getUserResourceRID(String)

getPrincipalCollectionRidSet

public IRidSet getPrincipalCollectionRidSet()
                                     throws WcmException

Gets a set of RIDs of all collections representing principals (user, groups, roles).

Returns:

set of all collections representing principals

Throws:

WcmException - on error

getUserResourceRID

public RID getUserResourceRID(com.sapportals.portal.security.usermanagement.IUser user)
                       throws WcmException

Gets the RID of a resource representing the specified user.

Parameters:

user - the user in question

Returns:

the RID of the corresponding user resource

Throws:

WcmException - on error

getUserResourceRID

public RID getUserResourceRID(com.sapportals.portal.security.usermanagement.IUser user,
                              java.lang.String format)
                       throws WcmException

Gets the RID of a resource in the specified format representing the specified user.

Parameters:

user - the user in question

format - the desired format (one of the constants FORMAT_* )

Returns:

the RID of the corresponding user resource

Throws:

WcmException - on error

getUserResourceRID

public RID getUserResourceRID(java.lang.String userId)
                       throws WcmException

Gets the RID of a resource representing the specified user.

Parameters:

userId - the identifier of the user in question

Returns:

the RID of the corresponding user resource

Throws:

WcmException - on error

getUserResourceRID

public RID getUserResourceRID(java.lang.String userId,
                              java.lang.String format)
                       throws WcmException

Gets the RID of a resource in the specified format representing the specified user.

Parameters:

userId - the identifier of the user in question

format - the desired format (one of the constants FORMAT_*

Returns:

the RID of the corresponding user resource

Throws:

WcmException - on error

getGroupResourceRID

public RID getGroupResourceRID(com.sapportals.portal.security.usermanagement.IGroup group)
                        throws WcmException

Gets the RID of a collection representing the specified group.

Parameters:

group - the group in question

Returns:

the RID of the corresponding group collection

Throws:

WcmException - on error

getGroupResourceRID

public RID getGroupResourceRID(java.lang.String groupId)
                        throws WcmException

Gets the RID of a collection representing the specified group.

Parameters:

groupId - the identifier of the group in question

Returns:

the RID of the corresponding group collection

Throws:

WcmException - on error

getRoleResourceRID

public RID getRoleResourceRID(com.sapportals.portal.security.usermanagement.IRole role)
                       throws WcmException

Gets the RID of a collection representing the specified role.

Parameters:

role - the role in question

Returns:

the RID of the corresponding role collection

Throws:

WcmException - on error

getRoleResourceRID

public RID getRoleResourceRID(java.lang.String roleId)
                       throws WcmException

Gets the RID of a collection representing the specified role.

Parameters:

roleId - the identifier of the role in question

Returns:

the RID of the corresponding role collection

Throws:

WcmException - on error

registerPlaceholderResolver

public void registerPlaceholderResolver(IPlaceholderResolver resolver)
                                 throws AlreadyRegisteredException

Registers resolver to this IURLGeneratorService .

The resolver will be registered for handling the placeholder which is returned by a call to IPlaceholderResolver.getPlaceholder().

If another resolver has already been registered for handling this placeholder, it depends on the classes of the two resolver wether an exception will be thrown or not.

If both resolver are instances of the same class, the new resolver will replace the old one. Otherwise, an AlreadyRegisteredException will be thrown.

Parameters:

resolver - the IPlaceholderResolver to be registered

Throws:

AlreadyRegisteredException - if a different class has already been registered for handling the corresponding placeholder

deregisterPlaceholderResolver

public void deregisterPlaceholderResolver(IPlaceholderResolver resolver)

Deregisters resolver from this IURLGeneratorService .

If resolver is not registered for handling the placeholder which is returned by a call to IPlaceholderResolver.getPlaceholder(), the call to this method will be ignored.

Parameters:

resolver - the IPlaceholderResolver to be deregistered

resolvePlaceholders

public java.lang.String resolvePlaceholders(java.lang.String uri,
                                            IResource resource)
                                     throws ResourceException

Resolves all placeholders contained in uri by their corresponding values.

Parameters:

uri - a String whose placeholder should be resolved

resource -

Returns:

TBD: Description of the outgoing return value

Throws:

ResourceException - on error

resolvePlaceholders

public java.lang.String resolvePlaceholders(java.lang.String uri,
                                            IResourceContext context)
                                     throws ResourceException

Resolves all placeholders contained in uri by their corresponding values.

Parameters:

uri - a String whose placeholder should be resolved

context -

Returns:

TBD: Description of the outgoing return value

Throws:

ResourceException - on error

registerUriMapper

public void registerUriMapper(IUriMapper mapper)

Registers mapper to this IURLGeneratorService .

Whenever a web resource needs to be represented as a CM resource, the method should be called which will use the registered mappers to accomplish the task of mapping a given web URL to a RID of a CM resource.

Parameters:

mapper - the URI mapper to be registered

deregisterUriMapper

public void deregisterUriMapper(IUriMapper mapper)

Deregisters mapper from this IURLGeneratorService .

Parameters:

mapper - the URI mapper to be deregistered

mapUri

public RID mapUri(IUri uri)
           throws WcmException

Gets the RID of the CM resource which represents the given URI (e.g. http resource).

Parameters:

uri - the URI to be mapped

Returns:

the RID of a CM resource representing the given URI or null if mapping not possible

Throws:

WcmException - Exception raised in failure situation

mapRID

public IUri mapRID(RID rid)
            throws WcmException

Gets the URI of the CM resource (e.g. http resource) represented by the given RID.

Parameters:

rid - the RID to be mapped

Returns:

the URI of a CM resource represented by the given RID or null if mapping not possible

Throws:

WcmException - Exception raised in failure situation