Metacat

/**

 *  '$RCSfile$'

 *    Purpose: A class that handles checking permssision for a document

               and subtree in a document 

 *             

 *  Copyright: 2000 Regents of the University of California and the

 *             National Center for Ecological Analysis and Synthesis

 *    Authors: Chad Berkley

 *    Release: @release@

 *

 *   '$Author: tao $'

 *     '$Date: 2003-04-08 16:30:15 -0700 (Tue, 08 Apr 2003) $'

 * '$Revision: 1527 $'

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License as published by

 * the Free Software Foundation; either version 2 of the License, or

 * (at your option) any later version.

 *

 * This program 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 General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 */

package edu.ucsb.nceas.metacat;

import java.sql.*;

import java.util.Enumeration;

import java.util.Hashtable;

import java.util.Stack;

import java.util.Vector;

public class PermissionController

{

   private String docId = null;

   private boolean hasSubTreeAccessControl = false; // flag if has a subtree

                                                    // access for this docid

   private Vector subTreeList = new Vector();

   private long TOPLEVELSTARTNODEID = 0; //if start node is 0, means it is top

                                         //level document

   /**

    * Constructor for PermissionController

    * @param myDocid      the docid need to access

    */

   public PermissionController(String myDocid) throws McdbException

   {

     // Get rid of rev number

     docId = MetaCatUtil.getDocIdFromString(myDocid);

     hasSubTreeAccessControl = checkSubTreeAccessControl();

   }

   /**

    * Return if a document has subtree access control

    */

   public boolean hasSubTreeAccessControl()

   {

     return hasSubTreeAccessControl;

   }

   /*

    * Go through the access table and find if has subtree access control

    * if has, store the subtree into list and return true. Otherwise, 

    * return false

    */

  private boolean checkSubTreeAccessControl() throws McdbException

  {

    boolean flag = false;

    PreparedStatement pStmt=null;

    ResultSet rs=null;

    DBConnection conn=null;

    int serialNumber=-1;

    String query="SELECT subtreeid, startnodeid, endnodeid from xml_access " +

                 "where docid =? ";

    try

    {

      //check out DBConnection

      conn=DBConnectionPool.getDBConnection("PermissionController.hasSubTreeA");

      serialNumber=conn.getCheckOutSerialNumber();

      pStmt=conn.prepareStatement(query);

      //bind the value to query

      pStmt.setString(1, docId);

      //execute the query

      pStmt.execute();

      rs=pStmt.getResultSet();

      //process the result

      while (rs.next()) //

      {

        String subTreeId = rs.getString(1);

        MetaCatUtil.debugMessage("subtreeid: "+subTreeId, 35);

        long startNodeId = rs.getLong(2);

        MetaCatUtil.debugMessage("subtree startNodeId: "+startNodeId, 35);

        long endNodeId = rs.getLong(3);

        MetaCatUtil.debugMessage("subtree endNodeId: "+endNodeId, 35);

        // if startnodeid field in table is empty,startNodeId will be 0

        if (subTreeId != null && startNodeId != 0 && startNodeId != 0)

        {

          flag = true;// has subtree control

          SubTree tree = new SubTree();

          tree.setSubTreeId(subTreeId);

          tree.setStartNodeId(startNodeId);

          tree.setEndNodeId(endNodeId);

          subTreeList.add(tree);

         }

      }

    }//try

    catch (SQLException e)

    {

      throw new McdbException(e);

    }

    finally

    {

      try

      {

        pStmt.close();

      }

      catch(SQLException ee)

      {

        throw new McdbException(ee);

      }

      finally

      {

        DBConnectionPool.returnDBConnection(conn, serialNumber);

      }

    }

    return flag;

  }

  /**

    * Check from db connection if at least one of the list of @principals

    * @param user  the user name

    * @param groups  the groups which the use is in

    * @param myPermission  permission type to check for

    */

  public boolean hasPermission(String user, String[]groups, String myPermission) 

                              throws SQLException, Exception

  {

    boolean hasPermission=false;

    String [] userPackage=null;

    int permission =AccessControlList.intValue(myPermission);

    //for the commnad line invocation

    if ((user==null) && (groups==null || groups.length==0))

    {

      return true;

    }

    //create a userpackage including user, public and group member

    userPackage=createUsersPackage(user, groups);

    //if the requested document is access documents and requested permission

    //is "write", the user should have "all" right

    if (isAccessDocument(docId) && (permission == AccessControlInterface.WRITE))

    {

      hasPermission = hasPermission(userPackage,docId, 7);// 7 is all permission

    }//if

    else //in other situation, just check the request permission

    {

      // Check for @permission on @docid for @user and/or @groups

      hasPermission = hasPermission(userPackage,docId, permission);

    }//else

    return hasPermission;

  }

  /**

    * Check from db connection if the users in String array @principals has

    * @permission on @docid* 

    * @param principals, names in userPakcage need to check for @permission

    * @param docid, document identifier to check on

    * @param permission, permission (write or all...) to check for 

    */

  private boolean hasPermission(String [] principals, String docId,

                                           int permission)

                         throws SQLException

  {

    long startId = TOPLEVELSTARTNODEID;// this is for top level, so startid is 0

    try 

    {

      //first, if there is a docid owner in user package, return true

      //because doc owner has all permssion 

      if (containDocumentOwner(principals, docId))

      {

          return true;

      }

      //If there is no owner in user package, checking the table

      //check perm_order

      if (isAllowFirst(principals, docId, startId))

      {

        if (hasExplicitDenyRule(principals, docId, permission, startId))

        {

          //if it is allowfirst and has deny rule(either explicit )

          //deny access

          return false;

        }//if

        else if ( hasAllowRule(principals, docId, permission, startId))

        {

          //if it is allowfirst and hasn't deny rule and has allow rule

          //allow access

          return true;

        }//else if

        else

        {

          //other situation deny access

          return false;

        }//else

     }//if isAllowFirst

     else //denyFirst

     {

       if (hasAllowRule(principals, docId, permission, startId))

       {

         //if it is denyFirst and has allow rule, allow access

         return true;

       }

       else

       {

         //if it is denyfirst but no allow rule, deny access

         return false;

       }

     }//else denyfirst

    }//try

    catch (Exception e)

    {

      MetaCatUtil.debugMessage("There is a exception in hasPermission method: "

                         +e.getMessage(), 50);

    }

    return false;

  }//hasPermission

  /**

   * The method to determine of a node can be access by a user just by subtree

   * access control

   */

  public boolean hasPermissionForSubTreeNode(String user, String[] groups,

                                             String myPermission, long nodeId)

                                             throws McdbException

  {

    boolean flag = true;

    // Get unaccessble subtree for this user

    Hashtable unaccessableSubTree = hasUnaccessableSubTree(user, groups, 

                                                           myPermission);

    Enumeration en = unaccessableSubTree.elements();

    while (en.hasMoreElements())

    {

      SubTree tree = (SubTree)en.nextElement();

      long start = tree.getStartNodeId();

      long stop  = tree.getEndNodeId();

      // nodeid in unaccessablesubtree, return false

      if ( nodeId >= start && nodeId <= stop)

      {

        flag = false;

        break;

      }

    }

    return flag;

  }

  /**

   * This method will return a hasTable of subtree which user doesn't has the 

   * permssion to access

   * @param user  the user name

   * @param groups  the groups which the use is in

   * @param myPermission  permission type to check for

   */

  public Hashtable hasUnaccessableSubTree(String user, String[] groups, 

                                       String myPermission) throws McdbException

  {

    Hashtable resultUnaccessableSubTree = new Hashtable();

    String [] principals=null;

    int permission =AccessControlList.intValue(myPermission);

    //for the commnad line invocation return null(no unaccessable subtree)

    if ((user==null) && (groups==null || groups.length==0))

    {

      return resultUnaccessableSubTree;

    }

    //create a userpackage including user, public and group member

    principals=createUsersPackage(user, groups);

    //for the document owner return null(no unaccessable subtree)

    try

    {

      if (containDocumentOwner(principals, docId))

      {

       return resultUnaccessableSubTree;

      }

    }

    catch (SQLException ee)

    {

      throw new McdbException(ee);

    }

    // go through every subtree which has access control

    for (int i = 0; i< subTreeList.size(); i++)

    {

      SubTree tree = (SubTree)subTreeList.elementAt(i);

      long startId = tree.getStartNodeId();

        try

        {

          if (isAllowFirst(principals, docId, startId))

          {

            if (hasExplicitDenyRule(principals, docId, permission, startId ))

            {

             //if it is allowfirst and has deny rule

              // put the subtree into unaccessable vector

              if (!resultUnaccessableSubTree.containsKey(new Long(startId)))

              {

                resultUnaccessableSubTree.put(new Long(startId), tree);

              }

            }//if

            else if ( hasAllowRule(principals, docId, permission, startId))

            {

              //if it is allowfirst and hasn't deny rule and has allow rule

              //allow access do nothing

            }//else if

            else

            {

              //other situation deny access

              if (!resultUnaccessableSubTree.containsKey(new Long(startId)))

              {

                resultUnaccessableSubTree.put(new Long(startId), tree);

              }

            }//else

          }//if isAllowFirst

          else //denyFirst

          {

            if (hasAllowRule(principals, docId, permission,startId))

            {

              //if it is denyFirst and has allow rule, allow access, do nothing

            }

            else

            {

              //if it is denyfirst but no allow rule, deny access

              // add into vector

              if (!resultUnaccessableSubTree.containsKey(new Long(startId)))

              {

                resultUnaccessableSubTree.put(new Long(startId), tree);

              }

            }

          }//else denyfirst

        }//try

        catch( Exception e)

        {

          MetaCatUtil.debugMessage("error in PermissionControl.has" +

                                   "UnaccessableSubTree "+e.getMessage(), 30);

          throw new McdbException(e);

        }

    }//for

    // merge the subtree if a subtree is another subtree'subtree    

    resultUnaccessableSubTree = mergeEquivalentSubtree(resultUnaccessableSubTree);

    return resultUnaccessableSubTree;

  }//hasUnaccessableSubtree

  /* 

   * A method to merge nested subtree into bigger one. For example subtree b

   * is a subtree of subtree a. And user doesn't have read permission for both

   * so we only use subtree a is enough.

   */

  private Hashtable mergeEquivalentSubtree(Hashtable unAccessSubTree)

  {

    Hashtable newSubTreeHash = new Hashtable();

    boolean   needDelete = false;

    // check the parameters

    if (unAccessSubTree == null || unAccessSubTree.isEmpty())

    {

      return newSubTreeHash;

    }

    else

    {

      // look every subtree start point and stop point, to see if it is embedded

      // in another one. If embedded, they are equavelent and we can use bigger

      // one to replace smaller one

      Enumeration en = unAccessSubTree.elements();

      while (en.hasMoreElements())

      {

        SubTree tree    = (SubTree)en.nextElement();

        String  treeId  = tree.getSubTreeId();

        long    startId = tree.getStartNodeId();

        long    endId   = tree.getEndNodeId();

        Enumeration enu = unAccessSubTree.elements();

        while (enu.hasMoreElements())

        {

          SubTree subTree = (SubTree)enu.nextElement();

          String subTreeId= subTree.getSubTreeId();

          long   subTreeStartId = subTree.getStartNodeId();

          long   subTreeEndId   = subTree.getEndNodeId();

          //compare and if the first subtree is a subtree of the second

          // one, set neeDelete true

          if (startId > subTreeStartId && endId < subTreeEndId)

          {

            needDelete = true;

            MetaCatUtil.debugMessage("the subtree: "+ treeId + 

                                     " need to be get rid of from unaccessable"+

                                     " subtree list becuase it is a subtree of"+

                                     " another subtree in the list", 45);

            break;

          }//if

        }//while

        // if not need to delete, put the subtree into hash

        if (!needDelete)

        {

          newSubTreeHash.put(new Long(startId), tree);

        }

        //reset needDelete

        needDelete = false;

      }//while

      return newSubTreeHash;

    }//else

  }

  /**

    * Check if a document id is a access document. Access document need user

    * has "all" permission to access it.

    * @param docId, the document id need to be checked

    */

    private boolean isAccessDocument(String docId) throws SQLException

    {

      //detele the rev number if docid contains it

      docId=MetaCatUtil.getDocIdFromString(docId);

      PreparedStatement pStmt=null;

      DBConnection conn = null;

      int serialNumber = -1;

      try

      {

        //check out DBConnection

        conn=DBConnectionPool.getDBConnection("PermissionControl.isAccessDoc");

        serialNumber=conn.getCheckOutSerialNumber();

        pStmt = conn.prepareStatement("select 'x' from xml_access where " +

                                      "accessfileid like '" + docId +  "'");

        pStmt.execute();

        ResultSet rs = pStmt.getResultSet();

        boolean hasRow = rs.next();

        pStmt.close();

        if(hasRow)

        {

          return true;

        }

      }

      catch(SQLException e)

      {

        throw new SQLException("PermissionControl.isAccessDocument " +

                     "Error checking" +

                     " on document " + docId + ". " + e.getMessage());

      }

      finally

      {

        try

        {

           pStmt.close();

        }

        finally

        {

          DBConnectionPool.returnDBConnection(conn, serialNumber);

        }

      }

      return false;

    }//isAccessDocument

  /**

    * Check if a stirng array contains a given documents' owner

    * @param principals, a string array storing the username, groups name and

    * public.

    * @param docid, the id of given documents 

    */ 

  private boolean containDocumentOwner( String[] principals, String docId)

                    throws SQLException

  {

    int lengthOfArray=principals.length;

    boolean hasRow; 

    PreparedStatement pStmt=null;

    DBConnection conn = null;

    int serialNumber = -1;

    try

    {

      //check out DBConnection

     conn=DBConnectionPool.getDBConnection("PermissionControl.containDocOnwer");

      serialNumber=conn.getCheckOutSerialNumber();

      pStmt = conn.prepareStatement(

                "SELECT 'x' FROM xml_documents " +

                "WHERE docid = ? AND user_owner = ?"); 

      //check every element in the string array too see if it conatains

      //the owner of document

      for (int i=0; i<lengthOfArray; i++)

      {

        // Bind the values to the query

        pStmt.setString(1, docId);

        pStmt.setString(2, principals[i]);

        pStmt.execute();

        ResultSet rs = pStmt.getResultSet();

        hasRow = rs.next();

        if (hasRow) 

        {

          pStmt.close();

          return true;

        }//if    

      }//for

    }//try

    catch (SQLException e) 

    {

        pStmt.close();

        throw new 

        SQLException("PermissionControl.hasPermission(). " +

                     "Error checking ownership for " + principals[0] +

                     " on document #" + docId + ". " + e.getMessage());

    }//catch

    finally

    {

      try

      {

        pStmt.close();

      }

      finally

      {

        DBConnectionPool.returnDBConnection(conn, serialNumber);

      }

    }

    return false; 

  }//containDocumentOwner

  /**

    * Check if the permission order for user at that documents is allowFirst

    * @param principals, list of names of principals to check for 

    * @param docid, document identifier to check for

    */

  private boolean isAllowFirst(String [] principals, String docId, 

                               long startId)

                  throws SQLException, Exception

  {

    int lengthOfArray=principals.length;

    boolean hasRow;

    PreparedStatement pStmt = null;

    DBConnection conn = null;

    int serialNumber = -1;

    String sql = null;

    boolean topLever =false;

    if (startId == TOPLEVELSTARTNODEID)

    {

      //top level

      topLever = true;

      sql = "SELECT perm_order FROM xml_access " +

            "WHERE principal_name= ? AND docid = ? AND startnodeid is NULL";

    }

    else

    {

      //sub tree level

      sql = "SELECT perm_order FROM xml_access " +

            "WHERE principal_name= ? AND docid = ? AND startnodeid = ?";

    }

    try

    {

      //check out DBConnection

      conn=DBConnectionPool.getDBConnection("AccessControlList.isAllowFirst");

      serialNumber=conn.getCheckOutSerialNumber();

      //select permission order from database

      pStmt = conn.prepareStatement(sql);

      //check every name in the array

      for (int i=0; i<lengthOfArray;i++)

      {

        //bind value

        pStmt.setString(1, principals[i]);//user name

        pStmt.setString(2, docId);//docid

        // if subtree, we need set subtree id 

        if (!topLever)

        {

          pStmt.setLong(3, startId);

        }

        pStmt.execute();

        ResultSet rs = pStmt.getResultSet();

        hasRow=rs.next();

        if (hasRow)

        {

          //get the permission order from data base

          String permissionOrder=rs.getString(1);

          //if the permission order is "allowFirst

          if (permissionOrder.equalsIgnoreCase(AccessControlInterface.ALLOWFIRST))

          {

            pStmt.close();

            return true;

          }

          else

          {

            pStmt.close();

            return false;

          }

        }//if

      }//for

    }//try

    catch (SQLException e)

    {

      throw e;

    }

    finally

    {

      try

      {

        pStmt.close();

      }

      finally

      {

        DBConnectionPool.returnDBConnection(conn, serialNumber);

      }

    }

    //if reach here, means there is no permssion record for given names and 

    //docid. So throw a exception.

    throw new Exception("There is no permission record for user"+principals[0]+

                        "at document "+docId);

  }//isAllowFirst

  /**

    * Check if the users array has allow rules for given users, docid and 

    * permission.

    * If it has permission rule and ticket count is greater than 0, the ticket

    * number will decrease one for every allow rule

    * @param principals, list of names of principals to check for 

    * @param docid, document identifier to check for

    * @param permission, the permssion need to check

    */

  private boolean hasAllowRule(String [] principals, String docId, 

                                  int permission, long startId)

                  throws SQLException, Exception

 {

   int lengthOfArray=principals.length;

   boolean allow=false;//initial value is no allow rule

   ResultSet rs;

   PreparedStatement pStmt = null;

   int permissionValue=permission;

   int permissionValueInTable;

   int ticketCount;

   DBConnection conn = null;

   int serialNumber = -1;

   boolean topLever = false;

   String sql = null;

   if (startId == TOPLEVELSTARTNODEID)

   {

     // for toplevel

     topLever = true;

     sql = "SELECT permission FROM xml_access WHERE docid = ? " +  

           "AND principal_name = ? AND perm_type = ? AND startnodeid is NULL";

   }

   else

   {

     topLever =false;

     sql = "SELECT permission FROM xml_access WHERE docid = ? " +  

           "AND principal_name = ? AND perm_type = ? AND startnodeid = ?";

   }

   try

   {

     //check out DBConnection

     conn=DBConnectionPool.getDBConnection("AccessControlList.hasAllowRule");

     serialNumber=conn.getCheckOutSerialNumber();

    //This sql statement will select entry with 

    //begin_time<=currentTime<=end_time in xml_access table

    //If begin_time or end_time is null in table, isnull(begin_time, sysdate)

    //function will assign begin_time=sysdate

    pStmt = conn.prepareStatement(sql);

    //bind docid, perm_type

    pStmt.setString(1, docId);

    pStmt.setString(3, AccessControlInterface.ALLOW);

    // if subtree lever, need to set subTreeId

    if (!topLever)

    {

      pStmt.setLong(4, startId);

    }

    //bind every elenment in user name array

    for (int i=0;i<lengthOfArray; i++)

    {

      pStmt.setString(2, principals[i]);

      pStmt.execute();

      rs=pStmt.getResultSet();

      while (rs.next())//check every entry for one user

      {

        permissionValueInTable=rs.getInt(1);

        //permission is ok  

        //the user have a permission to access the file

        if (( permissionValueInTable & permissionValue )== permissionValue )

        {

           allow=true;//has allow rule entry

        }//if

      }//while

    }//for

   }//try

   catch (SQLException sqlE)

   {

     throw sqlE;

   }

   catch (Exception e)

   {

     throw e;

   }

   finally

   {

     try

     {

       pStmt.close();

     }

     finally

     {

       DBConnectionPool.returnDBConnection(conn, serialNumber);

     }

   }

    return allow;

 }//hasAllowRule

   /**

    * Check if the users array has explicit deny rules for given users, docid 

    * and permission. That means the perm_type is deny and current time is

    * less than end_time and greater than begin time, or no time limit.

    * @param principals, list of names of principals to check for 

    * @param docid, document identifier to check for

    * @param permission, the permssion need to check

    */

  private boolean hasExplicitDenyRule(String [] principals, String docId, 

                                      int permission, long startId)

                  throws SQLException

 {

   int lengthOfArray=principals.length;

   ResultSet rs;

   PreparedStatement pStmt = null;

   int permissionValue=permission;

   int permissionValueInTable;

   DBConnection conn = null;

   int serialNumber = -1;

   String sql = null;

   boolean topLevel = false;

   // decide top level or subtree level

   if (startId == TOPLEVELSTARTNODEID)

   {

     topLevel = true;

     sql = "SELECT permission FROM xml_access WHERE docid = ? " + 

            "AND principal_name = ? AND perm_type = ? AND startnodeid is NULL";

   }

   else

   {

     topLevel = false;

     sql = "SELECT permission FROM xml_access WHERE docid = ? " + 

            "AND principal_name = ? AND perm_type = ? AND startnodeid = ?";

   }

   try

   {

     //check out DBConnection

     conn=DBConnectionPool.getDBConnection("PermissionControl.hasExplicitDeny");

     serialNumber=conn.getCheckOutSerialNumber();

     pStmt = conn.prepareStatement(sql);

    //bind docid, perm_type

    pStmt.setString(1, docId);

    pStmt.setString(3, AccessControlInterface.DENY);

    // subtree level need to set up subtreeid

    if (!topLevel)

    {

      pStmt.setLong(4, startId);

    }

    //bind every elenment in user name array

    for (int i=0;i<lengthOfArray; i++)

    {

      pStmt.setString(2, principals[i]);

      pStmt.execute();

      rs=pStmt.getResultSet();

      while (rs.next())//check every entry for one user

      {

        permissionValueInTable=rs.getInt(1);

        //permission is ok the user doesn't have permission to access the file

        if (( permissionValueInTable & permissionValue )== permissionValue )

        {

           pStmt.close();

           return true;

         }//if

      }//while

    }//for

   }//try

   catch (SQLException e)

   {

     throw e;

   }//catch

   finally

   {

     try

     {

       pStmt.close();

     }

     finally

     {

       DBConnectionPool.returnDBConnection(conn, serialNumber);

     }

   }//finally

   return false;//no deny rule

  }//hasExplicitDenyRule 

  /**

    * Creat a users pakages to check permssion rule, user itself, public and

    * the gourps the user belong will be include in this package

    * @param user, the name of user

    * @param groups, the string array of the groups that user belong to

    */

  private String[] createUsersPackage(String user, String [] groups)

  {

    String [] usersPackage=null;

    int lengthOfPackage;

    if (groups!=null)

    {

      //if gouprs is not null and user is not public, we should create a array 

      //to store the groups and user and public. 

      //So the length of userPackage is the length of group plus two

      if (!user.equalsIgnoreCase(AccessControlInterface.PUBLIC))

      {

        lengthOfPackage=(groups.length)+2;

        usersPackage=new String [lengthOfPackage];

        //the first two elements is user self and public

        usersPackage[0]=user;

        usersPackage[1]=AccessControlInterface.PUBLIC;

        //put groups element from index 0 to lengthOfPackage-3 into userPackage

        //from index 2 to lengthOfPackage-1

        for (int i=2; i<lengthOfPackage; i++)

        {

          usersPackage[i]=groups[i-2];

        } //for

      }//if user!=public

      else//use=public

      {

        lengthOfPackage=(groups.length)+1;

        usersPackage=new String [lengthOfPackage];

        //the first lements is public

        usersPackage[0]=AccessControlInterface.PUBLIC;

        //put groups element from index 0 to lengthOfPackage-2 into userPackage

        //from index 1 to lengthOfPackage-1

        for (int i=1; i<lengthOfPackage; i++)

        {

          usersPackage[i]=groups[i-1];

        } //for

      }//else user=public

    }//if groups!=null

    else

    {

      //because no groups, the userPackage only need two elements

      //one is for user, the other is for public

      if (!user.equalsIgnoreCase(AccessControlInterface.PUBLIC))

      {

        lengthOfPackage=2;

        usersPackage=new String [lengthOfPackage];

        usersPackage[0]=user;

        usersPackage[1]=AccessControlInterface.PUBLIC;

      }//if user!=public

      else //user==public

      {

        //only put public into array

        lengthOfPackage=1;

        usersPackage=new String [lengthOfPackage];

        usersPackage[0]=AccessControlInterface.PUBLIC;

      }

    }//else groups==null

    return usersPackage;

  }//createUsersPackage

  /**

    * This method will return a data set id for given access id.

    * @param accessDocId, the accessDocId which need to be found data set id

   */

  private String getDataSetId(String accessDocId) 

                              throws SQLException

  {

    String dataSetId=null;

    PreparedStatement pStmt=null;

    ResultSet rs=null;

    DBConnection conn=null;

    int serialNumber=-1;

    String query="SELECT docId from xml_relation where subject = ? or "

                                                +"object = ?";

    try

    {

      //check out DBConnection

      conn=DBConnectionPool.getDBConnection("PermissionControl.getDataSetId");

      serialNumber=conn.getCheckOutSerialNumber();

      pStmt=conn.prepareStatement(query);

      //bind the value to query

      pStmt.setString(1, accessDocId);

      pStmt.setString(2, accessDocId);

      //execute the query

      pStmt.execute();

      rs=pStmt.getResultSet();

      //process the result

      if (rs.next()) //There are some records for the data set id for access id

      {

        dataSetId=rs.getString(1);

      }

      else //No data set id for the given access id in xml_relation table

      {

        dataSetId=null;

      }

    }//try

    finally

    {

      try

      {

        pStmt.close();

      }

      finally

      {

        DBConnectionPool.returnDBConnection(conn, serialNumber);

      }

    }

    return dataSetId;

  }//getDataPackageId() 

  /**

    * To create a part of query: "docid like '" +str1+ "', " +"docid like '" 

    * +str2+"'" ... We need to check user, group and public together for the 

    * permission. So we need the principal in an array and according the array

    * to create a part of query which will be used in other methods

    * @param principals, a string array storing the username, groups name and

    * public.

    */

   private String partQueryAboutDocId( String [] principals)

   {

     String partQuery="";

     int lengthOfArray=principals.length;

     for (int i=0;i<(lengthOfArray-1);i++)

     {

        partQuery=partQuery+"docid like '"+principals[i]+"',";

     }

     //the last one dosen't has "'"

     partQuery=partQuery+"docid like '"+principals[(lengthOfArray-1)]+"'";