Repository: tapestry-5 Updated Branches: refs/heads/master 2c3e304f7 -> 7faf5f943
TAP5-2570 fix some javadoc errors related to Session State Object terminology Meanwhile updated license text to match http://www.apache.org/legal/src-headers.html#headers Project: http://git-wip-us.apache.org/repos/asf/tapestry-5/repo Commit: http://git-wip-us.apache.org/repos/asf/tapestry-5/commit/7faf5f94 Tree: http://git-wip-us.apache.org/repos/asf/tapestry-5/tree/7faf5f94 Diff: http://git-wip-us.apache.org/repos/asf/tapestry-5/diff/7faf5f94 Branch: refs/heads/master Commit: 7faf5f943301d5500538ce75593b1b324e5e9a65 Parents: 2c3e304 Author: Bob Harner <[email protected]> Authored: Sat Jan 14 14:42:37 2017 -0500 Committer: Bob Harner <[email protected]> Committed: Sat Jan 14 14:42:37 2017 -0500 ---------------------------------------------------------------------- .../tapestry5/annotations/SessionState.java | 53 +++++++++++--------- .../services/ApplicationStateCreator.java | 38 ++++++++------ .../services/ApplicationStateManager.java | 48 +++++++++++------- .../ApplicationStatePersistenceStrategy.java | 37 ++++++++------ ...plicationStatePersistenceStrategySource.java | 36 ++++++++----- 5 files changed, 128 insertions(+), 84 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tapestry-5/blob/7faf5f94/tapestry-core/src/main/java/org/apache/tapestry5/annotations/SessionState.java ---------------------------------------------------------------------- diff --git a/tapestry-core/src/main/java/org/apache/tapestry5/annotations/SessionState.java b/tapestry-core/src/main/java/org/apache/tapestry5/annotations/SessionState.java index d9366cc..a94697e 100644 --- a/tapestry-core/src/main/java/org/apache/tapestry5/annotations/SessionState.java +++ b/tapestry-core/src/main/java/org/apache/tapestry5/annotations/SessionState.java @@ -1,14 +1,19 @@ -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at // -// http://www.apache.org/licenses/LICENSE-2.0 +// http://www.apache.org/licenses/LICENSE-2.0 // -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. package org.apache.tapestry5.annotations; @@ -23,20 +28,22 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; import static org.apache.tapestry5.ioc.annotations.AnnotationUseContext.*; /** - * Marker annotation for a field that is a <em>session state object</em> (SSO) as controlled by the {@link - * org.apache.tapestry5.services.ApplicationStateManager}. An SSO stored as global session object (i.e., in the {@link - * javax.servlet.ServletContext}); every page or component. In fact, the built-in strategies for ASO management are - * <em>very</em> user specific, ultimately storing data in the {@link org.apache.tapestry5.services.Session}. - * - * An SSO field may have a companion field, of type boolean, used to see if the SSO has been created yet. If another - * field exists with the same name, suffixed with "Exists" (i.e., "sso" for the SSO field, and "ssoExists" for the - * companion field) and the type of that field is boolean, then access to the field will determine whether the SSO has - * already been created. This is necessary because even a null check ("sso != null") may force the SSO to be created. - * Instead, check the companion boolean field ("asoExists"). - * - * Note: Tapestry 5.0 called these objects "Application State Objects"; thus many of the underlying services have a - * confusing name (ApplicationStateManager, which really should be SessionStateManager ... but can't be renamed for - * backwards compatibility reasons). + * Marker annotation for a property that is a <em>session state object</em> (SSO) as controlled by + * the {@link org.apache.tapestry5.services.ApplicationStateManager}. An SSO property is stored as + * global session object (i.e., in the {@link javax.servlet.ServletContext}), accessible to every + * page or component, but in fact the built-in strategies for SSO management are + * session-specific, ultimately storing data in the {@link org.apache.tapestry5.services.Session}. + * <p> + * For each SSO property, you may declare a companion boolean property that can be checked to see if + * the SSO has been created yet. The companion boolean property must have the same name as the SSO + * property but suffixed with "Exists" (e.g., an SSO property named "user" and a companion boolean + * property named "userExists"). You can access the boolean property to determine whether the SSO + * has already been created. This mechanism is necessary because even a null check ("user != null") + * may force the SSO to be created. Instead, check the companion boolean field ("userExists"). + * <p> + * <em>Note: Tapestry 5.0 called these objects "Application State Objects"; thus some of the underlying + * services have confusing names (e.g., ApplicationStateManager, which really should be SessionStateManager) + * but can't be renamed for backward compatibility reasons.</em> * * @since 5.1.0.4 */ http://git-wip-us.apache.org/repos/asf/tapestry-5/blob/7faf5f94/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStateCreator.java ---------------------------------------------------------------------- diff --git a/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStateCreator.java b/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStateCreator.java index 7e4d2de..47ce8f8 100644 --- a/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStateCreator.java +++ b/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStateCreator.java @@ -1,29 +1,37 @@ -// Copyright 2007 The Apache Software Foundation +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at // -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at +// http://www.apache.org/licenses/LICENSE-2.0 // -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. package org.apache.tapestry5.services; /** - * Used by {@link ApplicationStateManager} and {@link ApplicationStatePersistenceStrategy} to create an application - * state object on demand. - * + * Used by {@link ApplicationStateManager} and {@link ApplicationStatePersistenceStrategy} to create + * a Session State Object (SSO) on demand. + * <p> + * <em>NOTE: The term "Application" here is a hold-over from Tapestry 5.0, which used + * the @ApplicationState (deprecated and deleted) annotation, and called them "ASOs" + * (Application State Objects). This service would be better named "SessionStateCreator" + * (but renaming it would cause backwards compatibility issues).</em> + * * @param <T> */ public interface ApplicationStateCreator<T> { /** - * Create a new instance of an application state object. + * Create a new instance of a session state object. */ T create(); } http://git-wip-us.apache.org/repos/asf/tapestry-5/blob/7faf5f94/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStateManager.java ---------------------------------------------------------------------- diff --git a/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStateManager.java b/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStateManager.java index f3f943f..53f5af1 100644 --- a/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStateManager.java +++ b/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStateManager.java @@ -1,14 +1,19 @@ -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. package org.apache.tapestry5.services; @@ -16,17 +21,22 @@ import org.apache.tapestry5.ioc.ObjectLocator; import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration; /** - * Responsible for managing <em>session state objects</em>, objects which persist between requests, but are not tied to - * any individual page or component. SSOs are also created on demand. SSOs are typically stored in the session, so that - * they are specific to a particular client. - * - * The term "Application" is a hold-over from Tapestry 5.0, which used the @ApplicationState (deprecated and deleted) - * annotation, and called them "ASOs" (Application State Objects). This service would be better named - * "SessionStateManager" (but renaming it would cause backwards compatibility issues). - * - * Tapestry has a built-in default strategy for storing SSOs (in the session) and instantiating them. If desired, - * contributions to the service configuration can override the default behavior, either specifying an alternate storage - * strategy, or an alternate {@linkplain org.apache.tapestry5.services.ApplicationStateCreator creation strategy}. + * Responsible for managing <em>Session State Objects</em> (SSO), objects which persist between + * requests but are not tied to + * any individual page or component. SSOs are typically stored in the session, so that + * they are specific to a particular user. + * <p> + * SSOs are created on demand. + * <p> + * Tapestry has a built-in default strategy for storing SSOs (in the session) and instantiating + * them. If desired, contributions to the service configuration can override the default behavior, + * either specifying an alternate storage strategy, or an alternate + * {@linkplain org.apache.tapestry5.services.ApplicationStateCreator creation strategy}. + * <p> + * <em>NOTE: The term "Application" here is a hold-over from Tapestry 5.0, which used + * the @ApplicationState (deprecated and deleted) annotation, and called them "ASOs" + * (Application State Objects). This service would be better named "SessionStateManager" + * (but renaming it would cause backwards compatibility issues).</em> * * @see org.apache.tapestry5.annotations.SessionState */ http://git-wip-us.apache.org/repos/asf/tapestry-5/blob/7faf5f94/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStatePersistenceStrategy.java ---------------------------------------------------------------------- diff --git a/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStatePersistenceStrategy.java b/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStatePersistenceStrategy.java index c6f5e87..c454f04 100644 --- a/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStatePersistenceStrategy.java +++ b/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStatePersistenceStrategy.java @@ -1,29 +1,38 @@ -// Copyright 2007, 2008 The Apache Software Foundation +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at // -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at +// http://www.apache.org/licenses/LICENSE-2.0 // -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. package org.apache.tapestry5.services; /** - * Used by {@link ApplicationStateManager} to manage a specific kind of Session State Object (SSO) persistence. The - * stategy is responsible for managing SSO instances within its domain. + * Used by {@link ApplicationStateManager} to manage a specific kind of Session State Object (SSO) + * persistence. The + * strategy is responsible for managing SSO instances within its domain. + * <p> + * <em>NOTE: The term "Application" here is a hold-over from Tapestry 5.0, which used the @ApplicationState + * (deprecated and deleted) annotation, and called them "ASOs" (Application State Objects). This service + * would be better named "SessionStatePersistenceStrategy" (but renaming it would cause backwards + * compatibility issues).</em> * * @see org.apache.tapestry5.services.ApplicationStatePersistenceStrategySource */ public interface ApplicationStatePersistenceStrategy { /** - * Gets the SSO from the domain. If the ASO does not already exist, it is created and stored, then returned. + * Gets the SSO from the domain. If the SSO does not already exist, it is created and stored, then returned. */ <T> T get(Class<T> ssoClass, ApplicationStateCreator<T> creator); http://git-wip-us.apache.org/repos/asf/tapestry-5/blob/7faf5f94/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStatePersistenceStrategySource.java ---------------------------------------------------------------------- diff --git a/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStatePersistenceStrategySource.java b/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStatePersistenceStrategySource.java index ad93fb7..7dbf3a0 100644 --- a/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStatePersistenceStrategySource.java +++ b/tapestry-core/src/main/java/org/apache/tapestry5/services/ApplicationStatePersistenceStrategySource.java @@ -1,24 +1,34 @@ -// Copyright 2007, 2008 The Apache Software Foundation +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at // -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at +// http://www.apache.org/licenses/LICENSE-2.0 // -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. package org.apache.tapestry5.services; import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration; /** - * Used to provide access to {@link org.apache.tapestry5.services.ApplicationStatePersistenceStrategySource} instances - * via a logical name for the stategy, such as "session". + * Used to provide access to + * {@link org.apache.tapestry5.services.ApplicationStatePersistenceStrategySource} instances + * via a logical name for the strategy, such as "session". + * <p> + * <em>NOTE: The term "Application" here is a hold-over from Tapestry 5.0, which used + * the @ApplicationState (deprecated and deleted) annotation, and called them "ASOs" + * (Application State Objects). This service would be better named + * "SessionStatePersistenceStrategySource" (but renaming it would cause backwards + * compatibility issues).</em> */ @UsesMappedConfiguration(ApplicationStatePersistenceStrategy.class) public interface ApplicationStatePersistenceStrategySource
