001: /*
002: * Copyright 2001-2006 C:1 Financial Services GmbH
003: *
004: * This software is free software; you can redistribute it and/or
005: * modify it under the terms of the GNU Lesser General Public
006: * License Version 2.1, as published by the Free Software Foundation.
007: *
008: * This software is distributed in the hope that it will be useful,
009: * but WITHOUT ANY WARRANTY; without even the implied warranty of
010: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
011: * Lesser General Public License for more details.
012: *
013: * You should have received a copy of the GNU Lesser General Public
014: * License along with this library; if not, write to the Free Software
015: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
016: */
017:
018: package de.finix.contelligent;
019:
020: import java.util.*;
021: import java.io.*;
022:
023: import javax.naming.NamingException;
024: import javax.servlet.http.Cookie;
025: import javax.sql.DataSource;
026: import javax.transaction.HeuristicMixedException;
027: import javax.transaction.HeuristicRollbackException;
028: import javax.transaction.RollbackException;
029: import javax.transaction.SystemException;
030:
031: import org.xml.sax.SAXException;
032:
033: import de.finix.contelligent.category.CategoryManager;
034: import de.finix.contelligent.core.ComponentManagerHierarchy;
035: import de.finix.contelligent.RelationsManager;
036: import de.finix.contelligent.core.security.User;
037: import de.finix.contelligent.exception.ContelligentException;
038: import de.finix.contelligent.exception.ContelligentSecurityException;
039: import de.finix.contelligent.exception.AlreadyLoggedInWarning;
040: import de.finix.contelligent.search.engine.SearchEngine;
041:
042: /**
043: * The main interface for Contelligent session and transaction control. Any
044: * implementation must be accessible by multiple threads concurently! <BR>
045: * Because components are usually called via the main servlet which
046: * automatically handles the transaction as well as creation of session and
047: * calldata they will never need to use this interface under normal
048: * circumstances. <BR>
049: * Manual session/transaction handling works as follows:
050: *
051: * <PRE>
052: *
053: * Contelligent contelligent = ContelligentImpl.getInstance() Session s =
054: * contelligent.beginSession("user", "group", "password"); CallData c =
055: * contelligent.createCallData(s); contelligent.beginTx(); // do anything within
056: * tx1 passing calldata c to methods ... contelligent.commitTx(); // no tx ...
057: * CallData c2 = contelligent.createCallData(s); contelligent.beginTx(); // do
058: * anything within tx2 passing calldata c2 to methods ...
059: * contelligent.commitTx(); contelligent.invalidateSession(s);
060: *
061: * </PRE>
062: */
063: public interface Contelligent {
064:
065: public final static String EXT_MARKUP = ".html";
066:
067: public final static String EXT_ACTION = ".act";
068:
069: public final static String EXT_BINARY = ".cstr";
070:
071: public final static String ENV_DATASOURCE = "jdbc/DataSource";
072:
073: public final static String ENV_DATASOURCE_NO_TX = "jdbc/DataSourceNoTx";
074:
075: public final static String ENV_CONTELLIGENT_DIR = "contelligentDir";
076:
077: public final static String ENV_SERVERMODE = "serverMode";
078:
079: public final static String JNDI_USERTRANSACTION = "java:comp/UserTransaction";
080:
081: public final static String SERVERMODE_WLS51 = "WLS51";
082:
083: public final static char MANAGER_NAMESEPARATOR = '.';
084:
085: public final static String DIR_INDEX = "/index/";
086:
087: public final static String DIR_SYSINDEX = "/sysindex/";
088:
089: public final static String DIR_INDEX_BUILD = "/buildIndex/";
090:
091: public final static String DIR_REVISION = "/revision/";
092:
093: public final static String DIR_LOG = "/log/";
094:
095: public final static String DIR_UPLOAD = "/upload/";
096:
097: public final static String DIR_PACKAGES = "/packages/";
098:
099: public final static String DIR_CONFIG = "/config/";
100:
101: public final static String DIR_WORK = "/work/";
102:
103: public final static String DIR_WORKFLOW = "/workflow/";
104:
105: public final static String PKG_DESCRIPTION = "META-INF/package.xml";
106:
107: public final static String PKG_EXTENSION = ".cpkg";
108:
109: public final static String MAIN_CONFIGURATION_FILE = "main.xml";
110:
111: public final static String JMX_CONFIGURATION_FILE = "contelligent-mbean.xml";
112:
113: public final static String PROJECT_CONFIGURATION_FILE = "project.xml";
114:
115: public final static String LOG_CONFIGURATION_FILE = "logging-conf.xml";
116:
117: public final static String CTL_LICENSE_FILE = "main_license.xml";
118:
119: public final static String CONTELLIGENT_SESSION_COOKIE = "cSession";
120:
121: public final static String PREVIEW_MODE = "previewMode";
122:
123: public final static String EDIT = "edit";
124:
125: public final static String PREVIEW_CONFIG = "previewConfig";
126:
127: public final static String PREVIEW_DATE = "previewDate";
128:
129: /** all files inside of a package must reside underneath this subdirectory */
130: final static String PKG_FILES_DIR = "META-INF/files";
131:
132: public final String WORKFLOW_DEFINITION_TYPE = "contelligent.configuration.WorkflowDefinition";
133:
134: public final static int RESOURCEGROUP_CONTENT = 0;
135:
136: public final static int RESOURCEGROUP_TEMPLATE = 1;
137:
138: public static final String PREVIEW_USERPRINCIPAL = "__previewgroup__:__previewuser__";
139:
140: /**
141: * Returns a newly created session and authenticates the given user using
142: * the specified password. The created session contains an empty
143: * category-map.
144: *
145: * @param userId
146: * the id of the user (unique among the group)
147: * @param groupId
148: * the id if the group the user belongs to
149: * @param password
150: * the user's password (XXX: encrypted?)
151: * @return a <code>Session</code> value
152: * @exception SessionCreationException
153: * if the session could not be created
154: * @exception ContelligentSecurityException
155: * if the user could not be authenticated
156: */
157: Session beginSession(String userId, String groupId, String password)
158: throws SessionCreationException,
159: ContelligentSecurityException;
160:
161: /**
162: * Returns a newly created session instance for the user specified by the
163: * given cookie. If the associated
164: * {@link de.finix.contelligent.core.security.UserGroup} does not support
165: * automatic login via cookies a <code>ContelligentSecurityException</code>
166: * is thrown.
167: *
168: * @param cookie
169: * a <code>Cookie</code> value
170: * @return a <code>Session</code> value
171: * @exception SessionCreationException
172: * if the session could not be created
173: * @exception ContelligentSecurityException
174: * if the user could not be authenticated
175: * @see de.finix.contelligent.core.security.AutologinCookie
176: */
177: Session beginSession(Cookie cookie)
178: throws SessionCreationException,
179: ContelligentSecurityException;
180:
181: /**
182: * Returns a newly created session instance for the given user.
183: *
184: * @param user
185: * an <code>User</code> value
186: * @param manager
187: * a <code>ComponentManager</code> value
188: * @return a <code>Session</code> value
189: * @exception SessionCreationException
190: * if an error occurs
191: */
192: Session beginSession(User user, ComponentManager manager)
193: throws SessionCreationException;
194:
195: /**
196: * Changes the user in the given session to the one specified by parameters
197: * <tt>userId</tt>, <tt>groupId</tt> and <tt>password</tt>. If now
198: * such user exists or an authentication error occurs a
199: * <code>ContelligentSecurityException</code> is thrown.
200: *
201: * @param session
202: * a <code>Session</code> value
203: * @param userId
204: * a <code>String</code> value
205: * @param groupId
206: * a <code>String</code> value
207: * @param password
208: * a <code>String</code> value
209: * @exception ContelligentException
210: * if an error occurs
211: * @exception ContelligentSecurityException
212: * if an error occurs
213: */
214: void changeUser(Session session, String userId, String groupId,
215: String password) throws ContelligentException,
216: ContelligentSecurityException;
217:
218: /**
219: * Returns the Contelligent session associated with the given id or null if
220: * no session with this id exists.
221: *
222: * @param sessionId
223: * a <code>String</code> value
224: * @return a <code>Session</code> value
225: */
226: Session getSession(String sessionId);
227:
228: /**
229: * Returns a collection of all {@link Session sessions} which are currently
230: * {@link Session#isClientSession associated with a client}.
231: *
232: * @return a <code>Collection</code> of {@link Session} instances
233: */
234: Collection getClientSessions();
235:
236: /**
237: * method to get statistic information of the contelligent server
238: *
239: * @return number of currently open sessions
240: */
241: public int getNumberOfSessions();
242:
243: /**
244: * Marks the given session so it is associated with a client.
245: *
246: * @param sessionId
247: * a <code>String</code> value
248: */
249: void markAsClientSession(String sessionId)
250: throws AlreadyLoggedInWarning,
251: MaxClientSessionsExceededException;
252:
253: /**
254: * Notifies all currently registered clients about the given events.
255: *
256: * @param eventList
257: * a <code>List</code> of
258: * {@link de.finix.contelligent.event.ContelligentEvent}
259: * instances
260: */
261: void notifyAllClientSessions(List eventList);
262:
263: /**
264: * Invalidates the given session.
265: */
266: void invalidateSession(Session session);
267:
268: /**
269: * Removes the given session from client sessions and calls
270: * {@link de.finix.contelligent.core.ContelligentSession#reset}.
271: *
272: * @param session
273: * a <code>Session</code> value
274: */
275: void resetSession(Session session);
276:
277: /**
278: * Creates a new {@link CallData} instance using the specified session.
279: *
280: * @param session
281: * a <code>Session</code> value
282: * @return a <code>CallData</code> value
283: */
284: CallData createCallData(Session session);
285:
286: /**
287: * Creates a new {@link CallData} instance using the specified session and
288: * category-map.
289: *
290: * @param session
291: * a <code>Session</code> value
292: * @param categoryMap
293: * a <code>Map</code> value
294: * @return a <code>CallData</code> value
295: */
296: CallData createCallData(Session session, Map categoryMap);
297:
298: /**
299: * Changes the {@link ComponentManager} associated with the current session
300: * to the specified one.
301: *
302: * @param callData
303: * a <code>CallData</code> value
304: * @param manager
305: * a <code>ComponentManager</code> value
306: */
307: void changeCM(CallData callData, ComponentManager manager);
308:
309: /**
310: * Changes the {@link ComponentManager} associated with the current session
311: * to the one specified by <tt>managerId</tt>. If no such manager exists
312: * a RuntimException is thrown.
313: *
314: * @param callData
315: * a <code>CallData</code> value
316: * @param managerId
317: * a <code>long</code> value
318: * @exception IllegalArgumentException
319: * if the specified manager does not exists
320: */
321: void changeCM(CallData callData, long managerId);
322:
323: /**
324: * Starts a new transaction using the default-timeout configured in
325: * main.xml. (NOT the server default!) If there is alread an active
326: * transaction no transaction is started.
327: *
328: * @return true if a new transaction was started.
329: */
330: boolean beginTx() throws SystemException;
331:
332: /**
333: * Starts a new transaction with the given timeout if there is no active
334: * transaction associated with the current thread yet.
335: *
336: * @param timeout
337: * the transaction timeout in seconds
338: * @return true if a new transaction was started.
339: * @exception SystemException
340: * if an error occurs
341: */
342: boolean beginTx(int timeout) throws SystemException;
343:
344: /**
345: * Returns the status of the transaction associated with the current thread.
346: *
347: * @return an <code>int</code> value
348: */
349: int getTxStatus();
350:
351: /**
352: * Returns the status of the transaction associated with the current thread
353: * as string.
354: *
355: * @return a <code>String</code> value
356: */
357: String txStatusToString();
358:
359: /**
360: * Completes the transaction associated with the current thread. If the
361: * transaction is marked for rollback either direct or by calling
362: * {@link CallData#markForRollback} the transaction is rolled back.
363: *
364: * @exception SystemException
365: * if an error occurs
366: * @exception RollbackException
367: * if an error occurs
368: * @exception HeuristicMixedException
369: * if an error occurs
370: * @exception HeuristicRollbackException
371: * if an error occurs
372: * @exception SecurityException
373: * if an error occurs
374: * @exception IllegalStateException
375: * if an error occurs
376: * @see Transaction#commit
377: */
378: void commitTx() throws SystemException, RollbackException,
379: HeuristicMixedException, HeuristicRollbackException,
380: SecurityException, IllegalStateException;
381:
382: /**
383: * Roll back the transaction associated with the current thread.
384: *
385: * @exception SystemException
386: * if an error occurs
387: * @exception SecurityException
388: * if an error occurs
389: * @exception IllegalStateException
390: * if an error occurs
391: * @see Transaction#rollback
392: */
393: void rollbackTx() throws SystemException, SecurityException,
394: IllegalStateException;
395:
396: /**
397: * Returns the default transaction timeout.
398: *
399: * @return the transaction timeout in seconds.
400: */
401: int getDefaultTransactionTimeout();
402:
403: // ---------------------------------------------------------------------------------------
404:
405: /**
406: * Returns a <code>String</code> containing the description of the
407: * Contelligent system as XML. <BR>
408: * Note that the string will NOT contain a trailing
409: *
410: * <pre>
411: * <?xml version=\"1.0\"?>
412: * </pre>
413: *
414: * phrase so it may easily be intergrated into other XML documents.
415: *
416: * @return a <code>String</code> value
417: */
418: String getInfo();
419:
420: /**
421: * Returns the root {@link ComponentManager}. It is guaranteed that if the
422: * Contelligent system has been properly initialized this method never
423: * returns null.
424: *
425: * @return a <code>ComponentManager</code> value
426: */
427: ComponentManager getRootComponentManager();
428:
429: /**
430: * Returns the omponent-manager with the given name or null if no such
431: * manager exists. Note that this method is synchronized except if the given
432: * name matches the one of the root manager.
433: *
434: * @param name
435: * a <code>String</code> value
436: * @return a <code>ComponentManager</code> value
437: */
438: ComponentManager getComponentManager(String name);
439:
440: /**
441: * Returns the name of the component-manager with the given id. If no such
442: * manager exists a RuntimException is thrown.
443: *
444: * @exception IllegalArgumentException
445: * if the specified manager does not exists
446: */
447: String getComponentManagerName(long id);
448:
449: /**
450: * Returns the {@link ComponentManagerHierarchy}.
451: *
452: * @return a <code>ComponentManagerHierarchy</code> value
453: */
454: ComponentManagerHierarchy getComponentManagerHierarchy();
455:
456: /**
457: * returns the {@link RelationsManagerImpl}.
458: *
459: * @return a <code>RelationsManagerImpl</code> value
460: */
461: RelationsManager getRelationsManager();
462:
463: /**
464: * Returns the {@link CategoryManager}.
465: *
466: * @return a <code>CategoryManager</code> value
467: */
468: CategoryManager getCategoryManager();
469:
470: /**
471: * Returns the local directory the Contelligent system uses.
472: *
473: * @return a <code>String</code> value
474: */
475: String getContelligentDir();
476:
477: String getContelligentDir(String subdir);
478:
479: String getHTTPSPort();
480:
481: String getHTTPPort();
482:
483: boolean supportSecureComponents();
484:
485: /**
486: * Answer the maximum length of binary resouces cached in memory.
487: *
488: * @return
489: */
490: int getSmallBinaryThreshold();
491:
492: // ---------------------------------------------------------------------------------------
493:
494: Object lookupEnvironment(String name) throws NamingException;
495:
496: ClassLoader getComponentClassLoader();
497:
498: Properties getProperties();
499:
500: String getProperty(String key);
501:
502: String getProperty(String key, String def);
503:
504: void setProperty(String key, String value);
505:
506: String getContelligentMode();
507:
508: boolean isInDevelopmentMode();
509:
510: DataSource getXADataSource() throws NamingException;
511:
512: DataSource getDataSource() throws NamingException;
513:
514: SearchEngine getSearchEngine();
515:
516: /**
517: * Returns a string representation of the given component using either an
518: * associated {@link de.finix.contelligent.render.Renderer} or the
519: * {@link de.finix.contelligent.render.DefaultRenderer}. If the component
520: * is not renderable or if an exception occurs during the render process an
521: * empty string is returned.
522: *
523: * @param component
524: * a <code>Component</code> value
525: * @param callData
526: * a <code>CallData</code> value
527: * @return a <code>String</code> value
528: */
529: String render(Component component, CallData callData);
530:
531: /**
532: * Add public dirs. This is not synchronized so it may only be used during
533: * startup.
534: *
535: * @param dirs
536: */
537: void addPublicDirs(Collection dirs);
538:
539: void addPrivateDirs(Collection dirs);
540:
541: boolean isInPublicDir(ComponentPath path);
542:
543: boolean hasSystemIndex();
544:
545: boolean hasWorkflow();
546:
547: boolean isReadOnly();
548:
549: String getLocalizedString(String key, Locale locale);
550:
551: String getServletMapping();
552:
553: void configurePreview(ComponentPath config, String previewDate,
554: Session session, CallData callData)
555: throws ContelligentException, IOException, SAXException;
556:
557: public String getDefaultEncoding();
558:
559: public String getParameterEncoding();
560:
561: public boolean isAvailable();
562: }
|