View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  
20  package org.apache.myfaces.orchestra;
21  
22  /**
23   * A place to define all the configuration constants that can be used to
24   * configure parts of Orchestra core.
25   * 
26   * @since 1.1
27   */
28  public final class CoreConfig
29  {
30      private static final String BASE = CoreConfig.class.getName();
31  
32      /**
33       * Value "org.apache.myfaces.orchestra.CoreConfig:SERIALIZE_REQUESTS".
34       * <p>
35       * Controls whether two threads are prevented from accessing the same
36       * ConversationContext concurrently, or not. This is generally a bad idea as it
37       * can lead to ugly race conditions, so it is TRUE by default.
38       * <p>
39       * It is possible for multiple requests associated with the same http session to be
40       * received concurrently. By default, a servlet engine simply processes all requests
41       * concurrently in different threads. However that can cause all sorts of unexpected
42       * problems with objects in scopes that are visible to both threads (session-scoped
43       * and conversation-scoped objects).
44       * <p>
45       * When enabled, this option will block the thread for any request which will
46       * access the same Orchestra ConversationContext as a thread that is already
47       * running, and release it only when the earlier request has completed. This protects
48       * all orchestra conversation-scoped objects from concurrent access, but
49       * <i>does not</i> protect any session-scoped objects.
50       * <p>
51       * When using Orchestra, it is recommended that session-scoped objects are avoided
52       * conversation-scoped beans used instead. If there is no session-scoped data in
53       * use by an application then it is safe to allow concurrent requests to the
54       * same http session. If you do wish to protect normal session-scoped objects as
55       * well, then the standard solution is to write a filter that uses standard java
56       * synchronisation on a session-scoped object, taking the lock on request entry
57       * and releasing it on request exit.
58       * <p>
59       * Note that the expression "serialize requests" as used here means requests are
60       * processed serially, ie one after the other rather than concurrently. This has
61       * nothing to do with java.io.Serializable.
62       */
63      public static final String SERIALIZE_REQUESTS = BASE + ":SERIALIZE_REQUESTS";
64  
65      /**
66       * Value "org.apache.myfaces.orchestra.CoreConfig:CLEANUP_CONNECTIONS".
67       * <p>
68       * Controls whether Orchestra should monitor the set of JDBC connections borrowed
69       * during a request, and clean up any that are still open at the end of the request.
70       * <p>
71       * Orchestra provides a special DataSource wrapper that can be configured for any
72       * datasource used by the application. The datasource simply wraps all real Connection
73       * objects it returns in a proxy, and keeps track of them. At the end of each request,
74       * any connections borrowed by this thread but not returned can be returned
75       * automatically. See ConnectionManagerDataSource for more details.
76       * <p>
77       * If this special DataSource is not configured, then checking for unreleased
78       * connections is harmless, and always finds nothing. Therefore this option is
79       * enabled by default. 
80       */
81      public static final String CLEANUP_CONNECTIONS = BASE + ":CLEANUP_CONNECTIONS";
82  
83      /**
84       * Value "org.apache.myfaces.orchestra.CoreConfig:CONVERSATION_MESSAGER".
85       * <p>
86       * Controls what class is used to present Orchestra-related error messages to
87       * the user. When not specified, the default implementation for the current 
88       * FrameworkAdapter (eg JsfFrameworkAdapter) is used.
89       * <p>
90       * See class ConversationMessager for further details.
91       */
92      public static final String CONVERSATION_MESSAGER = BASE + ":CONVERSATION_MESSAGER";
93  }