1 /** 2 * This file Copyright (c) 2010-2017 Magnolia International 3 * Ltd. (http://www.magnolia-cms.com). All rights reserved. 4 * 5 * 6 * This file is dual-licensed under both the Magnolia 7 * Network Agreement and the GNU General Public License. 8 * You may elect to use one or the other of these licenses. 9 * 10 * This file is distributed in the hope that it will be 11 * useful, but AS-IS and WITHOUT ANY WARRANTY; without even the 12 * implied warranty of MERCHANTABILITY or FITNESS FOR A 13 * PARTICULAR PURPOSE, TITLE, or NONINFRINGEMENT. 14 * Redistribution, except as permitted by whichever of the GPL 15 * or MNA you select, is prohibited. 16 * 17 * 1. For the GPL license (GPL), you can redistribute and/or 18 * modify this file under the terms of the GNU General 19 * Public License, Version 3, as published by the Free Software 20 * Foundation. You should have received a copy of the GNU 21 * General Public License, Version 3 along with this program; 22 * if not, write to the Free Software Foundation, Inc., 51 23 * Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 24 * 25 * 2. For the Magnolia Network Agreement (MNA), this file 26 * and the accompanying materials are made available under the 27 * terms of the MNA which accompanies this distribution, and 28 * is available at http://www.magnolia-cms.com/mna.html 29 * 30 * Any modifications to this file must keep this entire header 31 * intact. 32 * 33 */ 34 package info.magnolia.dam.api; 35 36 import info.magnolia.dam.api.metadata.AssetMetadata; 37 38 import com.google.common.net.MediaType; 39 import java.util.Iterator; 40 41 /** 42 * An AssetProvider exposes {@link Folder}s and {@link Asset}s from a particular source. 43 * Specifics of the storage of these items are left to implementations. 44 * 45 * While most provider implementations will only use the {@link ItemKey#assetId} field of keys passed to the various 46 * get methods, the entire key object is passed for consistency and flexibility, making it possible to implement 47 * delegating/aggregating providers, for example. 48 */ 49 public interface AssetProvider { 50 51 /** 52 * Return the AssetProvider identifier. 53 */ 54 String getIdentifier(); 55 56 /** 57 * Returns true if the provider supports the given {@link AssetProviderCapability}. 58 */ 59 boolean supports(AssetProviderCapability capability); 60 61 /** 62 * Whether this provider supports the given {@link AssetMetadata} type. 63 */ 64 boolean supports(Class<? extends AssetMetadata> metaData); 65 66 /** 67 * Whether this provider provides or allows the given MediaType. 68 * Some providers can be configured to only be used for a given set or subset of types. 69 */ 70 boolean provides(MediaType mediaType); 71 72 /** 73 * Cast-less convenience method for {@link #getItem(ItemKey)}. 74 * 75 * @throws IllegalArgumentException if the key does not correspond to an Item of the Asset type. 76 */ 77 Asset getAsset(ItemKey assetKey) throws AssetNotFoundException, IllegalItemKeyException; 78 79 /** 80 * Cast-less convenience method for {@link #getItem(ItemKey)}. 81 * 82 * @throws IllegalArgumentException if the key does not correspond to an Item of the Folder type. 83 */ 84 Folder getFolder(ItemKey folderKey) throws AssetNotFoundException, IllegalItemKeyException; 85 86 /** 87 * Returns the item associated with the given {@link ItemKey}, regardless of its type. 88 * 89 * @throws IllegalArgumentException if the key does not correspond to an Item of the Folder or Asset type. 90 */ 91 Item getItem(ItemKey itemKey) throws AssetNotFoundException, IllegalItemKeyException; 92 93 /** 94 * The top-most folder available from this AssetProvider. See notes at {@link Folder#isRoot()}. 95 */ 96 Folder getRootFolder(); 97 98 /** 99 * Returns an iterator over the results matching the given {@link AssetQuery}. Depending on the 100 * specific values of the {@link AssetQuery} and the {@link AssetProvider} implementation, 101 * this might list direct children, execute a query, ... 102 * It is up to the provider to validate the query - some combinations of criteria might not be supported by all 103 * providers. 104 * @see AssetProviderCapability 105 */ 106 Iterator<Item> list(AssetQuery assetQuery); 107 108 /** 109 * Returns an appropriate {@link AssetRenderer} if this provider has specific renderers, or null if there is none. 110 * @see {@link AssetProviderRegistry#getRendererFor(Asset, com.google.common.net.MediaType)}, which is what client 111 * code should be using rather than this method here. 112 * TODO: overdoing it if we move this to abstract to hide it from client code ? 113 */ 114 AssetRenderer getRendererFor(Asset asset, MediaType to); 115 116 /** 117 * Thrown when the given ItemKey can't be found. 118 */ 119 static class AssetNotFoundException extends DamException { 120 public AssetNotFoundException(ItemKey itemKey) { 121 super("No Asset found for ItemKey <" + itemKey + ">"); 122 } 123 } 124 125 /** 126 * Thrown when the given ItemKey isn't usable by the provider. 127 * Possible reasons are this ItemKey isn't mean for this provider, or points to an Asset outside the realm of this 128 * provider (if the provider has a "root path", for example). 129 */ 130 static class IllegalItemKeyException extends DamException { 131 public IllegalItemKeyException(ItemKey itemKey, AssetProvider provider, String reason) { 132 super("ItemKey <" + itemKey + "> can not be handled by " + provider + " : " + reason); 133 } 134 } 135 }