1 package com.sourceforge.jpatterns.core;
2
3 import com.sourceforge.jpatterns.patterns.IJPattern;
4 import com.sourceforge.jpatterns.patterns.config.IJPConfig;
5 import com.sourceforge.jpatterns.patterns.factory.IJPFactory;
6
7 /**
8 * It is an entry point for all the operations with JPatterns framework from the side of the consumer of this framework. This interface
9 * defines the methods which would be useful for working with the JPattern. Usually only this class would be used. The implementation of
10 * this interface could be customized (study appropriate documentation on the customization).
11 * <br/>
12 * The methods are represented here would return the implementations of the certain patterns:
13 * e.g. <code>IFactory</code>, <code>IChain</code> etc. Also they could return some additional stuff.
14 * <br/>
15 * Please access this functionality using {@link com.sourceforge.jpatterns.core.JPEngineFactory} - it is the only entry point for working
16 * with implementations of <code>IJPEngine</code> interface.
17 * <br/>
18 * All the stuff of the JPatterns configuration would be initialized at the static initialization so just access this class trough the
19 * appropriate factory.
20 * todo [zmicer]: method for the global configuration to be put here.
21 * note [zmicer]: be noticed this interface and the implementation are used for both consumer and framework specific operations.
22 * <p/>
23 * $Author:: zmicer $<br/>
24 * $Rev:: 67 $<br/> * $Date:: 2007-08-28 21:37:07 #$<br/>
25 * $Date:: 2007-08-28 21:37:07 #$<br/>
26 */
27 public interface IJPEngine
28 {
29 /**
30 * Set the JPatterns engine category type - it could be consumer, framework related etc. It defines the purposes it would be used.
31 *
32 * @param category instance of JPConstants.EngineConfigCaregory, Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
33 */
34 void init(JPConstants.EngineConfigCaregory category);
35
36 /**
37 * @return the JPatterns engine category. In the case it is not initialized - null would be returned
38 */
39 JPConstants.EngineConfigCaregory getCategory();
40
41 /**
42 * @return true if the instance is initialized, false otherwise. For now the presence of the category set only influence on this, but in the
43 * future it could be changed
44 */
45 boolean isInitialized();
46
47 /**
48 * Get the IJPFactory using the provided name and the scope. Please be noticed in the case the scope is not specified the following
49 * constant is used as the scope id:
50 * (<code>com.sourceforge.jpatterns.core.JPConstants.DEFAULT_SCOPE_NAME</code>)
51 * <br/>
52 * Please be noticed that the factory returned using the provided scope name, may contains the items(implementation mappings) different
53 * then this scope provided. It takes place in the case when the factory has the default scope, and has the items with different scopes
54 * - all of them would be accesible through this factory (having the different scope).
55 * <br/>
56 * Throws JPInitializationException in the case it is not initialized
57 *
58 * @param factoryName the name of the factory to be retrieved.
59 * Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
60 * @param scope scope name to be used for the retrieving of the appropriate factory. Could be null, in the case the default scope
61 * would be used.
62 *
63 * @return the IJPFactory instance to be used later.
64 */
65 IJPFactory getFactory(final String factoryName, final String scope);
66
67 /**
68 * Get the IJPattern using the provided name and the scope. Please be noticed in the case the scope is not specified the following
69 * constant is used as the scope id:
70 * (<code>com.sourceforge.jpatterns.core.JPConstants.DEFAULT_SCOPE_NAME</code>)
71 * <br/>
72 * Be noticed that the pattern returned using the provided scope name, may contains the items(implementation mappings) different
73 * then this scope provided.
74 * <br/>
75 * Throws JPInitializationException in the case it is not initialized
76 *
77 * @param patternName the name of the pattern to be retrieved.
78 * Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
79 * @param scope scope name to be used for the retrieving of the appropriate pattern. Could be null, in the case the default scope
80 * would be used.
81 *
82 * @return the IJPattern instance to be used later.
83 */
84 IJPattern getPattern(final String patternName, final String scope);
85
86 /**
87 * Get the config pattern
88 *
89 * @param configName the name of the config pattern, Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
90 * @param scope the name of the config scope, Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
91 *
92 * @return the IJPConfig instance.
93 */
94 IJPConfig getConfig(final String configName, final String scope);
95 }