| /******************************************************************************* |
| * Copyright (c) 2001, 2004 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.jst.j2ee.commonarchivecore.internal.helpers; |
| |
| |
| |
| import org.eclipse.jst.j2ee.commonarchivecore.internal.Archive; |
| import org.eclipse.jst.j2ee.commonarchivecore.internal.exception.OpenFailureException; |
| import org.eclipse.jst.j2ee.commonarchivecore.internal.strategy.ImportStrategy; |
| |
| |
| /** |
| * An interface that defines an API for opening archives. The {@link CommonArchiveFactory} |
| * implementation uses a root level discriminator to open an archive. The main benefit of this api |
| * is it allows extended teams or third parties to plug in to the framework to allow specialized |
| * kinds of jar files do be discerned at creation/open time without the client having to provide a |
| * lot of logic. For example, a client would simply write |
| * <code>((CommonArchivePackage)EPackage.Registry.INSTANCE.getEPackage(CommonArchivePackage.eNS_URI)).getCommonArchiveFactory().open(aString)<code>, and get back |
| * the correct kind of archive instance. A discriminator contains children, which is an ordered list of discriminators, each of which |
| * can have its turn to determine if it can open an archive. The first one to succeed wins. Once a discriminator determines that it |
| * can open an archive, it gives each of its children the opportuntity to do something more specific, and so on. In the base |
| * implementation, discriminators are defined as single instances of an inner class for each import strategy. The following code shows |
| * how to register a discriminator for a specialized EJBJarFile: |
| * <code>EjbJar11ImportStrategyImpl.getDiscriminator().addChild(aDiscriminator);</code> |
| * This would be done as an initialization at startup time. If the child discriminator is ever invoked, the parent will have already |
| * determined that the archive is an EJBJarFile and will have converted it to that type. |
| */ |
| public interface ArchiveTypeDiscriminator { |
| public void addChild(ArchiveTypeDiscriminator child); |
| |
| /** |
| * @throws java.util.NoSuchElementException |
| * if the predecessor is not included in the list of children |
| */ |
| public void addChildAfter(ArchiveTypeDiscriminator child, ArchiveTypeDiscriminator predecessor) throws java.util.NoSuchElementException; |
| |
| /** |
| * @throws java.util.NoSuchElementException |
| * if the successor is not included in the list of children |
| */ |
| public void addChildBefore(ArchiveTypeDiscriminator child, ArchiveTypeDiscriminator successor) throws java.util.NoSuchElementException; |
| |
| /** |
| * Performs tests on the archive to determine if it is the kind this discriminator is interested |
| * in |
| */ |
| public boolean canImport(Archive anArchive); |
| |
| /** |
| * Factory method to create the import strategy for a converted archive |
| */ |
| public ImportStrategy createImportStrategy(Archive old, Archive newArchive); |
| |
| /** |
| * Return a string to be presented either through an exception or error message when a specific |
| * kind of archive is expected and this discriminator can't open it. |
| */ |
| public String getUnableToOpenMessage(); |
| |
| public boolean hasChild(ArchiveTypeDiscriminator disc); |
| |
| public boolean hasChildren(); |
| |
| /** |
| * Point of entry for attempting to open an archive |
| * |
| * @return a converted archive or null if this discriminator can't convert it |
| */ |
| public Archive openArchive(Archive anArchive) throws OpenFailureException; |
| |
| public void removeChild(ArchiveTypeDiscriminator child); |
| } |