home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgLangD.iso / VCAFE.3.0A / Main.bin / ProjectFile.java < prev    next >
Text File  |  1998-11-11  |  9KB  |  227 lines
  1. /*
  2.  * Copyright 1998 Symantec Corporation, All Rights Reserved.
  3.  */
  4.  
  5. package com.symantec.itools.vcafe.openapi;
  6.  
  7. import java.io.File;
  8. import com.symantec.itools.vcafe.openapi.dtreflect.DTClass;
  9. import com.symantec.itools.vcafe.openapi.dtreflect.DTMember;
  10.  
  11. /**
  12.  * The API used to represent and access a Project File in a <code>VisualProject</code>.
  13.  * Each <code>ProjectFile</code> corresponds to an entry in the "Files" tab of Visual Cafe's 
  14.  * project window.
  15.  * A plug-in can use the methods in this class to update file attributes.
  16.  *
  17.  * The implementation of all of <code>ProjectFile</code>'s abstract methods first calls
  18.  * checkValidity().  Any method could therefore throw an <code>InvalidProjectFileException</code>.
  19.  * This exception extends <code>RuntimeException</code>, so doesn't have to be explicity declared or
  20.  * caught.  A <code>ProjectFile</code> can become invalid if it is removed from its project, or its
  21.  * project is closed, and the corresponding <code>ProjectListener</code> message is ignored, for example.
  22.  *
  23.  * @see VisualProject#getProjectFiles
  24.  * @see VisualProject#getProjectFiles(int)
  25.  * @see VisualProject#getProjectFile(String)
  26.  * @see VisualProject#getProjectFile(int)
  27.  * @see InvalidProjectFileException
  28.  *
  29.  * @author Symantec Internet Tools Division
  30.  * @version 1.0
  31.  * @since VCafe 3.0
  32.  */
  33. public abstract class ProjectFile
  34. {
  35.     /**
  36.      * Indicates this file was added by the user.
  37.      */
  38.     public static final int USER_ADDED = 1;
  39.  
  40.     /**
  41.      * Indicates this file was added by the compiler.
  42.      */
  43.     public static final int COMPILER_ADDED  = 2;
  44.  
  45.     /**
  46.      * Indicates this file was added by the parser.
  47.      */
  48.     public static final int PARSER_ADDED = 4;
  49.  
  50.     /**
  51.      * Indicates this file was added by an unknown source.
  52.      */
  53.     public static final int UNKNOWN_ADDED = 8;
  54.  
  55.     /**
  56.      * Indicates this file was added by the database.
  57.      */
  58.     public static final int SHARED_DATABASE_ADDED = 16;
  59.  
  60.     /**
  61.      * Indicates this file was added by one of the ERAD wizards.
  62.      */
  63.     public static final int ERAD_WIZARD_ADDED = 32;
  64.  
  65.     /**
  66.      * Specifies a file added by any source.
  67.      */
  68.     public static final int ALL_FILE_ADDED = 0x7fff;
  69.  
  70.  
  71.     /**
  72.      * Gets the complete filename (including path) of the <code>File</code> associated with
  73.      * this <code>ProjectFile</code>.
  74.      * @return      the complete filename of this <code>ProjectFile</code>.
  75.      */
  76.     public abstract String getFullName();
  77.  
  78.     /**
  79.      * Get the <code>File</code> that corresponds to this <code>ProjectFile</code>.
  80.      * This method never returns <code>null</code>, but the actual file may not exist on disk
  81.      * (i.e. <code> File.exists() == false</code>).
  82.      */
  83.     public abstract File getFile();
  84.  
  85.     /**
  86.      * Get a <code>SourceFile</code> associated with this <code>ProjectFile</code>.
  87.      * This method never returns <code>null</code>, but the actual file may not exist on disk
  88.      * (i.e. <code> SourceFile.getFile().exists() == false</code>).
  89.      */
  90.     public abstract SourceFile getSourceFile();
  91.  
  92.     /**
  93.      * Gets the <code>VisualProject</code> that owns this <code>ProjectFile</code>.
  94.      * @return      the owning <code>VisualProject</code>.
  95.      */
  96.     public abstract VisualProject getProject();
  97.  
  98.     /**
  99.      * Gets a number that uniquely identifies this file within its project.
  100.      * @return      a unique numeric ID within the project.
  101.      */
  102.     public abstract int getFileId();
  103.  
  104.     /**
  105.      * Determines who added this file to the project.
  106.      * @return      the source that added this file to the project, is a mask containing any of:<ul type=circle>
  107.      * <li>USER_ADDED - the file was added by the user.
  108.      * <li>COMPILER_ADDED - the file was added by the compiler.
  109.      * <li>PARSER_ADDED - the file was added by the parser.
  110.      * <li>UNKNOWN_ADDED - the file was added by an unknown source.
  111.      * <li>SHARED_DATABASE_ADDED - the file was added by the database.
  112.      * <li>ERAD_WIZARD_ADDED - the file was added by one of the ERAD wizards.
  113.      * </ul>
  114.      */
  115.     public abstract int getFileAddedBy();
  116.  
  117.     /**
  118.      * Gets the Rapid Application Development (RAD) state of this <code>ProjectFile</code>. This determines whether this
  119.      * <code>ProjectFile</code> is parsed for Rapid Application Development or not. It is shown by the 'Start RAD'/'Stop RAD'
  120.      * menu item in the project window.
  121.      * @return        <code>true</code>if RAD is enabled, <code>false</code> otherwise.
  122.      */
  123.     public abstract boolean isRADEnabled();
  124.  
  125.     /**
  126.      * Remove this <code>ProjectFile</code> from its <code>VisualProject</code>.
  127.      */
  128.     public abstract void remove();
  129.  
  130.     /**
  131.      * Renames this <code>ProjectFile</code>. The new file name must be fully qualified.
  132.      * This method optionally overwrites any existing file with the same new name.
  133.      * The old file with the original name is deleted.
  134.      * NOTE: This function assumes the file contents/type will remain the same.
  135.      * If it is a <code>.java</code> source file it will still be marked as a source file
  136.      * even if the extension changes. If you want to make sure that the file type
  137.      * in the build system is correct, remove the old file and add a new file instead.
  138.      *
  139.      * @param newName   the new fully qualified name for this file.
  140.      * @param replace   <code>true</code> to overwrite any file that might already have the new name.
  141.      */
  142.     public abstract void rename(String newName, boolean replace);
  143.  
  144.     /**
  145.      * Determines the package name for classes in this <code>ProjectFile</code>.
  146.      * @return the package name.
  147.      */
  148.     public abstract String getPackageName();
  149.  
  150.     /**
  151.      * Determines the list of imports in this <code>ProjectFile</code>.
  152.      * @return the list of imports.
  153.      */
  154.     public abstract String[] getImports();
  155.  
  156.     /**
  157.      * Gets an array of <code>DTClass</code> objects reflecting all the top-level classes and
  158.      * interfaces declared in this <code>ProjectFile</code>.  This includes public, protected, default
  159.      * (package) access, and private classes and interfaces declared in the <code>ProjectFile</code>.
  160.      * To also get nested classes, use the <code>getClasses()</code> method.
  161.      * @return an array of <code>DTClass</code> objects for top-level classes.
  162.      * @see getClasses
  163.      */
  164.     public abstract DTClass[] getDeclaredClasses();
  165.     
  166.     /**
  167.      * Gets an array of <code>DTClass</code> objects reflecting all the classes and interfaces
  168.      * declared in this <code>ProjectFile</code>.  This includes public, protected, default
  169.      * (package) access, and private classes and interfaces declared in the <code>ProjectFile</code>.
  170.      * This includes nested classes.
  171.      * To only get top-level classes (and not nested ones), use the <code>getDeclaredClasses</code> method.
  172.      * @return an array of <code>DTClass</code> objects for all <code>ProjectFile</code> classes.
  173.      * @see getDeclaredClasses
  174.      */
  175.     public abstract DTClass[] getClasses();
  176.     
  177.     /**
  178.      * Gets the closest class to the given <code>ProjectFile</code> location.  The closest class is the
  179.      * innermost class with a source range or Javadoc range that surrounds the given location.
  180.      * @param location the location offset, in zero-based bytes.
  181.      * @return the <code>DTClass</code> object of the closest class.
  182.      */
  183.     public abstract DTClass getClosestClass(int location);
  184.     
  185.     /**
  186.      * Gets the closest member to the given <code>ProjectFile</code> location..  The closest member is the
  187.      * member of the  innermost class with a source range or Javadoc range that surrounds the given location.
  188.      * @param location the location offset, in zero-based bytes.
  189.      * @return the <code>DTMember</code> object of the closest member.
  190.      * @see DTClass#getClosestMember
  191.      */
  192.     public abstract DTMember getClosestMember(int location);
  193.  
  194.     /**
  195.      * Gets a <code>String</code> representation of this <code>ProjectFile</code>.
  196.      * @return the <code>String</code>, formatted as "ProjectFile[full path name]".
  197.      */
  198.     public String toString() {
  199.         return "ProjectFile[" + getFullName() + "]";
  200.     }
  201.     
  202.     /**
  203.      * Determine if two <code>ProjectFile</code> objects represent the same file in a <code>VisualProject</code>.
  204.      * @param projectFile the <code>ProjectFile</code> to test against.
  205.      * @return <code>true</code> if the two <code>ProjectFile</code> objects represent the same file.
  206.      */
  207.     public abstract boolean equals(ProjectFile projectFile);
  208.  
  209.     /**
  210.      * Determine if this <code>ProjectFile</code> corresponds to a valid file in its <code>VisualProject</code>.
  211.      * A <code>ProjectFile</code> can become invalid if it has been removed from its project, or its
  212.      * project has been closed, for example.
  213.      * @return <code>true</code> if the <code>ProjectFile</code> is still valid.
  214.      */
  215.     public abstract boolean isValid();
  216.  
  217.     /**
  218.      * Checks that this object is valid, and throws a <code>RuntimeException</code> if not.
  219.      * Note that the implementation of all of <code>ProjectFile</code>'s abstract methods first call
  220.      * checkValidity().  Any method could therefore throw an <code>InvalidProjectFileException</code>. 
  221.      * @exception com.symantec.itools.vcafe.openapi.InvalidProjectFileException
  222.      */
  223.     public void checkValidity() throws InvalidProjectFileException {
  224.         if (!isValid()) throw new InvalidProjectFileException();
  225.     }
  226. }
  227.