diff --git a/dist/src/assembly/upgrading.txt b/dist/src/assembly/upgrading.txt index 2b4215b2..9f4c5be1 100644 --- a/dist/src/assembly/upgrading.txt +++ b/dist/src/assembly/upgrading.txt @@ -2,9 +2,7 @@ Upgrading Stripes http://www.stripesframework.org/ This file documents the steps involved in upgrading an application from Stripes -1.4.x to Stripes 1.5. Since Stripes 1.0-1.4.3 have been backwards compatible it -should be possible to apple these steps to upgrade to Stripes 1.5 from earlier -versions also. +1.6.0 to Stripes 1.6.0-Jakarta. Contents -------- @@ -18,151 +16,26 @@ Contents of the distribution. -> Replace your existing commons-logging.jar with the new copy from the lib/ directory of the distribution - -> If you are using commons-fileupload download the latest version from the - apache website http://commons.apache.org/downloads/download_fileupload.cgi - -> Address backward compatibilities listed in section 3 as necessary - -2. Suggested Steps - -------------- - One significant new feature in Stripes 1.5 that you may wish to leverage at upgrade - time is the concept of "Extension Packages". Using this feature you can inform Stripes - of one or more extension packages, e.g.: - - Extension.Packages - com.myco.myapp.web.stripesext - - - If one or more packages are specified Stripes will search these packages for classes - that implement various interfaces and wire them up without requiring you to configure - them manually in web.xml. This includes custom: - -> ActionBeanContext classes - -> Interceptor classes - -> ConfigurableComponent classes (e.g. ActionResolvers, LocalePickers) - -> Formatter classes - -> TypeConverter classes - - To reduce your configuration it is recommended that you move any and all such - custom classes into a single package hierarchy and specify the root package. Once - done you can remove all web.xml configuration for these custom classes. - -3. Backwards Incompatibilities + -> For security reasons, Log4jLogger has been removed and replaced with SimpleJdk14Logger. + If you want to continue to use log4j, copy the source from the Stripes 1.6.0 branch + into your application source and use at your own risk. + -> If you are using cos.jar it has been removed for security reasons. Commons-fileupload2 is now + the default. Remove cos.jar and remove the CosMultipartWrapper from your web.xml if it is + referenced there. + +2. Backwards Incompatibilities --------------------------- - Stripes 1.5 is the first major release of Stripes that is not completely - backwards compatible with earlier versions of Stripes. However most of the + Stripes 1.6.0-Jakarta is not completely + backwards compatible with Stripes 1.6.0 (non-Jakarta). However, most of the incompatible change are quite small and require only minor edits to your - application (often achievable with search & replace functionality). This - section documents these incompatibilities. - - -> ActionResolver.PackageFilters has been replaced by ActionResolver.Packages - which is now a required configuration property. Changes in class scanning to - make it more efficient and robust across containers have changed the meaning - of this property and we have therefore changed the name to reflect this. If you - already specified ActionResolver.PackageFilters simply renaming it will do. - Otherwise you must specify ActionResolver.Packages to be the list of root - packages to scan for ActionBeans in your application - - -> Attribute name change in @Before and @After annotations. Previously the - lifecycle changes were specified using the 'value' attribute which - allowed the abbreviated form of '@Before(LifecycleStage.BindingAndValidation)'. - Due to the addition of the 'on' attribute to support selective execution this - is no longer desirable and the 'value' attribute has been renamed to 'stages'. - In most cases replacing '@Before(' with '@Before(stages=' (and the same for - @After) will be enough to ix this problem. - - -> The Validatable interface has been removed. Where it was used remove the - implemented clause from your ActionBean and annotate your validate() method - with the @ValidationMethod annotation - - -> The link-param tag has been removed in preference to the param tag. A search - and replace of 'link-param' to 'param' is sufficient to fix this. - - -> SpringAwareActionResolver has been removed. Please instead use the - SpringInterceptor introduced in Stripes 1.3. - - -> Stripes now performs stricter checking of various annotations. If you have - multiple methods annotated with @DefaultHandler or if you have @Validate - annotations in multiple locations (e.g. getter and setter) for a single - property Stripes will throw an exception instead of producing non-deterministic - behaviour. + application (mentioned above). This section documents these incompatibilities. - -> The _sourcePage parameter is no longer inserted into links (using the link and - url tags) by default (it is still submitted in forms). If the _sourcePage parameter - is relied on in certain places you can request Stripes insert it using the new - attribute addSourcePage="true". - - -> The _sourcePage parameter is always encrypted to avoid revealing potentially - sensitive information. The plaintext value can be easily accessed by calling - the new method ActionBeanContext.getSourcePage(). - - -> The way Interceptor classes are configured has changed. Two configuration - properties are supported: 'Interceptor.Classes' and 'CoreInterceptor.Classes'. - The first has the same name as before but the behaviour has changed. Now specifying - this property does NOT require you to specify the interceptors that Stripes - executes by default, only additional interceptors you would like to use. To - override the set of core interceptors used by Stripes you may now separately - specify the 'CoreInterceptor.Classes' property. When upgrading you should - remove referenced to the BeforeAfterMethodInterceptor from the - 'Interceptor.Classes' property. - - -> Behaviour of file uploads when using commons-fileupload has changed to match - the behaviour when using the cos implementation. When the user does not provide - a file a null FileBean will be produced instead of one containing a zero-length - file. In addition the filenames returned will never have path information - (previously path information would be included if the user was using IE). - - -> ActionClassCache has been removed. If you require a list of all ActionBeans - configured use ActionResolver.getActionBeanClasses() instead. - - -> All parameter values are now trimmed before validation, type conversion and - binding. If your app has any fields that allow whitespace as valid input or need - to retain leading and trailing whitespace during binding, you must use - @Validate(trim=false) on the field to override this behavior. - - -> The special parameter _eventName now overrides all request parameters that would - otherwise indicate the event name. E.g., given an ActionBean with events foo, bar - and blah and request parameters foo=foo, bar=bar and _eventName=blah, the event to - be executed will be blah because _eventName overrides the other two parameters. - Previous versions gave _eventName a lower precedence than other parameters. - - -> If multiple request parameters match event names, Stripes will throw an exception - reporting the conflict. In such a case, it cannot be determined which event should - execute. However, if the _eventName parameter is present, as noted in the previous - bullet, it overrides all others, even in case of such a conflict. The behavior of - previous versions of Stripes was indeterminate. - - -> When flashing an ActionBean and redirecting to that same ActionBean, as in: - - return new RedirectResolution(getClass(), "event").flash(this); - - the ActionBean receives a newly created ActionBeanContext on the ensuing request. - (In cases where the flashed bean is not the target of the redirect, the bean - retains its old ActionBeanContext.) One side-effect of this is that - ValidationErrors no longer carry over to the next request. It is recommended - that you use Messages instead of ValidationErrors when flashing and redirecting - to the same ActionBean. - - In addition to the above changes there have also been changes to several core classes. - In most cases these changes will be invisible to application developers, but where you - have implemented your own ConfigurableComponents from scratch (as opposed to extending - the default implementations) you may notice additional interface methods and changes - to signatures. Please refer to the javadoc for the 1.5 release in these cases. The - following is a non-exhaustive list of core classes with interface changes in 1.5: - -> Configuration (and implementations thereof) - -> ActionResolver (and implementations thereof) - -> BootstrapPropertyResolver - -> UrlBuilder - - -> The default PopulationStrategy is now BeanFirstPopulationStrategy instead of - DefaultPopulationStrategy. This may cause backward compatibility issues if - you were relying on the behavior of DefaultPopulationStrategy. You can revert - back to this behavior by configuring the population strategy in web.xml: - - - PopulationStrategy.Class - net.sourceforge.stripes.tag.DefaultPopulationStrategy - - - On the other hand, if you had the above configuration present in web.xml but with - BeanFirstPopulationStrategy, it is no longer required since it has become the - default. Leaving it there would be redundant, but would cause no harm. + -> Log4jLogger has been removed and the dependency on log4j has been removed. + -> cos.jar and CosMultipartWrapper have been removed. + -> commons-fileupload has been replaced with commons-fileupload2 + -> jakarta.mail dependency has been removed. +2. More Information + --------------------------- + For more information about the release, you can look at the release page on GitHub + located here: https://github.com/StripesFramework/stripes/releases/tag/1.6.0-Jakarta-beta