cmsobject.java

cms是开源的框架

/*
 * File   : $Source: /usr/local/cvs/opencms/src/org/opencms/file/CmsObject.java,v $
 * Date   : $Date: 2006/03/27 14:52:41 $
 * Version: $Revision: 1.146 $
 *
 * This library is part of OpenCms -
 * the Open Source Content Mananagement System
 *
 * Copyright (c) 2005 Alkacon Software GmbH (http://www.alkacon.com)
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * For further information about Alkacon Software GmbH, please see the
 * company website: http://www.alkacon.com
 *
 * For further information about OpenCms, please see the
 * project website: http://www.opencms.org
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

package org.opencms.file;

import org.opencms.db.CmsPublishList;
import org.opencms.db.CmsSecurityManager;
import org.opencms.file.types.I_CmsResourceType;
import org.opencms.lock.CmsLock;
import org.opencms.main.CmsException;
import org.opencms.main.CmsIllegalArgumentException;
import org.opencms.main.I_CmsEventListener;
import org.opencms.main.OpenCms;
import org.opencms.report.CmsShellReport;
import org.opencms.report.I_CmsReport;
import org.opencms.security.CmsAccessControlEntry;
import org.opencms.security.CmsAccessControlList;
import org.opencms.security.CmsPermissionSet;
import org.opencms.security.CmsPrincipal;
import org.opencms.security.CmsRole;
import org.opencms.security.CmsRoleViolationException;
import org.opencms.security.CmsSecurityException;
import org.opencms.security.I_CmsPrincipal;
import org.opencms.util.CmsUUID;
import org.opencms.workflow.CmsTaskService;

import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.Set;

/**
 * This pivotal class provides all authorized access to the OpenCms VFS resources.<p>
 * 
 * It encapsulates user identification and permissions.
 * Think of it as an initialized "shell" to access the OpenCms VFS.
 * Every call to a method here will be checked for user permissions
 * according to the <code>{@link org.opencms.file.CmsRequestContext}</code> this CmsObject instance was created with.<p>
 * 
 * From a JSP page running in OpenCms, use <code>{@link org.opencms.jsp.CmsJspBean#getCmsObject()}</code> to gain 
 * access to the current users CmsObject. Usually this is done with a <code>{@link org.opencms.jsp.CmsJspActionElement}</code>.<p>
 * 
 * To generate a new instance of this class in your application, use 
 * <code>{@link org.opencms.main.OpenCms#initCmsObject(String)}</code>. The argument String should be 
 * the name of the guest user, usually "Guest" and more formally obtained by <code>{@link org.opencms.db.CmsDefaultUsers#getUserGuest()}</code>.
 * This will give you an initialized context with guest user permissions.
 * Then use <code>{@link CmsObject#loginUser(String, String)}</code> to log in the user you want.
 * Obviously you need the password for the new user.
 * You should never try to create an instance of this class using the constructor, 
 * this is reserved for internal operation only.<p> 
 *
 * @author Alexander Kandzior 
 * @author Thomas Weckert  
 * @author Carsten Weinholz 
 * @author Andreas Zahner 
 * @author Michael Moossen 
 * 
 * @version $Revision: 1.146 $
 * 
 * @since 6.0.0 
 */
public final class CmsObject {

    /**
     * The request context.
     */
    protected CmsRequestContext m_context;

    /**
     * The security manager to access the cms.
     */
    protected CmsSecurityManager m_securityManager;

    /**
     * Connects an OpenCms user context to a running database.<p>
     * 
     * <b>Please note:</b> This constructor is internal to OpenCms and not for public use.
     * If you want to create a new instance of a <code>{@link CmsObject}</code> in your application,
     * use <code>{@link org.opencms.main.OpenCms#initCmsObject(String)}</code>.<p>
     * 
     * @param securityManager the security manager
     * @param context the request context that contains the user authentification
     */
    public CmsObject(CmsSecurityManager securityManager, CmsRequestContext context) {

        init(securityManager, context);
    }

    /**
     * Adds a user to a group.<p>
     * 
     * @param username the name of the user that is to be added to the group
     * @param groupname the name of the group
     * 
     * @throws CmsException if something goes wrong
     */
    public void addUserToGroup(String username, String groupname) throws CmsException {

        m_securityManager.addUserToGroup(m_context, username, groupname);
    }

    /**
     * Creates a new web user.<p>
     * 
     * A web user has no access to the workplace but is able to access personalized
     * functions controlled by the OpenCms.<br>
     * 
     * Moreover, a web user can be created by any user, the intention being that
     * a "Guest" user can create a personalized account for himself.<p>
     *
     * @param name the name for the new web user
     * @param password the password for the user
     * @param group the default groupname for the user
     * @param description the description for the user
     * @param additionalInfos a <code>{@link Map}</code> with additional infos for the user
     * 
     * @return the newly created user
     * 
     * @throws CmsException if something goes wrong
     */
    public CmsUser addWebUser(String name, String password, String group, String description, Map additionalInfos)
    throws CmsException {

        return m_securityManager.addWebUser(m_context, name, password, group, description, additionalInfos);
    }

    /**
     * Creates a backup of the current project.<p>
     * 
     * @param versionId the version of the backup
     * @param publishDate the date of publishing
     *
     * @throws CmsException if operation was not succesful
     */
    public void backupProject(int versionId, long publishDate) throws CmsException {

        m_securityManager.backupProject(m_context, versionId, publishDate);
    }

    /**
     * Changes the access control for a given resource and a given principal(user/group).<p>
     * 
     * @param resourceName name of the resource
     * @param principalType the type of the principal (currently group or user):
     *      <ul>
     *          <li><code>{@link I_CmsPrincipal#PRINCIPAL_USER}</code></li>
     *          <li><code>{@link I_CmsPrincipal#PRINCIPAL_GROUP}</code></li>
     *      </ul>
     * @param principalName name of the principal
     * @param allowedPermissions bitset of allowed permissions
     * @param deniedPermissions bitset of denied permissions
     * @param flags additional flags of the access control entry
     * 
     * @throws CmsException if something goes wrong
     */
    public void chacc(
        String resourceName,
        String principalType,
        String principalName,
        int allowedPermissions,
        int deniedPermissions,
        int flags) throws CmsException {

        CmsResource res = readResource(resourceName, CmsResourceFilter.ALL);

        I_CmsPrincipal principal = CmsPrincipal.readPrincipal(this, principalType, principalName);
        CmsAccessControlEntry acEntry = new CmsAccessControlEntry(
            res.getResourceId(),
            principal.getId(),
            allowedPermissions,
            deniedPermissions,
            flags);
        acEntry.setFlagsForPrincipal(principal);

        m_securityManager.writeAccessControlEntry(m_context, res, acEntry);
    }

    /**
     * Changes the access control for a given resource and a given principal(user/group).<p>
     * 
     * @param resourceName name of the resource
     * @param principalType the type of the principal (group or user):
     *      <ul>
     *          <li><code>{@link I_CmsPrincipal#PRINCIPAL_USER}</code></li>
     *          <li><code>{@link I_CmsPrincipal#PRINCIPAL_GROUP}</code></li>
     *      </ul>
     * @param principalName name of the principal
     * @param permissionString the permissions in the format ((+|-)(r|w|v|c|i|o))*
     * 
     * @throws CmsException if something goes wrong
     */
    public void chacc(String resourceName, String principalType, String principalName, String permissionString)
    throws CmsException {

        CmsResource res = readResource(resourceName, CmsResourceFilter.ALL);

        I_CmsPrincipal principal = CmsPrincipal.readPrincipal(this, principalType, principalName);
        CmsAccessControlEntry acEntry = new CmsAccessControlEntry(
            res.getResourceId(),
            principal.getId(),
            permissionString);
        acEntry.setFlagsForPrincipal(principal);

        m_securityManager.writeAccessControlEntry(m_context, res, acEntry);
    }

    /**
     * Changes the project id of the resource to the current project, indicating that 
     * the resource was last modified in this project.<p>
     * 
     * This information is used while publishing. Only resources inside the 
     * project folders that are new/modified/changed <i>and</i> that "belong" 
     * to the project (i.e. have the id of the project set) are published
     * with the project.<p>
     * 
     * @param resourcename the name of the resource to change the project id for (full path)
     * 
     * @throws CmsException if something goes wrong
     */
    public void changeLastModifiedProjectId(String resourcename) throws CmsException {

        CmsResource resource = readResource(resourcename, CmsResourceFilter.ALL);
        getResourceType(resource.getTypeId()).changeLastModifiedProjectId(this, m_securityManager, resource);
    }

    /**
     * Changes the lock of a resource to the current user,
     * that is "steals" the lock from another user.<p>
     * 
     * This is the "steal lock" operation.<p>
     * 
     * @param resourcename the name of the resource to change the lock with complete path
     * 
     * @throws CmsException if something goes wrong
     */
    public void changeLock(String resourcename) throws CmsException {

        CmsResource resource = readResource(resourcename, CmsResourceFilter.ALL);
        getResourceType(resource.getTypeId()).changeLock(this, m_securityManager, resource);
    }

    /**
     * Returns a list with all sub resources of a given folder that have set the given property, 
     * matching the current property's value with the given old value and replacing it by a given new value.<p>
     *
     * @param resourcename the name of the resource to change the property value
     * @param property the name of the property to change the value
     * @param oldValue the old value of the property, can be a regular expression
     * @param newValue the new value of the property
     * @param recursive if true, change recursively all property values on sub-resources (only for folders)
     *
     * @return a list with the <code>{@link CmsResource}</code>'s where the property value has been changed
     *
     * @throws CmsException if operation was not successful
     */
    public List changeResourcesInFolderWithProperty(
        String resourcename,
        String property,
        String oldValue,
        String newValue,
        boolean recursive) throws CmsException {

        CmsResource resource = readResource(resourcename, CmsResourceFilter.IGNORE_EXPIRATION);
        return m_securityManager.changeResourcesInFolderWithProperty(
            m_context,
            resource,
            property,
            oldValue,
            newValue,
            recursive);
    }

    /**
     * Changes the type of a user given its id.<p>
     *
     * @param userId The id of the user to change
     * @param userType The new type of the user
     * 
     * @throws CmsException if something goes wrong
     */
    public void changeUserType(CmsUUID userId, int userType) throws CmsException {

        m_securityManager.changeUserType(m_context, userId, userType);
    }

    /**
     * Changes the type of a user given its name.<p>
     *
     * @param username The name of the user to change
     * @param userType The new type of the user
     * 
     * @throws CmsException if something goes wrong
     */
    public void changeUserType(String username, int userType) throws CmsException {

        m_securityManager.changeUserType(m_context, username, userType);
    }

    /**
     * Checks if the given base publish list can be published by the current user.<p>
     * 
     * @param publishList the base publish list to check
     * 
     * @throws CmsException in case the publish permissions are not granted
     */
    public void checkPublishPermissions(CmsPublishList publishList) throws CmsException {

        // now perform the permission test
        m_securityManager.checkPublishPermissions(m_context, publishList);
    }

    /**
     * Checks if the user of this OpenCms context 
     * is a member of at last one of the roles in the given role set.<p>
     *