# 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.

This is not an official release notes document.  It exists for Shiro developers
to jot down their notes while working in the source code.  These notes will be
combined with Jira's auto-generated release notes during a release for the
total set.

###########################################################
# 2.0 alpha 0
###########################################################

The 2.0 alpha 0 release's design goal is to introduce a much cleaner, more intuitive, more configurable API that is
even easier to understand and use than previous Shiro versions.

The design changes however introduce enough change such that there will be a decent amount of deprecation of old
concepts and implementations; the releases before 2.0.0 final will retain all of these 'legacy' concepts and
implementations to provide a smoother upgrade path for those trying alpha and beta releases.

2.0.0 final however will completely remove all deprecated interfaces, classes and methods to ensure a clean
codebase for the many years to come.

Design Changes
--------------------------------

- All of Shiro's SecurityManager implementations now require a CacheManager - it cannot be null.  Caching is still
  disabled by default however; the SecurityManager implementations just default to an
  org.apache.shiro.cache.DisabledCacheManager instance.  This reflects the Null Object design pattern, helping
  reducing cyclomatic complexity (and therefore the potential for bugs) in Shiro.

- org.apache.shiro.subject.PrincipalCollection has been deprecated and will be removed in 2.0 final.  This represents
  a big change, but for an extremely strong reason:

  Almost all Shiro end-users expect to be able to query a Subject's PrincipalCollection for identifying attributes,
  like a username, or first name, etc.  This is extraordinarily difficult with the PrincipalCollection API, which
  only allows users to acquire identity attributes _by type_.  If you had more than one attribute of the same
  type (e.g. a String username and a String surname), the PrincipalCollection is effectively useless, and you had to
  come up with all sorts of workarounds (like creating 'wrapper' objects) to obtain the data you needed.  Additionally
  these workarounds were not usable by any tools or frameworks that used reflection to lookup information.

  This was a huge problem, almost crippling in some cases, and so PrincipalCollection has been deprecated and
  replaced by a very simple 'attributes' map, of type Map<String,Object>.  This allows much cleaner code, like:

  subject.getAttributes().get("username");

  or, even simpler for Groovy or JSTL:

  subject.attributes['username']

  This change affords a huge number of simplifications/conveniences for the Shriro user community, dev team, and
  bean-compatible tools and frameworks.

- org.apache.shiro.authc.AuthenticationInfo (used widely by Realm implementations) has been deprecated and will be
  replaced by a brand new org.apache.shiro.account.Account interface.  This was done for three reasons:

  1. Account supports a getId() method, which allows explicit support for a data-store-unique account identifier.
     AuthenticationInfo did not have this, and id acquisition was implicit - not good for such a core Shiro concept.

  2. 'Account' is an inherently more intuitive name.  The < 2.0 'AuthenticationInfo' interface name actually always
     represented an Account, and the name 'AuthenticationInfo' is abstract and fairly unintuitive.  Now it is more
     obvious/explicit.

  3. Shiro's old PrincipalCollection concept is being removed.  Account instead represents principals with a
     new name, called 'attributes' as a simple Map<String,Object> collections, as described above.

  org.apache.shiro.authc.AuthenticationInfo is currently deprecated, but will be removed entirely when 2.0 final is
  released.

- The previously (very) complicated SecurityManager implementation hierarchy has been deprecated entirely:

  CachingSecurityManager < RealmSecurityManager < AuthenticatingSecurityManager < AuthorizingSecurityManager
      < SessionsSecurityManager < DefaultSecurityManager < DefaultWebSecurityManager

  An interim replacement, org.apache.shiro.mgt.ApplicationSecurityManager is the only SecurityManager implementation.
  All customization for this implementation can be done by customizing or plugging in its internal components.  This is
  now possible because the implementation much more heavily favors a "delegation over inheritance" best practice.
  This approach will allow much greater resilience to change over time and help keep Shiro's core SecurityManager
  codebase highly stable.

  Right before the 2.0 final release, ApplicationSecurityManager might be renamed to DefaultSecurityManager to adhere
  to all other existing default implementation naming conventions.  This just cannot be done prior to a 2.0 final
  release because it would be a backwards-incompatible change.

- For multi-realm authentication, the org.apache.shiro.authc.pam package and all of its internal
  org.apache.shiro.authc.pam.AuthenticationStrategy implementations have been deprecated in favor of the new
  org.apache.shiro.authc.strategy package.

  The new org.apache.shiro.authc.strategy.AuthenticationStrategy interface is much simpler - it is a single method that
  can perform all multi-realm interaction logic without compromise.

  The legacy org.apache.shiro.authc.pam.AuthenticationStrategy API and implementations suffered from an overly complex
  pre/before/after/post implementation requirement, and in some cases, entirely prevented some Strategy behavior from
  being implemented successfully.

  For example the org.apache.shiro.authc.pam.FirstSuccessfulStrategy did not
  short-circuit realm iteration (desired by most Shiro users) and the existing Strategy API provided no way to 'tell'
  the calling Authorizer how to stop iteration when things were successful.  The new Strategy API has no such problems,
  and is more holistic, allowing implementors exact control over the login attempt.

  Finally, the *Strategy implementations have been renamed to include the word 'Realm' in the name to more explicitly
  self-document what is occurring.

  For example, the class name 'FirstRealmSuccessfulStrategy' (in 2.0) is more intuitive than
  'FirstSuccessfulStrategy' in pre 2.0 (first *what* is successful?).  The 2.0 implementations naming scheme makes it
  very clear what is occurring.

- org.apache.shiro.authc.AuthenticationInfo (used widely by Realms) has been deprecated in favor of a

Deprecations (will be removed immediately before 2.0 final)
-----------------------------------------------------------

- org.apache.shiro.cache.Cache methods clear(), size() and keys() have been deprecated and will be removed before the
  2.0 final release.  These methods were never called by Shiro's components and caused an unnecessary implementation
  burden.

- org.apache.shiro.authc.credential.CredentialsMatcher doCredentialsMatch(AuthenticationToken, AuthenticationInfo)
  has been deprecated in favor of the new method (in the same interface):
  credentialsMatch(AuthenticationToken, Account) to reflect the new Account concept (discussed in 'Design Changes'
  above).

- org.apache.shiro.authc.credential.HashedCredentialsMatcher and all of its children implementations
  (Md5CredentialsMatcher, Sha256CredentialsMatcher, etc) have been deprecated and will be removed in 2.0 final.  The
  org.apache.shiro.authc.credential.PasswordMatcher and org.apache.shiro.authc.credential.PasswordService
  introduced in 1.2 perform all of these operations and more.

New Features / Implementations
--------------------------------
- org.apache.shiro.cache.DisabledCacheManager returns no-op implementations for all caching operations.  Mostly usable
  for the Null Object design pattern.


###########################################################
# 1.2.0
###########################################################

Backwards Incompatible Changes
--------------------------------
- The following org.apache.shiro.mgt.DefaultSecurityManager methods have been removed:
  bindPrincipalsToSession(principals, context)

  This logic has been moved into a SubjectDAO concept to allow end-users to control
  exactly how the Session may be used for subject state persistence.  This allows a
  single point of control rather than needing to configure Shiro in multiple places.

  If you overrode this method in Shiro 1.0 or 1.1, please look at the new
  org.apache.shiro.mgt.DefaultSubjectDAO implementation, which performs compatible logic.
  Documentation for this is covered here:
  http://shiro.apache.org/session-management.html#SessionManagement-SessionsandSubjectState

- The org.apache.shiro.web.session.mgt.ServletContainerSessionManager implementation
  (enabled by default for all web applications) no longer subclasses
  org.apache.shiro.session.mgt.AbstractSessionManager.  AbstractSessionManager existed
  originally to consolidate a 'globalSessionTimeout' configuration property for
  subclasses.  However, the ServletContainerSessionManager has been changed to always
  reflect the session configuration from web.xml (per its namesake).  Because web.xml
  is the definitive source for session timeout configuration, the 'extends' clause
  was removed to avoid configuration confusion: if someone attempted to configure
  'globalSessionTimeout' on a ServletContainerSessionManager instance, it would never
  be honored.  It was better to remove the extends clause to ensure that any
  such configuration would fail fast when Shiro starts up to reflect the invalid config.


Potential Breaking Changes
--------------------------------
- The org.apache.shiro.web.filter.mgt.FilterChainManager class's
  addFilter(String name, Filter filter) semantics have changed.  It now no longer
  attempts to initialize a filter by default before adding the filter to the chain.
  If you ever called this method, you can call the
  addFilter(name, filter, true) method to achieve the <= 1.1 behavior.

- The org.apache.shiro.crypto.SecureRandomNumberGenerator previously defaulted to generating
  128 random _bytes_ each time the nextBytes() method was called.  This is too large for most purposes, so the
  default has been changed to 16 _bytes_ (which equals 128 bits - what was originally intended).  If for some reason
  you need more than 16 bytes (128 bits) of randomly generated bits, you will need to configure the
  'defaultNextByteSize' property to match your desired size (in bytes, NOT bits).

- Shiro's Block Cipher Services (AesCipherService, BlowfishCipherService) have had the following changes:

  1) The internal Cipher Mode and Streaming Cipher Mode have been changed from CFB to the new default of CBC.
     CBC is more commonly used for block ciphers today (e.g. SSL).
     If you were using an AES or Blowfish CipherService you will want to revert to the previous defaults in your config
     to ensure you can still decrypt previously encrypted data.  For example, in code:

     blockCipherService.setMode(OperationMode.CFB);
     blockCipherService.setStreamingMode(OperationMode.CFB);

     or, in shiro.ini:

     blockCipherService.modeName = CFB
     blockCipherService.streamingModeName = CFB

  2) The internal Streaming Padding Scheme has been changed from NONE to PKCS5 as PKCS5 is more commonly used.
     If you were using an AES or Blowfish CipherService for streaming operations, you will want to revert to the
     previous padding scheme default to ensure you can still decrypt previously encrypted data.  For example, in code:

     blockCipherService.setStreamingPaddingScheme(PaddingScheme.NONE);

     or, in shiro.ini:

     blockCipherService.streamingPaddingSchemeName = NoPadding

     Note the difference in code vs shiro.ini in this last example: 'NoPadding' is the correct text value, 'NONE' is
     the correct Enum value.

###########################################################
# 1.1.0
###########################################################

Backwards Incompatible Changes
--------------------------------
- The org.apache.shiro.web.util.RedirectView class's
  appendQueryProperties(StringBuffer targetUrl, Map model, String encodingScheme)
  method has been changed to accept a StringBuilder argument instead of a
  StringBuffer per SHIRO-191.  RedirectView is considered an internal
  implementation support class and Shiro end-users should not be affected by this.