src/JAVA/classes/org/openafs/jafs/Group.java

   1 /*
   2  * @(#)Group.java       1.0 6/29/2001
   3  *
   4  * Copyright (c) 2001 International Business Machines Corp.
   5  * All rights reserved.
   6  *
   7  * This software has been released under the terms of the IBM Public
   8  * License.  For details, see the LICENSE file in the top-level source
   9  * directory or online at http://www.openafs.org/dl/license10.html
  10  *
  11  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  12  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  13  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  14  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR
  15  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  16  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  17  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  18  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  19  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  20  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  21  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  22  */
  23
  24 package org.openafs.jafs;
  25
  26 import java.util.Vector;
  27 import java.util.Enumeration;
  28 import java.util.ArrayList;
  29 import java.io.Serializable;
  30
  31 /**
  32  * An abstract representation of an AFS group.  It holds information about
  33  * the group, such as what groups it owns.<BR><BR>
  34  *
  35  * Constructing an instance of a <code>Group</code> does not mean an actual
  36  * AFS group is created in a cell -- usually a <code>Group</code>
  37  * object is a representation of an already existing AFS group.  If,
  38  * however, the <code>Group</code> is constructed with the name of a
  39  * group that does not exist in the cell represented by the provided
  40  * <code>Cell</code>, a new group with that name can be
  41  * created in that cell by calling the {@link #create(String, int)} or
  42  * {@link #create(String)} method. If such a group does already exist when
  43  * one of these methods is called, an exception will be thrown.<BR><BR>
  44  *
  45  * Each <code>Group</code> object has its own individual set of
  46  * <code>Group</code>s that it owns and <code>User</code>s that belong
  47  * to it.  These represents the properties and attributes
  48  * of an actual AFS group.
  49  * <BR><BR>
  50  *
  51  * <!--Information on how member values are set-->
  52  *
  53  * Associated with an AFS group are many attributes, such as whether or not
  54  * who is allowed to list the members of this group. The <code>Group</code>
  55  * class has many "set" methods to indicate values for these attributes (i.e.
  56  * {@link #setListMembership(int)}.  However, in order for these values to be
  57  * written to the actual AFS group, the {@link #flushInfo()} method needs to
  58  * be called.  This writes all user attributes set through this API to AFS.
  59  * This is done to minimize calls through JNI.<BR><BR>
  60  *
  61  * <!--Example of how to use class-->
  62  * The following is a simple example of how to construct and use a
  63  * <code>Group</code> object.  It lists the name and owner of a specified
  64  * group.
  65  *
  66  * <PRE>
  67  * import org.openafs.jafs.Cell;
  68  * import org.openafs.jafs.AFSException;
  69  * import org.openafs.jafs.Partition;
  70  * import org.openafs.jafs.Group;
  71  * ...
  72  * public class ...
  73  * {
  74  *   ...
  75  *   private Cell cell;
  76  *   private Group group;
  77  *   ...
  78  *   public static void main(String[] args) throws Exception
  79  *   {
  80  *     String username   = arg[0];
  81  *     String password   = arg[1];
  82  *     String cellName   = arg[2];
  83  *     String groupName  = arg[3];
  84  *
  85  *     token = new Token(username, password, cellName);
  86  *     cell   = new Cell(token);
  87  *     group = new Group(groupName, cell);
  88  *
  89  *     System.out.println("Owner of group " + group.getName() + " is "
  90  *                        + group.getOwnerName());
  91  *     ...
  92  *   }
  93  *   ...
  94  * }
  95  * </PRE>
  96  *
  97  */
  98 public class Group implements PTSEntry, Serializable, Comparable
  99 {
 100   /**
 101    * Only the owner of the group has access
 102    */
 103   public static final int GROUP_OWNER_ACCESS = 0;
 104   /**
 105    * Members of the group have access
 106    */
 107   public static final int GROUP_GROUP_ACCESS = 1;
 108   /**
 109    * Any user has access
 110    */
 111   public static final int GROUP_ANYUSER_ACCESS = 2;
 112
 113   protected Cell cell;
 114   protected long cellHandle;
 115   protected String name;
 116
 117   protected int membershipCount;
 118   protected int nameUID;
 119   protected int ownerUID;
 120   protected int creatorUID;
 121
 122   protected String owner;
 123   protected String creator;
 124
 125   /**
 126    * who is allowed to execute PTS examine for this group.  Valid values are:
 127    * <ul>
 128    * <li>{@link #GROUP_OWNER_ACCESS} -- only the owner has permission</li>
 129    * <li>{@link #GROUP_GROUP_ACCESS}
 130    *     -- only members of the group have permission</li>
 131    * <li>{@link #GROUP_ANYUSER_ACCESS} -- any user has permission</li></ul>
 132    */
 133   protected int listStatus;
 134   /**
 135    * who is allowed to execute PTS examine for this group.  Valid values are:
 136    * <ul>
 137    * <li>{@link #GROUP_OWNER_ACCESS} -- only the owner has permission</li>
 138    * <li>{@link #GROUP_GROUP_ACCESS}
 139    *     -- only members of the group have permission</li>
 140    * <li>{@link #GROUP_ANYUSER_ACCESS} -- any user has permission</li></ul>
 141    */
 142   protected int listGroupsOwned;
 143   /**
 144    * who is allowed to execute PTS listowned for this group.  Valid values are:
 145    * <ul>
 146    * <li>{@link #GROUP_OWNER_ACCESS} -- only the owner has permission</li>
 147    * <li>{@link #GROUP_GROUP_ACCESS}
 148    *     -- only members of the group have permission</li>
 149    * <li>{@link #GROUP_ANYUSER_ACCESS} -- any user has permission</li></ul>
 150    */
 151   protected int listMembership;
 152   /**
 153    * who is allowed to execute PTS adduser for this group.   Valid values are:
 154    * <ul>
 155    * <li>{@link #GROUP_OWNER_ACCESS} -- only the owner has permission</li>
 156    * <li>{@link #GROUP_GROUP_ACCESS}
 157    *     -- only members of the group have permission</li>
 158    * <li>{@link #GROUP_ANYUSER_ACCESS} -- any user has permission</li></ul>
 159    */
 160   protected int listAdd;
 161   /**
 162    * who is allowed to execute PTS removeuser for this group.   Valid
 163    * values are:
 164    * <ul>
 165    * <li>{@link #GROUP_OWNER_ACCESS} -- only the owner has permission</li>
 166    * <li>{@link #GROUP_GROUP_ACCESS}
 167    *     -- only members of the group have permission</li>
 168    * <li>{@link #GROUP_ANYUSER_ACCESS} -- any user has permission</li></ul>
 169    */
 170   protected int listDelete;
 171
 172   protected ArrayList members;
 173   protected ArrayList memberNames;
 174   protected ArrayList groupsOwned;
 175   protected ArrayList groupsOwnedNames;
 176
 177   /**
 178    * Whether or not the information fields of this group have been filled.
 179    */
 180   protected boolean cachedInfo;
 181
 182   /**
 183    * Constructs a new <code>Group</code> object instance given the name
 184    * of the AFS group and the AFS cell, represented by
 185    * <CODE>cell</CODE>, to which it belongs.   This does not actually
 186    * create a new AFS group, it just represents one.
 187    * If <code>name</code> is not an actual AFS group, exceptions
 188    * will be thrown during subsequent method invocations on this
 189    * object, unless the {@link #create(String, int)} or {@link #create(String)}
 190    * method is explicitly called to create it.
 191    *
 192    * @param name      the name of the group to represent
 193    * @param cell       the cell to which the group belongs.
 194    * @exception AFSException      If an error occurs in the native code
 195    */
 196   public Group( String name, Cell cell ) throws AFSException
 197   {
 198     this.name = name;
 199     this.cell = cell;
 200     cellHandle = cell.getCellHandle();
 201
 202     members = null;
 203     memberNames = null;
 204     groupsOwned = null;
 205     groupsOwnedNames = null;
 206     cachedInfo = false;
 207   }
 208
 209   /**
 210    * Constructs a new <code>Group</code> object instance given the name
 211    * of the AFS group and the AFS cell, represented by
 212    * <CODE>cell</CODE>, to which it belongs.   This does not actually
 213    * create a new AFS group, it just represents one.
 214    * If <code>name</code> is not an actual AFS group, exceptions
 215    * will be thrown during subsequent method invocations on this
 216    * object, unless the {@link #create(String, int)} or {@link #create(String)}
 217    * method is explicitly called to create it.   Note that if the process
 218    * doesn't exist and <code>preloadAllMembers</code> is true, an exception
 219    * will be thrown.
 220    *
 221    * <P> This constructor is ideal for point-in-time representation and
 222    * transient applications. It ensures all data member values are set and
 223    * available without calling back to the filesystem at the first request
 224    * for them.  Use the {@link #refresh()} method to address any coherency
 225    * concerns.
 226    *
 227    * @param name               the name of the group to represent
 228    * @param cell               the cell to which the group belongs.
 229    * @param preloadAllMembers  true will ensure all object members are
 230    *                           set upon construction;
 231    *                           otherwise members will be set upon access,
 232    *                           which is the default behavior.
 233    * @exception AFSException      If an error occurs in the native code
 234    * @see #refresh
 235    */
 236   public Group( String name, Cell cell, boolean preloadAllMembers )
 237       throws AFSException
 238   {
 239     this(name, cell);
 240     if (preloadAllMembers) refresh(true);
 241   }
 242
 243   /**
 244    * Creates a blank <code>Group</code> given the cell to which the group
 245    * belongs. Other methods cvan then be used to fill the fields of this
 246    * blank object.
 247    *
 248    * @exception AFSException      If an error occurs in the native code
 249    * @param cell       the cell to which the group belongs.
 250    */
 251   Group( Cell cell ) throws AFSException
 252   {
 253     this( null, cell );
 254   }
 255
 256   /*-------------------------------------------------------------------------*/
 257
 258   /**
 259    * Creates the PTS entry for a new group in this cell.  Automatically assigns
 260    * a group id.
 261    *
 262    * @param ownerName      the owner of this group
 263    */
 264   public void create( String ownerName ) throws AFSException
 265   {
 266     this.create( ownerName, 0 );
 267   }
 268
 269   /**
 270    * Creates the PTS entry for a new group in this cell.
 271    *
 272    * @param ownerName      the owner of this group
 273    * @param gid       the group id to assign to the new group
 274    * @exception AFSException  If an error occurs in the native code
 275    */
 276   public void create( String ownerName, int gid ) throws AFSException
 277   {
 278     Group.create( cell.getCellHandle(), name, ownerName, gid );
 279   }
 280
 281   /**
 282    * Deletes the PTS entry for a group in this cell. Deletes this group
 283    * from the membership list of the user that belonged to it, but does not
 284    * delete the groups owned by this group.  Also nullifies the Java object.
 285    *
 286    * @exception AFSException  If an error occurs in the native code
 287    */
 288   public void delete() throws AFSException
 289   {
 290     Group.delete( cell.getCellHandle(), name );
 291
 292     cell = null;
 293     name = null;
 294     owner = null;
 295     creator = null;
 296     members = null;
 297     memberNames = null;
 298     groupsOwned = null;
 299     groupsOwnedNames = null;
 300     try {
 301       finalize();
 302     } catch( Throwable t ) {
 303       throw new AFSException( t.getMessage() );
 304     }
 305   }
 306
 307   /**
 308    * Flushes the current information of this <code>Group</code> object to disk.
 309    * This will update the information of the actual AFS group to match the
 310    * settings that have been modified in this <code>Group</code> object.
 311    * This function must be called before any changes made to the information
 312    * fields of this group will be seen by the AFS system.
 313    *
 314    * @exception AFSException      If an error occurs in the native code
 315    */
 316   public void flushInfo() throws AFSException
 317   {
 318     Group.setGroupInfo( cell.getCellHandle(), name, this );
 319   }
 320
 321   /**
 322    * Add the specified member to this group.
 323    *
 324    * @param userName    the <code>User</code> object to add
 325    * @exception AFSException  If an error occurs in the native code
 326    */
 327   public void addMember( User theUser ) throws AFSException
 328   {
 329     String userName = theUser.getName();
 330
 331     Group.addMember( cell.getCellHandle(), name, userName );
 332
 333     // add to cache
 334     if( memberNames != null ) {
 335       memberNames.add( userName );
 336     }
 337     if( members != null ) {
 338       members.add( new User( userName, cell ) );
 339     }
 340   }
 341
 342   /**
 343    * Remove the specified member from this group.
 344    * @param userName    the <code>User</code> object to remove
 345    * @exception AFSException  If an error occurs in the native code
 346    */
 347   public void removeMember( User theUser ) throws AFSException
 348   {
 349     String userName = theUser.getName();
 350     Group.removeMember( cell.getCellHandle(), name, userName );
 351
 352     // remove from cache
 353     if( memberNames != null ) {
 354       memberNames.remove( memberNames.indexOf(userName) );
 355       memberNames.trimToSize();
 356     }
 357     if( members != null && members.indexOf(theUser) > -1) {
 358       members.remove( members.indexOf(theUser) );
 359       members.trimToSize();
 360     }
 361   }
 362
 363   /**
 364    * Change the owner of this group.
 365    *
 366    * @param ownerName    the new owner <code>User</code> object
 367    * @exception AFSException  If an error occurs in the native code
 368    */
 369   public void changeOwner( User theOwner ) throws AFSException
 370   {
 371     String ownerName = theOwner.getName();
 372
 373     Group.changeOwner( cell.getCellHandle(), name, ownerName );
 374
 375     if( cachedInfo ) {
 376       owner = ownerName;
 377     }
 378   }
 379
 380   /**
 381    * Change the owner of this group.
 382    *
 383    * @param ownerName    the new owner <code>Group</code> object
 384    * @exception AFSException  If an error occurs in the native code
 385    */
 386   public void changeOwner( Group theOwner ) throws AFSException
 387   {
 388     String ownerName = theOwner.getName();
 389     Group.changeOwner( cell.getCellHandle(), name, ownerName );
 390     if( cachedInfo ) {
 391       owner = ownerName;
 392     }
 393   }
 394
 395   /**
 396    * Change the name of this group.
 397    *
 398    * @param newName    the new name for this group
 399    * @exception AFSException  If an error occurs in the native code
 400    */
 401   public void rename( String newName ) throws AFSException
 402   {
 403     Group.rename( cell.getCellHandle(), name, newName );
 404     name = newName;
 405   }
 406
 407   /**
 408    * Refreshes the properties of this Group object instance with values from
 409    * the AFS group it represents.  All properties that have been initialized
 410    * and/or accessed will be renewed according to the values of the AFS group
 411    * this <code>Group</code> object instance represents.
 412    *
 413    * <P>Since in most environments administrative changes can be administered
 414    * from an AFS command-line program or an alternate GUI application, this
 415    * method provides a means to refresh the Java object representation and
 416    * thereby ascertain any possible modifications that may have been made
 417    * from such alternate administrative programs.  Using this method before
 418    * an associated instance accessor will ensure the highest level of
 419    * representative accuracy, accommodating changes made external to the
 420    * Java application space.  If administrative changes to the underlying AFS
 421    * system are only allowed via this API, then the use of this method is
 422    * unnecessary.
 423    *
 424    * @exception AFSException  If an error occurs in the native code
 425    */
 426   public void refresh() throws AFSException
 427   {
 428       refresh(false);
 429   }
 430
 431   /**
 432    * Refreshes the properties of this Group object instance with values from
 433    * the AFS group it represents.  If <CODE>all</CODE> is <CODE>true</CODE>
 434    * then <U>all</U> of the properties of this Group object instance will be
 435    * set, or renewed, according to the values of the AFS group it represents,
 436    * disregarding any previously set properties.
 437    *
 438    * <P> Thus, if <CODE>all</CODE> is <CODE>false</CODE> then properties that
 439    * are currently set will be refreshed and properties that are not set will
 440    * remain uninitialized. See {@link #refresh()} for more information.
 441    *
 442    * @param all   if true set or renew all object properties; otherwise renew
 443    *              all set properties
 444    * @exception AFSException  If an error occurs in the native code
 445    * @see #refresh()
 446    */
 447   protected void refresh(boolean all) throws AFSException
 448   {
 449     if( all || cachedInfo ) {
 450       refreshInfo();
 451     }
 452     if( all || groupsOwned != null ) {
 453       refreshGroupsOwned();
 454     }
 455     if( all || groupsOwnedNames != null ) {
 456       refreshGroupsOwnedNames();
 457     }
 458     if( all || members != null ) {
 459       refreshMembers();
 460     }
 461     if( all || memberNames != null ) {
 462       refreshMemberNames();
 463     }
 464   }
 465
 466   /**
 467    * Refreshes the information fields of this <code>Group</code> to reflect
 468    * the current state of the AFS group.  Does not refresh the members that
 469    * belong to the group, nor the groups the group owns.
 470    *
 471    * @exception AFSException      If an error occurs in the native code
 472    */
 473   protected void refreshInfo() throws AFSException
 474   {
 475     cachedInfo = true;
 476     Group.getGroupInfo( cell.getCellHandle(), name, this );
 477   }
 478
 479   /**
 480    * Refreshes the current information about the <code>User</code> objects
 481    * belonging to this group.  Does not refresh the information fields of
 482    * the group or groups owned.
 483    *
 484    * @exception AFSException  If an error occurs in the native code
 485    */
 486   protected void refreshMembers() throws AFSException
 487   {
 488     User currUser;
 489
 490     long iterationID = Group.getGroupMembersBegin( cell.getCellHandle(), name );
 491
 492     members = new ArrayList();
 493
 494     currUser = new User( cell );
 495     while( Group.getGroupMembersNext( cellHandle, iterationID, currUser )
 496            != 0 ) {
 497       members.add( currUser );
 498       currUser = new User( cell );
 499     }
 500
 501     Group.getGroupMembersDone( iterationID );
 502   }
 503
 504   /**
 505    * Refreshes the current information about the names of members belonging
 506    * to this group.  Does not refresh the information fields of the group
 507    * or groups owned.
 508    *
 509    * @exception AFSException  If an error occurs in the native code
 510    */
 511   protected void refreshMemberNames() throws AFSException
 512   {
 513     String currName;
 514     long iterationID = Group.getGroupMembersBegin( cell.getCellHandle(), name );
 515
 516     memberNames = new ArrayList();
 517
 518     while( ( currName = Group.getGroupMembersNextString( iterationID ) )
 519            != null ) {
 520       memberNames.add( currName );
 521     }
 522     Group.getGroupMembersDone( iterationID );
 523   }
 524
 525   /**
 526    * Refreshes the current information about the <code>Group</code> objects the
 527    * group owns.  Does not refresh the information fields of the group or
 528    * members.
 529    *
 530    * @exception AFSException  If an error occurs in the native code
 531    */
 532   protected void refreshGroupsOwned() throws AFSException
 533   {
 534     Group currGroup;
 535
 536     long iterationID = User.getGroupsOwnedBegin( cell.getCellHandle(), name );
 537
 538     groupsOwned = new ArrayList();
 539
 540     currGroup = new Group( cell );
 541     while( User.getGroupsOwnedNext( cellHandle, iterationID, currGroup )
 542            != 0 ) {
 543       groupsOwned.add( currGroup );
 544       currGroup = new Group( cell );
 545     }
 546
 547     User.getGroupsOwnedDone( iterationID );
 548   }
 549
 550   /**
 551    * Refreshes the current information about the names of groups the group
 552    * owns.  Does not refresh the information fields of the group or members.
 553    *
 554    * @exception AFSException  If an error occurs in the native code
 555    */
 556   protected void refreshGroupsOwnedNames() throws AFSException
 557   {
 558     String currName;
 559
 560     long iterationID = User.getGroupsOwnedBegin( cell.getCellHandle(), name );
 561
 562     groupsOwnedNames = new ArrayList();
 563     while( ( currName = User.getGroupsOwnedNextString( iterationID ) )
 564            != null ) {
 565       groupsOwnedNames.add( currName );
 566     }
 567     User.getGroupsOwnedDone( iterationID );
 568   }
 569
 570   /**
 571    * Adds an access control list entry for some AFS directory for this group.
 572    *
 573    * @param directory  the full path of the place in the AFS file system
 574    *                   for which to add an entry
 575    * @param read  whether or not to allow read access to this user
 576    * @param write  whether or not to allow write access to this user
 577    * @param lookup  whether or not to allow lookup access to this user
 578    * @param delete  whether or not to allow deletion access to this user
 579    * @param insert  whether or not to allow insertion access to this user
 580    * @param lock  whether or not to allow lock access to this user
 581    * @param admin  whether or not to allow admin access to this user
 582    * @exception AFSException  If an error occurs in the native code
 583   public void setACL( String directory, boolean read, boolean write, boolean lookup, boolean delete, boolean insert, boolean lock, boolean admin )
 584     throws AFSException
 585   {
 586     Cell.setACL( directory, name, read, write, lookup, delete, insert, lock, admin );
 587   }
 588    */
 589
 590   //////////////////////  accessors: ///////////////
 591
 592   /**
 593    * Returns the name of this group.
 594    *
 595    * @return the name of this group
 596    */
 597   public String getName()
 598   {
 599     return name;
 600   }
 601
 602   /**
 603    * Returns the numeric AFS id of this group.
 604    *
 605    * @return the AFS id of this group
 606    * @exception AFSException  If an error occurs in the native code
 607    */
 608   public int getUID() throws AFSException
 609   {
 610     if( !cachedInfo ) {
 611         refreshInfo();
 612     }
 613     return nameUID;
 614   }
 615
 616   /**
 617    * Returns the Cell this group belongs to.
 618    *
 619    * @return the Cell this group belongs to
 620    */
 621   public Cell getCell()
 622   {
 623     return cell;
 624   }
 625
 626   /**
 627    * Returns an array of the <code>User</code> object members of this group.
 628    *
 629    * @return      an array of the members of this group
 630    * @exception AFSException  If an error occurs in the native code
 631    */
 632   public User[] getMembers() throws AFSException
 633   {
 634     if( members == null ) {
 635       refreshMembers();
 636     }
 637     return (User[]) members.toArray( new User[members.size()] );
 638   }
 639
 640   /**
 641    * Returns an array of the member names of this group.
 642    *
 643    * @return      an array of the member names of this group
 644    * @exception AFSException  If an error occurs in the native code
 645    */
 646   public String[] getMemberNames() throws AFSException
 647   {
 648     if( memberNames == null ) {
 649       refreshMemberNames();
 650     }
 651     return (String[]) memberNames.toArray( new String[memberNames.size()] );
 652   }
 653
 654   /**
 655    * Returns an array of the <code>Group</code> objects this group owns.
 656    *
 657    * @return     an array of the <code>Groups</code> this group owns
 658    * @exception AFSException  If an error occurs in the native code
 659    */
 660   public Group[] getGroupsOwned() throws AFSException
 661   {
 662     if( groupsOwned == null ) {
 663       refreshGroupsOwned();
 664     }
 665     return (Group[]) groupsOwned.toArray( new Group[groupsOwned.size()] );
 666   }
 667
 668   /**
 669    * Returns an array of the group names this group owns.
 670    * Contains <code>String</code> objects.
 671    *
 672    * @return     an array of the group names this group owns
 673    * @exception AFSException  If an error occurs in the native code
 674    */
 675   public String[] getGroupsOwnedNames() throws AFSException
 676   {
 677     if( groupsOwnedNames == null ) {
 678       refreshGroupsOwnedNames();
 679     }
 680     return (String[])
 681         groupsOwnedNames.toArray(new String[groupsOwnedNames.size()] );
 682   }
 683
 684   /**
 685    * Returns the number of members of this group.
 686    *
 687    * @return the membership count
 688    * @exception AFSException  If an error occurs in the native code
 689    */
 690   public int getMembershipCount() throws AFSException
 691   {
 692     if( !cachedInfo ) {
 693         refreshInfo();
 694     }
 695     return membershipCount;
 696   }
 697
 698   /**
 699    * PTS: Returns the owner of this group in the form of a {@link PTSEntry}.
 700    *
 701    * <P>The returning object could be either a {@link User} or {@link Group};
 702    * to determine what type of object the {@link PTSEntry} represents,
 703    * call the {@link PTSEntry#getType()} method.
 704    *
 705    * @return the owner of this group
 706    * @exception AFSException  If an error occurs in the native code
 707    * @see PTSEntry
 708    * @see PTSEntry#getType()
 709    * @see #refresh()
 710    */
 711   public PTSEntry getOwner() throws AFSException
 712   {
 713     if (!cachedInfo) refreshInfo();
 714     if (owner == null) return null;
 715     if (ownerUID > 0) {
 716       return new User(owner, cell);
 717     } else {
 718       return new Group(owner, cell);
 719     }
 720   }
 721
 722   /**
 723    * PTS: Returns the creator of this group in the form of a {@link PTSEntry}.
 724    *
 725    * <P>The returning object could be either a {@link User} or {@link Group};
 726    * to determine what type of object the {@link PTSEntry} represents,
 727    * call the {@link PTSEntry#getType()} method.
 728    *
 729    * @return the creator of this group
 730    * @exception AFSException  If an error occurs in the native code
 731    * @see PTSEntry
 732    * @see PTSEntry#getType()
 733    * @see #refresh()
 734    */
 735   public PTSEntry getCreator() throws AFSException
 736   {
 737     if (!cachedInfo) refreshInfo();
 738     if (creator == null) return null;
 739     if (creatorUID > 0) {
 740       return new User(creator, cell);
 741     } else {
 742       return new Group(creator, cell);
 743     }
 744   }
 745
 746   /**
 747    * Returns the type of {@link PTSEntry} this object represents.
 748    *
 749    * <P>This method will always return {@link PTSEntry#PTS_GROUP}.
 750    *
 751    * @return  the type of PTSEntry this object represents
 752               (will always return {@link PTSEntry#PTS_GROUP})
 753    * @see PTSEntry
 754    * @see PTSEntry#getType()
 755    */
 756   public short getType()
 757   {
 758     return PTSEntry.PTS_GROUP;
 759   }
 760
 761   /**
 762    * Returns who can list the status (pts examine) of this group.
 763    * Valid values are:
 764    * <ul>
 765    * <li><code>{@link #GROUP_OWNER_ACCESS}</code>
 766    *           -- only the owner has permission</li>
 767    * <li><code>{@link #GROUP_GROUP_ACCESS}</code>
 768    *           -- only members of the group have permission</li>
 769    * <li><code>{@link #GROUP_ANYUSER_ACCESS}</code>
 770    *           -- any user has permission</li>
 771    * </ul>
 772    *
 773    * @return the status listing permission
 774    * @exception AFSException  If an error occurs in the native code
 775    */
 776   public int getListStatus() throws AFSException
 777   {
 778     if( !cachedInfo ) refreshInfo();
 779     return listStatus;
 780   }
 781
 782   /**
 783    * Returns who can list the groups owned (pts listowned) by this group.
 784    * Valid values are:
 785    * <ul>
 786    * <li><code>{@link #GROUP_OWNER_ACCESS}</code>
 787    *           -- only the owner has permission</li>
 788    * <li><code>{@link #GROUP_GROUP_ACCESS}</code>
 789    *           -- only members of the group have permission</li>
 790    * <li><code>{@link #GROUP_ANYUSER_ACCESS}</code>
 791    *           -- any user has permission</li>
 792    * </ul>
 793    *
 794    * @return the groups owned listing permission
 795    * @exception AFSException  If an error occurs in the native code
 796    */
 797   public int getListGroupsOwned() throws AFSException
 798   {
 799     if( !cachedInfo ) refreshInfo();
 800     return listGroupsOwned;
 801   }
 802
 803   /**
 804    * Returns who can list the users (pts membership) that belong to this group.
 805    * Valid values are:
 806    * <ul>
 807    * <li><code>{@link #GROUP_OWNER_ACCESS}</code>
 808    *           -- only the owner has permission</li>
 809    * <li><code>{@link #GROUP_GROUP_ACCESS}</code>
 810    *           -- only members of the group have permission</li>
 811    * <li><code>{@link #GROUP_ANYUSER_ACCESS}</code>
 812    *           -- any user has permission</li>
 813    * </ul>
 814    *
 815    * @return the membership listing permission
 816    * @exception AFSException  If an error occurs in the native code
 817    */
 818   public int getListMembership() throws AFSException
 819   {
 820     if( !cachedInfo ) refreshInfo();
 821     return listMembership;
 822   }
 823
 824   /**
 825    * Returns who can add members (pts adduser) to this group.
 826    * Valid values are:
 827    * <ul>
 828    * <li><code>{@link #GROUP_OWNER_ACCESS}</code>
 829    *           -- only the owner has permission</li>
 830    * <li><code>{@link #GROUP_GROUP_ACCESS}</code>
 831    *           -- only members of the group have permission</li>
 832    * <li><code>{@link #GROUP_ANYUSER_ACCESS}</code>
 833    *           -- any user has permission</li>
 834    * </ul>
 835    *
 836    * @return the member adding permission
 837    * @exception AFSException  If an error occurs in the native code
 838    */
 839   public int getListAdd() throws AFSException
 840   {
 841     if( !cachedInfo ) refreshInfo();
 842     return listAdd;
 843   }
 844
 845   /**
 846    * Returns who can delete members (pts removemember) from this group.
 847    * Valid values are:
 848    * <ul>
 849    * <li><code>{@link #GROUP_OWNER_ACCESS}</code>
 850    *           -- only the owner has permission</li>
 851    * <li><code>{@link #GROUP_GROUP_ACCESS}</code>
 852    *           -- only members of the group have permission</li>
 853    * <li><code>{@link #GROUP_ANYUSER_ACCESS}</code>
 854    *           -- any user has permission</li>
 855    * </ul>
 856    *
 857    * @return the member deleting permission
 858    * @exception AFSException  If an error occurs in the native code
 859    */
 860   public int getListDelete() throws AFSException
 861   {
 862     if( !cachedInfo ) refreshInfo();
 863     return listDelete;
 864   }
 865
 866     ///////////////////  mutators: //////////////////////
 867
 868   /**
 869    * Sets who can list the status (pts examine) of this group.
 870    * Valid values are:
 871    * <ul>
 872    * <li><code>{@link #GROUP_OWNER_ACCESS}</code>
 873    *           -- only the owner has permission</li>
 874    * <li><code>{@link #GROUP_GROUP_ACCESS}</code>
 875    *           -- only members of the group have permission</li>
 876    * <li><code>{@link #GROUP_ANYUSER_ACCESS}</code>
 877    *           -- any user has permission</li>
 878    * </ul>
 879    *
 880    * @param value    the value of the new list membership permission
 881    * @exception AFSException      if an error occurs in the native code
 882    * @exception IllegalArgumentException   if an invalud argument is provided
 883    */
 884   public void setListStatus( int value ) throws AFSException
 885   {
 886     if( (value != Group.GROUP_OWNER_ACCESS) &&
 887         (value != Group.GROUP_GROUP_ACCESS) &&
 888         (value != Group.GROUP_ANYUSER_ACCESS) ) {
 889         throw new IllegalArgumentException( "Cannot set listStatus to "
 890                                             + value );
 891     } else {
 892         listStatus = value;
 893     }
 894   }
 895
 896   /**
 897    * Sets who can list the groups owned (pts listowned) by this group.
 898    * Valid values are:
 899    * <ul>
 900    * <li><code>{@link #GROUP_OWNER_ACCESS}</code>
 901    *           -- only the owner has permission</li>
 902    * <li><code>{@link #GROUP_GROUP_ACCESS}</code>
 903    *           -- only members of the group have permission</li>
 904    * <li><code>{@link #GROUP_ANYUSER_ACCESS}</code>
 905    *           -- any user has permission</li>
 906    * </ul>
 907    *
 908    * @param value    the value of the new list membership permission
 909    * @exception AFSException      if an error occurs in the native code
 910    * @exception IllegalArgumentException   if an invalud argument is provided
 911    */
 912   public void setListGroupsOwned( int value ) throws AFSException
 913   {
 914     if( (value != Group.GROUP_OWNER_ACCESS) &&
 915         (value != Group.GROUP_GROUP_ACCESS) &&
 916         (value != Group.GROUP_ANYUSER_ACCESS) ) {
 917         throw new IllegalArgumentException( "Cannot set listGroupsOwned to "
 918                                             + value );
 919     } else {
 920         listGroupsOwned = value;
 921     }
 922   }
 923
 924   /**
 925    * Sets who can list the users (pts membership) that belong to this group.
 926    * Valid values are:
 927    * <ul>
 928    * <li><code>{@link #GROUP_OWNER_ACCESS}</code>
 929    *           -- only the owner has permission</li>
 930    * <li><code>{@link #GROUP_GROUP_ACCESS}</code>
 931    *           -- only members of the group have permission</li>
 932    * <li><code>{@link #GROUP_ANYUSER_ACCESS}</code>
 933    *           -- any user has permission</li>
 934    * </ul>
 935    *
 936    * @param value    the value of the new list membership permission
 937    * @exception AFSException      if an error occurs in the native code
 938    * @exception IllegalArgumentException   if an invalud argument is provided
 939    */
 940   public void setListMembership( int value ) throws AFSException
 941   {
 942     if( (value != Group.GROUP_OWNER_ACCESS) &&
 943         (value != Group.GROUP_GROUP_ACCESS) &&
 944         (value != Group.GROUP_ANYUSER_ACCESS) ) {
 945         throw new IllegalArgumentException( "Cannot set listMembership to "
 946                                             + value );
 947     } else {
 948         listMembership = value;
 949     }
 950   }
 951
 952   /**
 953    * Sets who can add members (pts adduser) to this group.
 954    * Valid values are:
 955    * <ul>
 956    * <li><code>{@link #GROUP_OWNER_ACCESS}</code>
 957    *           -- only the owner has permission</li>
 958    * <li><code>{@link #GROUP_GROUP_ACCESS}</code>
 959    *           -- only members of the group have permission</li>
 960    * <li><code>{@link #GROUP_ANYUSER_ACCESS}</code>
 961    *           -- any user has permission</li>
 962    * </ul>
 963    *
 964    * @param value    the value of the new list membership permission
 965    * @exception AFSException      if an invalid value is provided
 966    */
 967   public void setListAdd( int value ) throws AFSException
 968   {
 969     if( (value != Group.GROUP_OWNER_ACCESS) &&
 970         (value != Group.GROUP_GROUP_ACCESS) &&
 971         (value != Group.GROUP_ANYUSER_ACCESS) ) {
 972         throw new IllegalArgumentException( "Cannot set listAdd to " + value );
 973     } else {
 974         listAdd = value;
 975     }
 976   }
 977
 978   /**
 979    * Sets who can delete members (pts removemember) from this group.
 980    * Valid values are:
 981    * <ul>
 982    * <li><code>{@link #GROUP_OWNER_ACCESS}</code>
 983    *           -- only the owner has permission</li>
 984    * <li><code>{@link #GROUP_GROUP_ACCESS}</code>
 985    *           -- only members of the group have permission</li>
 986    * <li><code>{@link #GROUP_ANYUSER_ACCESS}</code>
 987    *           -- any user has permission</li>
 988    * </ul>
 989    *
 990    * @param value    the value of the new list membership permission
 991    * @exception AFSException      if an invalid value is provided
 992    */
 993   public void setListDelete( int value ) throws AFSException
 994   {
 995     if( (value != Group.GROUP_OWNER_ACCESS) &&
 996         (value != Group.GROUP_GROUP_ACCESS) &&
 997         (value != Group.GROUP_ANYUSER_ACCESS) ) {
 998         throw new IllegalArgumentException( "Cannot set listDelete to "
 999                                             + value );
1000     } else {
1001         listDelete = value;
1002     }
1003   }
1004
1005   /////////////// information methods ////////////////////
1006
1007   /**
1008    * Returns a <code>String</code> representation of this <code>Group</code>.
1009    * Contains the information fields and members.
1010    *
1011    * @return a <code>String</code> representation of the <code>Group</code>
1012    */
1013   public String getInfo()
1014   {
1015     String r;
1016     try {
1017         r = "Group: " + getName() + ", uid: " + getUID() + "\n";
1018         r += "\towner: " + getOwner().getName() + ", uid: " + getOwner().getUID() + "\n";
1019         r += "\tcreator: " + getCreator().getName() + ", uid: "
1020             + getCreator().getUID() + "\n";
1021         r += "\tMembership count: " + getMembershipCount() + "\n";
1022         r += "\tList status: " + getListStatus() + "\n";
1023         r += "\tList groups owned: " + getListGroupsOwned() + "\n";
1024         r += "\tList membership: " + getListMembership() + "\n";
1025         r += "\tAdd members: " + getListAdd() + "\n";
1026         r += "\tDelete members: " + getListDelete() + "\n";
1027
1028         r += "\tGroup members: \n";
1029         String names[] = getMemberNames();
1030         for( int i = 0; i < names.length; i++ ) {
1031             r += "\t\t" + names[i] + "\n";
1032         }
1033
1034         r += "\tOwns groups: \n";
1035         names = getGroupsOwnedNames();
1036         for( int i = 0; i < names.length; i++ ) {
1037             r += "\t\t" + names[i] + "\n";
1038         }
1039         return r;
1040     } catch ( AFSException e ) {
1041         return e.toString();
1042     }
1043   }
1044
1045   /////////////// custom override methods ////////////////////
1046
1047   /**
1048    * Compares two Group objects respective to their names and does not
1049    * factor any other attribute.    Alphabetic case is significant in
1050    * comparing names.
1051    *
1052    * @param     group    The Group object to be compared to this Group instance
1053    *
1054    * @return    Zero if the argument is equal to this Group's name, a
1055    *            value less than zero if this Group's name is
1056    *            lexicographically less than the argument, or a value greater
1057    *            than zero if this Group's name is lexicographically
1058    *            greater than the argument
1059    */
1060   public int compareTo(Group group)
1061   {
1062     return this.getName().compareTo(group.getName());
1063   }
1064
1065   /**
1066    * Comparable interface method.
1067    *
1068    * @see #compareTo(Group)
1069    */
1070   public int compareTo(Object obj)
1071   {
1072     return compareTo((Group)obj);
1073   }
1074
1075   /**
1076    * Tests whether two <code>Group</code> objects are equal, based on their
1077    * names.
1078    *
1079    * @param otherGroup   the Group to test
1080    * @return whether the specifed Group is the same as this Group
1081    */
1082   public boolean equals( Group otherGroup )
1083   {
1084     return name.equals( otherGroup.getName() );
1085   }
1086
1087   /**
1088    * Returns the name of this <CODE>Group</CODE>
1089    *
1090    * @return the name of this <CODE>Group</CODE>
1091    */
1092   public String toString()
1093   {
1094     return getName();
1095   }
1096
1097   /////////////// native methods ////////////////////
1098
1099   /**
1100    * Creates the PTS entry for a new group.  Pass in 0 for the uid if PTS is to
1101    * automatically assign the group id.
1102    *
1103    * @param cellHandle    the handle of the cell to which the group belongs
1104    * @see Cell#getCellHandle
1105    * @param groupName      the name of the group to create
1106    * @param ownerName      the owner of this group
1107    * @param gid     the group id to assign to the group (0 to have one
1108    *                automatically assigned)
1109    * @exception AFSException  If an error occurs in the native code
1110    */
1111   protected static native void create( long cellHandle, String groupName,
1112                                        String ownerName, int gid )
1113         throws AFSException;
1114
1115   /**
1116    * Deletes the PTS entry for a group.  Deletes this group from the
1117    * membership list of the users that belonged to it, but does not delete
1118    * the groups owned by this group.
1119    *
1120    * @param cellHandle    the handle of the cell to which the group belongs
1121    * @see Cell#getCellHandle
1122    * @param groupName      the name of the group to delete
1123    * @exception AFSException  If an error occurs in the native code
1124    */
1125   protected static native void delete( long cellHandle, String groupName )
1126         throws AFSException;
1127
1128   /**
1129    * Fills in the information fields of the provided <code>Group</code>.
1130    * Fills in values based on the current PTS information of the group.
1131    *
1132    * @param cellHandle    the handle of the cell to which the group belongs
1133    * @see Cell#getCellHandle
1134    * @param name     the name of the group for which to get the information
1135    * @param group     the <code>Group</code> object in which to fill in the
1136    *                  information
1137    * @see Group
1138    * @exception AFSException   If an error occurs in the native code
1139    */
1140   protected static native void getGroupInfo( long cellHandle, String name,
1141                                              Group group )
1142         throws AFSException;
1143
1144   /**
1145    * Sets the information values of this AFS group to be the parameter values.
1146    *
1147    * @param cellHandle    the handle of the cell to which the user belongs
1148    * @see Cell#getCellHandle
1149    * @param name     the name of the user for which to set the information
1150    * @param theGroup   the group object containing the desired information
1151    * @exception AFSException   If an error occurs in the native code
1152    */
1153   protected static native void setGroupInfo( long cellHandle, String name,
1154                                              Group theGroup )
1155         throws AFSException;
1156
1157   /**
1158    * Begin the process of getting the users that belong to the group.  Returns
1159    * an iteration ID to be used by subsequent calls to
1160    * <code>getGroupMembersNext</code> and <code>getGroupMembersDone</code>.
1161    *
1162    * @param cellHandle    the handle of the cell to which the group belongs
1163    * @see Cell#getCellHandle
1164    * @param name          the name of the group for which to get the members
1165    * @return an iteration ID
1166    * @exception AFSException   If an error occurs in the native code
1167    */
1168   protected static native long getGroupMembersBegin( long cellHandle,
1169                                                     String name )
1170         throws AFSException;
1171
1172   /**
1173    * Returns the next members that belongs to the group.  Returns
1174    * <code>null</code> if there are no more members.
1175    *
1176    * @param iterationId   the iteration ID of this iteration
1177    * @see getGroupMembersBegin
1178    * @return the name of the next member
1179    * @exception AFSException   If an error occurs in the native code
1180    */
1181   protected static native String getGroupMembersNextString( long iterationId )
1182         throws AFSException;
1183
1184   /**
1185    * Fills the next user object belonging to that group.  Returns 0 if there
1186    * are no more users, != 0 otherwise.
1187    *
1188    * @param cellHandle    the handle of the cell to which the users belong
1189    * @see Cell#getCellHandle
1190    * @param iterationId   the iteration ID of this iteration
1191    * @see getGroupMembersBegin
1192    * @param theUser   a User object to be populated with the values of the
1193    *                  next user
1194    * @return 0 if there are no more users, != 0 otherwise
1195    * @exception AFSException  If an error occurs in the native code
1196    */
1197   protected static native int getGroupMembersNext( long cellHandle,
1198                                                    long iterationId,
1199                                                    User theUser )
1200     throws AFSException;
1201
1202   /**
1203    * Signals that the iteration is complete and will not be accessed anymore.
1204    *
1205    * @param iterationId   the iteration ID of this iteration
1206    * @see getGroupMembersBegin
1207    * @exception AFSException   If an error occurs in the native code
1208    */
1209   protected static native void getGroupMembersDone( long iterationId )
1210         throws AFSException;
1211
1212   /**
1213    * Adds a user to the specified group.
1214    *
1215    * @param cellHandle    the handle of the cell to which the group belongs
1216    * @see Cell#getCellHandle
1217    * @param groupName          the name of the group to which to add a member
1218    * @param userName      the name of the user to add
1219    * @exception AFSException   If an error occurs in the native code
1220    */
1221   protected static native void addMember( long cellHandle, String groupName,
1222                                           String userName )
1223         throws AFSException;
1224
1225   /**
1226    * Removes a user from the specified group.
1227    *
1228    * @param cellHandle    the handle of the cell to which the group belongs
1229    * @see Cell#getCellHandle
1230    * @param groupName          the name of the group from which to remove a
1231    *                           member
1232    * @param userName      the name of the user to remove
1233    * @exception AFSException   If an error occurs in the native code
1234    */
1235   protected static native void removeMember( long cellHandle, String groupName,
1236                                              String userName )
1237         throws AFSException;
1238
1239   /**
1240    * Change the owner of the specified group.
1241    *
1242    * @param cellHandle    the handle of the cell to which the group belongs
1243    * @see Cell#getCellHandle
1244    * @param groupName          the name of the group of which to change the
1245    *                           owner
1246    * @param ownerName      the name of the new owner
1247    * @exception AFSException   If an error occurs in the native code
1248    */
1249   protected static native void changeOwner( long cellHandle, String groupName,
1250                                             String ownerName )
1251         throws AFSException;
1252
1253   /**
1254    * Change the name of the specified group.
1255    *
1256    * @param cellHandle    the handle of the cell to which the group belongs
1257    * @see Cell#getCellHandle
1258    * @param oldGroupName          the old name of the group
1259    * @param newGroupName      the new name for the group
1260    * @exception AFSException   If an error occurs in the native code
1261    */
1262   protected static native void rename( long cellHandle, String oldGroupName,
1263                                        String newGroupName )
1264         throws AFSException;
1265
1266   /**
1267    * Reclaims all memory being saved by the group portion of the native
1268    * library.
1269    * This method should be called when no more <code>Groups</code> are expected
1270    * to be used.
1271    */
1272   protected static native void reclaimGroupMemory();
1273 }
1274
1275
1276
1277
1278