OpenJPA
  1. OpenJPA
  2. OPENJPA-404

Backward-compatibility for pre-1.0 APIs

    Details

    • Type: New Feature New Feature
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 1.0.0
    • Fix Version/s: 1.1.0
    • Component/s: None
    • Labels:
      None

      Description

      When I changed the OpenJPA APIs before the 1.0 release, I made a number of incompatible changes. At the time, we deemed that this was fine since 1.0 was the first OpenJPA release. However, it turns out that this runs up against BEA policy, since BEA shipped a product using a build from around 0.9.7. So, we'd like to do some work to address this where possible.

      1. OPENJPA-404.patch
        34 kB
        Patrick Linskey

        Issue Links

          Activity

          Hide
          Patrick Linskey added a comment -

          This patch introduces deprecated methods for most of the methods that were removed or modified in OPENJPA-317.

          It re-introduces symbolic constants that were removed, but does so by directly listing the symbolic constants to the appropriate and marking them as deprecated, instead of making the interfaces extend the symbolic-constant interfaces.

          OpenJPAEntityManager now extends EntityTransaction. Sadly, there is no language-enforced way to mark this as deprecated that I know of, so I've noted the deprecation in the JavaDoc.

          The following thirteen methods changed only in their return type, so the old method signature could not be re-introduced. The - prefix denotes the pre-1.0 syntax; the + syntax denotes the 1.0-and-later syntax.

          OpenJPAEntityManager

          { - public int getConnectionRetainMode(); + public ConnectionRetainMode getConnectionRetainMode(); - public int getRestoreState(); + public RestoreStateType getRestoreState(); - public int getDetachState(); + public DetachStateType getDetachState(); - public int getAutoClear(); + public AutoClearType getAutoClear(); - public int getAutoDetach(); + public EnumSet<AutoDetachType> getAutoDetach(); }

          OpenJPAQuery

          { - public int getOperation(); + public QueryOperationType getOperation(); }

          JDBCFetchPlan

          { - public int getEagerFetchMode(); + public FetchMode getEagerFetchMode(); - public int getSubclassFetchMode(); + public FetchMode getSubclassFetchMode(); - public int getResultSetType(); + public ResultSetType getResultSetType(); - public int getFetchDirection(); + public FetchDirection getFetchDirection(); - public int getJoinSyntax(); + public JoinSyntax getJoinSyntax(); }

          EagerFetchMode

          { - EagerFetchType value() default EagerFetchType.NONE; + FetchMode value() default FetchMode.NONE; }

          SubclassFetchMode { - EagerFetchType value() default EagerFetchType.NONE; + FetchMode value() default FetchMode.NONE; }
          Show
          Patrick Linskey added a comment - This patch introduces deprecated methods for most of the methods that were removed or modified in OPENJPA-317 . It re-introduces symbolic constants that were removed, but does so by directly listing the symbolic constants to the appropriate and marking them as deprecated, instead of making the interfaces extend the symbolic-constant interfaces. OpenJPAEntityManager now extends EntityTransaction. Sadly, there is no language-enforced way to mark this as deprecated that I know of, so I've noted the deprecation in the JavaDoc. The following thirteen methods changed only in their return type, so the old method signature could not be re-introduced. The - prefix denotes the pre-1.0 syntax; the + syntax denotes the 1.0-and-later syntax. OpenJPAEntityManager { - public int getConnectionRetainMode(); + public ConnectionRetainMode getConnectionRetainMode(); - public int getRestoreState(); + public RestoreStateType getRestoreState(); - public int getDetachState(); + public DetachStateType getDetachState(); - public int getAutoClear(); + public AutoClearType getAutoClear(); - public int getAutoDetach(); + public EnumSet<AutoDetachType> getAutoDetach(); } OpenJPAQuery { - public int getOperation(); + public QueryOperationType getOperation(); } JDBCFetchPlan { - public int getEagerFetchMode(); + public FetchMode getEagerFetchMode(); - public int getSubclassFetchMode(); + public FetchMode getSubclassFetchMode(); - public int getResultSetType(); + public ResultSetType getResultSetType(); - public int getFetchDirection(); + public FetchDirection getFetchDirection(); - public int getJoinSyntax(); + public JoinSyntax getJoinSyntax(); } EagerFetchMode { - EagerFetchType value() default EagerFetchType.NONE; + FetchMode value() default FetchMode.NONE; } SubclassFetchMode { - EagerFetchType value() default EagerFetchType.NONE; + FetchMode value() default FetchMode.NONE; }
          Hide
          Michael Dick added a comment -

          Should these changes be migrated to the 1.0.x branch as well? I think we'd want to keep the interfaces in sync.

          Show
          Michael Dick added a comment - Should these changes be migrated to the 1.0.x branch as well? I think we'd want to keep the interfaces in sync.
          Hide
          Patrick Linskey added a comment -

          Since the re-introduced APIs are used by 0% of 1.0.x users, I'd say we should not bother the 1.0.x branch with the change. My call is generally to keep changes to maintenance branches to an absolute minimum (i.e., known bugfixes only).

          Show
          Patrick Linskey added a comment - Since the re-introduced APIs are used by 0% of 1.0.x users, I'd say we should not bother the 1.0.x branch with the change. My call is generally to keep changes to maintenance branches to an absolute minimum (i.e., known bugfixes only).
          Hide
          Craig L Russell added a comment -

          It might inform this discussion to understand what BEA policy has to say about fixing backward compatibility issues.

          Personally, I have no issue with this particular issue being fixed only in 1.1.x but it might be good to have OpenJPA policy in sync with BEA policy...

          Show
          Craig L Russell added a comment - It might inform this discussion to understand what BEA policy has to say about fixing backward compatibility issues. Personally, I have no issue with this particular issue being fixed only in 1.1.x but it might be good to have OpenJPA policy in sync with BEA policy...
          Hide
          Patrick Linskey added a comment -

          > It might inform this discussion to understand what BEA policy has to
          > say about fixing backward compatibility issues.

          The next WebLogic release will ship with something cut from what is currently in trunk, so we (BEA) have no need for this to be in 1.0.x.

          > Personally, I have no issue with this particular issue being fixed only
          > in 1.1.x but it might be good to have OpenJPA policy in sync with BEA policy...

          First, it's important to note that this problem is a special case, since OpenJPA went from pre-release (0.9.7) to release (1.0), and so we (OpenJPA) were in the initial state condition.

          I believe that it will be difficult in general to come up with a hard and fast policy for deprecation OpenJPA that is guaranteed to be compatible with BEA's policy. IIRC, BEA guarantees that a given API won't disappear within two major releases. Since the WebLogic release cycle is different than the OpenJPA release cycle, we can't write an OpenJPA policy that will guarantee that trunk is backward-compatible with whatever BEA released two release cycles earlier. (Well, unless we encoded a dependency on WebLogic release cycles in the OpenJPA policy, which seems like a bad idea.)

          I think that this is OK. If OpenJPA decides to break APIs in the future (presumably per our compatibility policy), then BEA may need to release off of an old line for some period of time. This is understood at BEA, and is just one of those things.

          Note that one of the goals of solidifying our APIs was to constrain things so that it's easy for people like us at BEA to reference a stable bounded set of OpenJPA APIs. So, I'm hopeful that post-1.0 (i.e., now), we will be in a safer position moving forward.

          Show
          Patrick Linskey added a comment - > It might inform this discussion to understand what BEA policy has to > say about fixing backward compatibility issues. The next WebLogic release will ship with something cut from what is currently in trunk, so we (BEA) have no need for this to be in 1.0.x. > Personally, I have no issue with this particular issue being fixed only > in 1.1.x but it might be good to have OpenJPA policy in sync with BEA policy... First, it's important to note that this problem is a special case, since OpenJPA went from pre-release (0.9.7) to release (1.0), and so we (OpenJPA) were in the initial state condition. I believe that it will be difficult in general to come up with a hard and fast policy for deprecation OpenJPA that is guaranteed to be compatible with BEA's policy. IIRC, BEA guarantees that a given API won't disappear within two major releases. Since the WebLogic release cycle is different than the OpenJPA release cycle, we can't write an OpenJPA policy that will guarantee that trunk is backward-compatible with whatever BEA released two release cycles earlier. (Well, unless we encoded a dependency on WebLogic release cycles in the OpenJPA policy, which seems like a bad idea.) I think that this is OK. If OpenJPA decides to break APIs in the future (presumably per our compatibility policy), then BEA may need to release off of an old line for some period of time. This is understood at BEA, and is just one of those things. Note that one of the goals of solidifying our APIs was to constrain things so that it's easy for people like us at BEA to reference a stable bounded set of OpenJPA APIs. So, I'm hopeful that post-1.0 (i.e., now), we will be in a safer position moving forward.
          Hide
          Kevin Sutter added a comment -

          FWIW, WebSphere's compatibility policy seems to be in synch with BEA's – two major release cycle. We also understand that attempting to keep OpenJPA in synch with WebSphere's release cycles will be a challenge. But, as long as we (OpenJPA) are consistent with our release and compatibility strategy, then we should be able to meld with any other app server's release cycle (in one form or another).

          Kevin

          Show
          Kevin Sutter added a comment - FWIW, WebSphere's compatibility policy seems to be in synch with BEA's – two major release cycle. We also understand that attempting to keep OpenJPA in synch with WebSphere's release cycles will be a challenge. But, as long as we (OpenJPA) are consistent with our release and compatibility strategy, then we should be able to meld with any other app server's release cycle (in one form or another). Kevin

            People

            • Assignee:
              Unassigned
              Reporter:
              Patrick Linskey
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development