1 /*
2 * This file is a part of CAST project.
3 * (c) Copyright 2007, AGH University of Science & Technology
4 * https://caribou.iisg.agh.edu.pl/trac/cast
5 *
6 * Licensed under the Eclipse Public License, Version 1.0 (the "License").
7 * You may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 * http://www.eclipse.org/legal/epl-v10.html
10 */
11 /*
12 * File: IResourceRegistry.java
13 * Created: 2009-07-17
14 * Author: kpietak
15 * $Id$
16 */
17
18 package pl.edu.agh.cast.resource;
19
20 import java.util.List;
21
22 /**
23 * <p>
24 * The registry which holds all visual resources in the application.
25 * </p>
26 * <p>
27 * A single resource is identified by its unique id in String format. For resources associated with data types such as
28 * icon for visualizing entity, the id is equal to {@link Type#toString()}. For other resources such as actions icons,
29 * the id is java package style unique identifier.
30 * </p>
31 * <p>
32 * Resources can also have tags (string identifiers) which allows for creating families of similar resources. For
33 * example all data sets could have <code>DATA_SET_RESOURCE</code> tag, creating data set resource family. Each resource
34 * can have zero or more associated tags.
35 * </p>
36 * <p>
37 * A single resource is represented by {@link IVisualResource} interface - see java doc for more details.
38 * </p>
39 * <p>
40 * The registry is initialized during the application start and reads & verifies all defined resources at this time so
41 * all errors or warnings are shown to user already at startup. Resources are read from
42 * <code>pl.edu.agh.cast.resource.provider</code> extension point which returns providers (
43 * {@link IVisualResourcesProvider}) containing definition of resources.
44 * </p>
45 *
46 * @author AGH CAST Team
47 */
48 public interface IResourceRegistry {
49
50 /**
51 * Initialize the resource registry. Reads available extensions from the extension point, creates and registers
52 * defined resources. Throws checked exception when any error in reading resources occur.
53 */
54 public void initalize() throws ResourceException;
55
56 /**
57 * Disposes all hold resources including loaded images.
58 */
59 public void dispose();
60
61 /**
62 * Creates a new resource on base of the given entry and register it by given id and tags (all included in entry
63 * object).
64 *
65 * @param resource
66 * resource to register
67 * @throws ResourceException
68 * when any error occur during creating resource or a resource with the same id already exists in the
69 * registry
70 */
71 public void register(IVisualResource resource) throws ResourceException;
72
73 /**
74 * <p>
75 * Unregisters a resource with the given id.
76 * </p>
77 * <p>
78 * <strong>Note:</strong> the method disposes all images associated with resource making it unavailable in the
79 * application. It should be used carefully, only from performance reasons.
80 * </p>
81 *
82 * @param id
83 * resource id to unregister
84 * @throws ResourceException
85 * when any error occurs during unregistering resource.
86 * @return true if resource was successfully unregistered; false if resource didn't exist.
87 */
88 public boolean unregister(String id) throws ResourceException;
89
90 /**
91 * Looks up and returns a resource with the given id. If resource is not found <code>null</code> is returned.
92 *
93 * @param id
94 * resource id
95 * @return resource object or <code>null</code> if no resource with given id is registered.
96 */
97 public IVisualResource getResource(String id);
98
99 /**
100 * Looks up and returns a resource with the given id. If resource is not then the resource with default id is
101 * returned. If none can be found <code>null</code> is returned.
102 *
103 * @param id
104 * resource id
105 * @param defaultId
106 * default resource id
107 * @return resource object or default resource object or <code>null</code> if no resource with given id and default
108 * id is registered.
109 */
110 public IVisualResource getResource(String id, String defaultId);
111
112 /**
113 * Returns list of all resources marked with given tag. For more details see class java doc.
114 *
115 * @param tag
116 * tag which identifies resource family.
117 * @return list of resource associated with given tag; if no resources found an empty list is returned;
118 */
119 public List<IVisualResource> getResources(String tag);
120
121 }