1 /*

     2  * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package javax.sql.rowset.spi;

    27 

    28 import java.sql.SQLException;

    29 import javax.sql.rowset.*;

    30 

    31 /**

    32  * Indicates an error with the <code>SyncProvider</code> mechanism. This exception

    33  * is created by a <code>SyncProvider</code> abstract class extension if it

    34  * encounters violations in reading from or writing to the originating data source.

    35  * <P>

    36  * If it is implemented to do so, the <code>SyncProvider</code> object may also create a

    37  * <code>SyncResolver</code> object and either initialize the <code>SyncProviderException</code>

    38  * object with it at construction time or set it with the <code>SyncProvider</code> object at

    39  * a later time.

    40  * <P>

    41  * The method <code>acceptChanges</code> will throw this exception after the writer

    42  * has finished checking for conflicts and has found one or more conflicts. An

    43  * application may catch a <code>SyncProviderException</code> object and call its

    44  * <code>getSyncResolver</code> method to get its <code>SyncResolver</code> object.

    45  * See the code fragment in the interface comment for

    46  * <a href="SyncResolver.html"><code>SyncResolver</code></a> for an example.

    47  * This <code>SyncResolver</code> object will mirror the <code>RowSet</code>

    48  * object that generated the exception, except that it will contain only the values

    49  * from the data source that are in conflict.  All other values in the <code>SyncResolver</code>

    50  * object will be <code>null</code>.

    51  * <P>

    52  * The <code>SyncResolver</code> object may be used to examine and resolve

    53  * each conflict in a row and then go to the next row with a conflict to

    54  * repeat the procedure.

    55  * <P>

    56  * A <code>SyncProviderException</code> object may or may not contain a description of the

    57  * condition causing the exception.  The inherited method <code>getMessage</code> may be

    58  * called to retrieve the description if there is one.

    59  *

    60  * @author Jonathan Bruce

    61  * @see javax.sql.rowset.spi.SyncFactory

    62  * @see javax.sql.rowset.spi.SyncResolver

    63  * @see javax.sql.rowset.spi.SyncFactoryException

    64  * @since 1.5

    65  */

    66 public class SyncProviderException extends java.sql.SQLException {

    67 

    68     /**

    69      * The instance of <code>javax.sql.rowset.spi.SyncResolver</code> that

    70      * this <code>SyncProviderException</code> object will return when its

    71      * <code>getSyncResolver</code> method is called.

    72      */

    73      private SyncResolver syncResolver = null;

    74 

    75     /**

    76      * Creates a new <code>SyncProviderException</code> object without a detail message.

    77      */

    78     public SyncProviderException() {

    79         super();

    80     }

    81 

    82     /**

    83      * Constructs a <code>SyncProviderException</code> object with the specified

    84      * detail message.

    85      *

    86      * @param msg the detail message

    87      */

    88     public SyncProviderException(String msg)  {

    89         super(msg);

    90     }

    91 

    92     /**

    93      * Constructs a <code>SyncProviderException</code> object with the specified

    94      * <code>SyncResolver</code> instance.

    95      *

    96      * @param syncResolver the <code>SyncResolver</code> instance used to

    97      *     to process the synchronization conflicts

    98      * @throws IllegalArgumentException if the <code>SyncResolver</code> object

    99      *     is <code>null</code>.

   100      */

   101     public SyncProviderException(SyncResolver syncResolver)  {

   102         if (syncResolver == null) {

   103             throw new IllegalArgumentException("Cannot instantiate a SyncProviderException " +

   104                 "with a null SyncResolver object");

   105         } else {

   106             this.syncResolver = syncResolver;

   107         }

   108     }

   109 

   110     /**

   111      * Retrieves the <code>SyncResolver</code> object that has been set for

   112      * this <code>SyncProviderException</code> object, or

   113      * if none has been set, an instance of the default <code>SyncResolver</code>

   114      * implementation included in the reference implementation.

   115      * <P>

   116      * If a <code>SyncProviderException</code> object is thrown, an application

   117      * may use this method to generate a <code>SyncResolver</code> object

   118      * with which to resolve the conflict or conflicts that caused the

   119      * exception to be thrown.

   120      *

   121      * @return the <code>SyncResolver</code> object set for this

   122      *     <code>SyncProviderException</code> object or, if none has

   123      *     been set, an instance of the default <code>SyncResolver</code>

   124      *     implementation. In addition, the default <code>SyncResolver</code>

   125      *     implementation is also returned if the <code>SyncResolver()</code> or

   126      *     <code>SyncResolver(String)</code> constructors are used to instantiate

   127      *     the <code>SyncResolver</code> instance.

   128      */

   129     public SyncResolver getSyncResolver() {

   130         if (syncResolver != null) {

   131             return syncResolver;

   132         } else {

   133             try {

   134               syncResolver = new com.sun.rowset.internal.SyncResolverImpl();

   135             } catch (SQLException sqle) {

   136             }

   137             return syncResolver;

   138         }

   139     }

   140 

   141     /**

   142      * Sets the <code>SyncResolver</code> object for this

   143      * <code>SyncProviderException</code> object to the one supplied.

   144      * If the argument supplied is <code>null</code>, a call to the method

   145      * <code>getSyncResolver</code> will return the default reference

   146      * implementation of the <code>SyncResolver</code> interface.

   147      *

   148      * @param syncResolver the <code>SyncResolver</code> object to be set;

   149      *     cannot be <code>null</code>

   150      * @throws IllegalArgumentException if the <code>SyncResolver</code> object

   151      *     is <code>null</code>.

   152      * @see #getSyncResolver

   153      */

   154     public void setSyncResolver(SyncResolver syncResolver) {

   155         if (syncResolver == null) {

   156             throw new IllegalArgumentException("Cannot set a null SyncResolver " +

   157                 "object");

   158         } else {

   159             this.syncResolver = syncResolver;

   160         }

   161     }

   162 

   163     static final long serialVersionUID = -939908523620640692L;

   164 

   165 }