Creating an annotation entry

At the end of the annotation, we need to create a new MS Annotation Entry and add that as a child entry for the corresponding MS Entry and save the project (that contains the MS Entry) to make changes permanent.

Several steps are included in this process (see org.grits.toolbox.importer.ms.annotation.glycan.simiansearch.handler.GelatoWorker):

1. Create a new Entry and set its display name: In the example below, we are getting the name from the wizard where a user enters a name for the annotation for each MS entry that is annotated.

        Entry msAnnotationEntry = new Entry();

        String msEntryDisplayName = msEntry.getDisplayName();
        String msAnnotName = wizard.getInitial().getListEntries().get(msEntryDisplayName);
        msAnnotationEntry.setDisplayName(msAnnotName);

2. Creating the property: We need to know the annotation folder to be able to assign a unique annotation id to the metadata in the property. "createRandomId" does the following: randomly generate an id and check to make sure it does not exist in the folder already.

        // getting the annotation folder
        File msAnnFile = getAnnotationFolder(msEntry);	
        String msAnnotationFolder = msAnnFile.getAbsolutePath();

        MSGlycanAnnotationProperty t_property = new MSGlycanAnnotationProperty();
        MSGlycanAnnotationMetaData metaData = new MSGlycanAnnotationMetaData();		
	t_property.setMSAnnotationMetaData(metaData);
	metaData.setAnnotationId(this.createRandomId(msAnnotationFolder));
	metaData.setDescription(somedescripton);
	metaData.setVersion(MSGlycanAnnotationMetaData.CURRENT_VERSION);
	metaData.setName(t_property.getMetaDataFileName());
        msAnnotationEntry.setProperty (t_property);        

Getting the annotation folder for the given ms entry:

        protected File getAnnotationFolder( Entry msEntry ) {

		String workspaceLocation = PropertyHandler.getVariable("workspace_location");
		MSGlycanAnnotationProperty t_property = new MSGlycanAnnotationProperty();
		Entry projectEntry = DataModelSearch.findParentByType(msEntry, ProjectProperty.TYPE);
		String projectName = projectEntry.getDisplayName();

		String msAnnotationFolder = workspaceLocation + projectName + File.separator + t_property.getArchiveFolder();	
		File msAnnotationFolderFile = new File(msAnnotationFolder);
		msAnnotationFolderFile.mkdirs();

		return msAnnotationFolderFile;
	}

3. Perform annotation and create the data files

           Data data = new Data();
   	DataHeader dHeader = new DataHeader();
   	data.setDataHeader(dHeader);
   	data.getDataHeader().setMethod(somemethod);     // somemethod is the Method object initialized in the wizard with all the different annotation settings
   
           // call performAnnotation - does all the work. 
   	iStatus = performAnnotation( gpd, data, sWorkspaceFolder, msAnnotationFolder, msAnnotProperty, 
   		dataFile.getMSFileWithReader(pathToFile, prop.getMassSpecMetaData().getMsExperimentType()));
   

During annotation this data file needs to be populated with annotation information and written to the file (see http://trac.grits-toolbox.org/wiki/CreatingAnnotion for details of how this annotation archive is created)

4. Saving the metadata and annotation files

           // if everything worked, save to workspace all of the appropriate files for Annotation
   	msAnnotProperty.getMSAnnotationMetaData().addAnnotationFile(dataFile);      // dataFile is the file we have used for annotation (a handle (MSPropertyDataFile) to the mzxml file for example)
   
   	PropertyDataFile msMetaData = MSAnnotationProperty.getNewSettingsFile(msAnnotProperty.getMetaDataFileName(), msAnnotProperty.getMSAnnotationMetaData());
   	msAnnotProperty.getDataFiles().add(msMetaData);
   	addResultFileToMetaData(dHeader.getMethod().getMsType(), msAnnotProperty);
   	MSAnnotationProperty.marshallSettingsFile(msAnnotProperty.getAnnotationFolder(msEntry) + File.separator + msAnnotProperty.getMetaDataFileName(), msAnnotProperty.getMSAnnotationMetaData());
   
   

        protected void addResultFileToMetaData(String sMSType, MSAnnotationProperty msAnnotProperty) {
		if( sMSType.equals(Method.MS_TYPE_LC) ) {
			NewGelatoHandlerLCMSMS.addResultFileToMetaData(gsa, (MSGlycanAnnotationProperty) msAnnotProperty);
		} else {
			NewGelatoHandler.addResultFileToMetaData(gsa, msAnnotProperty);
		}		
	}

	/**
	 * Determines the annotation file name and folder name (if applicable), creates MSPropertyDataFile objects for them, and adds
	 * them to the meta data for the result files.
	 * 
	 * @param gsa, the GlycanStructureAnnotation specific for the MS Type other than LC-MS/MS
	 * @param msAnnotProperty, the Property to add the results file to
	 */
	private static void addResultFileToMetaData(GlycanStructureAnnotation gsa, MSAnnotationProperty msAnnotProperty) {
		String sAnnotationFile = gsa.getFinalArchiveName();
		File annotationFile = new File( sAnnotationFile );
		MSPropertyDataFile pdfFolder = new MSPropertyDataFile(annotationFile.getName(), 
				MSAnnotationFileInfo.MS_ANNOTATION_CURRENT_VERSION, 
				MSAnnotationFileInfo.MS_ANNOTATION_TYPE_FILE,
				FileCategory.ANNOTATION_CATEGORY, 
				GeneralInformationMulti.FILE_TYPE_GELATO,
				annotationFile.getPath(), new ArrayList<String>() );
		msAnnotProperty.getMSAnnotationMetaData().addFile(pdfFolder);

	}

5. Saving the entries. (see org.grits.toolbox.importer.ms.annotation.glycan.simiansearch.handler.OpenGelatoWizard)

              gritsDataModelService.addEntry (msEntry, msAnnotationEntry);
              // parent of MS Entry is Sample, parent of Sample is the Project
	      ProjectFileHandler.saveProject(msEntry.getParent().getParent());

6. Locking the annotation files since they are now used in an annotation. This allows us to mark (annotation) files as "in use" in MS entry display. (see org.grits.toolbox.importer.ms.annotation.glycan.simiansearch.handler.OpenGelatoWizard)

        private void lockFiles(MSGlycanAnnotationWizard wizard, Entry msEntry, Entry msAnnotationEntry) {
		MassSpecProperty prop = (MassSpecProperty) msEntry.getProperty();
		FileLockManager mng;
		try {
			String lockFileLocation = prop.getLockFilePath(msEntry);
			mng = FileLockingUtils.readLockFile(lockFileLocation);
			MSPropertyDataFile file = wizard.getInitial().getFileMap().get(msEntry.getDisplayName());
			if (file != null) {
				mng.lockFile(file.getName(), msAnnotationEntry);
				FileLockingUtils.writeLockFile(mng, lockFileLocation);
			}
		} catch (IOException e) {
			logger.error("Could not lock the file", e);
		} catch (JAXBException e) {
			logger.error("Could not lock the file", e);
		}	
	}

7. Opening the editor to display the annotation results (see org.grits.toolbox.importer.ms.annotation.glycan.simiansearch.handler.OpenGelatoWizard):

try {
	// need to set the partService to refresh gritsUIServices' stale partService, see ticket #799
	gritsUIService.setPartService(partService);
	gritsUIService.openEntryInPart(msAnnotationEntry);
} catch (Exception e) {
	logger.debug("Could not open the part", e);
}