association.java

JDesktop Integration Components （JDIC）

/*
 * Copyright (C) 2004 Sun Microsystems, Inc. All rights reserved. Use is
 * subject to license terms.
 * 
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the Lesser 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 org.jdesktop.jdic.filetypes;


import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import org.jdesktop.jdic.filetypes.internal.AppUtility;


/**
 * This class represents a file type association. 
 * <P>
 * A file type association contains a description, the MIME type, file extensions,
 * icon file, actions which are represented by <code>Action</code> objects, and  
 * stored MIME file name for Gnome/UNIX platforms.
 * <p>
 * An association could be registered into or unregistered from the system using 
 * certain methods of <code>AssociationService</code>. An association for a particular
 * file type could be returned by certain methods of <code>AssociationService</code>. 
 * <p>
 *
 * @see Action
 * @see AssociationService
 */
public class Association {
  
    /**
     * The name of the generated or removed MIME files on Gnome while 
     * registering/unregistering an association. 
     */
    private String name;

    /**
     * Description of the association.
     */
    private String description;
  
    /**
     * Mime type of the association.
     */
    private String mimeType;
  
    /**
     * File extension list of the association.
     * <P>
     * For Gnome/Unix platforms, all the file extentions in the list will be used. 
     * For Microsoft Windows platforms, only the first file extension in the list is used.
     * 
     */
    private List fileExtensionList;
  
    /**
     * Icon file name of the association.
     */
    private String iconFileName;
  
    /**
     * Action list of the association.
     */
    private List actionList;
    
    /**
     * Hashcode for this association 
     */
    private int hashcode;
  
    /**
     * Returns the name of the MIME files the association is stored in
     * for Gnome/Unix platforms.
     * <p>
     * For Gnome/Unix platforms, the association is stored in plain text files: 
     * <code>name</code>.mime, <code>name</code>.keys and <code>name</code>.applications. 
     * While registering or unregistering an association using certain methods 
     * of <code>AssociationService</code>, the MIME files with the given name 
     * are created or removed.
     * <p>
     * For Microsoft Windows platforms, the association is stored in the registry, 
     * this name is not used.
     *
     * @return the MIME file name.
     */
    public String getName() {
        return name;
    }
  
    /**
     * Returns the name of the MIME files the association is stored in
     * for Gnome/Unix platforms.
     * 
     * @param name a given name value.
     */
    public void setName(String name) {
        if (name == null) {
            throw new IllegalArgumentException("The given MIME file name is null.");
        }
    	
        this.name = name;
    }

    /**
     * Returns the description string of this <code>Association</code>.
     *
     * @return the description of this association.
     */
    public String getDescription() {
        return description;
    }
  
    /**
     * Sets the description string of this <code>Association</code>.
     * 
     * @param description a given description value.
     */
    public void setDescription(String description) {
        if (description == null) {
            throw new IllegalArgumentException("The given description is null.");
        }

        this.description = description;
    }
  
    /**
     * Returns the MIME type of this <code>Association</code>.
     *
     * @return the MIME type.
     */
    public String getMimeType() {
        return mimeType;
    }
  
    /**
     * Sets the MIME type of this <code>Association</code>.
     * 
     * @param mimeType a given MIME type.
     */
    public void setMimeType(String mimeType) {
        if (mimeType == null) {
            throw new IllegalArgumentException("The given MIME type is null.");
        }
        
        this.mimeType = mimeType;
    }
  
    /**
     * Adds one file extension to the file extension list of this <code>Association</code>. 
     * If the given file extension already exists in the file extension
     * list, no changes are made to the file extension list.
     * <P>
     * The specified file extension could have a leading '.' character or not.
     * <P>
     * For Microsoft Windows platforms, only the first file extension is used during 
     * registeration.
     * 
     * @param fileExt a given file extension.
     * @return <code>true</code> if the given file extension is added successfully 
     *         to the file extension list; <code>false</code> otherwise.
     */
    public boolean addFileExtension(String fileExt) {
        if (fileExt == null) {
            throw new IllegalArgumentException("The given file extension is null.");
        }
   	
        // Add the leading '.' character to the given file extension if not exists.    
        fileExt = AppUtility.addDotToFileExtension(fileExt);
        
        if (fileExtensionList == null) {
            fileExtensionList = new ArrayList();
        }
        
        return fileExtensionList.add(fileExt);
    }
  
    /**
     * Removes the given file extension from the file extension list of this 
     * <code>Association</code>. If the file extension is not contained in the file 
     * extension list, no changes are made to the file extension list.
     * <P>
     * The specified file extension may have a leading '.' character or not.
     * 
     * @param fileExt a given file extension.
     * @return <code>true</code> if the given file extension is removed successfully 
     *         from the file extension list; <code>false</code> otherwise.
     */
    public boolean removeFileExtension(String fileExt) {
        if (fileExt == null) {
            throw new IllegalArgumentException("The given file extension is null.");
        }
    	
        // Add the leading '.' character to the given file extension if not exists.
        fileExt = AppUtility.addDotToFileExtension(fileExt);        
        if (fileExtensionList != null) {
            return fileExtensionList.remove(fileExt);
        }
        
        return false;
    }
  
    /**
     * Returns the file extension list of this <code>Association</code>.
     * 
     * @return the file extension list of the association.
     */
    public List getFileExtList() {
        // Make defensive copy
        if (fileExtensionList == null) {
            return null;
        } else {
            List retList = new ArrayList();
            
            Iterator iter = fileExtensionList.iterator();
            while (iter.hasNext()) {
                retList.add(iter.next());
            }
            
            return retList;
        }            
    }
  
    /**
     * Returns the icon file name representing this <code>Association</code>.
     *
     * @return the icon file name for this association.
     */
    public String getIconFileName() {
        return iconFileName;
    }
  
    /**
     * Sets the icon file name representing this <code>Association</code>.
     * <P>
     * For Microsoft Windows platforms, the given icon file will be registered
     * only if the given file extension list is not empty.
     * 
     * @param fileName a given icon file name.
     */
    public void setIconFileName(String fileName) {
        if (fileName == null) {
            throw new IllegalArgumentException("The given icon file name is null.");
        }

        this.iconFileName = fileName;
    }
  
    /**
     * Adds a given action to the action list of this <code>Association</code>. 
     * If the given action already exists in the action list, no changes are 
     * made to the action list.
     * <P>
     * A valid action should not have null verb or command field.
     * <P>
     * For Microsoft Windows platforms, an association with non-empty action list 
     * would be valid for registration when the file extension list is not empty.
     * 
     * @param action a given action.
     * @return <code>true</code> if the given action is added successfully 
     *         to the action list; <code>false</code> otherwise.
     */
    public boolean addAction(Action action) {
        if (action == null) {
            throw new IllegalArgumentException("The given action is null.");
        }
        
        // Check the specified action object has no null verb and command field.