001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: ResourceName.java,v 1.2 2008/06/25 05:43:47 qcheng Exp $
026 *
027 */
028
029package com.sun.identity.policy.interfaces;
030
031import java.util.Map;
032import java.util.Set;
033import com.sun.identity.policy.ResourceMatch;
034import com.sun.identity.policy.PolicyException;
035
036/**
037 * The interface <code>ResourceName</code> provides
038 * methods to determine the hierarchy of resource names.
039 * It provides methods to compare resources, get sub resources etc.
040 * Also it provides an interface to determine the service
041 * type to which it be used. Service developers could
042 * provide an implementation of this interface that will
043 * determine its hierarchy during policy evaluation and
044 * also its display in the GUI. A class that implements
045 * this interface must have a empty constructor.
046 * @supported.all.api
047 */
048public interface ResourceName {
049
050    /**
051     * Returns the service type names for which the resource name
052     * object can be used.
053     *
054     * @return service type names for which the resource
055     * comparator can be used
056     */
057    public Set getServiceTypeNames();
058
059    /**
060     * Initializes the resource name with configuration information,
061     * usually set by the administrators
062     *
063     * @param configParams configuration parameters as a map.
064     * The keys of the map are the configuration parameters. 
065     * Each key is corresponding to one <code>String</code> value
066     * which specifies the configuration parameter value.
067     */
068    public void initialize(Map configParams);
069
070    /**
071     * Compares two resources.
072     *
073     * @param origRes name of the resource which will be compared
074     * @param compRes name of the resource which will be compared with
075     * @param wildcardCompare flag for wildcard comparison
076     *
077     * @return returns <code>ResourceMatch</code> that
078     * specifies if the resources are exact match, or
079     * otherwise.
080     * <ul>
081     * <li><code>ResourceMatch.NO_MATCH</code> means two resources do not match
082     * <li><code>ResourceMatch.EXACT_MATCH</code> means two resources match
083     * <li><code>ResourceMatch.SUB_RESOURCE_MATCH</code> means
084     *     <code>compRes</code> is the sub resource of the <code>origRes</code>
085     * <li><code>ResourceMatch.SUPER_RESOURCE_MATCH</code> means
086     *     <code>compRes</code> is the super resource of the
087     *     <code>origRes</code>
088     * <li><code>ResourceMatch.WILDCARD_MATCH</code> means two resources match
089     *     with respect to the wildcard
090     * </ul>
091     */
092    public ResourceMatch compare(
093        String origRes, String compRes, boolean wildcardCompare);
094    
095    /**
096     * Appends sub-resource to super-resource.
097     *
098     * @param superResource name of the super-resource to be appended to.
099     * @param subResource name of the sub-resource to be appended.
100     *
101     * @return returns the combination resource.
102     */
103    public String append(String superResource, String subResource);
104
105    /**
106     * Gets sub-resource from an original resource minus
107     * a super resource. This is the complementary method of
108     * append().
109     *
110     * @param res name of the original resource consisting of
111     * the second parameter <code>superRes</code> and the returned value
112     * @param superRes name of the super-resource which the first
113     * parameter begins with.
114     *
115     * @return returns the sub-resource which the first parameter
116     * ends with. If the first parameter does not begin with the
117     * the first parameter, then the return value is null.
118     */
119    public String getSubResource(String res, String superRes);
120
121    /**
122     * Gets the canonicalized form of a resource string
123     * 
124     * @param res the resource string to be canonicalized
125     * @return the resource string in its canonicalized form.
126     * @throws PolicyException if resource string is invalid
127     */
128    public String canonicalize(String res) throws PolicyException;
129
130
131    /******* this method will be removed after the demo ********/
132    /**
133     * Method to split a resource into the smallest necessary
134     * sub resource units
135     *
136     * @param res name of the resource to be split
137     *
138     * @return returns the array of sub-resources, with the first
139     * element being what the original resource begins with, and
140     * the last one being what it ends with
141     */
142    public String[] split(String res);
143
144}