Metacat

/**

 *  '$RCSfile$'

 *    Purpose: A Class that loads eml-access.xml file containing ACL 

 *             for a metadata document into relational DB

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

 *             National Center for Ecological Analysis and Synthesis

 *    Authors: Jivka Bojilova

 *    Release: @release@

 *

 *   '$Author: tao $'

 *     '$Date: 2002-12-10 14:05:00 -0800 (Tue, 10 Dec 2002) $'

 * '$Revision: 1336 $'

 *

 * 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.io.*;

import java.sql.*;

import java.util.Stack;

import java.util.Vector;

import java.util.Hashtable;

import java.net.URL;

import java.net.MalformedURLException;

import org.xml.sax.Attributes;

import org.xml.sax.InputSource;

import org.xml.sax.ContentHandler;

import org.xml.sax.EntityResolver;

import org.xml.sax.ErrorHandler;

import org.xml.sax.SAXException;

import org.xml.sax.SAXParseException;

import org.xml.sax.XMLReader;

import org.xml.sax.helpers.XMLReaderFactory;

import org.xml.sax.helpers.DefaultHandler;

/** 

 * A Class that loads eml-access.xml file containing ACL for a metadata

 * document into relational DB. It extends DefaultHandler class to handle

 * SAX parsing events when processing the XML stream.

 */

public class AccessControlList extends DefaultHandler {

  private static final int CHMOD = 1;

  private static final int WRITE = 2;

  private static final int READ = 4;

  private static final int ALL = 7;

  private static final String ALLOWFIRST="allowFirst";

  private static final String DENYFIRST="denyFirst";

  private static final String ALLOW="allow";

  private static final String DENY="deny";

  private static final String PUBLIC="public";

  private static String sysdate = MetaCatUtil.dbAdapter.getDateTimeFunction();

  private static String isnull = MetaCatUtil.dbAdapter.getIsNULLFunction();

  private DBConnection connection;

  private String parserName;

  private Stack elementStack;

  private String server;

  private String sep;

  private boolean	processingDTD;

  private String  user;

  private String[] groups;

  private String  aclid;

  private int     rev;

  private String 	docname;

  private String 	doctype;

  private String 	systemid;

  private String docurl;

  private Vector resourceURL;

  private Vector resourceID;

  private Vector principal;

  private int    permission;

  private String permType;

  private String permOrder;

//  private String publicAcc;

  private String beginTime;

  private String endTime;

  private int    ticketCount;

  private int    serverCode = 1;

  private Vector aclObjects = new Vector();

  private boolean instarttag = true;

  private String tagName = "";

  /**

   * Construct an instance of the AccessControlList class.

   * It is used by the permission check up from DBQuery or DocumentImpl

   * and from "getaccesscontrol" action

   *

   * @param conn the JDBC connection where acl info is get

   */

  public AccessControlList(DBConnection conn) throws SQLException

  {

    this.connection = conn;

  }

  /**

   * Construct an instance of the AccessControlList class.

   * It parse acl file and loads acl data into db connection.

   *

   * @param conn the JDBC connection where acl data are loaded

   * @param aclid the Accession# of the document with the acl data

   * @param acl the acl file containing acl data

   * @param user the user connected to MetaCat servlet and owns the document

   * @param groups the groups to which user belongs

   * @param serverCode the serverid from xml_replication on which this document

   *        resides.

   */

  public AccessControlList(DBConnection conn, String aclid, //Reader acl,

                           String user, String[] groups, int serverCode)

                  throws SAXException, IOException, McdbException

  {

    String parserName = MetaCatUtil.getOption("saxparser");

    this.server = MetaCatUtil.getOption("server");

    this.sep = MetaCatUtil.getOption("accNumSeparator");

    this.connection = conn;

    this.parserName = parserName;

    this.processingDTD = false;

    this.elementStack = new Stack();

    this.user = user;

    this.groups = groups;

    this.aclid = aclid;

    this.resourceURL = new Vector();

    this.resourceID = new Vector();

    this.principal = new Vector();

    this.permission = 0;

    this.ticketCount = 0;

  //  this.publicAcc = null;

    this.serverCode = serverCode;

    // read the access file from db connection

    DocumentImpl acldoc = new DocumentImpl(aclid);

    String acl = acldoc.toString();

    this.rev = acldoc.getRev();

    // Initialize the parse

    XMLReader parser = initializeParser();

    // parse the access file and write the info to xml_access

    parser.parse(new InputSource(new StringReader(acl)));

  }

// NOT USED

//  /**

//   * Construct an instance of the AccessControlList class.

//   * It parses eml-access file and loads acl data into db connection.

//   * It is used from command line execution.

//   *

//   * @param conn the JDBC connection where acl data are loaded

//   * @param docid the Accession# of the document with the acl data

//   * @param aclfilename the name of acl file containing acl data

//   * @param user the user connected to MetaCat servlet and owns the document

//   * @param groups the groups to which user belongs

//   */

//  public AccessControlList( Connection conn, String aclid, String aclfilename,

//                           String user, String[] groups )

//                  throws SAXException, IOException, McdbException

//  {

//    this(conn, aclid, new FileReader(new File(aclfilename).toString()), 

//         user, groups, 1);

//  }

  /* Set up the SAX parser for reading the XML serialized ACL */

  private XMLReader initializeParser() throws SAXException 

  {

    XMLReader parser = null;

    // Get an instance of the parser

    parser = XMLReaderFactory.createXMLReader(parserName);

    // Turn off validation

    parser.setFeature("http://xml.org/sax/features/validation", true);

    // Set Handlers in the parser

    // Set the ContentHandler to this instance

    parser.setContentHandler((ContentHandler)this);

    // make a DBEntityResolver instance

    // Set the EntityReslover to DBEntityResolver instance

    EntityResolver eresolver = new DBEntityResolver(connection,this,null);

    parser.setEntityResolver((EntityResolver)eresolver);

    // Set the ErrorHandler to this instance

    parser.setErrorHandler((ErrorHandler)this);

    return parser; 

  }

  /**

   * Callback method used by the SAX Parser when beginning of the document

   */

  public void startDocument() throws SAXException 

  {

    //delete all previously submitted permissions @ relations

    //this happens only on UPDATE of the access file

    try {

      this.aclObjects = getACLObjects(aclid);

      //delete all permissions for resources related to @aclid if any

      if ( aclid != null ) {

        deletePermissionsForRelatedResources(aclid);

      }

    } catch (SQLException sqle) {

      throw new SAXException(sqle);

    }

  }

  /**

   * Callback method used by the SAX Parser when the start tag of an 

   * element is detected. Used in this context to parse and store

   * the acl information in class variables.

   */

  public void startElement (String uri, String localName, 

                            String qName, Attributes atts) 

         throws SAXException 

  {

    instarttag = true;

    if(localName.equals("allow"))

    {

      tagName = "allow";

    }

    else if(localName.equals("deny"))

    {

      tagName = "deny";

    }

    BasicNode currentNode = new BasicNode(localName);

    if (atts != null) {

      int len = atts.getLength();

      for (int i = 0; i < len; i++) {

        currentNode.setAttribute(atts.getLocalName(i), atts.getValue(i));

      }

    }

    if ( currentNode.getTagName().equals("acl") ) {

      permOrder = currentNode.getAttribute("order");

    //  publicAcc = currentNode.getAttribute("public");

    }

    elementStack.push(currentNode); 

  }

  /**

   * Callback method used by the SAX Parser when the text sequences of an 

   * xml stream are detected. Used in this context to parse and store

   * the acl information in class variables.

   */ 

  public void characters(char ch[], int start, int length)

         throws SAXException 

  {

    if(!instarttag)

    {

      return;

    }

    String inputString = new String(ch, start, length);

    inputString = inputString.trim(); 

    //System.out.println("==============inputString: " + inputString);

    BasicNode currentNode = (BasicNode)elementStack.peek(); 

    String currentTag = currentNode.getTagName();

      if (currentTag.equals("principal")) {

        principal.addElement(inputString);

      } else if (currentTag.equals("permission")) {

        if ( inputString.trim().toUpperCase().equals("READ") ) {

          permission = permission | READ;

        } else if ( inputString.trim().toUpperCase().equals("WRITE") ) {

          permission = permission | WRITE;

        } else if ( inputString.trim().toUpperCase().equals("CHANGEPERMISSION")) 

        {

          permission = permission | CHMOD;

        } else if ( inputString.trim().toUpperCase().equals("ALL") ) {

          permission = permission | ALL;

        }/*else{

          throw new SAXException("Unknown permission type: " + inputString);

        }*/

      } else if ( currentTag.equals("startDate") && beginTime == null ) {

        beginTime = inputString.trim();

      } else if ( currentTag.equals("stopDate") && endTime == null) {

        endTime = inputString.trim();

      } else if (currentTag.equals("ticketCount") && ticketCount == 0 ) {

        try {

          ticketCount = (new Integer(inputString.trim())).intValue();

        } catch (NumberFormatException nfe) {

          throw new SAXException("Wrong integer format for:" + inputString);

        }

      }

  }

  /**

   * Callback method used by the SAX Parser when the end tag of an 

   * element is detected. Used in this context to parse and store

   * the acl information in class variables.

   */

  public void endElement (String uri, String localName, String qName)

         throws SAXException 

  {

    instarttag = false;

    BasicNode leaving = (BasicNode)elementStack.pop();

    String leavingTagName = leaving.getTagName();

    if ( leavingTagName.equals("allow") ||

         leavingTagName.equals("deny")    ) {

      if ( permission > 0 ) {

        // insert into db calculated permission for the list of principals

        try {

          // go through the objects in xml_relation about this acl doc

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

            // docid of the current object

            String docid = (String)aclObjects.elementAt(i); 

            DocumentIdentifier docID = new DocumentIdentifier(docid);

            docid = docID.getIdentifier();

            insertPermissions(docid,leavingTagName);

          }

          // if acl is not in object list

          //should insert permission for aclid itself into database

          /*if (!aclObjects.contains(aclid))

          {

            DocumentIdentifier aclIdItself = new DocumentIdentifier(aclid);

            String aclIdString = aclIdItself.getIdentifier();

            insertPermissions(aclIdString,leavingTagName);

          }*/

        } catch (SQLException sqle) {

          throw new SAXException(sqle);

        } catch (Exception e) {

          throw new SAXException(e);

        }

      }

      // reset the allow/deny permission

      principal = new Vector();

      permission = 0;

      beginTime = null;

      endTime = null;

      ticketCount = 0;

    }

  }

  /** 

    * SAX Handler that receives notification of DOCTYPE. Sets the DTD.

    * @param name name of the DTD

    * @param publicId Public Identifier of the DTD

    * @param systemId System Identifier of the DTD

    */

  public void startDTD(String name, String publicId, String systemId) 

              throws SAXException {

    docname = name;

    doctype = publicId;

    systemid = systemId;

  }

  /** 

   * SAX Handler that receives notification of the start of entities.

   * @param name name of the entity

   */

  public void startEntity(String name) throws SAXException {

    if (name.equals("[dtd]")) {

      processingDTD = true;

    }

  }

  /** 

   * SAX Handler that receives notification of the end of entities.

   * @param name name of the entity

   */

  public void endEntity(String name) throws SAXException {

    if (name.equals("[dtd]")) {

      processingDTD = false;

    }

  }

  /**

   * Get the document name.

   */

  public String getDocname() {

    return docname;

  }

  /**

   * Get the document processing state.

   */

  public boolean processingDTD() {

    return processingDTD;

  }

  /* Get all objects associated with @aclid from db.*/

  private Vector getACLObjects(String aclid) 

          throws SQLException 

  {

    Vector aclObjects = new Vector();

    DBConnection conn = null;

    int serialNumber = -1;

    PreparedStatement pstmt = null;

    try

    {

      //get connection from DBConnectionPool

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

      serialNumber=conn.getCheckOutSerialNumber();

      // delete all acl records for resources related to @aclid if any

      pstmt = conn.prepareStatement(

                             "SELECT object FROM xml_relation " +

                             "WHERE subject = ? ");

      pstmt.setString(1,aclid);

      pstmt.execute();

      ResultSet rs = pstmt.getResultSet();

      boolean hasRows = rs.next();

      while (hasRows) {

        aclObjects.addElement(rs.getString(1));

        hasRows = rs.next();

      }//whil

    }

    catch (SQLException e)

    {

      throw e;

    }

    finally

    {

      try

      {

        pstmt.close();

      }

      finally

      {

        //retrun DBConnection

        DBConnectionPool.returnDBConnection(conn,serialNumber);

      }

    }

    return aclObjects;

  }

  /* Delete from db all permission for resources related to @aclid if any.*/

  private void deletePermissionsForRelatedResources(String aclid) 

          throws SQLException 

  {

    //DBConnection conn = null;

    //int serialNumber = -1;

    Statement stmt = null;

    try

    {

      //check out DBConenction

      //conn=DBConnectionPool.getDBConnection("AccessControlList.deltePerm");

      //serialNumber=conn.getCheckOutSerialNumber();

      // delete all acl records for resources related to @aclid if any

      stmt = connection.createStatement();

      // Increase DBConnection usage count

      connection.increaseUsageCount(1);

      stmt.execute("DELETE FROM xml_access WHERE accessfileid = '" + aclid 

                                                                      + "'");

      //increase usageCount!!!!!!

      //conn.increaseUsageCount(1);

    }

    catch (SQLException e)

    {

      throw e;

    }

    finally

    {

      stmt.close();

      //retrun DBConnection

      //DBConnectionPool.returnDBConnection(conn,serialNumber);

    }

  }

  /* Insert into db calculated permission for the list of principals 

   * The DBConnection it is use is class field. Because we want to keep rollback

   * features and it need use same connection

  */

  private void insertPermissions(String docid, String permType ) 

                                            throws SQLException 

  {

    PreparedStatement pstmt = null;

    //DBConnection conn = null;

    //int serialNumber = -1;

    try {

      //Check out DBConnection

      //conn=DBConnectionPool.getDBConnection("AccessControlList.insertPerm");

      //serialNumber=conn.getCheckOutSerialNumber();

      pstmt = connection.prepareStatement(

              "INSERT INTO xml_access " + 

              "(docid, principal_name, permission, perm_type, perm_order," +

              "begin_time,end_time,ticket_count, accessfileid) VALUES " +

              "(?,?,?,?,?,to_date(?,'mm/dd/yy'),to_date(?,'mm/dd/yy'),?,?)");

      // Increase DBConnection usage count

      connection.increaseUsageCount(1);

      // Bind the values to the query

      pstmt.setString(1, docid);

      pstmt.setInt(3, permission);

      pstmt.setString(4, permType);

      pstmt.setString(5, permOrder);

      pstmt.setString(6, beginTime);

      pstmt.setString(7, endTime);

      pstmt.setString(9, aclid);

      if ( ticketCount > 0 ) {

        pstmt.setString(8, "" + ticketCount);

      } else {

        pstmt.setString(8, null);

      }

      //incrase usagecount for DBConnection

      //conn.increaseUsageCount(1);

      String prName;

      for ( int j = 0; j < principal.size(); j++ ) {

        prName = (String)principal.elementAt(j);

        pstmt.setString(2, prName);

        pstmt.execute();

      /*    

        // check if there are conflict with permission's order

        String permOrderOpos = permOrder;

        int perm = getPermissions(permission, prName, docid, permOrder);

        if (  perm != 0 ) {

          if ( permOrder.equals("allowFirst") ) {

            permOrderOpos = "denyFirst";

          } else if ( permOrder.equals("denyFirst") ) {

            permOrderOpos = "allowFirst";

          }

          throw new SQLException("Permission(s) " + txtValue(perm) + 

                    " for \"" + prName + "\" on document #" + docid +

                    " has/have been used with \"" + permOrderOpos + "\"");

        }

      */

      }

      pstmt.close();

    } catch (SQLException e) {

      throw new 

      SQLException("AccessControlList.insertPermissions(): " + e.getMessage());

    }

    finally

    {

      pstmt.close();

      //return the DBConnection

      //DBConnectionPool.returnDBConnection(conn, serialNumber);

    }

  }

  /* Get permissions with permission order different than @permOrder. */

  private int getPermissions(int permission, String principal,

                             String docid, String permOrder)

          throws SQLException 

  {

    PreparedStatement pstmt = null;

    DBConnection conn = null;

    int serialNumber = -1;

    try

    {

      //check out DBConnection

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

      serialNumber=conn.getCheckOutSerialNumber();

      pstmt = conn.prepareStatement(

            "SELECT permission FROM xml_access " +

            "WHERE docid = ? " +

            "AND principal_name = ? " +

            "AND perm_order NOT = ?");

      pstmt.setString(1, docid);

      pstmt.setString(2, principal);

      pstmt.setString(3, permOrder);

      pstmt.execute();

      ResultSet rs = pstmt.getResultSet();

      boolean hasRow = rs.next();

      int perm = 0;

      while ( hasRow ) {

        perm = rs.getInt(1);

        perm = permission & perm;

        if ( perm != 0 ) {

          pstmt.close();

          return perm;

        }

        hasRow = rs.next();

      }

    }//try

    catch (SQLException e)

    {

      throw e;

    }

    finally

    {

      try

      {

        pstmt.close();

      }

      finally

      {

        DBConnectionPool.returnDBConnection(conn, serialNumber);

      }

    }

    return 0;

  }

  /* Get the int value of READ, WRITE or ALL. */

  private static int intValue ( String permission )

  {

    if ( permission.equals("READ") ) {

      return READ;

    } else if ( permission.equals("WRITE") ) {

      return WRITE;

    } else if ( permission.equals("ALL") ) {

      return ALL;

    }

    return -1;

  }

  /* Get the text value of READ, WRITE or ALL. */

  private String txtValue ( int permission )

  {

    StringBuffer txtPerm = new StringBuffer("\"");

    if ( (permission & READ) != 0 ) {

      txtPerm.append("read");

    } 

    if ( (permission & WRITE) != 0 ) {

      if ( txtPerm.length() > 0 ) txtPerm.append(",");

      txtPerm.append("write");

    }

    if ( (permission & ALL) != 0 ) {

      if ( txtPerm.length() > 0 ) txtPerm.append(",");

      txtPerm.append("all");

    }

    return txtPerm.append("\"").toString();

  }

  /**

    * 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 static 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("AccessControlList.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("AccessControlList.isAccessDocument " +

                     "Error checking" +

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

      }

      finally

      {

        try

        {

           pStmt.close();

        }

        finally

        {

          DBConnectionPool.returnDBConnection(conn, serialNumber);

        }

      }

      return false;

    }//isAccessDocument

  /**

    * 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)]+"'";

     return partQuery;

   }

  /**

    * 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 static 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("AccessControlList.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("AccessControlList.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 static boolean isAllowFirst(String [] principals, String docId)

                  throws SQLException, Exception

  {

    int lengthOfArray=principals.length;

    boolean hasRow;

    PreparedStatement pStmt = null;

    DBConnection conn = null;

    int serialNumber = -1;

    try

    {

      //check out DBConnection

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

      serialNumber=conn.getCheckOutSerialNumber();

      //select permission order from database

      pStmt = conn.prepareStatement(

                "SELECT perm_order FROM xml_access " +

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

      //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

        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(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 static boolean hasAllowRule(String [] principals, String docId, 

                                  String permission)

                  throws SQLException, Exception

 {

   int lengthOfArray=principals.length;

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

   ResultSet rs;

   PreparedStatement pStmt = null;

   int permissionValue=intValue(permission);

   int permissionValueInTable;

   int ticketCount;

   DBConnection conn = null;

   int serialNumber = -1;

   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(

                "SELECT permission, ticket_count " +

                "FROM xml_access " +

                "WHERE docid = ? " + 

                "AND principal_name = ? " +

                "AND perm_type = ? " +

                "AND " + sysdate + 

                " BETWEEN " + isnull + "(begin_time," + sysdate + ") " +

                     "AND " + isnull + "(end_time," + sysdate + ")");

    //bind docid, perm_type

    pStmt.setString(1, docId);

    pStmt.setString(3, ALLOW);

    //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);

        ticketCount=rs.getInt(2);

        //permission is ok and ticketcount geat than 0 or ticket is null, 

        //the user have a permission to access the file

        if ((( permissionValueInTable & permissionValue )== permissionValue )

              && (rs.wasNull()||ticketCount > 0))

        {

           //ticket count should minus one 

           //ticketCount isnot null and greater than 0, order is allowfirst

           if (!rs.wasNull() && ticketCount>0 && isAllowFirst(principals,docId))

           {

              decreaseNumberOfAccess(permissionValueInTable, principals[i],

                                              docId, ALLOW, ALLOWFIRST);

            }

           //ticketCount isnot null and greater than 0, order is not allowfirst

           if (!rs.wasNull() &&ticketCount>0 && !isAllowFirst(principals,docId))

           {

              decreaseNumberOfAccess(permissionValueInTable, principals[i],

                                              docId, ALLOW, DENYFIRST);

           }

           allow=true;//has allow rule entry