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: DiscoEntryHandler.java,v 1.2 2008/06/25 05:47:12 qcheng Exp $
026 *
027 */
028
029
030package com.sun.identity.liberty.ws.disco.plugins;
031
032import java.util.Map;
033import java.util.List;
034
035/**
036 * The class <code>DiscoEntryHandler</code> is an interface that is 
037 * used to get and set <code>DiscoEntries</code> for a user.
038 * <p>
039 * A default implementation will be provided for this discovery service.
040 * If you want to handle <code>DiscoEntry</code> differently, implement this
041 * interface and set the implementing class to
042 * <code>DiscoEntryHandler Plugins Class</code> field in Discovery Service.
043 *
044 * @supported.all.api
045 */
046public interface DiscoEntryHandler {
047
048    /**
049     * Key used in method <code>modifyDiscoEntries()</code> return Map.
050     * The value of this key is status code String such as "OK", "Failed", etc.
051     */
052    public static final String STATUS_CODE = "STATUS_CODE";
053
054    /**
055     * Key used in method <code>modifyDiscoEntries()</code> return Map.
056     * The value of this key is a List of <code>entryIds</code> for the entries
057     * that were added.
058     */
059    public static final String NEW_ENTRY_IDS = "newEntryIDs";
060
061    /**
062     * Finds all the discovery entries for a user.
063     * @param userID The user whose discovery entries will be returned.
064     * @param reqServiceTypes List of
065     *  <code>com.sun.identity.liberty.ws.disco.jaxb.RequestedServiceType</code>
066     *  objects from discovery query.
067     * @return Map of <code>entryId</code> and
068     *  <code>com.sun.identity.liberty.ws.disco.plugins.jaxb.DiscoEntryElement
069     *  </code> objects for this user. For each <code>DiscoEntry</code> element
070     *  in the List, the <code>entryId</code> attribute of
071     *  <code>ResourceOffering</code> should be set.
072     */
073    public Map getDiscoEntries(String userID, List reqServiceTypes); 
074
075
076    /**
077     * Modifies discovery entries for a user.
078     * @param userID The user whose discovery entries will be set.
079     * @param removes List of
080     *  <code>com.sun.identity.liberty.ws.disco.jaxb.RemoveEntryType</code>
081     *  <code>jaxb</code> objects.
082     * @param inserts List of
083     *  <code>com.sun.identity.liberty.ws.disco.jaxb.InsertEntryType</code>
084     *  <code>jaxb</code> objects.
085     * @return Map which contains the following key value pairs:
086     *  Key: <code>DiscoEntryHandler.STATUS_CODE</code>
087     *  Value: status code String such as "OK", "Failed", etc.
088     *  Key: <code>DiscoEntryHandler.NEW_ENTRY_IDS</code>
089     *  Value: List of <code>entryId</code>s for the entries that were added.
090     *  The second key/value pair will only exist when status code is
091     *  "OK", and there are <code>InsertEntry</code> elements in the
092     *  <code>Modify</code> request.
093     *  When successful, all modification (removes and inserts) should
094     *  be done. No partial changes should be done.
095     */
096    public Map modifyDiscoEntries(String userID,
097                                        List removes, List inserts);
098}