ZorbaXQDataSource.java
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2012 The FLWOR Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.zorbaxquery.api.xqj;
17 
18 import java.io.PrintWriter;
19 import java.sql.Connection;
20 import java.util.Enumeration;
21 import java.util.Properties;
22 import javax.xml.xquery.XQException;
23 
24  /**
25  * An ZorbaXQDataSource is a factory for ZorbaXQConnection objects.
26  */
27 public class ZorbaXQDataSource implements javax.xml.xquery.XQDataSource {
28 
29  static {
30  System.loadLibrary ( "zorba_api" );
31  }
32  public static final String ZORBA_PROPERTIES_URI_PATHS = "URI-PATHS";
33  public static final String ZORBA_PROPERTIES_LIB_PATHS = "LIB-PATHS";
34  public static final String ZORBA_PROPERTIES_MODULE_PATHS = "MODULE-PATHS";
35 
36  private int loginTimeout;
37  protected PrintWriter logWriter;
38  private Properties properties = new Properties();
40  public ZorbaXQDataSource() {
41  }
42 
43 
44  /** \brief Attempts to create a connection to an XML datasource.
45  *
46  * @return a connection to the XML datasource
47  * @throw XQException - if a datasource access error occurs
48  */
49  @Override
50  public ZorbaXQConnection getConnection() throws XQException {
51  ZorbaXQConnection conn;
52  try {
53  if (!properties.isEmpty()) {
54  conn = new ZorbaXQConnection(properties);
55  } else {
56  conn = new ZorbaXQConnection();
57  }
58  } catch ( Exception e ) {
59  throw new XQException("Error creating new Zorba Connection Instance");
60  }
61  return conn;
62  }
63 
64  /** \brief Attempts to create a connection to an XML datasource using an existing JDBC connection.
65  *
66  * An XQJ implementation is not required to support this method. If it is not supported, then an exception (XQException) is thrown. The XQJ and JDBC connections will operate under the same transaction context.
67  *
68  * @param cnctn - an existing JDBC connection
69  * @return a connection to the XML datasource
70  * @throw XQException - if (1) a datasource access error occurs, (2) the implementation does not support this method of getting an ZorbaXQConnection, or (3) if the con parameter is null
71  */
72  @Override
73  public ZorbaXQConnection getConnection(Connection cnctn) throws XQException {
74  /* Attempts to create a connection to an XML datasource using an
75  * existing JDBC connection. An XQJ implementation is not required
76  * to support this method. If it is not supported, then an
77  * exception (XQException) is thrown. The XQJ and JDBC connections
78  * will operate under the same transaction context.
79  * */
80  throw new XQException("Connection to an XML datasource using an existing JDBC connection is not supported.");
81  }
82 
83  /** \brief Attempts to establish a connection to an XML datasource using the supplied username and password.
84  *
85  * @param username - the user on whose behalf the connection is being made
86  * @param passwd - the user's password
87  * @return a connection to the XML datasource
88  * @throw XQException - if a datasource access error occurs
89  */
90  @Override
91  public ZorbaXQConnection getConnection(String username, String passwd) throws XQException {
92  ZorbaXQConnection conn;
93  try {
94  if (!properties.isEmpty()) {
95  conn = new ZorbaXQConnection(properties);
96  } else {
97  conn = new ZorbaXQConnection();
98  }
99  } catch ( Exception e ) {
100  throw new XQException("Error creating new Zorba Connection Instance");
101  }
102  return conn;
103  }
104 
105  /** \brief Gets the maximum time in seconds that this datasource can wait while attempting to connect to a database.
106  *
107  * A value of zero means that the timeout is the default system timeout if there is one; otherwise, it means that there is no timeout. When a ZorbaXQDataSource object is created, the login timeout is initially zero. It is implementation-defined whether the returned login timeout is actually used by the data source implementation.
108  *
109  * @return the datasource login time limit
110  * @throw XQException - if a datasource access error occurs
111  */
112  @Override
113  public int getLoginTimeout() throws XQException {
114  return loginTimeout;
115  }
116 
117  /** \brief Retrieves the log writer for this ZorbaXQDataSource object.
118  *
119  * The log writer is a character output stream to which all logging and tracing messages for this datasource will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. When a ZorbaXQDataSource object is created, the log writer is initially null; in other words, the default is for logging to be disabled.
120  *
121  * @return the log writer for this datasource or null if logging is disabled
122  * @throw XQException - if a datasource access error occurs
123  */
124  @Override
125  public PrintWriter getLogWriter() throws XQException {
126  return logWriter;
127  }
128 
129  /** \brief Returns an array containing the property names supported by this ZorbaXQDataSource.
130  *
131  * Implementations that support user name and password must recognize the user name and password properties listed below.
132  *
133  * user the user name to use for creating a connection
134  * password the password to use for creating a connection
135  *
136  * Any additional properties are implementation-defined.
137  *
138  * @return String[] an array of property names supported by this implementation
139  */
140  @Override
141  public String[] getSupportedPropertyNames() {
142  return propertiesAllowed;
143  }
144 
145  /** \brief Sets the named property to the specified value.
146  *
147  * If a property with the same name was already set, then this method will override the old value for that property with the new value.
148  * If the implementation does not support the given property or if it can determine that the value given for this property is invalid, then an exception is thrown. If an exception is thrown, then no previous value is overwritten.
149  *
150  * @param name - the name of the property to set
151  * @param value - the value of the named property
152  * @throw XQException - if (1) the given property is not recognized, (2) the value for the given property is determined to be invalid, or (3) the name parameter is null
153  */
154  @Override
155  public void setProperty(String name, String value) throws XQException {
156  if (name==null) {
157  throw new XQException("Property name is null.");
158  }
159  boolean allowed = false;
160  for(int i=0; i<propertiesAllowed.length; i++) {
161  if (propertiesAllowed[i].equals(name)) {
162  allowed = true;
163  }
164  }
165  if (allowed) {
166  properties.setProperty(name, value);
167  } else {
168  throw new XQException("Property not allowed.");
169  }
170  }
171 
172  /** \brief Returns the current value of the named property if set, else null.
173  *
174  * If the implementation does not support the given property then an exception is raised.
175  *
176  * @param name - the name of the property whose value is needed
177  * @return String representing the value of the required property if set, else null
178  * @throw XQException - if (1) a given property is not supported, or (2) the name parameter is null
179  */
180  @Override
181  public String getProperty(String name) throws XQException {
182  if (name==null) {
183  throw new XQException("Property name is null.");
184  }
185  boolean allowed = false;
186  for(int i=0; i<propertiesAllowed.length; i++) {
187  if (propertiesAllowed[i].equals(name)) {
188  allowed = true;
189  }
190  }
191  if (!allowed) {
192  throw new XQException("Property name not supported.");
193  }
194  return properties.getProperty(name);
195  }
196 
197  /** \brief Sets the data source properties from the specified Properties instance.
198  *
199  * Properties set before this call will still apply but those with the same name as any of these properties will be replaced. Properties set after this call also apply and may replace properties set during this call.
200  * If the implementation does not support one or more of the given property names, or if it can determine that the value given for a specific property is invalid, then an exception is thrown. If an exception is thrown, then no previous value is overwritten. is invalid, then an exception is raised.
201  *
202  * @param prprts - the list of properties to set
203  * @throw XQException - if (1) a given property is not recognized, (2) the value for a given property is determined to be invalid, or (3) the props parameter is null
204  */
205  @Override
206  public void setProperties(Properties prprts) throws XQException {
207  if (prprts==null) {
208  throw new XQException("Properties are null.");
209  }
210  boolean allowed = false;
211  String tmpstr = null;
212  Enumeration em = prprts.keys();
213  while (em.hasMoreElements()) {
214  allowed = false;
215  tmpstr = (String)em.nextElement();
216  for (int i=0; i<propertiesAllowed.length; i++) {
217  if (propertiesAllowed[i].equals(tmpstr)) {
218  allowed = true;
219  }
220  }
221  if (!allowed) {
222  throw new XQException("Property [" + tmpstr + "] not allowed");
223  }
224  }
225 
226  em = prprts.keys();
227  while (em.hasMoreElements()) {
228  tmpstr = (String)em.nextElement();
229  properties.setProperty(tmpstr, prprts.getProperty(tmpstr));
230  }
231 
232  }
233 
234  /** \brief Sets the maximum time in seconds that this datasource will wait while attempting to connect to a database.
235  *
236  * A value of zero specifies that the timeout is the default system timeout if there is one; otherwise, it specifies that there is no timeout. When a ZorbaXQDataSource object is created, the login timeout is initially zero. It is implementation-defined whether the specified login timeout is actually used by the data source implementation. If the connection is created over an existing JDBC connection, then the login timeout value from the underlying JDBC connection may be used.
237  *
238  * @param seconds - the datasource login time limit
239  * @throw XQException - if a datasource access error occurs
240  */
241  @Override
242  public void setLoginTimeout(int seconds) throws XQException {
243  loginTimeout = seconds;
244  }
245 
246  /** \brief Sets the log writer for this ZorbaXQDataSource object to the given java.io.PrintWriter object.
247  *
248  * The log writer is a character output stream to which all logging and tracing messages for this datasource will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. When a ZorbaXQDataSource object is created the log writer is initially null; in other words, the default is for logging to be disabled.
249  *
250  * @param writer - the new log writer; to disable logging, set to null
251  * @throw XQException - if a datasource access error occurs
252  */
253  @Override
254  public void setLogWriter(PrintWriter writer) throws XQException {
255  logWriter = writer;
256  }
257 
258 }
int getLoginTimeout()
Gets the maximum time in seconds that this datasource can wait while attempting to connect to a datab...
void setLoginTimeout(int seconds)
Sets the maximum time in seconds that this datasource will wait while attempting to connect to a data...
An ZorbaXQDataSource is a factory for ZorbaXQConnection objects.
A connection (session) with a specific XQuery engine.
String getProperty(String name)
Returns the current value of the named property if set, else null.
ZorbaXQConnection getConnection(Connection cnctn)
Attempts to create a connection to an XML datasource using an existing JDBC connection.
void setLogWriter(PrintWriter writer)
Sets the log writer for this ZorbaXQDataSource object to the given java.io.PrintWriter object...
PrintWriter getLogWriter()
Retrieves the log writer for this ZorbaXQDataSource object.
String[] getSupportedPropertyNames()
Returns an array containing the property names supported by this ZorbaXQDataSource.
void setProperties(Properties prprts)
Sets the data source properties from the specified Properties instance.
ZorbaXQConnection getConnection(String username, String passwd)
Attempts to establish a connection to an XML datasource using the supplied username and password...
ZorbaXQConnection getConnection()
Attempts to create a connection to an XML datasource.
void setProperty(String name, String value)
Sets the named property to the specified value.