Changeset 24409

Show
Ignore:
Timestamp:
15.08.2011 13:42:41 (8 years ago)
Author:
sjm84
Message:

Added comments and fixed an error that was somehow introduced

Files:
1 modified

Legend:

Unmodified
Added
Removed
  • main/trunk/greenstone3/src/java/org/greenstone/gsdl3/util/GSDocumentModel.java

    r24393 r24409  
    2525import org.w3c.dom.NodeList; 
    2626 
    27 import com.oopsconsultancy.xmltask.InsertAction.Position; 
    28  
    2927public class GSDocumentModel 
    3028{ 
     
    3331    protected static final String ARCHIVEINFDOC = "archiveinf-doc"; 
    3432 
    35     //Set section operations 
     33    //Set operations 
    3634    public static final int OPERATION_REPLACE = 1; 
    3735    public static final int OPERATION_INSERT_BEFORE = 2; 
     
    114112    } 
    115113 
     114    /** 
     115     * Can be used to create a document or create a section of a document 
     116     *  
     117     * @param oid 
     118     *            is the identifier of the document/section to create. 
     119     * @param collection 
     120     *            is the collection we want to create the document/section in. 
     121     */ 
    116122    public void documentCreate(String oid, String collection, String lang, String uid) 
    117123    { 
     
    172178    } 
    173179 
     180    /** 
     181     * Can be used to delete a document or section 
     182     *  
     183     * @param oid 
     184     *            is the identifier of the document/section to delete. 
     185     * @param collection 
     186     *            is the collection to delete the document/section from. 
     187     */ 
    174188    public void documentDelete(String oid, String collection, String lang, String uid) 
    175189    { 
     
    218232    } 
    219233 
     234    /** 
     235     * Can be used to copy a document or section from one place to another. 
     236     *  
     237     * @param oid 
     238     *            is the identifier of the document/section that is to be 
     239     *            copied. 
     240     * @param collection 
     241     *            is the collection the source document resides in. 
     242     * @param newOID 
     243     *            is the new identifier for the document/section (it cannot 
     244     *            already exist). 
     245     * @param newCollection 
     246     *            is the collection the new document/section will be copied to. 
     247     *            If this is null then the collection parameter will be used 
     248     *            instead. 
     249     */ 
    220250    public void documentDuplicate(String oid, String collection, String newOID, String newCollection, String lang, String uid) 
    221251    { 
     
    339369    } 
    340370 
    341     //TODO: Change return type to something else 
    342     public void documentGetInformation(String oid, String collection, String[] requestedInfo, String lang, String uid) 
     371    /** 
     372     * Can be used to acquire information about a given document or section. 
     373     *  
     374     * @param oid 
     375     *            is the identifier of the document or section. 
     376     * @param collection 
     377     *            is the collection the document or section resides in. 
     378     * @param requestedInfo 
     379     *            is an array containing the various requests. 
     380     * @return This returns an array containing the requested information. 
     381     */ 
     382    public String[] documentGetInformation(String oid, String collection, String[] requestedInfo, String lang, String uid) 
    343383    { 
    344384        if ((_errorStatus = checkOIDandCollection(oid, collection, lang, uid)) != NO_ERROR) 
    345385        { 
    346             return; 
     386            return null; 
    347387        } 
    348388 
     
    354394            //-Metadata keys 
    355395        } 
    356     } 
    357  
     396        //TODO: Implement 
     397        return null; 
     398    } 
     399 
     400    /** 
     401     * Can be used to move a document or section from one place to another. 
     402     *  
     403     * @param oid 
     404     *            is the identifier of the document/section to move. 
     405     * @param collection 
     406     *            is the collection the source document resides in. 
     407     * @param newOID 
     408     *            is the new identifer for the moved document. 
     409     * @param newCollection 
     410     *            is the collection the new document/section will be moved to. 
     411     *            If this is null then the collection parameter will be used 
     412     *            instead. 
     413     */ 
    358414    public void documentMove(String oid, String collection, String newOID, String newCollection, String lang, String uid) 
    359415    { 
     
    372428    } 
    373429 
     430    /** 
     431     * Can be used to merge two parts of a document together. The sections must 
     432     * be in the same document at the same level (e.g. D11.1.2 and D11.1.3) or a 
     433     * section and it's parent (e.g. D11.1.2 and D11.1). Also, the destination 
     434     * section cannot have any child sections. 
     435     *  
     436     * @param oid 
     437     *            the identifier of the section that is to be merged. 
     438     * @param collection 
     439     *            the collection the section resides in. 
     440     * @param mergeOID 
     441     *            the identifier of the section that the source section will be 
     442     *            merged into. 
     443     */ 
    374444    public void documentMerge(String oid, String collection, String mergeOID, String lang, String uid) 
    375445    { 
     
    483553    } 
    484554 
     555    /** 
     556     * Can be used to split a section into two sections (e.g. D11.2.1 will 
     557     * become D11.2.1 and D11.2.2). Any child section will belong to the second 
     558     * section (D11.2.2 in the example). 
     559     *  
     560     * @param oid 
     561     *            is the identifer of the section to be split. 
     562     * @param collection 
     563     *            is the collection the section resides in. 
     564     * @param splitPoint 
     565     *            is the point in the text we want to split at. 
     566     */ 
    485567    public void documentSplit(String oid, String collection, int splitPoint, String lang, String uid) 
    486568    { 
     
    551633    } 
    552634 
     635    /** 
     636     * Creates a basic doc.xml file with minimal contents. 
     637     *  
     638     * @param oid 
     639     *            is the identifier of the document to be created. 
     640     * @param collection 
     641     *            is the collection the new document will reside in. 
     642     */ 
    553643    public void documentXMLCreateDocXML(String oid, String collection, String lang, String uid) 
    554644    { 
     
    587677    } 
    588678 
     679    /** 
     680     * Gets a metadata value from a document or section. 
     681     *  
     682     * @param oid 
     683     *            is the identifier of the section or document to get metadata 
     684     *            from. 
     685     * @param collection 
     686     *            is the collection the section or document resides in. 
     687     * @param metadataName 
     688     *            is the name of metadata to retrieve 
     689     * @return an array of metadata elements containing the resquested metadata 
     690     */ 
    589691    public ArrayList<Element> documentXMLGetMetadata(String oid, String collection, String metadataName, String lang, String uid) 
    590692    { 
     
    609711    } 
    610712 
     713    /** 
     714     *  
     715     * @param oid 
     716     *            is the identifier of the document or section that is to have 
     717     *            it's metadata set. 
     718     * @param collection 
     719     *            is the collection the document/section resides in. 
     720     * @param metadataName 
     721     *            is the name of the metadata value that is to be set. 
     722     * @param newMetadataValue 
     723     *            is the new value of the metadata. 
     724     * @param position 
     725     *            specifies the position of the value to set. 
     726     * @param operation 
     727     *            can be one of OPERATION_REPLACE, OPERATION_INSERT_BEFORE, 
     728     *            OPERATION_INSERT_AFTER or OPERATION_APPEND. 
     729     */ 
    611730    public void documentXMLSetMetadata(String oid, String collection, String metadataName, String newMetadataValue, int position, int operation, String lang, String uid) 
    612731    { 
     
    687806    } 
    688807 
     808    /** 
     809     * Can be used to delete metadata at a specific position in a document or 
     810     * section (such as the third author of a document). 
     811     *  
     812     * @param oid 
     813     *            is the identifier of the document/section to delete metadata 
     814     *            from. 
     815     * @param collection 
     816     *            is the collection the document resides in. 
     817     * @param metadataName 
     818     *            is the name of the metadata that is to have an item deleted. 
     819     * @param position 
     820     *            is position of the item that is to be deleted. 
     821     */ 
    689822    public void documentXMLDeleteMetadata(String oid, String collection, String metadataName, int position, String lang, String uid) 
    690823    { 
     
    714847    } 
    715848 
     849    /** 
     850     * Can be used to delete all the metadata with a specific name from a 
     851     * document or section (e.g. all of the authors). 
     852     *  
     853     * @param oid 
     854     *            is the identifier of the document or section to delete the 
     855     *            metadata from. 
     856     * @param collection 
     857     *            is the collection the document resides in. 
     858     * @param metadataName 
     859     *            is the name of the metadata to delete. 
     860     */ 
    716861    public void documentXMLDeleteMetadata(String oid, String collection, String metadataName, String lang, String uid) 
    717862    { 
     
    741886    } 
    742887 
     888    /** 
     889     * Can be used to replace a specific metadata item of a given name, given 
     890     * it's value. 
     891     *  
     892     * @param oid 
     893     *            is the document/section of the metadata that is to be 
     894     *            replaced. 
     895     * @param collection 
     896     *            is the collection the document resides in. 
     897     * @param metadataName 
     898     *            is the name of the metadata to be replaced. 
     899     * @param oldMetadataValue 
     900     *            is the old value of the metadata (the value that will be 
     901     *            replaced). 
     902     * @param newMetadataValue 
     903     *            is the new value of the metadata that will replace the old 
     904     *            value. 
     905     */ 
    743906    public void documentXMLReplaceMetadata(String oid, String collection, String metadataName, String oldMetadataValue, String newMetadataValue, String lang, String uid) 
    744907    { 
     
    789952    } 
    790953 
     954    /** 
     955     * Can be used to create a blank section. 
     956     *  
     957     * @param oid 
     958     *            is the identifier of the section to be created. 
     959     * @param collection 
     960     *            is the collection the document resides in. 
     961     */ 
    791962    public void documentXMLCreateSection(String oid, String collection, String lang, String uid) 
    792963    { 
     
    8781049    } 
    8791050 
     1051    /** 
     1052     * Can be used to delete an entire section. 
     1053     *  
     1054     * @param oid 
     1055     *            is the identifier of the section to be deleted. 
     1056     * @param collection 
     1057     *            is the collection the document resides in. 
     1058     */ 
    8801059    public void documentXMLDeleteSection(String oid, String collection, String lang, String uid) 
    8811060    { 
     
    9081087    } 
    9091088 
     1089    /** 
     1090     * Can be used to get a section from a document. 
     1091     *  
     1092     * @param oid 
     1093     *            is the identifier of the section to get. 
     1094     * @param collection 
     1095     *            is the collection the document resides in. 
     1096     * @return the requested section. 
     1097     */ 
    9101098    public Element documentXMLGetSection(String oid, String collection, String lang, String uid) 
    9111099    { 
     
    9411129    } 
    9421130 
    943     public void documentXMLSetSection(String oid, String collection, Element newSection, int op, String lang, String uid) 
     1131    /** 
     1132     * Can be used to set an OID to the given section element. 
     1133     *  
     1134     * @param oid 
     1135     *            is the identifier of the section to be set. 
     1136     * @param collection 
     1137     *            is the collection the section will reside in. 
     1138     * @param newSection 
     1139     *            is the new section element. 
     1140     * @param operation 
     1141     *            can be one of OPERATION_REPLACE, OPERATION_INSERT_BEFORE, 
     1142     *            OPERATION_INSERT_AFTER or OPERATION_APPEND. 
     1143     */ 
     1144    public void documentXMLSetSection(String oid, String collection, Element newSection, int operation, String lang, String uid) 
    9441145    { 
    9451146        if ((_errorStatus = checkOIDandCollection(oid, collection, lang, uid)) != NO_ERROR) 
     
    9731174        Element importedSection = (Element) docXML.importNode(newSection, true); 
    9741175 
    975         if (op == OPERATION_APPEND) 
     1176        if (operation == OPERATION_APPEND) 
    9761177        { 
    9771178            existingSection.appendChild(importedSection); 
     
    9851186            importedSection.removeAttribute(GSXML.COLLECTION_ATT); 
    9861187 
    987             if (op == OPERATION_INSERT_BEFORE || op == OPERATION_REPLACE) 
     1188            if (operation == OPERATION_INSERT_BEFORE || operation == OPERATION_REPLACE) 
    9881189            { 
    9891190                sectionParent.insertBefore(importedSection, existingSection); 
    9901191            } 
    991             else if (op == OPERATION_INSERT_AFTER) 
     1192            else if (operation == OPERATION_INSERT_AFTER) 
    9921193            { 
    9931194                Element sibling = (Element) existingSection.getNextSibling(); 
     
    10021203            } 
    10031204 
    1004             if (op == OPERATION_REPLACE) 
     1205            if (operation == OPERATION_REPLACE) 
    10051206            { 
    10061207                sectionParent.removeChild(existingSection); 
     
    10161217    } 
    10171218 
     1219    /** 
     1220     * Gets the text of a given section as a string. 
     1221     *  
     1222     * @param oid 
     1223     *            is the identifier of the section to get the text from. 
     1224     * @param collection 
     1225     *            is the collection the document resides in. 
     1226     * @return the text from the section. 
     1227     */ 
    10181228    public String documentXMLGetText(String oid, String collection, String lang, String uid) 
    10191229    { 
     
    10611271    } 
    10621272 
     1273    /** 
     1274     * Sets the text of a given section using an element. 
     1275     *  
     1276     * @param oid 
     1277     *            is the identifier of the section to set the text of. 
     1278     * @param collection 
     1279     *            is the collection the document resides in. 
     1280     * @param newContent 
     1281     *            is the new content element for the section. 
     1282     */ 
    10631283    public void documentXMLSetText(String oid, String collection, Element newContent, String lang, String uid) 
    10641284    { 
     
    11201340    } 
    11211341 
     1342    /** 
     1343     * Sets the text of a given section using a string. 
     1344     *  
     1345     * @param oid 
     1346     *            is the identifier of the section to set the text of. 
     1347     * @param collection 
     1348     *            is the collection the document resides in. 
     1349     * @param newContent 
     1350     *            is the new text for the section. 
     1351     */ 
    11221352    public void documentXMLSetText(String oid, String collection, String newContent, String lang, String uid) 
    11231353    { 
     
    11801410    } 
    11811411 
     1412    /** 
     1413     * Can be used to get the file path of the doc.xml file containing the given 
     1414     * OID. 
     1415     *  
     1416     * @param oid 
     1417     *            is the identifier of the document/section to get the doc.xml 
     1418     *            of. 
     1419     * @param collection 
     1420     *            is the collection the document resides in. 
     1421     * @return the file path to the doc.xml file. 
     1422     */ 
    11821423    public String archiveGetDocumentFilePath(String oid, String collection, String lang, String uid) 
    11831424    { 
     
    12051446    } 
    12061447 
     1448    /** 
     1449     * Can be used to find the document that a specific source file is used in. 
     1450     *  
     1451     * @param srcFile 
     1452     *            is the name of the source file. 
     1453     * @param collection 
     1454     *            is the collection the source file resides in. 
     1455     * @return the OID of the document that the source file is used in. 
     1456     */ 
    12071457    public String archiveGetSourceFileOID(String srcFile, String collection, String lang, String uid) 
    12081458    { 
     
    12291479    } 
    12301480 
     1481    /** 
     1482     * Checks to see if a document or section at a given OID exists. 
     1483     *  
     1484     * @param oid 
     1485     *            is the identifier of the document/section to check. 
     1486     * @param collection 
     1487     *            is the collection to search in. 
     1488     * @return true if the document/section exists, false otherwise. 
     1489     */ 
    12311490    public boolean archiveCheckDocumentOrSectionExists(String oid, String collection, String lang, String uid) 
    12321491    { 
     
    12701529    } 
    12711530 
     1531    /** 
     1532     * Can be used to write a series of entries to the document database. 
     1533     *  
     1534     * @param oid 
     1535     *            is the key that the entries will be written to. 
     1536     * @param collection 
     1537     *            is the collection whose database will be written to. 
     1538     * @param infoList 
     1539     *            is the list of entries to write. 
     1540     */ 
    12721541    public void archiveWriteEntryToDatabase(String oid, String collection, HashMap<String, ArrayList<String>> infoList, String lang, String uid) 
    12731542    { 
     
    13041573    } 
    13051574 
     1575    /** 
     1576     * Can be used to remove an entry from the document database. 
     1577     *  
     1578     * @param oid 
     1579     *            is the key of the entry to erase. 
     1580     * @param collection 
     1581     *            is the collection whose database will have the entry removed. 
     1582     */ 
    13061583    public void archiveRemoveEntryFromDatabase(String oid, String collection, String lang, String uid) 
    13071584    { 
     
    13281605    } 
    13291606 
     1607    /** 
     1608     * Gets the list of associated files for a given document. 
     1609     * @param oid is the identifier that will be used to search for associated documents. 
     1610     * @param collection is the collection whose database will be searched. 
     1611     * @return the list of associated files. 
     1612     */ 
    13301613    public ArrayList<String> archiveGetAssociatedImportFiles(String oid, String collection, String lang, String uid) 
    13311614    {