001package org.apache.fulcrum.security.torque.peer;
002/*
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *   http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing,
014 * software distributed under the License is distributed on an
015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
016 * KIND, either express or implied.  See the License for the
017 * specific language governing permissions and limitations
018 * under the License.
019 */
020import java.io.Serializable;
021
022import org.apache.fulcrum.security.spi.AbstractEntityManager;
023import org.apache.fulcrum.security.util.DataBackendException;
024
025
026/**
027 * Use this manager in role-list, if you want to swap default peer classes.
028 * It gets automatically registered in {@literal TorqueTurbine<Type>ManagerImpl classes. <Types> are: <User>, <Group>, <Permission>, <Role>}.
029 * You have to register your {@literal <Type>PeerImpl classes} by adding the {@link TorqueTurbinePeer} interface.
030 * 
031 * If generating your ORM-classes from a Torque schema, you may have to delete or provide your own baseClasses in the schema.
032 * 
033 * @see <a href="http://db.apache.org/torque/torque-4.0/documentation/orm-reference/database-4-0.xsd" target=_blank>Torque 4.0 Schema</a>
034 * @see org.apache.fulcrum.security.torque.turbine TorqueTurbine&lt;Type&gt;ManagerImpl referencing manager classes.
035 *  
036 * @author <a href="mailto:gk@apache.org">Georg Kallidis</a>
037 * @version $Id$
038 */
039public interface PeerManager extends Serializable
040{
041
042    String ROLE = PeerManager.class.getName(); 
043
044    /**
045     * Expects the class name of a Torque Peer class, which could be instantiated. 
046     * {@link org.apache.fulcrum.security.spi.AbstractEntityManager#getClassName()}
047     *  
048     * @param peerClassName the peerClassName
049     * @return a cached peer class instance
050     * @throws DataBackendException data backend exception
051     */
052    public abstract <P extends Peer> P getPeerInstance(String peerClassName)
053        throws DataBackendException;
054
055    /**
056     * This method is provided to get more helpful exception messages.
057     * 
058     * @param peerClassName the peerClassName
059     * @param class1 expected class the peers should implement 
060     * @param className target class, i.e. the data object class type of the Peer object. The data object for which the peer is provided. 
061     * @return peer instance
062     * @throws DataBackendException data backend exception
063     */
064    public abstract <P extends Peer> P getPeerInstance( String peerClassName, Class<? extends Peer> class1, String className ) throws DataBackendException;
065
066
067}