diff --git a/Resources/.gitignore b/Resources/.gitignore new file mode 100644 index 00000000..1014a953 --- /dev/null +++ b/Resources/.gitignore @@ -0,0 +1,2 @@ +# Include all Resources +!* \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Ionic.Zip.Reduced.dll b/Resources/Libraries/DotNetZip/Ionic.Zip.Reduced.dll new file mode 100644 index 00000000..9622cc53 Binary files /dev/null and b/Resources/Libraries/DotNetZip/Ionic.Zip.Reduced.dll differ diff --git a/Resources/Libraries/DotNetZip/Source/BZip2/BZip2Compressor.cs b/Resources/Libraries/DotNetZip/Source/BZip2/BZip2Compressor.cs new file mode 100644 index 00000000..68099d2a --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/BZip2/BZip2Compressor.cs @@ -0,0 +1,1920 @@ +// BZip2Compressor.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// Last Saved: <2011-July-28 06:17:22> +// +// ------------------------------------------------------------------ +// +// This module defines the BZip2Compressor class, which is a +// BZIP2-compressing encoder. It is used internally in the BZIP2 +// library, by the BZip2OutputStream class and its parallel variant, +// ParallelBZip2OutputStream. This code was originally based on Apache +// commons source code, and significantly modified. The license below +// applies to the original Apache code and to this modified variant. +// +// ------------------------------------------------------------------ + + +/* + * 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 package is based on the work done by Keiron Liddle, Aftex Software + * to whom the Ant project is very grateful for his + * great code. + */ + + +// +// Design notes: +// +// This class performs BZip2 compression. It is derived from the +// BZip2OutputStream from the Apache commons source code, but is +// significantly modified from that code. While the Apache class is a +// stream that compresses, this particular class simply performs +// compression. It follows a Manager pattern. It manages an internal +// buffer for uncompressed data; callers place data into the buffer +// using the Fill() method. This class then compresses the data and +// writes the compressed form out, via the CompressAndWrite() method. +// Because BZip2 uses byte-shredding, this class relies on a BitWriter, +// and not a .NET Stream, to emit its output. (*Think of the BitWriter +// class as an Adapter that enables Bit-oriented output to a standard +// byte-oriented .NET stream.) +// +// This class exists to support the two distinct output streams that +// perform BZip2 compression: BZip2OutputStream and +// ParallelBZip2OutputStream. These streams rely on BZip2Compressor to +// provide the encoder/compression logic. This code has been derived +// from the bzip2 output stream in the Apache commons library; it has +// been significantly modified from that form, in order to provide a +// single compressor that could support both types of streams. +// +// In a bz2 file or stream, there is never any bit padding except for 0..7 +// bits in the final byte in the file. Successive compressed blocks in a +// .bz2 file are not byte-aligned. +// +// + +using System; +using System.IO; + +// flymake: csc.exe /t:module BZip2InputStream.cs BZip2OutputStream.cs Rand.cs BCRC32.cs @@FILE@@ + +namespace Ionic.BZip2 +{ + internal class BZip2Compressor + { + private int blockSize100k; // 0...9 + private int currentByte = -1; + private int runLength = 0; + private int last; // index into the block of the last char processed + private int outBlockFillThreshold; + private CompressionState cstate; + private readonly Ionic.Crc.CRC32 crc = new Ionic.Crc.CRC32(true); + BitWriter bw; + int runs; + + /* + * The following three vars are used when sorting. If too many long + * comparisons happen, we stop sorting, randomise the block slightly, and + * try again. I think this wrinkle in the implementation was removed from + * a later rev of the C-language bzip, not sure. -DPC 24 Jul 2011 + * + */ + private int workDone; + private int workLimit; + private bool firstAttempt; + private bool blockRandomised; + private int origPtr; + + private int nInUse; + private int nMTF; + + private static readonly int SETMASK = (1 << 21); + private static readonly int CLEARMASK = (~SETMASK); + private static readonly byte GREATER_ICOST = 15; + private static readonly byte LESSER_ICOST = 0; + private static readonly int SMALL_THRESH = 20; + private static readonly int DEPTH_THRESH = 10; + private static readonly int WORK_FACTOR = 30; + + /** + * Knuth's increments seem to work better than Incerpi-Sedgewick here. + * Possibly because the number of elems to sort is usually small, typically + * <= 20. + */ + private static readonly int[] increments = { 1, 4, 13, 40, 121, 364, 1093, 3280, + 9841, 29524, 88573, 265720, 797161, + 2391484 }; + + /// + /// BZip2Compressor writes its compressed data out via a BitWriter. This + /// is necessary because BZip2 does byte shredding. + /// + public BZip2Compressor(BitWriter writer) + : this(writer, BZip2.MaxBlockSize) + { + } + + public BZip2Compressor(BitWriter writer, int blockSize) + { + this.blockSize100k = blockSize; + this.bw = writer; + + // 20 provides a margin of slop (not to say "Safety"). The maximum + // size of an encoded run in the output block is 5 bytes, so really, 5 + // bytes ought to do, but this is a margin of slop found in the + // original bzip code. Not sure if important for decoding + // (decompressing). So we'll leave the slop. + this.outBlockFillThreshold = (blockSize * BZip2.BlockSizeMultiple) - 20; + this.cstate = new CompressionState(blockSize); + Reset(); + } + + + void Reset() + { + // initBlock(); + this.crc.Reset(); + this.currentByte = -1; + this.runLength = 0; + this.last = -1; + for (int i = 256; --i >= 0;) + this.cstate.inUse[i] = false; + //bw.Reset(); xxx? want this? no no no + } + + + public int BlockSize + { + get { return this.blockSize100k; } + } + + public uint Crc32 + { + get; private set; + } + + public int AvailableBytesOut + { + get; private set; + } + + /// + /// The number of uncompressed bytes being held in the buffer. + /// + /// + /// + /// I am thinking this may be useful in a Stream that uses this + /// compressor class. In the Close() method on the stream it could + /// check this value to see if anything has been written at all. You + /// may think the stream could easily track the number of bytes it + /// wrote, which would eliminate the need for this. But, there is the + /// case where the stream writes a complete block, and it is full, and + /// then writes no more. In that case the stream may want to check. + /// + /// + public int UncompressedBytes + { + get { return this.last + 1; } + } + + + /// + /// Accept new bytes into the compressor data buffer + /// + /// + /// + /// This method does the first-level (cheap) run-length encoding, and + /// stores the encoded data into the rle block. + /// + /// + public int Fill(byte[] buffer, int offset, int count) + { + if (this.last >= this.outBlockFillThreshold) + return 0; // We're full, I tell you! + + int bytesWritten = 0; + int limit = offset + count; + int rc; + + // do run-length-encoding until block is full + do + { + rc = write0(buffer[offset++]); + if (rc > 0) bytesWritten++; + } while (offset < limit && rc == 1); + + return bytesWritten; + } + + + + /// + /// Process one input byte into the block. + /// + /// + /// + /// + /// To "process" the byte means to do the run-length encoding. + /// There are 3 possible return values: + /// + /// 0 - the byte was not written, in other words, not + /// encoded into the block. This happens when the + /// byte b would require the start of a new run, and + /// the block has no more room for new runs. + /// + /// 1 - the byte was written, and the block is not full. + /// + /// 2 - the byte was written, and the block is full. + /// + /// + /// + /// 0 if the byte was not written, non-zero if written. + private int write0(byte b) + { + bool rc; + // there is no current run in progress + if (this.currentByte == -1) + { + this.currentByte = b; + this.runLength++; + return 1; + } + + // this byte is the same as the current run in progress + if (this.currentByte == b) + { + if (++this.runLength > 254) + { + rc = AddRunToOutputBlock(false); + this.currentByte = -1; + this.runLength = 0; + return (rc) ? 2 : 1; + } + return 1; // not full + } + + // This byte requires a new run. + // Put the prior run into the Run-length-encoded block, + // and try to start a new run. + rc = AddRunToOutputBlock(false); + + if (rc) + { + this.currentByte = -1; + this.runLength = 0; + // returning 0 implies the block is full, and the byte was not written. + return 0; + } + + // start a new run + this.runLength = 1; + this.currentByte = b; + return 1; + } + + /// + /// Append one run to the output block. + /// + /// + /// + /// + /// This compressor does run-length-encoding before BWT and etc. This + /// method simply appends a run to the output block. The append always + /// succeeds. The return value indicates whether the block is full: + /// false (not full) implies that at least one additional run could be + /// processed. + /// + /// + /// true if the block is now full; otherwise false. + private bool AddRunToOutputBlock(bool final) + { + runs++; + /* add_pair_to_block ( EState* s ) */ + int previousLast = this.last; + + // sanity check only - because of the check done at the + // bottom of this method, and the logic in write0(), this + // should never ever happen. + if (previousLast >= this.outBlockFillThreshold && !final) + { + var msg = String.Format("block overrun(final={2}): {0} >= threshold ({1})", + previousLast, this.outBlockFillThreshold, final); + throw new Exception(msg); + } + + // NB: the index used here into block is always (last+2). This is + // because last is -1 based - the initial value is -1, a flag value + // used to indicate that nothing has yet been written into the + // block. The endBlock() fn tests for -1 to detect empty blocks. Also, + // the first byte of block is used, during sorting, to hold block[last + // +1], which is the final byte value that had been written into the + // rle block. For those two reasons, the base offset from last is + // always +2. + + byte b = (byte) this.currentByte; + byte[] block = this.cstate.block; + this.cstate.inUse[b] = true; + int rl = this.runLength; + this.crc.UpdateCRC(b, rl); + + switch (rl) + { + case 1: + block[previousLast + 2] = b; + this.last = previousLast + 1; + break; + + case 2: + block[previousLast + 2] = b; + block[previousLast + 3] = b; + this.last = previousLast + 2; + break; + + case 3: + block[previousLast + 2] = b; + block[previousLast + 3] = b; + block[previousLast + 4] = b; + this.last = previousLast + 3; + break; + + default: + rl -= 4; + this.cstate.inUse[rl] = true; + block[previousLast + 2] = b; + block[previousLast + 3] = b; + block[previousLast + 4] = b; + block[previousLast + 5] = b; + block[previousLast + 6] = (byte) rl; + this.last = previousLast + 5; + break; + } + + // is full? + return (this.last >= this.outBlockFillThreshold); + } + + + /// + /// Compress the data that has been placed (Run-length-encoded) into the + /// block. The compressed data goes into the CompressedBytes array. + /// + /// + /// + /// Side effects: 1. fills the CompressedBytes array. 2. sets the + /// AvailableBytesOut property. + /// + /// + public void CompressAndWrite() // endBlock + { + if (this.runLength > 0) + AddRunToOutputBlock(true); + + this.currentByte = -1; + + // Console.WriteLine(" BZip2Compressor:CompressAndWrite (r={0} bcrc={1:X8})", + // runs, this.crc.Crc32Result); + + // has any data been written? + if (this.last == -1) + return; // no data; nothing to compress + + /* sort the block and establish posn of original string */ + blockSort(); + + /* + * A 6-byte block header, the value chosen arbitrarily as 0x314159265359 + * :-). A 32 bit value does not really give a strong enough guarantee + * that the value will not appear by chance in the compressed + * datastream. Worst-case probability of this event, for a 900k block, + * is about 2.0e-3 for 32 bits, 1.0e-5 for 40 bits and 4.0e-8 for 48 + * bits. For a compressed file of size 100Gb -- about 100000 blocks -- + * only a 48-bit marker will do. NB: normal compression/ decompression + * donot rely on these statistical properties. They are only important + * when trying to recover blocks from damaged files. + */ + this.bw.WriteByte(0x31); + this.bw.WriteByte(0x41); + this.bw.WriteByte(0x59); + this.bw.WriteByte(0x26); + this.bw.WriteByte(0x53); + this.bw.WriteByte(0x59); + + this.Crc32 = (uint) this.crc.Crc32Result; + this.bw.WriteInt(this.Crc32); + + /* Now a single bit indicating randomisation. */ + this.bw.WriteBits(1, (this.blockRandomised)?1U:0U); + + /* Finally, block's contents proper. */ + moveToFrontCodeAndSend(); + + Reset(); + } + + + private void randomiseBlock() + { + bool[] inUse = this.cstate.inUse; + byte[] block = this.cstate.block; + int lastShadow = this.last; + + for (int i = 256; --i >= 0;) + inUse[i] = false; + + int rNToGo = 0; + int rTPos = 0; + for (int i = 0, j = 1; i <= lastShadow; i = j, j++) + { + if (rNToGo == 0) + { + rNToGo = (char) Rand.Rnums(rTPos); + if (++rTPos == 512) + { + rTPos = 0; + } + } + + rNToGo--; + block[j] ^= (byte) ((rNToGo == 1) ? 1 : 0); + + // handle 16 bit signed numbers + inUse[block[j] & 0xff] = true; + } + + this.blockRandomised = true; + } + + private void mainSort() + { + CompressionState dataShadow = this.cstate; + int[] runningOrder = dataShadow.mainSort_runningOrder; + int[] copy = dataShadow.mainSort_copy; + bool[] bigDone = dataShadow.mainSort_bigDone; + int[] ftab = dataShadow.ftab; + byte[] block = dataShadow.block; + int[] fmap = dataShadow.fmap; + char[] quadrant = dataShadow.quadrant; + int lastShadow = this.last; + int workLimitShadow = this.workLimit; + bool firstAttemptShadow = this.firstAttempt; + + // Set up the 2-byte frequency table + for (int i = 65537; --i >= 0;) + { + ftab[i] = 0; + } + + /* + * In the various block-sized structures, live data runs from 0 to + * last+NUM_OVERSHOOT_BYTES inclusive. First, set up the overshoot area + * for block. + */ + for (int i = 0; i < BZip2.NUM_OVERSHOOT_BYTES; i++) + { + block[lastShadow + i + 2] = block[(i % (lastShadow + 1)) + 1]; + } + for (int i = lastShadow + BZip2.NUM_OVERSHOOT_BYTES +1; --i >= 0;) + { + quadrant[i] = '\0'; + } + block[0] = block[lastShadow + 1]; + + // Complete the initial radix sort: + + int c1 = block[0] & 0xff; + for (int i = 0; i <= lastShadow; i++) + { + int c2 = block[i + 1] & 0xff; + ftab[(c1 << 8) + c2]++; + c1 = c2; + } + + for (int i = 1; i <= 65536; i++) + ftab[i] += ftab[i - 1]; + + c1 = block[1] & 0xff; + for (int i = 0; i < lastShadow; i++) + { + int c2 = block[i + 2] & 0xff; + fmap[--ftab[(c1 << 8) + c2]] = i; + c1 = c2; + } + + fmap[--ftab[((block[lastShadow + 1] & 0xff) << 8) + (block[1] & 0xff)]] = lastShadow; + + /* + * Now ftab contains the first loc of every small bucket. Calculate the + * running order, from smallest to largest big bucket. + */ + for (int i = 256; --i >= 0;) + { + bigDone[i] = false; + runningOrder[i] = i; + } + + for (int h = 364; h != 1;) + { + h /= 3; + for (int i = h; i <= 255; i++) + { + int vv = runningOrder[i]; + int a = ftab[(vv + 1) << 8] - ftab[vv << 8]; + int b = h - 1; + int j = i; + for (int ro = runningOrder[j - h]; (ftab[(ro + 1) << 8] - ftab[ro << 8]) > a; ro = runningOrder[j + - h]) + { + runningOrder[j] = ro; + j -= h; + if (j <= b) + { + break; + } + } + runningOrder[j] = vv; + } + } + + /* + * The main sorting loop. + */ + for (int i = 0; i <= 255; i++) + { + /* + * Process big buckets, starting with the least full. + */ + int ss = runningOrder[i]; + + // Step 1: + /* + * Complete the big bucket [ss] by quicksorting any unsorted small + * buckets [ss, j]. Hopefully previous pointer-scanning phases have + * already completed many of the small buckets [ss, j], so we don't + * have to sort them at all. + */ + for (int j = 0; j <= 255; j++) + { + int sb = (ss << 8) + j; + int ftab_sb = ftab[sb]; + if ((ftab_sb & SETMASK) != SETMASK) + { + int lo = ftab_sb & CLEARMASK; + int hi = (ftab[sb + 1] & CLEARMASK) - 1; + if (hi > lo) + { + mainQSort3(dataShadow, lo, hi, 2); + if (firstAttemptShadow + && (this.workDone > workLimitShadow)) + { + return; + } + } + ftab[sb] = ftab_sb | SETMASK; + } + } + + // Step 2: + // Now scan this big bucket so as to synthesise the + // sorted order for small buckets [t, ss] for all t != ss. + + for (int j = 0; j <= 255; j++) + { + copy[j] = ftab[(j << 8) + ss] & CLEARMASK; + } + + for (int j = ftab[ss << 8] & CLEARMASK, hj = (ftab[(ss + 1) << 8] & CLEARMASK); j < hj; j++) + { + int fmap_j = fmap[j]; + c1 = block[fmap_j] & 0xff; + if (!bigDone[c1]) + { + fmap[copy[c1]] = (fmap_j == 0) ? lastShadow : (fmap_j - 1); + copy[c1]++; + } + } + + for (int j = 256; --j >= 0;) + ftab[(j << 8) + ss] |= SETMASK; + + // Step 3: + /* + * The ss big bucket is now done. Record this fact, and update the + * quadrant descriptors. Remember to update quadrants in the + * overshoot area too, if necessary. The "if (i < 255)" test merely + * skips this updating for the last bucket processed, since updating + * for the last bucket is pointless. + */ + bigDone[ss] = true; + + if (i < 255) + { + int bbStart = ftab[ss << 8] & CLEARMASK; + int bbSize = (ftab[(ss + 1) << 8] & CLEARMASK) - bbStart; + int shifts = 0; + + while ((bbSize >> shifts) > 65534) + { + shifts++; + } + + for (int j = 0; j < bbSize; j++) + { + int a2update = fmap[bbStart + j]; + char qVal = (char) (j >> shifts); + quadrant[a2update] = qVal; + if (a2update < BZip2.NUM_OVERSHOOT_BYTES) + { + quadrant[a2update + lastShadow + 1] = qVal; + } + } + } + + } + } + + + private void blockSort() + { + this.workLimit = WORK_FACTOR * this.last; + this.workDone = 0; + this.blockRandomised = false; + this.firstAttempt = true; + mainSort(); + + if (this.firstAttempt && (this.workDone > this.workLimit)) + { + randomiseBlock(); + this.workLimit = this.workDone = 0; + this.firstAttempt = false; + mainSort(); + } + + int[] fmap = this.cstate.fmap; + this.origPtr = -1; + for (int i = 0, lastShadow = this.last; i <= lastShadow; i++) + { + if (fmap[i] == 0) + { + this.origPtr = i; + break; + } + } + + // assert (this.origPtr != -1) : this.origPtr; + } + + + /** + * This is the most hammered method of this class. + * + *

+ * This is the version using unrolled loops. + *

+ */ + private bool mainSimpleSort(CompressionState dataShadow, int lo, + int hi, int d) + { + int bigN = hi - lo + 1; + if (bigN < 2) + { + return this.firstAttempt && (this.workDone > this.workLimit); + } + + int hp = 0; + while (increments[hp] < bigN) + hp++; + + int[] fmap = dataShadow.fmap; + char[] quadrant = dataShadow.quadrant; + byte[] block = dataShadow.block; + int lastShadow = this.last; + int lastPlus1 = lastShadow + 1; + bool firstAttemptShadow = this.firstAttempt; + int workLimitShadow = this.workLimit; + int workDoneShadow = this.workDone; + + // Following block contains unrolled code which could be shortened by + // coding it in additional loops. + + // HP: + while (--hp >= 0) + { + int h = increments[hp]; + int mj = lo + h - 1; + + for (int i = lo + h; i <= hi;) + { + // copy + for (int k = 3; (i <= hi) && (--k >= 0); i++) + { + int v = fmap[i]; + int vd = v + d; + int j = i; + + // for (int a; + // (j > mj) && mainGtU((a = fmap[j - h]) + d, vd, + // block, quadrant, lastShadow); + // j -= h) { + // fmap[j] = a; + // } + // + // unrolled version: + + // start inline mainGTU + bool onceRunned = false; + int a = 0; + + HAMMER: while (true) + { + if (onceRunned) + { + fmap[j] = a; + if ((j -= h) <= mj) + { + goto END_HAMMER; + } + } + else { + onceRunned = true; + } + + a = fmap[j - h]; + int i1 = a + d; + int i2 = vd; + + // following could be done in a loop, but + // unrolled it for performance: + if (block[i1 + 1] == block[i2 + 1]) + { + if (block[i1 + 2] == block[i2 + 2]) + { + if (block[i1 + 3] == block[i2 + 3]) + { + if (block[i1 + 4] == block[i2 + 4]) + { + if (block[i1 + 5] == block[i2 + 5]) + { + if (block[(i1 += 6)] == block[(i2 += 6)]) + { + int x = lastShadow; + X: while (x > 0) + { + x -= 4; + + if (block[i1 + 1] == block[i2 + 1]) + { + if (quadrant[i1] == quadrant[i2]) + { + if (block[i1 + 2] == block[i2 + 2]) + { + if (quadrant[i1 + 1] == quadrant[i2 + 1]) + { + if (block[i1 + 3] == block[i2 + 3]) + { + if (quadrant[i1 + 2] == quadrant[i2 + 2]) + { + if (block[i1 + 4] == block[i2 + 4]) + { + if (quadrant[i1 + 3] == quadrant[i2 + 3]) + { + if ((i1 += 4) >= lastPlus1) + { + i1 -= lastPlus1; + } + if ((i2 += 4) >= lastPlus1) + { + i2 -= lastPlus1; + } + workDoneShadow++; + goto X; + } + else if ((quadrant[i1 + 3] > quadrant[i2 + 3])) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + } + else if ((block[i1 + 4] & 0xff) > (block[i2 + 4] & 0xff)) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + } + else if ((quadrant[i1 + 2] > quadrant[i2 + 2])) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + } + else if ((block[i1 + 3] & 0xff) > (block[i2 + 3] & 0xff)) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + } + else if ((quadrant[i1 + 1] > quadrant[i2 + 1])) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + } + else if ((block[i1 + 2] & 0xff) > (block[i2 + 2] & 0xff)) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + } + else if ((quadrant[i1] > quadrant[i2])) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + } + else if ((block[i1 + 1] & 0xff) > (block[i2 + 1] & 0xff)) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + + } + goto END_HAMMER; + } // while x > 0 + else { + if ((block[i1] & 0xff) > (block[i2] & 0xff)) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + } + } + else if ((block[i1 + 5] & 0xff) > (block[i2 + 5] & 0xff)) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + } + else if ((block[i1 + 4] & 0xff) > (block[i2 + 4] & 0xff)) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + } + else if ((block[i1 + 3] & 0xff) > (block[i2 + 3] & 0xff)) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + } + else if ((block[i1 + 2] & 0xff) > (block[i2 + 2] & 0xff)) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + } + else if ((block[i1 + 1] & 0xff) > (block[i2 + 1] & 0xff)) + { + goto HAMMER; + } + else { + goto END_HAMMER; + } + + } // HAMMER + + END_HAMMER: + // end inline mainGTU + + fmap[j] = v; + } + + if (firstAttemptShadow && (i <= hi) + && (workDoneShadow > workLimitShadow)) + { + goto END_HP; + } + } + } + END_HP: + + this.workDone = workDoneShadow; + return firstAttemptShadow && (workDoneShadow > workLimitShadow); + } + + + + private static void vswap(int[] fmap, int p1, int p2, int n) + { + n += p1; + while (p1 < n) + { + int t = fmap[p1]; + fmap[p1++] = fmap[p2]; + fmap[p2++] = t; + } + } + + private static byte med3(byte a, byte b, byte c) + { + return (a < b) ? (b < c ? b : a < c ? c : a) : (b > c ? b : a > c ? c + : a); + } + + + /** + * Method "mainQSort3", file "blocksort.c", BZip2 1.0.2 + */ + private void mainQSort3(CompressionState dataShadow, int loSt, + int hiSt, int dSt) + { + int[] stack_ll = dataShadow.stack_ll; + int[] stack_hh = dataShadow.stack_hh; + int[] stack_dd = dataShadow.stack_dd; + int[] fmap = dataShadow.fmap; + byte[] block = dataShadow.block; + + stack_ll[0] = loSt; + stack_hh[0] = hiSt; + stack_dd[0] = dSt; + + for (int sp = 1; --sp >= 0;) + { + int lo = stack_ll[sp]; + int hi = stack_hh[sp]; + int d = stack_dd[sp]; + + if ((hi - lo < SMALL_THRESH) || (d > DEPTH_THRESH)) + { + if (mainSimpleSort(dataShadow, lo, hi, d)) + { + return; + } + } + else { + int d1 = d + 1; + int med = med3(block[fmap[lo] + d1], + block[fmap[hi] + d1], block[fmap[(lo + hi) >> 1] + d1]) & 0xff; + + int unLo = lo; + int unHi = hi; + int ltLo = lo; + int gtHi = hi; + + while (true) + { + while (unLo <= unHi) + { + int n = (block[fmap[unLo] + d1] & 0xff) + - med; + if (n == 0) + { + int temp = fmap[unLo]; + fmap[unLo++] = fmap[ltLo]; + fmap[ltLo++] = temp; + } + else if (n < 0) + { + unLo++; + } + else { + break; + } + } + + while (unLo <= unHi) + { + int n = (block[fmap[unHi] + d1] & 0xff) + - med; + if (n == 0) + { + int temp = fmap[unHi]; + fmap[unHi--] = fmap[gtHi]; + fmap[gtHi--] = temp; + } + else if (n > 0) + { + unHi--; + } + else { + break; + } + } + + if (unLo <= unHi) + { + int temp = fmap[unLo]; + fmap[unLo++] = fmap[unHi]; + fmap[unHi--] = temp; + } + else { + break; + } + } + + if (gtHi < ltLo) + { + stack_ll[sp] = lo; + stack_hh[sp] = hi; + stack_dd[sp] = d1; + sp++; + } + else { + int n = ((ltLo - lo) < (unLo - ltLo)) ? (ltLo - lo) + : (unLo - ltLo); + vswap(fmap, lo, unLo - n, n); + int m = ((hi - gtHi) < (gtHi - unHi)) ? (hi - gtHi) + : (gtHi - unHi); + vswap(fmap, unLo, hi - m + 1, m); + + n = lo + unLo - ltLo - 1; + m = hi - (gtHi - unHi) + 1; + + stack_ll[sp] = lo; + stack_hh[sp] = n; + stack_dd[sp] = d; + sp++; + + stack_ll[sp] = n + 1; + stack_hh[sp] = m - 1; + stack_dd[sp] = d1; + sp++; + + stack_ll[sp] = m; + stack_hh[sp] = hi; + stack_dd[sp] = d; + sp++; + } + } + } + } + + + + private void generateMTFValues() + { + int lastShadow = this.last; + CompressionState dataShadow = this.cstate; + bool[] inUse = dataShadow.inUse; + byte[] block = dataShadow.block; + int[] fmap = dataShadow.fmap; + char[] sfmap = dataShadow.sfmap; + int[] mtfFreq = dataShadow.mtfFreq; + byte[] unseqToSeq = dataShadow.unseqToSeq; + byte[] yy = dataShadow.generateMTFValues_yy; + + // make maps + int nInUseShadow = 0; + for (int i = 0; i < 256; i++) + { + if (inUse[i]) + { + unseqToSeq[i] = (byte) nInUseShadow; + nInUseShadow++; + } + } + this.nInUse = nInUseShadow; + + int eob = nInUseShadow + 1; + + for (int i = eob; i >= 0; i--) + { + mtfFreq[i] = 0; + } + + for (int i = nInUseShadow; --i >= 0;) + { + yy[i] = (byte) i; + } + + int wr = 0; + int zPend = 0; + + for (int i = 0; i <= lastShadow; i++) + { + byte ll_i = unseqToSeq[block[fmap[i]] & 0xff]; + byte tmp = yy[0]; + int j = 0; + + while (ll_i != tmp) + { + j++; + byte tmp2 = tmp; + tmp = yy[j]; + yy[j] = tmp2; + } + yy[0] = tmp; + + if (j == 0) + { + zPend++; + } + else + { + if (zPend > 0) + { + zPend--; + while (true) + { + if ((zPend & 1) == 0) + { + sfmap[wr] = BZip2.RUNA; + wr++; + mtfFreq[BZip2.RUNA]++; + } + else + { + sfmap[wr] = BZip2.RUNB; + wr++; + mtfFreq[BZip2.RUNB]++; + } + + if (zPend >= 2) + { + zPend = (zPend - 2) >> 1; + } + else + { + break; + } + } + zPend = 0; + } + sfmap[wr] = (char) (j + 1); + wr++; + mtfFreq[j + 1]++; + } + } + + if (zPend > 0) + { + zPend--; + while (true) + { + if ((zPend & 1) == 0) + { + sfmap[wr] = BZip2.RUNA; + wr++; + mtfFreq[BZip2.RUNA]++; + } + else + { + sfmap[wr] = BZip2.RUNB; + wr++; + mtfFreq[BZip2.RUNB]++; + } + + if (zPend >= 2) + { + zPend = (zPend - 2) >> 1; + } + else + { + break; + } + } + } + + sfmap[wr] = (char) eob; + mtfFreq[eob]++; + this.nMTF = wr + 1; + } + + + private static void hbAssignCodes(int[] code, byte[] length, + int minLen, int maxLen, + int alphaSize) + { + int vec = 0; + for (int n = minLen; n <= maxLen; n++) + { + for (int i = 0; i < alphaSize; i++) + { + if ((length[i] & 0xff) == n) + { + code[i] = vec; + vec++; + } + } + vec <<= 1; + } + } + + + + + private void sendMTFValues() + { + byte[][] len = this.cstate.sendMTFValues_len; + int alphaSize = this.nInUse + 2; + + for (int t = BZip2.NGroups; --t >= 0;) + { + byte[] len_t = len[t]; + for (int v = alphaSize; --v >= 0;) + { + len_t[v] = GREATER_ICOST; + } + } + + /* Decide how many coding tables to use */ + // assert (this.nMTF > 0) : this.nMTF; + int nGroups = (this.nMTF < 200) ? 2 : (this.nMTF < 600) ? 3 + : (this.nMTF < 1200) ? 4 : (this.nMTF < 2400) ? 5 : 6; + + /* Generate an initial set of coding tables */ + sendMTFValues0(nGroups, alphaSize); + + /* + * Iterate up to N_ITERS times to improve the tables. + */ + int nSelectors = sendMTFValues1(nGroups, alphaSize); + + /* Compute MTF values for the selectors. */ + sendMTFValues2(nGroups, nSelectors); + + /* Assign actual codes for the tables. */ + sendMTFValues3(nGroups, alphaSize); + + /* Transmit the mapping table. */ + sendMTFValues4(); + + /* Now the selectors. */ + sendMTFValues5(nGroups, nSelectors); + + /* Now the coding tables. */ + sendMTFValues6(nGroups, alphaSize); + + /* And finally, the block data proper */ + sendMTFValues7(nSelectors); + } + + private void sendMTFValues0(int nGroups, int alphaSize) + { + byte[][] len = this.cstate.sendMTFValues_len; + int[] mtfFreq = this.cstate.mtfFreq; + + int remF = this.nMTF; + int gs = 0; + + for (int nPart = nGroups; nPart > 0; nPart--) + { + int tFreq = remF / nPart; + int ge = gs - 1; + int aFreq = 0; + + for (int a = alphaSize - 1; (aFreq < tFreq) && (ge < a);) + { + aFreq += mtfFreq[++ge]; + } + + if ((ge > gs) && (nPart != nGroups) && (nPart != 1) + && (((nGroups - nPart) & 1) != 0)) + { + aFreq -= mtfFreq[ge--]; + } + + byte[] len_np = len[nPart - 1]; + for (int v = alphaSize; --v >= 0;) + { + if ((v >= gs) && (v <= ge)) + { + len_np[v] = LESSER_ICOST; + } + else { + len_np[v] = GREATER_ICOST; + } + } + + gs = ge + 1; + remF -= aFreq; + } + } + + + private static void hbMakeCodeLengths(byte[] len, int[] freq, + CompressionState state1, int alphaSize, + int maxLen) + { + /* + * Nodes and heap entries run from 1. Entry 0 for both the heap and + * nodes is a sentinel. + */ + int[] heap = state1.heap; + int[] weight = state1.weight; + int[] parent = state1.parent; + + for (int i = alphaSize; --i >= 0;) + { + weight[i + 1] = (freq[i] == 0 ? 1 : freq[i]) << 8; + } + + for (bool tooLong = true; tooLong;) + { + tooLong = false; + + int nNodes = alphaSize; + int nHeap = 0; + heap[0] = 0; + weight[0] = 0; + parent[0] = -2; + + for (int i = 1; i <= alphaSize; i++) + { + parent[i] = -1; + nHeap++; + heap[nHeap] = i; + + int zz = nHeap; + int tmp = heap[zz]; + while (weight[tmp] < weight[heap[zz >> 1]]) + { + heap[zz] = heap[zz >> 1]; + zz >>= 1; + } + heap[zz] = tmp; + } + + while (nHeap > 1) + { + int n1 = heap[1]; + heap[1] = heap[nHeap]; + nHeap--; + + int yy = 0; + int zz = 1; + int tmp = heap[1]; + + while (true) + { + yy = zz << 1; + + if (yy > nHeap) + { + break; + } + + if ((yy < nHeap) + && (weight[heap[yy + 1]] < weight[heap[yy]])) + { + yy++; + } + + if (weight[tmp] < weight[heap[yy]]) + { + break; + } + + heap[zz] = heap[yy]; + zz = yy; + } + + heap[zz] = tmp; + + int n2 = heap[1]; + heap[1] = heap[nHeap]; + nHeap--; + + yy = 0; + zz = 1; + tmp = heap[1]; + + while (true) + { + yy = zz << 1; + + if (yy > nHeap) + { + break; + } + + if ((yy < nHeap) + && (weight[heap[yy + 1]] < weight[heap[yy]])) + { + yy++; + } + + if (weight[tmp] < weight[heap[yy]]) + { + break; + } + + heap[zz] = heap[yy]; + zz = yy; + } + + heap[zz] = tmp; + nNodes++; + parent[n1] = parent[n2] = nNodes; + + int weight_n1 = weight[n1]; + int weight_n2 = weight[n2]; + weight[nNodes] = (int) (((uint)weight_n1 & 0xffffff00U) + + ((uint)weight_n2 & 0xffffff00U)) + | (1 + (((weight_n1 & 0x000000ff) + > (weight_n2 & 0x000000ff)) + ? (weight_n1 & 0x000000ff) + : (weight_n2 & 0x000000ff))); + + parent[nNodes] = -1; + nHeap++; + heap[nHeap] = nNodes; + + tmp = 0; + zz = nHeap; + tmp = heap[zz]; + int weight_tmp = weight[tmp]; + while (weight_tmp < weight[heap[zz >> 1]]) + { + heap[zz] = heap[zz >> 1]; + zz >>= 1; + } + heap[zz] = tmp; + + } + + for (int i = 1; i <= alphaSize; i++) + { + int j = 0; + int k = i; + + for (int parent_k; (parent_k = parent[k]) >= 0;) + { + k = parent_k; + j++; + } + + len[i - 1] = (byte) j; + if (j > maxLen) + { + tooLong = true; + } + } + + if (tooLong) + { + for (int i = 1; i < alphaSize; i++) + { + int j = weight[i] >> 8; + j = 1 + (j >> 1); + weight[i] = j << 8; + } + } + } + } + + + private int sendMTFValues1(int nGroups, int alphaSize) + { + CompressionState dataShadow = this.cstate; + int[][] rfreq = dataShadow.sendMTFValues_rfreq; + int[] fave = dataShadow.sendMTFValues_fave; + short[] cost = dataShadow.sendMTFValues_cost; + char[] sfmap = dataShadow.sfmap; + byte[] selector = dataShadow.selector; + byte[][] len = dataShadow.sendMTFValues_len; + byte[] len_0 = len[0]; + byte[] len_1 = len[1]; + byte[] len_2 = len[2]; + byte[] len_3 = len[3]; + byte[] len_4 = len[4]; + byte[] len_5 = len[5]; + int nMTFShadow = this.nMTF; + + int nSelectors = 0; + + for (int iter = 0; iter < BZip2.N_ITERS; iter++) + { + for (int t = nGroups; --t >= 0;) + { + fave[t] = 0; + int[] rfreqt = rfreq[t]; + for (int i = alphaSize; --i >= 0;) + { + rfreqt[i] = 0; + } + } + + nSelectors = 0; + + for (int gs = 0; gs < this.nMTF;) + { + /* Set group start & end marks. */ + + /* + * Calculate the cost of this group as coded by each of the + * coding tables. + */ + + int ge = Math.Min(gs + BZip2.G_SIZE - 1, nMTFShadow - 1); + + if (nGroups == BZip2.NGroups) + { + // unrolled version of the else-block + + int[] c = new int[6]; + + for (int i = gs; i <= ge; i++) + { + int icv = sfmap[i]; + c[0] += len_0[icv] & 0xff; + c[1] += len_1[icv] & 0xff; + c[2] += len_2[icv] & 0xff; + c[3] += len_3[icv] & 0xff; + c[4] += len_4[icv] & 0xff; + c[5] += len_5[icv] & 0xff; + } + + cost[0] = (short) c[0]; + cost[1] = (short) c[1]; + cost[2] = (short) c[2]; + cost[3] = (short) c[3]; + cost[4] = (short) c[4]; + cost[5] = (short) c[5]; + } + else + { + for (int t = nGroups; --t >= 0;) + { + cost[t] = 0; + } + + for (int i = gs; i <= ge; i++) + { + int icv = sfmap[i]; + for (int t = nGroups; --t >= 0;) + { + cost[t] += (short) (len[t][icv] & 0xff); + } + } + } + + /* + * Find the coding table which is best for this group, and + * record its identity in the selector table. + */ + int bt = -1; + for (int t = nGroups, bc = 999999999; --t >= 0;) + { + int cost_t = cost[t]; + if (cost_t < bc) + { + bc = cost_t; + bt = t; + } + } + + fave[bt]++; + selector[nSelectors] = (byte) bt; + nSelectors++; + + /* + * Increment the symbol frequencies for the selected table. + */ + int[] rfreq_bt = rfreq[bt]; + for (int i = gs; i <= ge; i++) + { + rfreq_bt[sfmap[i]]++; + } + + gs = ge + 1; + } + + /* + * Recompute the tables based on the accumulated frequencies. + */ + for (int t = 0; t < nGroups; t++) + { + hbMakeCodeLengths(len[t], rfreq[t], this.cstate, alphaSize, 20); + } + } + + return nSelectors; + } + + private void sendMTFValues2(int nGroups, int nSelectors) + { + // assert (nGroups < 8) : nGroups; + + CompressionState dataShadow = this.cstate; + byte[] pos = dataShadow.sendMTFValues2_pos; + + for (int i = nGroups; --i >= 0;) + { + pos[i] = (byte) i; + } + + for (int i = 0; i < nSelectors; i++) + { + byte ll_i = dataShadow.selector[i]; + byte tmp = pos[0]; + int j = 0; + + while (ll_i != tmp) + { + j++; + byte tmp2 = tmp; + tmp = pos[j]; + pos[j] = tmp2; + } + + pos[0] = tmp; + dataShadow.selectorMtf[i] = (byte) j; + } + } + + private void sendMTFValues3(int nGroups, int alphaSize) + { + int[][] code = this.cstate.sendMTFValues_code; + byte[][] len = this.cstate.sendMTFValues_len; + + for (int t = 0; t < nGroups; t++) + { + int minLen = 32; + int maxLen = 0; + byte[] len_t = len[t]; + for (int i = alphaSize; --i >= 0;) + { + int l = len_t[i] & 0xff; + if (l > maxLen) + { + maxLen = l; + } + if (l < minLen) + { + minLen = l; + } + } + + // assert (maxLen <= 20) : maxLen; + // assert (minLen >= 1) : minLen; + + hbAssignCodes(code[t], len[t], minLen, maxLen, alphaSize); + } + } + + private void sendMTFValues4() + { + bool[] inUse = this.cstate.inUse; + bool[] inUse16 = this.cstate.sentMTFValues4_inUse16; + + for (int i = 16; --i >= 0;) + { + inUse16[i] = false; + int i16 = i * 16; + for (int j = 16; --j >= 0;) + { + if (inUse[i16 + j]) + { + inUse16[i] = true; + } + } + } + + uint u = 0; + for (int i = 0; i < 16; i++) + { + if (inUse16[i]) + u |= 1U << (16 - i - 1); + } + this.bw.WriteBits(16, u); + + + for (int i = 0; i < 16; i++) + { + if (inUse16[i]) + { + int i16 = i * 16; + u = 0; + for (int j = 0; j < 16; j++) + { + if (inUse[i16 + j]) + { + u |= 1U << (16 - j - 1); + } + } + this.bw.WriteBits(16, u); + } + } + } + + + private void sendMTFValues5(int nGroups, int nSelectors) + { + this.bw.WriteBits(3, (uint) nGroups); + this.bw.WriteBits(15, (uint) nSelectors); + + byte[] selectorMtf = this.cstate.selectorMtf; + + for (int i = 0; i < nSelectors; i++) + { + for (int j = 0, hj = selectorMtf[i] & 0xff; j < hj; j++) + { + this.bw.WriteBits(1, 1); + } + + this.bw.WriteBits(1, 0); + } + } + + private void sendMTFValues6(int nGroups, int alphaSize) + { + byte[][] len = this.cstate.sendMTFValues_len; + + for (int t = 0; t < nGroups; t++) + { + byte[] len_t = len[t]; + uint curr = (uint) (len_t[0] & 0xff); + this.bw.WriteBits(5, curr); + + for (int i = 0; i < alphaSize; i++) + { + int lti = len_t[i] & 0xff; + while (curr < lti) + { + this.bw.WriteBits(2, 2U); + curr++; /* 10 */ + } + + while (curr > lti) + { + this.bw.WriteBits(2, 3U); + curr--; /* 11 */ + } + + this.bw.WriteBits(1, 0U); + } + } + } + + + private void sendMTFValues7(int nSelectors) + { + byte[][] len = this.cstate.sendMTFValues_len; + int[][] code = this.cstate.sendMTFValues_code; + byte[] selector = this.cstate.selector; + char[] sfmap = this.cstate.sfmap; + int nMTFShadow = this.nMTF; + + int selCtr = 0; + + for (int gs = 0; gs < nMTFShadow;) + { + int ge = Math.Min(gs + BZip2.G_SIZE - 1, nMTFShadow - 1); + int ix = selector[selCtr] & 0xff; + int[] code_selCtr = code[ix]; + byte[] len_selCtr = len[ix]; + + while (gs <= ge) + { + int sfmap_i = sfmap[gs]; + int n = len_selCtr[sfmap_i] & 0xFF; + this.bw.WriteBits(n, (uint) code_selCtr[sfmap_i]); + gs++; + } + + gs = ge + 1; + selCtr++; + } + } + + private void moveToFrontCodeAndSend() + { + this.bw.WriteBits(24, (uint) this.origPtr); + generateMTFValues(); + sendMTFValues(); + } + + + + + + + private class CompressionState + { + // with blockSize 900k + public readonly bool[] inUse = new bool[256]; // 256 byte + public readonly byte[] unseqToSeq = new byte[256]; // 256 byte + public readonly int[] mtfFreq = new int[BZip2.MaxAlphaSize]; // 1032 byte + public readonly byte[] selector = new byte[BZip2.MaxSelectors]; // 18002 byte + public readonly byte[] selectorMtf = new byte[BZip2.MaxSelectors]; // 18002 byte + + public readonly byte[] generateMTFValues_yy = new byte[256]; // 256 byte + public byte[][] sendMTFValues_len; + + // byte + public int[][] sendMTFValues_rfreq; + + // byte + public readonly int[] sendMTFValues_fave = new int[BZip2.NGroups]; // 24 byte + public readonly short[] sendMTFValues_cost = new short[BZip2.NGroups]; // 12 byte + public int[][] sendMTFValues_code; + + // byte + public readonly byte[] sendMTFValues2_pos = new byte[BZip2.NGroups]; // 6 byte + public readonly bool[] sentMTFValues4_inUse16 = new bool[16]; // 16 byte + + public readonly int[] stack_ll = new int[BZip2.QSORT_STACK_SIZE]; // 4000 byte + public readonly int[] stack_hh = new int[BZip2.QSORT_STACK_SIZE]; // 4000 byte + public readonly int[] stack_dd = new int[BZip2.QSORT_STACK_SIZE]; // 4000 byte + + public readonly int[] mainSort_runningOrder = new int[256]; // 1024 byte + public readonly int[] mainSort_copy = new int[256]; // 1024 byte + public readonly bool[] mainSort_bigDone = new bool[256]; // 256 byte + + public int[] heap = new int[BZip2.MaxAlphaSize + 2]; // 1040 byte + public int[] weight = new int[BZip2.MaxAlphaSize * 2]; // 2064 byte + public int[] parent = new int[BZip2.MaxAlphaSize * 2]; // 2064 byte + + public readonly int[] ftab = new int[65537]; // 262148 byte + // ------------ + // 333408 byte + + public byte[] block; // 900021 byte + public int[] fmap; // 3600000 byte + public char[] sfmap; // 3600000 byte + + // ------------ + // 8433529 byte + // ============ + + /** + * Array instance identical to sfmap, both are used only + * temporarily and independently, so we do not need to allocate + * additional memory. + */ + public char[] quadrant; + + public CompressionState(int blockSize100k) + { + int n = blockSize100k * BZip2.BlockSizeMultiple; + this.block = new byte[(n + 1 + BZip2.NUM_OVERSHOOT_BYTES)]; + this.fmap = new int[n]; + this.sfmap = new char[2 * n]; + this.quadrant = this.sfmap; + this.sendMTFValues_len = BZip2.InitRectangularArray(BZip2.NGroups,BZip2.MaxAlphaSize); + this.sendMTFValues_rfreq = BZip2.InitRectangularArray(BZip2.NGroups,BZip2.MaxAlphaSize); + this.sendMTFValues_code = BZip2.InitRectangularArray(BZip2.NGroups,BZip2.MaxAlphaSize); + } + + } + + + + } +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/BZip2/BZip2InputStream.cs b/Resources/Libraries/DotNetZip/Source/BZip2/BZip2InputStream.cs new file mode 100644 index 00000000..1c152d58 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/BZip2/BZip2InputStream.cs @@ -0,0 +1,1447 @@ +// BZip2InputStream.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// Last Saved: <2011-July-31 11:57:32> +// +// ------------------------------------------------------------------ +// +// This module defines the BZip2InputStream class, which is a decompressing +// stream that handles BZIP2. This code is derived from Apache commons source code. +// The license below applies to the original Apache code. +// +// ------------------------------------------------------------------ + +/* + * 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 package is based on the work done by Keiron Liddle, Aftex Software + * to whom the Ant project is very grateful for his + * great code. + */ + +// compile: msbuild +// not: csc.exe /t:library /debug+ /out:Ionic.BZip2.dll BZip2InputStream.cs BCRC32.cs Rand.cs + + + +using System; +using System.IO; + +namespace Ionic.BZip2 +{ + + /// + /// A read-only decorator stream that performs BZip2 decompression on Read. + /// + public class BZip2InputStream : System.IO.Stream + { + bool _disposed; + bool _leaveOpen; + Int64 totalBytesRead; + private int last; + + /* for undoing the Burrows-Wheeler transform */ + private int origPtr; + + // blockSize100k: 0 .. 9. + // + // This var name is a misnomer. The actual block size is 100000 + // * blockSize100k. (not 100k * blocksize100k) + private int blockSize100k; + private bool blockRandomised; + private int bsBuff; + private int bsLive; + private readonly Ionic.Crc.CRC32 crc = new Ionic.Crc.CRC32(true); + private int nInUse; + private Stream input; + private int currentChar = -1; + + /// + /// Compressor State + /// + enum CState + { + EOF = 0, + START_BLOCK = 1, + RAND_PART_A = 2, + RAND_PART_B = 3, + RAND_PART_C = 4, + NO_RAND_PART_A = 5, + NO_RAND_PART_B = 6, + NO_RAND_PART_C = 7, + } + + private CState currentState = CState.START_BLOCK; + + private uint storedBlockCRC, storedCombinedCRC; + private uint computedBlockCRC, computedCombinedCRC; + + // Variables used by setup* methods exclusively + private int su_count; + private int su_ch2; + private int su_chPrev; + private int su_i2; + private int su_j2; + private int su_rNToGo; + private int su_rTPos; + private int su_tPos; + private char su_z; + private BZip2InputStream.DecompressionState data; + + + /// + /// Create a BZip2InputStream, wrapping it around the given input Stream. + /// + /// + /// + /// The input stream will be closed when the BZip2InputStream is closed. + /// + /// + /// The stream from which to read compressed data + public BZip2InputStream(Stream input) + : this(input, false) + {} + + + /// + /// Create a BZip2InputStream with the given stream, and + /// specifying whether to leave the wrapped stream open when + /// the BZip2InputStream is closed. + /// + /// The stream from which to read compressed data + /// + /// Whether to leave the input stream open, when the BZip2InputStream closes. + /// + /// + /// + /// + /// This example reads a bzip2-compressed file, decompresses it, + /// and writes the decompressed data into a newly created file. + /// + /// + /// var fname = "logfile.log.bz2"; + /// using (var fs = File.OpenRead(fname)) + /// { + /// using (var decompressor = new Ionic.BZip2.BZip2InputStream(fs)) + /// { + /// var outFname = fname + ".decompressed"; + /// using (var output = File.Create(outFname)) + /// { + /// byte[] buffer = new byte[2048]; + /// int n; + /// while ((n = decompressor.Read(buffer, 0, buffer.Length)) > 0) + /// { + /// output.Write(buffer, 0, n); + /// } + /// } + /// } + /// } + /// + /// + public BZip2InputStream(Stream input, bool leaveOpen) + : base() + { + + this.input = input; + this._leaveOpen = leaveOpen; + init(); + } + + /// + /// Read data from the stream. + /// + /// + /// + /// + /// To decompress a BZip2 data stream, create a BZip2InputStream, + /// providing a stream that reads compressed data. Then call Read() on + /// that BZip2InputStream, and the data read will be decompressed + /// as you read. + /// + /// + /// + /// A BZip2InputStream can be used only for Read(), not for Write(). + /// + /// + /// + /// The buffer into which the read data should be placed. + /// the offset within that data array to put the first byte read. + /// the number of bytes to read. + /// the number of bytes actually read + public override int Read(byte[] buffer, int offset, int count) + { + if (offset < 0) + throw new IndexOutOfRangeException(String.Format("offset ({0}) must be > 0", offset)); + + if (count < 0) + throw new IndexOutOfRangeException(String.Format("count ({0}) must be > 0", count)); + + if (offset + count > buffer.Length) + throw new IndexOutOfRangeException(String.Format("offset({0}) count({1}) bLength({2})", + offset, count, buffer.Length)); + + if (this.input == null) + throw new IOException("the stream is not open"); + + + int hi = offset + count; + int destOffset = offset; + for (int b; (destOffset < hi) && ((b = ReadByte()) >= 0);) + { + buffer[destOffset++] = (byte) b; + } + + return (destOffset == offset) ? -1 : (destOffset - offset); + } + + private void MakeMaps() + { + bool[] inUse = this.data.inUse; + byte[] seqToUnseq = this.data.seqToUnseq; + + int n = 0; + + for (int i = 0; i < 256; i++) + { + if (inUse[i]) + seqToUnseq[n++] = (byte) i; + } + + this.nInUse = n; + } + + /// + /// Read a single byte from the stream. + /// + /// the byte read from the stream, or -1 if EOF + public override int ReadByte() + { + int retChar = this.currentChar; + totalBytesRead++; + switch (this.currentState) + { + case CState.EOF: + return -1; + + case CState.START_BLOCK: + throw new IOException("bad state"); + + case CState.RAND_PART_A: + throw new IOException("bad state"); + + case CState.RAND_PART_B: + SetupRandPartB(); + break; + + case CState.RAND_PART_C: + SetupRandPartC(); + break; + + case CState.NO_RAND_PART_A: + throw new IOException("bad state"); + + case CState.NO_RAND_PART_B: + SetupNoRandPartB(); + break; + + case CState.NO_RAND_PART_C: + SetupNoRandPartC(); + break; + + default: + throw new IOException("bad state"); + } + + return retChar; + } + + + + + /// + /// Indicates whether the stream can be read. + /// + /// + /// The return value depends on whether the captive stream supports reading. + /// + public override bool CanRead + { + get + { + if (_disposed) throw new ObjectDisposedException("BZip2Stream"); + return this.input.CanRead; + } + } + + + /// + /// Indicates whether the stream supports Seek operations. + /// + /// + /// Always returns false. + /// + public override bool CanSeek + { + get { return false; } + } + + + /// + /// Indicates whether the stream can be written. + /// + /// + /// The return value depends on whether the captive stream supports writing. + /// + public override bool CanWrite + { + get + { + if (_disposed) throw new ObjectDisposedException("BZip2Stream"); + return input.CanWrite; + } + } + + /// + /// Flush the stream. + /// + public override void Flush() + { + if (_disposed) throw new ObjectDisposedException("BZip2Stream"); + input.Flush(); + } + + /// + /// Reading this property always throws a . + /// + public override long Length + { + get { throw new NotImplementedException(); } + } + + /// + /// The position of the stream pointer. + /// + /// + /// + /// Setting this property always throws a . Reading will return the + /// total number of uncompressed bytes read in. + /// + public override long Position + { + get + { + return this.totalBytesRead; + } + set { throw new NotImplementedException(); } + } + + /// + /// Calling this method always throws a . + /// + /// this is irrelevant, since it will always throw! + /// this is irrelevant, since it will always throw! + /// irrelevant! + public override long Seek(long offset, System.IO.SeekOrigin origin) + { + throw new NotImplementedException(); + } + + /// + /// Calling this method always throws a . + /// + /// this is irrelevant, since it will always throw! + public override void SetLength(long value) + { + throw new NotImplementedException(); + } + + /// + /// Calling this method always throws a . + /// + /// this parameter is never used + /// this parameter is never used + /// this parameter is never used + public override void Write(byte[] buffer, int offset, int count) + { + throw new NotImplementedException(); + } + + + /// + /// Dispose the stream. + /// + /// + /// indicates whether the Dispose method was invoked by user code. + /// + protected override void Dispose(bool disposing) + { + try + { + if (!_disposed) + { + if (disposing && (this.input != null)) + this.input.Close(); + _disposed = true; + } + } + finally + { + base.Dispose(disposing); + } + } + + + void init() + { + if (null == this.input) + throw new IOException("No input Stream"); + + if (!this.input.CanRead) + throw new IOException("Unreadable input Stream"); + + CheckMagicChar('B', 0); + CheckMagicChar('Z', 1); + CheckMagicChar('h', 2); + + int blockSize = this.input.ReadByte(); + + if ((blockSize < '1') || (blockSize > '9')) + throw new IOException("Stream is not BZip2 formatted: illegal " + + "blocksize " + (char) blockSize); + + this.blockSize100k = blockSize - '0'; + + InitBlock(); + SetupBlock(); + } + + + void CheckMagicChar(char expected, int position) + { + int magic = this.input.ReadByte(); + if (magic != (int)expected) + { + var msg = String.Format("Not a valid BZip2 stream. byte {0}, expected '{1}', got '{2}'", + position, (int)expected, magic); + throw new IOException(msg); + } + } + + + void InitBlock() + { + char magic0 = bsGetUByte(); + char magic1 = bsGetUByte(); + char magic2 = bsGetUByte(); + char magic3 = bsGetUByte(); + char magic4 = bsGetUByte(); + char magic5 = bsGetUByte(); + + if (magic0 == 0x17 && magic1 == 0x72 && magic2 == 0x45 + && magic3 == 0x38 && magic4 == 0x50 && magic5 == 0x90) + { + complete(); // end of file + } + else if (magic0 != 0x31 || + magic1 != 0x41 || + magic2 != 0x59 || + magic3 != 0x26 || + magic4 != 0x53 || + magic5 != 0x59) + { + this.currentState = CState.EOF; + var msg = String.Format("bad block header at offset 0x{0:X}", + this.input.Position); + throw new IOException(msg); + } + else + { + this.storedBlockCRC = bsGetInt(); + // Console.WriteLine(" stored block CRC : {0:X8}", this.storedBlockCRC); + + this.blockRandomised = (GetBits(1) == 1); + + // Lazily allocate data + if (this.data == null) + this.data = new DecompressionState(this.blockSize100k); + + // currBlockNo++; + getAndMoveToFrontDecode(); + + this.crc.Reset(); + this.currentState = CState.START_BLOCK; + } + } + + + private void EndBlock() + { + this.computedBlockCRC = (uint)this.crc.Crc32Result; + + // A bad CRC is considered a fatal error. + if (this.storedBlockCRC != this.computedBlockCRC) + { + // make next blocks readable without error + // (repair feature, not yet documented, not tested) + // this.computedCombinedCRC = (this.storedCombinedCRC << 1) + // | (this.storedCombinedCRC >> 31); + // this.computedCombinedCRC ^= this.storedBlockCRC; + + var msg = String.Format("BZip2 CRC error (expected {0:X8}, computed {1:X8})", + this.storedBlockCRC, this.computedBlockCRC); + throw new IOException(msg); + } + + // Console.WriteLine(" combined CRC (before): {0:X8}", this.computedCombinedCRC); + this.computedCombinedCRC = (this.computedCombinedCRC << 1) + | (this.computedCombinedCRC >> 31); + this.computedCombinedCRC ^= this.computedBlockCRC; + // Console.WriteLine(" computed block CRC : {0:X8}", this.computedBlockCRC); + // Console.WriteLine(" combined CRC (after) : {0:X8}", this.computedCombinedCRC); + // Console.WriteLine(); + } + + + private void complete() + { + this.storedCombinedCRC = bsGetInt(); + this.currentState = CState.EOF; + this.data = null; + + if (this.storedCombinedCRC != this.computedCombinedCRC) + { + var msg = String.Format("BZip2 CRC error (expected {0:X8}, computed {1:X8})", + this.storedCombinedCRC, this.computedCombinedCRC); + + throw new IOException(msg); + } + } + + /// + /// Close the stream. + /// + public override void Close() + { + Stream inShadow = this.input; + if (inShadow != null) + { + try + { + if (!this._leaveOpen) + inShadow.Close(); + } + finally + { + this.data = null; + this.input = null; + } + } + } + + + /// + /// Read n bits from input, right justifying the result. + /// + /// + /// + /// For example, if you read 1 bit, the result is either 0 + /// or 1. + /// + /// + /// + /// The number of bits to read, always between 1 and 32. + /// + private int GetBits(int n) + { + int bsLiveShadow = this.bsLive; + int bsBuffShadow = this.bsBuff; + + if (bsLiveShadow < n) + { + do + { + int thech = this.input.ReadByte(); + + if (thech < 0) + throw new IOException("unexpected end of stream"); + + // Console.WriteLine("R {0:X2}", thech); + + bsBuffShadow = (bsBuffShadow << 8) | thech; + bsLiveShadow += 8; + } while (bsLiveShadow < n); + + this.bsBuff = bsBuffShadow; + } + + this.bsLive = bsLiveShadow - n; + return (bsBuffShadow >> (bsLiveShadow - n)) & ((1 << n) - 1); + } + + + // private bool bsGetBit() + // { + // int bsLiveShadow = this.bsLive; + // int bsBuffShadow = this.bsBuff; + // + // if (bsLiveShadow < 1) + // { + // int thech = this.input.ReadByte(); + // + // if (thech < 0) + // { + // throw new IOException("unexpected end of stream"); + // } + // + // bsBuffShadow = (bsBuffShadow << 8) | thech; + // bsLiveShadow += 8; + // this.bsBuff = bsBuffShadow; + // } + // + // this.bsLive = bsLiveShadow - 1; + // return ((bsBuffShadow >> (bsLiveShadow - 1)) & 1) != 0; + // } + + private bool bsGetBit() + { + int bit = GetBits(1); + return bit != 0; + } + + private char bsGetUByte() + { + return (char) GetBits(8); + } + + private uint bsGetInt() + { + return (uint)((((((GetBits(8) << 8) | GetBits(8)) << 8) | GetBits(8)) << 8) | GetBits(8)); + } + + + /** + * Called by createHuffmanDecodingTables() exclusively. + */ + private static void hbCreateDecodeTables(int[] limit, + int[] bbase, int[] perm, char[] length, + int minLen, int maxLen, int alphaSize) + { + for (int i = minLen, pp = 0; i <= maxLen; i++) + { + for (int j = 0; j < alphaSize; j++) + { + if (length[j] == i) + { + perm[pp++] = j; + } + } + } + + for (int i = BZip2.MaxCodeLength; --i > 0;) + { + bbase[i] = 0; + limit[i] = 0; + } + + for (int i = 0; i < alphaSize; i++) + { + bbase[length[i] + 1]++; + } + + for (int i = 1, b = bbase[0]; i < BZip2.MaxCodeLength; i++) + { + b += bbase[i]; + bbase[i] = b; + } + + for (int i = minLen, vec = 0, b = bbase[i]; i <= maxLen; i++) + { + int nb = bbase[i + 1]; + vec += nb - b; + b = nb; + limit[i] = vec - 1; + vec <<= 1; + } + + for (int i = minLen + 1; i <= maxLen; i++) + { + bbase[i] = ((limit[i - 1] + 1) << 1) - bbase[i]; + } + } + + + + private void recvDecodingTables() + { + var s = this.data; + bool[] inUse = s.inUse; + byte[] pos = s.recvDecodingTables_pos; + //byte[] selector = s.selector; + + int inUse16 = 0; + + /* Receive the mapping table */ + for (int i = 0; i < 16; i++) + { + if (bsGetBit()) + { + inUse16 |= 1 << i; + } + } + + for (int i = 256; --i >= 0;) + { + inUse[i] = false; + } + + for (int i = 0; i < 16; i++) + { + if ((inUse16 & (1 << i)) != 0) + { + int i16 = i << 4; + for (int j = 0; j < 16; j++) + { + if (bsGetBit()) + { + inUse[i16 + j] = true; + } + } + } + } + + MakeMaps(); + int alphaSize = this.nInUse + 2; + + /* Now the selectors */ + int nGroups = GetBits(3); + int nSelectors = GetBits(15); + + for (int i = 0; i < nSelectors; i++) + { + int j = 0; + while (bsGetBit()) + { + j++; + } + s.selectorMtf[i] = (byte) j; + } + + /* Undo the MTF values for the selectors. */ + for (int v = nGroups; --v >= 0;) + { + pos[v] = (byte) v; + } + + for (int i = 0; i < nSelectors; i++) + { + int v = s.selectorMtf[i]; + byte tmp = pos[v]; + while (v > 0) + { + // nearly all times v is zero, 4 in most other cases + pos[v] = pos[v - 1]; + v--; + } + pos[0] = tmp; + s.selector[i] = tmp; + } + + char[][] len = s.temp_charArray2d; + + /* Now the coding tables */ + for (int t = 0; t < nGroups; t++) + { + int curr = GetBits(5); + char[] len_t = len[t]; + for (int i = 0; i < alphaSize; i++) + { + while (bsGetBit()) + { + curr += bsGetBit() ? -1 : 1; + } + len_t[i] = (char) curr; + } + } + + // finally create the Huffman tables + createHuffmanDecodingTables(alphaSize, nGroups); + } + + + /** + * Called by recvDecodingTables() exclusively. + */ + private void createHuffmanDecodingTables(int alphaSize, + int nGroups) + { + var s = this.data; + char[][] len = s.temp_charArray2d; + + for (int t = 0; t < nGroups; t++) + { + int minLen = 32; + int maxLen = 0; + char[] len_t = len[t]; + for (int i = alphaSize; --i >= 0;) + { + char lent = len_t[i]; + if (lent > maxLen) + maxLen = lent; + + if (lent < minLen) + minLen = lent; + } + hbCreateDecodeTables(s.gLimit[t], s.gBase[t], s.gPerm[t], len[t], minLen, + maxLen, alphaSize); + s.gMinlen[t] = minLen; + } + } + + + + private void getAndMoveToFrontDecode() + { + var s = this.data; + this.origPtr = GetBits(24); + + if (this.origPtr < 0) + throw new IOException("BZ_DATA_ERROR"); + if (this.origPtr > 10 + BZip2.BlockSizeMultiple * this.blockSize100k) + throw new IOException("BZ_DATA_ERROR"); + + recvDecodingTables(); + + byte[] yy = s.getAndMoveToFrontDecode_yy; + int limitLast = this.blockSize100k * BZip2.BlockSizeMultiple; + + /* + * Setting up the unzftab entries here is not strictly necessary, but it + * does save having to do it later in a separate pass, and so saves a + * block's worth of cache misses. + */ + for (int i = 256; --i >= 0;) + { + yy[i] = (byte) i; + s.unzftab[i] = 0; + } + + int groupNo = 0; + int groupPos = BZip2.G_SIZE - 1; + int eob = this.nInUse + 1; + int nextSym = getAndMoveToFrontDecode0(0); + int bsBuffShadow = this.bsBuff; + int bsLiveShadow = this.bsLive; + int lastShadow = -1; + int zt = s.selector[groupNo] & 0xff; + int[] base_zt = s.gBase[zt]; + int[] limit_zt = s.gLimit[zt]; + int[] perm_zt = s.gPerm[zt]; + int minLens_zt = s.gMinlen[zt]; + + while (nextSym != eob) + { + if ((nextSym == BZip2.RUNA) || (nextSym == BZip2.RUNB)) + { + int es = -1; + + for (int n = 1; true; n <<= 1) + { + if (nextSym == BZip2.RUNA) + { + es += n; + } + else if (nextSym == BZip2.RUNB) + { + es += n << 1; + } + else + { + break; + } + + if (groupPos == 0) + { + groupPos = BZip2.G_SIZE - 1; + zt = s.selector[++groupNo] & 0xff; + base_zt = s.gBase[zt]; + limit_zt = s.gLimit[zt]; + perm_zt = s.gPerm[zt]; + minLens_zt = s.gMinlen[zt]; + } + else + { + groupPos--; + } + + int zn = minLens_zt; + + // Inlined: + // int zvec = GetBits(zn); + while (bsLiveShadow < zn) + { + int thech = this.input.ReadByte(); + if (thech >= 0) + { + bsBuffShadow = (bsBuffShadow << 8) | thech; + bsLiveShadow += 8; + continue; + } + else + { + throw new IOException("unexpected end of stream"); + } + } + int zvec = (bsBuffShadow >> (bsLiveShadow - zn)) + & ((1 << zn) - 1); + bsLiveShadow -= zn; + + while (zvec > limit_zt[zn]) + { + zn++; + while (bsLiveShadow < 1) + { + int thech = this.input.ReadByte(); + if (thech >= 0) + { + bsBuffShadow = (bsBuffShadow << 8) | thech; + bsLiveShadow += 8; + continue; + } + else + { + throw new IOException("unexpected end of stream"); + } + } + bsLiveShadow--; + zvec = (zvec << 1) + | ((bsBuffShadow >> bsLiveShadow) & 1); + } + nextSym = perm_zt[zvec - base_zt[zn]]; + } + + byte ch = s.seqToUnseq[yy[0]]; + s.unzftab[ch & 0xff] += es + 1; + + while (es-- >= 0) + { + s.ll8[++lastShadow] = ch; + } + + if (lastShadow >= limitLast) + throw new IOException("block overrun"); + } + else + { + if (++lastShadow >= limitLast) + throw new IOException("block overrun"); + + byte tmp = yy[nextSym - 1]; + s.unzftab[s.seqToUnseq[tmp] & 0xff]++; + s.ll8[lastShadow] = s.seqToUnseq[tmp]; + + /* + * This loop is hammered during decompression, hence avoid + * native method call overhead of System.Buffer.BlockCopy for very + * small ranges to copy. + */ + if (nextSym <= 16) + { + for (int j = nextSym - 1; j > 0;) + { + yy[j] = yy[--j]; + } + } + else + { + System.Buffer.BlockCopy(yy, 0, yy, 1, nextSym - 1); + } + + yy[0] = tmp; + + if (groupPos == 0) + { + groupPos = BZip2.G_SIZE - 1; + zt = s.selector[++groupNo] & 0xff; + base_zt = s.gBase[zt]; + limit_zt = s.gLimit[zt]; + perm_zt = s.gPerm[zt]; + minLens_zt = s.gMinlen[zt]; + } + else + { + groupPos--; + } + + int zn = minLens_zt; + + // Inlined: + // int zvec = GetBits(zn); + while (bsLiveShadow < zn) + { + int thech = this.input.ReadByte(); + if (thech >= 0) + { + bsBuffShadow = (bsBuffShadow << 8) | thech; + bsLiveShadow += 8; + continue; + } + else + { + throw new IOException("unexpected end of stream"); + } + } + int zvec = (bsBuffShadow >> (bsLiveShadow - zn)) + & ((1 << zn) - 1); + bsLiveShadow -= zn; + + while (zvec > limit_zt[zn]) + { + zn++; + while (bsLiveShadow < 1) + { + int thech = this.input.ReadByte(); + if (thech >= 0) + { + bsBuffShadow = (bsBuffShadow << 8) | thech; + bsLiveShadow += 8; + continue; + } + else + { + throw new IOException("unexpected end of stream"); + } + } + bsLiveShadow--; + zvec = (zvec << 1) | ((bsBuffShadow >> bsLiveShadow) & 1); + } + nextSym = perm_zt[zvec - base_zt[zn]]; + } + } + + this.last = lastShadow; + this.bsLive = bsLiveShadow; + this.bsBuff = bsBuffShadow; + } + + + private int getAndMoveToFrontDecode0(int groupNo) + { + var s = this.data; + int zt = s.selector[groupNo] & 0xff; + int[] limit_zt = s.gLimit[zt]; + int zn = s.gMinlen[zt]; + int zvec = GetBits(zn); + int bsLiveShadow = this.bsLive; + int bsBuffShadow = this.bsBuff; + + while (zvec > limit_zt[zn]) + { + zn++; + while (bsLiveShadow < 1) + { + int thech = this.input.ReadByte(); + + if (thech >= 0) + { + bsBuffShadow = (bsBuffShadow << 8) | thech; + bsLiveShadow += 8; + continue; + } + else + { + throw new IOException("unexpected end of stream"); + } + } + bsLiveShadow--; + zvec = (zvec << 1) | ((bsBuffShadow >> bsLiveShadow) & 1); + } + + this.bsLive = bsLiveShadow; + this.bsBuff = bsBuffShadow; + + return s.gPerm[zt][zvec - s.gBase[zt][zn]]; + } + + + private void SetupBlock() + { + if (this.data == null) + return; + + int i; + var s = this.data; + int[] tt = s.initTT(this.last + 1); + + // xxxx + + /* Check: unzftab entries in range. */ + for (i = 0; i <= 255; i++) + { + if (s.unzftab[i] < 0 || s.unzftab[i] > this.last) + throw new Exception("BZ_DATA_ERROR"); + } + + /* Actually generate cftab. */ + s.cftab[0] = 0; + for (i = 1; i <= 256; i++) s.cftab[i] = s.unzftab[i-1]; + for (i = 1; i <= 256; i++) s.cftab[i] += s.cftab[i-1]; + /* Check: cftab entries in range. */ + for (i = 0; i <= 256; i++) + { + if (s.cftab[i] < 0 || s.cftab[i] > this.last+1) + { + var msg = String.Format("BZ_DATA_ERROR: cftab[{0}]={1} last={2}", + i, s.cftab[i], this.last); + throw new Exception(msg); + } + } + /* Check: cftab entries non-descending. */ + for (i = 1; i <= 256; i++) + { + if (s.cftab[i-1] > s.cftab[i]) + throw new Exception("BZ_DATA_ERROR"); + } + + int lastShadow; + for (i = 0, lastShadow = this.last; i <= lastShadow; i++) + { + tt[s.cftab[s.ll8[i] & 0xff]++] = i; + } + + if ((this.origPtr < 0) || (this.origPtr >= tt.Length)) + throw new IOException("stream corrupted"); + + this.su_tPos = tt[this.origPtr]; + this.su_count = 0; + this.su_i2 = 0; + this.su_ch2 = 256; /* not a valid 8-bit byte value?, and not EOF */ + + if (this.blockRandomised) + { + this.su_rNToGo = 0; + this.su_rTPos = 0; + SetupRandPartA(); + } + else + { + SetupNoRandPartA(); + } + } + + + + private void SetupRandPartA() + { + if (this.su_i2 <= this.last) + { + this.su_chPrev = this.su_ch2; + int su_ch2Shadow = this.data.ll8[this.su_tPos] & 0xff; + this.su_tPos = this.data.tt[this.su_tPos]; + if (this.su_rNToGo == 0) + { + this.su_rNToGo = Rand.Rnums(this.su_rTPos) - 1; + if (++this.su_rTPos == 512) + { + this.su_rTPos = 0; + } + } + else + { + this.su_rNToGo--; + } + this.su_ch2 = su_ch2Shadow ^= (this.su_rNToGo == 1) ? 1 : 0; + this.su_i2++; + this.currentChar = su_ch2Shadow; + this.currentState = CState.RAND_PART_B; + this.crc.UpdateCRC((byte)su_ch2Shadow); + } + else + { + EndBlock(); + InitBlock(); + SetupBlock(); + } + } + + private void SetupNoRandPartA() + { + if (this.su_i2 <= this.last) + { + this.su_chPrev = this.su_ch2; + int su_ch2Shadow = this.data.ll8[this.su_tPos] & 0xff; + this.su_ch2 = su_ch2Shadow; + this.su_tPos = this.data.tt[this.su_tPos]; + this.su_i2++; + this.currentChar = su_ch2Shadow; + this.currentState = CState.NO_RAND_PART_B; + this.crc.UpdateCRC((byte)su_ch2Shadow); + } + else + { + this.currentState = CState.NO_RAND_PART_A; + EndBlock(); + InitBlock(); + SetupBlock(); + } + } + + private void SetupRandPartB() + { + if (this.su_ch2 != this.su_chPrev) + { + this.currentState = CState.RAND_PART_A; + this.su_count = 1; + SetupRandPartA(); + } + else if (++this.su_count >= 4) + { + this.su_z = (char) (this.data.ll8[this.su_tPos] & 0xff); + this.su_tPos = this.data.tt[this.su_tPos]; + if (this.su_rNToGo == 0) + { + this.su_rNToGo = Rand.Rnums(this.su_rTPos) - 1; + if (++this.su_rTPos == 512) + { + this.su_rTPos = 0; + } + } + else + { + this.su_rNToGo--; + } + this.su_j2 = 0; + this.currentState = CState.RAND_PART_C; + if (this.su_rNToGo == 1) + { + this.su_z ^= (char)1; + } + SetupRandPartC(); + } + else + { + this.currentState = CState.RAND_PART_A; + SetupRandPartA(); + } + } + + private void SetupRandPartC() + { + if (this.su_j2 < this.su_z) + { + this.currentChar = this.su_ch2; + this.crc.UpdateCRC((byte)this.su_ch2); + this.su_j2++; + } + else + { + this.currentState = CState.RAND_PART_A; + this.su_i2++; + this.su_count = 0; + SetupRandPartA(); + } + } + + private void SetupNoRandPartB() + { + if (this.su_ch2 != this.su_chPrev) + { + this.su_count = 1; + SetupNoRandPartA(); + } + else if (++this.su_count >= 4) + { + this.su_z = (char) (this.data.ll8[this.su_tPos] & 0xff); + this.su_tPos = this.data.tt[this.su_tPos]; + this.su_j2 = 0; + SetupNoRandPartC(); + } + else + { + SetupNoRandPartA(); + } + } + + private void SetupNoRandPartC() + { + if (this.su_j2 < this.su_z) + { + int su_ch2Shadow = this.su_ch2; + this.currentChar = su_ch2Shadow; + this.crc.UpdateCRC((byte)su_ch2Shadow); + this.su_j2++; + this.currentState = CState.NO_RAND_PART_C; + } + else + { + this.su_i2++; + this.su_count = 0; + SetupNoRandPartA(); + } + } + + private sealed class DecompressionState + { + // (with blockSize 900k) + readonly public bool[] inUse = new bool[256]; + readonly public byte[] seqToUnseq = new byte[256]; // 256 byte + readonly public byte[] selector = new byte[BZip2.MaxSelectors]; // 18002 byte + readonly public byte[] selectorMtf = new byte[BZip2.MaxSelectors]; // 18002 byte + + /** + * Freq table collected to save a pass over the data during + * decompression. + */ + public readonly int[] unzftab; + public readonly int[][] gLimit; + public readonly int[][] gBase; + public readonly int[][] gPerm; + public readonly int[] gMinlen; + + public readonly int[] cftab; + public readonly byte[] getAndMoveToFrontDecode_yy; + public readonly char[][] temp_charArray2d; + public readonly byte[] recvDecodingTables_pos; + // --------------- + // 60798 byte + + public int[] tt; // 3600000 byte + public byte[] ll8; // 900000 byte + + // --------------- + // 4560782 byte + // =============== + + public DecompressionState(int blockSize100k) + { + this.unzftab = new int[256]; // 1024 byte + + this.gLimit = BZip2.InitRectangularArray(BZip2.NGroups,BZip2.MaxAlphaSize); + this.gBase = BZip2.InitRectangularArray(BZip2.NGroups,BZip2.MaxAlphaSize); + this.gPerm = BZip2.InitRectangularArray(BZip2.NGroups,BZip2.MaxAlphaSize); + this.gMinlen = new int[BZip2.NGroups]; // 24 byte + + this.cftab = new int[257]; // 1028 byte + this.getAndMoveToFrontDecode_yy = new byte[256]; // 512 byte + this.temp_charArray2d = BZip2.InitRectangularArray(BZip2.NGroups,BZip2.MaxAlphaSize); + this.recvDecodingTables_pos = new byte[BZip2.NGroups]; // 6 byte + + this.ll8 = new byte[blockSize100k * BZip2.BlockSizeMultiple]; + } + + /** + * Initializes the tt array. + * + * This method is called when the required length of the array is known. + * I don't initialize it at construction time to avoid unneccessary + * memory allocation when compressing small files. + */ + public int[] initTT(int length) + { + int[] ttShadow = this.tt; + + // tt.length should always be >= length, but theoretically + // it can happen, if the compressor mixed small and large + // blocks. Normally only the last block will be smaller + // than others. + if ((ttShadow == null) || (ttShadow.Length < length)) + { + this.tt = ttShadow = new int[length]; + } + + return ttShadow; + } + } + + + } + + // /** + // * Checks if the signature matches what is expected for a bzip2 file. + // * + // * @param signature + // * the bytes to check + // * @param length + // * the number of bytes to check + // * @return true, if this stream is a bzip2 compressed stream, false otherwise + // * + // * @since Apache Commons Compress 1.1 + // */ + // public static boolean MatchesSig(byte[] signature) + // { + // if ((signature.Length < 3) || + // (signature[0] != 'B') || + // (signature[1] != 'Z') || + // (signature[2] != 'h')) + // return false; + // + // return true; + // } + + + internal static class BZip2 + { + internal static T[][] InitRectangularArray(int d1, int d2) + { + var x = new T[d1][]; + for (int i=0; i < d1; i++) + { + x[i] = new T[d2]; + } + return x; + } + + public static readonly int BlockSizeMultiple = 100000; + public static readonly int MinBlockSize = 1; + public static readonly int MaxBlockSize = 9; + public static readonly int MaxAlphaSize = 258; + public static readonly int MaxCodeLength = 23; + public static readonly char RUNA = (char) 0; + public static readonly char RUNB = (char) 1; + public static readonly int NGroups = 6; + public static readonly int G_SIZE = 50; + public static readonly int N_ITERS = 4; + public static readonly int MaxSelectors = (2 + (900000 / G_SIZE)); + public static readonly int NUM_OVERSHOOT_BYTES = 20; + /* + *

If you are ever unlucky/improbable enough to get a stack + * overflow whilst sorting, increase the following constant and + * try again. In practice I have never seen the stack go above 27 + * elems, so the following limit seems very generous.

+ */ + internal static readonly int QSORT_STACK_SIZE = 1000; + + + } + +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/BZip2/BZip2OutputStream.cs b/Resources/Libraries/DotNetZip/Source/BZip2/BZip2OutputStream.cs new file mode 100644 index 00000000..74dce3ca --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/BZip2/BZip2OutputStream.cs @@ -0,0 +1,530 @@ +//#define Trace + +// BZip2OutputStream.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// Last Saved: <2011-August-02 16:44:11> +// +// ------------------------------------------------------------------ +// +// This module defines the BZip2OutputStream class, which is a +// compressing stream that handles BZIP2. This code may have been +// derived in part from Apache commons source code. The license below +// applies to the original Apache code. +// +// ------------------------------------------------------------------ +// flymake: csc.exe /t:module BZip2InputStream.cs BZip2Compressor.cs Rand.cs BCRC32.cs @@FILE@@ + +/* + * 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. + */ + + +// Design Notes: +// +// This class follows the classic Decorator pattern: it is a Stream that +// wraps itself around a Stream, and in doing so provides bzip2 +// compression as callers Write into it. +// +// BZip2 is a straightforward data format: there are 4 magic bytes at +// the top of the file, followed by 1 or more compressed blocks. There +// is a small "magic byte" trailer after all compressed blocks. This +// class emits the magic bytes for the header and trailer, and relies on +// a BZip2Compressor to generate each of the compressed data blocks. +// +// BZip2 does byte-shredding - it uses partial fractions of bytes to +// represent independent pieces of information. This class relies on the +// BitWriter to adapt the bit-oriented BZip2 output to the byte-oriented +// model of the .NET Stream class. +// +// ---- +// +// Regarding the Apache code base: Most of the code in this particular +// class is related to stream operations, and is my own code. It largely +// does not rely on any code obtained from Apache commons. If you +// compare this code with the Apache commons BZip2OutputStream, you will +// see very little code that is common, except for the +// nearly-boilerplate structure that is common to all subtypes of +// System.IO.Stream. There may be some small remnants of code in this +// module derived from the Apache stuff, which is why I left the license +// in here. Most of the Apache commons compressor magic has been ported +// into the BZip2Compressor class. +// + +using System; +using System.IO; + + +namespace Ionic.BZip2 +{ + /// + /// A write-only decorator stream that compresses data as it is + /// written using the BZip2 algorithm. + /// + public class BZip2OutputStream : System.IO.Stream + { + int totalBytesWrittenIn; + bool leaveOpen; + BZip2Compressor compressor; + uint combinedCRC; + Stream output; + BitWriter bw; + int blockSize100k; // 0...9 + + private TraceBits desiredTrace = TraceBits.Crc | TraceBits.Write; + + /// + /// Constructs a new BZip2OutputStream, that sends its + /// compressed output to the given output stream. + /// + /// + /// + /// The destination stream, to which compressed output will be sent. + /// + /// + /// + /// + /// This example reads a file, then compresses it with bzip2 file, + /// and writes the compressed data into a newly created file. + /// + /// + /// var fname = "logfile.log"; + /// using (var fs = File.OpenRead(fname)) + /// { + /// var outFname = fname + ".bz2"; + /// using (var output = File.Create(outFname)) + /// { + /// using (var compressor = new Ionic.BZip2.BZip2OutputStream(output)) + /// { + /// byte[] buffer = new byte[2048]; + /// int n; + /// while ((n = fs.Read(buffer, 0, buffer.Length)) > 0) + /// { + /// compressor.Write(buffer, 0, n); + /// } + /// } + /// } + /// } + /// + /// + public BZip2OutputStream(Stream output) + : this(output, BZip2.MaxBlockSize, false) + { + } + + + /// + /// Constructs a new BZip2OutputStream with specified blocksize. + /// + /// the destination stream. + /// + /// The blockSize in units of 100000 bytes. + /// The valid range is 1..9. + /// + public BZip2OutputStream(Stream output, int blockSize) + : this(output, blockSize, false) + { + } + + + /// + /// Constructs a new BZip2OutputStream. + /// + /// the destination stream. + /// + /// whether to leave the captive stream open upon closing this stream. + /// + public BZip2OutputStream(Stream output, bool leaveOpen) + : this(output, BZip2.MaxBlockSize, leaveOpen) + { + } + + + /// + /// Constructs a new BZip2OutputStream with specified blocksize, + /// and explicitly specifies whether to leave the wrapped stream open. + /// + /// + /// the destination stream. + /// + /// The blockSize in units of 100000 bytes. + /// The valid range is 1..9. + /// + /// + /// whether to leave the captive stream open upon closing this stream. + /// + public BZip2OutputStream(Stream output, int blockSize, bool leaveOpen) + { + if (blockSize < BZip2.MinBlockSize || + blockSize > BZip2.MaxBlockSize) + { + var msg = String.Format("blockSize={0} is out of range; must be between {1} and {2}", + blockSize, + BZip2.MinBlockSize, BZip2.MaxBlockSize); + throw new ArgumentException(msg, "blockSize"); + } + + this.output = output; + if (!this.output.CanWrite) + throw new ArgumentException("The stream is not writable.", "output"); + + this.bw = new BitWriter(this.output); + this.blockSize100k = blockSize; + this.compressor = new BZip2Compressor(this.bw, blockSize); + this.leaveOpen = leaveOpen; + this.combinedCRC = 0; + EmitHeader(); + } + + + + + /// + /// Close the stream. + /// + /// + /// + /// This may or may not close the underlying stream. Check the + /// constructors that accept a bool value. + /// + /// + public override void Close() + { + if (output != null) + { + Stream o = this.output; + Finish(); + if (!leaveOpen) + o.Close(); + } + } + + + /// + /// Flush the stream. + /// + public override void Flush() + { + if (this.output != null) + { + this.bw.Flush(); + this.output.Flush(); + } + } + + private void EmitHeader() + { + var magic = new byte[] { + (byte) 'B', + (byte) 'Z', + (byte) 'h', + (byte) ('0' + this.blockSize100k) + }; + + // not necessary to shred the initial magic bytes + this.output.Write(magic, 0, magic.Length); + } + + private void EmitTrailer() + { + // A magic 48-bit number, 0x177245385090, to indicate the end + // of the last block. (sqrt(pi), if you want to know) + + TraceOutput(TraceBits.Write, "total written out: {0} (0x{0:X})", + this.bw.TotalBytesWrittenOut); + + // must shred + this.bw.WriteByte(0x17); + this.bw.WriteByte(0x72); + this.bw.WriteByte(0x45); + this.bw.WriteByte(0x38); + this.bw.WriteByte(0x50); + this.bw.WriteByte(0x90); + + this.bw.WriteInt(this.combinedCRC); + + this.bw.FinishAndPad(); + + TraceOutput(TraceBits.Write, "final total: {0} (0x{0:X})", + this.bw.TotalBytesWrittenOut); + } + + void Finish() + { + // Console.WriteLine("BZip2:Finish"); + + try + { + var totalBefore = this.bw.TotalBytesWrittenOut; + this.compressor.CompressAndWrite(); + TraceOutput(TraceBits.Write,"out block length (bytes): {0} (0x{0:X})", + this.bw.TotalBytesWrittenOut - totalBefore); + + TraceOutput(TraceBits.Crc, " combined CRC (before): {0:X8}", + this.combinedCRC); + this.combinedCRC = (this.combinedCRC << 1) | (this.combinedCRC >> 31); + this.combinedCRC ^= (uint) compressor.Crc32; + TraceOutput(TraceBits.Crc, " block CRC : {0:X8}", + this.compressor.Crc32); + TraceOutput(TraceBits.Crc, " combined CRC (final) : {0:X8}", + this.combinedCRC); + + EmitTrailer(); + } + finally + { + this.output = null; + this.compressor = null; + this.bw = null; + } + } + + + /// + /// The blocksize parameter specified at construction time. + /// + public int BlockSize + { + get { return this.blockSize100k; } + } + + + /// + /// Write data to the stream. + /// + /// + /// + /// + /// Use the BZip2OutputStream to compress data while writing: + /// create a BZip2OutputStream with a writable output stream. + /// Then call Write() on that BZip2OutputStream, providing + /// uncompressed data as input. The data sent to the output stream will + /// be the compressed form of the input data. + /// + /// + /// + /// A BZip2OutputStream can be used only for Write() not for Read(). + /// + /// + /// + /// + /// The buffer holding data to write to the stream. + /// the offset within that data array to find the first byte to write. + /// the number of bytes to write. + public override void Write(byte[] buffer, int offset, int count) + { + if (offset < 0) + throw new IndexOutOfRangeException(String.Format("offset ({0}) must be > 0", offset)); + if (count < 0) + throw new IndexOutOfRangeException(String.Format("count ({0}) must be > 0", count)); + if (offset + count > buffer.Length) + throw new IndexOutOfRangeException(String.Format("offset({0}) count({1}) bLength({2})", + offset, count, buffer.Length)); + if (this.output == null) + throw new IOException("the stream is not open"); + + if (count == 0) return; // nothing to do + + int bytesWritten = 0; + int bytesRemaining = count; + + do + { + int n = compressor.Fill(buffer, offset, bytesRemaining); + if (n != bytesRemaining) + { + // The compressor data block is full. Compress and + // write out the compressed data, then reset the + // compressor and continue. + + var totalBefore = this.bw.TotalBytesWrittenOut; + this.compressor.CompressAndWrite(); + TraceOutput(TraceBits.Write,"out block length (bytes): {0} (0x{0:X})", + this.bw.TotalBytesWrittenOut - totalBefore); + + // and now any remaining bits + TraceOutput(TraceBits.Write, + " remaining: {0} 0x{1:X}", + this.bw.NumRemainingBits, + this.bw.RemainingBits); + + TraceOutput(TraceBits.Crc, " combined CRC (before): {0:X8}", + this.combinedCRC); + this.combinedCRC = (this.combinedCRC << 1) | (this.combinedCRC >> 31); + this.combinedCRC ^= (uint) compressor.Crc32; + TraceOutput(TraceBits.Crc, " block CRC : {0:X8}", + compressor.Crc32); + TraceOutput(TraceBits.Crc, " combined CRC (after) : {0:X8}", + this.combinedCRC); + offset += n; + } + bytesRemaining -= n; + bytesWritten += n; + } while (bytesRemaining > 0); + + totalBytesWrittenIn += bytesWritten; + } + + + + + /// + /// Indicates whether the stream can be read. + /// + /// + /// The return value is always false. + /// + public override bool CanRead + { + get { return false; } + } + + /// + /// Indicates whether the stream supports Seek operations. + /// + /// + /// Always returns false. + /// + public override bool CanSeek + { + get { return false; } + } + + /// + /// Indicates whether the stream can be written. + /// + /// + /// The return value should always be true, unless and until the + /// object is disposed and closed. + /// + public override bool CanWrite + { + get + { + if (this.output == null) throw new ObjectDisposedException("BZip2Stream"); + return this.output.CanWrite; + } + } + + /// + /// Reading this property always throws a . + /// + public override long Length + { + get { throw new NotImplementedException(); } + } + + /// + /// The position of the stream pointer. + /// + /// + /// + /// Setting this property always throws a . Reading will return the + /// total number of uncompressed bytes written through. + /// + public override long Position + { + get + { + return this.totalBytesWrittenIn; + } + set { throw new NotImplementedException(); } + } + + /// + /// Calling this method always throws a . + /// + /// this is irrelevant, since it will always throw! + /// this is irrelevant, since it will always throw! + /// irrelevant! + public override long Seek(long offset, System.IO.SeekOrigin origin) + { + throw new NotImplementedException(); + } + + /// + /// Calling this method always throws a . + /// + /// this is irrelevant, since it will always throw! + public override void SetLength(long value) + { + throw new NotImplementedException(); + } + + /// + /// Calling this method always throws a . + /// + /// this parameter is never used + /// this parameter is never used + /// this parameter is never used + /// never returns anything; always throws + public override int Read(byte[] buffer, int offset, int count) + { + throw new NotImplementedException(); + } + + + // used only when Trace is defined + [Flags] + enum TraceBits : uint + { + None = 0, + Crc = 1, + Write = 2, + All = 0xffffffff, + } + + + [System.Diagnostics.ConditionalAttribute("Trace")] + private void TraceOutput(TraceBits bits, string format, params object[] varParams) + { + if ((bits & this.desiredTrace) != 0) + { + //lock(outputLock) + { + int tid = System.Threading.Thread.CurrentThread.GetHashCode(); +#if !SILVERLIGHT && !NETCF + Console.ForegroundColor = (ConsoleColor) (tid % 8 + 10); +#endif + Console.Write("{0:000} PBOS ", tid); + Console.WriteLine(format, varParams); +#if !SILVERLIGHT && !NETCF + Console.ResetColor(); +#endif + } + } + } + + + } + +} diff --git a/Resources/Libraries/DotNetZip/Source/BZip2/BitWriter.cs b/Resources/Libraries/DotNetZip/Source/BZip2/BitWriter.cs new file mode 100644 index 00000000..55cc36c3 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/BZip2/BitWriter.cs @@ -0,0 +1,248 @@ +// BitWriter.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// Last Saved: <2011-July-25 18:57:31> +// +// ------------------------------------------------------------------ +// +// This module defines the BitWriter class, which writes bits at a time +// to an output stream. It's used by the BZip2Compressor class, and by +// the BZip2OutputStream class and its parallel variant, +// ParallelBZip2OutputStream. +// +// ------------------------------------------------------------------ + +// +// Design notes: +// +// BZip2 employs byte-shredding in its data format - rather than +// aligning all data items in a compressed .bz2 file on byte barriers, +// the BZip2 format uses portions of bytes to represent independent +// pieces of information. This "shredding" starts with the first +// "randomised" bit - just 12 bytes or so into a bz2 file or stream. But +// the approach is used extensively in bzip2 files - sometimes 5 bits +// are used, sometimes 24 or 3 bits, sometimes just 1 bit, and so on. +// It's not possible to send this information directly to a stream in +// this form; Streams in .NET accept byte-oriented input. Therefore, +// when actually writing a bz2 file, the output data must be organized +// into a byte-aligned format before being written to the output stream. +// +// This BitWriter class provides the byte-shredding necessary for BZip2 +// output. Think of this class as an Adapter that enables Bit-oriented +// output to a standard byte-oriented .NET stream. This class writes +// data out to the captive output stream only after the data bits have +// been accumulated and aligned. For example, suppose that during +// operation, the BZip2 compressor emits 5 bits, then 24 bits, then 32 +// bits. When the first 5 bits are sent to the BitWriter, nothing is +// written to the output stream; instead these 5 bits are simply stored +// in the internal accumulator. When the next 24 bits are written, the +// first 3 bits are gathered with the accumulated bits. The resulting +// 5+3 constitutes an entire byte; the BitWriter then actually writes +// that byte to the output stream. This leaves 21 bits. BitWriter writes +// 2 more whole bytes (16 more bits), in 8-bit chunks, leaving 5 in the +// accumulator. BitWriter then follows the same procedure with the 32 +// new bits. And so on. +// +// A quick tour of the implementation: +// +// The accumulator is a uint - so it can accumulate at most 4 bytes of +// information. In practice because of the design of this class, it +// never accumulates more than 3 bytes. +// +// The Flush() method emits all whole bytes available. After calling +// Flush(), there may be between 0-7 bits yet to be emitted into the +// output stream. +// +// FinishAndPad() emits all data, including the last partial byte and +// any necessary padding. In effect, it establishes a byte-alignment +// barrier. To support bzip2, FinishAndPad() should be called only once +// for a bz2 file, after the last bit of data has been written through +// this adapter. Other binary file formats may use byte-alignment at +// various points within the file, and FinishAndPad() would support that +// scenario. +// +// The internal fn Reset() is used to reset the state of the adapter; +// this class is used by BZip2Compressor, instances of which get re-used +// by multiple distinct threads, for different blocks of data. +// + + +using System; +using System.IO; + +namespace Ionic.BZip2 +{ + + internal class BitWriter + { + uint accumulator; + int nAccumulatedBits; + Stream output; + int totalBytesWrittenOut; + + public BitWriter(Stream s) + { + this.output = s; + } + + /// + /// Delivers the remaining bits, left-aligned, in a byte. + /// + /// + /// + /// This is valid only if NumRemainingBits is less than 8; + /// in other words it is valid only after a call to Flush(). + /// + /// + public byte RemainingBits + { + get + { + return (byte) (this.accumulator >> (32 - this.nAccumulatedBits) & 0xff); + } + } + + public int NumRemainingBits + { + get + { + return this.nAccumulatedBits; + } + } + + public int TotalBytesWrittenOut + { + get + { + return this.totalBytesWrittenOut; + } + } + + /// + /// Reset the BitWriter. + /// + /// + /// + /// This is useful when the BitWriter writes into a MemoryStream, and + /// is used by a BZip2Compressor, which itself is re-used for multiple + /// distinct data blocks. + /// + /// + public void Reset() + { + this.accumulator = 0; + this.nAccumulatedBits = 0; + this.totalBytesWrittenOut = 0; + this.output.Seek(0, SeekOrigin.Begin); + this.output.SetLength(0); + } + + /// + /// Write some number of bits from the given value, into the output. + /// + /// + /// + /// The nbits value should be a max of 25, for safety. For performance + /// reasons, this method does not check! + /// + /// + public void WriteBits(int nbits, uint value) + { + int nAccumulated = this.nAccumulatedBits; + uint u = this.accumulator; + + while (nAccumulated >= 8) + { + this.output.WriteByte ((byte)(u >> 24 & 0xff)); + this.totalBytesWrittenOut++; + u <<= 8; + nAccumulated -= 8; + } + + this.accumulator = u | (value << (32 - nAccumulated - nbits)); + this.nAccumulatedBits = nAccumulated + nbits; + + // Console.WriteLine("WriteBits({0}, 0x{1:X2}) => {2:X8} n({3})", + // nbits, value, accumulator, nAccumulatedBits); + // Console.ReadLine(); + + // At this point the accumulator may contain up to 31 bits waiting for + // output. + } + + + /// + /// Write a full 8-bit byte into the output. + /// + public void WriteByte(byte b) + { + WriteBits(8, b); + } + + /// + /// Write four 8-bit bytes into the output. + /// + public void WriteInt(uint u) + { + WriteBits(8, (u >> 24) & 0xff); + WriteBits(8, (u >> 16) & 0xff); + WriteBits(8, (u >> 8) & 0xff); + WriteBits(8, u & 0xff); + } + + /// + /// Write all available byte-aligned bytes. + /// + /// + /// + /// This method writes no new output, but flushes any accumulated + /// bits. At completion, the accumulator may contain up to 7 + /// bits. + /// + /// + /// This is necessary when re-assembling output from N independent + /// compressors, one for each of N blocks. The output of any + /// particular compressor will in general have some fragment of a byte + /// remaining. This fragment needs to be accumulated into the + /// parent BZip2OutputStream. + /// + /// + public void Flush() + { + WriteBits(0,0); + } + + + /// + /// Writes all available bytes, and emits padding for the final byte as + /// necessary. This must be the last method invoked on an instance of + /// BitWriter. + /// + public void FinishAndPad() + { + Flush(); + + if (this.NumRemainingBits > 0) + { + byte b = (byte)((this.accumulator >> 24) & 0xff); + this.output.WriteByte(b); + this.totalBytesWrittenOut++; + } + } + + } + +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/BZip2/ParallelBZip2OutputStream.cs b/Resources/Libraries/DotNetZip/Source/BZip2/ParallelBZip2OutputStream.cs new file mode 100644 index 00000000..b6f241f6 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/BZip2/ParallelBZip2OutputStream.cs @@ -0,0 +1,999 @@ +//#define Trace + +// ParallelBZip2OutputStream.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// Last Saved: <2011-August-02 16:44:24> +// +// ------------------------------------------------------------------ +// +// This module defines the ParallelBZip2OutputStream class, which is a +// BZip2 compressing stream. This code was derived in part from Apache +// commons source code. The license below applies to the original Apache +// code. +// +// ------------------------------------------------------------------ +// flymake: csc.exe /t:module BZip2InputStream.cs BZip2Compressor.cs Rand.cs BCRC32.cs @@FILE@@ + + +/* + * 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. + */ + + +// Design Notes: +// +// This class follows the classic Decorator pattern: it is a Stream that +// wraps itself around a Stream, and in doing so provides bzip2 +// compression as callers Write into it. It is exactly the same in +// outward function as the BZip2OutputStream, except that this class can +// perform compression using multiple independent threads. Because of +// that, and because of the CPU-intensive nature of BZip2 compression, +// this class can perform significantly better (in terms of wall-click +// time) than the single-threaded variant, at the expense of memory and +// CPU utilization. +// +// BZip2 is a straightforward data format: there are 4 magic bytes at +// the top of the file, followed by 1 or more compressed blocks. There +// is a small "magic byte" trailer after all compressed blocks. +// +// In concept parallelizing BZip2 is simple: do the CPU-intensive +// compression for each block in a separate thread, then emit the +// compressed output, in order, to the output stream. Each block can be +// compressed independently, so a block is the natural candidate for the +// parcel of work that can be passed to an independent worker thread. +// +// The design approach used here is simple: within the Write() method of +// the stream, fill a block. When the block is full, pass it to a +// background worker thread for compression. When the compressor thread +// completes its work, the main thread (the application thread that +// calls Write()) can send the compressed data to the output stream, +// being careful to respect the order of the compressed blocks. +// +// The challenge of ordering the compressed data is a solved and +// well-understood problem - it is the same approach here as DotNetZip +// uses in the ParallelDeflateOutputStream. It is a map/reduce approach +// in design intent. +// +// One new twist for BZip2 is that the compressor output is not +// byte-aligned. In other words the final output of a compressed block +// will in general be a number of bits that is not a multiple of +// 8. Therefore, combining the ordered results of the N compressor +// threads requires additional byte-shredding by the parent +// stream. Hence this stream uses a BitWriter to adapt bit-oriented +// BZip2 output to the byte-oriented .NET Stream. +// +// The approach used here creates N instances of the BZip2Compressor +// type, where N is governed by the number of cores (cpus) and limited +// by the MaxWorkers property exposed by this class. Each +// BZip2Compressor instance gets its own MemoryStream, to which it +// writes its data, via a BitWriter. +// +// along with the bit accumulator described above. The MemoryStream +// would gather the byte-aligned compressed output of the compressor. + +// When reducing the output of the various workers, this class must +// again do the byte-shredding thing. The data from the compressors is +// therefore shredded twice: once when being placed into the +// MemoryStream, and again when emitted into the final output stream +// that this class decorates. This is an unfortunate and seemingly +// unavoidable inefficiency. Two rounds of byte-shredding will use more +// CPU than we'd like, but I haven't imagined a way to avoid it. +// +// The BZip2Compressor is designed to write directly into the parent +// stream's accumulator (BitWriter) when possible, and write into a +// distinct BitWriter when necessary. The former can be used in a +// single-thread scenario, while the latter is required in a +// multi-thread scenario. +// +// ---- +// +// Regarding the Apache code base: Most of the code in this particular +// class is related to stream operations and thread synchronization, and +// is my own code. It largely does not rely on any code obtained from +// Apache commons. If you compare this code with the Apache commons +// BZip2OutputStream, you will see very little code that is common, +// except for the nearly-boilerplate structure that is common to all +// subtypes of System.IO.Stream. There may be some small remnants of +// code in this module derived from the Apache stuff, which is why I +// left the license in here. Most of the Apache commons compressor magic +// has been ported into the BZip2Compressor class. +// + +using System; +using System.IO; +using System.Collections.Generic; +using System.Threading; + +namespace Ionic.BZip2 +{ + internal class WorkItem + { + public int index; + public BZip2Compressor Compressor { get; private set; } + public MemoryStream ms; + public int ordinal; + public BitWriter bw; + + public WorkItem(int ix, int blockSize) + { + // compressed data gets written to a MemoryStream + this.ms = new MemoryStream(); + this.bw = new BitWriter(ms); + this.Compressor = new BZip2Compressor(bw, blockSize); + this.index = ix; + } + } + + + /// + /// A write-only decorator stream that compresses data as it is + /// written using the BZip2 algorithm. This stream compresses by + /// block using multiple threads. + /// + /// + /// This class performs BZIP2 compression through writing. For + /// more information on the BZIP2 algorithm, see + /// . + /// + /// + /// + /// This class is similar to , + /// except that this implementation uses an approach that employs multiple + /// worker threads to perform the compression. On a multi-cpu or multi-core + /// computer, the performance of this class can be significantly higher than + /// the single-threaded BZip2OutputStream, particularly for larger streams. + /// How large? Anything over 10mb is a good candidate for parallel + /// compression. + /// + /// + /// + /// The tradeoff is that this class uses more memory and more CPU than the + /// vanilla BZip2OutputStream. Also, for small files, the + /// ParallelBZip2OutputStream can be much slower than the vanilla + /// BZip2OutputStream, because of the overhead associated to using the + /// thread pool. + /// + /// + /// + public class ParallelBZip2OutputStream : System.IO.Stream + { + private static readonly int BufferPairsPerCore = 4; + private int _maxWorkers; + private bool firstWriteDone; + private int lastFilled; + private int lastWritten; + private int latestCompressed; + private int currentlyFilling; + private volatile Exception pendingException; + private bool handlingException; + private bool emitting; + private System.Collections.Generic.Queue toWrite; + private System.Collections.Generic.Queue toFill; + private System.Collections.Generic.List pool; + private object latestLock = new object(); + private object eLock = new object(); // for exceptions + private object outputLock = new object(); // for multi-thread output + private AutoResetEvent newlyCompressedBlob; + + long totalBytesWrittenIn; + long totalBytesWrittenOut; + bool leaveOpen; + uint combinedCRC; + Stream output; + BitWriter bw; + int blockSize100k; // 0...9 + + private TraceBits desiredTrace = TraceBits.Crc | TraceBits.Write; + + /// + /// Constructs a new ParallelBZip2OutputStream, that sends its + /// compressed output to the given output stream. + /// + /// + /// + /// The destination stream, to which compressed output will be sent. + /// + /// + /// + /// + /// This example reads a file, then compresses it with bzip2 file, + /// and writes the compressed data into a newly created file. + /// + /// + /// var fname = "logfile.log"; + /// using (var fs = File.OpenRead(fname)) + /// { + /// var outFname = fname + ".bz2"; + /// using (var output = File.Create(outFname)) + /// { + /// using (var compressor = new Ionic.BZip2.ParallelBZip2OutputStream(output)) + /// { + /// byte[] buffer = new byte[2048]; + /// int n; + /// while ((n = fs.Read(buffer, 0, buffer.Length)) > 0) + /// { + /// compressor.Write(buffer, 0, n); + /// } + /// } + /// } + /// } + /// + /// + public ParallelBZip2OutputStream(Stream output) + : this(output, BZip2.MaxBlockSize, false) + { + } + + /// + /// Constructs a new ParallelBZip2OutputStream with specified blocksize. + /// + /// the destination stream. + /// + /// The blockSize in units of 100000 bytes. + /// The valid range is 1..9. + /// + public ParallelBZip2OutputStream(Stream output, int blockSize) + : this(output, blockSize, false) + { + } + + /// + /// Constructs a new ParallelBZip2OutputStream. + /// + /// the destination stream. + /// + /// whether to leave the captive stream open upon closing this stream. + /// + public ParallelBZip2OutputStream(Stream output, bool leaveOpen) + : this(output, BZip2.MaxBlockSize, leaveOpen) + { + } + + /// + /// Constructs a new ParallelBZip2OutputStream with specified blocksize, + /// and explicitly specifies whether to leave the wrapped stream open. + /// + /// + /// the destination stream. + /// + /// The blockSize in units of 100000 bytes. + /// The valid range is 1..9. + /// + /// + /// whether to leave the captive stream open upon closing this stream. + /// + public ParallelBZip2OutputStream(Stream output, int blockSize, bool leaveOpen) + { + if (blockSize < BZip2.MinBlockSize || blockSize > BZip2.MaxBlockSize) + { + var msg = String.Format("blockSize={0} is out of range; must be between {1} and {2}", + blockSize, + BZip2.MinBlockSize, BZip2.MaxBlockSize); + throw new ArgumentException(msg, "blockSize"); + } + + this.output = output; + if (!this.output.CanWrite) + throw new ArgumentException("The stream is not writable.", "output"); + + this.bw = new BitWriter(this.output); + this.blockSize100k = blockSize; + this.leaveOpen = leaveOpen; + this.combinedCRC = 0; + this.MaxWorkers = 16; // default + EmitHeader(); + } + + + private void InitializePoolOfWorkItems() + { + this.toWrite = new Queue(); + this.toFill = new Queue(); + this.pool = new System.Collections.Generic.List(); + int nWorkers = BufferPairsPerCore * Environment.ProcessorCount; + nWorkers = Math.Min(nWorkers, this.MaxWorkers); + for(int i=0; i < nWorkers; i++) + { + this.pool.Add(new WorkItem(i, this.blockSize100k)); + this.toFill.Enqueue(i); + } + + this.newlyCompressedBlob = new AutoResetEvent(false); + this.currentlyFilling = -1; + this.lastFilled = -1; + this.lastWritten = -1; + this.latestCompressed = -1; + } + + + /// + /// The maximum number of concurrent compression worker threads to use. + /// + /// + /// + /// + /// This property sets an upper limit on the number of concurrent worker + /// threads to employ for compression. The implementation of this stream + /// employs multiple threads from the .NET thread pool, via + /// ThreadPool.QueueUserWorkItem(), to compress the incoming data by + /// block. As each block of data is compressed, this stream re-orders the + /// compressed blocks and writes them to the output stream. + /// + /// + /// + /// A higher number of workers enables a higher degree of + /// parallelism, which tends to increase the speed of compression on + /// multi-cpu computers. On the other hand, a higher number of buffer + /// pairs also implies a larger memory consumption, more active worker + /// threads, and a higher cpu utilization for any compression. This + /// property enables the application to limit its memory consumption and + /// CPU utilization behavior depending on requirements. + /// + /// + /// + /// By default, DotNetZip allocates 4 workers per CPU core, subject to the + /// upper limit specified in this property. For example, suppose the + /// application sets this property to 16. Then, on a machine with 2 + /// cores, DotNetZip will use 8 workers; that number does not exceed the + /// upper limit specified by this property, so the actual number of + /// workers used will be 4 * 2 = 8. On a machine with 4 cores, DotNetZip + /// will use 16 workers; again, the limit does not apply. On a machine + /// with 8 cores, DotNetZip will use 16 workers, because of the limit. + /// + /// + /// + /// For each compression "worker thread" that occurs in parallel, there is + /// up to 2mb of memory allocated, for buffering and processing. The + /// actual number depends on the property. + /// + /// + /// + /// CPU utilization will also go up with additional workers, because a + /// larger number of buffer pairs allows a larger number of background + /// threads to compress in parallel. If you find that parallel + /// compression is consuming too much memory or CPU, you can adjust this + /// value downward. + /// + /// + /// + /// The default value is 16. Different values may deliver better or + /// worse results, depending on your priorities and the dynamic + /// performance characteristics of your storage and compute resources. + /// + /// + /// + /// The application can set this value at any time, but it is effective + /// only before the first call to Write(), which is when the buffers are + /// allocated. + /// + /// + public int MaxWorkers + { + get + { + return _maxWorkers; + } + set + { + if (value < 4) + throw new ArgumentException("MaxWorkers", + "Value must be 4 or greater."); + _maxWorkers = value; + } + } + + /// + /// Close the stream. + /// + /// + /// + /// This may or may not close the underlying stream. Check the + /// constructors that accept a bool value. + /// + /// + public override void Close() + { + if (this.pendingException != null) + { + this.handlingException = true; + var pe = this.pendingException; + this.pendingException = null; + throw pe; + } + + if (this.handlingException) + return; + + if (output == null) + return; + + Stream o = this.output; + + try + { + FlushOutput(true); + } + finally + { + this.output = null; + this.bw = null; + } + + if (!leaveOpen) + o.Close(); + } + + + private void FlushOutput(bool lastInput) + { + if (this.emitting) return; + + // compress and write whatever is ready + if (this.currentlyFilling >= 0) + { + WorkItem workitem = this.pool[this.currentlyFilling]; + CompressOne(workitem); + this.currentlyFilling = -1; // get a new buffer next Write() + } + + if (lastInput) + { + EmitPendingBuffers(true, false); + EmitTrailer(); + } + else + { + EmitPendingBuffers(false, false); + } + } + + + + /// + /// Flush the stream. + /// + public override void Flush() + { + if (this.output != null) + { + FlushOutput(false); + this.bw.Flush(); + this.output.Flush(); + } + } + + private void EmitHeader() + { + var magic = new byte[] { + (byte) 'B', + (byte) 'Z', + (byte) 'h', + (byte) ('0' + this.blockSize100k) + }; + + // not necessary to shred the initial magic bytes + this.output.Write(magic, 0, magic.Length); + } + + private void EmitTrailer() + { + // A magic 48-bit number, 0x177245385090, to indicate the end + // of the last block. (sqrt(pi), if you want to know) + + TraceOutput(TraceBits.Write, "total written out: {0} (0x{0:X})", + this.bw.TotalBytesWrittenOut); + + // must shred + this.bw.WriteByte(0x17); + this.bw.WriteByte(0x72); + this.bw.WriteByte(0x45); + this.bw.WriteByte(0x38); + this.bw.WriteByte(0x50); + this.bw.WriteByte(0x90); + + this.bw.WriteInt(this.combinedCRC); + + this.bw.FinishAndPad(); + + TraceOutput(TraceBits.Write, "final total : {0} (0x{0:X})", + this.bw.TotalBytesWrittenOut); + } + + + /// + /// The blocksize parameter specified at construction time. + /// + public int BlockSize + { + get { return this.blockSize100k; } + } + + + /// + /// Write data to the stream. + /// + /// + /// + /// + /// Use the ParallelBZip2OutputStream to compress data while + /// writing: create a ParallelBZip2OutputStream with a writable + /// output stream. Then call Write() on that + /// ParallelBZip2OutputStream, providing uncompressed data as + /// input. The data sent to the output stream will be the compressed + /// form of the input data. + /// + /// + /// + /// A ParallelBZip2OutputStream can be used only for + /// Write() not for Read(). + /// + /// + /// + /// + /// The buffer holding data to write to the stream. + /// the offset within that data array to find the first byte to write. + /// the number of bytes to write. + public override void Write(byte[] buffer, int offset, int count) + { + bool mustWait = false; + + // This method does this: + // 0. handles any pending exceptions + // 1. write any buffers that are ready to be written + // 2. fills a compressor buffer; when full, flip state to 'Filled', + // 3. if more data to be written, goto step 1 + + if (this.output == null) + throw new IOException("the stream is not open"); + + // dispense any exceptions that occurred on the BG threads + if (this.pendingException != null) + { + this.handlingException = true; + var pe = this.pendingException; + this.pendingException = null; + throw pe; + } + + if (offset < 0) + throw new IndexOutOfRangeException(String.Format("offset ({0}) must be > 0", offset)); + if (count < 0) + throw new IndexOutOfRangeException(String.Format("count ({0}) must be > 0", count)); + if (offset + count > buffer.Length) + throw new IndexOutOfRangeException(String.Format("offset({0}) count({1}) bLength({2})", + offset, count, buffer.Length)); + + + if (count == 0) return; // nothing to do + + + if (!this.firstWriteDone) + { + // Want to do this on first Write, first session, and not in the + // constructor. Must allow the MaxWorkers to change after + // construction, but before first Write(). + InitializePoolOfWorkItems(); + this.firstWriteDone = true; + } + + int bytesWritten = 0; + int bytesRemaining = count; + + do + { + // may need to make buffers available + EmitPendingBuffers(false, mustWait); + + mustWait = false; + + // get a compressor to fill + int ix = -1; + if (this.currentlyFilling >= 0) + { + ix = this.currentlyFilling; + } + else + { + if (this.toFill.Count == 0) + { + // No compressors available to fill, so... need to emit + // compressed buffers. + mustWait = true; + continue; + } + + ix = this.toFill.Dequeue(); + ++this.lastFilled; + } + + WorkItem workitem = this.pool[ix]; + workitem.ordinal = this.lastFilled; + + int n = workitem.Compressor.Fill(buffer, offset, bytesRemaining); + if (n != bytesRemaining) + { + if (!ThreadPool.QueueUserWorkItem( CompressOne, workitem )) + throw new Exception("Cannot enqueue workitem"); + + this.currentlyFilling = -1; // will get a new buffer next time + offset += n; + } + else + this.currentlyFilling = ix; + + bytesRemaining -= n; + bytesWritten += n; + } + while (bytesRemaining > 0); + + totalBytesWrittenIn += bytesWritten; + return; + } + + + + private void EmitPendingBuffers(bool doAll, bool mustWait) + { + // When combining parallel compression with a ZipSegmentedStream, it's + // possible for the ZSS to throw from within this method. In that + // case, Close/Dispose will be called on this stream, if this stream + // is employed within a using or try/finally pair as required. But + // this stream is unaware of the pending exception, so the Close() + // method invokes this method AGAIN. This can lead to a deadlock. + // Therefore, failfast if re-entering. + + if (emitting) return; + emitting = true; + + if (doAll || mustWait) + this.newlyCompressedBlob.WaitOne(); + + do + { + int firstSkip = -1; + int millisecondsToWait = doAll ? 200 : (mustWait ? -1 : 0); + int nextToWrite = -1; + + do + { + if (Monitor.TryEnter(this.toWrite, millisecondsToWait)) + { + nextToWrite = -1; + try + { + if (this.toWrite.Count > 0) + nextToWrite = this.toWrite.Dequeue(); + } + finally + { + Monitor.Exit(this.toWrite); + } + + if (nextToWrite >= 0) + { + WorkItem workitem = this.pool[nextToWrite]; + if (workitem.ordinal != this.lastWritten + 1) + { + // out of order. requeue and try again. + lock(this.toWrite) + { + this.toWrite.Enqueue(nextToWrite); + } + + if (firstSkip == nextToWrite) + { + // We went around the list once. + // None of the items in the list is the one we want. + // Now wait for a compressor to signal again. + this.newlyCompressedBlob.WaitOne(); + firstSkip = -1; + } + else if (firstSkip == -1) + firstSkip = nextToWrite; + + continue; + } + + firstSkip = -1; + + TraceOutput(TraceBits.Write, + "Writing block {0}", workitem.ordinal); + + // write the data to the output + var bw2 = workitem.bw; + bw2.Flush(); // not bw2.FinishAndPad()! + var ms = workitem.ms; + ms.Seek(0,SeekOrigin.Begin); + + // cannot dump bytes!! + // ms.WriteTo(this.output); + // + // must do byte shredding: + int n; + int y = -1; + long totOut = 0; + var buffer = new byte[1024]; + while ((n = ms.Read(buffer,0,buffer.Length)) > 0) + { +#if Trace + if (y == -1) // diagnostics only + { + var sb1 = new System.Text.StringBuilder(); + sb1.Append("first 16 whole bytes in block: "); + for (int z=0; z < 16; z++) + sb1.Append(String.Format(" {0:X2}", buffer[z])); + TraceOutput(TraceBits.Write, sb1.ToString()); + } +#endif + y = n; + for (int k=0; k < n; k++) + { + this.bw.WriteByte(buffer[k]); + } + totOut += n; + } +#if Trace + TraceOutput(TraceBits.Write,"out block length (bytes): {0} (0x{0:X})", totOut); + var sb = new System.Text.StringBuilder(); + sb.Append("final 16 whole bytes in block: "); + for (int z=0; z < 16; z++) + sb.Append(String.Format(" {0:X2}", buffer[y-1-12+z])); + TraceOutput(TraceBits.Write, sb.ToString()); +#endif + + // and now any remaining bits + TraceOutput(TraceBits.Write, + " remaining bits: {0} 0x{1:X}", + bw2.NumRemainingBits, + bw2.RemainingBits); + if (bw2.NumRemainingBits > 0) + { + this.bw.WriteBits(bw2.NumRemainingBits, bw2.RemainingBits); + } + + TraceOutput(TraceBits.Crc," combined CRC (before): {0:X8}", + this.combinedCRC); + this.combinedCRC = (this.combinedCRC << 1) | (this.combinedCRC >> 31); + this.combinedCRC ^= (uint) workitem.Compressor.Crc32; + + TraceOutput(TraceBits.Crc, + " block CRC : {0:X8}", + workitem.Compressor.Crc32); + TraceOutput(TraceBits.Crc, + " combined CRC (after) : {0:X8}", + this.combinedCRC); + TraceOutput(TraceBits.Write, + "total written out: {0} (0x{0:X})", + this.bw.TotalBytesWrittenOut); + TraceOutput(TraceBits.Write | TraceBits.Crc, ""); + + this.totalBytesWrittenOut += totOut; + + bw2.Reset(); + this.lastWritten = workitem.ordinal; + workitem.ordinal = -1; + this.toFill.Enqueue(workitem.index); + + // don't wait next time through + if (millisecondsToWait == -1) millisecondsToWait = 0; + } + } + else + nextToWrite = -1; + + } while (nextToWrite >= 0); + + } while (doAll && (this.lastWritten != this.latestCompressed)); + + if (doAll) + { + TraceOutput(TraceBits.Crc, + " combined CRC (final) : {0:X8}", this.combinedCRC); + } + + emitting = false; + } + + + private void CompressOne(Object wi) + { + // compress and one buffer + WorkItem workitem = (WorkItem) wi; + try + { + // compress and write to the compressor's MemoryStream + workitem.Compressor.CompressAndWrite(); + + lock(this.latestLock) + { + if (workitem.ordinal > this.latestCompressed) + this.latestCompressed = workitem.ordinal; + } + lock (this.toWrite) + { + this.toWrite.Enqueue(workitem.index); + } + this.newlyCompressedBlob.Set(); + } + catch (System.Exception exc1) + { + lock(this.eLock) + { + // expose the exception to the main thread + if (this.pendingException!=null) + this.pendingException = exc1; + } + } + } + + + + + /// + /// Indicates whether the stream can be read. + /// + /// + /// The return value is always false. + /// + public override bool CanRead + { + get { return false; } + } + + /// + /// Indicates whether the stream supports Seek operations. + /// + /// + /// Always returns false. + /// + public override bool CanSeek + { + get { return false; } + } + + /// + /// Indicates whether the stream can be written. + /// + /// + /// The return value depends on whether the captive stream supports writing. + /// + public override bool CanWrite + { + get + { + if (this.output == null) throw new ObjectDisposedException("BZip2Stream"); + return this.output.CanWrite; + } + } + + /// + /// Reading this property always throws a . + /// + public override long Length + { + get { throw new NotImplementedException(); } + } + + /// + /// The position of the stream pointer. + /// + /// + /// + /// Setting this property always throws a . Reading will return the + /// total number of uncompressed bytes written through. + /// + public override long Position + { + get + { + return this.totalBytesWrittenIn; + } + set { throw new NotImplementedException(); } + } + + /// + /// The total number of bytes written out by the stream. + /// + /// + /// This value is meaningful only after a call to Close(). + /// + public Int64 BytesWrittenOut { get { return totalBytesWrittenOut; } } + + /// + /// Calling this method always throws a . + /// + /// this is irrelevant, since it will always throw! + /// this is irrelevant, since it will always throw! + /// irrelevant! + public override long Seek(long offset, System.IO.SeekOrigin origin) + { + throw new NotImplementedException(); + } + + /// + /// Calling this method always throws a . + /// + /// this is irrelevant, since it will always throw! + public override void SetLength(long value) + { + throw new NotImplementedException(); + } + + /// + /// Calling this method always throws a . + /// + /// this parameter is never used + /// this parameter is never used + /// this parameter is never used + /// never returns anything; always throws + public override int Read(byte[] buffer, int offset, int count) + { + throw new NotImplementedException(); + } + + + // used only when Trace is defined + [Flags] + enum TraceBits : uint + { + None = 0, + Crc = 1, + Write = 2, + All = 0xffffffff, + } + + + [System.Diagnostics.ConditionalAttribute("Trace")] + private void TraceOutput(TraceBits bits, string format, params object[] varParams) + { + if ((bits & this.desiredTrace) != 0) + { + lock(outputLock) + { + int tid = Thread.CurrentThread.GetHashCode(); +#if !SILVERLIGHT + Console.ForegroundColor = (ConsoleColor) (tid % 8 + 10); +#endif + Console.Write("{0:000} PBOS ", tid); + Console.WriteLine(format, varParams); +#if !SILVERLIGHT + Console.ResetColor(); +#endif + } + } + } + + } + +} diff --git a/Resources/Libraries/DotNetZip/Source/BZip2/Rand.cs b/Resources/Libraries/DotNetZip/Source/BZip2/Rand.cs new file mode 100644 index 00000000..08169dbd --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/BZip2/Rand.cs @@ -0,0 +1,99 @@ +// Rand.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// Last Saved: <2011-July-31 15:09:16> +// +// ------------------------------------------------------------------ +// +// This module defines a helper class for the BZip2 classes. This code +// is derived from the original BZip2 source code. +// +// ------------------------------------------------------------------ + + +namespace Ionic.BZip2 +{ + internal static class Rand + { + private static int[] RNUMS = + { + 619, 720, 127, 481, 931, 816, 813, 233, 566, 247, + 985, 724, 205, 454, 863, 491, 741, 242, 949, 214, + 733, 859, 335, 708, 621, 574, 73, 654, 730, 472, + 419, 436, 278, 496, 867, 210, 399, 680, 480, 51, + 878, 465, 811, 169, 869, 675, 611, 697, 867, 561, + 862, 687, 507, 283, 482, 129, 807, 591, 733, 623, + 150, 238, 59, 379, 684, 877, 625, 169, 643, 105, + 170, 607, 520, 932, 727, 476, 693, 425, 174, 647, + 73, 122, 335, 530, 442, 853, 695, 249, 445, 515, + 909, 545, 703, 919, 874, 474, 882, 500, 594, 612, + 641, 801, 220, 162, 819, 984, 589, 513, 495, 799, + 161, 604, 958, 533, 221, 400, 386, 867, 600, 782, + 382, 596, 414, 171, 516, 375, 682, 485, 911, 276, + 98, 553, 163, 354, 666, 933, 424, 341, 533, 870, + 227, 730, 475, 186, 263, 647, 537, 686, 600, 224, + 469, 68, 770, 919, 190, 373, 294, 822, 808, 206, + 184, 943, 795, 384, 383, 461, 404, 758, 839, 887, + 715, 67, 618, 276, 204, 918, 873, 777, 604, 560, + 951, 160, 578, 722, 79, 804, 96, 409, 713, 940, + 652, 934, 970, 447, 318, 353, 859, 672, 112, 785, + 645, 863, 803, 350, 139, 93, 354, 99, 820, 908, + 609, 772, 154, 274, 580, 184, 79, 626, 630, 742, + 653, 282, 762, 623, 680, 81, 927, 626, 789, 125, + 411, 521, 938, 300, 821, 78, 343, 175, 128, 250, + 170, 774, 972, 275, 999, 639, 495, 78, 352, 126, + 857, 956, 358, 619, 580, 124, 737, 594, 701, 612, + 669, 112, 134, 694, 363, 992, 809, 743, 168, 974, + 944, 375, 748, 52, 600, 747, 642, 182, 862, 81, + 344, 805, 988, 739, 511, 655, 814, 334, 249, 515, + 897, 955, 664, 981, 649, 113, 974, 459, 893, 228, + 433, 837, 553, 268, 926, 240, 102, 654, 459, 51, + 686, 754, 806, 760, 493, 403, 415, 394, 687, 700, + 946, 670, 656, 610, 738, 392, 760, 799, 887, 653, + 978, 321, 576, 617, 626, 502, 894, 679, 243, 440, + 680, 879, 194, 572, 640, 724, 926, 56, 204, 700, + 707, 151, 457, 449, 797, 195, 791, 558, 945, 679, + 297, 59, 87, 824, 713, 663, 412, 693, 342, 606, + 134, 108, 571, 364, 631, 212, 174, 643, 304, 329, + 343, 97, 430, 751, 497, 314, 983, 374, 822, 928, + 140, 206, 73, 263, 980, 736, 876, 478, 430, 305, + 170, 514, 364, 692, 829, 82, 855, 953, 676, 246, + 369, 970, 294, 750, 807, 827, 150, 790, 288, 923, + 804, 378, 215, 828, 592, 281, 565, 555, 710, 82, + 896, 831, 547, 261, 524, 462, 293, 465, 502, 56, + 661, 821, 976, 991, 658, 869, 905, 758, 745, 193, + 768, 550, 608, 933, 378, 286, 215, 979, 792, 961, + 61, 688, 793, 644, 986, 403, 106, 366, 905, 644, + 372, 567, 466, 434, 645, 210, 389, 550, 919, 135, + 780, 773, 635, 389, 707, 100, 626, 958, 165, 504, + 920, 176, 193, 713, 857, 265, 203, 50, 668, 108, + 645, 990, 626, 197, 510, 357, 358, 850, 858, 364, + 936, 638 + }; + + + /// + /// Returns the "random" number at a specific index. + /// + /// the index + /// the random number + internal static int Rnums(int i) + { + return RNUMS[i]; + } + } + +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/CommonSrc/CRC32.cs b/Resources/Libraries/DotNetZip/Source/CommonSrc/CRC32.cs new file mode 100644 index 00000000..53a4fa37 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/CommonSrc/CRC32.cs @@ -0,0 +1,814 @@ +// CRC32.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// Last Saved: <2011-August-02 18:25:54> +// +// ------------------------------------------------------------------ +// +// This module defines the CRC32 class, which can do the CRC32 algorithm, using +// arbitrary starting polynomials, and bit reversal. The bit reversal is what +// distinguishes this CRC-32 used in BZip2 from the CRC-32 that is used in PKZIP +// files, or GZIP files. This class does both. +// +// ------------------------------------------------------------------ + + +using System; +using Interop = System.Runtime.InteropServices; + +namespace Ionic.Crc +{ + /// + /// Computes a CRC-32. The CRC-32 algorithm is parameterized - you + /// can set the polynomial and enable or disable bit + /// reversal. This can be used for GZIP, BZip2, or ZIP. + /// + /// + /// This type is used internally by DotNetZip; it is generally not used + /// directly by applications wishing to create, read, or manipulate zip + /// archive files. + /// + + [Interop.GuidAttribute("ebc25cf6-9120-4283-b972-0e5520d0000C")] + [Interop.ComVisible(true)] +#if !NETCF + [Interop.ClassInterface(Interop.ClassInterfaceType.AutoDispatch)] +#endif + public class CRC32 + { + /// + /// Indicates the total number of bytes applied to the CRC. + /// + public Int64 TotalBytesRead + { + get + { + return _TotalBytesRead; + } + } + + /// + /// Indicates the current CRC for all blocks slurped in. + /// + public Int32 Crc32Result + { + get + { + return unchecked((Int32)(~_register)); + } + } + + /// + /// Returns the CRC32 for the specified stream. + /// + /// The stream over which to calculate the CRC32 + /// the CRC32 calculation + public Int32 GetCrc32(System.IO.Stream input) + { + return GetCrc32AndCopy(input, null); + } + + /// + /// Returns the CRC32 for the specified stream, and writes the input into the + /// output stream. + /// + /// The stream over which to calculate the CRC32 + /// The stream into which to deflate the input + /// the CRC32 calculation + public Int32 GetCrc32AndCopy(System.IO.Stream input, System.IO.Stream output) + { + if (input == null) + throw new Exception("The input stream must not be null."); + + unchecked + { + byte[] buffer = new byte[BUFFER_SIZE]; + int readSize = BUFFER_SIZE; + + _TotalBytesRead = 0; + int count = input.Read(buffer, 0, readSize); + if (output != null) output.Write(buffer, 0, count); + _TotalBytesRead += count; + while (count > 0) + { + SlurpBlock(buffer, 0, count); + count = input.Read(buffer, 0, readSize); + if (output != null) output.Write(buffer, 0, count); + _TotalBytesRead += count; + } + + return (Int32)(~_register); + } + } + + + /// + /// Get the CRC32 for the given (word,byte) combo. This is a + /// computation defined by PKzip for PKZIP 2.0 (weak) encryption. + /// + /// The word to start with. + /// The byte to combine it with. + /// The CRC-ized result. + public Int32 ComputeCrc32(Int32 W, byte B) + { + return _InternalComputeCrc32((UInt32)W, B); + } + + internal Int32 _InternalComputeCrc32(UInt32 W, byte B) + { + return (Int32)(crc32Table[(W ^ B) & 0xFF] ^ (W >> 8)); + } + + + /// + /// Update the value for the running CRC32 using the given block of bytes. + /// This is useful when using the CRC32() class in a Stream. + /// + /// block of bytes to slurp + /// starting point in the block + /// how many bytes within the block to slurp + public void SlurpBlock(byte[] block, int offset, int count) + { + if (block == null) + throw new Exception("The data buffer must not be null."); + + // bzip algorithm + for (int i = 0; i < count; i++) + { + int x = offset + i; + byte b = block[x]; + if (this.reverseBits) + { + UInt32 temp = (_register >> 24) ^ b; + _register = (_register << 8) ^ crc32Table[temp]; + } + else + { + UInt32 temp = (_register & 0x000000FF) ^ b; + _register = (_register >> 8) ^ crc32Table[temp]; + } + } + _TotalBytesRead += count; + } + + + /// + /// Process one byte in the CRC. + /// + /// the byte to include into the CRC . + public void UpdateCRC(byte b) + { + if (this.reverseBits) + { + UInt32 temp = (_register >> 24) ^ b; + _register = (_register << 8) ^ crc32Table[temp]; + } + else + { + UInt32 temp = (_register & 0x000000FF) ^ b; + _register = (_register >> 8) ^ crc32Table[temp]; + } + } + + /// + /// Process a run of N identical bytes into the CRC. + /// + /// + /// + /// This method serves as an optimization for updating the CRC when a + /// run of identical bytes is found. Rather than passing in a buffer of + /// length n, containing all identical bytes b, this method accepts the + /// byte value and the length of the (virtual) buffer - the length of + /// the run. + /// + /// + /// the byte to include into the CRC. + /// the number of times that byte should be repeated. + public void UpdateCRC(byte b, int n) + { + while (n-- > 0) + { + if (this.reverseBits) + { + uint temp = (_register >> 24) ^ b; + _register = (_register << 8) ^ crc32Table[(temp >= 0) + ? temp + : (temp + 256)]; + } + else + { + UInt32 temp = (_register & 0x000000FF) ^ b; + _register = (_register >> 8) ^ crc32Table[(temp >= 0) + ? temp + : (temp + 256)]; + + } + } + } + + + + private static uint ReverseBits(uint data) + { + unchecked + { + uint ret = data; + ret = (ret & 0x55555555) << 1 | (ret >> 1) & 0x55555555; + ret = (ret & 0x33333333) << 2 | (ret >> 2) & 0x33333333; + ret = (ret & 0x0F0F0F0F) << 4 | (ret >> 4) & 0x0F0F0F0F; + ret = (ret << 24) | ((ret & 0xFF00) << 8) | ((ret >> 8) & 0xFF00) | (ret >> 24); + return ret; + } + } + + private static byte ReverseBits(byte data) + { + unchecked + { + uint u = (uint)data * 0x00020202; + uint m = 0x01044010; + uint s = u & m; + uint t = (u << 2) & (m << 1); + return (byte)((0x01001001 * (s + t)) >> 24); + } + } + + + + private void GenerateLookupTable() + { + crc32Table = new UInt32[256]; + unchecked + { + UInt32 dwCrc; + byte i = 0; + do + { + dwCrc = i; + for (byte j = 8; j > 0; j--) + { + if ((dwCrc & 1) == 1) + { + dwCrc = (dwCrc >> 1) ^ dwPolynomial; + } + else + { + dwCrc >>= 1; + } + } + if (reverseBits) + { + crc32Table[ReverseBits(i)] = ReverseBits(dwCrc); + } + else + { + crc32Table[i] = dwCrc; + } + i++; + } while (i!=0); + } + +#if VERBOSE + Console.WriteLine(); + Console.WriteLine("private static readonly UInt32[] crc32Table = {"); + for (int i = 0; i < crc32Table.Length; i+=4) + { + Console.Write(" "); + for (int j=0; j < 4; j++) + { + Console.Write(" 0x{0:X8}U,", crc32Table[i+j]); + } + Console.WriteLine(); + } + Console.WriteLine("};"); + Console.WriteLine(); +#endif + } + + + private uint gf2_matrix_times(uint[] matrix, uint vec) + { + uint sum = 0; + int i=0; + while (vec != 0) + { + if ((vec & 0x01)== 0x01) + sum ^= matrix[i]; + vec >>= 1; + i++; + } + return sum; + } + + private void gf2_matrix_square(uint[] square, uint[] mat) + { + for (int i = 0; i < 32; i++) + square[i] = gf2_matrix_times(mat, mat[i]); + } + + + + /// + /// Combines the given CRC32 value with the current running total. + /// + /// + /// This is useful when using a divide-and-conquer approach to + /// calculating a CRC. Multiple threads can each calculate a + /// CRC32 on a segment of the data, and then combine the + /// individual CRC32 values at the end. + /// + /// the crc value to be combined with this one + /// the length of data the CRC value was calculated on + public void Combine(int crc, int length) + { + uint[] even = new uint[32]; // even-power-of-two zeros operator + uint[] odd = new uint[32]; // odd-power-of-two zeros operator + + if (length == 0) + return; + + uint crc1= ~_register; + uint crc2= (uint) crc; + + // put operator for one zero bit in odd + odd[0] = this.dwPolynomial; // the CRC-32 polynomial + uint row = 1; + for (int i = 1; i < 32; i++) + { + odd[i] = row; + row <<= 1; + } + + // put operator for two zero bits in even + gf2_matrix_square(even, odd); + + // put operator for four zero bits in odd + gf2_matrix_square(odd, even); + + uint len2 = (uint) length; + + // apply len2 zeros to crc1 (first square will put the operator for one + // zero byte, eight zero bits, in even) + do { + // apply zeros operator for this bit of len2 + gf2_matrix_square(even, odd); + + if ((len2 & 1)== 1) + crc1 = gf2_matrix_times(even, crc1); + len2 >>= 1; + + if (len2 == 0) + break; + + // another iteration of the loop with odd and even swapped + gf2_matrix_square(odd, even); + if ((len2 & 1)==1) + crc1 = gf2_matrix_times(odd, crc1); + len2 >>= 1; + + + } while (len2 != 0); + + crc1 ^= crc2; + + _register= ~crc1; + + //return (int) crc1; + return; + } + + + /// + /// Create an instance of the CRC32 class using the default settings: no + /// bit reversal, and a polynomial of 0xEDB88320. + /// + public CRC32() : this(false) + { + } + + /// + /// Create an instance of the CRC32 class, specifying whether to reverse + /// data bits or not. + /// + /// + /// specify true if the instance should reverse data bits. + /// + /// + /// + /// In the CRC-32 used by BZip2, the bits are reversed. Therefore if you + /// want a CRC32 with compatibility with BZip2, you should pass true + /// here. In the CRC-32 used by GZIP and PKZIP, the bits are not + /// reversed; Therefore if you want a CRC32 with compatibility with + /// those, you should pass false. + /// + /// + public CRC32(bool reverseBits) : + this( unchecked((int)0xEDB88320), reverseBits) + { + } + + + /// + /// Create an instance of the CRC32 class, specifying the polynomial and + /// whether to reverse data bits or not. + /// + /// + /// The polynomial to use for the CRC, expressed in the reversed (LSB) + /// format: the highest ordered bit in the polynomial value is the + /// coefficient of the 0th power; the second-highest order bit is the + /// coefficient of the 1 power, and so on. Expressed this way, the + /// polynomial for the CRC-32C used in IEEE 802.3, is 0xEDB88320. + /// + /// + /// specify true if the instance should reverse data bits. + /// + /// + /// + /// + /// In the CRC-32 used by BZip2, the bits are reversed. Therefore if you + /// want a CRC32 with compatibility with BZip2, you should pass true + /// here for the reverseBits parameter. In the CRC-32 used by + /// GZIP and PKZIP, the bits are not reversed; Therefore if you want a + /// CRC32 with compatibility with those, you should pass false for the + /// reverseBits parameter. + /// + /// + public CRC32(int polynomial, bool reverseBits) + { + this.reverseBits = reverseBits; + this.dwPolynomial = (uint) polynomial; + this.GenerateLookupTable(); + } + + /// + /// Reset the CRC-32 class - clear the CRC "remainder register." + /// + /// + /// + /// Use this when employing a single instance of this class to compute + /// multiple, distinct CRCs on multiple, distinct data blocks. + /// + /// + public void Reset() + { + _register = 0xFFFFFFFFU; + } + + // private member vars + private UInt32 dwPolynomial; + private Int64 _TotalBytesRead; + private bool reverseBits; + private UInt32[] crc32Table; + private const int BUFFER_SIZE = 8192; + private UInt32 _register = 0xFFFFFFFFU; + } + + + /// + /// A Stream that calculates a CRC32 (a checksum) on all bytes read, + /// or on all bytes written. + /// + /// + /// + /// + /// This class can be used to verify the CRC of a ZipEntry when + /// reading from a stream, or to calculate a CRC when writing to a + /// stream. The stream should be used to either read, or write, but + /// not both. If you intermix reads and writes, the results are not + /// defined. + /// + /// + /// + /// This class is intended primarily for use internally by the + /// DotNetZip library. + /// + /// + public class CrcCalculatorStream : System.IO.Stream, System.IDisposable + { + private static readonly Int64 UnsetLengthLimit = -99; + + internal System.IO.Stream _innerStream; + private CRC32 _Crc32; + private Int64 _lengthLimit = -99; + private bool _leaveOpen; + + /// + /// The default constructor. + /// + /// + /// + /// Instances returned from this constructor will leave the underlying + /// stream open upon Close(). The stream uses the default CRC32 + /// algorithm, which implies a polynomial of 0xEDB88320. + /// + /// + /// The underlying stream + public CrcCalculatorStream(System.IO.Stream stream) + : this(true, CrcCalculatorStream.UnsetLengthLimit, stream, null) + { + } + + /// + /// The constructor allows the caller to specify how to handle the + /// underlying stream at close. + /// + /// + /// + /// The stream uses the default CRC32 algorithm, which implies a + /// polynomial of 0xEDB88320. + /// + /// + /// The underlying stream + /// true to leave the underlying stream + /// open upon close of the CrcCalculatorStream; false otherwise. + public CrcCalculatorStream(System.IO.Stream stream, bool leaveOpen) + : this(leaveOpen, CrcCalculatorStream.UnsetLengthLimit, stream, null) + { + } + + /// + /// A constructor allowing the specification of the length of the stream + /// to read. + /// + /// + /// + /// The stream uses the default CRC32 algorithm, which implies a + /// polynomial of 0xEDB88320. + /// + /// + /// Instances returned from this constructor will leave the underlying + /// stream open upon Close(). + /// + /// + /// The underlying stream + /// The length of the stream to slurp + public CrcCalculatorStream(System.IO.Stream stream, Int64 length) + : this(true, length, stream, null) + { + if (length < 0) + throw new ArgumentException("length"); + } + + /// + /// A constructor allowing the specification of the length of the stream + /// to read, as well as whether to keep the underlying stream open upon + /// Close(). + /// + /// + /// + /// The stream uses the default CRC32 algorithm, which implies a + /// polynomial of 0xEDB88320. + /// + /// + /// The underlying stream + /// The length of the stream to slurp + /// true to leave the underlying stream + /// open upon close of the CrcCalculatorStream; false otherwise. + public CrcCalculatorStream(System.IO.Stream stream, Int64 length, bool leaveOpen) + : this(leaveOpen, length, stream, null) + { + if (length < 0) + throw new ArgumentException("length"); + } + + /// + /// A constructor allowing the specification of the length of the stream + /// to read, as well as whether to keep the underlying stream open upon + /// Close(), and the CRC32 instance to use. + /// + /// + /// + /// The stream uses the specified CRC32 instance, which allows the + /// application to specify how the CRC gets calculated. + /// + /// + /// The underlying stream + /// The length of the stream to slurp + /// true to leave the underlying stream + /// open upon close of the CrcCalculatorStream; false otherwise. + /// the CRC32 instance to use to calculate the CRC32 + public CrcCalculatorStream(System.IO.Stream stream, Int64 length, bool leaveOpen, + CRC32 crc32) + : this(leaveOpen, length, stream, crc32) + { + if (length < 0) + throw new ArgumentException("length"); + } + + + // This ctor is private - no validation is done here. This is to allow the use + // of a (specific) negative value for the _lengthLimit, to indicate that there + // is no length set. So we validate the length limit in those ctors that use an + // explicit param, otherwise we don't validate, because it could be our special + // value. + private CrcCalculatorStream + (bool leaveOpen, Int64 length, System.IO.Stream stream, CRC32 crc32) + : base() + { + _innerStream = stream; + _Crc32 = crc32 ?? new CRC32(); + _lengthLimit = length; + _leaveOpen = leaveOpen; + } + + + /// + /// Gets the total number of bytes run through the CRC32 calculator. + /// + /// + /// + /// This is either the total number of bytes read, or the total number of + /// bytes written, depending on the direction of this stream. + /// + public Int64 TotalBytesSlurped + { + get { return _Crc32.TotalBytesRead; } + } + + /// + /// Provides the current CRC for all blocks slurped in. + /// + /// + /// + /// The running total of the CRC is kept as data is written or read + /// through the stream. read this property after all reads or writes to + /// get an accurate CRC for the entire stream. + /// + /// + public Int32 Crc + { + get { return _Crc32.Crc32Result; } + } + + /// + /// Indicates whether the underlying stream will be left open when the + /// CrcCalculatorStream is Closed. + /// + /// + /// + /// Set this at any point before calling . + /// + /// + public bool LeaveOpen + { + get { return _leaveOpen; } + set { _leaveOpen = value; } + } + + /// + /// Read from the stream + /// + /// the buffer to read + /// the offset at which to start + /// the number of bytes to read + /// the number of bytes actually read + public override int Read(byte[] buffer, int offset, int count) + { + int bytesToRead = count; + + // Need to limit the # of bytes returned, if the stream is intended to have + // a definite length. This is especially useful when returning a stream for + // the uncompressed data directly to the application. The app won't + // necessarily read only the UncompressedSize number of bytes. For example + // wrapping the stream returned from OpenReader() into a StreadReader() and + // calling ReadToEnd() on it, We can "over-read" the zip data and get a + // corrupt string. The length limits that, prevents that problem. + + if (_lengthLimit != CrcCalculatorStream.UnsetLengthLimit) + { + if (_Crc32.TotalBytesRead >= _lengthLimit) return 0; // EOF + Int64 bytesRemaining = _lengthLimit - _Crc32.TotalBytesRead; + if (bytesRemaining < count) bytesToRead = (int)bytesRemaining; + } + int n = _innerStream.Read(buffer, offset, bytesToRead); + if (n > 0) _Crc32.SlurpBlock(buffer, offset, n); + return n; + } + + /// + /// Write to the stream. + /// + /// the buffer from which to write + /// the offset at which to start writing + /// the number of bytes to write + public override void Write(byte[] buffer, int offset, int count) + { + if (count > 0) _Crc32.SlurpBlock(buffer, offset, count); + _innerStream.Write(buffer, offset, count); + } + + /// + /// Indicates whether the stream supports reading. + /// + public override bool CanRead + { + get { return _innerStream.CanRead; } + } + + /// + /// Indicates whether the stream supports seeking. + /// + /// + /// + /// Always returns false. + /// + /// + public override bool CanSeek + { + get { return false; } + } + + /// + /// Indicates whether the stream supports writing. + /// + public override bool CanWrite + { + get { return _innerStream.CanWrite; } + } + + /// + /// Flush the stream. + /// + public override void Flush() + { + _innerStream.Flush(); + } + + /// + /// Returns the length of the underlying stream. + /// + public override long Length + { + get + { + if (_lengthLimit == CrcCalculatorStream.UnsetLengthLimit) + return _innerStream.Length; + else return _lengthLimit; + } + } + + /// + /// The getter for this property returns the total bytes read. + /// If you use the setter, it will throw + /// . + /// + public override long Position + { + get { return _Crc32.TotalBytesRead; } + set { throw new NotSupportedException(); } + } + + /// + /// Seeking is not supported on this stream. This method always throws + /// + /// + /// N/A + /// N/A + /// N/A + public override long Seek(long offset, System.IO.SeekOrigin origin) + { + throw new NotSupportedException(); + } + + /// + /// This method always throws + /// + /// + /// N/A + public override void SetLength(long value) + { + throw new NotSupportedException(); + } + + + void IDisposable.Dispose() + { + Close(); + } + + /// + /// Closes the stream. + /// + public override void Close() + { + base.Close(); + if (!_leaveOpen) + _innerStream.Close(); + } + + } + +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ComHelper.cs b/Resources/Libraries/DotNetZip/Source/Zip/ComHelper.cs new file mode 100644 index 00000000..ccc20c8d --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ComHelper.cs @@ -0,0 +1,116 @@ +// ComHelper.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-June-13 17:04:06> +// +// ------------------------------------------------------------------ +// +// This module defines a COM Helper class. +// +// Created: Tue, 08 Sep 2009 22:03 +// + +using Interop=System.Runtime.InteropServices; + +namespace Ionic.Zip +{ + /// + /// This class exposes a set of COM-accessible wrappers for static + /// methods available on the ZipFile class. You don't need this + /// class unless you are using DotNetZip from a COM environment. + /// + [System.Runtime.InteropServices.GuidAttribute("ebc25cf6-9120-4283-b972-0e5520d0000F")] + [System.Runtime.InteropServices.ComVisible(true)] +#if !NETCF + [System.Runtime.InteropServices.ClassInterface(System.Runtime.InteropServices.ClassInterfaceType.AutoDispatch)] +#endif + + public class ComHelper + { + /// + /// A wrapper for ZipFile.IsZipFile(string) + /// + /// The filename to of the zip file to check. + /// true if the file contains a valid zip file. + public bool IsZipFile(string filename) + { + return ZipFile.IsZipFile(filename); + } + + /// + /// A wrapper for ZipFile.IsZipFile(string, bool) + /// + /// + /// We cannot use "overloaded" Method names in COM interop. + /// So, here, we use a unique name. + /// + /// The filename to of the zip file to check. + /// true if the file contains a valid zip file. + public bool IsZipFileWithExtract(string filename) + { + return ZipFile.IsZipFile(filename, true); + } + +#if !NETCF + /// + /// A wrapper for ZipFile.CheckZip(string) + /// + /// The filename to of the zip file to check. + /// + /// true if the named zip file checks OK. Otherwise, false. + public bool CheckZip(string filename) + { + return ZipFile.CheckZip(filename); + } + + /// + /// A COM-friendly wrapper for the static method . + /// + /// + /// The filename to of the zip file to check. + /// + /// The password to check. + /// + /// true if the named zip file checks OK. Otherwise, false. + public bool CheckZipPassword(string filename, string password) + { + return ZipFile.CheckZipPassword(filename, password); + } + + /// + /// A wrapper for ZipFile.FixZipDirectory(string) + /// + /// The filename to of the zip file to fix. + public void FixZipDirectory(string filename) + { + ZipFile.FixZipDirectory(filename); + } +#endif + + /// + /// A wrapper for ZipFile.LibraryVersion + /// + /// + /// the version number on the DotNetZip assembly, formatted as a string. + /// + public string GetZipLibraryVersion() + { + return ZipFile.LibraryVersion.ToString(); + } + + } +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/Zip/EncryptionAlgorithm.cs b/Resources/Libraries/DotNetZip/Source/Zip/EncryptionAlgorithm.cs new file mode 100644 index 00000000..391a8026 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/EncryptionAlgorithm.cs @@ -0,0 +1,135 @@ +// EncryptionAlgorithm.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2009-October-21 17:24:45> +// +// ------------------------------------------------------------------ +// +// This module defines the EncryptionAgorithm enum +// +// +// ------------------------------------------------------------------ + + +namespace Ionic.Zip +{ + /// + /// An enum that provides the various encryption algorithms supported by this + /// library. + /// + /// + /// + /// + /// + /// PkzipWeak implies the use of Zip 2.0 encryption, which is known to be + /// weak and subvertible. + /// + /// + /// + /// A note on interoperability: Values of PkzipWeak and None are + /// specified in PKWARE's zip + /// specification, and are considered to be "standard". Zip archives + /// produced using these options will be interoperable with many other zip tools + /// and libraries, including Windows Explorer. + /// + /// + /// + /// Values of WinZipAes128 and WinZipAes256 are not part of the Zip + /// specification, but rather imply the use of a vendor-specific extension from + /// WinZip. If you want to produce interoperable Zip archives, do not use these + /// values. For example, if you produce a zip archive using WinZipAes256, you + /// will be able to open it in Windows Explorer on Windows XP and Vista, but you + /// will not be able to extract entries; trying this will lead to an "unspecified + /// error". For this reason, some people have said that a zip archive that uses + /// WinZip's AES encryption is not actually a zip archive at all. A zip archive + /// produced this way will be readable with the WinZip tool (Version 11 and + /// beyond). + /// + /// + /// + /// There are other third-party tools and libraries, both commercial and + /// otherwise, that support WinZip's AES encryption. These will be able to read + /// AES-encrypted zip archives produced by DotNetZip, and conversely applications + /// that use DotNetZip to read zip archives will be able to read AES-encrypted + /// archives produced by those tools or libraries. Consult the documentation for + /// those other tools and libraries to find out if WinZip's AES encryption is + /// supported. + /// + /// + /// + /// In case you care: According to the WinZip specification, the + /// actual AES key used is derived from the via an + /// algorithm that complies with RFC 2898, using an iteration + /// count of 1000. The algorithm is sometimes referred to as PBKDF2, which stands + /// for "Password Based Key Derivation Function #2". + /// + /// + /// + /// A word about password strength and length: The AES encryption technology is + /// very good, but any system is only as secure as the weakest link. If you want + /// to secure your data, be sure to use a password that is hard to guess. To make + /// it harder to guess (increase its "entropy"), you should make it longer. If + /// you use normal characters from an ASCII keyboard, a password of length 20 will + /// be strong enough that it will be impossible to guess. For more information on + /// that, I'd encourage you to read this + /// article. + /// + /// + /// + /// The WinZip AES algorithms are not supported with the version of DotNetZip that + /// runs on the .NET Compact Framework. This is because .NET CF lacks the + /// HMACSHA1 class that is required for producing the archive. + /// + /// + public enum EncryptionAlgorithm + { + /// + /// No encryption at all. + /// + None = 0, + + /// + /// Traditional or Classic pkzip encryption. + /// + PkzipWeak, + +#if AESCRYPTO + /// + /// WinZip AES encryption (128 key bits). + /// + WinZipAes128, + + /// + /// WinZip AES encryption (256 key bits). + /// + WinZipAes256, +#endif + + /// + /// An encryption algorithm that is not supported by DotNetZip. + /// + Unsupported = 4, + + + // others... not implemented (yet?) + } + +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/Events.cs b/Resources/Libraries/DotNetZip/Source/Zip/Events.cs new file mode 100644 index 00000000..ad4497e0 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/Events.cs @@ -0,0 +1,684 @@ +// Events.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2006, 2007, 2008, 2009 Dino Chiesa and Microsoft Corporation. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-August-06 12:26:24> +// +// ------------------------------------------------------------------ +// +// This module defines events used by the ZipFile class. +// +// + +using System; +using System.Collections.Generic; +using System.Text; + +namespace Ionic.Zip +{ + /// + /// Delegate in which the application writes the ZipEntry content for the named entry. + /// + /// + /// The name of the entry that must be written. + /// The stream to which the entry data should be written. + /// + /// + /// When you add an entry and specify a WriteDelegate, via , the application + /// code provides the logic that writes the entry data directly into the zip file. + /// + /// + /// + /// + /// This example shows how to define a WriteDelegate that obtains a DataSet, and then + /// writes the XML for the DataSet into the zip archive. There's no need to + /// save the XML to a disk file first. + /// + /// + /// private void WriteEntry (String filename, Stream output) + /// { + /// DataSet ds1 = ObtainDataSet(); + /// ds1.WriteXml(output); + /// } + /// + /// private void Run() + /// { + /// using (var zip = new ZipFile()) + /// { + /// zip.AddEntry(zipEntryName, WriteEntry); + /// zip.Save(zipFileName); + /// } + /// } + /// + /// + /// + /// Private Sub WriteEntry (ByVal filename As String, ByVal output As Stream) + /// DataSet ds1 = ObtainDataSet() + /// ds1.WriteXml(stream) + /// End Sub + /// + /// Public Sub Run() + /// Using zip = New ZipFile + /// zip.AddEntry(zipEntryName, New WriteDelegate(AddressOf WriteEntry)) + /// zip.Save(zipFileName) + /// End Using + /// End Sub + /// + /// + /// + public delegate void WriteDelegate(string entryName, System.IO.Stream stream); + + + /// + /// Delegate in which the application opens the stream, just-in-time, for the named entry. + /// + /// + /// + /// The name of the ZipEntry that the application should open the stream for. + /// + /// + /// + /// When you add an entry via , the application code provides the logic that + /// opens and closes the stream for the given ZipEntry. + /// + /// + /// + public delegate System.IO.Stream OpenDelegate(string entryName); + + /// + /// Delegate in which the application closes the stream, just-in-time, for the named entry. + /// + /// + /// + /// The name of the ZipEntry that the application should close the stream for. + /// + /// + /// The stream to be closed. + /// + /// + /// When you add an entry via , the application code provides the logic that + /// opens and closes the stream for the given ZipEntry. + /// + /// + /// + public delegate void CloseDelegate(string entryName, System.IO.Stream stream); + + /// + /// Delegate for the callback by which the application tells the + /// library the CompressionLevel to use for a file. + /// + /// + /// + /// + /// Using this callback, the application can, for example, specify that + /// previously-compressed files (.mp3, .png, .docx, etc) should use a + /// CompressionLevel of None, or can set the compression level based + /// on any other factor. + /// + /// + /// + public delegate Ionic.Zlib.CompressionLevel SetCompressionCallback(string localFileName, string fileNameInArchive); + + /// + /// In an EventArgs type, indicates which sort of progress event is being + /// reported. + /// + /// + /// There are events for reading, events for saving, and events for + /// extracting. This enumeration allows a single EventArgs type to be sued to + /// describe one of multiple subevents. For example, a SaveProgress event is + /// invoked before, after, and during the saving of a single entry. The value + /// of an enum with this type, specifies which event is being triggered. The + /// same applies to Extraction, Reading and Adding events. + /// + public enum ZipProgressEventType + { + /// + /// Indicates that a Add() operation has started. + /// + Adding_Started, + + /// + /// Indicates that an individual entry in the archive has been added. + /// + Adding_AfterAddEntry, + + /// + /// Indicates that a Add() operation has completed. + /// + Adding_Completed, + + /// + /// Indicates that a Read() operation has started. + /// + Reading_Started, + + /// + /// Indicates that an individual entry in the archive is about to be read. + /// + Reading_BeforeReadEntry, + + /// + /// Indicates that an individual entry in the archive has just been read. + /// + Reading_AfterReadEntry, + + /// + /// Indicates that a Read() operation has completed. + /// + Reading_Completed, + + /// + /// The given event reports the number of bytes read so far + /// during a Read() operation. + /// + Reading_ArchiveBytesRead, + + /// + /// Indicates that a Save() operation has started. + /// + Saving_Started, + + /// + /// Indicates that an individual entry in the archive is about to be written. + /// + Saving_BeforeWriteEntry, + + /// + /// Indicates that an individual entry in the archive has just been saved. + /// + Saving_AfterWriteEntry, + + /// + /// Indicates that a Save() operation has completed. + /// + Saving_Completed, + + /// + /// Indicates that the zip archive has been created in a + /// temporary location during a Save() operation. + /// + Saving_AfterSaveTempArchive, + + /// + /// Indicates that the temporary file is about to be renamed to the final archive + /// name during a Save() operation. + /// + Saving_BeforeRenameTempArchive, + + /// + /// Indicates that the temporary file is has just been renamed to the final archive + /// name during a Save() operation. + /// + Saving_AfterRenameTempArchive, + + /// + /// Indicates that the self-extracting archive has been compiled + /// during a Save() operation. + /// + Saving_AfterCompileSelfExtractor, + + /// + /// The given event is reporting the number of source bytes that have run through the compressor so far + /// during a Save() operation. + /// + Saving_EntryBytesRead, + + /// + /// Indicates that an entry is about to be extracted. + /// + Extracting_BeforeExtractEntry, + + /// + /// Indicates that an entry has just been extracted. + /// + Extracting_AfterExtractEntry, + + /// + /// Indicates that extraction of an entry would overwrite an existing + /// filesystem file. You must use + /// + /// ExtractExistingFileAction.InvokeExtractProgressEvent in the call + /// to ZipEntry.Extract() in order to receive this event. + /// + Extracting_ExtractEntryWouldOverwrite, + + /// + /// The given event is reporting the number of bytes written so far for + /// the current entry during an Extract() operation. + /// + Extracting_EntryBytesWritten, + + /// + /// Indicates that an ExtractAll operation is about to begin. + /// + Extracting_BeforeExtractAll, + + /// + /// Indicates that an ExtractAll operation has completed. + /// + Extracting_AfterExtractAll, + + /// + /// Indicates that an error has occurred while saving a zip file. + /// This generally means the file cannot be opened, because it has been + /// removed, or because it is locked by another process. It can also + /// mean that the file cannot be Read, because of a range lock conflict. + /// + Error_Saving, + } + + + /// + /// Provides information about the progress of a save, read, or extract operation. + /// This is a base class; you will probably use one of the classes derived from this one. + /// + public class ZipProgressEventArgs : EventArgs + { + private int _entriesTotal; + private bool _cancel; + private ZipEntry _latestEntry; + private ZipProgressEventType _flavor; + private String _archiveName; + private Int64 _bytesTransferred; + private Int64 _totalBytesToTransfer; + + + internal ZipProgressEventArgs() { } + + internal ZipProgressEventArgs(string archiveName, ZipProgressEventType flavor) + { + this._archiveName = archiveName; + this._flavor = flavor; + } + + /// + /// The total number of entries to be saved or extracted. + /// + public int EntriesTotal + { + get { return _entriesTotal; } + set { _entriesTotal = value; } + } + + /// + /// The name of the last entry saved or extracted. + /// + public ZipEntry CurrentEntry + { + get { return _latestEntry; } + set { _latestEntry = value; } + } + + /// + /// In an event handler, set this to cancel the save or extract + /// operation that is in progress. + /// + public bool Cancel + { + get { return _cancel; } + set { _cancel = _cancel || value; } + } + + /// + /// The type of event being reported. + /// + public ZipProgressEventType EventType + { + get { return _flavor; } + set { _flavor = value; } + } + + /// + /// Returns the archive name associated to this event. + /// + public String ArchiveName + { + get { return _archiveName; } + set { _archiveName = value; } + } + + + /// + /// The number of bytes read or written so far for this entry. + /// + public Int64 BytesTransferred + { + get { return _bytesTransferred; } + set { _bytesTransferred = value; } + } + + + + /// + /// Total number of bytes that will be read or written for this entry. + /// This number will be -1 if the value cannot be determined. + /// + public Int64 TotalBytesToTransfer + { + get { return _totalBytesToTransfer; } + set { _totalBytesToTransfer = value; } + } + } + + + + /// + /// Provides information about the progress of a Read operation. + /// + public class ReadProgressEventArgs : ZipProgressEventArgs + { + + internal ReadProgressEventArgs() { } + + private ReadProgressEventArgs(string archiveName, ZipProgressEventType flavor) + : base(archiveName, flavor) + { } + + internal static ReadProgressEventArgs Before(string archiveName, int entriesTotal) + { + var x = new ReadProgressEventArgs(archiveName, ZipProgressEventType.Reading_BeforeReadEntry); + x.EntriesTotal = entriesTotal; + return x; + } + + internal static ReadProgressEventArgs After(string archiveName, ZipEntry entry, int entriesTotal) + { + var x = new ReadProgressEventArgs(archiveName, ZipProgressEventType.Reading_AfterReadEntry); + x.EntriesTotal = entriesTotal; + x.CurrentEntry = entry; + return x; + } + + internal static ReadProgressEventArgs Started(string archiveName) + { + var x = new ReadProgressEventArgs(archiveName, ZipProgressEventType.Reading_Started); + return x; + } + + internal static ReadProgressEventArgs ByteUpdate(string archiveName, ZipEntry entry, Int64 bytesXferred, Int64 totalBytes) + { + var x = new ReadProgressEventArgs(archiveName, ZipProgressEventType.Reading_ArchiveBytesRead); + x.CurrentEntry = entry; + x.BytesTransferred = bytesXferred; + x.TotalBytesToTransfer = totalBytes; + return x; + } + + internal static ReadProgressEventArgs Completed(string archiveName) + { + var x = new ReadProgressEventArgs(archiveName, ZipProgressEventType.Reading_Completed); + return x; + } + + } + + + /// + /// Provides information about the progress of a Add operation. + /// + public class AddProgressEventArgs : ZipProgressEventArgs + { + internal AddProgressEventArgs() { } + + private AddProgressEventArgs(string archiveName, ZipProgressEventType flavor) + : base(archiveName, flavor) + { } + + internal static AddProgressEventArgs AfterEntry(string archiveName, ZipEntry entry, int entriesTotal) + { + var x = new AddProgressEventArgs(archiveName, ZipProgressEventType.Adding_AfterAddEntry); + x.EntriesTotal = entriesTotal; + x.CurrentEntry = entry; + return x; + } + + internal static AddProgressEventArgs Started(string archiveName) + { + var x = new AddProgressEventArgs(archiveName, ZipProgressEventType.Adding_Started); + return x; + } + + internal static AddProgressEventArgs Completed(string archiveName) + { + var x = new AddProgressEventArgs(archiveName, ZipProgressEventType.Adding_Completed); + return x; + } + + } + + /// + /// Provides information about the progress of a save operation. + /// + public class SaveProgressEventArgs : ZipProgressEventArgs + { + private int _entriesSaved; + + /// + /// Constructor for the SaveProgressEventArgs. + /// + /// the name of the zip archive. + /// whether this is before saving the entry, or after + /// The total number of entries in the zip archive. + /// Number of entries that have been saved. + /// The entry involved in the event. + internal SaveProgressEventArgs(string archiveName, bool before, int entriesTotal, int entriesSaved, ZipEntry entry) + : base(archiveName, (before) ? ZipProgressEventType.Saving_BeforeWriteEntry : ZipProgressEventType.Saving_AfterWriteEntry) + { + this.EntriesTotal = entriesTotal; + this.CurrentEntry = entry; + this._entriesSaved = entriesSaved; + } + + internal SaveProgressEventArgs() { } + + internal SaveProgressEventArgs(string archiveName, ZipProgressEventType flavor) + : base(archiveName, flavor) + { } + + + internal static SaveProgressEventArgs ByteUpdate(string archiveName, ZipEntry entry, Int64 bytesXferred, Int64 totalBytes) + { + var x = new SaveProgressEventArgs(archiveName, ZipProgressEventType.Saving_EntryBytesRead); + x.ArchiveName = archiveName; + x.CurrentEntry = entry; + x.BytesTransferred = bytesXferred; + x.TotalBytesToTransfer = totalBytes; + return x; + } + + internal static SaveProgressEventArgs Started(string archiveName) + { + var x = new SaveProgressEventArgs(archiveName, ZipProgressEventType.Saving_Started); + return x; + } + + internal static SaveProgressEventArgs Completed(string archiveName) + { + var x = new SaveProgressEventArgs(archiveName, ZipProgressEventType.Saving_Completed); + return x; + } + + /// + /// Number of entries saved so far. + /// + public int EntriesSaved + { + get { return _entriesSaved; } + } + } + + + /// + /// Provides information about the progress of the extract operation. + /// + public class ExtractProgressEventArgs : ZipProgressEventArgs + { + private int _entriesExtracted; + private string _target; + + /// + /// Constructor for the ExtractProgressEventArgs. + /// + /// the name of the zip archive. + /// whether this is before saving the entry, or after + /// The total number of entries in the zip archive. + /// Number of entries that have been extracted. + /// The entry involved in the event. + /// The location to which entries are extracted. + internal ExtractProgressEventArgs(string archiveName, bool before, int entriesTotal, int entriesExtracted, ZipEntry entry, string extractLocation) + : base(archiveName, (before) ? ZipProgressEventType.Extracting_BeforeExtractEntry : ZipProgressEventType.Extracting_AfterExtractEntry) + { + this.EntriesTotal = entriesTotal; + this.CurrentEntry = entry; + this._entriesExtracted = entriesExtracted; + this._target = extractLocation; + } + + internal ExtractProgressEventArgs(string archiveName, ZipProgressEventType flavor) + : base(archiveName, flavor) + { } + + internal ExtractProgressEventArgs() + { } + + + internal static ExtractProgressEventArgs BeforeExtractEntry(string archiveName, ZipEntry entry, string extractLocation) + { + var x = new ExtractProgressEventArgs + { + ArchiveName = archiveName, + EventType = ZipProgressEventType.Extracting_BeforeExtractEntry, + CurrentEntry = entry, + _target = extractLocation, + }; + return x; + } + + internal static ExtractProgressEventArgs ExtractExisting(string archiveName, ZipEntry entry, string extractLocation) + { + var x = new ExtractProgressEventArgs + { + ArchiveName = archiveName, + EventType = ZipProgressEventType.Extracting_ExtractEntryWouldOverwrite, + CurrentEntry = entry, + _target = extractLocation, + }; + return x; + } + + internal static ExtractProgressEventArgs AfterExtractEntry(string archiveName, ZipEntry entry, string extractLocation) + { + var x = new ExtractProgressEventArgs + { + ArchiveName = archiveName, + EventType = ZipProgressEventType.Extracting_AfterExtractEntry, + CurrentEntry = entry, + _target = extractLocation, + }; + return x; + } + + internal static ExtractProgressEventArgs ExtractAllStarted(string archiveName, string extractLocation) + { + var x = new ExtractProgressEventArgs(archiveName, ZipProgressEventType.Extracting_BeforeExtractAll); + x._target = extractLocation; + return x; + } + + internal static ExtractProgressEventArgs ExtractAllCompleted(string archiveName, string extractLocation) + { + var x = new ExtractProgressEventArgs(archiveName, ZipProgressEventType.Extracting_AfterExtractAll); + x._target = extractLocation; + return x; + } + + + internal static ExtractProgressEventArgs ByteUpdate(string archiveName, ZipEntry entry, Int64 bytesWritten, Int64 totalBytes) + { + var x = new ExtractProgressEventArgs(archiveName, ZipProgressEventType.Extracting_EntryBytesWritten); + x.ArchiveName = archiveName; + x.CurrentEntry = entry; + x.BytesTransferred = bytesWritten; + x.TotalBytesToTransfer = totalBytes; + return x; + } + + + + /// + /// Number of entries extracted so far. This is set only if the + /// EventType is Extracting_BeforeExtractEntry or Extracting_AfterExtractEntry, and + /// the Extract() is occurring witin the scope of a call to ExtractAll(). + /// + public int EntriesExtracted + { + get { return _entriesExtracted; } + } + + /// + /// Returns the extraction target location, a filesystem path. + /// + public String ExtractLocation + { + get { return _target; } + } + + } + + + + /// + /// Provides information about the an error that occurred while zipping. + /// + public class ZipErrorEventArgs : ZipProgressEventArgs + { + private Exception _exc; + private ZipErrorEventArgs() { } + internal static ZipErrorEventArgs Saving(string archiveName, ZipEntry entry, Exception exception) + { + var x = new ZipErrorEventArgs + { + EventType = ZipProgressEventType.Error_Saving, + ArchiveName = archiveName, + CurrentEntry = entry, + _exc = exception + }; + return x; + } + + /// + /// Returns the exception that occurred, if any. + /// + public Exception @Exception + { + get { return _exc; } + } + + /// + /// Returns the name of the file that caused the exception, if any. + /// + public String FileName + { + get { return CurrentEntry.LocalFileName; } + } + } + + +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/Exceptions.cs b/Resources/Libraries/DotNetZip/Source/Zip/Exceptions.cs new file mode 100644 index 00000000..a42757e8 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/Exceptions.cs @@ -0,0 +1,300 @@ +// Exceptions.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2008, 2009 Dino Chiesa and Microsoft Corporation. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-12 12:19:10> +// +// ------------------------------------------------------------------ +// +// This module defines exceptions used in the class library. +// + + + +using System; +using System.Collections.Generic; +using System.Text; +#if !NETCF +using System.Runtime.Serialization; +#endif + +namespace Ionic.Zip +{ + ///// + ///// Base exception type for all custom exceptions in the Zip library. It acts as a marker class. + ///// + //[AttributeUsage(AttributeTargets.Class)] + //public class ZipExceptionAttribute : Attribute { } + + + + /// + /// Issued when an ZipEntry.ExtractWithPassword() method is invoked + /// with an incorrect password. + /// +#if !SILVERLIGHT + [Serializable] +#endif + [System.Runtime.InteropServices.GuidAttribute("ebc25cf6-9120-4283-b972-0e5520d0000B")] + public class BadPasswordException : ZipException + { + /// + /// Default ctor. + /// + public BadPasswordException() { } + + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The message in the exception. + public BadPasswordException(String message) + : base(message) + { } + + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The message in the exception. + /// The innerException for this exception. + public BadPasswordException(String message, Exception innerException) + : base(message, innerException) + { + } + + +#if ! (NETCF || SILVERLIGHT) + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The serialization info for the exception. + /// The streaming context from which to deserialize. + protected BadPasswordException(SerializationInfo info, StreamingContext context) + : base(info, context) + { } +#endif + + } + + /// + /// Indicates that a read was attempted on a stream, and bad or incomplete data was + /// received. + /// +#if !SILVERLIGHT + [Serializable] +#endif + [System.Runtime.InteropServices.GuidAttribute("ebc25cf6-9120-4283-b972-0e5520d0000A")] + public class BadReadException : ZipException + { + /// + /// Default ctor. + /// + public BadReadException() { } + + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The message in the exception. + public BadReadException(String message) + : base(message) + { } + + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The message in the exception. + /// The innerException for this exception. + public BadReadException(String message, Exception innerException) + : base(message, innerException) + { + } + +#if ! (NETCF || SILVERLIGHT) + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The serialization info for the exception. + /// The streaming context from which to deserialize. + protected BadReadException(SerializationInfo info, StreamingContext context) + : base(info, context) + { } +#endif + + } + + + + /// + /// Issued when an CRC check fails upon extracting an entry from a zip archive. + /// +#if !SILVERLIGHT + [Serializable] +#endif + [System.Runtime.InteropServices.GuidAttribute("ebc25cf6-9120-4283-b972-0e5520d00009")] + public class BadCrcException : ZipException + { + /// + /// Default ctor. + /// + public BadCrcException() { } + + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The message in the exception. + public BadCrcException(String message) + : base(message) + { } + + +#if ! (NETCF || SILVERLIGHT) + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The serialization info for the exception. + /// The streaming context from which to deserialize. + protected BadCrcException(SerializationInfo info, StreamingContext context) + : base(info, context) + { } +#endif + + } + + + /// + /// Issued when errors occur saving a self-extracting archive. + /// +#if !SILVERLIGHT + [Serializable] +#endif + [System.Runtime.InteropServices.GuidAttribute("ebc25cf6-9120-4283-b972-0e5520d00008")] + public class SfxGenerationException : ZipException + { + /// + /// Default ctor. + /// + public SfxGenerationException() { } + + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The message in the exception. + public SfxGenerationException(String message) + : base(message) + { } + +#if ! (NETCF || SILVERLIGHT) + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The serialization info for the exception. + /// The streaming context from which to deserialize. + protected SfxGenerationException(SerializationInfo info, StreamingContext context) + : base(info, context) + { } +#endif + + } + + + /// + /// Indicates that an operation was attempted on a ZipFile which was not possible + /// given the state of the instance. For example, if you call Save() on a ZipFile + /// which has no filename set, you can get this exception. + /// +#if !SILVERLIGHT + [Serializable] +#endif + [System.Runtime.InteropServices.GuidAttribute("ebc25cf6-9120-4283-b972-0e5520d00007")] + public class BadStateException : ZipException + { + /// + /// Default ctor. + /// + public BadStateException() { } + + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The message in the exception. + public BadStateException(String message) + : base(message) + { } + + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The message in the exception. + /// The innerException for this exception. + public BadStateException(String message, Exception innerException) + : base(message, innerException) + {} + +#if ! (NETCF || SILVERLIGHT) + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The serialization info for the exception. + /// The streaming context from which to deserialize. + protected BadStateException(SerializationInfo info, StreamingContext context) + : base(info, context) + { } +#endif + + } + + /// + /// Base class for all exceptions defined by and throw by the Zip library. + /// +#if !SILVERLIGHT + [Serializable] +#endif + [System.Runtime.InteropServices.GuidAttribute("ebc25cf6-9120-4283-b972-0e5520d00006")] + public class ZipException : Exception + { + /// + /// Default ctor. + /// + public ZipException() { } + + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The message in the exception. + public ZipException(String message) : base(message) { } + + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The message in the exception. + /// The innerException for this exception. + public ZipException(String message, Exception innerException) + : base(message, innerException) + { } + +#if ! (NETCF || SILVERLIGHT) + /// + /// Come on, you know how exceptions work. Why are you looking at this documentation? + /// + /// The serialization info for the exception. + /// The streaming context from which to deserialize. + protected ZipException(SerializationInfo info, StreamingContext context) + : base(info, context) + { } +#endif + + } + +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ExtractExistingFileAction.cs b/Resources/Libraries/DotNetZip/Source/Zip/ExtractExistingFileAction.cs new file mode 100644 index 00000000..01f3555b --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ExtractExistingFileAction.cs @@ -0,0 +1,85 @@ +// ExtractExistingFileAction.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2009-August-25 08:44:37> +// +// ------------------------------------------------------------------ +// +// This module defines the ExtractExistingFileAction enum +// +// +// ------------------------------------------------------------------ + + +namespace Ionic.Zip +{ + + /// + /// An enum for the options when extracting an entry would overwrite an existing file. + /// + /// + /// + /// + /// This enum describes the actions that the library can take when an + /// Extract() or ExtractWithPassword() method is called to extract an + /// entry to a filesystem, and the extraction would overwrite an existing filesystem + /// file. + /// + /// + /// + public enum ExtractExistingFileAction + { + /// + /// Throw an exception when extraction would overwrite an existing file. (For + /// COM clients, this is a 0 (zero).) + /// + Throw, + + /// + /// When extraction would overwrite an existing file, overwrite the file silently. + /// The overwrite will happen even if the target file is marked as read-only. + /// (For COM clients, this is a 1.) + /// + OverwriteSilently, + + /// + /// When extraction would overwrite an existing file, don't overwrite the file, silently. + /// (For COM clients, this is a 2.) + /// + DoNotOverwrite, + + /// + /// When extraction would overwrite an existing file, invoke the ExtractProgress + /// event, using an event type of . In + /// this way, the application can decide, just-in-time, whether to overwrite the + /// file. For example, a GUI application may wish to pop up a dialog to allow + /// the user to choose. You may want to examine the property before making + /// the decision. If, after your processing in the Extract progress event, you + /// want to NOT extract the file, set + /// on the ZipProgressEventArgs.CurrentEntry to DoNotOverwrite. + /// If you do want to extract the file, set ZipEntry.ExtractExistingFile + /// to OverwriteSilently. If you want to cancel the Extraction, set + /// ZipProgressEventArgs.Cancel to true. Cancelling differs from using + /// DoNotOverwrite in that a cancel will not extract any further entries, if + /// there are any. (For COM clients, the value of this enum is a 3.) + /// + InvokeExtractProgressEvent, + } + +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/FileSelector.cs b/Resources/Libraries/DotNetZip/Source/Zip/FileSelector.cs new file mode 100644 index 00000000..92555230 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/FileSelector.cs @@ -0,0 +1,1608 @@ +//#define SelectorTrace + +// FileSelector.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2008-2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved: <2011-August-05 11:03:11> +// +// ------------------------------------------------------------------ +// +// This module implements a "file selector" that finds files based on a +// set of inclusion criteria, including filename, size, file time, and +// potentially file attributes. The criteria are given in a string with +// a simple expression language. Examples: +// +// find all .txt files: +// name = *.txt +// +// shorthand for the above +// *.txt +// +// all files modified after January 1st, 2009 +// mtime > 2009-01-01 +// +// All .txt files modified after the first of the year +// name = *.txt AND mtime > 2009-01-01 +// +// All .txt files modified after the first of the year, or any file with the archive bit set +// (name = *.txt AND mtime > 2009-01-01) or (attribtues = A) +// +// All .txt files or any file greater than 1mb in size +// (name = *.txt or size > 1mb) +// +// and so on. +// ------------------------------------------------------------------ + + +using System; +using System.IO; +using System.Text; +using System.Reflection; +using System.ComponentModel; +using System.Text.RegularExpressions; +using System.Collections.Generic; +#if SILVERLIGHT +using System.Linq; +#endif + +namespace Ionic +{ + + /// + /// Enumerates the options for a logical conjunction. This enum is intended for use + /// internally by the FileSelector class. + /// + internal enum LogicalConjunction + { + NONE, + AND, + OR, + XOR, + } + + internal enum WhichTime + { + atime, + mtime, + ctime, + } + + + internal enum ComparisonOperator + { + [Description(">")] + GreaterThan, + [Description(">=")] + GreaterThanOrEqualTo, + [Description("<")] + LesserThan, + [Description("<=")] + LesserThanOrEqualTo, + [Description("=")] + EqualTo, + [Description("!=")] + NotEqualTo + } + + + internal abstract partial class SelectionCriterion + { + internal virtual bool Verbose + { + get;set; + } + internal abstract bool Evaluate(string filename); + + [System.Diagnostics.Conditional("SelectorTrace")] + protected static void CriterionTrace(string format, params object[] args) + { + //System.Console.WriteLine(" " + format, args); + } + } + + + internal partial class SizeCriterion : SelectionCriterion + { + internal ComparisonOperator Operator; + internal Int64 Size; + + public override String ToString() + { + StringBuilder sb = new StringBuilder(); + sb.Append("size ").Append(EnumUtil.GetDescription(Operator)).Append(" ").Append(Size.ToString()); + return sb.ToString(); + } + + internal override bool Evaluate(string filename) + { + System.IO.FileInfo fi = new System.IO.FileInfo(filename); + CriterionTrace("SizeCriterion::Evaluate('{0}' [{1}])", + filename, this.ToString()); + return _Evaluate(fi.Length); + } + + private bool _Evaluate(Int64 Length) + { + bool result = false; + switch (Operator) + { + case ComparisonOperator.GreaterThanOrEqualTo: + result = Length >= Size; + break; + case ComparisonOperator.GreaterThan: + result = Length > Size; + break; + case ComparisonOperator.LesserThanOrEqualTo: + result = Length <= Size; + break; + case ComparisonOperator.LesserThan: + result = Length < Size; + break; + case ComparisonOperator.EqualTo: + result = Length == Size; + break; + case ComparisonOperator.NotEqualTo: + result = Length != Size; + break; + default: + throw new ArgumentException("Operator"); + } + return result; + } + + } + + + + internal partial class TimeCriterion : SelectionCriterion + { + internal ComparisonOperator Operator; + internal WhichTime Which; + internal DateTime Time; + + public override String ToString() + { + StringBuilder sb = new StringBuilder(); + sb.Append(Which.ToString()).Append(" ").Append(EnumUtil.GetDescription(Operator)).Append(" ").Append(Time.ToString("yyyy-MM-dd-HH:mm:ss")); + return sb.ToString(); + } + + internal override bool Evaluate(string filename) + { + DateTime x; + switch (Which) + { + case WhichTime.atime: + x = System.IO.File.GetLastAccessTime(filename).ToUniversalTime(); + break; + case WhichTime.mtime: + x = System.IO.File.GetLastWriteTime(filename).ToUniversalTime(); + break; + case WhichTime.ctime: + x = System.IO.File.GetCreationTime(filename).ToUniversalTime(); + break; + default: + throw new ArgumentException("Operator"); + } + CriterionTrace("TimeCriterion({0},{1})= {2}", filename, Which.ToString(), x); + return _Evaluate(x); + } + + + private bool _Evaluate(DateTime x) + { + bool result = false; + switch (Operator) + { + case ComparisonOperator.GreaterThanOrEqualTo: + result = (x >= Time); + break; + case ComparisonOperator.GreaterThan: + result = (x > Time); + break; + case ComparisonOperator.LesserThanOrEqualTo: + result = (x <= Time); + break; + case ComparisonOperator.LesserThan: + result = (x < Time); + break; + case ComparisonOperator.EqualTo: + result = (x == Time); + break; + case ComparisonOperator.NotEqualTo: + result = (x != Time); + break; + default: + throw new ArgumentException("Operator"); + } + + CriterionTrace("TimeCriterion: {0}", result); + return result; + } + } + + + + internal partial class NameCriterion : SelectionCriterion + { + private Regex _re; + private String _regexString; + internal ComparisonOperator Operator; + private string _MatchingFileSpec; + internal virtual string MatchingFileSpec + { + set + { + // workitem 8245 + if (Directory.Exists(value)) + { + _MatchingFileSpec = ".\\" + value + "\\*.*"; + } + else + { + _MatchingFileSpec = value; + } + + _regexString = "^" + + Regex.Escape(_MatchingFileSpec) + .Replace(@"\\\*\.\*", @"\\([^\.]+|.*\.[^\\\.]*)") + .Replace(@"\.\*", @"\.[^\\\.]*") + .Replace(@"\*", @".*") + //.Replace(@"\*", @"[^\\\.]*") // ill-conceived + .Replace(@"\?", @"[^\\\.]") + + "$"; + + CriterionTrace("NameCriterion regexString({0})", _regexString); + + _re = new Regex(_regexString, RegexOptions.IgnoreCase); + } + } + + + public override String ToString() + { + StringBuilder sb = new StringBuilder(); + sb.Append("name ").Append(EnumUtil.GetDescription(Operator)) + .Append(" '") + .Append(_MatchingFileSpec) + .Append("'"); + return sb.ToString(); + } + + + internal override bool Evaluate(string filename) + { + CriterionTrace("NameCriterion::Evaluate('{0}' pattern[{1}])", + filename, _MatchingFileSpec); + return _Evaluate(filename); + } + + private bool _Evaluate(string fullpath) + { + CriterionTrace("NameCriterion::Evaluate({0})", fullpath); + // No slash in the pattern implicitly means recurse, which means compare to + // filename only, not full path. + String f = (_MatchingFileSpec.IndexOf('\\') == -1) + ? System.IO.Path.GetFileName(fullpath) + : fullpath; // compare to fullpath + + bool result = _re.IsMatch(f); + + if (Operator != ComparisonOperator.EqualTo) + result = !result; + return result; + } + } + + + internal partial class TypeCriterion : SelectionCriterion + { + private char ObjectType; // 'D' = Directory, 'F' = File + internal ComparisonOperator Operator; + internal string AttributeString + { + get + { + return ObjectType.ToString(); + } + set + { + if (value.Length != 1 || + (value[0]!='D' && value[0]!='F')) + throw new ArgumentException("Specify a single character: either D or F"); + ObjectType = value[0]; + } + } + + public override String ToString() + { + StringBuilder sb = new StringBuilder(); + sb.Append("type ").Append(EnumUtil.GetDescription(Operator)).Append(" ").Append(AttributeString); + return sb.ToString(); + } + + internal override bool Evaluate(string filename) + { + CriterionTrace("TypeCriterion::Evaluate({0})", filename); + + bool result = (ObjectType == 'D') + ? Directory.Exists(filename) + : File.Exists(filename); + + if (Operator != ComparisonOperator.EqualTo) + result = !result; + return result; + } + } + + +#if !SILVERLIGHT + internal partial class AttributesCriterion : SelectionCriterion + { + private FileAttributes _Attributes; + internal ComparisonOperator Operator; + internal string AttributeString + { + get + { + string result = ""; + if ((_Attributes & FileAttributes.Hidden) != 0) + result += "H"; + if ((_Attributes & FileAttributes.System) != 0) + result += "S"; + if ((_Attributes & FileAttributes.ReadOnly) != 0) + result += "R"; + if ((_Attributes & FileAttributes.Archive) != 0) + result += "A"; + if ((_Attributes & FileAttributes.ReparsePoint) != 0) + result += "L"; + if ((_Attributes & FileAttributes.NotContentIndexed) != 0) + result += "I"; + return result; + } + + set + { + _Attributes = FileAttributes.Normal; + foreach (char c in value.ToUpper()) + { + switch (c) + { + case 'H': + if ((_Attributes & FileAttributes.Hidden) != 0) + throw new ArgumentException(String.Format("Repeated flag. ({0})", c), "value"); + _Attributes |= FileAttributes.Hidden; + break; + + case 'R': + if ((_Attributes & FileAttributes.ReadOnly) != 0) + throw new ArgumentException(String.Format("Repeated flag. ({0})", c), "value"); + _Attributes |= FileAttributes.ReadOnly; + break; + + case 'S': + if ((_Attributes & FileAttributes.System) != 0) + throw new ArgumentException(String.Format("Repeated flag. ({0})", c), "value"); + _Attributes |= FileAttributes.System; + break; + + case 'A': + if ((_Attributes & FileAttributes.Archive) != 0) + throw new ArgumentException(String.Format("Repeated flag. ({0})", c), "value"); + _Attributes |= FileAttributes.Archive; + break; + + case 'I': + if ((_Attributes & FileAttributes.NotContentIndexed) != 0) + throw new ArgumentException(String.Format("Repeated flag. ({0})", c), "value"); + _Attributes |= FileAttributes.NotContentIndexed; + break; + + case 'L': + if ((_Attributes & FileAttributes.ReparsePoint) != 0) + throw new ArgumentException(String.Format("Repeated flag. ({0})", c), "value"); + _Attributes |= FileAttributes.ReparsePoint; + break; + + default: + throw new ArgumentException(value); + } + } + } + } + + + public override String ToString() + { + StringBuilder sb = new StringBuilder(); + sb.Append("attributes ").Append(EnumUtil.GetDescription(Operator)).Append(" ").Append(AttributeString); + return sb.ToString(); + } + + private bool _EvaluateOne(FileAttributes fileAttrs, FileAttributes criterionAttrs) + { + bool result = false; + if ((_Attributes & criterionAttrs) == criterionAttrs) + result = ((fileAttrs & criterionAttrs) == criterionAttrs); + else + result = true; + return result; + } + + + + internal override bool Evaluate(string filename) + { + // workitem 10191 + if (Directory.Exists(filename)) + { + // Directories don't have file attributes, so the result + // of an evaluation is always NO. This gets negated if + // the operator is NotEqualTo. + return (Operator != ComparisonOperator.EqualTo); + } +#if NETCF + FileAttributes fileAttrs = NetCfFile.GetAttributes(filename); +#else + FileAttributes fileAttrs = System.IO.File.GetAttributes(filename); +#endif + + return _Evaluate(fileAttrs); + } + + private bool _Evaluate(FileAttributes fileAttrs) + { + bool result = _EvaluateOne(fileAttrs, FileAttributes.Hidden); + if (result) + result = _EvaluateOne(fileAttrs, FileAttributes.System); + if (result) + result = _EvaluateOne(fileAttrs, FileAttributes.ReadOnly); + if (result) + result = _EvaluateOne(fileAttrs, FileAttributes.Archive); + if (result) + result = _EvaluateOne(fileAttrs, FileAttributes.NotContentIndexed); + if (result) + result = _EvaluateOne(fileAttrs, FileAttributes.ReparsePoint); + + if (Operator != ComparisonOperator.EqualTo) + result = !result; + + return result; + } + } +#endif + + + internal partial class CompoundCriterion : SelectionCriterion + { + internal LogicalConjunction Conjunction; + internal SelectionCriterion Left; + + private SelectionCriterion _Right; + internal SelectionCriterion Right + { + get { return _Right; } + set + { + _Right = value; + if (value == null) + Conjunction = LogicalConjunction.NONE; + else if (Conjunction == LogicalConjunction.NONE) + Conjunction = LogicalConjunction.AND; + } + } + + + internal override bool Evaluate(string filename) + { + bool result = Left.Evaluate(filename); + switch (Conjunction) + { + case LogicalConjunction.AND: + if (result) + result = Right.Evaluate(filename); + break; + case LogicalConjunction.OR: + if (!result) + result = Right.Evaluate(filename); + break; + case LogicalConjunction.XOR: + result ^= Right.Evaluate(filename); + break; + default: + throw new ArgumentException("Conjunction"); + } + return result; + } + + + public override String ToString() + { + StringBuilder sb = new StringBuilder(); + sb.Append("(") + .Append((Left != null) ? Left.ToString() : "null") + .Append(" ") + .Append(Conjunction.ToString()) + .Append(" ") + .Append((Right != null) ? Right.ToString() : "null") + .Append(")"); + return sb.ToString(); + } + } + + + + /// + /// FileSelector encapsulates logic that selects files from a source - a zip file + /// or the filesystem - based on a set of criteria. This class is used internally + /// by the DotNetZip library, in particular for the AddSelectedFiles() methods. + /// This class can also be used independently of the zip capability in DotNetZip. + /// + /// + /// + /// + /// + /// The FileSelector class is used internally by the ZipFile class for selecting + /// files for inclusion into the ZipFile, when the method, or one of + /// its overloads, is called. It's also used for the methods. Typically, an + /// application that creates or manipulates Zip archives will not directly + /// interact with the FileSelector class. + /// + /// + /// + /// Some applications may wish to use the FileSelector class directly, to + /// select files from disk volumes based on a set of criteria, without creating or + /// querying Zip archives. The file selection criteria include: a pattern to + /// match the filename; the last modified, created, or last accessed time of the + /// file; the size of the file; and the attributes of the file. + /// + /// + /// + /// Consult the documentation for + /// for more information on specifying the selection criteria. + /// + /// + /// + public partial class FileSelector + { + internal SelectionCriterion _Criterion; + +#if NOTUSED + /// + /// The default constructor. + /// + /// + /// Typically, applications won't use this constructor. Instead they'll + /// call the constructor that accepts a selectionCriteria string. If you + /// use this constructor, you'll want to set the SelectionCriteria + /// property on the instance before calling SelectFiles(). + /// + protected FileSelector() { } +#endif + /// + /// Constructor that allows the caller to specify file selection criteria. + /// + /// + /// + /// + /// This constructor allows the caller to specify a set of criteria for + /// selection of files. + /// + /// + /// + /// See for a description of + /// the syntax of the selectionCriteria string. + /// + /// + /// + /// By default the FileSelector will traverse NTFS Reparse Points. To + /// change this, use FileSelector(String, bool). + /// + /// + /// + /// The criteria for file selection. + public FileSelector(String selectionCriteria) + : this(selectionCriteria, true) + { + } + + /// + /// Constructor that allows the caller to specify file selection criteria. + /// + /// + /// + /// + /// This constructor allows the caller to specify a set of criteria for + /// selection of files. + /// + /// + /// + /// See for a description of + /// the syntax of the selectionCriteria string. + /// + /// + /// + /// The criteria for file selection. + /// + /// whether to traverse NTFS reparse points (junctions). + /// + public FileSelector(String selectionCriteria, bool traverseDirectoryReparsePoints) + { + if (!String.IsNullOrEmpty(selectionCriteria)) + _Criterion = _ParseCriterion(selectionCriteria); + TraverseReparsePoints = traverseDirectoryReparsePoints; + } + + + + /// + /// The string specifying which files to include when retrieving. + /// + /// + /// + /// + /// Specify the criteria in statements of 3 elements: a noun, an operator, + /// and a value. Consider the string "name != *.doc" . The noun is + /// "name". The operator is "!=", implying "Not Equal". The value is + /// "*.doc". That criterion, in English, says "all files with a name that + /// does not end in the .doc extension." + /// + /// + /// + /// Supported nouns include "name" (or "filename") for the filename; + /// "atime", "mtime", and "ctime" for last access time, last modfied time, + /// and created time of the file, respectively; "attributes" (or "attrs") + /// for the file attributes; "size" (or "length") for the file length + /// (uncompressed); and "type" for the type of object, either a file or a + /// directory. The "attributes", "type", and "name" nouns all support = + /// and != as operators. The "size", "atime", "mtime", and "ctime" nouns + /// support = and !=, and >, >=, <, <= as well. The times are + /// taken to be expressed in local time. + /// + /// + /// + /// Specify values for the file attributes as a string with one or more of + /// the characters H,R,S,A,I,L in any order, implying file attributes of + /// Hidden, ReadOnly, System, Archive, NotContextIndexed, and ReparsePoint + /// (symbolic link) respectively. + /// + /// + /// + /// To specify a time, use YYYY-MM-DD-HH:mm:ss or YYYY/MM/DD-HH:mm:ss as + /// the format. If you omit the HH:mm:ss portion, it is assumed to be + /// 00:00:00 (midnight). + /// + /// + /// + /// The value for a size criterion is expressed in integer quantities of + /// bytes, kilobytes (use k or kb after the number), megabytes (m or mb), + /// or gigabytes (g or gb). + /// + /// + /// + /// The value for a name is a pattern to match against the filename, + /// potentially including wildcards. The pattern follows CMD.exe glob + /// rules: * implies one or more of any character, while ? implies one + /// character. If the name pattern contains any slashes, it is matched to + /// the entire filename, including the path; otherwise, it is matched + /// against only the filename without the path. This means a pattern of + /// "*\*.*" matches all files one directory level deep, while a pattern of + /// "*.*" matches all files in all directories. + /// + /// + /// + /// To specify a name pattern that includes spaces, use single quotes + /// around the pattern. A pattern of "'* *.*'" will match all files that + /// have spaces in the filename. The full criteria string for that would + /// be "name = '* *.*'" . + /// + /// + /// + /// The value for a type criterion is either F (implying a file) or D + /// (implying a directory). + /// + /// + /// + /// Some examples: + /// + /// + /// + /// + /// criteria + /// Files retrieved + /// + /// + /// + /// name != *.xls + /// any file with an extension that is not .xls + /// + /// + /// + /// + /// name = *.mp3 + /// any file with a .mp3 extension. + /// + /// + /// + /// + /// *.mp3 + /// (same as above) any file with a .mp3 extension. + /// + /// + /// + /// + /// attributes = A + /// all files whose attributes include the Archive bit. + /// + /// + /// + /// + /// attributes != H + /// all files whose attributes do not include the Hidden bit. + /// + /// + /// + /// + /// mtime > 2009-01-01 + /// all files with a last modified time after January 1st, 2009. + /// + /// + /// + /// + /// ctime > 2009/01/01-03:00:00 + /// all files with a created time after 3am (local time), + /// on January 1st, 2009. + /// + /// + /// + /// + /// size > 2gb + /// all files whose uncompressed size is greater than 2gb. + /// + /// + /// + /// + /// type = D + /// all directories in the filesystem. + /// + /// + /// + /// + /// + /// You can combine criteria with the conjunctions AND, OR, and XOR. Using + /// a string like "name = *.txt AND size >= 100k" for the + /// selectionCriteria retrieves entries whose names end in .txt, and whose + /// uncompressed size is greater than or equal to 100 kilobytes. + /// + /// + /// + /// For more complex combinations of criteria, you can use parenthesis to + /// group clauses in the boolean logic. Absent parenthesis, the + /// precedence of the criterion atoms is determined by order of + /// appearance. Unlike the C# language, the AND conjunction does not take + /// precendence over the logical OR. This is important only in strings + /// that contain 3 or more criterion atoms. In other words, "name = *.txt + /// and size > 1000 or attributes = H" implies "((name = *.txt AND size + /// > 1000) OR attributes = H)" while "attributes = H OR name = *.txt + /// and size > 1000" evaluates to "((attributes = H OR name = *.txt) + /// AND size > 1000)". When in doubt, use parenthesis. + /// + /// + /// + /// Using time properties requires some extra care. If you want to + /// retrieve all entries that were last updated on 2009 February 14, + /// specify "mtime >= 2009-02-14 AND mtime < 2009-02-15". Read this + /// to say: all files updated after 12:00am on February 14th, until + /// 12:00am on February 15th. You can use the same bracketing approach to + /// specify any time period - a year, a month, a week, and so on. + /// + /// + /// + /// The syntax allows one special case: if you provide a string with no + /// spaces, it is treated as a pattern to match for the filename. + /// Therefore a string like "*.xls" will be equivalent to specifying "name + /// = *.xls". This "shorthand" notation does not work with compound + /// criteria. + /// + /// + /// + /// There is no logic in this class that insures that the inclusion + /// criteria are internally consistent. For example, it's possible to + /// specify criteria that says the file must have a size of less than 100 + /// bytes, as well as a size that is greater than 1000 bytes. Obviously + /// no file will ever satisfy such criteria, but this class does not check + /// for or detect such inconsistencies. + /// + /// + /// + /// + /// + /// Thrown in the setter if the value has an invalid syntax. + /// + public String SelectionCriteria + { + get + { + if (_Criterion == null) return null; + return _Criterion.ToString(); + } + set + { + if (value == null) _Criterion = null; + else if (value.Trim() == "") _Criterion = null; + else + _Criterion = _ParseCriterion(value); + } + } + + /// + /// Indicates whether searches will traverse NTFS reparse points, like Junctions. + /// + public bool TraverseReparsePoints + { + get; set; + } + + + private enum ParseState + { + Start, + OpenParen, + CriterionDone, + ConjunctionPending, + Whitespace, + } + + + private static class RegexAssertions + { + public static readonly String PrecededByOddNumberOfSingleQuotes = "(?<=(?:[^']*'[^']*')*'[^']*)"; + public static readonly String FollowedByOddNumberOfSingleQuotesAndLineEnd = "(?=[^']*'(?:[^']*'[^']*')*[^']*$)"; + + public static readonly String PrecededByEvenNumberOfSingleQuotes = "(?<=(?:[^']*'[^']*')*[^']*)"; + public static readonly String FollowedByEvenNumberOfSingleQuotesAndLineEnd = "(?=(?:[^']*'[^']*')*[^']*$)"; + } + + + private static string NormalizeCriteriaExpression(string source) + { + // The goal here is to normalize the criterion expression. At output, in + // the transformed criterion string, every significant syntactic element + // - a property element, grouping paren for the boolean logic, operator + // ( = < > != ), conjunction, or property value - will be separated from + // its neighbors by at least one space. Thus, + // + // before after + // ------------------------------------------------------------------- + // name=*.txt name = *.txt + // (size>100)AND(name=*.txt) ( size > 100 ) AND ( name = *.txt ) + // + // This is relatively straightforward using regular expression + // replacement. This method applies a distinct regex pattern and + // corresponding replacement string for each one of a number of cases: + // an open paren followed by a word; a word followed by a close-paren; a + // pair of open parens; a close paren followed by a word (which should + // then be followed by an open paren). And so on. These patterns and + // replacements are all stored in prPairs. By applying each of these + // regex replacements in turn, we get the transformed string. Easy. + // + // The resulting "normalized" criterion string, is then used as the + // subject that gets parsed, by splitting the string into tokens that + // are separated by spaces. Here, there's a twist. The spaces within + // single-quote delimiters do not delimit distinct tokens. So, this + // normalization method temporarily replaces those spaces with + // ASCII 6 (0x06), a control character which is not a legal + // character in a filename. The parsing logic that happens later will + // revert that change, restoring the original value of the filename + // specification. + // + // To illustrate, for a "before" string of [(size>100)AND(name='Name + // (with Parens).txt')] , the "after" string is [( size > 100 ) AND + // ( name = 'Name\u0006(with\u0006Parens).txt' )]. + // + + string[][] prPairs = + { + // A. opening double parens - insert a space between them + new string[] { @"([^']*)\(\(([^']+)", "$1( ($2" }, + + // B. closing double parens - insert a space between + new string[] { @"(.)\)\)", "$1) )" }, + + // C. single open paren with a following word - insert a space between + new string[] { @"\((\S)", "( $1" }, + + // D. single close paren with a preceding word - insert a space between the two + new string[] { @"(\S)\)", "$1 )" }, + + // E. close paren at line start?, insert a space before the close paren + // this seems like a degenerate case. I don't recall why it's here. + new string[] { @"^\)", " )" }, + + // F. a word (likely a conjunction) followed by an open paren - insert a space between + new string[] { @"(\S)\(", "$1 (" }, + + // G. single close paren followed by word - insert a paren after close paren + new string[] { @"\)(\S)", ") $1" }, + + // H. insert space between = and a following single quote + //new string[] { @"(=|!=)('[^']*')", "$1 $2" }, + new string[] { @"(=)('[^']*')", "$1 $2" }, + + // I. insert space between property names and the following operator + //new string[] { @"([^ ])([><(?:!=)=])", "$1 $2" }, + new string[] { @"([^ !><])(>|<|!=|=)", "$1 $2" }, + + // J. insert spaces between operators and the following values + //new string[] { @"([><(?:!=)=])([^ ])", "$1 $2" }, + new string[] { @"(>|<|!=|=)([^ =])", "$1 $2" }, + + // K. replace fwd slash with backslash + new string[] { @"/", "\\" }, + }; + + string interim = source; + + for (int i=0; i < prPairs.Length; i++) + { + //char caseIdx = (char)('A' + i); + string pattern = RegexAssertions.PrecededByEvenNumberOfSingleQuotes + + prPairs[i][0] + + RegexAssertions.FollowedByEvenNumberOfSingleQuotesAndLineEnd; + + interim = Regex.Replace(interim, pattern, prPairs[i][1]); + } + + // match a fwd slash, followed by an odd number of single quotes. + // This matches fwd slashes only inside a pair of single quote delimiters, + // eg, a filename. This must be done as well as the case above, to handle + // filenames specified inside quotes as well as filenames without quotes. + var regexPattern = @"/" + + RegexAssertions.FollowedByOddNumberOfSingleQuotesAndLineEnd; + // replace with backslash + interim = Regex.Replace(interim, regexPattern, "\\"); + + // match a space, followed by an odd number of single quotes. + // This matches spaces only inside a pair of single quote delimiters. + regexPattern = " " + + RegexAssertions.FollowedByOddNumberOfSingleQuotesAndLineEnd; + + // Replace all spaces that appear inside single quotes, with + // ascii 6. This allows a split on spaces to get tokens in + // the expression. The split will not split any filename or + // wildcard that appears within single quotes. After tokenizing, we + // need to replace ascii 6 with ascii 32 to revert the + // spaces within quotes. + return Regex.Replace(interim, regexPattern, "\u0006"); + } + + + private static SelectionCriterion _ParseCriterion(String s) + { + if (s == null) return null; + + // inject spaces after open paren and before close paren, etc + s = NormalizeCriteriaExpression(s); + + // no spaces in the criteria is shorthand for filename glob + if (s.IndexOf(" ") == -1) + s = "name = " + s; + + // split the expression into tokens + string[] tokens = s.Trim().Split(' ', '\t'); + + if (tokens.Length < 3) throw new ArgumentException(s); + + SelectionCriterion current = null; + + LogicalConjunction pendingConjunction = LogicalConjunction.NONE; + + ParseState state; + var stateStack = new System.Collections.Generic.Stack(); + var critStack = new System.Collections.Generic.Stack(); + stateStack.Push(ParseState.Start); + + for (int i = 0; i < tokens.Length; i++) + { + string tok1 = tokens[i].ToLower(); + switch (tok1) + { + case "and": + case "xor": + case "or": + state = stateStack.Peek(); + if (state != ParseState.CriterionDone) + throw new ArgumentException(String.Join(" ", tokens, i, tokens.Length - i)); + + if (tokens.Length <= i + 3) + throw new ArgumentException(String.Join(" ", tokens, i, tokens.Length - i)); + + pendingConjunction = (LogicalConjunction)Enum.Parse(typeof(LogicalConjunction), tokens[i].ToUpper(), true); + current = new CompoundCriterion { Left = current, Right = null, Conjunction = pendingConjunction }; + stateStack.Push(state); + stateStack.Push(ParseState.ConjunctionPending); + critStack.Push(current); + break; + + case "(": + state = stateStack.Peek(); + if (state != ParseState.Start && state != ParseState.ConjunctionPending && state != ParseState.OpenParen) + throw new ArgumentException(String.Join(" ", tokens, i, tokens.Length - i)); + + if (tokens.Length <= i + 4) + throw new ArgumentException(String.Join(" ", tokens, i, tokens.Length - i)); + + stateStack.Push(ParseState.OpenParen); + break; + + case ")": + state = stateStack.Pop(); + if (stateStack.Peek() != ParseState.OpenParen) + throw new ArgumentException(String.Join(" ", tokens, i, tokens.Length - i)); + + stateStack.Pop(); + stateStack.Push(ParseState.CriterionDone); + break; + + case "atime": + case "ctime": + case "mtime": + if (tokens.Length <= i + 2) + throw new ArgumentException(String.Join(" ", tokens, i, tokens.Length - i)); + + DateTime t; + try + { + t = DateTime.ParseExact(tokens[i + 2], "yyyy-MM-dd-HH:mm:ss", null); + } + catch (FormatException) + { + try + { + t = DateTime.ParseExact(tokens[i + 2], "yyyy/MM/dd-HH:mm:ss", null); + } + catch (FormatException) + { + try + { + t = DateTime.ParseExact(tokens[i + 2], "yyyy/MM/dd", null); + } + catch (FormatException) + { + try + { + t = DateTime.ParseExact(tokens[i + 2], "MM/dd/yyyy", null); + } + catch (FormatException) + { + t = DateTime.ParseExact(tokens[i + 2], "yyyy-MM-dd", null); + } + } + } + } + t= DateTime.SpecifyKind(t, DateTimeKind.Local).ToUniversalTime(); + current = new TimeCriterion + { + Which = (WhichTime)Enum.Parse(typeof(WhichTime), tokens[i], true), + Operator = (ComparisonOperator)EnumUtil.Parse(typeof(ComparisonOperator), tokens[i + 1]), + Time = t + }; + i += 2; + stateStack.Push(ParseState.CriterionDone); + break; + + + case "length": + case "size": + if (tokens.Length <= i + 2) + throw new ArgumentException(String.Join(" ", tokens, i, tokens.Length - i)); + + Int64 sz = 0; + string v = tokens[i + 2]; + if (v.ToUpper().EndsWith("K")) + sz = Int64.Parse(v.Substring(0, v.Length - 1)) * 1024; + else if (v.ToUpper().EndsWith("KB")) + sz = Int64.Parse(v.Substring(0, v.Length - 2)) * 1024; + else if (v.ToUpper().EndsWith("M")) + sz = Int64.Parse(v.Substring(0, v.Length - 1)) * 1024 * 1024; + else if (v.ToUpper().EndsWith("MB")) + sz = Int64.Parse(v.Substring(0, v.Length - 2)) * 1024 * 1024; + else if (v.ToUpper().EndsWith("G")) + sz = Int64.Parse(v.Substring(0, v.Length - 1)) * 1024 * 1024 * 1024; + else if (v.ToUpper().EndsWith("GB")) + sz = Int64.Parse(v.Substring(0, v.Length - 2)) * 1024 * 1024 * 1024; + else sz = Int64.Parse(tokens[i + 2]); + + current = new SizeCriterion + { + Size = sz, + Operator = (ComparisonOperator)EnumUtil.Parse(typeof(ComparisonOperator), tokens[i + 1]) + }; + i += 2; + stateStack.Push(ParseState.CriterionDone); + break; + + case "filename": + case "name": + { + if (tokens.Length <= i + 2) + throw new ArgumentException(String.Join(" ", tokens, i, tokens.Length - i)); + + ComparisonOperator c = + (ComparisonOperator)EnumUtil.Parse(typeof(ComparisonOperator), tokens[i + 1]); + + if (c != ComparisonOperator.NotEqualTo && c != ComparisonOperator.EqualTo) + throw new ArgumentException(String.Join(" ", tokens, i, tokens.Length - i)); + + string m = tokens[i + 2]; + + // handle single-quoted filespecs (used to include + // spaces in filename patterns) + if (m.StartsWith("'") && m.EndsWith("'")) + { + // trim off leading and trailing single quotes and + // revert the control characters to spaces. + m = m.Substring(1, m.Length - 2) + .Replace("\u0006", " "); + } + + // if (m.StartsWith("'")) + // m = m.Replace("\u0006", " "); + + current = new NameCriterion + { + MatchingFileSpec = m, + Operator = c + }; + i += 2; + stateStack.Push(ParseState.CriterionDone); + } + break; + +#if !SILVERLIGHT + case "attrs": + case "attributes": +#endif + case "type": + { + if (tokens.Length <= i + 2) + throw new ArgumentException(String.Join(" ", tokens, i, tokens.Length - i)); + + ComparisonOperator c = + (ComparisonOperator)EnumUtil.Parse(typeof(ComparisonOperator), tokens[i + 1]); + + if (c != ComparisonOperator.NotEqualTo && c != ComparisonOperator.EqualTo) + throw new ArgumentException(String.Join(" ", tokens, i, tokens.Length - i)); + +#if SILVERLIGHT + current = (SelectionCriterion) new TypeCriterion + { + AttributeString = tokens[i + 2], + Operator = c + }; +#else + current = (tok1 == "type") + ? (SelectionCriterion) new TypeCriterion + { + AttributeString = tokens[i + 2], + Operator = c + } + : (SelectionCriterion) new AttributesCriterion + { + AttributeString = tokens[i + 2], + Operator = c + }; +#endif + i += 2; + stateStack.Push(ParseState.CriterionDone); + } + break; + + case "": + // NOP + stateStack.Push(ParseState.Whitespace); + break; + + default: + throw new ArgumentException("'" + tokens[i] + "'"); + } + + state = stateStack.Peek(); + if (state == ParseState.CriterionDone) + { + stateStack.Pop(); + if (stateStack.Peek() == ParseState.ConjunctionPending) + { + while (stateStack.Peek() == ParseState.ConjunctionPending) + { + var cc = critStack.Pop() as CompoundCriterion; + cc.Right = current; + current = cc; // mark the parent as current (walk up the tree) + stateStack.Pop(); // the conjunction is no longer pending + + state = stateStack.Pop(); + if (state != ParseState.CriterionDone) + throw new ArgumentException("??"); + } + } + else stateStack.Push(ParseState.CriterionDone); // not sure? + } + + if (state == ParseState.Whitespace) + stateStack.Pop(); + } + + return current; + } + + + /// + /// Returns a string representation of the FileSelector object. + /// + /// The string representation of the boolean logic statement of the file + /// selection criteria for this instance. + public override String ToString() + { + return "FileSelector("+_Criterion.ToString()+")"; + } + + + private bool Evaluate(string filename) + { + // dinoch - Thu, 11 Feb 2010 18:34 + SelectorTrace("Evaluate({0})", filename); + bool result = _Criterion.Evaluate(filename); + return result; + } + + [System.Diagnostics.Conditional("SelectorTrace")] + private void SelectorTrace(string format, params object[] args) + { + if (_Criterion != null && _Criterion.Verbose) + System.Console.WriteLine(format, args); + } + + /// + /// Returns the names of the files in the specified directory + /// that fit the selection criteria specified in the FileSelector. + /// + /// + /// + /// This is equivalent to calling + /// with recurseDirectories = false. + /// + /// + /// + /// The name of the directory over which to apply the FileSelector + /// criteria. + /// + /// + /// + /// A collection of strings containing fully-qualified pathnames of files + /// that match the criteria specified in the FileSelector instance. + /// + public System.Collections.Generic.ICollection SelectFiles(String directory) + { + return SelectFiles(directory, false); + } + + + /// + /// Returns the names of the files in the specified directory that fit the + /// selection criteria specified in the FileSelector, optionally recursing + /// through subdirectories. + /// + /// + /// + /// This method applies the file selection criteria contained in the + /// FileSelector to the files contained in the given directory, and + /// returns the names of files that conform to the criteria. + /// + /// + /// + /// The name of the directory over which to apply the FileSelector + /// criteria. + /// + /// + /// + /// Whether to recurse through subdirectories when applying the file + /// selection criteria. + /// + /// + /// + /// A collection of strings containing fully-qualified pathnames of files + /// that match the criteria specified in the FileSelector instance. + /// + public System.Collections.ObjectModel.ReadOnlyCollection + SelectFiles(String directory, + bool recurseDirectories) + { + if (_Criterion == null) + throw new ArgumentException("SelectionCriteria has not been set"); + + var list = new List(); + try + { + if (Directory.Exists(directory)) + { + String[] filenames = Directory.GetFiles(directory); + + // add the files: + foreach (String filename in filenames) + { + if (Evaluate(filename)) + list.Add(filename); + } + + if (recurseDirectories) + { + // add the subdirectories: + String[] dirnames = Directory.GetDirectories(directory); + foreach (String dir in dirnames) + { + if (this.TraverseReparsePoints +#if !SILVERLIGHT + || ((File.GetAttributes(dir) & FileAttributes.ReparsePoint) == 0) +#endif + ) + { + // workitem 10191 + if (Evaluate(dir)) list.Add(dir); + list.AddRange(this.SelectFiles(dir, recurseDirectories)); + } + } + } + } + } + // can get System.UnauthorizedAccessException here + catch (System.UnauthorizedAccessException) + { + } + catch (System.IO.IOException) + { + } + + return list.AsReadOnly(); + } + } + + + + /// + /// Summary description for EnumUtil. + /// + internal sealed class EnumUtil + { + private EnumUtil() { } + /// + /// Returns the value of the DescriptionAttribute if the specified Enum + /// value has one. If not, returns the ToString() representation of the + /// Enum value. + /// + /// The Enum to get the description for + /// + internal static string GetDescription(System.Enum value) + { + FieldInfo fi = value.GetType().GetField(value.ToString()); + var attributes = (DescriptionAttribute[])fi.GetCustomAttributes(typeof(DescriptionAttribute), false); + if (attributes.Length > 0) + return attributes[0].Description; + else + return value.ToString(); + } + + /// + /// Converts the string representation of the name or numeric value of one + /// or more enumerated constants to an equivalent enumerated object. + /// Note: use the DescriptionAttribute on enum values to enable this. + /// + /// The System.Type of the enumeration. + /// + /// A string containing the name or value to convert. + /// + /// + internal static object Parse(Type enumType, string stringRepresentation) + { + return Parse(enumType, stringRepresentation, false); + } + + +#if SILVERLIGHT + public static System.Enum[] GetEnumValues(Type type) + { + if (!type.IsEnum) + throw new ArgumentException("not an enum"); + + return ( + from field in type.GetFields(BindingFlags.Public | BindingFlags.Static) + where field.IsLiteral + select (System.Enum)field.GetValue(null) + ).ToArray(); + } + + public static string[] GetEnumStrings() + { + var type = typeof(T); + if (!type.IsEnum) + throw new ArgumentException("not an enum"); + + return ( + from field in type.GetFields(BindingFlags.Public | BindingFlags.Static) + where field.IsLiteral + select field.Name + ).ToArray(); + } +#endif + + /// + /// Converts the string representation of the name or numeric value of one + /// or more enumerated constants to an equivalent enumerated object. A + /// parameter specified whether the operation is case-sensitive. Note: + /// use the DescriptionAttribute on enum values to enable this. + /// + /// The System.Type of the enumeration. + /// + /// A string containing the name or value to convert. + /// + /// + /// Whether the operation is case-sensitive or not. + /// + internal static object Parse(Type enumType, string stringRepresentation, bool ignoreCase) + { + if (ignoreCase) + stringRepresentation = stringRepresentation.ToLower(); + +#if SILVERLIGHT + foreach (System.Enum enumVal in GetEnumValues(enumType)) +#else + foreach (System.Enum enumVal in System.Enum.GetValues(enumType)) +#endif + { + string description = GetDescription(enumVal); + if (ignoreCase) + description = description.ToLower(); + if (description == stringRepresentation) + return enumVal; + } + + return System.Enum.Parse(enumType, stringRepresentation, ignoreCase); + } + } + + +#if DEMO + public class DemonstrateFileSelector + { + private string _directory; + private bool _recurse; + private bool _traverse; + private bool _verbose; + private string _selectionCriteria; + private FileSelector f; + + public DemonstrateFileSelector() + { + this._directory = "."; + this._recurse = true; + } + + public DemonstrateFileSelector(string[] args) : this() + { + for (int i = 0; i < args.Length; i++) + { + switch(args[i]) + { + case"-?": + Usage(); + Environment.Exit(0); + break; + case "-d": + i++; + if (args.Length <= i) + throw new ArgumentException("-directory"); + this._directory = args[i]; + break; + case "-norecurse": + this._recurse = false; + break; + + case "-j-": + this._traverse = false; + break; + + case "-j+": + this._traverse = true; + break; + + case "-v": + this._verbose = true; + break; + + default: + if (this._selectionCriteria != null) + throw new ArgumentException(args[i]); + this._selectionCriteria = args[i]; + break; + } + + if (this._selectionCriteria != null) + this.f = new FileSelector(this._selectionCriteria); + } + } + + + public static void Main(string[] args) + { + try + { + Console.WriteLine(); + new DemonstrateFileSelector(args).Run(); + } + catch (Exception exc1) + { + Console.WriteLine("Exception: {0}", exc1.ToString()); + Usage(); + } + } + + + public void Run() + { + if (this.f == null) + this.f = new FileSelector("name = *.jpg AND (size > 1000 OR atime < 2009-02-14-01:00:00)"); + + this.f.TraverseReparsePoints = _traverse; + this.f.Verbose = this._verbose; + Console.WriteLine(); + Console.WriteLine(new String(':', 88)); + Console.WriteLine("Selecting files:\n" + this.f.ToString()); + var files = this.f.SelectFiles(this._directory, this._recurse); + if (files.Count == 0) + { + Console.WriteLine("no files."); + } + else + { + Console.WriteLine("files: {0}", files.Count); + foreach (string file in files) + { + Console.WriteLine(" " + file); + } + } + } + + public static void Usage() + { + Console.WriteLine("FileSelector: select files based on selection criteria.\n"); + Console.WriteLine("Usage:\n FileSelector [options]\n" + + "\n" + + " -d directory to select from (Default .)\n" + + " -norecurse don't recurse into subdirs\n" + + " -j- don't traverse junctions\n" + + " -v verbose output\n"); + } + } + +#endif + + + +} + + diff --git a/Resources/Libraries/DotNetZip/Source/Zip/OffsetStream.cs b/Resources/Libraries/DotNetZip/Source/Zip/OffsetStream.cs new file mode 100644 index 00000000..8ae2811d --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/OffsetStream.cs @@ -0,0 +1,114 @@ +// OffsetStream.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2009-August-27 12:50:35> +// +// ------------------------------------------------------------------ +// +// This module defines logic for handling reading of zip archives embedded +// into larger streams. The initial position of the stream serves as +// the base offset for all future Seek() operations. +// +// ------------------------------------------------------------------ + + +using System; +using System.IO; + +namespace Ionic.Zip +{ + internal class OffsetStream : System.IO.Stream, System.IDisposable + { + private Int64 _originalPosition; + private Stream _innerStream; + + public OffsetStream(Stream s) + : base() + { + _originalPosition = s.Position; + _innerStream = s; + } + + public override int Read(byte[] buffer, int offset, int count) + { + return _innerStream.Read(buffer, offset, count); + } + + public override void Write(byte[] buffer, int offset, int count) + { + throw new NotImplementedException(); + } + + public override bool CanRead + { + get { return _innerStream.CanRead; } + } + + public override bool CanSeek + { + get { return _innerStream.CanSeek; } + } + + public override bool CanWrite + { + get { return false; } + } + + public override void Flush() + { + _innerStream.Flush(); + } + + public override long Length + { + get + { + return _innerStream.Length; + } + } + + public override long Position + { + get { return _innerStream.Position - _originalPosition; } + set { _innerStream.Position = _originalPosition + value; } + } + + + public override long Seek(long offset, System.IO.SeekOrigin origin) + { + return _innerStream.Seek(_originalPosition + offset, origin) - _originalPosition; + } + + + public override void SetLength(long value) + { + throw new NotImplementedException(); + } + + void IDisposable.Dispose() + { + Close(); + } + + public override void Close() + { + base.Close(); + } + + } + +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/Zip/Shared.cs b/Resources/Libraries/DotNetZip/Source/Zip/Shared.cs new file mode 100644 index 00000000..4b1854b6 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/Shared.cs @@ -0,0 +1,901 @@ +// Shared.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2006-2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// Last Saved: <2011-August-02 19:41:01> +// +// ------------------------------------------------------------------ +// +// This module defines some shared utility classes and methods. +// +// Created: Tue, 27 Mar 2007 15:30 +// + +using System; +using System.IO; +using System.Security.Permissions; + +namespace Ionic.Zip +{ + /// + /// Collects general purpose utility methods. + /// + internal static class SharedUtilities + { + /// private null constructor + //private SharedUtilities() { } + + // workitem 8423 + public static Int64 GetFileLength(string fileName) + { + if (!File.Exists(fileName)) + throw new System.IO.FileNotFoundException(fileName); + + long fileLength = 0L; + FileShare fs = FileShare.ReadWrite; +#if !NETCF + // FileShare.Delete is not defined for the Compact Framework + fs |= FileShare.Delete; +#endif + using (var s = File.Open(fileName, FileMode.Open, FileAccess.Read, fs)) + { + fileLength = s.Length; + } + return fileLength; + } + + + [System.Diagnostics.Conditional("NETCF")] + public static void Workaround_Ladybug318918(Stream s) + { + // This is a workaround for this issue: + // https://connect.microsoft.com/VisualStudio/feedback/details/318918 + // It's required only on NETCF. + s.Flush(); + } + + +#if LEGACY + /// + /// Round the given DateTime value to an even second value. + /// + /// + /// + /// + /// Round up in the case of an odd second value. The rounding does not consider + /// fractional seconds. + /// + /// + /// This is useful because the Zip spec allows storage of time only to the nearest + /// even second. So if you want to compare the time of an entry in the archive with + /// it's actual time in the filesystem, you need to round the actual filesystem + /// time, or use a 2-second threshold for the comparison. + /// + /// + /// This is most nautrally an extension method for the DateTime class but this + /// library is built for .NET 2.0, not for .NET 3.5; This means extension methods + /// are a no-no. + /// + /// + /// The DateTime value to round + /// The ruonded DateTime value + public static DateTime RoundToEvenSecond(DateTime source) + { + // round to nearest second: + if ((source.Second % 2) == 1) + source += new TimeSpan(0, 0, 1); + + DateTime dtRounded = new DateTime(source.Year, source.Month, source.Day, source.Hour, source.Minute, source.Second); + //if (source.Millisecond >= 500) dtRounded = dtRounded.AddSeconds(1); + return dtRounded; + } +#endif + +#if YOU_LIKE_REDUNDANT_CODE + internal static string NormalizePath(string path) + { + // remove leading single dot slash + if (path.StartsWith(".\\")) path = path.Substring(2); + + // remove intervening dot-slash + path = path.Replace("\\.\\", "\\"); + + // remove double dot when preceded by a directory name + var re = new System.Text.RegularExpressions.Regex(@"^(.*\\)?([^\\\.]+\\\.\.\\)(.+)$"); + path = re.Replace(path, "$1$3"); + return path; + } +#endif + + private static System.Text.RegularExpressions.Regex doubleDotRegex1 = + new System.Text.RegularExpressions.Regex(@"^(.*/)?([^/\\.]+/\\.\\./)(.+)$"); + + private static string SimplifyFwdSlashPath(string path) + { + if (path.StartsWith("./")) path = path.Substring(2); + path = path.Replace("/./", "/"); + + // Replace foo/anything/../bar with foo/bar + path = doubleDotRegex1.Replace(path, "$1$3"); + return path; + } + + + /// + /// Utility routine for transforming path names from filesystem format (on Windows that means backslashes) to + /// a format suitable for use within zipfiles. This means trimming the volume letter and colon (if any) And + /// swapping backslashes for forward slashes. + /// + /// source path. + /// transformed path + public static string NormalizePathForUseInZipFile(string pathName) + { + // boundary case + if (String.IsNullOrEmpty(pathName)) return pathName; + + // trim volume if necessary + if ((pathName.Length >= 2) && ((pathName[1] == ':') && (pathName[2] == '\\'))) + pathName = pathName.Substring(3); + + // swap slashes + pathName = pathName.Replace('\\', '/'); + + // trim all leading slashes + while (pathName.StartsWith("/")) pathName = pathName.Substring(1); + + return SimplifyFwdSlashPath(pathName); + } + + + static System.Text.Encoding ibm437 = System.Text.Encoding.GetEncoding("IBM437"); + static System.Text.Encoding utf8 = System.Text.Encoding.GetEncoding("UTF-8"); + + internal static byte[] StringToByteArray(string value, System.Text.Encoding encoding) + { + byte[] a = encoding.GetBytes(value); + return a; + } + internal static byte[] StringToByteArray(string value) + { + return StringToByteArray(value, ibm437); + } + + //internal static byte[] Utf8StringToByteArray(string value) + //{ + // return StringToByteArray(value, utf8); + //} + + //internal static string StringFromBuffer(byte[] buf, int maxlength) + //{ + // return StringFromBuffer(buf, maxlength, ibm437); + //} + + internal static string Utf8StringFromBuffer(byte[] buf) + { + return StringFromBuffer(buf, utf8); + } + + internal static string StringFromBuffer(byte[] buf, System.Text.Encoding encoding) + { + // this form of the GetString() method is required for .NET CF compatibility + string s = encoding.GetString(buf, 0, buf.Length); + return s; + } + + + internal static int ReadSignature(System.IO.Stream s) + { + int x = 0; + try { x = _ReadFourBytes(s, "n/a"); } + catch (BadReadException) { } + return x; + } + + + internal static int ReadEntrySignature(System.IO.Stream s) + { + // handle the case of ill-formatted zip archives - includes a data descriptor + // when none is expected. + int x = 0; + try + { + x = _ReadFourBytes(s, "n/a"); + if (x == ZipConstants.ZipEntryDataDescriptorSignature) + { + // advance past data descriptor - 12 bytes if not zip64 + s.Seek(12, SeekOrigin.Current); + // workitem 10178 + Workaround_Ladybug318918(s); + x = _ReadFourBytes(s, "n/a"); + if (x != ZipConstants.ZipEntrySignature) + { + // Maybe zip64 was in use for the prior entry. + // Therefore, skip another 8 bytes. + s.Seek(8, SeekOrigin.Current); + // workitem 10178 + Workaround_Ladybug318918(s); + x = _ReadFourBytes(s, "n/a"); + if (x != ZipConstants.ZipEntrySignature) + { + // seek back to the first spot + s.Seek(-24, SeekOrigin.Current); + // workitem 10178 + Workaround_Ladybug318918(s); + x = _ReadFourBytes(s, "n/a"); + } + } + } + } + catch (BadReadException) { } + return x; + } + + + internal static int ReadInt(System.IO.Stream s) + { + return _ReadFourBytes(s, "Could not read block - no data! (position 0x{0:X8})"); + } + + private static int _ReadFourBytes(System.IO.Stream s, string message) + { + int n = 0; + byte[] block = new byte[4]; +#if NETCF + // workitem 9181 + // Reading here in NETCF sometimes reads "backwards". Seems to happen for + // larger files. Not sure why. Maybe an error in caching. If the data is: + // + // 00100210: 9efa 0f00 7072 6f6a 6563 742e 6963 7750 ....project.icwP + // 00100220: 4b05 0600 0000 0006 0006 0091 0100 008e K............... + // 00100230: 0010 0000 00 ..... + // + // ...and the stream Position is 10021F, then a Read of 4 bytes is returning + // 50776369, instead of 06054b50. This seems to happen the 2nd time Read() + // is called from that Position.. + // + // submitted to connect.microsoft.com + // https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=318918#tabs + // + for (int i = 0; i < block.Length; i++) + { + n+= s.Read(block, i, 1); + } +#else + n = s.Read(block, 0, block.Length); +#endif + if (n != block.Length) throw new BadReadException(String.Format(message, s.Position)); + int data = unchecked((((block[3] * 256 + block[2]) * 256) + block[1]) * 256 + block[0]); + return data; + } + + + + /// + /// Finds a signature in the zip stream. This is useful for finding + /// the end of a zip entry, for example, or the beginning of the next ZipEntry. + /// + /// + /// + /// + /// Scans through 64k at a time. + /// + /// + /// + /// If the method fails to find the requested signature, the stream Position + /// after completion of this method is unchanged. If the method succeeds in + /// finding the requested signature, the stream position after completion is + /// direct AFTER the signature found in the stream. + /// + /// + /// + /// The stream to search + /// The 4-byte signature to find + /// The number of bytes read + internal static long FindSignature(System.IO.Stream stream, int SignatureToFind) + { + long startingPosition = stream.Position; + + int BATCH_SIZE = 65536; // 8192; + byte[] targetBytes = new byte[4]; + targetBytes[0] = (byte)(SignatureToFind >> 24); + targetBytes[1] = (byte)((SignatureToFind & 0x00FF0000) >> 16); + targetBytes[2] = (byte)((SignatureToFind & 0x0000FF00) >> 8); + targetBytes[3] = (byte)(SignatureToFind & 0x000000FF); + byte[] batch = new byte[BATCH_SIZE]; + int n = 0; + bool success = false; + do + { + n = stream.Read(batch, 0, batch.Length); + if (n != 0) + { + for (int i = 0; i < n; i++) + { + if (batch[i] == targetBytes[3]) + { + long curPosition = stream.Position; + stream.Seek(i - n, System.IO.SeekOrigin.Current); + // workitem 10178 + Workaround_Ladybug318918(stream); + + // workitem 7711 + int sig = ReadSignature(stream); + + success = (sig == SignatureToFind); + if (!success) + { + stream.Seek(curPosition, System.IO.SeekOrigin.Begin); + // workitem 10178 + Workaround_Ladybug318918(stream); + } + else + break; // out of for loop + } + } + } + else break; + if (success) break; + + } while (true); + + if (!success) + { + stream.Seek(startingPosition, System.IO.SeekOrigin.Begin); + // workitem 10178 + Workaround_Ladybug318918(stream); + return -1; // or throw? + } + + // subtract 4 for the signature. + long bytesRead = (stream.Position - startingPosition) - 4; + + return bytesRead; + } + + + // If I have a time in the .NET environment, and I want to use it for + // SetWastWriteTime() etc, then I need to adjust it for Win32. + internal static DateTime AdjustTime_Reverse(DateTime time) + { + if (time.Kind == DateTimeKind.Utc) return time; + DateTime adjusted = time; + if (DateTime.Now.IsDaylightSavingTime() && !time.IsDaylightSavingTime()) + adjusted = time - new System.TimeSpan(1, 0, 0); + + else if (!DateTime.Now.IsDaylightSavingTime() && time.IsDaylightSavingTime()) + adjusted = time + new System.TimeSpan(1, 0, 0); + + return adjusted; + } + +#if NECESSARY + // If I read a time from a file with GetLastWriteTime() (etc), I need + // to adjust it for display in the .NET environment. + internal static DateTime AdjustTime_Forward(DateTime time) + { + if (time.Kind == DateTimeKind.Utc) return time; + DateTime adjusted = time; + if (DateTime.Now.IsDaylightSavingTime() && !time.IsDaylightSavingTime()) + adjusted = time + new System.TimeSpan(1, 0, 0); + + else if (!DateTime.Now.IsDaylightSavingTime() && time.IsDaylightSavingTime()) + adjusted = time - new System.TimeSpan(1, 0, 0); + + return adjusted; + } +#endif + + + internal static DateTime PackedToDateTime(Int32 packedDateTime) + { + // workitem 7074 & workitem 7170 + if (packedDateTime == 0xFFFF || packedDateTime == 0) + return new System.DateTime(1995, 1, 1, 0, 0, 0, 0); // return a fixed date when none is supplied. + + Int16 packedTime = unchecked((Int16)(packedDateTime & 0x0000ffff)); + Int16 packedDate = unchecked((Int16)((packedDateTime & 0xffff0000) >> 16)); + + int year = 1980 + ((packedDate & 0xFE00) >> 9); + int month = (packedDate & 0x01E0) >> 5; + int day = packedDate & 0x001F; + + int hour = (packedTime & 0xF800) >> 11; + int minute = (packedTime & 0x07E0) >> 5; + //int second = packedTime & 0x001F; + int second = (packedTime & 0x001F) * 2; + + // validation and error checking. + // this is not foolproof but will catch most errors. + if (second >= 60) { minute++; second = 0; } + if (minute >= 60) { hour++; minute = 0; } + if (hour >= 24) { day++; hour = 0; } + + DateTime d = System.DateTime.Now; + bool success= false; + try + { + d = new System.DateTime(year, month, day, hour, minute, second, 0); + success= true; + } + catch (System.ArgumentOutOfRangeException) + { + if (year == 1980 && (month == 0 || day == 0)) + { + try + { + d = new System.DateTime(1980, 1, 1, hour, minute, second, 0); + success= true; + } + catch (System.ArgumentOutOfRangeException) + { + try + { + d = new System.DateTime(1980, 1, 1, 0, 0, 0, 0); + success= true; + } + catch (System.ArgumentOutOfRangeException) { } + + } + } + // workitem 8814 + // my god, I can't believe how many different ways applications + // can mess up a simple date format. + else + { + try + { + while (year < 1980) year++; + while (year > 2030) year--; + while (month < 1) month++; + while (month > 12) month--; + while (day < 1) day++; + while (day > 28) day--; + while (minute < 0) minute++; + while (minute > 59) minute--; + while (second < 0) second++; + while (second > 59) second--; + d = new System.DateTime(year, month, day, hour, minute, second, 0); + success= true; + } + catch (System.ArgumentOutOfRangeException) { } + } + } + if (!success) + { + string msg = String.Format("y({0}) m({1}) d({2}) h({3}) m({4}) s({5})", year, month, day, hour, minute, second); + throw new ZipException(String.Format("Bad date/time format in the zip file. ({0})", msg)); + + } + // workitem 6191 + //d = AdjustTime_Reverse(d); + d = DateTime.SpecifyKind(d, DateTimeKind.Local); + return d; + } + + + internal + static Int32 DateTimeToPacked(DateTime time) + { + // The time is passed in here only for purposes of writing LastModified to the + // zip archive. It should always be LocalTime, but we convert anyway. And, + // since the time is being written out, it needs to be adjusted. + + time = time.ToLocalTime(); + // workitem 7966 + //time = AdjustTime_Forward(time); + + // see http://www.vsft.com/hal/dostime.htm for the format + UInt16 packedDate = (UInt16)((time.Day & 0x0000001F) | ((time.Month << 5) & 0x000001E0) | (((time.Year - 1980) << 9) & 0x0000FE00)); + UInt16 packedTime = (UInt16)((time.Second / 2 & 0x0000001F) | ((time.Minute << 5) & 0x000007E0) | ((time.Hour << 11) & 0x0000F800)); + + Int32 result = (Int32)(((UInt32)(packedDate << 16)) | packedTime); + return result; + } + + + /// + /// Create a pseudo-random filename, suitable for use as a temporary + /// file, and open it. + /// + /// + /// + /// The System.IO.Path.GetRandomFileName() method is not available on + /// the Compact Framework, so this library provides its own substitute + /// on NETCF. + /// + /// + /// This method produces a filename of the form + /// DotNetZip-xxxxxxxx.tmp, where xxxxxxxx is replaced by randomly + /// chosen characters, and creates that file. + /// + /// + public static void CreateAndOpenUniqueTempFile(string dir, + out Stream fs, + out string filename) + { + // workitem 9763 + // http://dotnet.org.za/markn/archive/2006/04/15/51594.aspx + // try 3 times: + for (int i = 0; i < 3; i++) + { + try + { + filename = Path.Combine(dir, InternalGetTempFileName()); + fs = new FileStream(filename, FileMode.CreateNew); + return; + } + catch (IOException) + { + if (i == 2) throw; + } + } + throw new IOException(); + } + +#if NETCF || SILVERLIGHT + public static string InternalGetTempFileName() + { + return "DotNetZip-" + GenerateRandomStringImpl(8,0) + ".tmp"; + } + + internal static string GenerateRandomStringImpl(int length, int delta) + { + bool WantMixedCase = (delta == 0); + System.Random rnd = new System.Random(); + + string result = ""; + char[] a = new char[length]; + + for (int i = 0; i < length; i++) + { + // delta == 65 means uppercase + // delta == 97 means lowercase + if (WantMixedCase) + delta = (rnd.Next(2) == 0) ? 65 : 97; + a[i] = (char)(rnd.Next(26) + delta); + } + + result = new System.String(a); + return result; + } +#else + public static string InternalGetTempFileName() + { + return "DotNetZip-" + Path.GetRandomFileName().Substring(0, 8) + ".tmp"; + } + +#endif + + + /// + /// Workitem 7889: handle ERROR_LOCK_VIOLATION during read + /// + /// + /// This could be gracefully handled with an extension attribute, but + /// This assembly is built for .NET 2.0, so I cannot use them. + /// + internal static int ReadWithRetry(System.IO.Stream s, byte[] buffer, int offset, int count, string FileName) + { + int n = 0; + bool done = false; +#if !NETCF && !SILVERLIGHT + int retries = 0; +#endif + do + { + try + { + n = s.Read(buffer, offset, count); + done = true; + } +#if NETCF || SILVERLIGHT + catch (System.IO.IOException) + { + throw; + } +#else + catch (System.IO.IOException ioexc1) + { + // Check if we can call GetHRForException, + // which makes unmanaged code calls. + var p = new SecurityPermission(SecurityPermissionFlag.UnmanagedCode); + if (p.IsUnrestricted()) + { + uint hresult = _HRForException(ioexc1); + if (hresult != 0x80070021) // ERROR_LOCK_VIOLATION + throw new System.IO.IOException(String.Format("Cannot read file {0}", FileName), ioexc1); + retries++; + if (retries > 10) + throw new System.IO.IOException(String.Format("Cannot read file {0}, at offset 0x{1:X8} after 10 retries", FileName, offset), ioexc1); + + // max time waited on last retry = 250 + 10*550 = 5.75s + // aggregate time waited after 10 retries: 250 + 55*550 = 30.5s + System.Threading.Thread.Sleep(250 + retries * 550); + } + else + { + // The permission.Demand() failed. Therefore, we cannot call + // GetHRForException, and cannot do the subtle handling of + // ERROR_LOCK_VIOLATION. Just bail. + throw; + } + } +#endif + } + while (!done); + + return n; + } + + +#if !NETCF + // workitem 8009 + // + // This method must remain separate. + // + // Marshal.GetHRForException() is needed to do special exception handling for + // the read. But, that method requires UnmanagedCode permissions, and is marked + // with LinkDemand for UnmanagedCode. In an ASP.NET medium trust environment, + // where UnmanagedCode is restricted, will generate a SecurityException at the + // time of JIT of the method that calls a method that is marked with LinkDemand + // for UnmanagedCode. The SecurityException, if it is restricted, will occur + // when this method is JITed. + // + // The Marshal.GetHRForException() is factored out of ReadWithRetry in order to + // avoid the SecurityException at JIT compile time. Because _HRForException is + // called only when the UnmanagedCode is allowed. This means .NET never + // JIT-compiles this method when UnmanagedCode is disallowed, and thus never + // generates the JIT-compile time exception. + // +#endif + private static uint _HRForException(System.Exception ex1) + { + return unchecked((uint)System.Runtime.InteropServices.Marshal.GetHRForException(ex1)); + } + + } + + + + /// + /// A decorator stream. It wraps another stream, and performs bookkeeping + /// to keep track of the stream Position. + /// + /// + /// + /// In some cases, it is not possible to get the Position of a stream, let's + /// say, on a write-only output stream like ASP.NET's + /// Response.OutputStream, or on a different write-only stream + /// provided as the destination for the zip by the application. In this + /// case, programmers can use this counting stream to count the bytes read + /// or written. + /// + /// + /// Consider the scenario of an application that saves a self-extracting + /// archive (SFX), that uses a custom SFX stub. + /// + /// + /// Saving to a filesystem file, the application would open the + /// filesystem file (getting a FileStream), save the custom sfx stub + /// into it, and then call ZipFile.Save(), specifying the same + /// FileStream. ZipFile.Save() does the right thing for the zipentry + /// offsets, by inquiring the Position of the FileStream before writing + /// any data, and then adding that initial offset into any ZipEntry + /// offsets in the zip directory. Everything works fine. + /// + /// + /// Now suppose the application is an ASPNET application and it saves + /// directly to Response.OutputStream. It's not possible for DotNetZip to + /// inquire the Position, so the offsets for the SFX will be wrong. + /// + /// + /// The workaround is for the application to use this class to wrap + /// HttpResponse.OutputStream, then write the SFX stub and the ZipFile + /// into that wrapper stream. Because ZipFile.Save() can inquire the + /// Position, it will then do the right thing with the offsets. + /// + /// + public class CountingStream : System.IO.Stream + { + // workitem 12374: this class is now public + private System.IO.Stream _s; + private Int64 _bytesWritten; + private Int64 _bytesRead; + private Int64 _initialOffset; + + /// + /// The constructor. + /// + /// The underlying stream + public CountingStream(System.IO.Stream stream) + : base() + { + _s = stream; + try + { + _initialOffset = _s.Position; + } + catch + { + _initialOffset = 0L; + } + } + + /// + /// Gets the wrapped stream. + /// + public Stream WrappedStream + { + get + { + return _s; + } + } + + /// + /// The count of bytes written out to the stream. + /// + public Int64 BytesWritten + { + get { return _bytesWritten; } + } + + /// + /// the count of bytes that have been read from the stream. + /// + public Int64 BytesRead + { + get { return _bytesRead; } + } + + /// + /// Adjust the byte count on the stream. + /// + /// + /// + /// the number of bytes to subtract from the count. + /// + /// + /// + /// + /// Subtract delta from the count of bytes written to the stream. + /// This is necessary when seeking back, and writing additional data, + /// as happens in some cases when saving Zip files. + /// + /// + public void Adjust(Int64 delta) + { + _bytesWritten -= delta; + if (_bytesWritten < 0) + throw new InvalidOperationException(); + if (_s as CountingStream != null) + ((CountingStream)_s).Adjust(delta); + } + + /// + /// The read method. + /// + /// The buffer to hold the data read from the stream. + /// the offset within the buffer to copy the first byte read. + /// the number of bytes to read. + /// the number of bytes read, after decryption and decompression. + public override int Read(byte[] buffer, int offset, int count) + { + int n = _s.Read(buffer, offset, count); + _bytesRead += n; + return n; + } + + /// + /// Write data into the stream. + /// + /// The buffer holding data to write to the stream. + /// the offset within that data array to find the first byte to write. + /// the number of bytes to write. + public override void Write(byte[] buffer, int offset, int count) + { + if (count == 0) return; + _s.Write(buffer, offset, count); + _bytesWritten += count; + } + + /// + /// Whether the stream can be read. + /// + public override bool CanRead + { + get { return _s.CanRead; } + } + + /// + /// Whether it is possible to call Seek() on the stream. + /// + public override bool CanSeek + { + get { return _s.CanSeek; } + } + + /// + /// Whether it is possible to call Write() on the stream. + /// + public override bool CanWrite + { + get { return _s.CanWrite; } + } + + /// + /// Flushes the underlying stream. + /// + public override void Flush() + { + _s.Flush(); + } + + /// + /// The length of the underlying stream. + /// + public override long Length + { + get { return _s.Length; } // bytesWritten?? + } + + /// + /// Returns the sum of number of bytes written, plus the initial + /// offset before writing. + /// + public long ComputedPosition + { + get { return _initialOffset + _bytesWritten; } + } + + + /// + /// The Position of the stream. + /// + public override long Position + { + get { return _s.Position; } + set + { + _s.Seek(value, System.IO.SeekOrigin.Begin); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(_s); + } + } + + /// + /// Seek in the stream. + /// + /// the offset point to seek to + /// the reference point from which to seek + /// The new position + public override long Seek(long offset, System.IO.SeekOrigin origin) + { + return _s.Seek(offset, origin); + } + + /// + /// Set the length of the underlying stream. Be careful with this! + /// + /// + /// the length to set on the underlying stream. + public override void SetLength(long value) + { + _s.SetLength(value); + } + } + + +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/WinZipAes.cs b/Resources/Libraries/DotNetZip/Source/Zip/WinZipAes.cs new file mode 100644 index 00000000..0654742c --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/WinZipAes.cs @@ -0,0 +1,941 @@ +//#define Trace + +// WinZipAes.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009-2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-12 13:42:06> +// +// ------------------------------------------------------------------ +// +// This module defines the classes for dealing with WinZip's AES encryption, +// according to the specifications for the format available on WinZip's website. +// +// Created: January 2009 +// +// ------------------------------------------------------------------ + +using System; +using System.IO; +using System.Collections.Generic; +using System.Security.Cryptography; + +#if AESCRYPTO +namespace Ionic.Zip +{ + /// + /// This is a helper class supporting WinZip AES encryption. + /// This class is intended for use only by the DotNetZip library. + /// + /// + /// + /// Most uses of the DotNetZip library will not involve direct calls into + /// the WinZipAesCrypto class. Instead, the WinZipAesCrypto class is + /// instantiated and used by the ZipEntry() class when WinZip AES + /// encryption or decryption on an entry is employed. + /// + internal class WinZipAesCrypto + { + internal byte[] _Salt; + internal byte[] _providedPv; + internal byte[] _generatedPv; + internal int _KeyStrengthInBits; + private byte[] _MacInitializationVector; + private byte[] _StoredMac; + private byte[] _keyBytes; + private Int16 PasswordVerificationStored; + private Int16 PasswordVerificationGenerated; + private int Rfc2898KeygenIterations = 1000; + private string _Password; + private bool _cryptoGenerated ; + + private WinZipAesCrypto(string password, int KeyStrengthInBits) + { + _Password = password; + _KeyStrengthInBits = KeyStrengthInBits; + } + + public static WinZipAesCrypto Generate(string password, int KeyStrengthInBits) + { + WinZipAesCrypto c = new WinZipAesCrypto(password, KeyStrengthInBits); + + int saltSizeInBytes = c._KeyStrengthInBytes / 2; + c._Salt = new byte[saltSizeInBytes]; + Random rnd = new Random(); + rnd.NextBytes(c._Salt); + return c; + } + + + + public static WinZipAesCrypto ReadFromStream(string password, int KeyStrengthInBits, Stream s) + { + // from http://www.winzip.com/aes_info.htm + // + // Size(bytes) Content + // ----------------------------------- + // Variable Salt value + // 2 Password verification value + // Variable Encrypted file data + // 10 Authentication code + // + // ZipEntry.CompressedSize represents the size of all of those elements. + + // salt size varies with key length: + // 128 bit key => 8 bytes salt + // 192 bits => 12 bytes salt + // 256 bits => 16 bytes salt + + WinZipAesCrypto c = new WinZipAesCrypto(password, KeyStrengthInBits); + + int saltSizeInBytes = c._KeyStrengthInBytes / 2; + c._Salt = new byte[saltSizeInBytes]; + c._providedPv = new byte[2]; + + s.Read(c._Salt, 0, c._Salt.Length); + s.Read(c._providedPv, 0, c._providedPv.Length); + + c.PasswordVerificationStored = (Int16)(c._providedPv[0] + c._providedPv[1] * 256); + if (password != null) + { + c.PasswordVerificationGenerated = (Int16)(c.GeneratedPV[0] + c.GeneratedPV[1] * 256); + if (c.PasswordVerificationGenerated != c.PasswordVerificationStored) + throw new BadPasswordException("bad password"); + } + + return c; + } + + public byte[] GeneratedPV + { + get + { + if (!_cryptoGenerated) _GenerateCryptoBytes(); + return _generatedPv; + } + } + + + public byte[] Salt + { + get + { + return _Salt; + } + } + + + private int _KeyStrengthInBytes + { + get + { + return _KeyStrengthInBits / 8; + + } + } + + public int SizeOfEncryptionMetadata + { + get + { + // 10 bytes after, (n-10) before the compressed data + return _KeyStrengthInBytes / 2 + 10 + 2; + } + } + + public string Password + { + set + { + _Password = value; + if (_Password != null) + { + PasswordVerificationGenerated = (Int16)(GeneratedPV[0] + GeneratedPV[1] * 256); + if (PasswordVerificationGenerated != PasswordVerificationStored) + throw new Ionic.Zip.BadPasswordException(); + } + } + private get + { + return _Password; + } + } + + + private void _GenerateCryptoBytes() + { + //Console.WriteLine(" provided password: '{0}'", _Password); + + System.Security.Cryptography.Rfc2898DeriveBytes rfc2898 = + new System.Security.Cryptography.Rfc2898DeriveBytes(_Password, Salt, Rfc2898KeygenIterations); + + _keyBytes = rfc2898.GetBytes(_KeyStrengthInBytes); // 16 or 24 or 32 ??? + _MacInitializationVector = rfc2898.GetBytes(_KeyStrengthInBytes); + _generatedPv = rfc2898.GetBytes(2); + + _cryptoGenerated = true; + } + + + public byte[] KeyBytes + { + get + { + if (!_cryptoGenerated) _GenerateCryptoBytes(); + return _keyBytes; + } + } + + + public byte[] MacIv + { + get + { + if (!_cryptoGenerated) _GenerateCryptoBytes(); + return _MacInitializationVector; + } + } + + public byte[] CalculatedMac; + + + public void ReadAndVerifyMac(System.IO.Stream s) + { + bool invalid = false; + + // read integrityCheckVector. + // caller must ensure that the file pointer is in the right spot! + _StoredMac = new byte[10]; // aka "authentication code" + s.Read(_StoredMac, 0, _StoredMac.Length); + + if (_StoredMac.Length != CalculatedMac.Length) + invalid = true; + + if (!invalid) + { + for (int i = 0; i < _StoredMac.Length; i++) + { + if (_StoredMac[i] != CalculatedMac[i]) + invalid = true; + } + } + + if (invalid) + throw new Ionic.Zip.BadStateException("The MAC does not match."); + } + + } + + + #region DONT_COMPILE_BUT_KEEP_FOR_POTENTIAL_FUTURE_USE +#if NO + internal class Util + { + private static void _Format(System.Text.StringBuilder sb1, + byte[] b, + int offset, + int length) + { + + System.Text.StringBuilder sb2 = new System.Text.StringBuilder(); + sb1.Append("0000 "); + int i; + for (i = 0; i < length; i++) + { + int x = offset+i; + if (i != 0 && i % 16 == 0) + { + sb1.Append(" ") + .Append(sb2) + .Append("\n") + .Append(String.Format("{0:X4} ", i)); + sb2.Remove(0,sb2.Length); + } + sb1.Append(System.String.Format("{0:X2} ", b[x])); + if (b[x] >=32 && b[x] <= 126) + sb2.Append((char)b[x]); + else + sb2.Append("."); + } + if (sb2.Length > 0) + { + sb1.Append(new String(' ', ((16 - i%16) * 3) + 4)) + .Append(sb2); + } + } + + + + internal static string FormatByteArray(byte[] b, int limit) + { + System.Text.StringBuilder sb1 = new System.Text.StringBuilder(); + + if ((limit * 2 > b.Length) || limit == 0) + { + _Format(sb1, b, 0, b.Length); + } + else + { + // first N bytes of the buffer + _Format(sb1, b, 0, limit); + + if (b.Length > limit * 2) + sb1.Append(String.Format("\n ...({0} other bytes here)....\n", b.Length - limit * 2)); + + // last N bytes of the buffer + _Format(sb1, b, b.Length - limit, limit); + } + + return sb1.ToString(); + } + + + internal static string FormatByteArray(byte[] b) + { + return FormatByteArray(b, 0); + } + } + +#endif + #endregion + + + + + /// + /// A stream that encrypts as it writes, or decrypts as it reads. The + /// Crypto is AES in CTR (counter) mode, which is compatible with the AES + /// encryption employed by WinZip 12.0. + /// + /// + /// + /// The AES/CTR encryption protocol used by WinZip works like this: + /// + /// - start with a counter, initialized to zero. + /// + /// - to encrypt, take the data by 16-byte blocks. For each block: + /// - apply the transform to the counter + /// - increement the counter + /// - XOR the result of the transform with the plaintext to + /// get the ciphertext. + /// - compute the mac on the encrypted bytes + /// - when finished with all blocks, store the computed MAC. + /// + /// - to decrypt, take the data by 16-byte blocks. For each block: + /// - compute the mac on the encrypted bytes, + /// - apply the transform to the counter + /// - increement the counter + /// - XOR the result of the transform with the ciphertext to + /// get the plaintext. + /// - when finished with all blocks, compare the computed MAC against + /// the stored MAC + /// + /// + /// + // + internal class WinZipAesCipherStream : Stream + { + private WinZipAesCrypto _params; + private System.IO.Stream _s; + private CryptoMode _mode; + private int _nonce; + private bool _finalBlock; + + internal HMACSHA1 _mac; + + // Use RijndaelManaged from .NET 2.0. + // AesManaged came in .NET 3.5, but we want to limit + // dependency to .NET 2.0. AES is just a restricted form + // of Rijndael (fixed block size of 128, some crypto modes not supported). + + internal RijndaelManaged _aesCipher; + internal ICryptoTransform _xform; + + private const int BLOCK_SIZE_IN_BYTES = 16; + + private byte[] counter = new byte[BLOCK_SIZE_IN_BYTES]; + private byte[] counterOut = new byte[BLOCK_SIZE_IN_BYTES]; + + // I've had a problem when wrapping a WinZipAesCipherStream inside + // a DeflateStream. Calling Read() on the DeflateStream results in + // a Read() on the WinZipAesCipherStream, but the buffer is larger + // than the total size of the encrypted data, and larger than the + // initial Read() on the DeflateStream! When the encrypted + // bytestream is embedded within a larger stream (As in a zip + // archive), the Read() doesn't fail with EOF. This causes bad + // data to be returned, and it messes up the MAC. + + // This field is used to provide a hard-stop to the size of + // data that can be read from the stream. In Read(), if the buffer or + // read request goes beyond the stop, we truncate it. + + private long _length; + private long _totalBytesXferred; + private byte[] _PendingWriteBlock; + private int _pendingCount; + private byte[] _iobuf; + + /// + /// The constructor. + /// + /// The underlying stream + /// To either encrypt or decrypt. + /// The pre-initialized WinZipAesCrypto object. + /// The maximum number of bytes to read from the stream. + internal WinZipAesCipherStream(System.IO.Stream s, WinZipAesCrypto cryptoParams, long length, CryptoMode mode) + : this(s, cryptoParams, mode) + { + // don't read beyond this limit! + _length = length; + //Console.WriteLine("max length of AES stream: {0}", _length); + } + + +#if WANT_TRACE + Stream untransformed; + String traceFileUntransformed; + Stream transformed; + String traceFileTransformed; +#endif + + + internal WinZipAesCipherStream(System.IO.Stream s, WinZipAesCrypto cryptoParams, CryptoMode mode) + : base() + { + TraceOutput("-------------------------------------------------------"); + TraceOutput("Create {0:X8}", this.GetHashCode()); + + _params = cryptoParams; + _s = s; + _mode = mode; + _nonce = 1; + + if (_params == null) + throw new BadPasswordException("Supply a password to use AES encryption."); + + int keySizeInBits = _params.KeyBytes.Length * 8; + if (keySizeInBits != 256 && keySizeInBits != 128 && keySizeInBits != 192) + throw new ArgumentOutOfRangeException("keysize", + "size of key must be 128, 192, or 256"); + + _mac = new HMACSHA1(_params.MacIv); + + _aesCipher = new System.Security.Cryptography.RijndaelManaged(); + _aesCipher.BlockSize = 128; + _aesCipher.KeySize = keySizeInBits; // 128, 192, 256 + _aesCipher.Mode = CipherMode.ECB; + _aesCipher.Padding = PaddingMode.None; + + byte[] iv = new byte[BLOCK_SIZE_IN_BYTES]; // all zeroes + + // Create an ENCRYPTOR, regardless whether doing decryption or encryption. + // It is reflexive. + _xform = _aesCipher.CreateEncryptor(_params.KeyBytes, iv); + + if (_mode == CryptoMode.Encrypt) + { + _iobuf = new byte[2048]; + _PendingWriteBlock = new byte[BLOCK_SIZE_IN_BYTES]; + } + + +#if WANT_TRACE + traceFileUntransformed = "unpack\\WinZipAesCipherStream.trace.untransformed.out"; + traceFileTransformed = "unpack\\WinZipAesCipherStream.trace.transformed.out"; + + untransformed = System.IO.File.Create(traceFileUntransformed); + transformed = System.IO.File.Create(traceFileTransformed); +#endif + } + + private void XorInPlace(byte[] buffer, int offset, int count) + { + for (int i = 0; i < count; i++) + { + buffer[offset + i] = (byte)(counterOut[i] ^ buffer[offset + i]); + } + } + + private void WriteTransformOneBlock(byte[] buffer, int offset) + { + System.Array.Copy(BitConverter.GetBytes(_nonce++), 0, counter, 0, 4); + _xform.TransformBlock(counter, + 0, + BLOCK_SIZE_IN_BYTES, + counterOut, + 0); + XorInPlace(buffer, offset, BLOCK_SIZE_IN_BYTES); + _mac.TransformBlock(buffer, offset, BLOCK_SIZE_IN_BYTES, null, 0); + } + + + private void WriteTransformBlocks(byte[] buffer, int offset, int count) + { + int posn = offset; + int last = count + offset; + + while (posn < buffer.Length && posn < last) + { + WriteTransformOneBlock (buffer, posn); + posn += BLOCK_SIZE_IN_BYTES; + } + } + + + private void WriteTransformFinalBlock() + { + if (_pendingCount == 0) + throw new InvalidOperationException("No bytes available."); + + if (_finalBlock) + throw new InvalidOperationException("The final block has already been transformed."); + + System.Array.Copy(BitConverter.GetBytes(_nonce++), 0, counter, 0, 4); + counterOut = _xform.TransformFinalBlock(counter, + 0, + BLOCK_SIZE_IN_BYTES); + XorInPlace(_PendingWriteBlock, 0, _pendingCount); + _mac.TransformFinalBlock(_PendingWriteBlock, 0, _pendingCount); + _finalBlock = true; + } + + + + + + private int ReadTransformOneBlock(byte[] buffer, int offset, int last) + { + if (_finalBlock) + throw new NotSupportedException(); + + int bytesRemaining = last - offset; + int bytesToRead = (bytesRemaining > BLOCK_SIZE_IN_BYTES) + ? BLOCK_SIZE_IN_BYTES + : bytesRemaining; + + // update the counter + System.Array.Copy(BitConverter.GetBytes(_nonce++), 0, counter, 0, 4); + + // Determine if this is the final block + if ((bytesToRead == bytesRemaining) && + (_length > 0) && + (_totalBytesXferred + last == _length)) + { + _mac.TransformFinalBlock(buffer, offset, bytesToRead); + counterOut = _xform.TransformFinalBlock(counter, + 0, + BLOCK_SIZE_IN_BYTES); + _finalBlock = true; + } + else + { + _mac.TransformBlock(buffer, offset, bytesToRead, null, 0); + _xform.TransformBlock(counter, + 0, // offset + BLOCK_SIZE_IN_BYTES, + counterOut, + 0); // offset + } + + XorInPlace(buffer, offset, bytesToRead); + return bytesToRead; + } + + + + private void ReadTransformBlocks(byte[] buffer, int offset, int count) + { + int posn = offset; + int last = count + offset; + + while (posn < buffer.Length && posn < last ) + { + int n = ReadTransformOneBlock (buffer, posn, last); + posn += n; + } + } + + + + public override int Read(byte[] buffer, int offset, int count) + { + if (_mode == CryptoMode.Encrypt) + throw new NotSupportedException(); + + if (buffer == null) + throw new ArgumentNullException("buffer"); + + if (offset < 0) + throw new ArgumentOutOfRangeException("offset", + "Must not be less than zero."); + if (count < 0) + throw new ArgumentOutOfRangeException("count", + "Must not be less than zero."); + + if (buffer.Length < offset + count) + throw new ArgumentException("The buffer is too small"); + + // When I wrap a WinZipAesStream in a DeflateStream, the + // DeflateStream asks its captive to read 4k blocks, even if the + // encrypted bytestream is smaller than that. This is a way to + // limit the number of bytes read. + + int bytesToRead = count; + + if (_totalBytesXferred >= _length) + { + return 0; // EOF + } + + long bytesRemaining = _length - _totalBytesXferred; + if (bytesRemaining < count) bytesToRead = (int)bytesRemaining; + + int n = _s.Read(buffer, offset, bytesToRead); + + +#if WANT_TRACE + untransformed.Write(buffer, offset, bytesToRead); +#endif + + ReadTransformBlocks(buffer, offset, bytesToRead); + +#if WANT_TRACE + transformed.Write(buffer, offset, bytesToRead); +#endif + _totalBytesXferred += n; + return n; + } + + + + /// + /// Returns the final HMAC-SHA1-80 for the data that was encrypted. + /// + public byte[] FinalAuthentication + { + get + { + if (!_finalBlock) + { + // special-case zero-byte files + if ( _totalBytesXferred != 0) + throw new BadStateException("The final hash has not been computed."); + + // Must call ComputeHash on an empty byte array when no data + // has run through the MAC. + + byte[] b = { }; + _mac.ComputeHash(b); + // fall through + } + byte[] macBytes10 = new byte[10]; + System.Array.Copy(_mac.Hash, 0, macBytes10, 0, 10); + return macBytes10; + } + } + + + public override void Write(byte[] buffer, int offset, int count) + { + if (_finalBlock) + throw new InvalidOperationException("The final block has already been transformed."); + + if (_mode == CryptoMode.Decrypt) + throw new NotSupportedException(); + + if (buffer == null) + throw new ArgumentNullException("buffer"); + + if (offset < 0) + throw new ArgumentOutOfRangeException("offset", + "Must not be less than zero."); + if (count < 0) + throw new ArgumentOutOfRangeException("count", + "Must not be less than zero."); + if (buffer.Length < offset + count) + throw new ArgumentException("The offset and count are too large"); + + if (count == 0) + return; + + TraceOutput("Write off({0}) count({1})", offset, count); + +#if WANT_TRACE + untransformed.Write(buffer, offset, count); +#endif + + // For proper AES encryption, an AES encryptor application calls + // TransformBlock repeatedly for all 16-byte blocks except the + // last. For the last block, it then calls TransformFinalBlock(). + // + // This class is a stream that encrypts via Write(). But, it's not + // possible to recognize which are the "last" bytes from within the call + // to Write(). The caller can call Write() several times in succession, + // with varying buffers. This class only "knows" that the last bytes + // have been written when the app calls Close(). + // + // Therefore, this class buffers writes: After completion every Write(), + // a 16-byte "pending" block (_PendingWriteBlock) must hold between 1 + // and 16 bytes, which will be used in TransformFinalBlock if the app + // calls Close() immediately thereafter. Also, every write must + // transform any pending bytes, before transforming the data passed in + // to the current call. + // + // In operation, after the first call to Write() and before the call to + // Close(), one full or partial block of bytes is always available, + // pending. At time of Close(), this class calls + // WriteTransformFinalBlock() to flush the pending bytes. + // + // This approach works whether the caller writes in odd-sized batches, + // for example 5000 bytes, or in batches that are neat multiples of the + // blocksize (16). + // + // Logicaly, what we do is this: + // + // 1. if there are fewer than 16 bytes (pending + current), then + // just copy them into th pending buffer and return. + // + // 2. there are more than 16 bytes to write. So, take the leading slice + // of bytes from the current buffer, enough to fill the pending + // buffer. Transform the pending block, and write it out. + // + // 3. Take the trailing slice of bytes (a full block or a partial block), + // and copy it to the pending block for next time. + // + // 4. transform and write all the other blocks, the middle slice. + // + + // There are 16 or fewer bytes, so just buffer the bytes. + if (count + _pendingCount <= BLOCK_SIZE_IN_BYTES) + { + Buffer.BlockCopy(buffer, + offset, + _PendingWriteBlock, + _pendingCount, + count); + _pendingCount += count; + + // At this point, _PendingWriteBlock contains up to + // BLOCK_SIZE_IN_BYTES bytes, and _pendingCount ranges from 0 to + // BLOCK_SIZE_IN_BYTES. We don't want to xform+write them yet, + // because this may have been the last block. The last block gets + // written at Close(). + return; + } + + // We know there are at least 17 bytes, counting those in the current + // buffer, along with the (possibly empty) pending block. + + int bytesRemaining = count; + int curOffset = offset; + + // workitem 12815 + // + // xform chunkwise ... Cannot transform in place using the original + // buffer because that is user-maintained. + + if (_pendingCount != 0) + { + // We have more than one block of data to write, therefore it is safe + // to xform+write. + int fillCount = BLOCK_SIZE_IN_BYTES - _pendingCount; + + // fillCount is possibly zero here. That happens when the pending + // buffer held 16 bytes (one complete block) before this call to + // Write. + if (fillCount > 0) + { + Buffer.BlockCopy(buffer, + offset, + _PendingWriteBlock, + _pendingCount, + fillCount); + + // adjust counts: + bytesRemaining -= fillCount; + curOffset += fillCount; + } + + // xform and write: + WriteTransformOneBlock(_PendingWriteBlock, 0); + _s.Write(_PendingWriteBlock, 0, BLOCK_SIZE_IN_BYTES); + _totalBytesXferred += BLOCK_SIZE_IN_BYTES; + _pendingCount = 0; + } + + // At this point _PendingWriteBlock is empty, and bytesRemaining is + // always greater than 0. + + // Now, xform N blocks, where N = floor((bytesRemaining-1)/16). If + // writing 32 bytes, then xform 1 block, and stage the remaining 16. If + // writing 10037 bytes, xform 627 blocks of 16 bytes, then stage the + // remaining 5 bytes. + + int blocksToXform = (bytesRemaining-1)/BLOCK_SIZE_IN_BYTES; + _pendingCount = bytesRemaining - (blocksToXform * BLOCK_SIZE_IN_BYTES); + + // _pendingCount is ALWAYS between 1 and 16. + // Put the last _pendingCount bytes into the pending block. + Buffer.BlockCopy(buffer, + curOffset + bytesRemaining - _pendingCount, + _PendingWriteBlock, + 0, + _pendingCount); + bytesRemaining -= _pendingCount; + _totalBytesXferred += bytesRemaining; // will be true after the loop + + // now, transform all the full blocks preceding that. + // bytesRemaining is always a multiple of 16 . + if (blocksToXform > 0) + { + do + { + int c = _iobuf.Length; + if (c > bytesRemaining) c = bytesRemaining; + Buffer.BlockCopy(buffer, + curOffset, + _iobuf, + 0, + c); + + WriteTransformBlocks(_iobuf, 0, c); + _s.Write(_iobuf, 0, c); + bytesRemaining -= c; + curOffset += c; + } while(bytesRemaining > 0); + } + } + + + + /// + /// Close the stream. + /// + public override void Close() + { + TraceOutput("Close {0:X8}", this.GetHashCode()); + + // In the degenerate case, no bytes have been written to the + // stream at all. Need to check here, and NOT emit the + // final block if Write has not been called. + if (_pendingCount > 0) + { + WriteTransformFinalBlock(); + _s.Write(_PendingWriteBlock, 0, _pendingCount); + _totalBytesXferred += _pendingCount; + _pendingCount = 0; + } + _s.Close(); + +#if WANT_TRACE + untransformed.Close(); + transformed.Close(); + Console.WriteLine("\nuntransformed bytestream is in {0}", traceFileUntransformed); + Console.WriteLine("\ntransformed bytestream is in {0}", traceFileTransformed); +#endif + TraceOutput("-------------------------------------------------------"); + } + + + /// + /// Returns true if the stream can be read. + /// + public override bool CanRead + { + get + { + if (_mode != CryptoMode.Decrypt) return false; + return true; + } + } + + + /// + /// Always returns false. + /// + public override bool CanSeek + { + get { return false; } + } + + /// + /// Returns true if the CryptoMode is Encrypt. + /// + public override bool CanWrite + { + get { return (_mode == CryptoMode.Encrypt); } + } + + /// + /// Flush the content in the stream. + /// + public override void Flush() + { + _s.Flush(); + } + + /// + /// Getting this property throws a NotImplementedException. + /// + public override long Length + { + get { throw new NotImplementedException(); } + } + + /// + /// Getting or Setting this property throws a NotImplementedException. + /// + public override long Position + { + get { throw new NotImplementedException(); } + set { throw new NotImplementedException(); } + } + + /// + /// This method throws a NotImplementedException. + /// + public override long Seek(long offset, System.IO.SeekOrigin origin) + { + throw new NotImplementedException(); + } + + /// + /// This method throws a NotImplementedException. + /// + public override void SetLength(long value) + { + throw new NotImplementedException(); + } + + + + [System.Diagnostics.ConditionalAttribute("Trace")] + private void TraceOutput(string format, params object[] varParams) + { + lock(_outputLock) + { + int tid = System.Threading.Thread.CurrentThread.GetHashCode(); + Console.ForegroundColor = (ConsoleColor) (tid % 8 + 8); + Console.Write("{0:000} WZACS ", tid); + Console.WriteLine(format, varParams); + Console.ResetColor(); + } + } + + private object _outputLock = new Object(); + } +} +#endif diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipConstants.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipConstants.cs new file mode 100644 index 00000000..d958d316 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipConstants.cs @@ -0,0 +1,51 @@ +// ZipConstants.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2006, 2007, 2008, 2009 Dino Chiesa and Microsoft Corporation. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2009-August-27 23:22:32> +// +// ------------------------------------------------------------------ +// +// This module defines a few constants that are used in the project. +// +// ------------------------------------------------------------------ + +using System; + +namespace Ionic.Zip +{ + static class ZipConstants + { + public const UInt32 PackedToRemovableMedia = 0x30304b50; + public const UInt32 Zip64EndOfCentralDirectoryRecordSignature = 0x06064b50; + public const UInt32 Zip64EndOfCentralDirectoryLocatorSignature = 0x07064b50; + public const UInt32 EndOfCentralDirectorySignature = 0x06054b50; + public const int ZipEntrySignature = 0x04034b50; + public const int ZipEntryDataDescriptorSignature = 0x08074b50; + public const int SplitArchiveSignature = 0x08074b50; + public const int ZipDirEntrySignature = 0x02014b50; + + + // These are dictated by the Zip Spec.See APPNOTE.txt + public const int AesKeySize = 192; // 128, 192, 256 + public const int AesBlockSize = 128; // ??? + + public const UInt16 AesAlgId128 = 0x660E; + public const UInt16 AesAlgId192 = 0x660F; + public const UInt16 AesAlgId256 = 0x6610; + + } +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipCrypto.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipCrypto.cs new file mode 100644 index 00000000..7f94e455 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipCrypto.cs @@ -0,0 +1,455 @@ +// ZipCrypto.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2008, 2009, 2011 Dino Chiesa +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-28 06:30:59> +// +// ------------------------------------------------------------------ +// +// This module provides the implementation for "traditional" Zip encryption. +// +// Created Tue Apr 15 17:39:56 2008 +// +// ------------------------------------------------------------------ + +using System; + +namespace Ionic.Zip +{ + /// + /// This class implements the "traditional" or "classic" PKZip encryption, + /// which today is considered to be weak. On the other hand it is + /// ubiquitous. This class is intended for use only by the DotNetZip + /// library. + /// + /// + /// + /// Most uses of the DotNetZip library will not involve direct calls into + /// the ZipCrypto class. Instead, the ZipCrypto class is instantiated and + /// used by the ZipEntry() class when encryption or decryption on an entry + /// is employed. If for some reason you really wanted to use a weak + /// encryption algorithm in some other application, you might use this + /// library. But you would be much better off using one of the built-in + /// strong encryption libraries in the .NET Framework, like the AES + /// algorithm or SHA. + /// + internal class ZipCrypto + { + /// + /// The default constructor for ZipCrypto. + /// + /// + /// + /// This class is intended for internal use by the library only. It's + /// probably not useful to you. Seriously. Stop reading this + /// documentation. It's a waste of your time. Go do something else. + /// Check the football scores. Go get an ice cream with a friend. + /// Seriously. + /// + /// + private ZipCrypto() { } + + public static ZipCrypto ForWrite(string password) + { + ZipCrypto z = new ZipCrypto(); + if (password == null) + throw new BadPasswordException("This entry requires a password."); + z.InitCipher(password); + return z; + } + + + public static ZipCrypto ForRead(string password, ZipEntry e) + { + System.IO.Stream s = e._archiveStream; + e._WeakEncryptionHeader = new byte[12]; + byte[] eh = e._WeakEncryptionHeader; + ZipCrypto z = new ZipCrypto(); + + if (password == null) + throw new BadPasswordException("This entry requires a password."); + + z.InitCipher(password); + + ZipEntry.ReadWeakEncryptionHeader(s, eh); + + // Decrypt the header. This has a side effect of "further initializing the + // encryption keys" in the traditional zip encryption. + byte[] DecryptedHeader = z.DecryptMessage(eh, eh.Length); + + // CRC check + // According to the pkzip spec, the final byte in the decrypted header + // is the highest-order byte in the CRC. We check it here. + if (DecryptedHeader[11] != (byte)((e._Crc32 >> 24) & 0xff)) + { + // In the case that bit 3 of the general purpose bit flag is set to + // indicate the presence of an 'Extended File Header' or a 'data + // descriptor' (signature 0x08074b50), the last byte of the decrypted + // header is sometimes compared with the high-order byte of the + // lastmodified time, rather than the high-order byte of the CRC, to + // verify the password. + // + // This is not documented in the PKWare Appnote.txt. It was + // discovered this by analysis of the Crypt.c source file in the + // InfoZip library http://www.info-zip.org/pub/infozip/ + // + // The reason for this is that the CRC for a file cannot be known + // until the entire contents of the file have been streamed. This + // means a tool would have to read the file content TWICE in its + // entirety in order to perform PKZIP encryption - once to compute + // the CRC, and again to actually encrypt. + // + // This is so important for performance that using the timeblob as + // the verification should be the standard practice for DotNetZip + // when using PKZIP encryption. This implies that bit 3 must be + // set. The downside is that some tools still cannot cope with ZIP + // files that use bit 3. Therefore, DotNetZip DOES NOT force bit 3 + // when PKZIP encryption is in use, and instead, reads the stream + // twice. + // + + if ((e._BitField & 0x0008) != 0x0008) + { + throw new BadPasswordException("The password did not match."); + } + else if (DecryptedHeader[11] != (byte)((e._TimeBlob >> 8) & 0xff)) + { + throw new BadPasswordException("The password did not match."); + } + + // We have a good password. + } + else + { + // A-OK + } + return z; + } + + + + + /// + /// From AppNote.txt: + /// unsigned char decrypt_byte() + /// local unsigned short temp + /// temp :=- Key(2) | 2 + /// decrypt_byte := (temp * (temp ^ 1)) bitshift-right 8 + /// end decrypt_byte + /// + private byte MagicByte + { + get + { + UInt16 t = (UInt16)((UInt16)(_Keys[2] & 0xFFFF) | 2); + return (byte)((t * (t ^ 1)) >> 8); + } + } + + // Decrypting: + // From AppNote.txt: + // loop for i from 0 to 11 + // C := buffer(i) ^ decrypt_byte() + // update_keys(C) + // buffer(i) := C + // end loop + + + /// + /// Call this method on a cipher text to render the plaintext. You must + /// first initialize the cipher with a call to InitCipher. + /// + /// + /// + /// + /// var cipher = new ZipCrypto(); + /// cipher.InitCipher(Password); + /// // Decrypt the header. This has a side effect of "further initializing the + /// // encryption keys" in the traditional zip encryption. + /// byte[] DecryptedMessage = cipher.DecryptMessage(EncryptedMessage); + /// + /// + /// + /// The encrypted buffer. + /// + /// The number of bytes to encrypt. + /// Should be less than or equal to CipherText.Length. + /// + /// + /// The plaintext. + public byte[] DecryptMessage(byte[] cipherText, int length) + { + if (cipherText == null) + throw new ArgumentNullException("cipherText"); + + if (length > cipherText.Length) + throw new ArgumentOutOfRangeException("length", + "Bad length during Decryption: the length parameter must be smaller than or equal to the size of the destination array."); + + byte[] plainText = new byte[length]; + for (int i = 0; i < length; i++) + { + byte C = (byte)(cipherText[i] ^ MagicByte); + UpdateKeys(C); + plainText[i] = C; + } + return plainText; + } + + /// + /// This is the converse of DecryptMessage. It encrypts the plaintext + /// and produces a ciphertext. + /// + /// + /// The plain text buffer. + /// + /// + /// The number of bytes to encrypt. + /// Should be less than or equal to plainText.Length. + /// + /// + /// The ciphertext. + public byte[] EncryptMessage(byte[] plainText, int length) + { + if (plainText == null) + throw new ArgumentNullException("plaintext"); + + if (length > plainText.Length) + throw new ArgumentOutOfRangeException("length", + "Bad length during Encryption: The length parameter must be smaller than or equal to the size of the destination array."); + + byte[] cipherText = new byte[length]; + for (int i = 0; i < length; i++) + { + byte C = plainText[i]; + cipherText[i] = (byte)(plainText[i] ^ MagicByte); + UpdateKeys(C); + } + return cipherText; + } + + + /// + /// This initializes the cipher with the given password. + /// See AppNote.txt for details. + /// + /// + /// + /// The passphrase for encrypting or decrypting with this cipher. + /// + /// + /// + /// + /// Step 1 - Initializing the encryption keys + /// ----------------------------------------- + /// Start with these keys: + /// Key(0) := 305419896 (0x12345678) + /// Key(1) := 591751049 (0x23456789) + /// Key(2) := 878082192 (0x34567890) + /// + /// Then, initialize the keys with a password: + /// + /// loop for i from 0 to length(password)-1 + /// update_keys(password(i)) + /// end loop + /// + /// Where update_keys() is defined as: + /// + /// update_keys(char): + /// Key(0) := crc32(key(0),char) + /// Key(1) := Key(1) + (Key(0) bitwiseAND 000000ffH) + /// Key(1) := Key(1) * 134775813 + 1 + /// Key(2) := crc32(key(2),key(1) rightshift 24) + /// end update_keys + /// + /// Where crc32(old_crc,char) is a routine that given a CRC value and a + /// character, returns an updated CRC value after applying the CRC-32 + /// algorithm described elsewhere in this document. + /// + /// + /// + /// + /// After the keys are initialized, then you can use the cipher to + /// encrypt the plaintext. + /// + /// + /// + /// Essentially we encrypt the password with the keys, then discard the + /// ciphertext for the password. This initializes the keys for later use. + /// + /// + /// + public void InitCipher(string passphrase) + { + byte[] p = SharedUtilities.StringToByteArray(passphrase); + for (int i = 0; i < passphrase.Length; i++) + UpdateKeys(p[i]); + } + + + private void UpdateKeys(byte byteValue) + { + _Keys[0] = (UInt32)crc32.ComputeCrc32((int)_Keys[0], byteValue); + _Keys[1] = _Keys[1] + (byte)_Keys[0]; + _Keys[1] = _Keys[1] * 0x08088405 + 1; + _Keys[2] = (UInt32)crc32.ComputeCrc32((int)_Keys[2], (byte)(_Keys[1] >> 24)); + } + + ///// + ///// The byte array representing the seed keys used. + ///// Get this after calling InitCipher. The 12 bytes represents + ///// what the zip spec calls the "EncryptionHeader". + ///// + //public byte[] KeyHeader + //{ + // get + // { + // byte[] result = new byte[12]; + // result[0] = (byte)(_Keys[0] & 0xff); + // result[1] = (byte)((_Keys[0] >> 8) & 0xff); + // result[2] = (byte)((_Keys[0] >> 16) & 0xff); + // result[3] = (byte)((_Keys[0] >> 24) & 0xff); + // result[4] = (byte)(_Keys[1] & 0xff); + // result[5] = (byte)((_Keys[1] >> 8) & 0xff); + // result[6] = (byte)((_Keys[1] >> 16) & 0xff); + // result[7] = (byte)((_Keys[1] >> 24) & 0xff); + // result[8] = (byte)(_Keys[2] & 0xff); + // result[9] = (byte)((_Keys[2] >> 8) & 0xff); + // result[10] = (byte)((_Keys[2] >> 16) & 0xff); + // result[11] = (byte)((_Keys[2] >> 24) & 0xff); + // return result; + // } + //} + + // private fields for the crypto stuff: + private UInt32[] _Keys = { 0x12345678, 0x23456789, 0x34567890 }; + private Ionic.Crc.CRC32 crc32 = new Ionic.Crc.CRC32(); + + } + + internal enum CryptoMode + { + Encrypt, + Decrypt + } + + /// + /// A Stream for reading and concurrently decrypting data from a zip file, + /// or for writing and concurrently encrypting data to a zip file. + /// + internal class ZipCipherStream : System.IO.Stream + { + private ZipCrypto _cipher; + private System.IO.Stream _s; + private CryptoMode _mode; + + /// The constructor. + /// The underlying stream + /// To either encrypt or decrypt. + /// The pre-initialized ZipCrypto object. + public ZipCipherStream(System.IO.Stream s, ZipCrypto cipher, CryptoMode mode) + : base() + { + _cipher = cipher; + _s = s; + _mode = mode; + } + + public override int Read(byte[] buffer, int offset, int count) + { + if (_mode == CryptoMode.Encrypt) + throw new NotSupportedException("This stream does not encrypt via Read()"); + + if (buffer == null) + throw new ArgumentNullException("buffer"); + + byte[] db = new byte[count]; + int n = _s.Read(db, 0, count); + byte[] decrypted = _cipher.DecryptMessage(db, n); + for (int i = 0; i < n; i++) + { + buffer[offset + i] = decrypted[i]; + } + return n; + } + + public override void Write(byte[] buffer, int offset, int count) + { + if (_mode == CryptoMode.Decrypt) + throw new NotSupportedException("This stream does not Decrypt via Write()"); + + if (buffer == null) + throw new ArgumentNullException("buffer"); + + // workitem 7696 + if (count == 0) return; + + byte[] plaintext = null; + if (offset != 0) + { + plaintext = new byte[count]; + for (int i = 0; i < count; i++) + { + plaintext[i] = buffer[offset + i]; + } + } + else plaintext = buffer; + + byte[] encrypted = _cipher.EncryptMessage(plaintext, count); + _s.Write(encrypted, 0, encrypted.Length); + } + + + public override bool CanRead + { + get { return (_mode == CryptoMode.Decrypt); } + } + public override bool CanSeek + { + get { return false; } + } + + public override bool CanWrite + { + get { return (_mode == CryptoMode.Encrypt); } + } + + public override void Flush() + { + //throw new NotSupportedException(); + } + + public override long Length + { + get { throw new NotSupportedException(); } + } + + public override long Position + { + get { throw new NotSupportedException(); } + set { throw new NotSupportedException(); } + } + public override long Seek(long offset, System.IO.SeekOrigin origin) + { + throw new NotSupportedException(); + } + + public override void SetLength(long value) + { + throw new NotSupportedException(); + } + } +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipDirEntry.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipDirEntry.cs new file mode 100644 index 00000000..6c67236a --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipDirEntry.cs @@ -0,0 +1,381 @@ +// ZipDirEntry.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2006-2011 Dino Chiesa . +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-11 12:03:03> +// +// ------------------------------------------------------------------ +// +// This module defines members of the ZipEntry class for reading the +// Zip file central directory. +// +// Created: Tue, 27 Mar 2007 15:30 +// +// ------------------------------------------------------------------ + + +using System; +using System.Collections.Generic; + +namespace Ionic.Zip +{ + + partial class ZipEntry + { + /// + /// True if the referenced entry is a directory. + /// + internal bool AttributesIndicateDirectory + { + get { return ((_InternalFileAttrs == 0) && ((_ExternalFileAttrs & 0x0010) == 0x0010)); } + } + + + internal void ResetDirEntry() + { + // __FileDataPosition is the position of the file data for an entry. + // It is _RelativeOffsetOfLocalHeader + size of local header. + + // We cannot know the __FileDataPosition until we read the local + // header. + + // The local header is not necessarily the same length as the record + // in the central directory. + + // Set to -1, to indicate we need to read this later. + this.__FileDataPosition = -1; + + // set _LengthOfHeader to 0, to indicate we need to read later. + this._LengthOfHeader = 0; + } + + /// + /// Provides a human-readable string with information about the ZipEntry. + /// + public string Info + { + get + { + var builder = new System.Text.StringBuilder(); + builder + .Append(string.Format(" ZipEntry: {0}\n", this.FileName)) + .Append(string.Format(" Version Made By: {0}\n", this._VersionMadeBy)) + .Append(string.Format(" Needed to extract: {0}\n", this.VersionNeeded)); + + if (this._IsDirectory) + builder.Append(" Entry type: directory\n"); + else + { + builder.Append(string.Format(" File type: {0}\n", this._IsText? "text":"binary")) + .Append(string.Format(" Compression: {0}\n", this.CompressionMethod)) + .Append(string.Format(" Compressed: 0x{0:X}\n", this.CompressedSize)) + .Append(string.Format(" Uncompressed: 0x{0:X}\n", this.UncompressedSize)) + .Append(string.Format(" CRC32: 0x{0:X8}\n", this._Crc32)); + } + builder.Append(string.Format(" Disk Number: {0}\n", this._diskNumber)); + if (this._RelativeOffsetOfLocalHeader > 0xFFFFFFFF) + builder + .Append(string.Format(" Relative Offset: 0x{0:X16}\n", this._RelativeOffsetOfLocalHeader)); + else + builder + .Append(string.Format(" Relative Offset: 0x{0:X8}\n", this._RelativeOffsetOfLocalHeader)); + + builder + .Append(string.Format(" Bit Field: 0x{0:X4}\n", this._BitField)) + .Append(string.Format(" Encrypted?: {0}\n", this._sourceIsEncrypted)) + .Append(string.Format(" Timeblob: 0x{0:X8}\n", this._TimeBlob)) + .Append(string.Format(" Time: {0}\n", Ionic.Zip.SharedUtilities.PackedToDateTime(this._TimeBlob))); + + builder.Append(string.Format(" Is Zip64?: {0}\n", this._InputUsesZip64)); + if (!string.IsNullOrEmpty(this._Comment)) + { + builder.Append(string.Format(" Comment: {0}\n", this._Comment)); + } + builder.Append("\n"); + return builder.ToString(); + } + } + + + // workitem 10330 + private class CopyHelper + { + private static System.Text.RegularExpressions.Regex re = + new System.Text.RegularExpressions.Regex(" \\(copy (\\d+)\\)$"); + + private static int callCount = 0; + + internal static string AppendCopyToFileName(string f) + { + callCount++; + if (callCount > 25) + throw new OverflowException("overflow while creating filename"); + + int n = 1; + int r = f.LastIndexOf("."); + + if (r == -1) + { + // there is no extension + System.Text.RegularExpressions.Match m = re.Match(f); + if (m.Success) + { + n = Int32.Parse(m.Groups[1].Value) + 1; + string copy = String.Format(" (copy {0})", n); + f = f.Substring(0, m.Index) + copy; + } + else + { + string copy = String.Format(" (copy {0})", n); + f = f + copy; + } + } + else + { + //System.Console.WriteLine("HasExtension"); + System.Text.RegularExpressions.Match m = re.Match(f.Substring(0, r)); + if (m.Success) + { + n = Int32.Parse(m.Groups[1].Value) + 1; + string copy = String.Format(" (copy {0})", n); + f = f.Substring(0, m.Index) + copy + f.Substring(r); + } + else + { + string copy = String.Format(" (copy {0})", n); + f = f.Substring(0, r) + copy + f.Substring(r); + } + + //System.Console.WriteLine("returning f({0})", f); + } + return f; + } + } + + + + /// + /// Reads one entry from the zip directory structure in the zip file. + /// + /// + /// + /// The zipfile for which a directory entry will be read. From this param, the + /// method gets the ReadStream and the expected text encoding + /// (ProvisionalAlternateEncoding) which is used if the entry is not marked + /// UTF-8. + /// + /// + /// + /// a list of previously seen entry names; used to prevent duplicates. + /// + /// + /// the entry read from the archive. + internal static ZipEntry ReadDirEntry(ZipFile zf, + Dictionary previouslySeen) + { + System.IO.Stream s = zf.ReadStream; + System.Text.Encoding expectedEncoding = (zf.AlternateEncodingUsage == ZipOption.Always) + ? zf.AlternateEncoding + : ZipFile.DefaultEncoding; + + int signature = Ionic.Zip.SharedUtilities.ReadSignature(s); + // return null if this is not a local file header signature + if (IsNotValidZipDirEntrySig(signature)) + { + s.Seek(-4, System.IO.SeekOrigin.Current); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(s); + + // Getting "not a ZipDirEntry signature" here is not always wrong or an + // error. This can happen when walking through a zipfile. After the + // last ZipDirEntry, we expect to read an + // EndOfCentralDirectorySignature. When we get this is how we know + // we've reached the end of the central directory. + if (signature != ZipConstants.EndOfCentralDirectorySignature && + signature != ZipConstants.Zip64EndOfCentralDirectoryRecordSignature && + signature != ZipConstants.ZipEntrySignature // workitem 8299 + ) + { + throw new BadReadException(String.Format(" Bad signature (0x{0:X8}) at position 0x{1:X8}", signature, s.Position)); + } + return null; + } + + int bytesRead = 42 + 4; + byte[] block = new byte[42]; + int n = s.Read(block, 0, block.Length); + if (n != block.Length) return null; + + int i = 0; + ZipEntry zde = new ZipEntry(); + zde.AlternateEncoding = expectedEncoding; + zde._Source = ZipEntrySource.ZipFile; + zde._container = new ZipContainer(zf); + + unchecked + { + zde._VersionMadeBy = (short)(block[i++] + block[i++] * 256); + zde._VersionNeeded = (short)(block[i++] + block[i++] * 256); + zde._BitField = (short)(block[i++] + block[i++] * 256); + zde._CompressionMethod = (Int16)(block[i++] + block[i++] * 256); + zde._TimeBlob = block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256; + zde._LastModified = Ionic.Zip.SharedUtilities.PackedToDateTime(zde._TimeBlob); + zde._timestamp |= ZipEntryTimestamp.DOS; + + zde._Crc32 = block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256; + zde._CompressedSize = (uint)(block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256); + zde._UncompressedSize = (uint)(block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256); + } + + // preserve + zde._CompressionMethod_FromZipFile = zde._CompressionMethod; + + zde._filenameLength = (short)(block[i++] + block[i++] * 256); + zde._extraFieldLength = (short)(block[i++] + block[i++] * 256); + zde._commentLength = (short)(block[i++] + block[i++] * 256); + zde._diskNumber = (UInt32)(block[i++] + block[i++] * 256); + + zde._InternalFileAttrs = (short)(block[i++] + block[i++] * 256); + zde._ExternalFileAttrs = block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256; + + zde._RelativeOffsetOfLocalHeader = (uint)(block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256); + + // workitem 7801 + zde.IsText = ((zde._InternalFileAttrs & 0x01) == 0x01); + + block = new byte[zde._filenameLength]; + n = s.Read(block, 0, block.Length); + bytesRead += n; + if ((zde._BitField & 0x0800) == 0x0800) + { + // UTF-8 is in use + zde._FileNameInArchive = Ionic.Zip.SharedUtilities.Utf8StringFromBuffer(block); + } + else + { + zde._FileNameInArchive = Ionic.Zip.SharedUtilities.StringFromBuffer(block, expectedEncoding); + } + + // workitem 10330 + // insure unique entry names + while (previouslySeen.ContainsKey(zde._FileNameInArchive)) + { + zde._FileNameInArchive = CopyHelper.AppendCopyToFileName(zde._FileNameInArchive); + zde._metadataChanged = true; + } + + if (zde.AttributesIndicateDirectory) + zde.MarkAsDirectory(); // may append a slash to filename if nec. + // workitem 6898 + else if (zde._FileNameInArchive.EndsWith("/")) zde.MarkAsDirectory(); + + zde._CompressedFileDataSize = zde._CompressedSize; + if ((zde._BitField & 0x01) == 0x01) + { + // this may change after processing the Extra field + zde._Encryption_FromZipFile = zde._Encryption = + EncryptionAlgorithm.PkzipWeak; + zde._sourceIsEncrypted = true; + } + + if (zde._extraFieldLength > 0) + { + zde._InputUsesZip64 = (zde._CompressedSize == 0xFFFFFFFF || + zde._UncompressedSize == 0xFFFFFFFF || + zde._RelativeOffsetOfLocalHeader == 0xFFFFFFFF); + + // Console.WriteLine(" Input uses Z64?: {0}", zde._InputUsesZip64); + + bytesRead += zde.ProcessExtraField(s, zde._extraFieldLength); + zde._CompressedFileDataSize = zde._CompressedSize; + } + + // we've processed the extra field, so we know the encryption method is set now. + if (zde._Encryption == EncryptionAlgorithm.PkzipWeak) + { + // the "encryption header" of 12 bytes precedes the file data + zde._CompressedFileDataSize -= 12; + } +#if AESCRYPTO + else if (zde.Encryption == EncryptionAlgorithm.WinZipAes128 || + zde.Encryption == EncryptionAlgorithm.WinZipAes256) + { + zde._CompressedFileDataSize = zde.CompressedSize - + (ZipEntry.GetLengthOfCryptoHeaderBytes(zde.Encryption) + 10); + zde._LengthOfTrailer = 10; + } +#endif + + // tally the trailing descriptor + if ((zde._BitField & 0x0008) == 0x0008) + { + // sig, CRC, Comp and Uncomp sizes + if (zde._InputUsesZip64) + zde._LengthOfTrailer += 24; + else + zde._LengthOfTrailer += 16; + } + + // workitem 12744 + zde.AlternateEncoding = ((zde._BitField & 0x0800) == 0x0800) + ? System.Text.Encoding.UTF8 + :expectedEncoding; + + zde.AlternateEncodingUsage = ZipOption.Always; + + if (zde._commentLength > 0) + { + block = new byte[zde._commentLength]; + n = s.Read(block, 0, block.Length); + bytesRead += n; + if ((zde._BitField & 0x0800) == 0x0800) + { + // UTF-8 is in use + zde._Comment = Ionic.Zip.SharedUtilities.Utf8StringFromBuffer(block); + } + else + { + zde._Comment = Ionic.Zip.SharedUtilities.StringFromBuffer(block, expectedEncoding); + } + } + //zde._LengthOfDirEntry = bytesRead; + return zde; + } + + + /// + /// Returns true if the passed-in value is a valid signature for a ZipDirEntry. + /// + /// the candidate 4-byte signature value. + /// true, if the signature is valid according to the PKWare spec. + internal static bool IsNotValidZipDirEntrySig(int signature) + { + return (signature != ZipConstants.ZipDirEntrySignature); + } + + + private Int16 _VersionMadeBy; + private Int16 _InternalFileAttrs; + private Int32 _ExternalFileAttrs; + + //private Int32 _LengthOfDirEntry; + private Int16 _filenameLength; + private Int16 _extraFieldLength; + private Int16 _commentLength; + } + + +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipEntry.Extract.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipEntry.Extract.cs new file mode 100644 index 00000000..76cd9a7e --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipEntry.Extract.cs @@ -0,0 +1,1456 @@ +// ZipEntry.Extract.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009-2011 Dino Chiesa +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-August-06 18:08:21> +// +// ------------------------------------------------------------------ +// +// This module defines logic for Extract methods on the ZipEntry class. +// +// ------------------------------------------------------------------ + + +using System; +using System.IO; + +namespace Ionic.Zip +{ + + public partial class ZipEntry + { + /// + /// Extract the entry to the filesystem, starting at the current + /// working directory. + /// + /// + /// + /// This method has a bunch of overloads! One of them is sure to + /// be the right one for you... If you don't like these, check + /// out the ExtractWithPassword() methods. + /// + /// + /// + /// + /// + /// + /// + /// + /// This method extracts an entry from a zip file into the current + /// working directory. The path of the entry as extracted is the full + /// path as specified in the zip archive, relative to the current + /// working directory. After the file is extracted successfully, the + /// file attributes and timestamps are set. + /// + /// + /// + /// The action taken when extraction an entry would overwrite an + /// existing file is determined by the property. + /// + /// + /// + /// Within the call to Extract(), the content for the entry is + /// written into a filesystem file, and then the last modified time of the + /// file is set according to the property on + /// the entry. See the remarks the property for + /// some details about the last modified time. + /// + /// + /// + public void Extract() + { + InternalExtract(".", null, null); + } + + + /// + /// Extract the entry to a file in the filesystem, using the specified + /// behavior when extraction would overwrite an existing file. + /// + /// + /// + /// + /// See the remarks on the property, for some + /// details about how the last modified time of the file is set after + /// extraction. + /// + /// + /// + /// + /// The action to take if extraction would overwrite an existing file. + /// + public void Extract(ExtractExistingFileAction extractExistingFile) + { + ExtractExistingFile = extractExistingFile; + InternalExtract(".", null, null); + } + + /// + /// Extracts the entry to the specified stream. + /// + /// + /// + /// + /// The caller can specify any write-able stream, for example a , a , or ASP.NET's + /// Response.OutputStream. The content will be decrypted and + /// decompressed as necessary. If the entry is encrypted and no password + /// is provided, this method will throw. + /// + /// + /// The position on the stream is not reset by this method before it extracts. + /// You may want to call stream.Seek() before calling ZipEntry.Extract(). + /// + /// + /// + /// + /// the stream to which the entry should be extracted. + /// + /// + public void Extract(Stream stream) + { + InternalExtract(null, stream, null); + } + + /// + /// Extract the entry to the filesystem, starting at the specified base + /// directory. + /// + /// + /// the pathname of the base directory + /// + /// + /// + /// + /// + /// This example extracts only the entries in a zip file that are .txt files, + /// into a directory called "textfiles". + /// + /// using (ZipFile zip = ZipFile.Read("PackedDocuments.zip")) + /// { + /// foreach (string s1 in zip.EntryFilenames) + /// { + /// if (s1.EndsWith(".txt")) + /// { + /// zip[s1].Extract("textfiles"); + /// } + /// } + /// } + /// + /// + /// Using zip As ZipFile = ZipFile.Read("PackedDocuments.zip") + /// Dim s1 As String + /// For Each s1 In zip.EntryFilenames + /// If s1.EndsWith(".txt") Then + /// zip(s1).Extract("textfiles") + /// End If + /// Next + /// End Using + /// + /// + /// + /// + /// + /// + /// Using this method, existing entries in the filesystem will not be + /// overwritten. If you would like to force the overwrite of existing + /// files, see the property, or call + /// . + /// + /// + /// + /// See the remarks on the property, for some + /// details about how the last modified time of the created file is set. + /// + /// + public void Extract(string baseDirectory) + { + InternalExtract(baseDirectory, null, null); + } + + + + + + /// + /// Extract the entry to the filesystem, starting at the specified base + /// directory, and using the specified behavior when extraction would + /// overwrite an existing file. + /// + /// + /// + /// + /// See the remarks on the property, for some + /// details about how the last modified time of the created file is set. + /// + /// + /// + /// + /// + /// String sZipPath = "Airborne.zip"; + /// String sFilePath = "Readme.txt"; + /// String sRootFolder = "Digado"; + /// using (ZipFile zip = ZipFile.Read(sZipPath)) + /// { + /// if (zip.EntryFileNames.Contains(sFilePath)) + /// { + /// // use the string indexer on the zip file + /// zip[sFileName].Extract(sRootFolder, + /// ExtractExistingFileAction.OverwriteSilently); + /// } + /// } + /// + /// + /// + /// Dim sZipPath as String = "Airborne.zip" + /// Dim sFilePath As String = "Readme.txt" + /// Dim sRootFolder As String = "Digado" + /// Using zip As ZipFile = ZipFile.Read(sZipPath) + /// If zip.EntryFileNames.Contains(sFilePath) + /// ' use the string indexer on the zip file + /// zip(sFilePath).Extract(sRootFolder, _ + /// ExtractExistingFileAction.OverwriteSilently) + /// End If + /// End Using + /// + /// + /// + /// the pathname of the base directory + /// + /// The action to take if extraction would overwrite an existing file. + /// + public void Extract(string baseDirectory, ExtractExistingFileAction extractExistingFile) + { + ExtractExistingFile = extractExistingFile; + InternalExtract(baseDirectory, null, null); + } + + + /// + /// Extract the entry to the filesystem, using the current working directory + /// and the specified password. + /// + /// + /// + /// This method has a bunch of overloads! One of them is sure to be + /// the right one for you... + /// + /// + /// + /// + /// + /// + /// + /// + /// Existing entries in the filesystem will not be overwritten. If you + /// would like to force the overwrite of existing files, see the property, or call + /// . + /// + /// + /// + /// See the remarks on the property for some + /// details about how the "last modified" time of the created file is + /// set. + /// + /// + /// + /// + /// In this example, entries that use encryption are extracted using a + /// particular password. + /// + /// using (var zip = ZipFile.Read(FilePath)) + /// { + /// foreach (ZipEntry e in zip) + /// { + /// if (e.UsesEncryption) + /// e.ExtractWithPassword("Secret!"); + /// else + /// e.Extract(); + /// } + /// } + /// + /// + /// Using zip As ZipFile = ZipFile.Read(FilePath) + /// Dim e As ZipEntry + /// For Each e In zip + /// If (e.UsesEncryption) + /// e.ExtractWithPassword("Secret!") + /// Else + /// e.Extract + /// End If + /// Next + /// End Using + /// + /// + /// The Password to use for decrypting the entry. + public void ExtractWithPassword(string password) + { + InternalExtract(".", null, password); + } + + /// + /// Extract the entry to the filesystem, starting at the specified base + /// directory, and using the specified password. + /// + /// + /// + /// + /// + /// + /// + /// Existing entries in the filesystem will not be overwritten. If you + /// would like to force the overwrite of existing files, see the property, or call + /// . + /// + /// + /// + /// See the remarks on the property, for some + /// details about how the last modified time of the created file is set. + /// + /// + /// + /// The pathname of the base directory. + /// The Password to use for decrypting the entry. + public void ExtractWithPassword(string baseDirectory, string password) + { + InternalExtract(baseDirectory, null, password); + } + + + + + /// + /// Extract the entry to a file in the filesystem, relative to the + /// current directory, using the specified behavior when extraction + /// would overwrite an existing file. + /// + /// + /// + /// + /// See the remarks on the property, for some + /// details about how the last modified time of the created file is set. + /// + /// + /// + /// The Password to use for decrypting the entry. + /// + /// + /// The action to take if extraction would overwrite an existing file. + /// + public void ExtractWithPassword(ExtractExistingFileAction extractExistingFile, string password) + { + ExtractExistingFile = extractExistingFile; + InternalExtract(".", null, password); + } + + + + /// + /// Extract the entry to the filesystem, starting at the specified base + /// directory, and using the specified behavior when extraction would + /// overwrite an existing file. + /// + /// + /// + /// See the remarks on the property, for some + /// details about how the last modified time of the created file is set. + /// + /// + /// the pathname of the base directory + /// + /// The action to take if extraction would + /// overwrite an existing file. + /// + /// The Password to use for decrypting the entry. + public void ExtractWithPassword(string baseDirectory, ExtractExistingFileAction extractExistingFile, string password) + { + ExtractExistingFile = extractExistingFile; + InternalExtract(baseDirectory, null, password); + } + + /// + /// Extracts the entry to the specified stream, using the specified + /// Password. For example, the caller could extract to Console.Out, or + /// to a MemoryStream. + /// + /// + /// + /// + /// The caller can specify any write-able stream, for example a , a , or ASP.NET's + /// Response.OutputStream. The content will be decrypted and + /// decompressed as necessary. If the entry is encrypted and no password + /// is provided, this method will throw. + /// + /// + /// The position on the stream is not reset by this method before it extracts. + /// You may want to call stream.Seek() before calling ZipEntry.Extract(). + /// + /// + /// + /// + /// + /// the stream to which the entry should be extracted. + /// + /// + /// The password to use for decrypting the entry. + /// + public void ExtractWithPassword(Stream stream, string password) + { + InternalExtract(null, stream, password); + } + + + /// + /// Opens a readable stream corresponding to the zip entry in the + /// archive. The stream decompresses and decrypts as necessary, as it + /// is read. + /// + /// + /// + /// + /// + /// DotNetZip offers a variety of ways to extract entries from a zip + /// file. This method allows an application to extract an entry by + /// reading a . + /// + /// + /// + /// The return value is of type . Use it as you would any + /// stream for reading. When an application calls on that stream, it will + /// receive data from the zip entry that is decrypted and decompressed + /// as necessary. + /// + /// + /// + /// CrcCalculatorStream adds one additional feature: it keeps a + /// CRC32 checksum on the bytes of the stream as it is read. The CRC + /// value is available in the property on the + /// CrcCalculatorStream. When the read is complete, your + /// application + /// should check this CRC against the + /// property on the ZipEntry to validate the content of the + /// ZipEntry. You don't have to validate the entry using the CRC, but + /// you should, to verify integrity. Check the example for how to do + /// this. + /// + /// + /// + /// If the entry is protected with a password, then you need to provide + /// a password prior to calling , either by + /// setting the property on the entry, or the + /// property on the ZipFile + /// itself. Or, you can use , the + /// overload of OpenReader that accepts a password parameter. + /// + /// + /// + /// If you want to extract entry data into a write-able stream that is + /// already opened, like a , do not + /// use this method. Instead, use . + /// + /// + /// + /// Your application may use only one stream created by OpenReader() at + /// a time, and you should not call other Extract methods before + /// completing your reads on a stream obtained from OpenReader(). This + /// is because there is really only one source stream for the compressed + /// content. A call to OpenReader() seeks in the source stream, to the + /// beginning of the compressed content. A subsequent call to + /// OpenReader() on a different entry will seek to a different position + /// in the source stream, as will a call to Extract() or one of its + /// overloads. This will corrupt the state for the decompressing stream + /// from the original call to OpenReader(). + /// + /// + /// + /// The OpenReader() method works only when the ZipEntry is + /// obtained from an instance of ZipFile. This method will throw + /// an exception if the ZipEntry is obtained from a . + /// + /// + /// + /// + /// This example shows how to open a zip archive, then read in a named + /// entry via a stream. After the read loop is complete, the code + /// compares the calculated during the read loop with the expected CRC + /// on the ZipEntry, to verify the extraction. + /// + /// using (ZipFile zip = new ZipFile(ZipFileToRead)) + /// { + /// ZipEntry e1= zip["Elevation.mp3"]; + /// using (Ionic.Zlib.CrcCalculatorStream s = e1.OpenReader()) + /// { + /// byte[] buffer = new byte[4096]; + /// int n, totalBytesRead= 0; + /// do { + /// n = s.Read(buffer,0, buffer.Length); + /// totalBytesRead+=n; + /// } while (n>0); + /// if (s.Crc32 != e1.Crc32) + /// throw new Exception(string.Format("The Zip Entry failed the CRC Check. (0x{0:X8}!=0x{1:X8})", s.Crc32, e1.Crc32)); + /// if (totalBytesRead != e1.UncompressedSize) + /// throw new Exception(string.Format("We read an unexpected number of bytes. ({0}!={1})", totalBytesRead, e1.UncompressedSize)); + /// } + /// } + /// + /// + /// Using zip As New ZipFile(ZipFileToRead) + /// Dim e1 As ZipEntry = zip.Item("Elevation.mp3") + /// Using s As Ionic.Zlib.CrcCalculatorStream = e1.OpenReader + /// Dim n As Integer + /// Dim buffer As Byte() = New Byte(4096) {} + /// Dim totalBytesRead As Integer = 0 + /// Do + /// n = s.Read(buffer, 0, buffer.Length) + /// totalBytesRead = (totalBytesRead + n) + /// Loop While (n > 0) + /// If (s.Crc32 <> e1.Crc32) Then + /// Throw New Exception(String.Format("The Zip Entry failed the CRC Check. (0x{0:X8}!=0x{1:X8})", s.Crc32, e1.Crc32)) + /// End If + /// If (totalBytesRead <> e1.UncompressedSize) Then + /// Throw New Exception(String.Format("We read an unexpected number of bytes. ({0}!={1})", totalBytesRead, e1.UncompressedSize)) + /// End If + /// End Using + /// End Using + /// + /// + /// + /// The Stream for reading. + public Ionic.Crc.CrcCalculatorStream OpenReader() + { + // workitem 10923 + if (_container.ZipFile == null) + throw new InvalidOperationException("Use OpenReader() only with ZipFile."); + + // use the entry password if it is non-null, + // else use the zipfile password, which is possibly null + return InternalOpenReader(this._Password ?? this._container.Password); + } + + /// + /// Opens a readable stream for an encrypted zip entry in the archive. + /// The stream decompresses and decrypts as necessary, as it is read. + /// + /// + /// + /// + /// See the documentation on the method for + /// full details. This overload allows the application to specify a + /// password for the ZipEntry to be read. + /// + /// + /// + /// The password to use for decrypting the entry. + /// The Stream for reading. + public Ionic.Crc.CrcCalculatorStream OpenReader(string password) + { + // workitem 10923 + if (_container.ZipFile == null) + throw new InvalidOperationException("Use OpenReader() only with ZipFile."); + + return InternalOpenReader(password); + } + + + + internal Ionic.Crc.CrcCalculatorStream InternalOpenReader(string password) + { + ValidateCompression(); + ValidateEncryption(); + SetupCryptoForExtract(password); + + // workitem 7958 + if (this._Source != ZipEntrySource.ZipFile) + throw new BadStateException("You must call ZipFile.Save before calling OpenReader"); + + // LeftToRead is a count of bytes remaining to be read (out) + // from the stream AFTER decompression and decryption. + // It is the uncompressed size, unless ... there is no compression in which + // case ...? :< I'm not sure why it's not always UncompressedSize + Int64 LeftToRead = (_CompressionMethod_FromZipFile == (short)CompressionMethod.None) + ? this._CompressedFileDataSize + : this.UncompressedSize; + + Stream input = this.ArchiveStream; + + this.ArchiveStream.Seek(this.FileDataPosition, SeekOrigin.Begin); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(this.ArchiveStream); + + _inputDecryptorStream = GetExtractDecryptor(input); + Stream input3 = GetExtractDecompressor(_inputDecryptorStream); + + return new Ionic.Crc.CrcCalculatorStream(input3, LeftToRead); + } + + + + private void OnExtractProgress(Int64 bytesWritten, Int64 totalBytesToWrite) + { + if (_container.ZipFile != null) + _ioOperationCanceled = _container.ZipFile.OnExtractBlock(this, bytesWritten, totalBytesToWrite); + } + + + private void OnBeforeExtract(string path) + { + // When in the context of a ZipFile.ExtractAll, the events are generated from + // the ZipFile method, not from within the ZipEntry instance. (why?) + // Therefore we suppress the events originating from the ZipEntry method. + if (_container.ZipFile != null) + { + if (!_container.ZipFile._inExtractAll) + { + _ioOperationCanceled = _container.ZipFile.OnSingleEntryExtract(this, path, true); + } + } + } + + private void OnAfterExtract(string path) + { + // When in the context of a ZipFile.ExtractAll, the events are generated from + // the ZipFile method, not from within the ZipEntry instance. (why?) + // Therefore we suppress the events originating from the ZipEntry method. + if (_container.ZipFile != null) + { + if (!_container.ZipFile._inExtractAll) + { + _container.ZipFile.OnSingleEntryExtract(this, path, false); + } + } + } + + private void OnExtractExisting(string path) + { + if (_container.ZipFile != null) + _ioOperationCanceled = _container.ZipFile.OnExtractExisting(this, path); + } + + private static void ReallyDelete(string fileName) + { + // workitem 7881 + // reset ReadOnly bit if necessary +#if NETCF + if ( (NetCfFile.GetAttributes(fileName) & (uint)FileAttributes.ReadOnly) == (uint)FileAttributes.ReadOnly) + NetCfFile.SetAttributes(fileName, (uint)FileAttributes.Normal); +#elif SILVERLIGHT +#else + if ((File.GetAttributes(fileName) & FileAttributes.ReadOnly) == FileAttributes.ReadOnly) + File.SetAttributes(fileName, FileAttributes.Normal); +#endif + File.Delete(fileName); + } + + + private void WriteStatus(string format, params Object[] args) + { + if (_container.ZipFile != null && _container.ZipFile.Verbose) _container.ZipFile.StatusMessageTextWriter.WriteLine(format, args); + } + + + // Pass in either basedir or s, but not both. + // In other words, you can extract to a stream or to a directory (filesystem), but not both! + // The Password param is required for encrypted entries. + private void InternalExtract(string baseDir, Stream outstream, string password) + { + // workitem 7958 + if (_container == null) + throw new BadStateException("This entry is an orphan"); + + // workitem 10355 + if (_container.ZipFile == null) + throw new InvalidOperationException("Use Extract() only with ZipFile."); + + _container.ZipFile.Reset(false); + + if (this._Source != ZipEntrySource.ZipFile) + throw new BadStateException("You must call ZipFile.Save before calling any Extract method"); + + OnBeforeExtract(baseDir); + _ioOperationCanceled = false; + string targetFileName = null; + Stream output = null; + bool fileExistsBeforeExtraction = false; + bool checkLaterForResetDirTimes = false; + try + { + ValidateCompression(); + ValidateEncryption(); + + if (ValidateOutput(baseDir, outstream, out targetFileName)) + { + WriteStatus("extract dir {0}...", targetFileName); + // if true, then the entry was a directory and has been created. + // We need to fire the Extract Event. + OnAfterExtract(baseDir); + return; + } + + // workitem 10639 + // do we want to extract to a regular filesystem file? + if (targetFileName != null) + { + // Check for extracting to a previously extant file. The user + // can specify bejavior for that case: overwrite, don't + // overwrite, and throw. Also, if the file exists prior to + // extraction, it affects exception handling: whether to delete + // the target of extraction or not. This check needs to be done + // before the password check is done, because password check may + // throw a BadPasswordException, which triggers the catch, + // wherein the extant file may be deleted if not flagged as + // pre-existing. + if (File.Exists(targetFileName)) + { + fileExistsBeforeExtraction = true; + int rc = CheckExtractExistingFile(baseDir, targetFileName); + if (rc == 2) goto ExitTry; // cancel + if (rc == 1) return; // do not overwrite + } + } + + // If no password explicitly specified, use the password on the entry itself, + // or on the zipfile itself. + string p = password ?? this._Password ?? this._container.Password; + if (_Encryption_FromZipFile != EncryptionAlgorithm.None) + { + if (p == null) + throw new BadPasswordException(); + SetupCryptoForExtract(p); + } + + + // set up the output stream + if (targetFileName != null) + { + WriteStatus("extract file {0}...", targetFileName); + targetFileName += ".tmp"; + var dirName = Path.GetDirectoryName(targetFileName); + // ensure the target path exists + if (!Directory.Exists(dirName)) + { + // we create the directory here, but we do not set the + // create/modified/accessed times on it because it is being + // created implicitly, not explcitly. There's no entry in the + // zip archive for the directory. + Directory.CreateDirectory(dirName); + } + else + { + // workitem 8264 + if (_container.ZipFile != null) + checkLaterForResetDirTimes = _container.ZipFile._inExtractAll; + } + + // File.Create(CreateNew) will overwrite any existing file. + output = new FileStream(targetFileName, FileMode.CreateNew); + } + else + { + WriteStatus("extract entry {0} to stream...", FileName); + output = outstream; + } + + + if (_ioOperationCanceled) + goto ExitTry; + + Int32 ActualCrc32 = ExtractOne(output); + + if (_ioOperationCanceled) + goto ExitTry; + + VerifyCrcAfterExtract(ActualCrc32); + + if (targetFileName != null) + { + output.Close(); + output = null; + + // workitem 10639 + // move file to permanent home + string tmpName = targetFileName; + string zombie = null; + targetFileName = tmpName.Substring(0,tmpName.Length-4); + + if (fileExistsBeforeExtraction) + { + // An AV program may hold the target file open, which means + // File.Delete() will succeed, though the actual deletion + // remains pending. This will prevent a subsequent + // File.Move() from succeeding. To avoid this, when the file + // already exists, we need to replace it in 3 steps: + // + // 1. rename the existing file to a zombie name; + // 2. rename the extracted file from the temp name to + // the target file name; + // 3. delete the zombie. + // + zombie = targetFileName + ".PendingOverwrite"; + File.Move(targetFileName, zombie); + } + + File.Move(tmpName, targetFileName); + _SetTimes(targetFileName, true); + + if (zombie != null && File.Exists(zombie)) + ReallyDelete(zombie); + + // workitem 8264 + if (checkLaterForResetDirTimes) + { + // This is sort of a hack. What I do here is set the time on + // the parent directory, every time a file is extracted into + // it. If there is a directory with 1000 files, then I set + // the time on the dir, 1000 times. This allows the directory + // to have times that reflect the actual time on the entry in + // the zip archive. + + // String.Contains is not available on .NET CF 2.0 + if (this.FileName.IndexOf('/') != -1) + { + string dirname = Path.GetDirectoryName(this.FileName); + if (this._container.ZipFile[dirname] == null) + { + _SetTimes(Path.GetDirectoryName(targetFileName), false); + } + } + } + +#if NETCF + // workitem 7926 - version made by OS can be zero or 10 + if ((_VersionMadeBy & 0xFF00) == 0x0a00 || (_VersionMadeBy & 0xFF00) == 0x0000) + NetCfFile.SetAttributes(targetFileName, (uint)_ExternalFileAttrs); + +#else + // workitem 7071 + // + // We can only apply attributes if they are relevant to the NTFS + // OS. Must do this LAST because it may involve a ReadOnly bit, + // which would prevent us from setting the time, etc. + // + // workitem 7926 - version made by OS can be zero (FAT) or 10 + // (NTFS) + if ((_VersionMadeBy & 0xFF00) == 0x0a00 || (_VersionMadeBy & 0xFF00) == 0x0000) + File.SetAttributes(targetFileName, (FileAttributes)_ExternalFileAttrs); +#endif + } + + OnAfterExtract(baseDir); + + ExitTry: ; + } + catch (Exception) + { + _ioOperationCanceled = true; + throw; + } + finally + { + if (_ioOperationCanceled) + { + if (targetFileName != null) + { + try + { + if (output != null) output.Close(); + // An exception has occurred. If the file exists, check + // to see if it existed before we tried extracting. If + // it did not, attempt to remove the target file. There + // is a small possibility that the existing file has + // been extracted successfully, overwriting a previously + // existing file, and an exception was thrown after that + // but before final completion (setting times, etc). In + // that case the file will remain, even though some + // error occurred. Nothing to be done about it. + if (File.Exists(targetFileName) && !fileExistsBeforeExtraction) + File.Delete(targetFileName); + + } + finally { } + } + } + } + } + + +#if NOT + internal void CalcWinZipAesMac(Stream input) + { + if (Encryption == EncryptionAlgorithm.WinZipAes128 || + Encryption == EncryptionAlgorithm.WinZipAes256) + { + if (input is WinZipAesCipherStream) + wzs = input as WinZipAesCipherStream; + + else if (input is Ionic.Zlib.CrcCalculatorStream) + { + xxx; + } + + } + } +#endif + + + internal void VerifyCrcAfterExtract(Int32 actualCrc32) + { + +#if AESCRYPTO + // After extracting, Validate the CRC32 + if (actualCrc32 != _Crc32) + { + // CRC is not meaningful with WinZipAES and AES method 2 (AE-2) + if ((Encryption != EncryptionAlgorithm.WinZipAes128 && + Encryption != EncryptionAlgorithm.WinZipAes256) + || _WinZipAesMethod != 0x02) + throw new BadCrcException("CRC error: the file being extracted appears to be corrupted. " + + String.Format("Expected 0x{0:X8}, Actual 0x{1:X8}", _Crc32, actualCrc32)); + } + + // ignore MAC if the size of the file is zero + if (this.UncompressedSize == 0) + return; + + // calculate the MAC + if (Encryption == EncryptionAlgorithm.WinZipAes128 || + Encryption == EncryptionAlgorithm.WinZipAes256) + { + WinZipAesCipherStream wzs = _inputDecryptorStream as WinZipAesCipherStream; + _aesCrypto_forExtract.CalculatedMac = wzs.FinalAuthentication; + + _aesCrypto_forExtract.ReadAndVerifyMac(this.ArchiveStream); // throws if MAC is bad + // side effect: advances file position. + } + + + + +#else + if (actualCrc32 != _Crc32) + throw new BadCrcException("CRC error: the file being extracted appears to be corrupted. " + + String.Format("Expected 0x{0:X8}, Actual 0x{1:X8}", _Crc32, actualCrc32)); +#endif + } + + + + + private int CheckExtractExistingFile(string baseDir, string targetFileName) + { + int loop = 0; + // returns: 0 == extract, 1 = don't, 2 = cancel + do + { + switch (ExtractExistingFile) + { + case ExtractExistingFileAction.OverwriteSilently: + WriteStatus("the file {0} exists; will overwrite it...", targetFileName); + return 0; + + case ExtractExistingFileAction.DoNotOverwrite: + WriteStatus("the file {0} exists; not extracting entry...", FileName); + OnAfterExtract(baseDir); + return 1; + + case ExtractExistingFileAction.InvokeExtractProgressEvent: + if (loop>0) + throw new ZipException(String.Format("The file {0} already exists.", targetFileName)); + OnExtractExisting(baseDir); + if (_ioOperationCanceled) + return 2; + + // loop around + break; + + case ExtractExistingFileAction.Throw: + default: + throw new ZipException(String.Format("The file {0} already exists.", targetFileName)); + } + loop++; + } + while (true); + } + + + + + private void _CheckRead(int nbytes) + { + if (nbytes == 0) + throw new BadReadException(String.Format("bad read of entry {0} from compressed archive.", + this.FileName)); + } + + + private Stream _inputDecryptorStream; + + private Int32 ExtractOne(Stream output) + { + Int32 CrcResult = 0; + Stream input = this.ArchiveStream; + + try + { + // change for workitem 8098 + input.Seek(this.FileDataPosition, SeekOrigin.Begin); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(input); + + byte[] bytes = new byte[BufferSize]; + + // The extraction process varies depending on how the entry was + // stored. It could have been encrypted, and it coould have + // been compressed, or both, or neither. So we need to check + // both the encryption flag and the compression flag, and take + // the proper action in all cases. + + Int64 LeftToRead = (_CompressionMethod_FromZipFile != (short)CompressionMethod.None) + ? this.UncompressedSize + : this._CompressedFileDataSize; + + // Get a stream that either decrypts or not. + _inputDecryptorStream = GetExtractDecryptor(input); + + Stream input3 = GetExtractDecompressor( _inputDecryptorStream ); + + Int64 bytesWritten = 0; + // As we read, we maybe decrypt, and then we maybe decompress. Then we write. + using (var s1 = new Ionic.Crc.CrcCalculatorStream(input3)) + { + while (LeftToRead > 0) + { + //Console.WriteLine("ExtractOne: LeftToRead {0}", LeftToRead); + + // Casting LeftToRead down to an int is ok here in the else clause, + // because that only happens when it is less than bytes.Length, + // which is much less than MAX_INT. + int len = (LeftToRead > bytes.Length) ? bytes.Length : (int)LeftToRead; + int n = s1.Read(bytes, 0, len); + + // must check data read - essential for detecting corrupt zip files + _CheckRead(n); + + output.Write(bytes, 0, n); + LeftToRead -= n; + bytesWritten += n; + + // fire the progress event, check for cancels + OnExtractProgress(bytesWritten, UncompressedSize); + if (_ioOperationCanceled) + { + break; + } + } + + CrcResult = s1.Crc; + } + } + finally + { + var zss = input as ZipSegmentedStream; + if (zss != null) + { +#if NETCF + zss.Close(); +#else + // need to dispose it + zss.Dispose(); +#endif + _archiveStream = null; + } + } + + return CrcResult; + } + + + + internal Stream GetExtractDecompressor(Stream input2) + { + // get a stream that either decompresses or not. + switch (_CompressionMethod_FromZipFile) + { + case (short)CompressionMethod.None: + return input2; + case (short)CompressionMethod.Deflate: + return new Ionic.Zlib.DeflateStream(input2, Ionic.Zlib.CompressionMode.Decompress, true); +#if BZIP + case (short)CompressionMethod.BZip2: + return new Ionic.BZip2.BZip2InputStream(input2, true); +#endif + } + + return null; + } + + + + internal Stream GetExtractDecryptor(Stream input) + { + Stream input2 = null; + if (_Encryption_FromZipFile == EncryptionAlgorithm.PkzipWeak) + input2 = new ZipCipherStream(input, _zipCrypto_forExtract, CryptoMode.Decrypt); + +#if AESCRYPTO + else if (_Encryption_FromZipFile == EncryptionAlgorithm.WinZipAes128 || + _Encryption_FromZipFile == EncryptionAlgorithm.WinZipAes256) + input2 = new WinZipAesCipherStream(input, _aesCrypto_forExtract, _CompressedFileDataSize, CryptoMode.Decrypt); +#endif + + else + input2 = input; + + return input2; + } + + + + + internal void _SetTimes(string fileOrDirectory, bool isFile) + { +#if SILVERLIGHT + // punt on setting file times +#else + // workitem 8807: + // Because setting the time is not considered to be a fatal error, + // and because other applications can interfere with the setting + // of a time on a directory, we're going to swallow IO exceptions + // in this method. + + try + { + if (_ntfsTimesAreSet) + { +#if NETCF + // workitem 7944: set time should not be a fatal error on CF + int rc = NetCfFile.SetTimes(fileOrDirectory, _Ctime, _Atime, _Mtime); + if ( rc != 0) + { + WriteStatus("Warning: SetTimes failed. entry({0}) file({1}) rc({2})", + FileName, fileOrDirectory, rc); + } +#else + if (isFile) + { + // It's possible that the extract was cancelled, in which case, + // the file does not exist. + if (File.Exists(fileOrDirectory)) + { + File.SetCreationTimeUtc(fileOrDirectory, _Ctime); + File.SetLastAccessTimeUtc(fileOrDirectory, _Atime); + File.SetLastWriteTimeUtc(fileOrDirectory, _Mtime); + } + } + else + { + // It's possible that the extract was cancelled, in which case, + // the directory does not exist. + if (Directory.Exists(fileOrDirectory)) + { + Directory.SetCreationTimeUtc(fileOrDirectory, _Ctime); + Directory.SetLastAccessTimeUtc(fileOrDirectory, _Atime); + Directory.SetLastWriteTimeUtc(fileOrDirectory, _Mtime); + } + } +#endif + } + else + { + // workitem 6191 + DateTime AdjustedLastModified = Ionic.Zip.SharedUtilities.AdjustTime_Reverse(LastModified); + +#if NETCF + int rc = NetCfFile.SetLastWriteTime(fileOrDirectory, AdjustedLastModified); + + if ( rc != 0) + { + WriteStatus("Warning: SetLastWriteTime failed. entry({0}) file({1}) rc({2})", + FileName, fileOrDirectory, rc); + } +#else + if (isFile) + File.SetLastWriteTime(fileOrDirectory, AdjustedLastModified); + else + Directory.SetLastWriteTime(fileOrDirectory, AdjustedLastModified); +#endif + } + } + catch (System.IO.IOException ioexc1) + { + WriteStatus("failed to set time on {0}: {1}", fileOrDirectory, ioexc1.Message); + } +#endif + } + + + #region Support methods + + + // workitem 7968 + private string UnsupportedAlgorithm + { + get + { + string alg = String.Empty; + switch (_UnsupportedAlgorithmId) + { + case 0: + alg = "--"; + break; + case 0x6601: + alg = "DES"; + break; + case 0x6602: // - RC2 (version needed to extract < 5.2) + alg = "RC2"; + break; + case 0x6603: // - 3DES 168 + alg = "3DES-168"; + break; + case 0x6609: // - 3DES 112 + alg = "3DES-112"; + break; + case 0x660E: // - AES 128 + alg = "PKWare AES128"; + break; + case 0x660F: // - AES 192 + alg = "PKWare AES192"; + break; + case 0x6610: // - AES 256 + alg = "PKWare AES256"; + break; + case 0x6702: // - RC2 (version needed to extract >= 5.2) + alg = "RC2"; + break; + case 0x6720: // - Blowfish + alg = "Blowfish"; + break; + case 0x6721: // - Twofish + alg = "Twofish"; + break; + case 0x6801: // - RC4 + alg = "RC4"; + break; + case 0xFFFF: // - Unknown algorithm + default: + alg = String.Format("Unknown (0x{0:X4})", _UnsupportedAlgorithmId); + break; + } + return alg; + } + } + + // workitem 7968 + private string UnsupportedCompressionMethod + { + get + { + string meth = String.Empty; + switch ((int)_CompressionMethod) + { + case 0: + meth = "Store"; + break; + case 1: + meth = "Shrink"; + break; + case 8: + meth = "DEFLATE"; + break; + case 9: + meth = "Deflate64"; + break; + case 12: + meth = "BZIP2"; // only if BZIP not compiled in + break; + case 14: + meth = "LZMA"; + break; + case 19: + meth = "LZ77"; + break; + case 98: + meth = "PPMd"; + break; + default: + meth = String.Format("Unknown (0x{0:X4})", _CompressionMethod); + break; + } + return meth; + } + } + + + internal void ValidateEncryption() + { + if (Encryption != EncryptionAlgorithm.PkzipWeak && +#if AESCRYPTO + Encryption != EncryptionAlgorithm.WinZipAes128 && + Encryption != EncryptionAlgorithm.WinZipAes256 && +#endif + Encryption != EncryptionAlgorithm.None) + { + // workitem 7968 + if (_UnsupportedAlgorithmId != 0) + throw new ZipException(String.Format("Cannot extract: Entry {0} is encrypted with an algorithm not supported by DotNetZip: {1}", + FileName, UnsupportedAlgorithm)); + else + throw new ZipException(String.Format("Cannot extract: Entry {0} uses an unsupported encryption algorithm ({1:X2})", + FileName, (int)Encryption)); + } + } + + + private void ValidateCompression() + { + if ((_CompressionMethod_FromZipFile != (short)CompressionMethod.None) && + (_CompressionMethod_FromZipFile != (short)CompressionMethod.Deflate) +#if BZIP + && (_CompressionMethod_FromZipFile != (short)CompressionMethod.BZip2) +#endif + ) + throw new ZipException(String.Format("Entry {0} uses an unsupported compression method (0x{1:X2}, {2})", + FileName, _CompressionMethod_FromZipFile, UnsupportedCompressionMethod)); + } + + + private void SetupCryptoForExtract(string password) + { + //if (password == null) return; + if (_Encryption_FromZipFile == EncryptionAlgorithm.None) return; + + if (_Encryption_FromZipFile == EncryptionAlgorithm.PkzipWeak) + { + if (password == null) + throw new ZipException("Missing password."); + + this.ArchiveStream.Seek(this.FileDataPosition - 12, SeekOrigin.Begin); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(this.ArchiveStream); + _zipCrypto_forExtract = ZipCrypto.ForRead(password, this); + } + +#if AESCRYPTO + else if (_Encryption_FromZipFile == EncryptionAlgorithm.WinZipAes128 || + _Encryption_FromZipFile == EncryptionAlgorithm.WinZipAes256) + { + if (password == null) + throw new ZipException("Missing password."); + + // If we already have a WinZipAesCrypto object in place, use it. + // It can be set up in the ReadDirEntry(), or during a previous Extract. + if (_aesCrypto_forExtract != null) + { + _aesCrypto_forExtract.Password = password; + } + else + { + int sizeOfSaltAndPv = GetLengthOfCryptoHeaderBytes(_Encryption_FromZipFile); + this.ArchiveStream.Seek(this.FileDataPosition - sizeOfSaltAndPv, SeekOrigin.Begin); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(this.ArchiveStream); + int keystrength = GetKeyStrengthInBits(_Encryption_FromZipFile); + _aesCrypto_forExtract = WinZipAesCrypto.ReadFromStream(password, keystrength, this.ArchiveStream); + } + } +#endif + } + + + + /// + /// Validates that the args are consistent. + /// + /// + /// Only one of {baseDir, outStream} can be non-null. + /// If baseDir is non-null, then the outputFile is created. + /// + private bool ValidateOutput(string basedir, Stream outstream, out string outFileName) + { + if (basedir != null) + { + // Sometimes the name on the entry starts with a slash. + // Rather than unpack to the root of the volume, we're going to + // drop the slash and unpack to the specified base directory. + string f = this.FileName.Replace("\\","/"); + + // workitem 11772: remove drive letter with separator + if (f.IndexOf(':') == 1) + f= f.Substring(2); + + if (f.StartsWith("/")) + f= f.Substring(1); + + // String.Contains is not available on .NET CF 2.0 + + if (_container.ZipFile.FlattenFoldersOnExtract) + outFileName = Path.Combine(basedir, + (f.IndexOf('/') != -1) ? Path.GetFileName(f) : f); + else + outFileName = Path.Combine(basedir, f); + + // workitem 10639 + outFileName = outFileName.Replace("/","\\"); + + // check if it is a directory + if ((IsDirectory) || (FileName.EndsWith("/"))) + { + if (!Directory.Exists(outFileName)) + { + Directory.CreateDirectory(outFileName); + _SetTimes(outFileName, false); + } + else + { + // the dir exists, maybe we want to overwrite times. + if (ExtractExistingFile == ExtractExistingFileAction.OverwriteSilently) + _SetTimes(outFileName, false); + } + return true; // true == all done, caller will return + } + return false; // false == work to do by caller. + } + + if (outstream != null) + { + outFileName = null; + if ((IsDirectory) || (FileName.EndsWith("/"))) + { + // extract a directory to streamwriter? nothing to do! + return true; // true == all done! caller can return + } + return false; + } + + throw new ArgumentNullException("outstream"); + } + + + #endregion + + } +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipEntry.Read.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipEntry.Read.cs new file mode 100644 index 00000000..a1aba115 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipEntry.Read.cs @@ -0,0 +1,798 @@ +// ZipEntry.Read.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009-2011 Dino Chiesa +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-09 21:31:28> +// +// ------------------------------------------------------------------ +// +// This module defines logic for Reading the ZipEntry from a +// zip file. +// +// ------------------------------------------------------------------ + + +using System; +using System.IO; + +namespace Ionic.Zip +{ + public partial class ZipEntry + { + private int _readExtraDepth; + private void ReadExtraField() + { + _readExtraDepth++; + // workitem 8098: ok (restore) + long posn = this.ArchiveStream.Position; + this.ArchiveStream.Seek(this._RelativeOffsetOfLocalHeader, SeekOrigin.Begin); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(this.ArchiveStream); + + byte[] block = new byte[30]; + this.ArchiveStream.Read(block, 0, block.Length); + int i = 26; + Int16 filenameLength = (short)(block[i++] + block[i++] * 256); + Int16 extraFieldLength = (short)(block[i++] + block[i++] * 256); + + // workitem 8098: ok (relative) + this.ArchiveStream.Seek(filenameLength, SeekOrigin.Current); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(this.ArchiveStream); + + ProcessExtraField(this.ArchiveStream, extraFieldLength); + + // workitem 8098: ok (restore) + this.ArchiveStream.Seek(posn, SeekOrigin.Begin); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(this.ArchiveStream); + _readExtraDepth--; + } + + + private static bool ReadHeader(ZipEntry ze, System.Text.Encoding defaultEncoding) + { + int bytesRead = 0; + + // change for workitem 8098 + ze._RelativeOffsetOfLocalHeader = ze.ArchiveStream.Position; + + int signature = Ionic.Zip.SharedUtilities.ReadEntrySignature(ze.ArchiveStream); + bytesRead += 4; + + // Return false if this is not a local file header signature. + if (ZipEntry.IsNotValidSig(signature)) + { + // Getting "not a ZipEntry signature" is not always wrong or an error. + // This will happen after the last entry in a zipfile. In that case, we + // expect to read : + // a ZipDirEntry signature (if a non-empty zip file) or + // a ZipConstants.EndOfCentralDirectorySignature. + // + // Anything else is a surprise. + + ze.ArchiveStream.Seek(-4, SeekOrigin.Current); // unread the signature + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(ze.ArchiveStream); + if (ZipEntry.IsNotValidZipDirEntrySig(signature) && (signature != ZipConstants.EndOfCentralDirectorySignature)) + { + throw new BadReadException(String.Format(" Bad signature (0x{0:X8}) at position 0x{1:X8}", signature, ze.ArchiveStream.Position)); + } + return false; + } + + byte[] block = new byte[26]; + int n = ze.ArchiveStream.Read(block, 0, block.Length); + if (n != block.Length) return false; + bytesRead += n; + + int i = 0; + ze._VersionNeeded = (Int16)(block[i++] + block[i++] * 256); + ze._BitField = (Int16)(block[i++] + block[i++] * 256); + ze._CompressionMethod_FromZipFile = ze._CompressionMethod = (Int16)(block[i++] + block[i++] * 256); + ze._TimeBlob = block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256; + // transform the time data into something usable (a DateTime) + ze._LastModified = Ionic.Zip.SharedUtilities.PackedToDateTime(ze._TimeBlob); + ze._timestamp |= ZipEntryTimestamp.DOS; + + if ((ze._BitField & 0x01) == 0x01) + { + ze._Encryption_FromZipFile = ze._Encryption = EncryptionAlgorithm.PkzipWeak; // this *may* change after processing the Extra field + ze._sourceIsEncrypted = true; + } + + // NB: if ((ze._BitField & 0x0008) != 0x0008), then the Compressed, uncompressed and + // CRC values are not true values; the true values will follow the entry data. + // But, regardless of the status of bit 3 in the bitfield, the slots for + // the three amigos may contain marker values for ZIP64. So we must read them. + { + ze._Crc32 = (Int32)(block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256); + ze._CompressedSize = (uint)(block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256); + ze._UncompressedSize = (uint)(block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256); + + if ((uint)ze._CompressedSize == 0xFFFFFFFF || + (uint)ze._UncompressedSize == 0xFFFFFFFF) + + ze._InputUsesZip64 = true; + } + + Int16 filenameLength = (short)(block[i++] + block[i++] * 256); + Int16 extraFieldLength = (short)(block[i++] + block[i++] * 256); + + block = new byte[filenameLength]; + n = ze.ArchiveStream.Read(block, 0, block.Length); + bytesRead += n; + + // if the UTF8 bit is set for this entry, override the + // encoding the application requested. + + if ((ze._BitField & 0x0800) == 0x0800) + { + // workitem 12744 + ze.AlternateEncoding = System.Text.Encoding.UTF8; + ze.AlternateEncodingUsage = ZipOption.Always; + } + + // need to use this form of GetString() for .NET CF + ze._FileNameInArchive = ze.AlternateEncoding.GetString(block, 0, block.Length); + + // workitem 6898 + if (ze._FileNameInArchive.EndsWith("/")) ze.MarkAsDirectory(); + + bytesRead += ze.ProcessExtraField(ze.ArchiveStream, extraFieldLength); + + ze._LengthOfTrailer = 0; + + // workitem 6607 - don't read for directories + // actually get the compressed size and CRC if necessary + if (!ze._FileNameInArchive.EndsWith("/") && (ze._BitField & 0x0008) == 0x0008) + { + // This descriptor exists only if bit 3 of the general + // purpose bit flag is set (see below). It is byte aligned + // and immediately follows the last byte of compressed data, + // as well as any encryption trailer, as with AES. + // This descriptor is used only when it was not possible to + // seek in the output .ZIP file, e.g., when the output .ZIP file + // was standard output or a non-seekable device. For ZIP64(tm) format + // archives, the compressed and uncompressed sizes are 8 bytes each. + + // workitem 8098: ok (restore) + long posn = ze.ArchiveStream.Position; + + // Here, we're going to loop until we find a ZipEntryDataDescriptorSignature and + // a consistent data record after that. To be consistent, the data record must + // indicate the length of the entry data. + bool wantMore = true; + long SizeOfDataRead = 0; + int tries = 0; + while (wantMore) + { + tries++; + // We call the FindSignature shared routine to find the specified signature + // in the already-opened zip archive, starting from the current cursor + // position in that filestream. If we cannot find the signature, then the + // routine returns -1, and the ReadHeader() method returns false, + // indicating we cannot read a legal entry header. If we have found it, + // then the FindSignature() method returns the number of bytes in the + // stream we had to seek forward, to find the sig. We need this to + // determine if the zip entry is valid, later. + + if (ze._container.ZipFile != null) + ze._container.ZipFile.OnReadBytes(ze); + + long d = Ionic.Zip.SharedUtilities.FindSignature(ze.ArchiveStream, ZipConstants.ZipEntryDataDescriptorSignature); + if (d == -1) return false; + + // total size of data read (through all loops of this). + SizeOfDataRead += d; + + if (ze._InputUsesZip64) + { + // read 1x 4-byte (CRC) and 2x 8-bytes (Compressed Size, Uncompressed Size) + block = new byte[20]; + n = ze.ArchiveStream.Read(block, 0, block.Length); + if (n != 20) return false; + + // do not increment bytesRead - it is for entry header only. + // the data we have just read is a footer (falls after the file data) + //bytesRead += n; + + i = 0; + ze._Crc32 = (Int32)(block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256); + ze._CompressedSize = BitConverter.ToInt64(block, i); + i += 8; + ze._UncompressedSize = BitConverter.ToInt64(block, i); + i += 8; + + ze._LengthOfTrailer += 24; // bytes including sig, CRC, Comp and Uncomp sizes + } + else + { + // read 3x 4-byte fields (CRC, Compressed Size, Uncompressed Size) + block = new byte[12]; + n = ze.ArchiveStream.Read(block, 0, block.Length); + if (n != 12) return false; + + // do not increment bytesRead - it is for entry header only. + // the data we have just read is a footer (falls after the file data) + //bytesRead += n; + + i = 0; + ze._Crc32 = (Int32)(block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256); + ze._CompressedSize = (uint)(block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256); + ze._UncompressedSize = (uint)(block[i++] + block[i++] * 256 + block[i++] * 256 * 256 + block[i++] * 256 * 256 * 256); + + ze._LengthOfTrailer += 16; // bytes including sig, CRC, Comp and Uncomp sizes + + } + + wantMore = (SizeOfDataRead != ze._CompressedSize); + + if (wantMore) + { + // Seek back to un-read the last 12 bytes - maybe THEY contain + // the ZipEntryDataDescriptorSignature. + // (12 bytes for the CRC, Comp and Uncomp size.) + ze.ArchiveStream.Seek(-12, SeekOrigin.Current); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(ze.ArchiveStream); + + // Adjust the size to account for the false signature read in + // FindSignature(). + SizeOfDataRead += 4; + } + } + + // seek back to previous position, to prepare to read file data + // workitem 8098: ok (restore) + ze.ArchiveStream.Seek(posn, SeekOrigin.Begin); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(ze.ArchiveStream); + } + + ze._CompressedFileDataSize = ze._CompressedSize; + + + // bit 0 set indicates that some kind of encryption is in use + if ((ze._BitField & 0x01) == 0x01) + { +#if AESCRYPTO + if (ze.Encryption == EncryptionAlgorithm.WinZipAes128 || + ze.Encryption == EncryptionAlgorithm.WinZipAes256) + { + int bits = ZipEntry.GetKeyStrengthInBits(ze._Encryption_FromZipFile); + // read in the WinZip AES metadata: salt + PV. 18 bytes for AES256. 10 bytes for AES128. + ze._aesCrypto_forExtract = WinZipAesCrypto.ReadFromStream(null, bits, ze.ArchiveStream); + bytesRead += ze._aesCrypto_forExtract.SizeOfEncryptionMetadata - 10; // MAC (follows crypto bytes) + // according to WinZip, the CompressedSize includes the AES Crypto framing data. + ze._CompressedFileDataSize -= ze._aesCrypto_forExtract.SizeOfEncryptionMetadata; + ze._LengthOfTrailer += 10; // MAC + } + else +#endif + { + // read in the header data for "weak" encryption + ze._WeakEncryptionHeader = new byte[12]; + bytesRead += ZipEntry.ReadWeakEncryptionHeader(ze._archiveStream, ze._WeakEncryptionHeader); + // decrease the filedata size by 12 bytes + ze._CompressedFileDataSize -= 12; + } + } + + // Remember the size of the blob for this entry. + // We also have the starting position in the stream for this entry. + ze._LengthOfHeader = bytesRead; + ze._TotalEntrySize = ze._LengthOfHeader + ze._CompressedFileDataSize + ze._LengthOfTrailer; + + + // We've read in the regular entry header, the extra field, and any + // encryption header. The pointer in the file is now at the start of the + // filedata, which is potentially compressed and encrypted. Just ahead in + // the file, there are _CompressedFileDataSize bytes of data, followed by + // potentially a non-zero length trailer, consisting of optionally, some + // encryption stuff (10 byte MAC for AES), and the bit-3 trailer (16 or 24 + // bytes). + + return true; + } + + + + internal static int ReadWeakEncryptionHeader(Stream s, byte[] buffer) + { + // PKZIP encrypts the compressed data stream. Encrypted files must + // be decrypted before they can be extracted. + + // Each PKZIP-encrypted file has an extra 12 bytes stored at the start of the data + // area defining the encryption header for that file. The encryption header is + // originally set to random values, and then itself encrypted, using three, 32-bit + // keys. The key values are initialized using the supplied encryption password. + // After each byte is encrypted, the keys are then updated using pseudo-random + // number generation techniques in combination with the same CRC-32 algorithm used + // in PKZIP and implemented in the CRC32.cs module in this project. + + // read the 12-byte encryption header + int additionalBytesRead = s.Read(buffer, 0, 12); + if (additionalBytesRead != 12) + throw new ZipException(String.Format("Unexpected end of data at position 0x{0:X8}", s.Position)); + + return additionalBytesRead; + } + + + + private static bool IsNotValidSig(int signature) + { + return (signature != ZipConstants.ZipEntrySignature); + } + + + /// + /// Reads one ZipEntry from the given stream. The content for + /// the entry does not get decompressed or decrypted. This method + /// basically reads metadata, and seeks. + /// + /// the ZipContainer this entry belongs to. + /// + /// true of this is the first entry being read from the stream. + /// + /// the ZipEntry read from the stream. + internal static ZipEntry ReadEntry(ZipContainer zc, bool first) + { + ZipFile zf = zc.ZipFile; + Stream s = zc.ReadStream; + System.Text.Encoding defaultEncoding = zc.AlternateEncoding; + ZipEntry entry = new ZipEntry(); + entry._Source = ZipEntrySource.ZipFile; + entry._container = zc; + entry._archiveStream = s; + if (zf != null) + zf.OnReadEntry(true, null); + + if (first) HandlePK00Prefix(s); + + // Read entry header, including any encryption header + if (!ReadHeader(entry, defaultEncoding)) return null; + + // Store the position in the stream for this entry + // change for workitem 8098 + entry.__FileDataPosition = entry.ArchiveStream.Position; + + // seek past the data without reading it. We will read on Extract() + s.Seek(entry._CompressedFileDataSize + entry._LengthOfTrailer, SeekOrigin.Current); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(s); + + // ReadHeader moves the file pointer to the end of the entry header, + // as well as any encryption header. + + // CompressedFileDataSize includes: + // the maybe compressed, maybe encrypted file data + // the encryption trailer, if any + // the bit 3 descriptor, if any + + // workitem 5306 + // http://www.codeplex.com/DotNetZip/WorkItem/View.aspx?WorkItemId=5306 + HandleUnexpectedDataDescriptor(entry); + + if (zf != null) + { + zf.OnReadBytes(entry); + zf.OnReadEntry(false, entry); + } + + return entry; + } + + + internal static void HandlePK00Prefix(Stream s) + { + // in some cases, the zip file begins with "PK00". This is a throwback and is rare, + // but we handle it anyway. We do not change behavior based on it. + uint datum = (uint)Ionic.Zip.SharedUtilities.ReadInt(s); + if (datum != ZipConstants.PackedToRemovableMedia) + { + s.Seek(-4, SeekOrigin.Current); // unread the block + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(s); + } + } + + + + private static void HandleUnexpectedDataDescriptor(ZipEntry entry) + { + Stream s = entry.ArchiveStream; + + // In some cases, the "data descriptor" is present, without a signature, even when + // bit 3 of the BitField is NOT SET. This is the CRC, followed + // by the compressed length and the uncompressed length (4 bytes for each + // of those three elements). Need to check that here. + // + uint datum = (uint)Ionic.Zip.SharedUtilities.ReadInt(s); + if (datum == entry._Crc32) + { + int sz = Ionic.Zip.SharedUtilities.ReadInt(s); + if (sz == entry._CompressedSize) + { + sz = Ionic.Zip.SharedUtilities.ReadInt(s); + if (sz == entry._UncompressedSize) + { + // ignore everything and discard it. + } + else + { + s.Seek(-12, SeekOrigin.Current); // unread the three blocks + + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(s); + } + } + else + { + s.Seek(-8, SeekOrigin.Current); // unread the two blocks + + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(s); + } + } + else + { + s.Seek(-4, SeekOrigin.Current); // unread the block + + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(s); + } + } + + + /// + /// Finds a particular segment in the given extra field. + /// This is used when modifying a previously-generated + /// extra field, in particular when removing the AES crypto + /// segment in the extra field. + /// + static internal int FindExtraFieldSegment(byte[] extra, int offx, UInt16 targetHeaderId) + { + int j = offx; + while (j + 3 < extra.Length) + { + UInt16 headerId = (UInt16)(extra[j++] + extra[j++] * 256); + if (headerId == targetHeaderId) return j-2; + + // else advance to next segment + Int16 dataSize = (short)(extra[j++] + extra[j++] * 256); + j+= dataSize; + } + + return -1; + } + + + /// + /// At current cursor position in the stream, read the extra + /// field, and set the properties on the ZipEntry instance + /// appropriately. This can be called when processing the + /// Extra field in the Central Directory, or in the local + /// header. + /// + internal int ProcessExtraField(Stream s, Int16 extraFieldLength) + { + int additionalBytesRead = 0; + if (extraFieldLength > 0) + { + byte[] buffer = this._Extra = new byte[extraFieldLength]; + additionalBytesRead = s.Read(buffer, 0, buffer.Length); + long posn = s.Position - additionalBytesRead; + int j = 0; + while (j + 3 < buffer.Length) + { + int start = j; + UInt16 headerId = (UInt16)(buffer[j++] + buffer[j++] * 256); + Int16 dataSize = (short)(buffer[j++] + buffer[j++] * 256); + + switch (headerId) + { + case 0x000a: // NTFS ctime, atime, mtime + j = ProcessExtraFieldWindowsTimes(buffer, j, dataSize, posn); + break; + + case 0x5455: // Unix ctime, atime, mtime + j = ProcessExtraFieldUnixTimes(buffer, j, dataSize, posn); + break; + + case 0x5855: // Info-zip Extra field (outdated) + // This is outdated, so the field is supported on + // read only. + j = ProcessExtraFieldInfoZipTimes(buffer, j, dataSize, posn); + break; + + case 0x7855: // Unix uid/gid + // ignored. DotNetZip does not handle this field. + break; + + case 0x7875: // ?? + // ignored. I could not find documentation on this field, + // though it appears in some zip files. + break; + + case 0x0001: // ZIP64 + j = ProcessExtraFieldZip64(buffer, j, dataSize, posn); + break; + +#if AESCRYPTO + case 0x9901: // WinZip AES encryption is in use. (workitem 6834) + // we will handle this extra field only if compressionmethod is 0x63 + j = ProcessExtraFieldWinZipAes(buffer, j, dataSize, posn); + break; +#endif + case 0x0017: // workitem 7968: handle PKWare Strong encryption header + j = ProcessExtraFieldPkwareStrongEncryption(buffer, j); + break; + } + + // move to the next Header in the extra field + j = start + dataSize + 4; + } + } + return additionalBytesRead; + } + + private int ProcessExtraFieldPkwareStrongEncryption(byte[] Buffer, int j) + { + // Value Size Description + // ----- ---- ----------- + // 0x0017 2 bytes Tag for this "extra" block type + // TSize 2 bytes Size of data that follows + // Format 2 bytes Format definition for this record + // AlgID 2 bytes Encryption algorithm identifier + // Bitlen 2 bytes Bit length of encryption key + // Flags 2 bytes Processing flags + // CertData TSize-8 Certificate decryption extra field data + // (refer to the explanation for CertData + // in the section describing the + // Certificate Processing Method under + // the Strong Encryption Specification) + + j += 2; + _UnsupportedAlgorithmId = (UInt16)(Buffer[j++] + Buffer[j++] * 256); + _Encryption_FromZipFile = _Encryption = EncryptionAlgorithm.Unsupported; + + // DotNetZip doesn't support this algorithm, but we don't need to throw + // here. we might just be reading the archive, which is fine. We'll + // need to throw if Extract() is called. + + return j; + } + + +#if AESCRYPTO + private int ProcessExtraFieldWinZipAes(byte[] buffer, int j, Int16 dataSize, long posn) + { + if (this._CompressionMethod == 0x0063) + { + if ((this._BitField & 0x01) != 0x01) + throw new BadReadException(String.Format(" Inconsistent metadata at position 0x{0:X16}", posn)); + + this._sourceIsEncrypted = true; + + //this._aesCrypto = new WinZipAesCrypto(this); + // see spec at http://www.winzip.com/aes_info.htm + if (dataSize != 7) + throw new BadReadException(String.Format(" Inconsistent size (0x{0:X4}) in WinZip AES field at position 0x{1:X16}", dataSize, posn)); + + this._WinZipAesMethod = BitConverter.ToInt16(buffer, j); + j += 2; + if (this._WinZipAesMethod != 0x01 && this._WinZipAesMethod != 0x02) + throw new BadReadException(String.Format(" Unexpected vendor version number (0x{0:X4}) for WinZip AES metadata at position 0x{1:X16}", + this._WinZipAesMethod, posn)); + + Int16 vendorId = BitConverter.ToInt16(buffer, j); + j += 2; + if (vendorId != 0x4541) + throw new BadReadException(String.Format(" Unexpected vendor ID (0x{0:X4}) for WinZip AES metadata at position 0x{1:X16}", vendorId, posn)); + + int keystrength = (buffer[j] == 1) ? 128 : (buffer[j] == 3) ? 256 : -1; + if (keystrength < 0) + throw new BadReadException(String.Format("Invalid key strength ({0})", keystrength)); + + _Encryption_FromZipFile = this._Encryption = (keystrength == 128) + ? EncryptionAlgorithm.WinZipAes128 + : EncryptionAlgorithm.WinZipAes256; + + j++; + + // set the actual compression method + this._CompressionMethod_FromZipFile = + this._CompressionMethod = BitConverter.ToInt16(buffer, j); + j += 2; // for the next segment of the extra field + } + return j; + } + +#endif + + private delegate T Func(); + + private int ProcessExtraFieldZip64(byte[] buffer, int j, Int16 dataSize, long posn) + { + // The PKWare spec says that any of {UncompressedSize, CompressedSize, + // RelativeOffset} exceeding 0xFFFFFFFF can lead to the ZIP64 header, + // and the ZIP64 header may contain one or more of those. If the + // values are present, they will be found in the prescribed order. + // There may also be a 4-byte "disk start number." + // This means that the DataSize must be 28 bytes or less. + + this._InputUsesZip64 = true; + + // workitem 7941: check datasize before reading. + if (dataSize > 28) + throw new BadReadException(String.Format(" Inconsistent size (0x{0:X4}) for ZIP64 extra field at position 0x{1:X16}", + dataSize, posn)); + int remainingData = dataSize; + + var slurp = new Func( () => { + if (remainingData < 8) + throw new BadReadException(String.Format(" Missing data for ZIP64 extra field, position 0x{0:X16}", posn)); + var x = BitConverter.ToInt64(buffer, j); + j+= 8; + remainingData -= 8; + return x; + }); + + if (this._UncompressedSize == 0xFFFFFFFF) + this._UncompressedSize = slurp(); + + if (this._CompressedSize == 0xFFFFFFFF) + this._CompressedSize = slurp(); + + if (this._RelativeOffsetOfLocalHeader == 0xFFFFFFFF) + this._RelativeOffsetOfLocalHeader = slurp(); + + // Ignore anything else. Potentially there are 4 more bytes for the + // disk start number. DotNetZip currently doesn't handle multi-disk + // archives. + return j; + } + + + private int ProcessExtraFieldInfoZipTimes(byte[] buffer, int j, Int16 dataSize, long posn) + { + if (dataSize != 12 && dataSize != 8) + throw new BadReadException(String.Format(" Unexpected size (0x{0:X4}) for InfoZip v1 extra field at position 0x{1:X16}", dataSize, posn)); + + Int32 timet = BitConverter.ToInt32(buffer, j); + this._Mtime = _unixEpoch.AddSeconds(timet); + j += 4; + + timet = BitConverter.ToInt32(buffer, j); + this._Atime = _unixEpoch.AddSeconds(timet); + j += 4; + + this._Ctime = DateTime.UtcNow; + + _ntfsTimesAreSet = true; + _timestamp |= ZipEntryTimestamp.InfoZip1; return j; + } + + + + private int ProcessExtraFieldUnixTimes(byte[] buffer, int j, Int16 dataSize, long posn) + { + // The Unix filetimes are 32-bit unsigned integers, + // storing seconds since Unix epoch. + + if (dataSize != 13 && dataSize != 9 && dataSize != 5) + throw new BadReadException(String.Format(" Unexpected size (0x{0:X4}) for Extended Timestamp extra field at position 0x{1:X16}", dataSize, posn)); + + int remainingData = dataSize; + + var slurp = new Func( () => { + Int32 timet = BitConverter.ToInt32(buffer, j); + j += 4; + remainingData -= 4; + return _unixEpoch.AddSeconds(timet); + }); + + if (dataSize == 13 || _readExtraDepth > 0) + { + byte flag = buffer[j++]; + remainingData--; + + if ((flag & 0x0001) != 0 && remainingData >= 4) + this._Mtime = slurp(); + + this._Atime = ((flag & 0x0002) != 0 && remainingData >= 4) + ? slurp() + : DateTime.UtcNow; + + this._Ctime = ((flag & 0x0004) != 0 && remainingData >= 4) + ? slurp() + :DateTime.UtcNow; + + _timestamp |= ZipEntryTimestamp.Unix; + _ntfsTimesAreSet = true; + _emitUnixTimes = true; + } + else + ReadExtraField(); // will recurse + + return j; + } + + + private int ProcessExtraFieldWindowsTimes(byte[] buffer, int j, Int16 dataSize, long posn) + { + // The NTFS filetimes are 64-bit unsigned integers, stored in Intel + // (least significant byte first) byte order. They are expressed as the + // number of 1.0E-07 seconds (1/10th microseconds!) past WinNT "epoch", + // which is "01-Jan-1601 00:00:00 UTC". + // + // HeaderId 2 bytes 0x000a == NTFS stuff + // Datasize 2 bytes ?? (usually 32) + // reserved 4 bytes ?? + // timetag 2 bytes 0x0001 == time + // size 2 bytes 24 == 8 bytes each for ctime, mtime, atime + // mtime 8 bytes win32 ticks since win32epoch + // atime 8 bytes win32 ticks since win32epoch + // ctime 8 bytes win32 ticks since win32epoch + + if (dataSize != 32) + throw new BadReadException(String.Format(" Unexpected size (0x{0:X4}) for NTFS times extra field at position 0x{1:X16}", dataSize, posn)); + + j += 4; // reserved + Int16 timetag = (Int16)(buffer[j] + buffer[j + 1] * 256); + Int16 addlsize = (Int16)(buffer[j + 2] + buffer[j + 3] * 256); + j += 4; // tag and size + + if (timetag == 0x0001 && addlsize == 24) + { + Int64 z = BitConverter.ToInt64(buffer, j); + this._Mtime = DateTime.FromFileTimeUtc(z); + j += 8; + + // At this point the library *could* set the LastModified value + // to coincide with the Mtime value. In theory, they refer to + // the same property of the file, and should be the same anyway, + // allowing for differences in precision. But they are + // independent quantities in the zip archive, and this library + // will keep them separate in the object model. There is no ill + // effect from this, because as files are extracted, the + // higher-precision value (Mtime) is used if it is present. + // Apps may wish to compare the Mtime versus LastModified + // values, but any difference when both are present is not + // germaine to the correctness of the library. but note: when + // explicitly setting either value, both are set. See the setter + // for LastModified or the SetNtfsTimes() method. + + z = BitConverter.ToInt64(buffer, j); + this._Atime = DateTime.FromFileTimeUtc(z); + j += 8; + + z = BitConverter.ToInt64(buffer, j); + this._Ctime = DateTime.FromFileTimeUtc(z); + j += 8; + + _ntfsTimesAreSet = true; + _timestamp |= ZipEntryTimestamp.Windows; + _emitNtfsTimes = true; + } + return j; + } + + + } +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipEntry.Write.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipEntry.Write.cs new file mode 100644 index 00000000..1106de42 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipEntry.Write.cs @@ -0,0 +1,2582 @@ +//#define Trace + +// ZipEntry.Write.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009-2011 Dino Chiesa +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// Last Saved: <2011-July-30 14:55:47> +// +// ------------------------------------------------------------------ +// +// This module defines logic for writing (saving) the ZipEntry into a +// zip file. +// +// ------------------------------------------------------------------ + + +using System; +using System.IO; +using RE = System.Text.RegularExpressions; + +namespace Ionic.Zip +{ + public partial class ZipEntry + { + internal void WriteCentralDirectoryEntry(Stream s) + { + byte[] bytes = new byte[4096]; + int i = 0; + // signature + bytes[i++] = (byte)(ZipConstants.ZipDirEntrySignature & 0x000000FF); + bytes[i++] = (byte)((ZipConstants.ZipDirEntrySignature & 0x0000FF00) >> 8); + bytes[i++] = (byte)((ZipConstants.ZipDirEntrySignature & 0x00FF0000) >> 16); + bytes[i++] = (byte)((ZipConstants.ZipDirEntrySignature & 0xFF000000) >> 24); + + // Version Made By + // workitem 7071 + // We must not overwrite the VersionMadeBy field when writing out a zip + // archive. The VersionMadeBy tells the zip reader the meaning of the + // File attributes. Overwriting the VersionMadeBy will result in + // inconsistent metadata. Consider the scenario where the application + // opens and reads a zip file that had been created on Linux. Then the + // app adds one file to the Zip archive, and saves it. The file + // attributes for all the entries added on Linux will be significant for + // Linux. Therefore the VersionMadeBy for those entries must not be + // changed. Only the entries that are actually created on Windows NTFS + // should get the VersionMadeBy indicating Windows/NTFS. + bytes[i++] = (byte)(_VersionMadeBy & 0x00FF); + bytes[i++] = (byte)((_VersionMadeBy & 0xFF00) >> 8); + + // Apparently we want to duplicate the extra field here; we cannot + // simply zero it out and assume tools and apps will use the right one. + + ////Int16 extraFieldLengthSave = (short)(_EntryHeader[28] + _EntryHeader[29] * 256); + ////_EntryHeader[28] = 0; + ////_EntryHeader[29] = 0; + + // Version Needed, Bitfield, compression method, lastmod, + // crc, compressed and uncompressed sizes, filename length and extra field length. + // These are all present in the local file header, but they may be zero values there. + // So we cannot just copy them. + + // workitem 11969: Version Needed To Extract in central directory must be + // the same as the local entry or MS .NET System.IO.Zip fails read. + Int16 vNeeded = (Int16)(VersionNeeded != 0 ? VersionNeeded : 20); + // workitem 12964 + if (_OutputUsesZip64==null) + { + // a zipentry in a zipoutputstream, with zero bytes written + _OutputUsesZip64 = new Nullable(_container.Zip64 == Zip64Option.Always); + } + + Int16 versionNeededToExtract = (Int16)(_OutputUsesZip64.Value ? 45 : vNeeded); +#if BZIP + if (this.CompressionMethod == Ionic.Zip.CompressionMethod.BZip2) + versionNeededToExtract = 46; +#endif + + bytes[i++] = (byte)(versionNeededToExtract & 0x00FF); + bytes[i++] = (byte)((versionNeededToExtract & 0xFF00) >> 8); + + bytes[i++] = (byte)(_BitField & 0x00FF); + bytes[i++] = (byte)((_BitField & 0xFF00) >> 8); + + bytes[i++] = (byte)(_CompressionMethod & 0x00FF); + bytes[i++] = (byte)((_CompressionMethod & 0xFF00) >> 8); + +#if AESCRYPTO + if (Encryption == EncryptionAlgorithm.WinZipAes128 || + Encryption == EncryptionAlgorithm.WinZipAes256) + { + i -= 2; + bytes[i++] = 0x63; + bytes[i++] = 0; + } +#endif + + bytes[i++] = (byte)(_TimeBlob & 0x000000FF); + bytes[i++] = (byte)((_TimeBlob & 0x0000FF00) >> 8); + bytes[i++] = (byte)((_TimeBlob & 0x00FF0000) >> 16); + bytes[i++] = (byte)((_TimeBlob & 0xFF000000) >> 24); + bytes[i++] = (byte)(_Crc32 & 0x000000FF); + bytes[i++] = (byte)((_Crc32 & 0x0000FF00) >> 8); + bytes[i++] = (byte)((_Crc32 & 0x00FF0000) >> 16); + bytes[i++] = (byte)((_Crc32 & 0xFF000000) >> 24); + + int j = 0; + if (_OutputUsesZip64.Value) + { + // CompressedSize (Int32) and UncompressedSize - all 0xFF + for (j = 0; j < 8; j++) + bytes[i++] = 0xFF; + } + else + { + bytes[i++] = (byte)(_CompressedSize & 0x000000FF); + bytes[i++] = (byte)((_CompressedSize & 0x0000FF00) >> 8); + bytes[i++] = (byte)((_CompressedSize & 0x00FF0000) >> 16); + bytes[i++] = (byte)((_CompressedSize & 0xFF000000) >> 24); + + bytes[i++] = (byte)(_UncompressedSize & 0x000000FF); + bytes[i++] = (byte)((_UncompressedSize & 0x0000FF00) >> 8); + bytes[i++] = (byte)((_UncompressedSize & 0x00FF0000) >> 16); + bytes[i++] = (byte)((_UncompressedSize & 0xFF000000) >> 24); + } + + byte[] fileNameBytes = GetEncodedFileNameBytes(); + Int16 filenameLength = (Int16)fileNameBytes.Length; + bytes[i++] = (byte)(filenameLength & 0x00FF); + bytes[i++] = (byte)((filenameLength & 0xFF00) >> 8); + + // do this again because now we have real data + _presumeZip64 = _OutputUsesZip64.Value; + + // workitem 11131 + // + // cannot generate the extra field again, here's why: In the case of a + // zero-byte entry, which uses encryption, DotNetZip will "remove" the + // encryption from the entry. It does this in PostProcessOutput; it + // modifies the entry header, and rewrites it, resetting the Bitfield + // (one bit indicates encryption), and potentially resetting the + // compression method - for AES the Compression method is 0x63, and it + // would get reset to zero (no compression). It then calls SetLength() + // to truncate the stream to remove the encryption header (12 bytes for + // AES256). But, it leaves the previously-generated "Extra Field" + // metadata (11 bytes) for AES in the entry header. This extra field + // data is now "orphaned" - it refers to AES encryption when in fact no + // AES encryption is used. But no problem, the PKWARE spec says that + // unrecognized extra fields can just be ignored. ok. After "removal" + // of AES encryption, the length of the Extra Field can remains the + // same; it's just that there will be 11 bytes in there that previously + // pertained to AES which are now unused. Even the field code is still + // there, but it will be unused by readers, as the encryption bit is not + // set. + // + // Re-calculating the Extra field now would produce a block that is 11 + // bytes shorter, and that mismatch - between the extra field in the + // local header and the extra field in the Central Directory - would + // cause problems. (where? why? what problems?) So we can't do + // that. It's all good though, because though the content may have + // changed, the length definitely has not. Also, the _EntryHeader + // contains the "updated" extra field (after PostProcessOutput) at + // offset (30 + filenameLength). + + _Extra = ConstructExtraField(true); + + Int16 extraFieldLength = (Int16)((_Extra == null) ? 0 : _Extra.Length); + bytes[i++] = (byte)(extraFieldLength & 0x00FF); + bytes[i++] = (byte)((extraFieldLength & 0xFF00) >> 8); + + // File (entry) Comment Length + // the _CommentBytes private field was set during WriteHeader() + int commentLength = (_CommentBytes == null) ? 0 : _CommentBytes.Length; + + // the size of our buffer defines the max length of the comment we can write + if (commentLength + i > bytes.Length) commentLength = bytes.Length - i; + bytes[i++] = (byte)(commentLength & 0x00FF); + bytes[i++] = (byte)((commentLength & 0xFF00) >> 8); + + // Disk number start + bool segmented = (this._container.ZipFile != null) && + (this._container.ZipFile.MaxOutputSegmentSize != 0); + if (segmented) // workitem 13915 + { + // Emit nonzero disknumber only if saving segmented archive. + bytes[i++] = (byte)(_diskNumber & 0x00FF); + bytes[i++] = (byte)((_diskNumber & 0xFF00) >> 8); + } + else + { + // If reading a segmneted archive and saving to a regular archive, + // ZipEntry._diskNumber will be non-zero but it should be saved as + // zero. + bytes[i++] = 0; + bytes[i++] = 0; + } + + // internal file attrs + // workitem 7801 + bytes[i++] = (byte)((_IsText) ? 1 : 0); // lo bit: filetype hint. 0=bin, 1=txt. + bytes[i++] = 0; + + // external file attrs + // workitem 7071 + bytes[i++] = (byte)(_ExternalFileAttrs & 0x000000FF); + bytes[i++] = (byte)((_ExternalFileAttrs & 0x0000FF00) >> 8); + bytes[i++] = (byte)((_ExternalFileAttrs & 0x00FF0000) >> 16); + bytes[i++] = (byte)((_ExternalFileAttrs & 0xFF000000) >> 24); + + // workitem 11131 + // relative offset of local header. + // + // If necessary to go to 64-bit value, then emit 0xFFFFFFFF, + // else write out the value. + // + // Even if zip64 is required for other reasons - number of the entry + // > 65534, or uncompressed size of the entry > MAX_INT32, the ROLH + // need not be stored in a 64-bit field . + if (_RelativeOffsetOfLocalHeader > 0xFFFFFFFFL) // _OutputUsesZip64.Value + { + bytes[i++] = 0xFF; + bytes[i++] = 0xFF; + bytes[i++] = 0xFF; + bytes[i++] = 0xFF; + } + else + { + bytes[i++] = (byte)(_RelativeOffsetOfLocalHeader & 0x000000FF); + bytes[i++] = (byte)((_RelativeOffsetOfLocalHeader & 0x0000FF00) >> 8); + bytes[i++] = (byte)((_RelativeOffsetOfLocalHeader & 0x00FF0000) >> 16); + bytes[i++] = (byte)((_RelativeOffsetOfLocalHeader & 0xFF000000) >> 24); + } + + // actual filename + Buffer.BlockCopy(fileNameBytes, 0, bytes, i, filenameLength); + i += filenameLength; + + // "Extra field" + if (_Extra != null) + { + // workitem 11131 + // + // copy from EntryHeader if available - it may have been updated. + // if not, copy from Extra. This would be unnecessary if I just + // updated the Extra field when updating EntryHeader, in + // PostProcessOutput. + + //?? I don't understand why I wouldn't want to just use + // the recalculated Extra field. ?? + + // byte[] h = _EntryHeader ?? _Extra; + // int offx = (h == _EntryHeader) ? 30 + filenameLength : 0; + // Buffer.BlockCopy(h, offx, bytes, i, extraFieldLength); + // i += extraFieldLength; + + byte[] h = _Extra; + int offx = 0; + Buffer.BlockCopy(h, offx, bytes, i, extraFieldLength); + i += extraFieldLength; + } + + // file (entry) comment + if (commentLength != 0) + { + // now actually write the comment itself into the byte buffer + Buffer.BlockCopy(_CommentBytes, 0, bytes, i, commentLength); + // for (j = 0; (j < commentLength) && (i + j < bytes.Length); j++) + // bytes[i + j] = _CommentBytes[j]; + i += commentLength; + } + + s.Write(bytes, 0, i); + } + + +#if INFOZIP_UTF8 + static private bool FileNameIsUtf8(char[] FileNameChars) + { + bool isUTF8 = false; + bool isUnicode = false; + for (int j = 0; j < FileNameChars.Length; j++) + { + byte[] b = System.BitConverter.GetBytes(FileNameChars[j]); + isUnicode |= (b.Length != 2); + isUnicode |= (b[1] != 0); + isUTF8 |= ((b[0] & 0x80) != 0); + } + + return isUTF8; + } +#endif + + + private byte[] ConstructExtraField(bool forCentralDirectory) + { + var listOfBlocks = new System.Collections.Generic.List(); + byte[] block; + + // Conditionally emit an extra field with Zip64 information. If the + // Zip64 option is Always, we emit the field, before knowing that it's + // necessary. Later, if it turns out this entry does not need zip64, + // we'll set the header ID to rubbish and the data will be ignored. + // This results in additional overhead metadata in the zip file, but + // it will be small in comparison to the entry data. + // + // On the other hand if the Zip64 option is AsNecessary and it's NOT + // for the central directory, then we do the same thing. Or, if the + // Zip64 option is AsNecessary and it IS for the central directory, + // and the entry requires zip64, then emit the header. + if (_container.Zip64 == Zip64Option.Always || + (_container.Zip64 == Zip64Option.AsNecessary && + (!forCentralDirectory || _entryRequiresZip64.Value))) + { + // add extra field for zip64 here + // workitem 7924 + int sz = 4 + (forCentralDirectory ? 28 : 16); + block = new byte[sz]; + int i = 0; + + if (_presumeZip64 || forCentralDirectory) + { + // HeaderId = always use zip64 extensions. + block[i++] = 0x01; + block[i++] = 0x00; + } + else + { + // HeaderId = dummy data now, maybe set to 0x0001 (ZIP64) later. + block[i++] = 0x99; + block[i++] = 0x99; + } + + // DataSize + block[i++] = (byte)(sz - 4); // decimal 28 or 16 (workitem 7924) + block[i++] = 0x00; + + // The actual metadata - we may or may not have real values yet... + + // uncompressed size + Array.Copy(BitConverter.GetBytes(_UncompressedSize), 0, block, i, 8); + i += 8; + // compressed size + Array.Copy(BitConverter.GetBytes(_CompressedSize), 0, block, i, 8); + i += 8; + + // workitem 7924 - only include this if the "extra" field is for + // use in the central directory. It is unnecessary and not useful + // for local header; makes WinZip choke. + if (forCentralDirectory) + { + // relative offset + Array.Copy(BitConverter.GetBytes(_RelativeOffsetOfLocalHeader), 0, block, i, 8); + i += 8; + + // starting disk number + Array.Copy(BitConverter.GetBytes(0), 0, block, i, 4); + } + listOfBlocks.Add(block); + } + + +#if AESCRYPTO + if (Encryption == EncryptionAlgorithm.WinZipAes128 || + Encryption == EncryptionAlgorithm.WinZipAes256) + { + block = new byte[4 + 7]; + int i = 0; + // extra field for WinZip AES + // header id + block[i++] = 0x01; + block[i++] = 0x99; + + // data size + block[i++] = 0x07; + block[i++] = 0x00; + + // vendor number + block[i++] = 0x01; // AE-1 - means "Verify CRC" + block[i++] = 0x00; + + // vendor id "AE" + block[i++] = 0x41; + block[i++] = 0x45; + + // key strength + int keystrength = GetKeyStrengthInBits(Encryption); + if (keystrength == 128) + block[i] = 1; + else if (keystrength == 256) + block[i] = 3; + else + block[i] = 0xFF; + i++; + + // actual compression method + block[i++] = (byte)(_CompressionMethod & 0x00FF); + block[i++] = (byte)(_CompressionMethod & 0xFF00); + + listOfBlocks.Add(block); + } +#endif + + if (_ntfsTimesAreSet && _emitNtfsTimes) + { + block = new byte[32 + 4]; + // HeaderId 2 bytes 0x000a == NTFS times + // Datasize 2 bytes 32 + // reserved 4 bytes ?? don't care + // timetag 2 bytes 0x0001 == NTFS time + // size 2 bytes 24 == 8 bytes each for ctime, mtime, atime + // mtime 8 bytes win32 ticks since win32epoch + // atime 8 bytes win32 ticks since win32epoch + // ctime 8 bytes win32 ticks since win32epoch + int i = 0; + // extra field for NTFS times + // header id + block[i++] = 0x0a; + block[i++] = 0x00; + + // data size + block[i++] = 32; + block[i++] = 0; + + i += 4; // reserved + + // time tag + block[i++] = 0x01; + block[i++] = 0x00; + + // data size (again) + block[i++] = 24; + block[i++] = 0; + + Int64 z = _Mtime.ToFileTime(); + Array.Copy(BitConverter.GetBytes(z), 0, block, i, 8); + i += 8; + z = _Atime.ToFileTime(); + Array.Copy(BitConverter.GetBytes(z), 0, block, i, 8); + i += 8; + z = _Ctime.ToFileTime(); + Array.Copy(BitConverter.GetBytes(z), 0, block, i, 8); + i += 8; + + listOfBlocks.Add(block); + } + + if (_ntfsTimesAreSet && _emitUnixTimes) + { + int len = 5 + 4; + if (!forCentralDirectory) len += 8; + + block = new byte[len]; + // local form: + // -------------- + // HeaderId 2 bytes 0x5455 == unix timestamp + // Datasize 2 bytes 13 + // flags 1 byte 7 (low three bits all set) + // mtime 4 bytes seconds since unix epoch + // atime 4 bytes seconds since unix epoch + // ctime 4 bytes seconds since unix epoch + // + // central directory form: + //--------------------------------- + // HeaderId 2 bytes 0x5455 == unix timestamp + // Datasize 2 bytes 5 + // flags 1 byte 7 (low three bits all set) + // mtime 4 bytes seconds since unix epoch + // + int i = 0; + // extra field for "unix" times + // header id + block[i++] = 0x55; + block[i++] = 0x54; + + // data size + block[i++] = unchecked((byte)(len - 4)); + block[i++] = 0; + + // flags + block[i++] = 0x07; + + Int32 z = unchecked((int)((_Mtime - _unixEpoch).TotalSeconds)); + Array.Copy(BitConverter.GetBytes(z), 0, block, i, 4); + i += 4; + if (!forCentralDirectory) + { + z = unchecked((int)((_Atime - _unixEpoch).TotalSeconds)); + Array.Copy(BitConverter.GetBytes(z), 0, block, i, 4); + i += 4; + z = unchecked((int)((_Ctime - _unixEpoch).TotalSeconds)); + Array.Copy(BitConverter.GetBytes(z), 0, block, i, 4); + i += 4; + } + listOfBlocks.Add(block); + } + + + // inject other blocks here... + + + // concatenate any blocks we've got: + byte[] aggregateBlock = null; + if (listOfBlocks.Count > 0) + { + int totalLength = 0; + int i, current = 0; + for (i = 0; i < listOfBlocks.Count; i++) + totalLength += listOfBlocks[i].Length; + aggregateBlock = new byte[totalLength]; + for (i = 0; i < listOfBlocks.Count; i++) + { + System.Array.Copy(listOfBlocks[i], 0, aggregateBlock, current, listOfBlocks[i].Length); + current += listOfBlocks[i].Length; + } + } + + return aggregateBlock; + } + + + + // private System.Text.Encoding GenerateCommentBytes() + // { + // var getEncoding = new Func({ + // switch (AlternateEncodingUsage) + // { + // case ZipOption.Always: + // return AlternateEncoding; + // case ZipOption.Never: + // return ibm437; + // } + // var cb = ibm437.GetBytes(_Comment); + // // need to use this form of GetString() for .NET CF + // string s1 = ibm437.GetString(cb, 0, cb.Length); + // if (s1 == _Comment) + // return ibm437; + // return AlternateEncoding; + // }); + // + // var encoding = getEncoding(); + // _CommentBytes = encoding.GetBytes(_Comment); + // return encoding; + // } + + + private string NormalizeFileName() + { + // here, we need to flip the backslashes to forward-slashes, + // also, we need to trim the \\server\share syntax from any UNC path. + // and finally, we need to remove any leading .\ + + string SlashFixed = FileName.Replace("\\", "/"); + string s1 = null; + if ((_TrimVolumeFromFullyQualifiedPaths) && (FileName.Length >= 3) + && (FileName[1] == ':') && (SlashFixed[2] == '/')) + { + // trim off volume letter, colon, and slash + s1 = SlashFixed.Substring(3); + } + else if ((FileName.Length >= 4) + && ((SlashFixed[0] == '/') && (SlashFixed[1] == '/'))) + { + int n = SlashFixed.IndexOf('/', 2); + if (n == -1) + throw new ArgumentException("The path for that entry appears to be badly formatted"); + s1 = SlashFixed.Substring(n + 1); + } + else if ((FileName.Length >= 3) + && ((SlashFixed[0] == '.') && (SlashFixed[1] == '/'))) + { + // trim off dot and slash + s1 = SlashFixed.Substring(2); + } + else + { + s1 = SlashFixed; + } + return s1; + } + + + /// + /// generate and return a byte array that encodes the filename + /// for the entry. + /// + /// + /// + /// side effects: generate and store into _CommentBytes the + /// byte array for any comment attached to the entry. Also + /// sets _actualEncoding to indicate the actual encoding + /// used. The same encoding is used for both filename and + /// comment. + /// + /// + private byte[] GetEncodedFileNameBytes() + { + // workitem 6513 + var s1 = NormalizeFileName(); + + switch(AlternateEncodingUsage) + { + case ZipOption.Always: + if (!(_Comment == null || _Comment.Length == 0)) + _CommentBytes = AlternateEncoding.GetBytes(_Comment); + _actualEncoding = AlternateEncoding; + return AlternateEncoding.GetBytes(s1); + + case ZipOption.Never: + if (!(_Comment == null || _Comment.Length == 0)) + _CommentBytes = ibm437.GetBytes(_Comment); + _actualEncoding = ibm437; + return ibm437.GetBytes(s1); + } + + // arriving here means AlternateEncodingUsage is "AsNecessary" + + // case ZipOption.AsNecessary: + // workitem 6513: when writing, use the alternative encoding + // only when _actualEncoding is not yet set (it can be set + // during Read), and when ibm437 will not do. + + byte[] result = ibm437.GetBytes(s1); + // need to use this form of GetString() for .NET CF + string s2 = ibm437.GetString(result, 0, result.Length); + _CommentBytes = null; + if (s2 != s1) + { + // Encoding the filename with ibm437 does not allow round-trips. + // Therefore, use the alternate encoding. Assume it will work, + // no checking of round trips here. + result = AlternateEncoding.GetBytes(s1); + if (_Comment != null && _Comment.Length != 0) + _CommentBytes = AlternateEncoding.GetBytes(_Comment); + _actualEncoding = AlternateEncoding; + return result; + } + + _actualEncoding = ibm437; + + // Using ibm437, FileName can be encoded without information + // loss; now try the Comment. + + // if there is no comment, use ibm437. + if (_Comment == null || _Comment.Length == 0) + return result; + + // there is a comment. Get the encoded form. + byte[] cbytes = ibm437.GetBytes(_Comment); + string c2 = ibm437.GetString(cbytes,0,cbytes.Length); + + // Check for round-trip. + if (c2 != Comment) + { + // Comment cannot correctly be encoded with ibm437. Use + // the alternate encoding. + + result = AlternateEncoding.GetBytes(s1); + _CommentBytes = AlternateEncoding.GetBytes(_Comment); + _actualEncoding = AlternateEncoding; + return result; + } + + // use IBM437 + _CommentBytes = cbytes; + return result; + } + + + + private bool WantReadAgain() + { + if (_UncompressedSize < 0x10) return false; + if (_CompressionMethod == 0x00) return false; + if (CompressionLevel == Ionic.Zlib.CompressionLevel.None) return false; + if (_CompressedSize < _UncompressedSize) return false; + + if (this._Source == ZipEntrySource.Stream && !this._sourceStream.CanSeek) return false; + +#if AESCRYPTO + if (_aesCrypto_forWrite != null && (CompressedSize - _aesCrypto_forWrite.SizeOfEncryptionMetadata) <= UncompressedSize + 0x10) return false; +#endif + + if (_zipCrypto_forWrite != null && (CompressedSize - 12) <= UncompressedSize) return false; + + return true; + } + + + + private void MaybeUnsetCompressionMethodForWriting(int cycle) + { + // if we've already tried with compression... turn it off this time + if (cycle > 1) + { + _CompressionMethod = 0x0; + return; + } + // compression for directories = 0x00 (No Compression) + if (IsDirectory) + { + _CompressionMethod = 0x0; + return; + } + + if (this._Source == ZipEntrySource.ZipFile) + { + return; // do nothing + } + + // If __FileDataPosition is zero, then that means we will get the data + // from a file or stream. + + // It is never possible to compress a zero-length file, so we check for + // this condition. + + if (this._Source == ZipEntrySource.Stream) + { + // workitem 7742 + if (_sourceStream != null && _sourceStream.CanSeek) + { + // Length prop will throw if CanSeek is false + long fileLength = _sourceStream.Length; + if (fileLength == 0) + { + _CompressionMethod = 0x00; + return; + } + } + } + else if ((this._Source == ZipEntrySource.FileSystem) && (SharedUtilities.GetFileLength(LocalFileName) == 0L)) + { + _CompressionMethod = 0x00; + return; + } + + // Ok, we're getting the data to be compressed from a + // non-zero-length file or stream, or a file or stream of + // unknown length, and we presume that it is non-zero. In + // that case we check the callback to see if the app wants + // to tell us whether to compress or not. + if (SetCompression != null) + CompressionLevel = SetCompression(LocalFileName, _FileNameInArchive); + + // finally, set CompressionMethod to None if CompressionLevel is None + if (CompressionLevel == (short)Ionic.Zlib.CompressionLevel.None && + CompressionMethod == Ionic.Zip.CompressionMethod.Deflate) + _CompressionMethod = 0x00; + + return; + } + + + + // write the header info for an entry + internal void WriteHeader(Stream s, int cycle) + { + // Must remember the offset, within the output stream, of this particular + // entry header. + // + // This is for 2 reasons: + // + // 1. so we can determine the RelativeOffsetOfLocalHeader (ROLH) for + // use in the central directory. + // 2. so we can seek backward in case there is an error opening or reading + // the file, and the application decides to skip the file. In this case, + // we need to seek backward in the output stream to allow the next entry + // to be added to the zipfile output stream. + // + // Normally you would just store the offset before writing to the output + // stream and be done with it. But the possibility to use split archives + // makes this approach ineffective. In split archives, each file or segment + // is bound to a max size limit, and each local file header must not span a + // segment boundary; it must be written contiguously. If it will fit in the + // current segment, then the ROLH is just the current Position in the output + // stream. If it won't fit, then we need a new file (segment) and the ROLH + // is zero. + // + // But we only can know if it is possible to write a header contiguously + // after we know the size of the local header, a size that varies with + // things like filename length, comments, and extra fields. We have to + // compute the header fully before knowing whether it will fit. + // + // That takes care of item #1 above. Now, regarding #2. If an error occurs + // while computing the local header, we want to just seek backward. The + // exception handling logic (in the caller of WriteHeader) uses ROLH to + // scroll back. + // + // All this means we have to preserve the starting offset before computing + // the header, and also we have to compute the offset later, to handle the + // case of split archives. + + var counter = s as CountingStream; + + // workitem 8098: ok (output) + // This may change later, for split archives + + // Don't set _RelativeOffsetOfLocalHeader. Instead, set a temp variable. + // This allows for re-streaming, where a zip entry might be read from a + // zip archive (and maybe decrypted, and maybe decompressed) and then + // written to another zip archive, with different settings for + // compression method, compression level, or encryption algorithm. + _future_ROLH = (counter != null) + ? counter.ComputedPosition + : s.Position; + + int j = 0, i = 0; + + byte[] block = new byte[30]; + + // signature + block[i++] = (byte)(ZipConstants.ZipEntrySignature & 0x000000FF); + block[i++] = (byte)((ZipConstants.ZipEntrySignature & 0x0000FF00) >> 8); + block[i++] = (byte)((ZipConstants.ZipEntrySignature & 0x00FF0000) >> 16); + block[i++] = (byte)((ZipConstants.ZipEntrySignature & 0xFF000000) >> 24); + + // Design notes for ZIP64: + // + // The specification says that the header must include the Compressed + // and Uncompressed sizes, as well as the CRC32 value. When creating + // a zip via streamed processing, these quantities are not known until + // after the compression is done. Thus, a typical way to do it is to + // insert zeroes for these quantities, then do the compression, then + // seek back to insert the appropriate values, then seek forward to + // the end of the file data. + // + // There is also the option of using bit 3 in the GP bitfield - to + // specify that there is a data descriptor after the file data + // containing these three quantities. + // + // This works when the size of the quantities is known, either 32-bits + // or 64 bits as with the ZIP64 extensions. + // + // With Zip64, the 4-byte fields are set to 0xffffffff, and there is a + // corresponding data block in the "extra field" that contains the + // actual Compressed, uncompressed sizes. (As well as an additional + // field, the "Relative Offset of Local Header") + // + // The problem is when the app desires to use ZIP64 extensions + // optionally, only when necessary. Suppose the library assumes no + // zip64 extensions when writing the header, then after compression + // finds that the size of the data requires zip64. At this point, the + // header, already written to the file, won't have the necessary data + // block in the "extra field". The size of the entry header is fixed, + // so it is not possible to just "add on" the zip64 data block after + // compressing the file. On the other hand, always using zip64 will + // break interoperability with many other systems and apps. + // + // The approach we take is to insert a 32-byte dummy data block in the + // extra field, whenever zip64 is to be used "as necessary". This data + // block will get the actual zip64 HeaderId and zip64 metadata if + // necessary. If not necessary, the data block will get a meaningless + // HeaderId (0x1111), and will be filled with zeroes. + // + // When zip64 is actually in use, we also need to set the + // VersionNeededToExtract field to 45. + // + // There is one additional wrinkle: using zip64 as necessary conflicts + // with output to non-seekable devices. The header is emitted and + // must indicate whether zip64 is in use, before we know if zip64 is + // necessary. Because there is no seeking, the header can never be + // changed. Therefore, on non-seekable devices, + // Zip64Option.AsNecessary is the same as Zip64Option.Always. + // + + + // version needed- see AppNote.txt. + // + // need v5.1 for PKZIP strong encryption, or v2.0 for no encryption or + // for PK encryption, 4.5 for zip64. We may reset this later, as + // necessary or zip64. + + _presumeZip64 = (_container.Zip64 == Zip64Option.Always || + (_container.Zip64 == Zip64Option.AsNecessary && !s.CanSeek)); + Int16 VersionNeededToExtract = (Int16)(_presumeZip64 ? 45 : 20); +#if BZIP + if (this.CompressionMethod == Ionic.Zip.CompressionMethod.BZip2) + VersionNeededToExtract = 46; +#endif + + // (i==4) + block[i++] = (byte)(VersionNeededToExtract & 0x00FF); + block[i++] = (byte)((VersionNeededToExtract & 0xFF00) >> 8); + + // Get byte array. Side effect: sets ActualEncoding. + // Must determine encoding before setting the bitfield. + // workitem 6513 + byte[] fileNameBytes = GetEncodedFileNameBytes(); + Int16 filenameLength = (Int16)fileNameBytes.Length; + + // general purpose bitfield + // In the current implementation, this library uses only these bits + // in the GP bitfield: + // bit 0 = if set, indicates the entry is encrypted + // bit 3 = if set, indicates the CRC, C and UC sizes follow the file data. + // bit 6 = strong encryption - for pkware's meaning of strong encryption + // bit 11 = UTF-8 encoding is used in the comment and filename + + + // Here we set or unset the encryption bit. + // _BitField may already be set, as with a ZipEntry added into ZipOutputStream, which + // has bit 3 always set. We only want to set one bit + if (_Encryption == EncryptionAlgorithm.None) + _BitField &= ~1; // encryption bit OFF + else + _BitField |= 1; // encryption bit ON + + + // workitem 7941: WinZip does not the "strong encryption" bit when using AES. + // This "Strong Encryption" is a PKWare Strong encryption thing. + // _BitField |= 0x0020; + + // set the UTF8 bit if necessary +#if SILVERLIGHT + if (_actualEncoding.WebName == "utf-8") +#else + if (_actualEncoding.CodePage == System.Text.Encoding.UTF8.CodePage) +#endif + _BitField |= 0x0800; + + // The PKZIP spec says that if bit 3 is set (0x0008) in the General + // Purpose BitField, then the CRC, Compressed size, and uncompressed + // size are written directly after the file data. + // + // These 3 quantities are normally present in the regular zip entry + // header. But, they are not knowable until after the compression is + // done. So, in the normal case, we + // + // - write the header, using zeros for these quantities + // - compress the data, and incidentally compute these quantities. + // - seek back and write the correct values them into the header. + // + // This is nice because, while it is more complicated to write the zip + // file, it is simpler and less error prone to read the zip file, and + // as a result more applications can read zip files produced this way, + // with those 3 quantities in the header. + // + // But if seeking in the output stream is not possible, then we need + // to set the appropriate bitfield and emit these quantities after the + // compressed file data in the output. + // + // workitem 7216 - having trouble formatting a zip64 file that is + // readable by WinZip. not sure why! What I found is that setting + // bit 3 and following all the implications, the zip64 file is + // readable by WinZip 12. and Perl's IO::Compress::Zip . Perl takes + // an interesting approach - it always sets bit 3 if ZIP64 in use. + // DotNetZip now does the same; this gives better compatibility with + // WinZip 12. + + if (IsDirectory || cycle == 99) + { + // (cycle == 99) indicates a zero-length entry written by ZipOutputStream + + _BitField &= ~0x0008; // unset bit 3 - no "data descriptor" - ever + _BitField &= ~0x0001; // unset bit 1 - no encryption - ever + Encryption = EncryptionAlgorithm.None; + Password = null; + } + else if (!s.CanSeek) + _BitField |= 0x0008; + +#if DONT_GO_THERE + else if (this.Encryption == EncryptionAlgorithm.PkzipWeak && + this._Source != ZipEntrySource.ZipFile) + { + // Set bit 3 to avoid the double-read perf issue. + // + // When PKZIP encryption is used, byte 11 of the encryption header is + // used as a consistency check. It is normally set to the MSByte of the + // CRC. But this means the cRC must be known ebfore compression and + // encryption, which means the entire stream has to be read twice. To + // avoid that, the high-byte of the time blob (when in DOS format) can + // be used for the consistency check (byte 11 in the encryption header). + // But this means the entry must have bit 3 set. + // + // Previously I used a more complex arrangement - using the methods like + // FigureCrc32(), PrepOutputStream() and others, in order to manage the + // seek-back in the source stream. Why? Because bit 3 is not always + // friendly with third-party zip tools, like those on the Mac. + // + // This is why this code is still ifdef'd out. + // + // Might consider making this yet another programmable option - + // AlwaysUseBit3ForPkzip. But that's for another day. + // + _BitField |= 0x0008; + } +#endif + + // (i==6) + block[i++] = (byte)(_BitField & 0x00FF); + block[i++] = (byte)((_BitField & 0xFF00) >> 8); + + // Here, we want to set values for Compressed Size, Uncompressed Size, + // and CRC. If we have __FileDataPosition as not -1 (zero is a valid + // FDP), then that means we are reading this zip entry from a zip + // file, and we have good values for those quantities. + // + // If _FileDataPosition is -1, then we are constructing this Entry + // from nothing. We zero those quantities now, and we will compute + // actual values for the three quantities later, when we do the + // compression, and then seek back to write them into the appropriate + // place in the header. + if (this.__FileDataPosition == -1) + { + //_UncompressedSize = 0; // do not unset - may need this value for restream + // _Crc32 = 0; // ditto + _CompressedSize = 0; + _crcCalculated = false; + } + + // set compression method here + MaybeUnsetCompressionMethodForWriting(cycle); + + // (i==8) compression method + block[i++] = (byte)(_CompressionMethod & 0x00FF); + block[i++] = (byte)((_CompressionMethod & 0xFF00) >> 8); + + if (cycle == 99) + { + // (cycle == 99) indicates a zero-length entry written by ZipOutputStream + SetZip64Flags(); + } + +#if AESCRYPTO + else if (Encryption == EncryptionAlgorithm.WinZipAes128 || Encryption == EncryptionAlgorithm.WinZipAes256) + { + i -= 2; + block[i++] = 0x63; + block[i++] = 0; + } +#endif + + // LastMod + _TimeBlob = Ionic.Zip.SharedUtilities.DateTimeToPacked(LastModified); + + // (i==10) time blob + block[i++] = (byte)(_TimeBlob & 0x000000FF); + block[i++] = (byte)((_TimeBlob & 0x0000FF00) >> 8); + block[i++] = (byte)((_TimeBlob & 0x00FF0000) >> 16); + block[i++] = (byte)((_TimeBlob & 0xFF000000) >> 24); + + // (i==14) CRC - if source==filesystem, this is zero now, actual value + // will be calculated later. if source==archive, this is a bonafide + // value. + block[i++] = (byte)(_Crc32 & 0x000000FF); + block[i++] = (byte)((_Crc32 & 0x0000FF00) >> 8); + block[i++] = (byte)((_Crc32 & 0x00FF0000) >> 16); + block[i++] = (byte)((_Crc32 & 0xFF000000) >> 24); + + if (_presumeZip64) + { + // (i==18) CompressedSize (Int32) and UncompressedSize - all 0xFF for now + for (j = 0; j < 8; j++) + block[i++] = 0xFF; + } + else + { + // (i==18) CompressedSize (Int32) - this value may or may not be + // bonafide. if source == filesystem, then it is zero, and we'll + // learn it after we compress. if source == archive, then it is + // bonafide data. + block[i++] = (byte)(_CompressedSize & 0x000000FF); + block[i++] = (byte)((_CompressedSize & 0x0000FF00) >> 8); + block[i++] = (byte)((_CompressedSize & 0x00FF0000) >> 16); + block[i++] = (byte)((_CompressedSize & 0xFF000000) >> 24); + + // (i==22) UncompressedSize (Int32) - this value may or may not be + // bonafide. + block[i++] = (byte)(_UncompressedSize & 0x000000FF); + block[i++] = (byte)((_UncompressedSize & 0x0000FF00) >> 8); + block[i++] = (byte)((_UncompressedSize & 0x00FF0000) >> 16); + block[i++] = (byte)((_UncompressedSize & 0xFF000000) >> 24); + } + + // (i==26) filename length (Int16) + block[i++] = (byte)(filenameLength & 0x00FF); + block[i++] = (byte)((filenameLength & 0xFF00) >> 8); + + _Extra = ConstructExtraField(false); + + // (i==28) extra field length (short) + Int16 extraFieldLength = (Int16)((_Extra == null) ? 0 : _Extra.Length); + block[i++] = (byte)(extraFieldLength & 0x00FF); + block[i++] = (byte)((extraFieldLength & 0xFF00) >> 8); + + // workitem 13542 + byte[] bytes = new byte[i + filenameLength + extraFieldLength]; + + // get the fixed portion + Buffer.BlockCopy(block, 0, bytes, 0, i); + //for (j = 0; j < i; j++) bytes[j] = block[j]; + + // The filename written to the archive. + Buffer.BlockCopy(fileNameBytes, 0, bytes, i, fileNameBytes.Length); + // for (j = 0; j < fileNameBytes.Length; j++) + // bytes[i + j] = fileNameBytes[j]; + + i += fileNameBytes.Length; + + // "Extra field" + if (_Extra != null) + { + Buffer.BlockCopy(_Extra, 0, bytes, i, _Extra.Length); + // for (j = 0; j < _Extra.Length; j++) + // bytes[i + j] = _Extra[j]; + i += _Extra.Length; + } + + _LengthOfHeader = i; + + // handle split archives + var zss = s as ZipSegmentedStream; + if (zss != null) + { + zss.ContiguousWrite = true; + UInt32 requiredSegment = zss.ComputeSegment(i); + if (requiredSegment != zss.CurrentSegment) + _future_ROLH = 0; // rollover! + else + _future_ROLH = zss.Position; + + _diskNumber = requiredSegment; + } + + // validate the ZIP64 usage + if (_container.Zip64 == Zip64Option.Never && (uint)_RelativeOffsetOfLocalHeader >= 0xFFFFFFFF) + throw new ZipException("Offset within the zip archive exceeds 0xFFFFFFFF. Consider setting the UseZip64WhenSaving property on the ZipFile instance."); + + + // finally, write the header to the stream + s.Write(bytes, 0, i); + + // now that the header is written, we can turn off the contiguous write restriction. + if (zss != null) + zss.ContiguousWrite = false; + + // Preserve this header data, we'll use it again later. + // ..when seeking backward, to write again, after we have the Crc, compressed + // and uncompressed sizes. + // ..and when writing the central directory structure. + _EntryHeader = bytes; + } + + + + + private Int32 FigureCrc32() + { + if (_crcCalculated == false) + { + Stream input = null; + // get the original stream: + if (this._Source == ZipEntrySource.WriteDelegate) + { + var output = new Ionic.Crc.CrcCalculatorStream(Stream.Null); + // allow the application to write the data + this._WriteDelegate(this.FileName, output); + _Crc32 = output.Crc; + } + else if (this._Source == ZipEntrySource.ZipFile) + { + // nothing to do - the CRC is already set + } + else + { + if (this._Source == ZipEntrySource.Stream) + { + PrepSourceStream(); + input = this._sourceStream; + } + else if (this._Source == ZipEntrySource.JitStream) + { + // allow the application to open the stream + if (this._sourceStream == null) + _sourceStream = this._OpenDelegate(this.FileName); + PrepSourceStream(); + input = this._sourceStream; + } + else if (this._Source == ZipEntrySource.ZipOutputStream) + { + } + else + { + //input = File.OpenRead(LocalFileName); + input = File.Open(LocalFileName, FileMode.Open, FileAccess.Read, FileShare.ReadWrite); + } + + var crc32 = new Ionic.Crc.CRC32(); + _Crc32 = crc32.GetCrc32(input); + + if (_sourceStream == null) + { +#if NETCF + input.Close(); +#else + input.Dispose(); +#endif + } + } + _crcCalculated = true; + } + return _Crc32; + } + + + /// + /// Stores the position of the entry source stream, or, if the position is + /// already stored, seeks to that position. + /// + /// + /// + /// + /// This method is called in prep for reading the source stream. If PKZIP + /// encryption is used, then we need to calc the CRC32 before doing the + /// encryption, because the CRC is used in the 12th byte of the PKZIP + /// encryption header. So, we need to be able to seek backward in the source + /// when saving the ZipEntry. This method is called from the place that + /// calculates the CRC, and also from the method that does the encryption of + /// the file data. + /// + /// + /// + /// The first time through, this method sets the _sourceStreamOriginalPosition + /// field. Subsequent calls to this method seek to that position. + /// + /// + private void PrepSourceStream() + { + if (_sourceStream == null) + throw new ZipException(String.Format("The input stream is null for entry '{0}'.", FileName)); + + if (this._sourceStreamOriginalPosition != null) + { + // this will happen the 2nd cycle through, if the stream is seekable + this._sourceStream.Position = this._sourceStreamOriginalPosition.Value; + } + else if (this._sourceStream.CanSeek) + { + // this will happen the first cycle through, if seekable + this._sourceStreamOriginalPosition = new Nullable(this._sourceStream.Position); + } + else if (this.Encryption == EncryptionAlgorithm.PkzipWeak) + { + // In general, using PKZIP encryption on a a zip entry whose input + // comes from a non-seekable stream, is tricky. Here's why: + // + // Byte 11 of the PKZIP encryption header is used for password + // validation and consistency checknig. + // + // Normally, the highest byte of the CRC is used as the 11th (last) byte + // in the PKZIP encryption header. This means the CRC must be known + // before encryption is performed. Normally that means we read the full + // data stream, compute the CRC, then seek back and read it again for + // the compression+encryption phase. Obviously this is bad for + // performance with a large input file. + // + // There's a twist in the ZIP spec (actually documented only in infozip + // code, not in the spec itself) that allows the high-order byte of the + // last modified time for the entry, when the lastmod time is in packed + // (DOS) format, to be used for Byte 11 in the encryption header. In + // this case, the bit 3 "data descriptor" must be used. + // + // An intelligent implementation would therefore force the use of the + // bit 3 data descriptor when PKZIP encryption is in use, regardless. + // This avoids the double-read of the stream to be encrypted. So far, + // DotNetZip doesn't do that; it just punts when the input stream is + // non-seekable, and the output does not use Bit 3. + // + // The other option is to use the CRC when it is already available, eg, + // when the source for the data is a ZipEntry (when the zip file is + // being updated). In this case we already know the CRC and can just use + // what we know. + + if (this._Source != ZipEntrySource.ZipFile && ((this._BitField & 0x0008) != 0x0008)) + throw new ZipException("It is not possible to use PKZIP encryption on a non-seekable input stream"); + } + } + + + /// + /// Copy metadata that may have been changed by the app. We do this when + /// resetting the zipFile instance. If the app calls Save() on a ZipFile, then + /// tries to party on that file some more, we may need to Reset() it , which + /// means re-reading the entries and then copying the metadata. I think. + /// + internal void CopyMetaData(ZipEntry source) + { + this.__FileDataPosition = source.__FileDataPosition; + this.CompressionMethod = source.CompressionMethod; + this._CompressionMethod_FromZipFile = source._CompressionMethod_FromZipFile; + this._CompressedFileDataSize = source._CompressedFileDataSize; + this._UncompressedSize = source._UncompressedSize; + this._BitField = source._BitField; + this._Source = source._Source; + this._LastModified = source._LastModified; + this._Mtime = source._Mtime; + this._Atime = source._Atime; + this._Ctime = source._Ctime; + this._ntfsTimesAreSet = source._ntfsTimesAreSet; + this._emitUnixTimes = source._emitUnixTimes; + this._emitNtfsTimes = source._emitNtfsTimes; + } + + + private void OnWriteBlock(Int64 bytesXferred, Int64 totalBytesToXfer) + { + if (_container.ZipFile != null) + _ioOperationCanceled = _container.ZipFile.OnSaveBlock(this, bytesXferred, totalBytesToXfer); + } + + + + private void _WriteEntryData(Stream s) + { + // Read in the data from the input stream (often a file in the filesystem), + // and write it to the output stream, calculating a CRC on it as we go. + // We will also compress and encrypt as necessary. + + Stream input = null; + long fdp = -1L; + try + { + // Want to record the position in the zip file of the zip entry + // data (as opposed to the metadata). s.Position may fail on some + // write-only streams, eg stdout or System.Web.HttpResponseStream. + // We swallow that exception, because we don't care, in that case. + // But, don't set __FileDataPosition directly. It may be needed + // to READ the zip entry from the zip file, if this is a + // "re-stream" situation. In other words if the zip entry has + // changed compression level, or compression method, or (maybe?) + // encryption algorithm. In that case if the original entry is + // encrypted, we need __FileDataPosition to be the value for the + // input zip file. This s.Position is for the output zipfile. So + // we copy fdp to __FileDataPosition after this entry has been + // (maybe) restreamed. + fdp = s.Position; + } + catch (Exception) { } + + try + { + // Use fileLength for progress updates, and to decide whether we can + // skip encryption and compression altogether (in case of length==zero) + long fileLength = SetInputAndFigureFileLength(ref input); + + // Wrap a counting stream around the raw output stream: + // This is the last thing that happens before the bits go to the + // application-provided stream. + // + // Sometimes s is a CountingStream. Doesn't matter. Wrap it with a + // counter anyway. We need to count at both levels. + + CountingStream entryCounter = new CountingStream(s); + + Stream encryptor; + Stream compressor; + + if (fileLength != 0L) + { + // Maybe wrap an encrypting stream around the counter: This will + // happen BEFORE output counting, and AFTER compression, if encryption + // is used. + encryptor = MaybeApplyEncryption(entryCounter); + + // Maybe wrap a compressing Stream around that. + // This will happen BEFORE encryption (if any) as we write data out. + compressor = MaybeApplyCompression(encryptor, fileLength); + } + else + { + encryptor = compressor = entryCounter; + } + + // Wrap a CrcCalculatorStream around that. + // This will happen BEFORE compression (if any) as we write data out. + var output = new Ionic.Crc.CrcCalculatorStream(compressor, true); + + // output.Write() causes this flow: + // calc-crc -> compress -> encrypt -> count -> actually write + + if (this._Source == ZipEntrySource.WriteDelegate) + { + // allow the application to write the data + this._WriteDelegate(this.FileName, output); + } + else + { + // synchronously copy the input stream to the output stream-chain + byte[] buffer = new byte[BufferSize]; + int n; + while ((n = SharedUtilities.ReadWithRetry(input, buffer, 0, buffer.Length, FileName)) != 0) + { + output.Write(buffer, 0, n); + OnWriteBlock(output.TotalBytesSlurped, fileLength); + if (_ioOperationCanceled) + break; + } + } + + FinishOutputStream(s, entryCounter, encryptor, compressor, output); + } + finally + { + if (this._Source == ZipEntrySource.JitStream) + { + // allow the application to close the stream + if (this._CloseDelegate != null) + this._CloseDelegate(this.FileName, input); + } + else if ((input as FileStream) != null) + { +#if NETCF + input.Close(); +#else + input.Dispose(); +#endif + } + } + + if (_ioOperationCanceled) + return; + + // set FDP now, to allow for re-streaming + this.__FileDataPosition = fdp; + PostProcessOutput(s); + } + + + /// + /// Set the input stream and get its length, if possible. The length is + /// used for progress updates, AND, to allow an optimization in case of + /// a stream/file of zero length. In that case we skip the Encrypt and + /// compression Stream. (like DeflateStream or BZip2OutputStream) + /// + private long SetInputAndFigureFileLength(ref Stream input) + { + long fileLength = -1L; + // get the original stream: + if (this._Source == ZipEntrySource.Stream) + { + PrepSourceStream(); + input = this._sourceStream; + + // Try to get the length, no big deal if not available. + try { fileLength = this._sourceStream.Length; } + catch (NotSupportedException) { } + } + else if (this._Source == ZipEntrySource.ZipFile) + { + // we are "re-streaming" the zip entry. + string pwd = (_Encryption_FromZipFile == EncryptionAlgorithm.None) ? null : (this._Password ?? this._container.Password); + this._sourceStream = InternalOpenReader(pwd); + PrepSourceStream(); + input = this._sourceStream; + fileLength = this._sourceStream.Length; + } + else if (this._Source == ZipEntrySource.JitStream) + { + // allow the application to open the stream + if (this._sourceStream == null) _sourceStream = this._OpenDelegate(this.FileName); + PrepSourceStream(); + input = this._sourceStream; + try { fileLength = this._sourceStream.Length; } + catch (NotSupportedException) { } + } + else if (this._Source == ZipEntrySource.FileSystem) + { + // workitem 7145 + FileShare fs = FileShare.ReadWrite; +#if !NETCF + // FileShare.Delete is not defined for the Compact Framework + fs |= FileShare.Delete; +#endif + // workitem 8423 + input = File.Open(LocalFileName, FileMode.Open, FileAccess.Read, fs); + fileLength = input.Length; + } + + return fileLength; + } + + + + internal void FinishOutputStream(Stream s, + CountingStream entryCounter, + Stream encryptor, + Stream compressor, + Ionic.Crc.CrcCalculatorStream output) + { + if (output == null) return; + + output.Close(); + + // by calling Close() on the deflate stream, we write the footer bytes, as necessary. + if ((compressor as Ionic.Zlib.DeflateStream) != null) + compressor.Close(); +#if BZIP + else if ((compressor as Ionic.BZip2.BZip2OutputStream) != null) + compressor.Close(); +#if !NETCF + else if ((compressor as Ionic.BZip2.ParallelBZip2OutputStream) != null) + compressor.Close(); +#endif +#endif + +#if !NETCF + else if ((compressor as Ionic.Zlib.ParallelDeflateOutputStream) != null) + compressor.Close(); +#endif + + encryptor.Flush(); + encryptor.Close(); + + _LengthOfTrailer = 0; + + _UncompressedSize = output.TotalBytesSlurped; + +#if AESCRYPTO + WinZipAesCipherStream wzacs = encryptor as WinZipAesCipherStream; + if (wzacs != null && _UncompressedSize > 0) + { + s.Write(wzacs.FinalAuthentication, 0, 10); + _LengthOfTrailer += 10; + } +#endif + _CompressedFileDataSize = entryCounter.BytesWritten; + _CompressedSize = _CompressedFileDataSize; // may be adjusted + _Crc32 = output.Crc; + + // Set _RelativeOffsetOfLocalHeader now, to allow for re-streaming + StoreRelativeOffset(); + } + + + + + internal void PostProcessOutput(Stream s) + { + var s1 = s as CountingStream; + + // workitem 8931 - for WriteDelegate. + // The WriteDelegate changes things because there can be a zero-byte stream + // written. In all other cases DotNetZip knows the length of the stream + // before compressing and encrypting. In this case we have to circle back, + // and omit all the crypto stuff - the GP bitfield, and the crypto header. + if (_UncompressedSize == 0 && _CompressedSize == 0) + { + if (this._Source == ZipEntrySource.ZipOutputStream) return; // nothing to do... + + if (_Password != null) + { + int headerBytesToRetract = 0; + if (Encryption == EncryptionAlgorithm.PkzipWeak) + headerBytesToRetract = 12; +#if AESCRYPTO + else if (Encryption == EncryptionAlgorithm.WinZipAes128 || + Encryption == EncryptionAlgorithm.WinZipAes256) + { + headerBytesToRetract = _aesCrypto_forWrite._Salt.Length + _aesCrypto_forWrite.GeneratedPV.Length; + } +#endif + if (this._Source == ZipEntrySource.ZipOutputStream && !s.CanSeek) + throw new ZipException("Zero bytes written, encryption in use, and non-seekable output."); + + if (Encryption != EncryptionAlgorithm.None) + { + // seek back in the stream to un-output the security metadata + s.Seek(-1 * headerBytesToRetract, SeekOrigin.Current); + s.SetLength(s.Position); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(s); + + // workitem 11131 + // adjust the count on the CountingStream as necessary + if (s1 != null) s1.Adjust(headerBytesToRetract); + + // subtract the size of the security header from the _LengthOfHeader + _LengthOfHeader -= headerBytesToRetract; + __FileDataPosition -= headerBytesToRetract; + } + _Password = null; + + // turn off the encryption bit + _BitField &= ~(0x0001); + + // copy the updated bitfield value into the header + int j = 6; + _EntryHeader[j++] = (byte)(_BitField & 0x00FF); + _EntryHeader[j++] = (byte)((_BitField & 0xFF00) >> 8); + +#if AESCRYPTO + if (Encryption == EncryptionAlgorithm.WinZipAes128 || + Encryption == EncryptionAlgorithm.WinZipAes256) + { + // Fix the extra field - overwrite the 0x9901 headerId + // with dummy data. (arbitrarily, 0x9999) + Int16 fnLength = (short)(_EntryHeader[26] + _EntryHeader[27] * 256); + int offx = 30 + fnLength; + int aesIndex = FindExtraFieldSegment(_EntryHeader, offx, 0x9901); + if (aesIndex >= 0) + { + _EntryHeader[aesIndex++] = 0x99; + _EntryHeader[aesIndex++] = 0x99; + } + } +#endif + } + + CompressionMethod = 0; + Encryption = EncryptionAlgorithm.None; + } + else if (_zipCrypto_forWrite != null +#if AESCRYPTO + || _aesCrypto_forWrite != null +#endif + ) + + { + if (Encryption == EncryptionAlgorithm.PkzipWeak) + { + _CompressedSize += 12; // 12 extra bytes for the encryption header + } +#if AESCRYPTO + else if (Encryption == EncryptionAlgorithm.WinZipAes128 || + Encryption == EncryptionAlgorithm.WinZipAes256) + { + // adjust the compressed size to include the variable (salt+pv) + // security header and 10-byte trailer. According to the winzip AES + // spec, that metadata is included in the "Compressed Size" figure + // when encoding the zip archive. + _CompressedSize += _aesCrypto_forWrite.SizeOfEncryptionMetadata; + } +#endif + } + + int i = 8; + _EntryHeader[i++] = (byte)(_CompressionMethod & 0x00FF); + _EntryHeader[i++] = (byte)((_CompressionMethod & 0xFF00) >> 8); + + i = 14; + // CRC - the correct value now + _EntryHeader[i++] = (byte)(_Crc32 & 0x000000FF); + _EntryHeader[i++] = (byte)((_Crc32 & 0x0000FF00) >> 8); + _EntryHeader[i++] = (byte)((_Crc32 & 0x00FF0000) >> 16); + _EntryHeader[i++] = (byte)((_Crc32 & 0xFF000000) >> 24); + + SetZip64Flags(); + + // (i==26) filename length (Int16) + Int16 filenameLength = (short)(_EntryHeader[26] + _EntryHeader[27] * 256); + Int16 extraFieldLength = (short)(_EntryHeader[28] + _EntryHeader[29] * 256); + + if (_OutputUsesZip64.Value) + { + // VersionNeededToExtract - set to 45 to indicate zip64 + _EntryHeader[4] = (byte)(45 & 0x00FF); + _EntryHeader[5] = 0x00; + + // workitem 7924 - don't need bit 3 + // // workitem 7917 + // // set bit 3 for ZIP64 compatibility with WinZip12 + // _BitField |= 0x0008; + // _EntryHeader[6] = (byte)(_BitField & 0x00FF); + + // CompressedSize and UncompressedSize - 0xFF + for (int j = 0; j < 8; j++) + _EntryHeader[i++] = 0xff; + + // At this point we need to find the "Extra field" that follows the + // filename. We had already emitted it, but the data (uncomp, comp, + // ROLH) was not available at the time we did so. Here, we emit it + // again, with final values. + + i = 30 + filenameLength; + _EntryHeader[i++] = 0x01; // zip64 + _EntryHeader[i++] = 0x00; + + i += 2; // skip over data size, which is 16+4 + + Array.Copy(BitConverter.GetBytes(_UncompressedSize), 0, _EntryHeader, i, 8); + i += 8; + Array.Copy(BitConverter.GetBytes(_CompressedSize), 0, _EntryHeader, i, 8); + } + else + { + // VersionNeededToExtract - reset to 20 since no zip64 + _EntryHeader[4] = (byte)(20 & 0x00FF); + _EntryHeader[5] = 0x00; + + // CompressedSize - the correct value now + i = 18; + _EntryHeader[i++] = (byte)(_CompressedSize & 0x000000FF); + _EntryHeader[i++] = (byte)((_CompressedSize & 0x0000FF00) >> 8); + _EntryHeader[i++] = (byte)((_CompressedSize & 0x00FF0000) >> 16); + _EntryHeader[i++] = (byte)((_CompressedSize & 0xFF000000) >> 24); + + // UncompressedSize - the correct value now + _EntryHeader[i++] = (byte)(_UncompressedSize & 0x000000FF); + _EntryHeader[i++] = (byte)((_UncompressedSize & 0x0000FF00) >> 8); + _EntryHeader[i++] = (byte)((_UncompressedSize & 0x00FF0000) >> 16); + _EntryHeader[i++] = (byte)((_UncompressedSize & 0xFF000000) >> 24); + + // The HeaderId in the extra field header, is already dummied out. + if (extraFieldLength != 0) + { + i = 30 + filenameLength; + // For zip archives written by this library, if the zip64 + // header exists, it is the first header. Because of the logic + // used when first writing the _EntryHeader bytes, the + // HeaderId is not guaranteed to be any particular value. So + // we determine if the first header is a putative zip64 header + // by examining the datasize. UInt16 HeaderId = + // (UInt16)(_EntryHeader[i] + _EntryHeader[i + 1] * 256); + Int16 DataSize = (short)(_EntryHeader[i + 2] + _EntryHeader[i + 3] * 256); + if (DataSize == 16) + { + // reset to Header Id to dummy value, effectively dummy-ing out the zip64 metadata + _EntryHeader[i++] = 0x99; + _EntryHeader[i++] = 0x99; + } + } + } + + +#if AESCRYPTO + + if (Encryption == EncryptionAlgorithm.WinZipAes128 || + Encryption == EncryptionAlgorithm.WinZipAes256) + { + // Must set compressionmethod to 0x0063 (decimal 99) + // + // and then set the compression method bytes inside the extra + // field to the actual compression method value. + + i = 8; + _EntryHeader[i++] = 0x63; + _EntryHeader[i++] = 0; + + i = 30 + filenameLength; + do + { + UInt16 HeaderId = (UInt16)(_EntryHeader[i] + _EntryHeader[i + 1] * 256); + Int16 DataSize = (short)(_EntryHeader[i + 2] + _EntryHeader[i + 3] * 256); + if (HeaderId != 0x9901) + { + // skip this header + i += DataSize + 4; + } + else + { + i += 9; + // actual compression method + _EntryHeader[i++] = (byte)(_CompressionMethod & 0x00FF); + _EntryHeader[i++] = (byte)(_CompressionMethod & 0xFF00); + } + } while (i < (extraFieldLength - 30 - filenameLength)); + } +#endif + + // finally, write the data. + + // workitem 7216 - sometimes we don't seek even if we CAN. ASP.NET + // Response.OutputStream, or stdout are non-seekable. But we may also want + // to NOT seek in other cases, eg zip64. For all cases, we just check bit 3 + // to see if we want to seek. There's one exception - if using a + // ZipOutputStream, and PKZip encryption is in use, then we set bit 3 even + // if the out is seekable. This is so the check on the last byte of the + // PKZip Encryption Header can be done on the current time, as opposed to + // the CRC, to prevent streaming the file twice. So, test for + // ZipOutputStream and seekable, and if so, seek back, even if bit 3 is set. + + if ((_BitField & 0x0008) != 0x0008 || + (this._Source == ZipEntrySource.ZipOutputStream && s.CanSeek)) + { + // seek back and rewrite the entry header + var zss = s as ZipSegmentedStream; + if (zss != null && _diskNumber != zss.CurrentSegment) + { + // In this case the entry header is in a different file, + // which has already been closed. Need to re-open it. + using (Stream hseg = ZipSegmentedStream.ForUpdate(this._container.ZipFile.Name, _diskNumber)) + { + hseg.Seek(this._RelativeOffsetOfLocalHeader, SeekOrigin.Begin); + hseg.Write(_EntryHeader, 0, _EntryHeader.Length); + } + } + else + { + // seek in the raw output stream, to the beginning of the header for + // this entry. + // workitem 8098: ok (output) + s.Seek(this._RelativeOffsetOfLocalHeader, SeekOrigin.Begin); + + // write the updated header to the output stream + s.Write(_EntryHeader, 0, _EntryHeader.Length); + + // adjust the count on the CountingStream as necessary + if (s1 != null) s1.Adjust(_EntryHeader.Length); + + // seek in the raw output stream, to the end of the file data + // for this entry + s.Seek(_CompressedSize, SeekOrigin.Current); + } + } + + // emit the descriptor - only if not a directory. + if (((_BitField & 0x0008) == 0x0008) && !IsDirectory) + { + byte[] Descriptor = new byte[16 + (_OutputUsesZip64.Value ? 8 : 0)]; + i = 0; + + // signature + Array.Copy(BitConverter.GetBytes(ZipConstants.ZipEntryDataDescriptorSignature), 0, Descriptor, i, 4); + i += 4; + + // CRC - the correct value now + Array.Copy(BitConverter.GetBytes(_Crc32), 0, Descriptor, i, 4); + i += 4; + + // workitem 7917 + if (_OutputUsesZip64.Value) + { + // CompressedSize - the correct value now + Array.Copy(BitConverter.GetBytes(_CompressedSize), 0, Descriptor, i, 8); + i += 8; + + // UncompressedSize - the correct value now + Array.Copy(BitConverter.GetBytes(_UncompressedSize), 0, Descriptor, i, 8); + i += 8; + } + else + { + // CompressedSize - (lower 32 bits) the correct value now + Descriptor[i++] = (byte)(_CompressedSize & 0x000000FF); + Descriptor[i++] = (byte)((_CompressedSize & 0x0000FF00) >> 8); + Descriptor[i++] = (byte)((_CompressedSize & 0x00FF0000) >> 16); + Descriptor[i++] = (byte)((_CompressedSize & 0xFF000000) >> 24); + + // UncompressedSize - (lower 32 bits) the correct value now + Descriptor[i++] = (byte)(_UncompressedSize & 0x000000FF); + Descriptor[i++] = (byte)((_UncompressedSize & 0x0000FF00) >> 8); + Descriptor[i++] = (byte)((_UncompressedSize & 0x00FF0000) >> 16); + Descriptor[i++] = (byte)((_UncompressedSize & 0xFF000000) >> 24); + } + + // finally, write the trailing descriptor to the output stream + s.Write(Descriptor, 0, Descriptor.Length); + + _LengthOfTrailer += Descriptor.Length; + } + } + + + + private void SetZip64Flags() + { + // zip64 housekeeping + _entryRequiresZip64 = new Nullable + (_CompressedSize >= 0xFFFFFFFF || _UncompressedSize >= 0xFFFFFFFF || _RelativeOffsetOfLocalHeader >= 0xFFFFFFFF); + + // validate the ZIP64 usage + if (_container.Zip64 == Zip64Option.Never && _entryRequiresZip64.Value) + throw new ZipException("Compressed or Uncompressed size, or offset exceeds the maximum value. Consider setting the UseZip64WhenSaving property on the ZipFile instance."); + + _OutputUsesZip64 = new Nullable(_container.Zip64 == Zip64Option.Always || _entryRequiresZip64.Value); + } + + + + /// + /// Prepare the given stream for output - wrap it in a CountingStream, and + /// then in a CRC stream, and an encryptor and deflator as appropriate. + /// + /// + /// + /// Previously this was used in ZipEntry.Write(), but in an effort to + /// introduce some efficiencies in that method I've refactored to put the + /// code inline. This method still gets called by ZipOutputStream. + /// + /// + internal void PrepOutputStream(Stream s, + long streamLength, + out CountingStream outputCounter, + out Stream encryptor, + out Stream compressor, + out Ionic.Crc.CrcCalculatorStream output) + { + TraceWriteLine("PrepOutputStream: e({0}) comp({1}) crypto({2}) zf({3})", + FileName, + CompressionLevel, + Encryption, + _container.Name); + + // Wrap a counting stream around the raw output stream: + // This is the last thing that happens before the bits go to the + // application-provided stream. + outputCounter = new CountingStream(s); + + // Sometimes the incoming "raw" output stream is already a CountingStream. + // Doesn't matter. Wrap it with a counter anyway. We need to count at both + // levels. + + if (streamLength != 0L) + { + // Maybe wrap an encrypting stream around that: + // This will happen BEFORE output counting, and AFTER deflation, if encryption + // is used. + encryptor = MaybeApplyEncryption(outputCounter); + + // Maybe wrap a compressing Stream around that. + // This will happen BEFORE encryption (if any) as we write data out. + compressor = MaybeApplyCompression(encryptor, streamLength); + } + else + { + encryptor = compressor = outputCounter; + } + // Wrap a CrcCalculatorStream around that. + // This will happen BEFORE compression (if any) as we write data out. + output = new Ionic.Crc.CrcCalculatorStream(compressor, true); + } + + + + private Stream MaybeApplyCompression(Stream s, long streamLength) + { + if (_CompressionMethod == 0x08 && CompressionLevel != Ionic.Zlib.CompressionLevel.None) + { +#if !NETCF + // ParallelDeflateThreshold == 0 means ALWAYS use parallel deflate + // ParallelDeflateThreshold == -1L means NEVER use parallel deflate + // Other values specify the actual threshold. + if (_container.ParallelDeflateThreshold == 0L || + (streamLength > _container.ParallelDeflateThreshold && + _container.ParallelDeflateThreshold > 0L)) + { + // This is sort of hacky. + // + // It's expensive to create a ParallelDeflateOutputStream, because + // of the large memory buffers. But the class is unlike most Stream + // classes in that it can be re-used, so the caller can compress + // multiple files with it, one file at a time. The key is to call + // Reset() on it, in between uses. + // + // The ParallelDeflateOutputStream is attached to the container + // itself - there is just one for the entire ZipFile or + // ZipOutputStream. So it gets created once, per save, and then + // re-used many times. + // + // This approach will break when we go to a "parallel save" + // approach, where multiple entries within the zip file are being + // compressed and saved at the same time. But for now it's ok. + // + + // instantiate the ParallelDeflateOutputStream + if (_container.ParallelDeflater == null) + { + _container.ParallelDeflater = + new Ionic.Zlib.ParallelDeflateOutputStream(s, + CompressionLevel, + _container.Strategy, + true); + // can set the codec buffer size only before the first call to Write(). + if (_container.CodecBufferSize > 0) + _container.ParallelDeflater.BufferSize = _container.CodecBufferSize; + if (_container.ParallelDeflateMaxBufferPairs > 0) + _container.ParallelDeflater.MaxBufferPairs = + _container.ParallelDeflateMaxBufferPairs; + } + // reset it with the new stream + Ionic.Zlib.ParallelDeflateOutputStream o1 = _container.ParallelDeflater; + o1.Reset(s); + return o1; + } +#endif + var o = new Ionic.Zlib.DeflateStream(s, Ionic.Zlib.CompressionMode.Compress, + CompressionLevel, + true); + if (_container.CodecBufferSize > 0) + o.BufferSize = _container.CodecBufferSize; + o.Strategy = _container.Strategy; + return o; + } + + +#if BZIP + if (_CompressionMethod == 0x0c) + { +#if !NETCF + if (_container.ParallelDeflateThreshold == 0L || + (streamLength > _container.ParallelDeflateThreshold && + _container.ParallelDeflateThreshold > 0L)) + { + + var o1 = new Ionic.BZip2.ParallelBZip2OutputStream(s, true); + return o1; + } +#endif + var o = new Ionic.BZip2.BZip2OutputStream(s, true); + return o; + } +#endif + + return s; + } + + + + private Stream MaybeApplyEncryption(Stream s) + { + if (Encryption == EncryptionAlgorithm.PkzipWeak) + { + TraceWriteLine("MaybeApplyEncryption: e({0}) PKZIP", FileName); + + return new ZipCipherStream(s, _zipCrypto_forWrite, CryptoMode.Encrypt); + } +#if AESCRYPTO + if (Encryption == EncryptionAlgorithm.WinZipAes128 || + Encryption == EncryptionAlgorithm.WinZipAes256) + { + TraceWriteLine("MaybeApplyEncryption: e({0}) AES", FileName); + + return new WinZipAesCipherStream(s, _aesCrypto_forWrite, CryptoMode.Encrypt); + } +#endif + TraceWriteLine("MaybeApplyEncryption: e({0}) None", FileName); + + return s; + } + + + + private void OnZipErrorWhileSaving(Exception e) + { + if (_container.ZipFile != null) + _ioOperationCanceled = _container.ZipFile.OnZipErrorSaving(this, e); + } + + + + internal void Write(Stream s) + { + var cs1 = s as CountingStream; + var zss1 = s as ZipSegmentedStream; + + bool done = false; + do + { + try + { + // When the app is updating a zip file, it may be possible to + // just copy data for a ZipEntry from the source zipfile to the + // destination, as a block, without decompressing and + // recompressing, etc. But, in some cases the app modifies the + // properties on a ZipEntry prior to calling Save(). A change to + // any of the metadata - the FileName, CompressioLeve and so on, + // means DotNetZip cannot simply copy through the existing + // ZipEntry data unchanged. + // + // There are two cases: + // + // 1. Changes to only metadata, which means the header and + // central directory must be changed. + // + // 2. Changes to the properties that affect the compressed + // stream, such as CompressionMethod, CompressionLevel, or + // EncryptionAlgorithm. In this case, DotNetZip must + // "re-stream" the data: the old entry data must be maybe + // decrypted, maybe decompressed, then maybe re-compressed + // and maybe re-encrypted. + // + // This test checks if the source for the entry data is a zip file, and + // if a restream is necessary. If NOT, then it just copies through + // one entry, potentially changing the metadata. + + if (_Source == ZipEntrySource.ZipFile && !_restreamRequiredOnSave) + { + CopyThroughOneEntry(s); + return; + } + + // Is the entry a directory? If so, the write is relatively simple. + if (IsDirectory) + { + WriteHeader(s, 1); + StoreRelativeOffset(); + _entryRequiresZip64 = new Nullable(_RelativeOffsetOfLocalHeader >= 0xFFFFFFFF); + _OutputUsesZip64 = new Nullable(_container.Zip64 == Zip64Option.Always || _entryRequiresZip64.Value); + // handle case for split archives + if (zss1 != null) + _diskNumber = zss1.CurrentSegment; + + return; + } + + // At this point, the source for this entry is not a directory, and + // not a previously created zip file, or the source for the entry IS + // a previously created zip but the settings whave changed in + // important ways and therefore we will need to process the + // bytestream (compute crc, maybe compress, maybe encrypt) in order + // to write the content into the new zip. + // + // We do this in potentially 2 passes: The first time we do it as + // requested, maybe with compression and maybe encryption. If that + // causes the bytestream to inflate in size, and if compression was + // on, then we turn off compression and do it again. + + + bool readAgain = true; + int nCycles = 0; + do + { + nCycles++; + + WriteHeader(s, nCycles); + + // write the encrypted header + WriteSecurityMetadata(s); + + // write the (potentially compressed, potentially encrypted) file data + _WriteEntryData(s); + + // track total entry size (including the trailing descriptor and MAC) + _TotalEntrySize = _LengthOfHeader + _CompressedFileDataSize + _LengthOfTrailer; + + // The file data has now been written to the stream, and + // the file pointer is positioned directly after file data. + + if (nCycles > 1) readAgain = false; + else if (!s.CanSeek) readAgain = false; + else readAgain = WantReadAgain(); + + if (readAgain) + { + // Seek back in the raw output stream, to the beginning of the file + // data for this entry. + + // handle case for split archives + if (zss1 != null) + { + // Console.WriteLine("***_diskNumber/first: {0}", _diskNumber); + // Console.WriteLine("***_diskNumber/current: {0}", zss.CurrentSegment); + zss1.TruncateBackward(_diskNumber, _RelativeOffsetOfLocalHeader); + } + else + // workitem 8098: ok (output). + s.Seek(_RelativeOffsetOfLocalHeader, SeekOrigin.Begin); + + // If the last entry expands, we read again; but here, we must + // truncate the stream to prevent garbage data after the + // end-of-central-directory. + + // workitem 8098: ok (output). + s.SetLength(s.Position); + + // Adjust the count on the CountingStream as necessary. + if (cs1 != null) cs1.Adjust(_TotalEntrySize); + } + } + while (readAgain); + _skippedDuringSave = false; + done = true; + } + catch (System.Exception exc1) + { + ZipErrorAction orig = this.ZipErrorAction; + int loop = 0; + do + { + if (ZipErrorAction == ZipErrorAction.Throw) + throw; + + if (ZipErrorAction == ZipErrorAction.Skip || + ZipErrorAction == ZipErrorAction.Retry) + { + // must reset file pointer here. + // workitem 13903 - seek back only when necessary + long p1 = (cs1 != null) + ? cs1.ComputedPosition + : s.Position; + long delta = p1 - _future_ROLH; + if (delta > 0) + { + s.Seek(delta, SeekOrigin.Current); // may throw + long p2 = s.Position; + s.SetLength(s.Position); // to prevent garbage if this is the last entry + if (cs1 != null) cs1.Adjust(p1 - p2); + } + if (ZipErrorAction == ZipErrorAction.Skip) + { + WriteStatus("Skipping file {0} (exception: {1})", LocalFileName, exc1.ToString()); + + _skippedDuringSave = true; + done = true; + } + else + this.ZipErrorAction = orig; + break; + } + + if (loop > 0) throw; + + if (ZipErrorAction == ZipErrorAction.InvokeErrorEvent) + { + OnZipErrorWhileSaving(exc1); + if (_ioOperationCanceled) + { + done = true; + break; + } + } + loop++; + } + while (true); + } + } + while (!done); + } + + + internal void StoreRelativeOffset() + { + _RelativeOffsetOfLocalHeader = _future_ROLH; + } + + + + internal void NotifySaveComplete() + { + // When updating a zip file, there are two contexts for properties + // like Encryption or CompressionMethod - the values read from the + // original zip file, and the values used in the updated zip file. + // The _FromZipFile versions are the originals. At the end of a save, + // these values are the same. So we need to update them. This takes + // care of the boundary case where a single zipfile instance can be + // saved multiple times, with distinct changes to the properties on + // the entries, in between each Save(). + _Encryption_FromZipFile = _Encryption; + _CompressionMethod_FromZipFile = _CompressionMethod; + _restreamRequiredOnSave = false; + _metadataChanged = false; + //_Source = ZipEntrySource.None; + _Source = ZipEntrySource.ZipFile; // workitem 10694 + } + + + internal void WriteSecurityMetadata(Stream outstream) + { + if (Encryption == EncryptionAlgorithm.None) + return; + + string pwd = this._Password; + + // special handling for source == ZipFile. + // Want to support the case where we re-stream an encrypted entry. This will involve, + // at runtime, reading, decrypting, and decompressing from the original zip file, then + // compressing, encrypting, and writing to the output zip file. + + // If that's what we're doing, and the password hasn't been set on the entry, + // we use the container (ZipFile/ZipOutputStream) password to decrypt. + // This test here says to use the container password to re-encrypt, as well, + // with that password, if the entry password is null. + + if (this._Source == ZipEntrySource.ZipFile && pwd == null) + pwd = this._container.Password; + + if (pwd == null) + { + _zipCrypto_forWrite = null; +#if AESCRYPTO + _aesCrypto_forWrite = null; +#endif + return; + } + + TraceWriteLine("WriteSecurityMetadata: e({0}) crypto({1}) pw({2})", + FileName, Encryption.ToString(), pwd); + + if (Encryption == EncryptionAlgorithm.PkzipWeak) + { + // If PKZip (weak) encryption is in use, then the encrypted entry data + // is preceded by 12-byte "encryption header" for the entry. + + _zipCrypto_forWrite = ZipCrypto.ForWrite(pwd); + + // generate the random 12-byte header: + var rnd = new System.Random(); + byte[] encryptionHeader = new byte[12]; + rnd.NextBytes(encryptionHeader); + + // workitem 8271 + if ((this._BitField & 0x0008) == 0x0008) + { + // In the case that bit 3 of the general purpose bit flag is set to + // indicate the presence of a 'data descriptor' (signature + // 0x08074b50), the last byte of the decrypted header is sometimes + // compared with the high-order byte of the lastmodified time, + // rather than the high-order byte of the CRC, to verify the + // password. + // + // This is not documented in the PKWare Appnote.txt. + // This was discovered this by analysis of the Crypt.c source file in the + // InfoZip library + // http://www.info-zip.org/pub/infozip/ + + // Also, winzip insists on this! + _TimeBlob = Ionic.Zip.SharedUtilities.DateTimeToPacked(LastModified); + encryptionHeader[11] = (byte)((this._TimeBlob >> 8) & 0xff); + } + else + { + // When bit 3 is not set, the CRC value is required before + // encryption of the file data begins. In this case there is no way + // around it: must read the stream in its entirety to compute the + // actual CRC before proceeding. + FigureCrc32(); + encryptionHeader[11] = (byte)((this._Crc32 >> 24) & 0xff); + } + + // Encrypt the random header, INCLUDING the final byte which is either + // the high-order byte of the CRC32, or the high-order byte of the + // _TimeBlob. Must do this BEFORE encrypting the file data. This + // step changes the state of the cipher, or in the words of the PKZIP + // spec, it "further initializes" the cipher keys. + + byte[] cipherText = _zipCrypto_forWrite.EncryptMessage(encryptionHeader, encryptionHeader.Length); + + // Write the ciphered bonafide encryption header. + outstream.Write(cipherText, 0, cipherText.Length); + _LengthOfHeader += cipherText.Length; // 12 bytes + } + +#if AESCRYPTO + else if (Encryption == EncryptionAlgorithm.WinZipAes128 || + Encryption == EncryptionAlgorithm.WinZipAes256) + { + // If WinZip AES encryption is in use, then the encrypted entry data is + // preceded by a variable-sized Salt and a 2-byte "password + // verification" value for the entry. + + int keystrength = GetKeyStrengthInBits(Encryption); + _aesCrypto_forWrite = WinZipAesCrypto.Generate(pwd, keystrength); + outstream.Write(_aesCrypto_forWrite.Salt, 0, _aesCrypto_forWrite._Salt.Length); + outstream.Write(_aesCrypto_forWrite.GeneratedPV, 0, _aesCrypto_forWrite.GeneratedPV.Length); + _LengthOfHeader += _aesCrypto_forWrite._Salt.Length + _aesCrypto_forWrite.GeneratedPV.Length; + + TraceWriteLine("WriteSecurityMetadata: AES e({0}) keybits({1}) _LOH({2})", + FileName, keystrength, _LengthOfHeader); + + } +#endif + + } + + + + private void CopyThroughOneEntry(Stream outStream) + { + // Just read the entry from the existing input zipfile and write to the output. + // But, if metadata has changed (like file times or attributes), or if the ZIP64 + // option has changed, we can re-stream the entry data but must recompute the + // metadata. + if (this.LengthOfHeader == 0) + throw new BadStateException("Bad header length."); + + // is it necessary to re-constitute new metadata for this entry? + bool needRecompute = _metadataChanged || + (this.ArchiveStream is ZipSegmentedStream) || + (outStream is ZipSegmentedStream) || + (_InputUsesZip64 && _container.UseZip64WhenSaving == Zip64Option.Never) || + (!_InputUsesZip64 && _container.UseZip64WhenSaving == Zip64Option.Always); + + if (needRecompute) + CopyThroughWithRecompute(outStream); + else + CopyThroughWithNoChange(outStream); + + // zip64 housekeeping + _entryRequiresZip64 = new Nullable + (_CompressedSize >= 0xFFFFFFFF || _UncompressedSize >= 0xFFFFFFFF || + _RelativeOffsetOfLocalHeader >= 0xFFFFFFFF + ); + + _OutputUsesZip64 = new Nullable(_container.Zip64 == Zip64Option.Always || _entryRequiresZip64.Value); + } + + + + private void CopyThroughWithRecompute(Stream outstream) + { + int n; + byte[] bytes = new byte[BufferSize]; + var input = new CountingStream(this.ArchiveStream); + + long origRelativeOffsetOfHeader = _RelativeOffsetOfLocalHeader; + + // The header length may change due to rename of file, add a comment, etc. + // We need to retain the original. + int origLengthOfHeader = LengthOfHeader; // including crypto bytes! + + // WriteHeader() has the side effect of changing _RelativeOffsetOfLocalHeader + // and setting _LengthOfHeader. While ReadHeader() reads the crypto header if + // present, WriteHeader() does not write the crypto header. + WriteHeader(outstream, 0); + StoreRelativeOffset(); + + if (!this.FileName.EndsWith("/")) + { + // Not a directory; there is file data. + // Seek to the beginning of the entry data in the input stream. + + long pos = origRelativeOffsetOfHeader + origLengthOfHeader; + int len = GetLengthOfCryptoHeaderBytes(_Encryption_FromZipFile); + pos -= len; // want to keep the crypto header + _LengthOfHeader += len; + + input.Seek(pos, SeekOrigin.Begin); + + // copy through everything after the header to the output stream + long remaining = this._CompressedSize; + + while (remaining > 0) + { + len = (remaining > bytes.Length) ? bytes.Length : (int)remaining; + + // read + n = input.Read(bytes, 0, len); + //_CheckRead(n); + + // write + outstream.Write(bytes, 0, n); + remaining -= n; + OnWriteBlock(input.BytesRead, this._CompressedSize); + if (_ioOperationCanceled) + break; + } + + // bit 3 descriptor + if ((this._BitField & 0x0008) == 0x0008) + { + int size = 16; + if (_InputUsesZip64) size += 8; + byte[] Descriptor = new byte[size]; + input.Read(Descriptor, 0, size); + + if (_InputUsesZip64 && _container.UseZip64WhenSaving == Zip64Option.Never) + { + // original descriptor was 24 bytes, now we need 16. + // Must check for underflow here. + // signature + CRC. + outstream.Write(Descriptor, 0, 8); + + // Compressed + if (_CompressedSize > 0xFFFFFFFF) + throw new InvalidOperationException("ZIP64 is required"); + outstream.Write(Descriptor, 8, 4); + + // UnCompressed + if (_UncompressedSize > 0xFFFFFFFF) + throw new InvalidOperationException("ZIP64 is required"); + outstream.Write(Descriptor, 16, 4); + _LengthOfTrailer -= 8; + } + else if (!_InputUsesZip64 && _container.UseZip64WhenSaving == Zip64Option.Always) + { + // original descriptor was 16 bytes, now we need 24 + // signature + CRC + byte[] pad = new byte[4]; + outstream.Write(Descriptor, 0, 8); + // Compressed + outstream.Write(Descriptor, 8, 4); + outstream.Write(pad, 0, 4); + // UnCompressed + outstream.Write(Descriptor, 12, 4); + outstream.Write(pad, 0, 4); + _LengthOfTrailer += 8; + } + else + { + // same descriptor on input and output. Copy it through. + outstream.Write(Descriptor, 0, size); + //_LengthOfTrailer += size; + } + } + } + + _TotalEntrySize = _LengthOfHeader + _CompressedFileDataSize + _LengthOfTrailer; + } + + + private void CopyThroughWithNoChange(Stream outstream) + { + int n; + byte[] bytes = new byte[BufferSize]; + var input = new CountingStream(this.ArchiveStream); + + // seek to the beginning of the entry data in the input stream + input.Seek(this._RelativeOffsetOfLocalHeader, SeekOrigin.Begin); + + if (this._TotalEntrySize == 0) + { + // We've never set the length of the entry. + // Set it here. + this._TotalEntrySize = this._LengthOfHeader + this._CompressedFileDataSize + _LengthOfTrailer; + + // The CompressedSize includes all the leading metadata associated + // to encryption, if any, as well as the compressed data, or + // compressed-then-encrypted data, and the trailer in case of AES. + + // The CompressedFileData size is the same, less the encryption + // framing data (12 bytes header for PKZip; 10/18 bytes header and + // 10 byte trailer for AES). + + // The _LengthOfHeader includes all the zip entry header plus the + // crypto header, if any. The _LengthOfTrailer includes the + // 10-byte MAC for AES, where appropriate, and the bit-3 + // Descriptor, where applicable. + } + + + // workitem 5616 + // remember the offset, within the output stream, of this particular entry header. + // This may have changed if any of the other entries changed (eg, if a different + // entry was removed or added.) + var counter = outstream as CountingStream; + _RelativeOffsetOfLocalHeader = (counter != null) + ? counter.ComputedPosition + : outstream.Position; // BytesWritten + + // copy through the header, filedata, trailer, everything... + long remaining = this._TotalEntrySize; + while (remaining > 0) + { + int len = (remaining > bytes.Length) ? bytes.Length : (int)remaining; + + // read + n = input.Read(bytes, 0, len); + //_CheckRead(n); + + // write + outstream.Write(bytes, 0, n); + remaining -= n; + OnWriteBlock(input.BytesRead, this._TotalEntrySize); + if (_ioOperationCanceled) + break; + } + } + + + + + [System.Diagnostics.ConditionalAttribute("Trace")] + private void TraceWriteLine(string format, params object[] varParams) + { + lock (_outputLock) + { + int tid = System.Threading.Thread.CurrentThread.GetHashCode(); +#if ! (NETCF || SILVERLIGHT) + Console.ForegroundColor = (ConsoleColor)(tid % 8 + 8); +#endif + Console.Write("{0:000} ZipEntry.Write ", tid); + Console.WriteLine(format, varParams); +#if ! (NETCF || SILVERLIGHT) + Console.ResetColor(); +#endif + } + } + + private object _outputLock = new Object(); + } +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipEntry.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipEntry.cs new file mode 100644 index 00000000..fdb576fb --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipEntry.cs @@ -0,0 +1,2968 @@ +// ZipEntry.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2006-2010 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-August-06 17:25:53> +// +// ------------------------------------------------------------------ +// +// This module defines the ZipEntry class, which models the entries within a zip file. +// +// Created: Tue, 27 Mar 2007 15:30 +// +// ------------------------------------------------------------------ + + +using System; +using System.IO; +using Interop = System.Runtime.InteropServices; + +namespace Ionic.Zip +{ + /// + /// Represents a single entry in a ZipFile. Typically, applications get a ZipEntry + /// by enumerating the entries within a ZipFile, or by adding an entry to a ZipFile. + /// + + [Interop.GuidAttribute("ebc25cf6-9120-4283-b972-0e5520d00004")] + [Interop.ComVisible(true)] +#if !NETCF + [Interop.ClassInterface(Interop.ClassInterfaceType.AutoDispatch)] // AutoDual +#endif + public partial class ZipEntry + { + /// + /// Default constructor. + /// + /// + /// Applications should never need to call this directly. It is exposed to + /// support COM Automation environments. + /// + public ZipEntry() + { + _CompressionMethod = (Int16)CompressionMethod.Deflate; + _CompressionLevel = Ionic.Zlib.CompressionLevel.Default; + _Encryption = EncryptionAlgorithm.None; + _Source = ZipEntrySource.None; + AlternateEncoding = System.Text.Encoding.GetEncoding("IBM437"); + AlternateEncodingUsage = ZipOption.Never; + } + + /// + /// The time and date at which the file indicated by the ZipEntry was + /// last modified. + /// + /// + /// + /// + /// The DotNetZip library sets the LastModified value for an entry, equal to + /// the Last Modified time of the file in the filesystem. If an entry is + /// added from a stream, the library uses System.DateTime.Now for this + /// value, for the given entry. + /// + /// + /// + /// This property allows the application to retrieve and possibly set the + /// LastModified value on an entry, to an arbitrary value. values with a + /// setting of DateTimeKind.Unspecified are taken to be expressed as + /// DateTimeKind.Local. + /// + /// + /// + /// Be aware that because of the way PKWare's + /// Zip specification describes how times are stored in the zip file, + /// the full precision of the System.DateTime datatype is not stored + /// for the last modified time when saving zip files. For more information on + /// how times are formatted, see the PKZip specification. + /// + /// + /// + /// The actual last modified time of a file can be stored in multiple ways in + /// the zip file, and they are not mutually exclusive: + /// + /// + /// + /// + /// In the so-called "DOS" format, which has a 2-second precision. Values + /// are rounded to the nearest even second. For example, if the time on the + /// file is 12:34:43, then it will be stored as 12:34:44. This first value + /// is accessible via the LastModified property. This value is always + /// present in the metadata for each zip entry. In some cases the value is + /// invalid, or zero. + /// + /// + /// + /// In the so-called "Windows" or "NTFS" format, as an 8-byte integer + /// quantity expressed as the number of 1/10 milliseconds (in other words + /// the number of 100 nanosecond units) since January 1, 1601 (UTC). This + /// format is how Windows represents file times. This time is accessible + /// via the ModifiedTime property. + /// + /// + /// + /// In the "Unix" format, a 4-byte quantity specifying the number of seconds since + /// January 1, 1970 UTC. + /// + /// + /// + /// In an older format, now deprecated but still used by some current + /// tools. This format is also a 4-byte quantity specifying the number of + /// seconds since January 1, 1970 UTC. + /// + /// + /// + /// + /// + /// Zip tools and libraries will always at least handle (read or write) the + /// DOS time, and may also handle the other time formats. Keep in mind that + /// while the names refer to particular operating systems, there is nothing in + /// the time formats themselves that prevents their use on other operating + /// systems. + /// + /// + /// + /// When reading ZIP files, the DotNetZip library reads the Windows-formatted + /// time, if it is stored in the entry, and sets both LastModified and + /// ModifiedTime to that value. When writing ZIP files, the DotNetZip + /// library by default will write both time quantities. It can also emit the + /// Unix-formatted time if desired (See .) + /// + /// + /// + /// The last modified time of the file created upon a call to + /// ZipEntry.Extract() may be adjusted during extraction to compensate + /// for differences in how the .NET Base Class Library deals with daylight + /// saving time (DST) versus how the Windows filesystem deals with daylight + /// saving time. Raymond Chen provides + /// some good context. + /// + /// + /// + /// In a nutshell: Daylight savings time rules change regularly. In 2007, for + /// example, the inception week of DST changed. In 1977, DST was in place all + /// year round. In 1945, likewise. And so on. Win32 does not attempt to + /// guess which time zone rules were in effect at the time in question. It + /// will render a time as "standard time" and allow the app to change to DST + /// as necessary. .NET makes a different choice. + /// + /// + /// + /// Compare the output of FileInfo.LastWriteTime.ToString("f") with what you + /// see in the Windows Explorer property sheet for a file that was last + /// written to on the other side of the DST transition. For example, suppose + /// the file was last modified on October 17, 2003, during DST but DST is not + /// currently in effect. Explorer's file properties reports Thursday, October + /// 17, 2003, 8:45:38 AM, but .NETs FileInfo reports Thursday, October 17, + /// 2003, 9:45 AM. + /// + /// + /// + /// Win32 says, "Thursday, October 17, 2002 8:45:38 AM PST". Note: Pacific + /// STANDARD Time. Even though October 17 of that year occurred during Pacific + /// Daylight Time, Win32 displays the time as standard time because that's + /// what time it is NOW. + /// + /// + /// + /// .NET BCL assumes that the current DST rules were in place at the time in + /// question. So, .NET says, "Well, if the rules in effect now were also in + /// effect on October 17, 2003, then that would be daylight time" so it + /// displays "Thursday, October 17, 2003, 9:45 AM PDT" - daylight time. + /// + /// + /// + /// So .NET gives a value which is more intuitively correct, but is also + /// potentially incorrect, and which is not invertible. Win32 gives a value + /// which is intuitively incorrect, but is strictly correct. + /// + /// + /// + /// Because of this funkiness, this library adds one hour to the LastModified + /// time on the extracted file, if necessary. That is to say, if the time in + /// question had occurred in what the .NET Base Class Library assumed to be + /// DST. This assumption may be wrong given the constantly changing DST rules, + /// but it is the best we can do. + /// + /// + /// + /// + public DateTime LastModified + { + get { return _LastModified.ToLocalTime(); } + set + { + _LastModified = (value.Kind == DateTimeKind.Unspecified) + ? DateTime.SpecifyKind(value, DateTimeKind.Local) + : value.ToLocalTime(); + _Mtime = Ionic.Zip.SharedUtilities.AdjustTime_Reverse(_LastModified).ToUniversalTime(); + _metadataChanged = true; + } + } + + + private int BufferSize + { + get + { + return this._container.BufferSize; + } + } + + /// + /// Last Modified time for the file represented by the entry. + /// + /// + /// + /// + /// + /// This value corresponds to the "last modified" time in the NTFS file times + /// as described in the Zip + /// specification. When getting this property, the value may be + /// different from . When setting the property, + /// the property also gets set, but with a lower + /// precision. + /// + /// + /// + /// Let me explain. It's going to take a while, so get + /// comfortable. Originally, waaaaay back in 1989 when the ZIP specification + /// was originally described by the esteemed Mr. Phil Katz, the dominant + /// operating system of the time was MS-DOS. MSDOS stored file times with a + /// 2-second precision, because, c'mon, who is ever going to need better + /// resolution than THAT? And so ZIP files, regardless of the platform on + /// which the zip file was created, store file times in exactly the same format that DOS used + /// in 1989. + /// + /// + /// + /// Since then, the ZIP spec has evolved, but the internal format for file + /// timestamps remains the same. Despite the fact that the way times are + /// stored in a zip file is rooted in DOS heritage, any program on any + /// operating system can format a time in this way, and most zip tools and + /// libraries DO - they round file times to the nearest even second and store + /// it just like DOS did 25+ years ago. + /// + /// + /// + /// PKWare extended the ZIP specification to allow a zip file to store what + /// are called "NTFS Times" and "Unix(tm) times" for a file. These are the + /// last write, last access, and file creation + /// times of a particular file. These metadata are not actually specific + /// to NTFS or Unix. They are tracked for each file by NTFS and by various + /// Unix filesystems, but they are also tracked by other filesystems, too. + /// The key point is that the times are formatted in the zip file + /// in the same way that NTFS formats the time (ticks since win32 epoch), + /// or in the same way that Unix formats the time (seconds since Unix + /// epoch). As with the DOS time, any tool or library running on any + /// operating system is capable of formatting a time in one of these ways + /// and embedding it into the zip file. + /// + /// + /// + /// These extended times are higher precision quantities than the DOS time. + /// As described above, the (DOS) LastModified has a precision of 2 seconds. + /// The Unix time is stored with a precision of 1 second. The NTFS time is + /// stored with a precision of 0.0000001 seconds. The quantities are easily + /// convertible, except for the loss of precision you may incur. + /// + /// + /// + /// A zip archive can store the {C,A,M} times in NTFS format, in Unix format, + /// or not at all. Often a tool running on Unix or Mac will embed the times + /// in Unix format (1 second precision), while WinZip running on Windows might + /// embed the times in NTFS format (precision of of 0.0000001 seconds). When + /// reading a zip file with these "extended" times, in either format, + /// DotNetZip represents the values with the + /// ModifiedTime, AccessedTime and CreationTime + /// properties on the ZipEntry. + /// + /// + /// + /// While any zip application or library, regardless of the platform it + /// runs on, could use any of the time formats allowed by the ZIP + /// specification, not all zip tools or libraries do support all these + /// formats. Storing the higher-precision times for each entry is + /// optional for zip files, and many tools and libraries don't use the + /// higher precision quantities at all. The old DOS time, represented by + /// , is guaranteed to be present, though it + /// sometimes unset. + /// + /// + /// + /// Ok, getting back to the question about how the LastModified + /// property relates to this ModifiedTime + /// property... LastModified is always set, while + /// ModifiedTime is not. (The other times stored in the NTFS + /// times extension, CreationTime and AccessedTime also + /// may not be set on an entry that is read from an existing zip file.) + /// When reading a zip file, then LastModified takes the DOS time + /// that is stored with the file. If the DOS time has been stored as zero + /// in the zipfile, then this library will use DateTime.Now for the + /// LastModified value. If the ZIP file was created by an evolved + /// tool, then there will also be higher precision NTFS or Unix times in + /// the zip file. In that case, this library will read those times, and + /// set LastModified and ModifiedTime to the same value, the + /// one corresponding to the last write time of the file. If there are no + /// higher precision times stored for the entry, then ModifiedTime + /// remains unset (likewise AccessedTime and CreationTime), + /// and LastModified keeps its DOS time. + /// + /// + /// + /// When creating zip files with this library, by default the extended time + /// properties (ModifiedTime, AccessedTime, and + /// CreationTime) are set on the ZipEntry instance, and these data are + /// stored in the zip archive for each entry, in NTFS format. If you add an + /// entry from an actual filesystem file, then the entry gets the actual file + /// times for that file, to NTFS-level precision. If you add an entry from a + /// stream, or a string, then the times get the value DateTime.Now. In + /// this case LastModified and ModifiedTime will be identical, + /// to 2 seconds of precision. You can explicitly set the + /// CreationTime, AccessedTime, and ModifiedTime of an + /// entry using the property setters. If you want to set all of those + /// quantities, it's more efficient to use the method. Those + /// changes are not made permanent in the zip file until you call or one of its cousins. + /// + /// + /// + /// When creating a zip file, you can override the default behavior of + /// this library for formatting times in the zip file, disabling the + /// embedding of file times in NTFS format or enabling the storage of file + /// times in Unix format, or both. You may want to do this, for example, + /// when creating a zip file on Windows, that will be consumed on a Mac, + /// by an application that is not hip to the "NTFS times" format. To do + /// this, use the and + /// properties. A valid zip + /// file may store the file times in both formats. But, there are no + /// guarantees that a program running on Mac or Linux will gracefully + /// handle the NTFS-formatted times when Unix times are present, or that a + /// non-DotNetZip-powered application running on Windows will be able to + /// handle file times in Unix format. DotNetZip will always do something + /// reasonable; other libraries or tools may not. When in doubt, test. + /// + /// + /// + /// I'll bet you didn't think one person could type so much about time, eh? + /// And reading it was so enjoyable, too! Well, in appreciation, maybe you + /// should donate? + /// + /// + /// + /// + /// + /// + /// + public DateTime ModifiedTime + { + get { return _Mtime; } + set + { + SetEntryTimes(_Ctime, _Atime, value); + } + } + + /// + /// Last Access time for the file represented by the entry. + /// + /// + /// This value may or may not be meaningful. If the ZipEntry was read from an existing + /// Zip archive, this information may not be available. For an explanation of why, see + /// . + /// + /// + /// + /// + public DateTime AccessedTime + { + get { return _Atime; } + set + { + SetEntryTimes(_Ctime, value, _Mtime); + } + } + + /// + /// The file creation time for the file represented by the entry. + /// + /// + /// + /// This value may or may not be meaningful. If the ZipEntry was read + /// from an existing zip archive, and the creation time was not set on the entry + /// when the zip file was created, then this property may be meaningless. For an + /// explanation of why, see . + /// + /// + /// + /// + public DateTime CreationTime + { + get { return _Ctime; } + set + { + SetEntryTimes(value, _Atime, _Mtime); + } + } + + /// + /// Sets the NTFS Creation, Access, and Modified times for the given entry. + /// + /// + /// + /// + /// When adding an entry from a file or directory, the Creation, Access, and + /// Modified times for the given entry are automatically set from the + /// filesystem values. When adding an entry from a stream or string, the + /// values are implicitly set to DateTime.Now. The application may wish to + /// set these values to some arbitrary value, before saving the archive, and + /// can do so using the various setters. If you want to set all of the times, + /// this method is more efficient. + /// + /// + /// + /// The values you set here will be retrievable with the , and properties. + /// + /// + /// + /// When this method is called, if both and are false, then the + /// EmitTimesInWindowsFormatWhenSaving flag is automatically set. + /// + /// + /// + /// DateTime values provided here without a DateTimeKind are assumed to be Local Time. + /// + /// + /// + /// the creation time of the entry. + /// the last access time of the entry. + /// the last modified time of the entry. + /// + /// + /// + /// + /// + /// + public void SetEntryTimes(DateTime created, DateTime accessed, DateTime modified) + { + _ntfsTimesAreSet = true; + if (created == _zeroHour && created.Kind == _zeroHour.Kind) created = _win32Epoch; + if (accessed == _zeroHour && accessed.Kind == _zeroHour.Kind) accessed = _win32Epoch; + if (modified == _zeroHour && modified.Kind == _zeroHour.Kind) modified = _win32Epoch; + _Ctime = created.ToUniversalTime(); + _Atime = accessed.ToUniversalTime(); + _Mtime = modified.ToUniversalTime(); + _LastModified = _Mtime; + if (!_emitUnixTimes && !_emitNtfsTimes) + _emitNtfsTimes = true; + _metadataChanged = true; + } + + + + /// + /// Specifies whether the Creation, Access, and Modified times for the given + /// entry will be emitted in "Windows format" when the zip archive is saved. + /// + /// + /// + /// + /// An application creating a zip archive can use this flag to explicitly + /// specify that the file times for the entry should or should not be stored + /// in the zip archive in the format used by Windows. The default value of + /// this property is true. + /// + /// + /// + /// When adding an entry from a file or directory, the Creation (), Access (), and Modified + /// () times for the given entry are automatically + /// set from the filesystem values. When adding an entry from a stream or + /// string, all three values are implicitly set to DateTime.Now. Applications + /// can also explicitly set those times by calling . + /// + /// + /// + /// PKWARE's + /// zip specification describes multiple ways to format these times in a + /// zip file. One is the format Windows applications normally use: 100ns ticks + /// since Jan 1, 1601 UTC. The other is a format Unix applications typically + /// use: seconds since January 1, 1970 UTC. Each format can be stored in an + /// "extra field" in the zip entry when saving the zip archive. The former + /// uses an extra field with a Header Id of 0x000A, while the latter uses a + /// header ID of 0x5455. + /// + /// + /// + /// Not all zip tools and libraries can interpret these fields. Windows + /// compressed folders is one that can read the Windows Format timestamps, + /// while I believe the Infozip + /// tools can read the Unix format timestamps. Although the time values are + /// easily convertible, subject to a loss of precision, some tools and + /// libraries may be able to read only one or the other. DotNetZip can read or + /// write times in either or both formats. + /// + /// + /// + /// The times stored are taken from , , and . + /// + /// + /// + /// This property is not mutually exclusive from the property. It is + /// possible that a zip entry can embed the timestamps in both forms, one + /// form, or neither. But, there are no guarantees that a program running on + /// Mac or Linux will gracefully handle NTFS Formatted times, or that a + /// non-DotNetZip-powered application running on Windows will be able to + /// handle file times in Unix format. When in doubt, test. + /// + /// + /// + /// Normally you will use the ZipFile.EmitTimesInWindowsFormatWhenSaving + /// property, to specify the behavior for all entries in a zip, rather than + /// the property on each individual entry. + /// + /// + /// + /// + /// + /// + /// + /// + /// + public bool EmitTimesInWindowsFormatWhenSaving + { + get + { + return _emitNtfsTimes; + } + set + { + _emitNtfsTimes = value; + _metadataChanged = true; + } + } + + /// + /// Specifies whether the Creation, Access, and Modified times for the given + /// entry will be emitted in "Unix(tm) format" when the zip archive is saved. + /// + /// + /// + /// + /// An application creating a zip archive can use this flag to explicitly + /// specify that the file times for the entry should or should not be stored + /// in the zip archive in the format used by Unix. By default this flag is + /// false, meaning the Unix-format times are not stored in the zip + /// archive. + /// + /// + /// + /// When adding an entry from a file or directory, the Creation (), Access (), and Modified + /// () times for the given entry are automatically + /// set from the filesystem values. When adding an entry from a stream or + /// string, all three values are implicitly set to DateTime.Now. Applications + /// can also explicitly set those times by calling . + /// + /// + /// + /// PKWARE's + /// zip specification describes multiple ways to format these times in a + /// zip file. One is the format Windows applications normally use: 100ns ticks + /// since Jan 1, 1601 UTC. The other is a format Unix applications typically + /// use: seconds since Jan 1, 1970 UTC. Each format can be stored in an + /// "extra field" in the zip entry when saving the zip archive. The former + /// uses an extra field with a Header Id of 0x000A, while the latter uses a + /// header ID of 0x5455. + /// + /// + /// + /// Not all tools and libraries can interpret these fields. Windows + /// compressed folders is one that can read the Windows Format timestamps, + /// while I believe the Infozip + /// tools can read the Unix format timestamps. Although the time values are + /// easily convertible, subject to a loss of precision, some tools and + /// libraries may be able to read only one or the other. DotNetZip can read or + /// write times in either or both formats. + /// + /// + /// + /// The times stored are taken from , , and . + /// + /// + /// + /// This property is not mutually exclusive from the property. It is + /// possible that a zip entry can embed the timestamps in both forms, one + /// form, or neither. But, there are no guarantees that a program running on + /// Mac or Linux will gracefully handle NTFS Formatted times, or that a + /// non-DotNetZip-powered application running on Windows will be able to + /// handle file times in Unix format. When in doubt, test. + /// + /// + /// + /// Normally you will use the ZipFile.EmitTimesInUnixFormatWhenSaving + /// property, to specify the behavior for all entries, rather than the + /// property on each individual entry. + /// + /// + /// + /// + /// + /// + /// + /// + /// + public bool EmitTimesInUnixFormatWhenSaving + { + get + { + return _emitUnixTimes; + } + set + { + _emitUnixTimes = value; + _metadataChanged = true; + } + } + + + /// + /// The type of timestamp attached to the ZipEntry. + /// + /// + /// + /// This property is valid only for a ZipEntry that was read from a zip archive. + /// It indicates the type of timestamp attached to the entry. + /// + /// + /// + /// + public ZipEntryTimestamp Timestamp + { + get + { + return _timestamp; + } + } + + /// + /// The file attributes for the entry. + /// + /// + /// + /// + /// + /// The attributes in NTFS include + /// ReadOnly, Archive, Hidden, System, and Indexed. When adding a + /// ZipEntry to a ZipFile, these attributes are set implicitly when + /// adding an entry from the filesystem. When adding an entry from a stream + /// or string, the Attributes are not set implicitly. Regardless of the way + /// an entry was added to a ZipFile, you can set the attributes + /// explicitly if you like. + /// + /// + /// + /// When reading a ZipEntry from a ZipFile, the attributes are + /// set according to the data stored in the ZipFile. If you extract the + /// entry from the archive to a filesystem file, DotNetZip will set the + /// attributes on the resulting file accordingly. + /// + /// + /// + /// The attributes can be set explicitly by the application. For example the + /// application may wish to set the FileAttributes.ReadOnly bit for all + /// entries added to an archive, so that on unpack, this attribute will be set + /// on the extracted file. Any changes you make to this property are made + /// permanent only when you call a Save() method on the ZipFile + /// instance that contains the ZipEntry. + /// + /// + /// + /// For example, an application may wish to zip up a directory and set the + /// ReadOnly bit on every file in the archive, so that upon later extraction, + /// the resulting files will be marked as ReadOnly. Not every extraction tool + /// respects these attributes, but if you unpack with DotNetZip, as for + /// example in a self-extracting archive, then the attributes will be set as + /// they are stored in the ZipFile. + /// + /// + /// + /// These attributes may not be interesting or useful if the resulting archive + /// is extracted on a non-Windows platform. How these attributes get used + /// upon extraction depends on the platform and tool used. + /// + /// + /// + /// This property is only partially supported in the Silverlight version + /// of the library: applications can read attributes on entries within + /// ZipFiles. But extracting entries within Silverlight will not set the + /// attributes on the extracted files. + /// + /// + /// + public System.IO.FileAttributes Attributes + { + // workitem 7071 + get { return (System.IO.FileAttributes)_ExternalFileAttrs; } + set + { + _ExternalFileAttrs = (int)value; + // Since the application is explicitly setting the attributes, overwriting + // whatever was there, we will explicitly set the Version made by field. + // workitem 7926 - "version made by" OS should be zero for compat with WinZip + _VersionMadeBy = (0 << 8) + 45; // v4.5 of the spec + _metadataChanged = true; + } + } + + + /// + /// The name of the filesystem file, referred to by the ZipEntry. + /// + /// + /// + /// + /// This property specifies the thing-to-be-zipped on disk, and is set only + /// when the ZipEntry is being created from a filesystem file. If the + /// ZipFile is instantiated by reading an existing .zip archive, then + /// the LocalFileName will be null (Nothing in VB). + /// + /// + /// + /// When it is set, the value of this property may be different than , which is the path used in the archive itself. If you + /// call Zip.AddFile("foop.txt", AlternativeDirectory), then the path + /// used for the ZipEntry within the zip archive will be different + /// than this path. + /// + /// + /// + /// If the entry is being added from a stream, then this is null (Nothing in VB). + /// + /// + /// + /// + internal string LocalFileName + { + get { return _LocalFileName; } + } + + /// + /// The name of the file contained in the ZipEntry. + /// + /// + /// + /// + /// + /// This is the name of the entry in the ZipFile itself. When creating + /// a zip archive, if the ZipEntry has been created from a filesystem + /// file, via a call to or , or a related overload, the value + /// of this property is derived from the name of that file. The + /// FileName property does not include drive letters, and may include a + /// different directory path, depending on the value of the + /// directoryPathInArchive parameter used when adding the entry into + /// the ZipFile. + /// + /// + /// + /// In some cases there is no related filesystem file - for example when a + /// ZipEntry is created using or one of the similar overloads. In this case, the value of + /// this property is derived from the fileName and the directory path passed + /// to that method. + /// + /// + /// + /// When reading a zip file, this property takes the value of the entry name + /// as stored in the zip file. If you extract such an entry, the extracted + /// file will take the name given by this property. + /// + /// + /// + /// Applications can set this property when creating new zip archives or when + /// reading existing archives. When setting this property, the actual value + /// that is set will replace backslashes with forward slashes, in accordance + /// with the Zip + /// specification, for compatibility with Unix(tm) and ... get + /// this.... Amiga! + /// + /// + /// + /// If an application reads a ZipFile via or a related overload, and then explicitly + /// sets the FileName on an entry contained within the ZipFile, and + /// then calls , the application will effectively + /// rename the entry within the zip archive. + /// + /// + /// + /// If an application sets the value of FileName, then calls + /// Extract() on the entry, the entry is extracted to a file using the + /// newly set value as the filename. The FileName value is made + /// permanent in the zip archive only after a call to one of the + /// ZipFile.Save() methods on the ZipFile that contains the + /// ZipEntry. + /// + /// + /// + /// If an application attempts to set the FileName to a value that + /// would result in a duplicate entry in the ZipFile, an exception is + /// thrown. + /// + /// + /// + /// When a ZipEntry is contained within a ZipFile, applications + /// cannot rename the entry within the context of a foreach (For + /// Each in VB) loop, because of the way the ZipFile stores + /// entries. If you need to enumerate through all the entries and rename one + /// or more of them, use ZipFile.EntriesSorted as the + /// collection. See also, ZipFile.GetEnumerator(). + /// + /// + /// + public string FileName + { + get { return _FileNameInArchive; } + set + { + if (_container.ZipFile == null) + throw new ZipException("Cannot rename; this is not supported in ZipOutputStream/ZipInputStream."); + + // rename the entry! + if (String.IsNullOrEmpty(value)) throw new ZipException("The FileName must be non empty and non-null."); + + var filename = ZipEntry.NameInArchive(value, null); + // workitem 8180 + if (_FileNameInArchive == filename) return; // nothing to do + + // workitem 8047 - when renaming, must remove old and then add a new entry + this._container.ZipFile.RemoveEntry(this); + this._container.ZipFile.InternalAddEntry(filename, this); + + _FileNameInArchive = filename; + _container.ZipFile.NotifyEntryChanged(); + _metadataChanged = true; + } + } + + + /// + /// The stream that provides content for the ZipEntry. + /// + /// + /// + /// + /// + /// The application can use this property to set the input stream for an + /// entry on a just-in-time basis. Imagine a scenario where the application + /// creates a ZipFile comprised of content obtained from hundreds of + /// files, via calls to AddFile(). The DotNetZip library opens streams + /// on these files on a just-in-time basis, only when writing the entry out to + /// an external store within the scope of a ZipFile.Save() call. Only + /// one input stream is opened at a time, as each entry is being written out. + /// + /// + /// + /// Now imagine a different application that creates a ZipFile + /// with content obtained from hundreds of streams, added through . Normally the + /// application would supply an open stream to that call. But when large + /// numbers of streams are being added, this can mean many open streams at one + /// time, unnecessarily. + /// + /// + /// + /// To avoid this, call and specify delegates that open and close the stream at + /// the time of Save. + /// + /// + /// + /// + /// Setting the value of this property when the entry was not added from a + /// stream (for example, when the ZipEntry was added with or , or when the entry was added by + /// reading an existing zip archive) will throw an exception. + /// + /// + /// + /// + public Stream InputStream + { + get { return _sourceStream; } + + set + { + if (this._Source != ZipEntrySource.Stream) + throw new ZipException("You must not set the input stream for this entry."); + + _sourceWasJitProvided = true; + _sourceStream = value; + } + } + + + /// + /// A flag indicating whether the InputStream was provided Just-in-time. + /// + /// + /// + /// + /// + /// When creating a zip archive, an application can obtain content for one or + /// more of the ZipEntry instances from streams, using the method. At the time + /// of calling that method, the application can supply null as the value of + /// the stream parameter. By doing so, the application indicates to the + /// library that it will provide a stream for the entry on a just-in-time + /// basis, at the time one of the ZipFile.Save() methods is called and + /// the data for the various entries are being compressed and written out. + /// + /// + /// + /// In this case, the application can set the + /// property, typically within the SaveProgress event (event type: ) for that entry. + /// + /// + /// + /// The application will later want to call Close() and Dispose() on that + /// stream. In the SaveProgress event, when the event type is , the application can + /// do so. This flag indicates that the stream has been provided by the + /// application on a just-in-time basis and that it is the application's + /// responsibility to call Close/Dispose on that stream. + /// + /// + /// + /// + public bool InputStreamWasJitProvided + { + get { return _sourceWasJitProvided; } + } + + + + /// + /// An enum indicating the source of the ZipEntry. + /// + public ZipEntrySource Source + { + get { return _Source; } + } + + + /// + /// The version of the zip engine needed to read the ZipEntry. + /// + /// + /// + /// + /// This is a readonly property, indicating the version of the Zip + /// specification that the extracting tool or library must support to + /// extract the given entry. Generally higher versions indicate newer + /// features. Older zip engines obviously won't know about new features, and + /// won't be able to extract entries that depend on those newer features. + /// + /// + /// + /// + /// value + /// Features + /// + /// + /// + /// 20 + /// a basic Zip Entry, potentially using PKZIP encryption. + /// + /// + /// + /// + /// 45 + /// The ZIP64 extension is used on the entry. + /// + /// + /// + /// + /// 46 + /// File is compressed using BZIP2 compression* + /// + /// + /// + /// 50 + /// File is encrypted using PkWare's DES, 3DES, (broken) RC2 or RC4 + /// + /// + /// + /// 51 + /// File is encrypted using PKWare's AES encryption or corrected RC2 encryption. + /// + /// + /// + /// 52 + /// File is encrypted using corrected RC2-64 encryption** + /// + /// + /// + /// 61 + /// File is encrypted using non-OAEP key wrapping*** + /// + /// + /// + /// 63 + /// File is compressed using LZMA, PPMd+, Blowfish, or Twofish + /// + /// + /// + /// + /// + /// There are other values possible, not listed here. DotNetZip supports + /// regular PKZip encryption, and ZIP64 extensions. DotNetZip cannot extract + /// entries that require a zip engine higher than 45. + /// + /// + /// + /// This value is set upon reading an existing zip file, or after saving a zip + /// archive. + /// + /// + public Int16 VersionNeeded + { + get { return _VersionNeeded; } + } + + /// + /// The comment attached to the ZipEntry. + /// + /// + /// + /// + /// Each entry in a zip file can optionally have a comment associated to + /// it. The comment might be displayed by a zip tool during extraction, for + /// example. + /// + /// + /// + /// By default, the Comment is encoded in IBM437 code page. You can + /// specify an alternative with and + /// . + /// + /// + /// + /// + public string Comment + { + get { return _Comment; } + set + { + _Comment = value; + _metadataChanged = true; + } + } + + + /// + /// Indicates whether the entry requires ZIP64 extensions. + /// + /// + /// + /// + /// + /// This property is null (Nothing in VB) until a Save() method on the + /// containing instance has been called. The property is + /// non-null (HasValue is true) only after a Save() method has + /// been called. + /// + /// + /// + /// After the containing ZipFile has been saved, the Value of this + /// property is true if any of the following three conditions holds: the + /// uncompressed size of the entry is larger than 0xFFFFFFFF; the compressed + /// size of the entry is larger than 0xFFFFFFFF; the relative offset of the + /// entry within the zip archive is larger than 0xFFFFFFFF. These quantities + /// are not known until a Save() is attempted on the zip archive and + /// the compression is applied. + /// + /// + /// + /// If none of the three conditions holds, then the Value is false. + /// + /// + /// + /// A Value of false does not indicate that the entry, as saved in the + /// zip archive, does not use ZIP64. It merely indicates that ZIP64 is + /// not required. An entry may use ZIP64 even when not required if + /// the property on the containing + /// ZipFile instance is set to , or if + /// the property on the containing + /// ZipFile instance is set to + /// and the output stream was not seekable. + /// + /// + /// + /// + public Nullable RequiresZip64 + { + get + { + return _entryRequiresZip64; + } + } + + /// + /// Indicates whether the entry actually used ZIP64 extensions, as it was most + /// recently written to the output file or stream. + /// + /// + /// + /// + /// + /// This Nullable property is null (Nothing in VB) until a Save() + /// method on the containing instance has been + /// called. HasValue is true only after a Save() method has been + /// called. + /// + /// + /// + /// The value of this property for a particular ZipEntry may change + /// over successive calls to Save() methods on the containing ZipFile, + /// even if the file that corresponds to the ZipEntry does not. This + /// may happen if other entries contained in the ZipFile expand, + /// causing the offset for this particular entry to exceed 0xFFFFFFFF. + /// + /// + /// + public Nullable OutputUsedZip64 + { + get { return _OutputUsesZip64; } + } + + + /// + /// The bitfield for the entry as defined in the zip spec. You probably + /// never need to look at this. + /// + /// + /// + /// + /// You probably do not need to concern yourself with the contents of this + /// property, but in case you do: + /// + /// + /// + /// + /// bit + /// meaning + /// + /// + /// + /// 0 + /// set if encryption is used. + /// + /// + /// + /// 1-2 + /// + /// set to determine whether normal, max, fast deflation. DotNetZip library + /// always leaves these bits unset when writing (indicating "normal" + /// deflation"), but can read an entry with any value here. + /// + /// + /// + /// + /// 3 + /// + /// Indicates that the Crc32, Compressed and Uncompressed sizes are zero in the + /// local header. This bit gets set on an entry during writing a zip file, when + /// it is saved to a non-seekable output stream. + /// + /// + /// + /// + /// + /// 4 + /// reserved for "enhanced deflating". This library doesn't do enhanced deflating. + /// + /// + /// + /// 5 + /// set to indicate the zip is compressed patched data. This library doesn't do that. + /// + /// + /// + /// 6 + /// + /// set if PKWare's strong encryption is used (must also set bit 1 if bit 6 is + /// set). This bit is not set if WinZip's AES encryption is set. + /// + /// + /// + /// 7 + /// not used + /// + /// + /// + /// 8 + /// not used + /// + /// + /// + /// 9 + /// not used + /// + /// + /// + /// 10 + /// not used + /// + /// + /// + /// 11 + /// + /// Language encoding flag (EFS). If this bit is set, the filename and comment + /// fields for this file must be encoded using UTF-8. This library currently + /// does not support UTF-8. + /// + /// + /// + /// + /// 12 + /// Reserved by PKWARE for enhanced compression. + /// + /// + /// + /// 13 + /// + /// Used when encrypting the Central Directory to indicate selected data + /// values in the Local Header are masked to hide their actual values. See + /// the section in the Zip + /// specification describing the Strong Encryption Specification for + /// details. + /// + /// + /// + /// + /// 14 + /// Reserved by PKWARE. + /// + /// + /// + /// 15 + /// Reserved by PKWARE. + /// + /// + /// + /// + /// + public Int16 BitField + { + get { return _BitField; } + } + + /// + /// The compression method employed for this ZipEntry. + /// + /// + /// + /// + /// + /// The + /// Zip specification allows a variety of compression methods. This + /// library supports just two: 0x08 = Deflate. 0x00 = Store (no compression), + /// for reading or writing. + /// + /// + /// + /// When reading an entry from an existing zipfile, the value you retrieve + /// here indicates the compression method used on the entry by the original + /// creator of the zip. When writing a zipfile, you can specify either 0x08 + /// (Deflate) or 0x00 (None). If you try setting something else, you will get + /// an exception. + /// + /// + /// + /// You may wish to set CompressionMethod to CompressionMethod.None (0) + /// when zipping already-compressed data like a jpg, png, or mp3 file. + /// This can save time and cpu cycles. + /// + /// + /// + /// When setting this property on a ZipEntry that is read from an + /// existing zip file, calling ZipFile.Save() will cause the new + /// CompressionMethod to be used on the entry in the newly saved zip file. + /// + /// + /// + /// Setting this property may have the side effect of modifying the + /// CompressionLevel property. If you set the CompressionMethod to a + /// value other than None, and CompressionLevel is previously + /// set to None, then CompressionLevel will be set to + /// Default. + /// + /// + /// + /// + /// + /// + /// In this example, the first entry added to the zip archive uses the default + /// behavior - compression is used where it makes sense. The second entry, + /// the MP3 file, is added to the archive without being compressed. + /// + /// using (ZipFile zip = new ZipFile(ZipFileToCreate)) + /// { + /// ZipEntry e1= zip.AddFile(@"notes\Readme.txt"); + /// ZipEntry e2= zip.AddFile(@"music\StopThisTrain.mp3"); + /// e2.CompressionMethod = CompressionMethod.None; + /// zip.Save(); + /// } + /// + /// + /// + /// Using zip As New ZipFile(ZipFileToCreate) + /// zip.AddFile("notes\Readme.txt") + /// Dim e2 as ZipEntry = zip.AddFile("music\StopThisTrain.mp3") + /// e2.CompressionMethod = CompressionMethod.None + /// zip.Save + /// End Using + /// + /// + public CompressionMethod CompressionMethod + { + get { return (CompressionMethod)_CompressionMethod; } + set + { + if (value == (CompressionMethod)_CompressionMethod) return; // nothing to do. + + if (value != CompressionMethod.None && value != CompressionMethod.Deflate +#if BZIP + && value != CompressionMethod.BZip2 +#endif + ) + throw new InvalidOperationException("Unsupported compression method."); + + // If the source is a zip archive and there was encryption on the + // entry, changing the compression method is not supported. + // if (this._Source == ZipEntrySource.ZipFile && _sourceIsEncrypted) + // throw new InvalidOperationException("Cannot change compression method on encrypted entries read from archives."); + + _CompressionMethod = (Int16)value; + + if (_CompressionMethod == (Int16)Ionic.Zip.CompressionMethod.None) + _CompressionLevel = Ionic.Zlib.CompressionLevel.None; + else if (CompressionLevel == Ionic.Zlib.CompressionLevel.None) + _CompressionLevel = Ionic.Zlib.CompressionLevel.Default; + + if (_container.ZipFile != null) _container.ZipFile.NotifyEntryChanged(); + _restreamRequiredOnSave = true; + } + } + + + /// + /// Sets the compression level to be used for the entry when saving the zip + /// archive. This applies only for CompressionMethod = DEFLATE. + /// + /// + /// + /// + /// When using the DEFLATE compression method, Varying the compression + /// level used on entries can affect the size-vs-speed tradeoff when + /// compression and decompressing data streams or files. + /// + /// + /// + /// If you do not set this property, the default compression level is used, + /// which normally gives a good balance of compression efficiency and + /// compression speed. In some tests, using BestCompression can + /// double the time it takes to compress, while delivering just a small + /// increase in compression efficiency. This behavior will vary with the + /// type of data you compress. If you are in doubt, just leave this setting + /// alone, and accept the default. + /// + /// + /// + /// When setting this property on a ZipEntry that is read from an + /// existing zip file, calling ZipFile.Save() will cause the new + /// CompressionLevel to be used on the entry in the newly saved zip file. + /// + /// + /// + /// Setting this property may have the side effect of modifying the + /// CompressionMethod property. If you set the CompressionLevel + /// to a value other than None, CompressionMethod will be set + /// to Deflate, if it was previously None. + /// + /// + /// + /// Setting this property has no effect if the CompressionMethod is something + /// other than Deflate or None. + /// + /// + /// + /// + public Ionic.Zlib.CompressionLevel CompressionLevel + { + get + { + return _CompressionLevel; + } + set + { + if (_CompressionMethod != (short)CompressionMethod.Deflate && + _CompressionMethod != (short)CompressionMethod.None) + return ; // no effect + + if (value == Ionic.Zlib.CompressionLevel.Default && + _CompressionMethod == (short)CompressionMethod.Deflate) return; // nothing to do + _CompressionLevel = value; + + if (value == Ionic.Zlib.CompressionLevel.None && + _CompressionMethod == (short)CompressionMethod.None) + return; // nothing more to do + + if (_CompressionLevel == Ionic.Zlib.CompressionLevel.None) + _CompressionMethod = (short) Ionic.Zip.CompressionMethod.None; + else + _CompressionMethod = (short) Ionic.Zip.CompressionMethod.Deflate; + + if (_container.ZipFile != null) _container.ZipFile.NotifyEntryChanged(); + _restreamRequiredOnSave = true; + } + } + + + + /// + /// The compressed size of the file, in bytes, within the zip archive. + /// + /// + /// + /// When reading a ZipFile, this value is read in from the existing + /// zip file. When creating or updating a ZipFile, the compressed + /// size is computed during compression. Therefore the value on a + /// ZipEntry is valid after a call to Save() (or one of its + /// overloads) in that case. + /// + /// + /// + public Int64 CompressedSize + { + get { return _CompressedSize; } + } + + /// + /// The size of the file, in bytes, before compression, or after extraction. + /// + /// + /// + /// When reading a ZipFile, this value is read in from the existing + /// zip file. When creating or updating a ZipFile, the uncompressed + /// size is computed during compression. Therefore the value on a + /// ZipEntry is valid after a call to Save() (or one of its + /// overloads) in that case. + /// + /// + /// + public Int64 UncompressedSize + { + get { return _UncompressedSize; } + } + + /// + /// The ratio of compressed size to uncompressed size of the ZipEntry. + /// + /// + /// + /// + /// This is a ratio of the compressed size to the uncompressed size of the + /// entry, expressed as a double in the range of 0 to 100+. A value of 100 + /// indicates no compression at all. It could be higher than 100 when the + /// compression algorithm actually inflates the data, as may occur for small + /// files, or uncompressible data that is encrypted. + /// + /// + /// + /// You could format it for presentation to a user via a format string of + /// "{3,5:F0}%" to see it as a percentage. + /// + /// + /// + /// If the size of the original uncompressed file is 0, implying a + /// denominator of 0, the return value will be zero. + /// + /// + /// + /// This property is valid after reading in an existing zip file, or after + /// saving the ZipFile that contains the ZipEntry. You cannot know the + /// effect of a compression transform until you try it. + /// + /// + /// + public Double CompressionRatio + { + get + { + if (UncompressedSize == 0) return 0; + return 100 * (1.0 - (1.0 * CompressedSize) / (1.0 * UncompressedSize)); + } + } + + /// + /// The 32-bit CRC (Cyclic Redundancy Check) on the contents of the ZipEntry. + /// + /// + /// + /// + /// You probably don't need to concern yourself with this. It is used + /// internally by DotNetZip to verify files or streams upon extraction. + /// + /// The value is a 32-bit + /// CRC using 0xEDB88320 for the polynomial. This is the same CRC-32 used in + /// PNG, MPEG-2, and other protocols and formats. It is a read-only property; when + /// creating a Zip archive, the CRC for each entry is set only after a call to + /// Save() on the containing ZipFile. When reading an existing zip file, the value + /// of this property reflects the stored CRC for the entry. + /// + /// + public Int32 Crc + { + get { return _Crc32; } + } + + /// + /// True if the entry is a directory (not a file). + /// This is a readonly property on the entry. + /// + public bool IsDirectory + { + get { return _IsDirectory; } + } + + /// + /// A derived property that is true if the entry uses encryption. + /// + /// + /// + /// + /// This is a readonly property on the entry. When reading a zip file, + /// the value for the ZipEntry is determined by the data read + /// from the zip file. After saving a ZipFile, the value of this + /// property for each ZipEntry indicates whether encryption was + /// actually used (which will have been true if the was set and the property + /// was something other than . + /// + /// + public bool UsesEncryption + { + get { return (_Encryption_FromZipFile != EncryptionAlgorithm.None); } + } + + + /// + /// Set this to specify which encryption algorithm to use for the entry when + /// saving it to a zip archive. + /// + /// + /// + /// + /// + /// Set this property in order to encrypt the entry when the ZipFile is + /// saved. When setting this property, you must also set a on the entry. If you set a value other than on this property and do not set a + /// Password then the entry will not be encrypted. The ZipEntry + /// data is encrypted as the ZipFile is saved, when you call or one of its cousins on the containing + /// ZipFile instance. You do not need to specify the Encryption + /// when extracting entries from an archive. + /// + /// + /// + /// The Zip specification from PKWare defines a set of encryption algorithms, + /// and the data formats for the zip archive that support them, and PKWare + /// supports those algorithms in the tools it produces. Other vendors of tools + /// and libraries, such as WinZip or Xceed, typically support a + /// subset of the algorithms specified by PKWare. These tools can + /// sometimes support additional different encryption algorithms and data + /// formats, not specified by PKWare. The AES Encryption specified and + /// supported by WinZip is the most popular example. This library supports a + /// subset of the complete set of algorithms specified by PKWare and other + /// vendors. + /// + /// + /// + /// There is no common, ubiquitous multi-vendor standard for strong encryption + /// within zip files. There is broad support for so-called "traditional" Zip + /// encryption, sometimes called Zip 2.0 encryption, as specified + /// by PKWare, but this encryption is considered weak and + /// breakable. This library currently supports the Zip 2.0 "weak" encryption, + /// and also a stronger WinZip-compatible AES encryption, using either 128-bit + /// or 256-bit key strength. If you want DotNetZip to support an algorithm + /// that is not currently supported, call the author of this library and maybe + /// we can talk business. + /// + /// + /// + /// The class also has a property. In most cases you will use + /// that property when setting encryption. This property takes + /// precedence over any Encryption set on the ZipFile itself. + /// Typically, you would use the per-entry Encryption when most entries in the + /// zip archive use one encryption algorithm, and a few entries use a + /// different one. If all entries in the zip file use the same Encryption, + /// then it is simpler to just set this property on the ZipFile itself, when + /// creating a zip archive. + /// + /// + /// + /// Some comments on updating archives: If you read a ZipFile, you can + /// modify the Encryption on an encrypted entry: you can remove encryption + /// from an entry that was encrypted; you can encrypt an entry that was not + /// encrypted previously; or, you can change the encryption algorithm. The + /// changes in encryption are not made permanent until you call Save() on the + /// ZipFile. To effect changes in encryption, the entry content is + /// streamed through several transformations, depending on the modification + /// the application has requested. For example if the entry is not encrypted + /// and the application sets Encryption to PkzipWeak, then at + /// the time of Save(), the original entry is read and decompressed, + /// then re-compressed and encrypted. Conversely, if the original entry is + /// encrypted with PkzipWeak encryption, and the application sets the + /// Encryption property to WinZipAes128, then at the time of + /// Save(), the original entry is decrypted via PKZIP encryption and + /// decompressed, then re-compressed and re-encrypted with AES. This all + /// happens automatically within the library, but it can be time-consuming for + /// large entries. + /// + /// + /// + /// Additionally, when updating archives, it is not possible to change the + /// password when changing the encryption algorithm. To change both the + /// algorithm and the password, you need to Save() the zipfile twice. First + /// set the Encryption to None, then call Save(). Then set the + /// Encryption to the new value (not "None"), then call Save() + /// once again. + /// + /// + /// + /// The WinZip AES encryption algorithms are not supported on the .NET Compact + /// Framework. + /// + /// + /// + /// + /// + /// This example creates a zip archive that uses encryption, and then extracts + /// entries from the archive. When creating the zip archive, the ReadMe.txt + /// file is zipped without using a password or encryption. The other file + /// uses encryption. + /// + /// + /// // Create a zip archive with AES Encryption. + /// using (ZipFile zip = new ZipFile()) + /// { + /// zip.AddFile("ReadMe.txt") + /// ZipEntry e1= zip.AddFile("2008-Regional-Sales-Report.pdf"); + /// e1.Encryption= EncryptionAlgorithm.WinZipAes256; + /// e1.Password= "Top.Secret.No.Peeking!"; + /// zip.Save("EncryptedArchive.zip"); + /// } + /// + /// // Extract a zip archive that uses AES Encryption. + /// // You do not need to specify the algorithm during extraction. + /// using (ZipFile zip = ZipFile.Read("EncryptedArchive.zip")) + /// { + /// // Specify the password that is used during extraction, for + /// // all entries that require a password: + /// zip.Password= "Top.Secret.No.Peeking!"; + /// zip.ExtractAll("extractDirectory"); + /// } + /// + /// + /// + /// ' Create a zip that uses Encryption. + /// Using zip As New ZipFile() + /// zip.AddFile("ReadMe.txt") + /// Dim e1 as ZipEntry + /// e1= zip.AddFile("2008-Regional-Sales-Report.pdf") + /// e1.Encryption= EncryptionAlgorithm.WinZipAes256 + /// e1.Password= "Top.Secret.No.Peeking!" + /// zip.Save("EncryptedArchive.zip") + /// End Using + /// + /// ' Extract a zip archive that uses AES Encryption. + /// ' You do not need to specify the algorithm during extraction. + /// Using (zip as ZipFile = ZipFile.Read("EncryptedArchive.zip")) + /// ' Specify the password that is used during extraction, for + /// ' all entries that require a password: + /// zip.Password= "Top.Secret.No.Peeking!" + /// zip.ExtractAll("extractDirectory") + /// End Using + /// + /// + /// + /// + /// + /// Thrown in the setter if EncryptionAlgorithm.Unsupported is specified. + /// + /// + /// ZipEntry.Password + /// ZipFile.Encryption + public EncryptionAlgorithm Encryption + { + get + { + return _Encryption; + } + set + { + if (value == _Encryption) return; // no change + + if (value == EncryptionAlgorithm.Unsupported) + throw new InvalidOperationException("You may not set Encryption to that value."); + + // If the source is a zip archive and there was encryption + // on the entry, this will not work. + //if (this._Source == ZipEntrySource.ZipFile && _sourceIsEncrypted) + // throw new InvalidOperationException("You cannot change the encryption method on encrypted entries read from archives."); + + _Encryption = value; + _restreamRequiredOnSave = true; + if (_container.ZipFile!=null) + _container.ZipFile.NotifyEntryChanged(); + } + } + + + /// + /// The Password to be used when encrypting a ZipEntry upon + /// ZipFile.Save(), or when decrypting an entry upon Extract(). + /// + /// + /// + /// + /// This is a write-only property on the entry. Set this to request that the + /// entry be encrypted when writing the zip archive, or set it to specify the + /// password to be used when extracting an existing entry that is encrypted. + /// + /// + /// + /// The password set here is implicitly used to encrypt the entry during the + /// operation, or to decrypt during the or operation. If you set + /// the Password on a ZipEntry after calling Save(), there is no + /// effect. + /// + /// + /// + /// Consider setting the property when using a + /// password. Answering concerns that the standard password protection + /// supported by all zip tools is weak, WinZip has extended the ZIP + /// specification with a way to use AES Encryption to protect entries in the + /// Zip file. Unlike the "PKZIP 2.0" encryption specified in the PKZIP + /// specification, AES + /// Encryption uses a standard, strong, tested, encryption + /// algorithm. DotNetZip can create zip archives that use WinZip-compatible + /// AES encryption, if you set the property. But, + /// archives created that use AES encryption may not be readable by all other + /// tools and libraries. For example, Windows Explorer cannot read a + /// "compressed folder" (a zip file) that uses AES encryption, though it can + /// read a zip file that uses "PKZIP encryption." + /// + /// + /// + /// The class also has a + /// property. This property takes precedence over any password set on the + /// ZipFile itself. Typically, you would use the per-entry Password when most + /// entries in the zip archive use one password, and a few entries use a + /// different password. If all entries in the zip file use the same password, + /// then it is simpler to just set this property on the ZipFile itself, + /// whether creating a zip archive or extracting a zip archive. + /// + /// + /// + /// Some comments on updating archives: If you read a ZipFile, you + /// cannot modify the password on any encrypted entry, except by extracting + /// the entry with the original password (if any), removing the original entry + /// via , and then adding a new + /// entry with a new Password. + /// + /// + /// + /// For example, suppose you read a ZipFile, and there is an encrypted + /// entry. Setting the Password property on that ZipEntry and then + /// calling Save() on the ZipFile does not update the password + /// on that entry in the archive. Neither is an exception thrown. Instead, + /// what happens during the Save() is the existing entry is copied + /// through to the new zip archive, in its original encrypted form. Upon + /// re-reading that archive, the entry can be decrypted with its original + /// password. + /// + /// + /// + /// If you read a ZipFile, and there is an un-encrypted entry, you can set the + /// Password on the entry and then call Save() on the ZipFile, and get + /// encryption on that entry. + /// + /// + /// + /// + /// + /// + /// This example creates a zip file with two entries, and then extracts the + /// entries from the zip file. When creating the zip file, the two files are + /// added to the zip file using password protection. Each entry uses a + /// different password. During extraction, each file is extracted with the + /// appropriate password. + /// + /// + /// // create a file with encryption + /// using (ZipFile zip = new ZipFile()) + /// { + /// ZipEntry entry; + /// entry= zip.AddFile("Declaration.txt"); + /// entry.Password= "123456!"; + /// entry = zip.AddFile("Report.xls"); + /// entry.Password= "1Secret!"; + /// zip.Save("EncryptedArchive.zip"); + /// } + /// + /// // extract entries that use encryption + /// using (ZipFile zip = ZipFile.Read("EncryptedArchive.zip")) + /// { + /// ZipEntry entry; + /// entry = zip["Declaration.txt"]; + /// entry.Password = "123456!"; + /// entry.Extract("extractDir"); + /// entry = zip["Report.xls"]; + /// entry.Password = "1Secret!"; + /// entry.Extract("extractDir"); + /// } + /// + /// + /// + /// + /// Using zip As New ZipFile + /// Dim entry as ZipEntry + /// entry= zip.AddFile("Declaration.txt") + /// entry.Password= "123456!" + /// entry = zip.AddFile("Report.xls") + /// entry.Password= "1Secret!" + /// zip.Save("EncryptedArchive.zip") + /// End Using + /// + /// + /// ' extract entries that use encryption + /// Using (zip as ZipFile = ZipFile.Read("EncryptedArchive.zip")) + /// Dim entry as ZipEntry + /// entry = zip("Declaration.txt") + /// entry.Password = "123456!" + /// entry.Extract("extractDir") + /// entry = zip("Report.xls") + /// entry.Password = "1Secret!" + /// entry.Extract("extractDir") + /// End Using + /// + /// + /// + /// + /// + /// + /// ZipFile.Password + public string Password + { + set + { + _Password = value; + if (_Password == null) + { + _Encryption = EncryptionAlgorithm.None; + } + else + { + // We're setting a non-null password. + + // For entries obtained from a zip file that are encrypted, we cannot + // simply restream (recompress, re-encrypt) the file data, because we + // need the old password in order to decrypt the data, and then we + // need the new password to encrypt. So, setting the password is + // never going to work on an entry that is stored encrypted in a zipfile. + + // But it is not en error to set the password, obviously: callers will + // set the password in order to Extract encrypted archives. + + // If the source is a zip archive and there was previously no encryption + // on the entry, then we must re-stream the entry in order to encrypt it. + if (this._Source == ZipEntrySource.ZipFile && !_sourceIsEncrypted) + _restreamRequiredOnSave = true; + + if (Encryption == EncryptionAlgorithm.None) + { + _Encryption = EncryptionAlgorithm.PkzipWeak; + } + } + } + private get { return _Password; } + } + + + + internal bool IsChanged + { + get + { + return _restreamRequiredOnSave | _metadataChanged; + } + } + + + /// + /// The action the library should take when extracting a file that already exists. + /// + /// + /// + /// + /// This property affects the behavior of the Extract methods (one of the + /// Extract() or ExtractWithPassword() overloads), when + /// extraction would would overwrite an existing filesystem file. If you do + /// not set this property, the library throws an exception when extracting + /// an entry would overwrite an existing file. + /// + /// + /// + /// This property has no effect when extracting to a stream, or when the file to be + /// extracted does not already exist. + /// + /// + /// + /// + /// + /// + /// This example shows how to set the ExtractExistingFile property in + /// an ExtractProgress event, in response to user input. The + /// ExtractProgress event is invoked if and only if the + /// ExtractExistingFile property was previously set to + /// ExtractExistingFileAction.InvokeExtractProgressEvent. + /// + /// public static void ExtractProgress(object sender, ExtractProgressEventArgs e) + /// { + /// if (e.EventType == ZipProgressEventType.Extracting_BeforeExtractEntry) + /// Console.WriteLine("extract {0} ", e.CurrentEntry.FileName); + /// + /// else if (e.EventType == ZipProgressEventType.Extracting_ExtractEntryWouldOverwrite) + /// { + /// ZipEntry entry = e.CurrentEntry; + /// string response = null; + /// // Ask the user if he wants overwrite the file + /// do + /// { + /// Console.Write("Overwrite {0} in {1} ? (y/n/C) ", entry.FileName, e.ExtractLocation); + /// response = Console.ReadLine(); + /// Console.WriteLine(); + /// + /// } while (response != null && response[0]!='Y' && + /// response[0]!='N' && response[0]!='C'); + /// + /// if (response[0]=='C') + /// e.Cancel = true; + /// else if (response[0]=='Y') + /// entry.ExtractExistingFile = ExtractExistingFileAction.OverwriteSilently; + /// else + /// entry.ExtractExistingFile= ExtractExistingFileAction.DoNotOverwrite; + /// } + /// } + /// + /// + public ExtractExistingFileAction ExtractExistingFile + { + get; + set; + } + + + /// + /// The action to take when an error is encountered while + /// opening or reading files as they are saved into a zip archive. + /// + /// + /// + /// + /// Errors can occur within a call to ZipFile.Save, as the various files contained + /// in a ZipFile are being saved into the zip archive. During the + /// Save, DotNetZip will perform a File.Open on the file + /// associated to the ZipEntry, and then will read the entire contents of + /// the file as it is zipped. Either the open or the Read may fail, because + /// of lock conflicts or other reasons. Using this property, you can + /// specify the action to take when such errors occur. + /// + /// + /// + /// Typically you will NOT set this property on individual ZipEntry + /// instances. Instead, you will set the ZipFile.ZipErrorAction property on + /// the ZipFile instance, before adding any entries to the + /// ZipFile. If you do this, errors encountered on behalf of any of + /// the entries in the ZipFile will be handled the same way. + /// + /// + /// + /// But, if you use a handler, you will want + /// to set this property on the ZipEntry within the handler, to + /// communicate back to DotNetZip what you would like to do with the + /// particular error. + /// + /// + /// + /// + /// + public ZipErrorAction ZipErrorAction + { + get; + set; + } + + + /// + /// Indicates whether the entry was included in the most recent save. + /// + /// + /// An entry can be excluded or skipped from a save if there is an error + /// opening or reading the entry. + /// + /// + public bool IncludedInMostRecentSave + { + get + { + return !_skippedDuringSave; + } + } + + + /// + /// A callback that allows the application to specify the compression to use + /// for a given entry that is about to be added to the zip archive. + /// + /// + /// + /// + /// See + /// + /// + public SetCompressionCallback SetCompression + { + get; + set; + } + + + + /// + /// Set to indicate whether to use UTF-8 encoding for filenames and comments. + /// + /// + /// + /// + /// + /// If this flag is set, the comment and filename for the entry will be + /// encoded with UTF-8, as described in the Zip + /// specification, if necessary. "Necessary" means, the filename or + /// entry comment (if any) cannot be reflexively encoded and decoded using the + /// default code page, IBM437. + /// + /// + /// + /// Setting this flag to true is equivalent to setting to System.Text.Encoding.UTF8. + /// + /// + /// + /// This flag has no effect or relation to the text encoding used within the + /// file itself. + /// + /// + /// + [Obsolete("Beginning with v1.9.1.6 of DotNetZip, this property is obsolete. It will be removed in a future version of the library. Your applications should use AlternateEncoding and AlternateEncodingUsage instead.")] + public bool UseUnicodeAsNecessary + { + get + { + return (AlternateEncoding == System.Text.Encoding.GetEncoding("UTF-8")) && + (AlternateEncodingUsage == ZipOption.AsNecessary); + } + set + { + if (value) + { + AlternateEncoding = System.Text.Encoding.GetEncoding("UTF-8"); + AlternateEncodingUsage = ZipOption.AsNecessary; + + } + else + { + AlternateEncoding = Ionic.Zip.ZipFile.DefaultEncoding; + AlternateEncodingUsage = ZipOption.Never; + } + } + } + + /// + /// The text encoding to use for the FileName and Comment on this ZipEntry, + /// when the default encoding is insufficient. + /// + /// + /// + /// + /// + /// Don't use this property. See . + /// + /// + /// + [Obsolete("This property is obsolete since v1.9.1.6. Use AlternateEncoding and AlternateEncodingUsage instead.", true)] + public System.Text.Encoding ProvisionalAlternateEncoding + { + get; set; + } + + /// + /// Specifies the alternate text encoding used by this ZipEntry + /// + /// + /// + /// The default text encoding used in Zip files for encoding filenames and + /// comments is IBM437, which is something like a superset of ASCII. In + /// cases where this is insufficient, applications can specify an + /// alternate encoding. + /// + /// + /// When creating a zip file, the usage of the alternate encoding is + /// governed by the property. + /// Typically you would set both properties to tell DotNetZip to employ an + /// encoding that is not IBM437 in the zipfile you are creating. + /// + /// + /// Keep in mind that because the ZIP specification states that the only + /// valid encodings to use are IBM437 and UTF-8, if you use something + /// other than that, then zip tools and libraries may not be able to + /// successfully read the zip archive you generate. + /// + /// + /// The zip specification states that applications should presume that + /// IBM437 is in use, except when a special bit is set, which indicates + /// UTF-8. There is no way to specify an arbitrary code page, within the + /// zip file itself. When you create a zip file encoded with gb2312 or + /// ibm861 or anything other than IBM437 or UTF-8, then the application + /// that reads the zip file needs to "know" which code page to use. In + /// some cases, the code page used when reading is chosen implicitly. For + /// example, WinRar uses the ambient code page for the host desktop + /// operating system. The pitfall here is that if you create a zip in + /// Copenhagen and send it to Tokyo, the reader of the zipfile may not be + /// able to decode successfully. + /// + /// + /// + /// This example shows how to create a zipfile encoded with a + /// language-specific encoding: + /// + /// using (var zip = new ZipFile()) + /// { + /// zip.AlternateEnoding = System.Text.Encoding.GetEncoding("ibm861"); + /// zip.AlternateEnodingUsage = ZipOption.Always; + /// zip.AddFileS(arrayOfFiles); + /// zip.Save("Myarchive-Encoded-in-IBM861.zip"); + /// } + /// + /// + /// + public System.Text.Encoding AlternateEncoding + { + get; set; + } + + + /// + /// Describes if and when this instance should apply + /// AlternateEncoding to encode the FileName and Comment, when + /// saving. + /// + /// + public ZipOption AlternateEncodingUsage + { + get; set; + } + + + // /// + // /// The text encoding actually used for this ZipEntry. + // /// + // /// + // /// + // /// + // /// + // /// This read-only property describes the encoding used by the + // /// ZipEntry. If the entry has been read in from an existing ZipFile, + // /// then it may take the value UTF-8, if the entry is coded to specify UTF-8. + // /// If the entry does not specify UTF-8, the typical case, then the encoding + // /// used is whatever the application specified in the call to + // /// ZipFile.Read(). If the application has used one of the overloads of + // /// ZipFile.Read() that does not accept an encoding parameter, then the + // /// encoding used is IBM437, which is the default encoding described in the + // /// ZIP specification. + // /// + // /// + // /// If the entry is being created, then the value of ActualEncoding is taken + // /// according to the logic described in the documentation for . + // /// + // /// + // /// An application might be interested in retrieving this property to see if + // /// an entry read in from a file has used Unicode (UTF-8). + // /// + // /// + // /// + // /// + // public System.Text.Encoding ActualEncoding + // { + // get + // { + // return _actualEncoding; + // } + // } + + + + + internal static string NameInArchive(String filename, string directoryPathInArchive) + { + string result = null; + if (directoryPathInArchive == null) + result = filename; + + else + { + if (String.IsNullOrEmpty(directoryPathInArchive)) + { + result = Path.GetFileName(filename); + } + else + { + // explicitly specify a pathname for this file + result = Path.Combine(directoryPathInArchive, Path.GetFileName(filename)); + } + } + + //result = Path.GetFullPath(result); + result = SharedUtilities.NormalizePathForUseInZipFile(result); + + return result; + } + + // workitem 9073 + internal static ZipEntry CreateFromNothing(String nameInArchive) + { + return Create(nameInArchive, ZipEntrySource.None, null, null); + } + + internal static ZipEntry CreateFromFile(String filename, string nameInArchive) + { + return Create(nameInArchive, ZipEntrySource.FileSystem, filename, null); + } + + internal static ZipEntry CreateForStream(String entryName, Stream s) + { + return Create(entryName, ZipEntrySource.Stream, s, null); + } + + internal static ZipEntry CreateForWriter(String entryName, WriteDelegate d) + { + return Create(entryName, ZipEntrySource.WriteDelegate, d, null); + } + + internal static ZipEntry CreateForJitStreamProvider(string nameInArchive, OpenDelegate opener, CloseDelegate closer) + { + return Create(nameInArchive, ZipEntrySource.JitStream, opener, closer); + } + + internal static ZipEntry CreateForZipOutputStream(string nameInArchive) + { + return Create(nameInArchive, ZipEntrySource.ZipOutputStream, null, null); + } + + + private static ZipEntry Create(string nameInArchive, ZipEntrySource source, Object arg1, Object arg2) + { + if (String.IsNullOrEmpty(nameInArchive)) + throw new Ionic.Zip.ZipException("The entry name must be non-null and non-empty."); + + ZipEntry entry = new ZipEntry(); + + // workitem 7071 + // workitem 7926 - "version made by" OS should be zero for compat with WinZip + entry._VersionMadeBy = (0 << 8) + 45; // indicates the attributes are FAT Attributes, and v4.5 of the spec + entry._Source = source; + entry._Mtime = entry._Atime = entry._Ctime = DateTime.UtcNow; + + if (source == ZipEntrySource.Stream) + { + entry._sourceStream = (arg1 as Stream); // may or may not be null + } + else if (source == ZipEntrySource.WriteDelegate) + { + entry._WriteDelegate = (arg1 as WriteDelegate); // may or may not be null + } + else if (source == ZipEntrySource.JitStream) + { + entry._OpenDelegate = (arg1 as OpenDelegate); // may or may not be null + entry._CloseDelegate = (arg2 as CloseDelegate); // may or may not be null + } + else if (source == ZipEntrySource.ZipOutputStream) + { + } + // workitem 9073 + else if (source == ZipEntrySource.None) + { + // make this a valid value, for later. + entry._Source = ZipEntrySource.FileSystem; + } + else + { + String filename = (arg1 as String); // must not be null + + if (String.IsNullOrEmpty(filename)) + throw new Ionic.Zip.ZipException("The filename must be non-null and non-empty."); + + try + { + // The named file may or may not exist at this time. For + // example, when adding a directory by name. We test existence + // when necessary: when saving the ZipFile, or when getting the + // attributes, and so on. + +#if NETCF + // workitem 6878 + // Ionic.Zip.SharedUtilities.AdjustTime_Win32ToDotNet + entry._Mtime = File.GetLastWriteTime(filename).ToUniversalTime(); + entry._Ctime = File.GetCreationTime(filename).ToUniversalTime(); + entry._Atime = File.GetLastAccessTime(filename).ToUniversalTime(); + + // workitem 7071 + // can only get attributes of files that exist. + if (File.Exists(filename) || Directory.Exists(filename)) + entry._ExternalFileAttrs = (int)NetCfFile.GetAttributes(filename); + +#elif SILVERLIGHT + entry._Mtime = + entry._Ctime = + entry._Atime = System.DateTime.UtcNow; + entry._ExternalFileAttrs = (int)0; +#else + // workitem 6878?? + entry._Mtime = File.GetLastWriteTime(filename).ToUniversalTime(); + entry._Ctime = File.GetCreationTime(filename).ToUniversalTime(); + entry._Atime = File.GetLastAccessTime(filename).ToUniversalTime(); + + // workitem 7071 + // can only get attributes on files that exist. + if (File.Exists(filename) || Directory.Exists(filename)) + entry._ExternalFileAttrs = (int)File.GetAttributes(filename); + +#endif + entry._ntfsTimesAreSet = true; + + entry._LocalFileName = Path.GetFullPath(filename); // workitem 8813 + + } + catch (System.IO.PathTooLongException ptle) + { + // workitem 14035 + var msg = String.Format("The path is too long, filename={0}", + filename); + throw new ZipException(msg, ptle); + } + + } + + entry._LastModified = entry._Mtime; + entry._FileNameInArchive = SharedUtilities.NormalizePathForUseInZipFile(nameInArchive); + // We don't actually slurp in the file data until the caller invokes Write on this entry. + + return entry; + } + + + + + internal void MarkAsDirectory() + { + _IsDirectory = true; + // workitem 6279 + if (!_FileNameInArchive.EndsWith("/")) + _FileNameInArchive += "/"; + } + + + + /// + /// Indicates whether an entry is marked as a text file. Be careful when + /// using on this property. Unless you have a good reason, you should + /// probably ignore this property. + /// + /// + /// + /// + /// The ZIP format includes a provision for specifying whether an entry in + /// the zip archive is a text or binary file. This property exposes that + /// metadata item. Be careful when using this property: It's not clear + /// that this property as a firm meaning, across tools and libraries. + /// + /// + /// + /// To be clear, when reading a zip file, the property value may or may + /// not be set, and its value may or may not be valid. Not all entries + /// that you may think of as "text" entries will be so marked, and entries + /// marked as "text" are not guaranteed in any way to be text entries. + /// Whether the value is set and set correctly depends entirely on the + /// application that produced the zip file. + /// + /// + /// + /// There are many zip tools available, and when creating zip files, some + /// of them "respect" the IsText metadata field, and some of them do not. + /// Unfortunately, even when an application tries to do "the right thing", + /// it's not always clear what "the right thing" is. + /// + /// + /// + /// There's no firm definition of just what it means to be "a text file", + /// and the zip specification does not help in this regard. Twenty years + /// ago, text was ASCII, each byte was less than 127. IsText meant, all + /// bytes in the file were less than 127. These days, it is not the case + /// that all text files have all bytes less than 127. Any unicode file + /// may have bytes that are above 0x7f. The zip specification has nothing + /// to say on this topic. Therefore, it's not clear what IsText really + /// means. + /// + /// + /// + /// This property merely tells a reading application what is stored in the + /// metadata for an entry, without guaranteeing its validity or its + /// meaning. + /// + /// + /// + /// When DotNetZip is used to create a zipfile, it attempts to set this + /// field "correctly." For example, if a file ends in ".txt", this field + /// will be set. Your application may override that default setting. When + /// writing a zip file, you must set the property before calling + /// Save() on the ZipFile. + /// + /// + /// + /// When reading a zip file, a more general way to decide just what kind + /// of file is contained in a particular entry is to use the file type + /// database stored in the operating system. The operating system stores + /// a table that says, a file with .jpg extension is a JPG image file, a + /// file with a .xml extension is an XML document, a file with a .txt is a + /// pure ASCII text document, and so on. To get this information on + /// Windows, you + /// need to read and parse the registry. + /// + /// + /// + /// + /// using (var zip = new ZipFile()) + /// { + /// var e = zip.UpdateFile("Descriptions.mme", ""); + /// e.IsText = true; + /// zip.Save(zipPath); + /// } + /// + /// + /// + /// Using zip As New ZipFile + /// Dim e2 as ZipEntry = zip.AddFile("Descriptions.mme", "") + /// e.IsText= True + /// zip.Save(zipPath) + /// End Using + /// + /// + public bool IsText + { + // workitem 7801 + get { return _IsText; } + set { _IsText = value; } + } + + + + /// Provides a string representation of the instance. + /// a string representation of the instance. + public override String ToString() + { + return String.Format("ZipEntry::{0}", FileName); + } + + + internal Stream ArchiveStream + { + get + { + if (_archiveStream == null) + { + if (_container.ZipFile != null) + { + var zf = _container.ZipFile; + zf.Reset(false); + _archiveStream = zf.StreamForDiskNumber(_diskNumber); + } + else + { + _archiveStream = _container.ZipOutputStream.OutputStream; + } + } + return _archiveStream; + } + } + + + private void SetFdpLoh() + { + // The value for FileDataPosition has not yet been set. + // Therefore, seek to the local header, and figure the start of file data. + // workitem 8098: ok (restore) + long origPosition = this.ArchiveStream.Position; + try + { + this.ArchiveStream.Seek(this._RelativeOffsetOfLocalHeader, SeekOrigin.Begin); + + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(this.ArchiveStream); + } + catch (System.IO.IOException exc1) + { + string description = String.Format("Exception seeking entry({0}) offset(0x{1:X8}) len(0x{2:X8})", + this.FileName, this._RelativeOffsetOfLocalHeader, + this.ArchiveStream.Length); + throw new BadStateException(description, exc1); + } + + byte[] block = new byte[30]; + this.ArchiveStream.Read(block, 0, block.Length); + + // At this point we could verify the contents read from the local header + // with the contents read from the central header. We could, but don't need to. + // So we won't. + + Int16 filenameLength = (short)(block[26] + block[27] * 256); + Int16 extraFieldLength = (short)(block[28] + block[29] * 256); + + // Console.WriteLine(" pos 0x{0:X8} ({0})", this.ArchiveStream.Position); + // Console.WriteLine(" seek 0x{0:X8} ({0})", filenameLength + extraFieldLength); + + this.ArchiveStream.Seek(filenameLength + extraFieldLength, SeekOrigin.Current); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(this.ArchiveStream); + + this._LengthOfHeader = 30 + extraFieldLength + filenameLength + + GetLengthOfCryptoHeaderBytes(_Encryption_FromZipFile); + + // Console.WriteLine(" ROLH 0x{0:X8} ({0})", _RelativeOffsetOfLocalHeader); + // Console.WriteLine(" LOH 0x{0:X8} ({0})", _LengthOfHeader); + // workitem 8098: ok (arithmetic) + this.__FileDataPosition = _RelativeOffsetOfLocalHeader + _LengthOfHeader; + // Console.WriteLine(" FDP 0x{0:X8} ({0})", __FileDataPosition); + + // restore file position: + // workitem 8098: ok (restore) + this.ArchiveStream.Seek(origPosition, SeekOrigin.Begin); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(this.ArchiveStream); + } + + + +#if AESCRYPTO + private static int GetKeyStrengthInBits(EncryptionAlgorithm a) + { + if (a == EncryptionAlgorithm.WinZipAes256) return 256; + else if (a == EncryptionAlgorithm.WinZipAes128) return 128; + return -1; + } +#endif + + internal static int GetLengthOfCryptoHeaderBytes(EncryptionAlgorithm a) + { + //if ((_BitField & 0x01) != 0x01) return 0; + if (a == EncryptionAlgorithm.None) return 0; + +#if AESCRYPTO + if (a == EncryptionAlgorithm.WinZipAes128 || + a == EncryptionAlgorithm.WinZipAes256) + { + int KeyStrengthInBits = GetKeyStrengthInBits(a); + int sizeOfSaltAndPv = ((KeyStrengthInBits / 8 / 2) + 2); + return sizeOfSaltAndPv; + } +#endif + if (a == EncryptionAlgorithm.PkzipWeak) + return 12; + throw new ZipException("internal error"); + } + + + internal long FileDataPosition + { + get + { + if (__FileDataPosition == -1) + SetFdpLoh(); + + return __FileDataPosition; + } + } + + private int LengthOfHeader + { + get + { + if (_LengthOfHeader == 0) + SetFdpLoh(); + + return _LengthOfHeader; + } + } + + + + private ZipCrypto _zipCrypto_forExtract; + private ZipCrypto _zipCrypto_forWrite; +#if AESCRYPTO + private WinZipAesCrypto _aesCrypto_forExtract; + private WinZipAesCrypto _aesCrypto_forWrite; + private Int16 _WinZipAesMethod; +#endif + + internal DateTime _LastModified; + private DateTime _Mtime, _Atime, _Ctime; // workitem 6878: NTFS quantities + private bool _ntfsTimesAreSet; + private bool _emitNtfsTimes = true; + private bool _emitUnixTimes; // by default, false + private bool _TrimVolumeFromFullyQualifiedPaths = true; // by default, trim them. + internal string _LocalFileName; + private string _FileNameInArchive; + internal Int16 _VersionNeeded; + internal Int16 _BitField; + internal Int16 _CompressionMethod; + private Int16 _CompressionMethod_FromZipFile; + private Ionic.Zlib.CompressionLevel _CompressionLevel; + internal string _Comment; + private bool _IsDirectory; + private byte[] _CommentBytes; + internal Int64 _CompressedSize; + internal Int64 _CompressedFileDataSize; // CompressedSize less 12 bytes for the encryption header, if any + internal Int64 _UncompressedSize; + internal Int32 _TimeBlob; + private bool _crcCalculated; + internal Int32 _Crc32; + internal byte[] _Extra; + private bool _metadataChanged; + private bool _restreamRequiredOnSave; + private bool _sourceIsEncrypted; + private bool _skippedDuringSave; + private UInt32 _diskNumber; + + private static System.Text.Encoding ibm437 = System.Text.Encoding.GetEncoding("IBM437"); + //private System.Text.Encoding _provisionalAlternateEncoding = System.Text.Encoding.GetEncoding("IBM437"); + private System.Text.Encoding _actualEncoding; + + internal ZipContainer _container; + + private long __FileDataPosition = -1; + private byte[] _EntryHeader; + internal Int64 _RelativeOffsetOfLocalHeader; + private Int64 _future_ROLH; + private Int64 _TotalEntrySize; + private int _LengthOfHeader; + private int _LengthOfTrailer; + internal bool _InputUsesZip64; + private UInt32 _UnsupportedAlgorithmId; + + internal string _Password; + internal ZipEntrySource _Source; + internal EncryptionAlgorithm _Encryption; + internal EncryptionAlgorithm _Encryption_FromZipFile; + internal byte[] _WeakEncryptionHeader; + internal Stream _archiveStream; + private Stream _sourceStream; + private Nullable _sourceStreamOriginalPosition; + private bool _sourceWasJitProvided; + private bool _ioOperationCanceled; + private bool _presumeZip64; + private Nullable _entryRequiresZip64; + private Nullable _OutputUsesZip64; + private bool _IsText; // workitem 7801 + private ZipEntryTimestamp _timestamp; + + private static System.DateTime _unixEpoch = new System.DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc); + private static System.DateTime _win32Epoch = System.DateTime.FromFileTimeUtc(0L); + private static System.DateTime _zeroHour = new System.DateTime(1, 1, 1, 0, 0, 0, DateTimeKind.Utc); + + private WriteDelegate _WriteDelegate; + private OpenDelegate _OpenDelegate; + private CloseDelegate _CloseDelegate; + + + // summary + // The default size of the IO buffer for ZipEntry instances. Currently it is 8192 bytes. + // summary + //public const int IO_BUFFER_SIZE_DEFAULT = 8192; // 0x8000; // 0x4400 + + } + + + + /// + /// An enum that specifies the type of timestamp available on the ZipEntry. + /// + /// + /// + /// + /// + /// The last modified time of a file can be stored in multiple ways in + /// a zip file, and they are not mutually exclusive: + /// + /// + /// + /// + /// In the so-called "DOS" format, which has a 2-second precision. Values + /// are rounded to the nearest even second. For example, if the time on the + /// file is 12:34:43, then it will be stored as 12:34:44. This first value + /// is accessible via the LastModified property. This value is always + /// present in the metadata for each zip entry. In some cases the value is + /// invalid, or zero. + /// + /// + /// + /// In the so-called "Windows" or "NTFS" format, as an 8-byte integer + /// quantity expressed as the number of 1/10 milliseconds (in other words + /// the number of 100 nanosecond units) since January 1, 1601 (UTC). This + /// format is how Windows represents file times. This time is accessible + /// via the ModifiedTime property. + /// + /// + /// + /// In the "Unix" format, a 4-byte quantity specifying the number of seconds since + /// January 1, 1970 UTC. + /// + /// + /// + /// In an older format, now deprecated but still used by some current + /// tools. This format is also a 4-byte quantity specifying the number of + /// seconds since January 1, 1970 UTC. + /// + /// + /// + /// + /// + /// This bit field describes which of the formats were found in a ZipEntry that was read. + /// + /// + /// + [Flags] + public enum ZipEntryTimestamp + { + /// + /// Default value. + /// + None = 0, + + /// + /// A DOS timestamp with 2-second precision. + /// + DOS = 1, + + /// + /// A Windows timestamp with 100-ns precision. + /// + Windows = 2, + + /// + /// A Unix timestamp with 1-second precision. + /// + Unix = 4, + + /// + /// A Unix timestamp with 1-second precision, stored in InfoZip v1 format. This + /// format is outdated and is supported for reading archives only. + /// + InfoZip1 = 8, + } + + + + /// + /// The method of compression to use for a particular ZipEntry. + /// + /// + /// + /// PKWare's + /// ZIP Specification describes a number of distinct + /// cmopression methods that can be used within a zip + /// file. DotNetZip supports a subset of them. + /// + public enum CompressionMethod + { + /// + /// No compression at all. For COM environments, the value is 0 (zero). + /// + None = 0, + + /// + /// DEFLATE compression, as described in IETF RFC + /// 1951. This is the "normal" compression used in zip + /// files. For COM environments, the value is 8. + /// + Deflate = 8, + +#if BZIP + /// + /// BZip2 compression, a compression algorithm developed by Julian Seward. + /// For COM environments, the value is 12. + /// + BZip2 = 12, +#endif + } + + +#if NETCF + internal class NetCfFile + { + public static int SetTimes(string filename, DateTime ctime, DateTime atime, DateTime mtime) + { + IntPtr hFile = (IntPtr) CreateFileCE(filename, + (uint)0x40000000L, // (uint)FileAccess.Write, + (uint)0x00000002L, // (uint)FileShare.Write, + 0, + (uint) 3, // == open existing + (uint)0, // flagsAndAttributes + 0); + + if((int)hFile == -1) + { + // workitem 7944: don't throw on failure to set file times + // throw new ZipException("CreateFileCE Failed"); + return Interop.Marshal.GetLastWin32Error(); + } + + SetFileTime(hFile, + BitConverter.GetBytes(ctime.ToFileTime()), + BitConverter.GetBytes(atime.ToFileTime()), + BitConverter.GetBytes(mtime.ToFileTime())); + + CloseHandle(hFile); + return 0; + } + + + public static int SetLastWriteTime(string filename, DateTime mtime) + { + IntPtr hFile = (IntPtr) CreateFileCE(filename, + (uint)0x40000000L, // (uint)FileAccess.Write, + (uint)0x00000002L, // (uint)FileShare.Write, + 0, + (uint) 3, // == open existing + (uint)0, // flagsAndAttributes + 0); + + if((int)hFile == -1) + { + // workitem 7944: don't throw on failure to set file time + // throw new ZipException(String.Format("CreateFileCE Failed ({0})", + // Interop.Marshal.GetLastWin32Error())); + return Interop.Marshal.GetLastWin32Error(); + } + + SetFileTime(hFile, null, null, + BitConverter.GetBytes(mtime.ToFileTime())); + + CloseHandle(hFile); + return 0; + } + + + [Interop.DllImport("coredll.dll", EntryPoint="CreateFile", SetLastError=true)] + internal static extern int CreateFileCE(string lpFileName, + uint dwDesiredAccess, + uint dwShareMode, + int lpSecurityAttributes, + uint dwCreationDisposition, + uint dwFlagsAndAttributes, + int hTemplateFile); + + + [Interop.DllImport("coredll", EntryPoint="GetFileAttributes", SetLastError=true)] + internal static extern uint GetAttributes(string lpFileName); + + [Interop.DllImport("coredll", EntryPoint="SetFileAttributes", SetLastError=true)] + internal static extern bool SetAttributes(string lpFileName, uint dwFileAttributes); + + [Interop.DllImport("coredll", EntryPoint="SetFileTime", SetLastError=true)] + internal static extern bool SetFileTime(IntPtr hFile, byte[] lpCreationTime, byte[] lpLastAccessTime, byte[] lpLastWriteTime); + + [Interop.DllImport("coredll.dll", SetLastError=true)] + internal static extern bool CloseHandle(IntPtr hObject); + + } +#endif + + + +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipEntrySource.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipEntrySource.cs new file mode 100644 index 00000000..51aa154a --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipEntrySource.cs @@ -0,0 +1,69 @@ +// ZipEntrySource.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2009-November-19 11:18:42> +// +// ------------------------------------------------------------------ +// + +namespace Ionic.Zip +{ + /// + /// An enum that specifies the source of the ZipEntry. + /// + public enum ZipEntrySource + { + /// + /// Default value. Invalid on a bonafide ZipEntry. + /// + None = 0, + + /// + /// The entry was instantiated by calling AddFile() or another method that + /// added an entry from the filesystem. + /// + FileSystem, + + /// + /// The entry was instantiated via or + /// . + /// + Stream, + + /// + /// The ZipEntry was instantiated by reading a zipfile. + /// + ZipFile, + + /// + /// The content for the ZipEntry will be or was provided by the WriteDelegate. + /// + WriteDelegate, + + /// + /// The content for the ZipEntry will be obtained from the stream dispensed by the OpenDelegate. + /// The entry was instantiated via . + /// + JitStream, + + /// + /// The content for the ZipEntry will be or was obtained from a ZipOutputStream. + /// + ZipOutputStream, + } + +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipErrorAction.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipErrorAction.cs new file mode 100644 index 00000000..c8b862a9 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipErrorAction.cs @@ -0,0 +1,97 @@ +// ZipErrorAction.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2009-September-01 18:43:20> +// +// ------------------------------------------------------------------ +// +// This module defines the ZipErrorAction enum, which provides +// an action to take when errors occur when opening or reading +// files to be added to a zip file. +// +// ------------------------------------------------------------------ + + +namespace Ionic.Zip +{ + /// + /// An enum providing the options when an error occurs during opening or reading + /// of a file or directory that is being saved to a zip file. + /// + /// + /// + /// + /// This enum describes the actions that the library can take when an error occurs + /// opening or reading a file, as it is being saved into a Zip archive. + /// + /// + /// + /// In some cases an error will occur when DotNetZip tries to open a file to be + /// added to the zip archive. In other cases, an error might occur after the + /// file has been successfully opened, while DotNetZip is reading the file. + /// + /// + /// + /// The first problem might occur when calling AddDirectory() on a directory + /// that contains a Clipper .dbf file; the file is locked by Clipper and + /// cannot be opened by another process. An example of the second problem is + /// the ERROR_LOCK_VIOLATION that results when a file is opened by another + /// process, but not locked, and a range lock has been taken on the file. + /// Microsoft Outlook takes range locks on .PST files. + /// + /// + public enum ZipErrorAction + { + /// + /// Throw an exception when an error occurs while zipping. This is the default + /// behavior. (For COM clients, this is a 0 (zero).) + /// + Throw, + + /// + /// When an error occurs during zipping, for example a file cannot be opened, + /// skip the file causing the error, and continue zipping. (For COM clients, + /// this is a 1.) + /// + Skip, + + /// + /// When an error occurs during zipping, for example a file cannot be opened, + /// retry the operation that caused the error. Be careful with this option. If + /// the error is not temporary, the library will retry forever. (For COM + /// clients, this is a 2.) + /// + Retry, + + /// + /// When an error occurs, invoke the zipError event. The event type used is + /// . A typical use of this option: + /// a GUI application may wish to pop up a dialog to allow the user to view the + /// error that occurred, and choose an appropriate action. After your + /// processing in the error event, if you want to skip the file, set on the + /// ZipProgressEventArgs.CurrentEntry to Skip. If you want the + /// exception to be thrown, set ZipErrorAction on the CurrentEntry + /// to Throw. If you want to cancel the zip, set + /// ZipProgressEventArgs.Cancel to true. Cancelling differs from using + /// Skip in that a cancel will not save any further entries, if there are any. + /// (For COM clients, the value of this enum is a 3.) + /// + InvokeErrorEvent, + } + +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.AddUpdate.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.AddUpdate.cs new file mode 100644 index 00000000..2de1680b --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.AddUpdate.cs @@ -0,0 +1,2163 @@ +// ZipFile.AddUpdate.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009-2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-August-01 16:42:07> +// +// ------------------------------------------------------------------ +// +// This module defines the methods for Adding and Updating entries in +// the ZipFile. +// +// ------------------------------------------------------------------ +// + + +using System; +using System.IO; +using System.Collections.Generic; + +namespace Ionic.Zip +{ + public partial class ZipFile + { + /// + /// Adds an item, either a file or a directory, to a zip file archive. + /// + /// + /// + /// + /// This method is handy if you are adding things to zip archive and don't + /// want to bother distinguishing between directories or files. Any files are + /// added as single entries. A directory added through this method is added + /// recursively: all files and subdirectories contained within the directory + /// are added to the ZipFile. + /// + /// + /// + /// The name of the item may be a relative path or a fully-qualified + /// path. Remember, the items contained in ZipFile instance get written + /// to the disk only when you call or a similar + /// save method. + /// + /// + /// + /// The directory name used for the file within the archive is the same + /// as the directory name (potentially a relative path) specified in the + /// . + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to the + /// ZipEntry added. + /// + /// + /// + /// + /// + /// + /// + /// + /// This method has two overloads. + /// + /// the name of the file or directory to add. + /// + /// The ZipEntry added. + public ZipEntry AddItem(string fileOrDirectoryName) + { + return AddItem(fileOrDirectoryName, null); + } + + + /// + /// Adds an item, either a file or a directory, to a zip file archive, + /// explicitly specifying the directory path to be used in the archive. + /// + /// + /// + /// + /// If adding a directory, the add is recursive on all files and + /// subdirectories contained within it. + /// + /// + /// The name of the item may be a relative path or a fully-qualified path. + /// The item added by this call to the ZipFile is not read from the + /// disk nor written to the zip file archive until the application calls + /// Save() on the ZipFile. + /// + /// + /// + /// This version of the method allows the caller to explicitly specify the + /// directory path to be used in the archive, which would override the + /// "natural" path of the filesystem file. + /// + /// + /// + /// Encryption will be used on the file data if the Password has + /// been set on the ZipFile object, prior to calling this method. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to the + /// ZipEntry added. + /// + /// + /// + /// + /// + /// Thrown if the file or directory passed in does not exist. + /// + /// + /// the name of the file or directory to add. + /// + /// + /// + /// The name of the directory path to use within the zip archive. This path + /// need not refer to an extant directory in the current filesystem. If the + /// files within the zip are later extracted, this is the path used for the + /// extracted file. Passing null (Nothing in VB) will use the + /// path on the fileOrDirectoryName. Passing the empty string ("") will + /// insert the item at the root path within the archive. + /// + /// + /// + /// + /// + /// + /// + /// This example shows how to zip up a set of files into a flat hierarchy, + /// regardless of where in the filesystem the files originated. The resulting + /// zip archive will contain a toplevel directory named "flat", which itself + /// will contain files Readme.txt, MyProposal.docx, and Image1.jpg. A + /// subdirectory under "flat" called SupportFiles will contain all the files + /// in the "c:\SupportFiles" directory on disk. + /// + /// + /// String[] itemnames= { + /// "c:\\fixedContent\\Readme.txt", + /// "MyProposal.docx", + /// "c:\\SupportFiles", // a directory + /// "images\\Image1.jpg" + /// }; + /// + /// try + /// { + /// using (ZipFile zip = new ZipFile()) + /// { + /// for (int i = 1; i < itemnames.Length; i++) + /// { + /// // will add Files or Dirs, recurses and flattens subdirectories + /// zip.AddItem(itemnames[i],"flat"); + /// } + /// zip.Save(ZipToCreate); + /// } + /// } + /// catch (System.Exception ex1) + /// { + /// System.Console.Error.WriteLine("exception: {0}", ex1); + /// } + /// + /// + /// + /// Dim itemnames As String() = _ + /// New String() { "c:\fixedContent\Readme.txt", _ + /// "MyProposal.docx", _ + /// "SupportFiles", _ + /// "images\Image1.jpg" } + /// Try + /// Using zip As New ZipFile + /// Dim i As Integer + /// For i = 1 To itemnames.Length - 1 + /// ' will add Files or Dirs, recursing and flattening subdirectories. + /// zip.AddItem(itemnames(i), "flat") + /// Next i + /// zip.Save(ZipToCreate) + /// End Using + /// Catch ex1 As Exception + /// Console.Error.WriteLine("exception: {0}", ex1.ToString()) + /// End Try + /// + /// + /// The ZipEntry added. + public ZipEntry AddItem(String fileOrDirectoryName, String directoryPathInArchive) + { + if (File.Exists(fileOrDirectoryName)) + return AddFile(fileOrDirectoryName, directoryPathInArchive); + + if (Directory.Exists(fileOrDirectoryName)) + return AddDirectory(fileOrDirectoryName, directoryPathInArchive); + + throw new FileNotFoundException(String.Format("That file or directory ({0}) does not exist!", + fileOrDirectoryName)); + } + + /// + /// Adds a File to a Zip file archive. + /// + /// + /// + /// + /// This call collects metadata for the named file in the filesystem, + /// including the file attributes and the timestamp, and inserts that metadata + /// into the resulting ZipEntry. Only when the application calls Save() on + /// the ZipFile, does DotNetZip read the file from the filesystem and + /// then write the content to the zip file archive. + /// + /// + /// + /// This method will throw an exception if an entry with the same name already + /// exists in the ZipFile. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to the + /// ZipEntry added. + /// + /// + /// + /// + /// + /// + /// In this example, three files are added to a Zip archive. The ReadMe.txt + /// file will be placed in the root of the archive. The .png file will be + /// placed in a folder within the zip called photos\personal. The pdf file + /// will be included into a folder within the zip called Desktop. + /// + /// + /// try + /// { + /// using (ZipFile zip = new ZipFile()) + /// { + /// zip.AddFile("c:\\photos\\personal\\7440-N49th.png"); + /// zip.AddFile("c:\\Desktop\\2008-Regional-Sales-Report.pdf"); + /// zip.AddFile("ReadMe.txt"); + /// + /// zip.Save("Package.zip"); + /// } + /// } + /// catch (System.Exception ex1) + /// { + /// System.Console.Error.WriteLine("exception: " + ex1); + /// } + /// + /// + /// + /// Try + /// Using zip As ZipFile = New ZipFile + /// zip.AddFile("c:\photos\personal\7440-N49th.png") + /// zip.AddFile("c:\Desktop\2008-Regional-Sales-Report.pdf") + /// zip.AddFile("ReadMe.txt") + /// zip.Save("Package.zip") + /// End Using + /// Catch ex1 As Exception + /// Console.Error.WriteLine("exception: {0}", ex1.ToString) + /// End Try + /// + /// + /// + /// This method has two overloads. + /// + /// + /// + /// + /// + /// + /// The name of the file to add. It should refer to a file in the filesystem. + /// The name of the file may be a relative path or a fully-qualified path. + /// + /// The ZipEntry corresponding to the File added. + public ZipEntry AddFile(string fileName) + { + return AddFile(fileName, null); + } + + + + + + /// + /// Adds a File to a Zip file archive, potentially overriding the path to be + /// used within the zip archive. + /// + /// + /// + /// + /// The file added by this call to the ZipFile is not written to the + /// zip file archive until the application calls Save() on the ZipFile. + /// + /// + /// + /// This method will throw an exception if an entry with the same name already + /// exists in the ZipFile. + /// + /// + /// + /// This version of the method allows the caller to explicitly specify the + /// directory path to be used in the archive. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to the + /// ZipEntry added. + /// + /// + /// + /// + /// + /// + /// In this example, three files are added to a Zip archive. The ReadMe.txt + /// file will be placed in the root of the archive. The .png file will be + /// placed in a folder within the zip called images. The pdf file will be + /// included into a folder within the zip called files\docs, and will be + /// encrypted with the given password. + /// + /// + /// try + /// { + /// using (ZipFile zip = new ZipFile()) + /// { + /// // the following entry will be inserted at the root in the archive. + /// zip.AddFile("c:\\datafiles\\ReadMe.txt", ""); + /// // this image file will be inserted into the "images" directory in the archive. + /// zip.AddFile("c:\\photos\\personal\\7440-N49th.png", "images"); + /// // the following will result in a password-protected file called + /// // files\\docs\\2008-Regional-Sales-Report.pdf in the archive. + /// zip.Password = "EncryptMe!"; + /// zip.AddFile("c:\\Desktop\\2008-Regional-Sales-Report.pdf", "files\\docs"); + /// zip.Save("Archive.zip"); + /// } + /// } + /// catch (System.Exception ex1) + /// { + /// System.Console.Error.WriteLine("exception: {0}", ex1); + /// } + /// + /// + /// + /// Try + /// Using zip As ZipFile = New ZipFile + /// ' the following entry will be inserted at the root in the archive. + /// zip.AddFile("c:\datafiles\ReadMe.txt", "") + /// ' this image file will be inserted into the "images" directory in the archive. + /// zip.AddFile("c:\photos\personal\7440-N49th.png", "images") + /// ' the following will result in a password-protected file called + /// ' files\\docs\\2008-Regional-Sales-Report.pdf in the archive. + /// zip.Password = "EncryptMe!" + /// zip.AddFile("c:\Desktop\2008-Regional-Sales-Report.pdf", "files\documents") + /// zip.Save("Archive.zip") + /// End Using + /// Catch ex1 As Exception + /// Console.Error.WriteLine("exception: {0}", ex1) + /// End Try + /// + /// + /// + /// + /// + /// + /// + /// + /// The name of the file to add. The name of the file may be a relative path + /// or a fully-qualified path. + /// + /// + /// + /// Specifies a directory path to use to override any path in the fileName. + /// This path may, or may not, correspond to a real directory in the current + /// filesystem. If the files within the zip are later extracted, this is the + /// path used for the extracted file. Passing null (Nothing in + /// VB) will use the path on the fileName, if any. Passing the empty string + /// ("") will insert the item at the root path within the archive. + /// + /// + /// The ZipEntry corresponding to the file added. + public ZipEntry AddFile(string fileName, String directoryPathInArchive) + { + string nameInArchive = ZipEntry.NameInArchive(fileName, directoryPathInArchive); + ZipEntry ze = ZipEntry.CreateFromFile(fileName, nameInArchive); + if (Verbose) StatusMessageTextWriter.WriteLine("adding {0}...", fileName); + return _InternalAddEntry(ze); + } + + + /// + /// This method removes a collection of entries from the ZipFile. + /// + /// + /// + /// A collection of ZipEntry instances from this zip file to be removed. For + /// example, you can pass in an array of ZipEntry instances; or you can call + /// SelectEntries(), and then add or remove entries from that + /// ICollection<ZipEntry> (ICollection(Of ZipEntry) in VB), and pass + /// that ICollection to this method. + /// + /// + /// + /// + public void RemoveEntries(System.Collections.Generic.ICollection entriesToRemove) + { + if (entriesToRemove == null) + throw new ArgumentNullException("entriesToRemove"); + + foreach (ZipEntry e in entriesToRemove) + { + this.RemoveEntry(e); + } + } + + + /// + /// This method removes a collection of entries from the ZipFile, by name. + /// + /// + /// + /// A collection of strings that refer to names of entries to be removed + /// from the ZipFile. For example, you can pass in an array or a + /// List of Strings that provide the names of entries to be removed. + /// + /// + /// + /// + public void RemoveEntries(System.Collections.Generic.ICollection entriesToRemove) + { + if (entriesToRemove == null) + throw new ArgumentNullException("entriesToRemove"); + + foreach (String e in entriesToRemove) + { + this.RemoveEntry(e); + } + } + + + /// + /// This method adds a set of files to the ZipFile. + /// + /// + /// + /// + /// Use this method to add a set of files to the zip archive, in one call. + /// For example, a list of files received from + /// System.IO.Directory.GetFiles() can be added to a zip archive in one + /// call. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to each + /// ZipEntry added. + /// + /// + /// + /// + /// The collection of names of the files to add. Each string should refer to a + /// file in the filesystem. The name of the file may be a relative path or a + /// fully-qualified path. + /// + /// + /// + /// This example shows how to create a zip file, and add a few files into it. + /// + /// String ZipFileToCreate = "archive1.zip"; + /// String DirectoryToZip = "c:\\reports"; + /// using (ZipFile zip = new ZipFile()) + /// { + /// // Store all files found in the top level directory, into the zip archive. + /// String[] filenames = System.IO.Directory.GetFiles(DirectoryToZip); + /// zip.AddFiles(filenames); + /// zip.Save(ZipFileToCreate); + /// } + /// + /// + /// + /// Dim ZipFileToCreate As String = "archive1.zip" + /// Dim DirectoryToZip As String = "c:\reports" + /// Using zip As ZipFile = New ZipFile + /// ' Store all files found in the top level directory, into the zip archive. + /// Dim filenames As String() = System.IO.Directory.GetFiles(DirectoryToZip) + /// zip.AddFiles(filenames) + /// zip.Save(ZipFileToCreate) + /// End Using + /// + /// + /// + /// + public void AddFiles(System.Collections.Generic.IEnumerable fileNames) + { + this.AddFiles(fileNames, null); + } + + + /// + /// Adds or updates a set of files in the ZipFile. + /// + /// + /// + /// + /// Any files that already exist in the archive are updated. Any files that + /// don't yet exist in the archive are added. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to each + /// ZipEntry added. + /// + /// + /// + /// + /// The collection of names of the files to update. Each string should refer to a file in + /// the filesystem. The name of the file may be a relative path or a fully-qualified path. + /// + /// + public void UpdateFiles(System.Collections.Generic.IEnumerable fileNames) + { + this.UpdateFiles(fileNames, null); + } + + + /// + /// Adds a set of files to the ZipFile, using the + /// specified directory path in the archive. + /// + /// + /// + /// + /// Any directory structure that may be present in the + /// filenames contained in the list is "flattened" in the + /// archive. Each file in the list is added to the archive in + /// the specified top-level directory. + /// + /// + /// + /// For ZipFile properties including , , , , , , and , their respective values at the + /// time of this call will be applied to each ZipEntry added. + /// + /// + /// + /// + /// The names of the files to add. Each string should refer to + /// a file in the filesystem. The name of the file may be a + /// relative path or a fully-qualified path. + /// + /// + /// + /// Specifies a directory path to use to override any path in the file name. + /// Th is path may, or may not, correspond to a real directory in the current + /// filesystem. If the files within the zip are later extracted, this is the + /// path used for the extracted file. Passing null (Nothing in + /// VB) will use the path on each of the fileNames, if any. Passing + /// the empty string ("") will insert the item at the root path within the + /// archive. + /// + /// + /// + public void AddFiles(System.Collections.Generic.IEnumerable fileNames, String directoryPathInArchive) + { + AddFiles(fileNames, false, directoryPathInArchive); + } + + + + /// + /// Adds a set of files to the ZipFile, using the specified directory + /// path in the archive, and preserving the full directory structure in the + /// filenames. + /// + /// + /// + /// + /// If preserveDirHierarchy is true, any directory structure present in the + /// filenames contained in the list is preserved in the archive. On the other + /// hand, if preserveDirHierarchy is false, any directory structure that may + /// be present in the filenames contained in the list is "flattened" in the + /// archive; Each file in the list is added to the archive in the specified + /// top-level directory. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to each + /// ZipEntry added. + /// + /// + /// + /// + /// + /// The names of the files to add. Each string should refer to a file in the + /// filesystem. The name of the file may be a relative path or a + /// fully-qualified path. + /// + /// + /// + /// Specifies a directory path to use to override any path in the file name. + /// This path may, or may not, correspond to a real directory in the current + /// filesystem. If the files within the zip are later extracted, this is the + /// path used for the extracted file. Passing null (Nothing in + /// VB) will use the path on each of the fileNames, if any. Passing + /// the empty string ("") will insert the item at the root path within the + /// archive. + /// + /// + /// + /// whether the entries in the zip archive will reflect the directory + /// hierarchy that is present in the various filenames. For example, if + /// includes two paths, \Animalia\Chordata\Mammalia\Info.txt and + /// \Plantae\Magnoliophyta\Dicotyledon\Info.txt, then calling this method with + /// = false will result in an + /// exception because of a duplicate entry name, while calling this method + /// with = true will result in the + /// full direcory paths being included in the entries added to the ZipFile. + /// + /// + public void AddFiles(System.Collections.Generic.IEnumerable fileNames, + bool preserveDirHierarchy, + String directoryPathInArchive) + { + if (fileNames == null) + throw new ArgumentNullException("fileNames"); + + _addOperationCanceled = false; + OnAddStarted(); + if (preserveDirHierarchy) + { + foreach (var f in fileNames) + { + if (_addOperationCanceled) break; + if (directoryPathInArchive != null) + { + //string s = SharedUtilities.NormalizePath(Path.Combine(directoryPathInArchive, Path.GetDirectoryName(f))); + string s = Path.GetFullPath(Path.Combine(directoryPathInArchive, Path.GetDirectoryName(f))); + this.AddFile(f, s); + } + else + this.AddFile(f, null); + } + } + else + { + foreach (var f in fileNames) + { + if (_addOperationCanceled) break; + this.AddFile(f, directoryPathInArchive); + } + } + if (!_addOperationCanceled) + OnAddCompleted(); + } + + + /// + /// Adds or updates a set of files to the ZipFile, using the specified + /// directory path in the archive. + /// + /// + /// + /// + /// + /// Any files that already exist in the archive are updated. Any files that + /// don't yet exist in the archive are added. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to each + /// ZipEntry added. + /// + /// + /// + /// + /// The names of the files to add or update. Each string should refer to a + /// file in the filesystem. The name of the file may be a relative path or a + /// fully-qualified path. + /// + /// + /// + /// Specifies a directory path to use to override any path in the file name. + /// This path may, or may not, correspond to a real directory in the current + /// filesystem. If the files within the zip are later extracted, this is the + /// path used for the extracted file. Passing null (Nothing in + /// VB) will use the path on each of the fileNames, if any. Passing + /// the empty string ("") will insert the item at the root path within the + /// archive. + /// + /// + /// + public void UpdateFiles(System.Collections.Generic.IEnumerable fileNames, String directoryPathInArchive) + { + if (fileNames == null) + throw new ArgumentNullException("fileNames"); + + OnAddStarted(); + foreach (var f in fileNames) + this.UpdateFile(f, directoryPathInArchive); + OnAddCompleted(); + } + + + + + /// + /// Adds or Updates a File in a Zip file archive. + /// + /// + /// + /// + /// This method adds a file to a zip archive, or, if the file already exists + /// in the zip archive, this method Updates the content of that given filename + /// in the zip archive. The UpdateFile method might more accurately be + /// called "AddOrUpdateFile". + /// + /// + /// + /// Upon success, there is no way for the application to learn whether the file + /// was added versus updated. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to the + /// ZipEntry added. + /// + /// + /// + /// + /// + /// This example shows how to Update an existing entry in a zipfile. The first + /// call to UpdateFile adds the file to the newly-created zip archive. The + /// second call to UpdateFile updates the content for that file in the zip + /// archive. + /// + /// + /// using (ZipFile zip1 = new ZipFile()) + /// { + /// // UpdateFile might more accurately be called "AddOrUpdateFile" + /// zip1.UpdateFile("MyDocuments\\Readme.txt"); + /// zip1.UpdateFile("CustomerList.csv"); + /// zip1.Comment = "This zip archive has been created."; + /// zip1.Save("Content.zip"); + /// } + /// + /// using (ZipFile zip2 = ZipFile.Read("Content.zip")) + /// { + /// zip2.UpdateFile("Updates\\Readme.txt"); + /// zip2.Comment = "This zip archive has been updated: The Readme.txt file has been changed."; + /// zip2.Save(); + /// } + /// + /// + /// + /// Using zip1 As New ZipFile + /// ' UpdateFile might more accurately be called "AddOrUpdateFile" + /// zip1.UpdateFile("MyDocuments\Readme.txt") + /// zip1.UpdateFile("CustomerList.csv") + /// zip1.Comment = "This zip archive has been created." + /// zip1.Save("Content.zip") + /// End Using + /// + /// Using zip2 As ZipFile = ZipFile.Read("Content.zip") + /// zip2.UpdateFile("Updates\Readme.txt") + /// zip2.Comment = "This zip archive has been updated: The Readme.txt file has been changed." + /// zip2.Save + /// End Using + /// + /// + /// + /// + /// + /// + /// + /// + /// The name of the file to add or update. It should refer to a file in the + /// filesystem. The name of the file may be a relative path or a + /// fully-qualified path. + /// + /// + /// + /// The ZipEntry corresponding to the File that was added or updated. + /// + public ZipEntry UpdateFile(string fileName) + { + return UpdateFile(fileName, null); + } + + + + /// + /// Adds or Updates a File in a Zip file archive. + /// + /// + /// + /// + /// This method adds a file to a zip archive, or, if the file already exists + /// in the zip archive, this method Updates the content of that given filename + /// in the zip archive. + /// + /// + /// + /// This version of the method allows the caller to explicitly specify the + /// directory path to be used in the archive. The entry to be added or + /// updated is found by using the specified directory path, combined with the + /// basename of the specified filename. + /// + /// + /// + /// Upon success, there is no way for the application to learn if the file was + /// added versus updated. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to the + /// ZipEntry added. + /// + /// + /// + /// + /// + /// + /// + /// + /// The name of the file to add or update. It should refer to a file in the + /// filesystem. The name of the file may be a relative path or a + /// fully-qualified path. + /// + /// + /// + /// Specifies a directory path to use to override any path in the + /// fileName. This path may, or may not, correspond to a real + /// directory in the current filesystem. If the files within the zip are + /// later extracted, this is the path used for the extracted file. Passing + /// null (Nothing in VB) will use the path on the + /// fileName, if any. Passing the empty string ("") will insert the + /// item at the root path within the archive. + /// + /// + /// + /// The ZipEntry corresponding to the File that was added or updated. + /// + public ZipEntry UpdateFile(string fileName, String directoryPathInArchive) + { + // ideally this would all be transactional! + var key = ZipEntry.NameInArchive(fileName, directoryPathInArchive); + if (this[key] != null) + this.RemoveEntry(key); + return this.AddFile(fileName, directoryPathInArchive); + } + + + + + + /// + /// Add or update a directory in a zip archive. + /// + /// + /// + /// If the specified directory does not exist in the archive, then this method + /// is equivalent to calling AddDirectory(). If the specified + /// directory already exists in the archive, then this method updates any + /// existing entries, and adds any new entries. Any entries that are in the + /// zip archive but not in the specified directory, are left alone. In other + /// words, the contents of the zip file will be a union of the previous + /// contents and the new files. + /// + /// + /// + /// + /// + /// + /// + /// The path to the directory to be added to the zip archive, or updated in + /// the zip archive. + /// + /// + /// + /// The ZipEntry corresponding to the Directory that was added or updated. + /// + public ZipEntry UpdateDirectory(string directoryName) + { + return UpdateDirectory(directoryName, null); + } + + + /// + /// Add or update a directory in the zip archive at the specified root + /// directory in the archive. + /// + /// + /// + /// If the specified directory does not exist in the archive, then this method + /// is equivalent to calling AddDirectory(). If the specified + /// directory already exists in the archive, then this method updates any + /// existing entries, and adds any new entries. Any entries that are in the + /// zip archive but not in the specified directory, are left alone. In other + /// words, the contents of the zip file will be a union of the previous + /// contents and the new files. + /// + /// + /// + /// + /// + /// + /// + /// The path to the directory to be added to the zip archive, or updated + /// in the zip archive. + /// + /// + /// + /// Specifies a directory path to use to override any path in the + /// directoryName. This path may, or may not, correspond to a real + /// directory in the current filesystem. If the files within the zip are + /// later extracted, this is the path used for the extracted file. Passing + /// null (Nothing in VB) will use the path on the + /// directoryName, if any. Passing the empty string ("") will insert + /// the item at the root path within the archive. + /// + /// + /// + /// The ZipEntry corresponding to the Directory that was added or updated. + /// + public ZipEntry UpdateDirectory(string directoryName, String directoryPathInArchive) + { + return this.AddOrUpdateDirectoryImpl(directoryName, directoryPathInArchive, AddOrUpdateAction.AddOrUpdate); + } + + + + + + /// + /// Add or update a file or directory in the zip archive. + /// + /// + /// + /// + /// This is useful when the application is not sure or does not care if the + /// item to be added is a file or directory, and does not know or does not + /// care if the item already exists in the ZipFile. Calling this method + /// is equivalent to calling RemoveEntry() if an entry by the same name + /// already exists, followed calling by AddItem(). + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to the + /// ZipEntry added. + /// + /// + /// + /// + /// + /// + /// + /// + /// the path to the file or directory to be added or updated. + /// + public void UpdateItem(string itemName) + { + UpdateItem(itemName, null); + } + + + /// + /// Add or update a file or directory. + /// + /// + /// + /// + /// This method is useful when the application is not sure or does not care if + /// the item to be added is a file or directory, and does not know or does not + /// care if the item already exists in the ZipFile. Calling this method + /// is equivalent to calling RemoveEntry(), if an entry by that name + /// exists, and then calling AddItem(). + /// + /// + /// + /// This version of the method allows the caller to explicitly specify the + /// directory path to be used for the item being added to the archive. The + /// entry or entries that are added or updated will use the specified + /// DirectoryPathInArchive. Extracting the entry from the archive will + /// result in a file stored in that directory path. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to the + /// ZipEntry added. + /// + /// + /// + /// + /// + /// + /// + /// + /// The path for the File or Directory to be added or updated. + /// + /// + /// Specifies a directory path to use to override any path in the + /// itemName. This path may, or may not, correspond to a real + /// directory in the current filesystem. If the files within the zip are + /// later extracted, this is the path used for the extracted file. Passing + /// null (Nothing in VB) will use the path on the + /// itemName, if any. Passing the empty string ("") will insert the + /// item at the root path within the archive. + /// + public void UpdateItem(string itemName, string directoryPathInArchive) + { + if (File.Exists(itemName)) + UpdateFile(itemName, directoryPathInArchive); + + else if (Directory.Exists(itemName)) + UpdateDirectory(itemName, directoryPathInArchive); + + else + throw new FileNotFoundException(String.Format("That file or directory ({0}) does not exist!", itemName)); + } + + + + + /// + /// Adds a named entry into the zip archive, taking content for the entry + /// from a string. + /// + /// + /// + /// Calling this method creates an entry using the given fileName and + /// directory path within the archive. There is no need for a file by the + /// given name to exist in the filesystem; the name is used within the zip + /// archive only. The content for the entry is encoded using the default text + /// encoding for the machine, or on Silverlight, using UTF-8. + /// + /// + /// + /// The content of the file, should it be extracted from the zip. + /// + /// + /// + /// The name, including any path, to use for the entry within the archive. + /// + /// + /// The ZipEntry added. + /// + /// + /// + /// This example shows how to add an entry to the zipfile, using a string as + /// content for that entry. + /// + /// + /// string Content = "This string will be the content of the Readme.txt file in the zip archive."; + /// using (ZipFile zip1 = new ZipFile()) + /// { + /// zip1.AddFile("MyDocuments\\Resume.doc", "files"); + /// zip1.AddEntry("Readme.txt", Content); + /// zip1.Comment = "This zip file was created at " + System.DateTime.Now.ToString("G"); + /// zip1.Save("Content.zip"); + /// } + /// + /// + /// + /// Public Sub Run() + /// Dim Content As String = "This string will be the content of the Readme.txt file in the zip archive." + /// Using zip1 As ZipFile = New ZipFile + /// zip1.AddEntry("Readme.txt", Content) + /// zip1.AddFile("MyDocuments\Resume.doc", "files") + /// zip1.Comment = ("This zip file was created at " & DateTime.Now.ToString("G")) + /// zip1.Save("Content.zip") + /// End Using + /// End Sub + /// + /// + public ZipEntry AddEntry(string entryName, string content) + { +#if SILVERLIGHT + return AddEntry(entryName, content, System.Text.Encoding.UTF8); +#else + return AddEntry(entryName, content, System.Text.Encoding.Default); +#endif + } + + + + /// + /// Adds a named entry into the zip archive, taking content for the entry + /// from a string, and using the specified text encoding. + /// + /// + /// + /// + /// + /// Calling this method creates an entry using the given fileName and + /// directory path within the archive. There is no need for a file by the + /// given name to exist in the filesystem; the name is used within the zip + /// archive only. + /// + /// + /// + /// The content for the entry, a string value, is encoded using the given + /// text encoding. A BOM (byte-order-mark) is emitted into the file, if the + /// Encoding parameter is set for that. + /// + /// + /// + /// Most Encoding classes support a constructor that accepts a boolean, + /// indicating whether to emit a BOM or not. For example see . + /// + /// + /// + /// + /// + /// The name, including any path, to use within the archive for the entry. + /// + /// + /// + /// The content of the file, should it be extracted from the zip. + /// + /// + /// + /// The text encoding to use when encoding the string. Be aware: This is + /// distinct from the text encoding used to encode the fileName, as specified + /// in . + /// + /// + /// The ZipEntry added. + /// + public ZipEntry AddEntry(string entryName, string content, System.Text.Encoding encoding) + { + // cannot employ a using clause here. We need the stream to + // persist after exit from this method. + var ms = new MemoryStream(); + + // cannot use a using clause here; StreamWriter takes + // ownership of the stream and Disposes it before we are ready. + var sw = new StreamWriter(ms, encoding); + sw.Write(content); + sw.Flush(); + + // reset to allow reading later + ms.Seek(0, SeekOrigin.Begin); + + return AddEntry(entryName, ms); + + // must not dispose the MemoryStream - it will be used later. + } + + + /// + /// Create an entry in the ZipFile using the given Stream + /// as input. The entry will have the given filename. + /// + /// + /// + /// + /// + /// The application should provide an open, readable stream; in this case it + /// will be read during the call to or one of + /// its overloads. + /// + /// + /// + /// The passed stream will be read from its current position. If + /// necessary, callers should set the position in the stream before + /// calling AddEntry(). This might be appropriate when using this method + /// with a MemoryStream, for example. + /// + /// + /// + /// In cases where a large number of streams will be added to the + /// ZipFile, the application may wish to avoid maintaining all of the + /// streams open simultaneously. To handle this situation, the application + /// should use the + /// overload. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to the + /// ZipEntry added. + /// + /// + /// + /// + /// + /// + /// This example adds a single entry to a ZipFile via a Stream. + /// + /// + /// + /// String zipToCreate = "Content.zip"; + /// String fileNameInArchive = "Content-From-Stream.bin"; + /// using (System.IO.Stream streamToRead = MyStreamOpener()) + /// { + /// using (ZipFile zip = new ZipFile()) + /// { + /// ZipEntry entry= zip.AddEntry(fileNameInArchive, streamToRead); + /// zip.AddFile("Readme.txt"); + /// zip.Save(zipToCreate); // the stream is read implicitly here + /// } + /// } + /// + /// + /// + /// Dim zipToCreate As String = "Content.zip" + /// Dim fileNameInArchive As String = "Content-From-Stream.bin" + /// Using streamToRead as System.IO.Stream = MyStreamOpener() + /// Using zip As ZipFile = New ZipFile() + /// Dim entry as ZipEntry = zip.AddEntry(fileNameInArchive, streamToRead) + /// zip.AddFile("Readme.txt") + /// zip.Save(zipToCreate) '' the stream is read implicitly, here + /// End Using + /// End Using + /// + /// + /// + /// + /// + /// + /// The name, including any path, which is shown in the zip file for the added + /// entry. + /// + /// + /// The input stream from which to grab content for the file + /// + /// The ZipEntry added. + public ZipEntry AddEntry(string entryName, Stream stream) + { + ZipEntry ze = ZipEntry.CreateForStream(entryName, stream); + ze.SetEntryTimes(DateTime.Now,DateTime.Now,DateTime.Now); + if (Verbose) StatusMessageTextWriter.WriteLine("adding {0}...", entryName); + return _InternalAddEntry(ze); + } + + + + /// + /// Add a ZipEntry for which content is written directly by the application. + /// + /// + /// + /// + /// When the application needs to write the zip entry data, use this + /// method to add the ZipEntry. For example, in the case that the + /// application wishes to write the XML representation of a DataSet into + /// a ZipEntry, the application can use this method to do so. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to the + /// ZipEntry added. + /// + /// + /// + /// About progress events: When using the WriteDelegate, DotNetZip does + /// not issue any SaveProgress events with EventType = + /// Saving_EntryBytesRead. (This is because it is the + /// application's code that runs in WriteDelegate - there's no way for + /// DotNetZip to know when to issue a EntryBytesRead event.) + /// Applications that want to update a progress bar or similar status + /// indicator should do so from within the WriteDelegate + /// itself. DotNetZip will issue the other SaveProgress events, + /// including + /// Saving_Started, + /// + /// Saving_BeforeWriteEntry, and + /// Saving_AfterWriteEntry. + /// + /// + /// + /// Note: When you use PKZip encryption, it's normally necessary to + /// compute the CRC of the content to be encrypted, before compressing or + /// encrypting it. Therefore, when using PKZip encryption with a + /// WriteDelegate, the WriteDelegate CAN BE called twice: once to compute + /// the CRC, and the second time to potentially compress and + /// encrypt. Surprising, but true. This is because PKWARE specified that + /// the encryption initialization data depends on the CRC. + /// If this happens, for each call of the delegate, your + /// application must stream the same entry data in its entirety. If your + /// application writes different data during the second call, it will + /// result in a corrupt zip file. + /// + /// + /// + /// The double-read behavior happens with all types of entries, not only + /// those that use WriteDelegate. It happens if you add an entry from a + /// filesystem file, or using a string, or a stream, or an opener/closer + /// pair. But in those cases, DotNetZip takes care of reading twice; in + /// the case of the WriteDelegate, the application code gets invoked + /// twice. Be aware. + /// + /// + /// + /// As you can imagine, this can cause performance problems for large + /// streams, and it can lead to correctness problems when you use a + /// WriteDelegate. This is a pretty big pitfall. There are two + /// ways to avoid it. First, and most preferred: don't use PKZIP + /// encryption. If you use the WinZip AES encryption, this problem + /// doesn't occur, because the encryption protocol doesn't require the CRC + /// up front. Second: if you do choose to use PKZIP encryption, write out + /// to a non-seekable stream (like standard output, or the + /// Response.OutputStream in an ASP.NET application). In this case, + /// DotNetZip will use an alternative encryption protocol that does not + /// rely on the CRC of the content. This also implies setting bit 3 in + /// the zip entry, which still presents problems for some zip tools. + /// + /// + /// + /// In the future I may modify DotNetZip to *always* use bit 3 when PKZIP + /// encryption is in use. This seems like a win overall, but there will + /// be some work involved. If you feel strongly about it, visit the + /// DotNetZip forums and vote up the Workitem + /// tracking this issue. + /// + /// + /// + /// + /// the name of the entry to add + /// the delegate which will write the entry content + /// the ZipEntry added + /// + /// + /// + /// This example shows an application filling a DataSet, then saving the + /// contents of that DataSet as XML, into a ZipEntry in a ZipFile, using an + /// anonymous delegate in C#. The DataSet XML is never saved to a disk file. + /// + /// + /// var c1= new System.Data.SqlClient.SqlConnection(connstring1); + /// var da = new System.Data.SqlClient.SqlDataAdapter() + /// { + /// SelectCommand= new System.Data.SqlClient.SqlCommand(strSelect, c1) + /// }; + /// + /// DataSet ds1 = new DataSet(); + /// da.Fill(ds1, "Invoices"); + /// + /// using(Ionic.Zip.ZipFile zip = new Ionic.Zip.ZipFile()) + /// { + /// zip.AddEntry(zipEntryName, (name,stream) => ds1.WriteXml(stream) ); + /// zip.Save(zipFileName); + /// } + /// + /// + /// + /// + /// + /// This example uses an anonymous method in C# as the WriteDelegate to provide + /// the data for the ZipEntry. The example is a bit contrived - the + /// AddFile() method is a simpler way to insert the contents of a file + /// into an entry in a zip file. On the other hand, if there is some sort of + /// processing or transformation of the file contents required before writing, + /// the application could use the WriteDelegate to do it, in this way. + /// + /// + /// using (var input = File.Open(filename, FileMode.Open, FileAccess.Read, FileShare.ReadWrite )) + /// { + /// using(Ionic.Zip.ZipFile zip = new Ionic.Zip.ZipFile()) + /// { + /// zip.AddEntry(zipEntryName, (name,output) => + /// { + /// byte[] buffer = new byte[BufferSize]; + /// int n; + /// while ((n = input.Read(buffer, 0, buffer.Length)) != 0) + /// { + /// // could transform the data here... + /// output.Write(buffer, 0, n); + /// // could update a progress bar here + /// } + /// }); + /// + /// zip.Save(zipFileName); + /// } + /// } + /// + /// + /// + /// + /// + /// This example uses a named delegate in VB to write data for the given + /// ZipEntry (VB9 does not have anonymous delegates). The example here is a bit + /// contrived - a simpler way to add the contents of a file to a ZipEntry is to + /// simply use the appropriate AddFile() method. The key scenario for + /// which the WriteDelegate makes sense is saving a DataSet, in XML + /// format, to the zip file. The DataSet can write XML to a stream, and the + /// WriteDelegate is the perfect place to write into the zip file. There may be + /// other data structures that can write to a stream, but cannot be read as a + /// stream. The WriteDelegate would be appropriate for those cases as + /// well. + /// + /// + /// Private Sub WriteEntry (ByVal name As String, ByVal output As Stream) + /// Using input As FileStream = File.Open(filename, FileMode.Open, FileAccess.Read, FileShare.ReadWrite) + /// Dim n As Integer = -1 + /// Dim buffer As Byte() = New Byte(BufferSize){} + /// Do While n <> 0 + /// n = input.Read(buffer, 0, buffer.Length) + /// output.Write(buffer, 0, n) + /// Loop + /// End Using + /// End Sub + /// + /// Public Sub Run() + /// Using zip = New ZipFile + /// zip.AddEntry(zipEntryName, New WriteDelegate(AddressOf WriteEntry)) + /// zip.Save(zipFileName) + /// End Using + /// End Sub + /// + /// + public ZipEntry AddEntry(string entryName, WriteDelegate writer) + { + ZipEntry ze = ZipEntry.CreateForWriter(entryName, writer); + if (Verbose) StatusMessageTextWriter.WriteLine("adding {0}...", entryName); + return _InternalAddEntry(ze); + } + + + /// + /// Add an entry, for which the application will provide a stream, + /// just-in-time. + /// + /// + /// + /// + /// In cases where the application wishes to open the stream that holds + /// the content for the ZipEntry, on a just-in-time basis, the application + /// can use this method and provide delegates to open and close the + /// stream. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to the + /// ZipEntry added. + /// + /// + /// + /// + /// + /// + /// This example uses anonymous methods in C# to open and close the + /// source stream for the content for a zip entry. In a real + /// application, the logic for the OpenDelegate would probably be more + /// involved. + /// + /// + /// using(Ionic.Zip.ZipFile zip = new Ionic.Zip.ZipFile()) + /// { + /// zip.AddEntry(zipEntryName, + /// (name) => File.Open(filename, FileMode.Open, FileAccess.Read, FileShare.ReadWrite ), + /// (name, stream) => stream.Close() + /// ); + /// + /// zip.Save(zipFileName); + /// } + /// + /// + /// + /// + /// + /// + /// This example uses delegates in VB.NET to open and close the + /// the source stream for the content for a zip entry. VB 9.0 lacks + /// support for "Sub" lambda expressions, and so the CloseDelegate must + /// be an actual, named Sub. + /// + /// + /// + /// Function MyStreamOpener(ByVal entryName As String) As Stream + /// '' This simply opens a file. You probably want to do somethinig + /// '' more involved here: open a stream to read from a database, + /// '' open a stream on an HTTP connection, and so on. + /// Return File.OpenRead(entryName) + /// End Function + /// + /// Sub MyStreamCloser(entryName As String, stream As Stream) + /// stream.Close() + /// End Sub + /// + /// Public Sub Run() + /// Dim dirToZip As String = "fodder" + /// Dim zipFileToCreate As String = "Archive.zip" + /// Dim opener As OpenDelegate = AddressOf MyStreamOpener + /// Dim closer As CloseDelegate = AddressOf MyStreamCloser + /// Dim numFilestoAdd As Int32 = 4 + /// Using zip As ZipFile = New ZipFile + /// Dim i As Integer + /// For i = 0 To numFilesToAdd - 1 + /// zip.AddEntry(String.Format("content-{0:000}.txt"), opener, closer) + /// Next i + /// zip.Save(zipFileToCreate) + /// End Using + /// End Sub + /// + /// + /// + /// + /// the name of the entry to add + /// + /// the delegate that will be invoked to open the stream + /// + /// + /// the delegate that will be invoked to close the stream + /// + /// the ZipEntry added + /// + public ZipEntry AddEntry(string entryName, OpenDelegate opener, CloseDelegate closer) + { + ZipEntry ze = ZipEntry.CreateForJitStreamProvider(entryName, opener, closer); + ze.SetEntryTimes(DateTime.Now,DateTime.Now,DateTime.Now); + if (Verbose) StatusMessageTextWriter.WriteLine("adding {0}...", entryName); + return _InternalAddEntry(ze); + } + + + + private ZipEntry _InternalAddEntry(ZipEntry ze) + { + // stamp all the props onto the entry + ze._container = new ZipContainer(this); + ze.CompressionMethod = this.CompressionMethod; + ze.CompressionLevel = this.CompressionLevel; + ze.ExtractExistingFile = this.ExtractExistingFile; + ze.ZipErrorAction = this.ZipErrorAction; + ze.SetCompression = this.SetCompression; + ze.AlternateEncoding = this.AlternateEncoding; + ze.AlternateEncodingUsage = this.AlternateEncodingUsage; + ze.Password = this._Password; + ze.Encryption = this.Encryption; + ze.EmitTimesInWindowsFormatWhenSaving = this._emitNtfsTimes; + ze.EmitTimesInUnixFormatWhenSaving = this._emitUnixTimes; + //string key = DictionaryKeyForEntry(ze); + InternalAddEntry(ze.FileName,ze); + AfterAddEntry(ze); + return ze; + } + + + + + /// + /// Updates the given entry in the ZipFile, using the given + /// string as content for the ZipEntry. + /// + /// + /// + /// + /// + /// Calling this method is equivalent to removing the ZipEntry for + /// the given file name and directory path, if it exists, and then calling + /// . See the documentation for + /// that method for further explanation. The string content is encoded + /// using the default encoding for the machine, or on Silverlight, using + /// UTF-8. This encoding is distinct from the encoding used for the + /// filename itself. See . + /// + /// + /// + /// + /// + /// The name, including any path, to use within the archive for the entry. + /// + /// + /// + /// The content of the file, should it be extracted from the zip. + /// + /// + /// The ZipEntry added. + /// + public ZipEntry UpdateEntry(string entryName, string content) + { +#if SILVERLIGHT + return UpdateEntry(entryName, content, System.Text.Encoding.UTF8); +#else + return UpdateEntry(entryName, content, System.Text.Encoding.Default); +#endif + } + + + /// + /// Updates the given entry in the ZipFile, using the given string as + /// content for the ZipEntry. + /// + /// + /// + /// Calling this method is equivalent to removing the ZipEntry for the + /// given file name and directory path, if it exists, and then calling . See the + /// documentation for that method for further explanation. + /// + /// + /// + /// The name, including any path, to use within the archive for the entry. + /// + /// + /// + /// The content of the file, should it be extracted from the zip. + /// + /// + /// + /// The text encoding to use when encoding the string. Be aware: This is + /// distinct from the text encoding used to encode the filename. See . + /// + /// + /// The ZipEntry added. + /// + public ZipEntry UpdateEntry(string entryName, string content, System.Text.Encoding encoding) + { + RemoveEntryForUpdate(entryName); + return AddEntry(entryName, content, encoding); + } + + + + /// + /// Updates the given entry in the ZipFile, using the given delegate + /// as the source for content for the ZipEntry. + /// + /// + /// + /// Calling this method is equivalent to removing the ZipEntry for the + /// given file name and directory path, if it exists, and then calling . See the + /// documentation for that method for further explanation. + /// + /// + /// + /// The name, including any path, to use within the archive for the entry. + /// + /// + /// the delegate which will write the entry content. + /// + /// The ZipEntry added. + /// + public ZipEntry UpdateEntry(string entryName, WriteDelegate writer) + { + RemoveEntryForUpdate(entryName); + return AddEntry(entryName, writer); + } + + + + /// + /// Updates the given entry in the ZipFile, using the given delegates + /// to open and close the stream that provides the content for the ZipEntry. + /// + /// + /// + /// Calling this method is equivalent to removing the ZipEntry for the + /// given file name and directory path, if it exists, and then calling . See the + /// documentation for that method for further explanation. + /// + /// + /// + /// The name, including any path, to use within the archive for the entry. + /// + /// + /// + /// the delegate that will be invoked to open the stream + /// + /// + /// the delegate that will be invoked to close the stream + /// + /// + /// The ZipEntry added or updated. + /// + public ZipEntry UpdateEntry(string entryName, OpenDelegate opener, CloseDelegate closer) + { + RemoveEntryForUpdate(entryName); + return AddEntry(entryName, opener, closer); + } + + + /// + /// Updates the given entry in the ZipFile, using the given stream as + /// input, and the given filename and given directory Path. + /// + /// + /// + /// + /// Calling the method is equivalent to calling RemoveEntry() if an + /// entry by the same name already exists, and then calling AddEntry() + /// with the given fileName and stream. + /// + /// + /// + /// The stream must be open and readable during the call to + /// ZipFile.Save. You can dispense the stream on a just-in-time basis + /// using the property. Check the + /// documentation of that property for more information. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to the + /// ZipEntry added. + /// + /// + /// + /// + /// + /// + /// + /// + /// The name, including any path, to use within the archive for the entry. + /// + /// + /// The input stream from which to read file data. + /// The ZipEntry added. + public ZipEntry UpdateEntry(string entryName, Stream stream) + { + RemoveEntryForUpdate(entryName); + return AddEntry(entryName, stream); + } + + + private void RemoveEntryForUpdate(string entryName) + { + if (String.IsNullOrEmpty(entryName)) + throw new ArgumentNullException("entryName"); + + string directoryPathInArchive = null; + if (entryName.IndexOf('\\') != -1) + { + directoryPathInArchive = Path.GetDirectoryName(entryName); + entryName = Path.GetFileName(entryName); + } + var key = ZipEntry.NameInArchive(entryName, directoryPathInArchive); + if (this[key] != null) + this.RemoveEntry(key); + } + + + + + /// + /// Add an entry into the zip archive using the given filename and + /// directory path within the archive, and the given content for the + /// file. No file is created in the filesystem. + /// + /// + /// The data to use for the entry. + /// + /// + /// The name, including any path, to use within the archive for the entry. + /// + /// + /// The ZipEntry added. + public ZipEntry AddEntry(string entryName, byte[] byteContent) + { + if (byteContent == null) throw new ArgumentException("bad argument", "byteContent"); + var ms = new MemoryStream(byteContent); + return AddEntry(entryName, ms); + } + + + /// + /// Updates the given entry in the ZipFile, using the given byte + /// array as content for the entry. + /// + /// + /// + /// Calling this method is equivalent to removing the ZipEntry + /// for the given filename and directory path, if it exists, and then + /// calling . See the + /// documentation for that method for further explanation. + /// + /// + /// + /// The name, including any path, to use within the archive for the entry. + /// + /// + /// The content to use for the ZipEntry. + /// + /// The ZipEntry added. + /// + public ZipEntry UpdateEntry(string entryName, byte[] byteContent) + { + RemoveEntryForUpdate(entryName); + return AddEntry(entryName, byteContent); + } + + +// private string DictionaryKeyForEntry(ZipEntry ze1) +// { +// var filename = SharedUtilities.NormalizePathForUseInZipFile(ze1.FileName); +// return filename; +// } + + + /// + /// Adds the contents of a filesystem directory to a Zip file archive. + /// + /// + /// + /// + /// + /// The name of the directory may be a relative path or a fully-qualified + /// path. Any files within the named directory are added to the archive. Any + /// subdirectories within the named directory are also added to the archive, + /// recursively. + /// + /// + /// + /// Top-level entries in the named directory will appear as top-level entries + /// in the zip archive. Entries in subdirectories in the named directory will + /// result in entries in subdirectories in the zip archive. + /// + /// + /// + /// If you want the entries to appear in a containing directory in the zip + /// archive itself, then you should call the AddDirectory() overload that + /// allows you to explicitly specify a directory path for use in the archive. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to each + /// ZipEntry added. + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// This method has 2 overloads. + /// + /// The name of the directory to add. + /// The ZipEntry added. + public ZipEntry AddDirectory(string directoryName) + { + return AddDirectory(directoryName, null); + } + + + /// + /// Adds the contents of a filesystem directory to a Zip file archive, + /// overriding the path to be used for entries in the archive. + /// + /// + /// + /// + /// The name of the directory may be a relative path or a fully-qualified + /// path. The add operation is recursive, so that any files or subdirectories + /// within the name directory are also added to the archive. + /// + /// + /// + /// Top-level entries in the named directory will appear as top-level entries + /// in the zip archive. Entries in subdirectories in the named directory will + /// result in entries in subdirectories in the zip archive. + /// + /// + /// + /// For ZipFile properties including , , , , , + /// , and , their + /// respective values at the time of this call will be applied to each + /// ZipEntry added. + /// + /// + /// + /// + /// + /// + /// In this code, calling the ZipUp() method with a value of "c:\reports" for + /// the directory parameter will result in a zip file structure in which all + /// entries are contained in a toplevel "reports" directory. + /// + /// + /// + /// public void ZipUp(string targetZip, string directory) + /// { + /// using (var zip = new ZipFile()) + /// { + /// zip.AddDirectory(directory, System.IO.Path.GetFileName(directory)); + /// zip.Save(targetZip); + /// } + /// } + /// + /// + /// + /// + /// + /// + /// + /// The name of the directory to add. + /// + /// + /// Specifies a directory path to use to override any path in the + /// DirectoryName. This path may, or may not, correspond to a real directory + /// in the current filesystem. If the zip is later extracted, this is the + /// path used for the extracted file or directory. Passing null + /// (Nothing in VB) or the empty string ("") will insert the items at + /// the root path within the archive. + /// + /// + /// The ZipEntry added. + public ZipEntry AddDirectory(string directoryName, string directoryPathInArchive) + { + return AddOrUpdateDirectoryImpl(directoryName, directoryPathInArchive, AddOrUpdateAction.AddOnly); + } + + + /// + /// Creates a directory in the zip archive. + /// + /// + /// + /// + /// + /// Use this when you want to create a directory in the archive but there is + /// no corresponding filesystem representation for that directory. + /// + /// + /// + /// You will probably not need to do this in your code. One of the only times + /// you will want to do this is if you want an empty directory in the zip + /// archive. The reason: if you add a file to a zip archive that is stored + /// within a multi-level directory, all of the directory tree is implicitly + /// created in the zip archive. + /// + /// + /// + /// + /// + /// The name of the directory to create in the archive. + /// + /// The ZipEntry added. + public ZipEntry AddDirectoryByName(string directoryNameInArchive) + { + // workitem 9073 + ZipEntry dir = ZipEntry.CreateFromNothing(directoryNameInArchive); + dir._container = new ZipContainer(this); + dir.MarkAsDirectory(); + dir.AlternateEncoding = this.AlternateEncoding; // workitem 8984 + dir.AlternateEncodingUsage = this.AlternateEncodingUsage; + dir.SetEntryTimes(DateTime.Now,DateTime.Now,DateTime.Now); + dir.EmitTimesInWindowsFormatWhenSaving = _emitNtfsTimes; + dir.EmitTimesInUnixFormatWhenSaving = _emitUnixTimes; + dir._Source = ZipEntrySource.Stream; + //string key = DictionaryKeyForEntry(dir); + InternalAddEntry(dir.FileName,dir); + AfterAddEntry(dir); + return dir; + } + + + + private ZipEntry AddOrUpdateDirectoryImpl(string directoryName, + string rootDirectoryPathInArchive, + AddOrUpdateAction action) + { + if (rootDirectoryPathInArchive == null) + { + rootDirectoryPathInArchive = ""; + } + + return AddOrUpdateDirectoryImpl(directoryName, rootDirectoryPathInArchive, action, true, 0); + } + + + internal void InternalAddEntry(String name, ZipEntry entry) + { + _entries.Add(name, entry); + _zipEntriesAsList = null; + _contentsChanged = true; + } + + + + private ZipEntry AddOrUpdateDirectoryImpl(string directoryName, + string rootDirectoryPathInArchive, + AddOrUpdateAction action, + bool recurse, + int level) + { + if (Verbose) + StatusMessageTextWriter.WriteLine("{0} {1}...", + (action == AddOrUpdateAction.AddOnly) ? "adding" : "Adding or updating", + directoryName); + + if (level == 0) + { + _addOperationCanceled = false; + OnAddStarted(); + } + + // workitem 13371 + if (_addOperationCanceled) + return null; + + string dirForEntries = rootDirectoryPathInArchive; + ZipEntry baseDir = null; + + if (level > 0) + { + int f = directoryName.Length; + for (int i = level; i > 0; i--) + f = directoryName.LastIndexOfAny("/\\".ToCharArray(), f - 1, f - 1); + + dirForEntries = directoryName.Substring(f + 1); + dirForEntries = Path.Combine(rootDirectoryPathInArchive, dirForEntries); + } + + // if not top level, or if the root is non-empty, then explicitly add the directory + if (level > 0 || rootDirectoryPathInArchive != "") + { + baseDir = ZipEntry.CreateFromFile(directoryName, dirForEntries); + baseDir._container = new ZipContainer(this); + baseDir.AlternateEncoding = this.AlternateEncoding; // workitem 6410 + baseDir.AlternateEncodingUsage = this.AlternateEncodingUsage; + baseDir.MarkAsDirectory(); + baseDir.EmitTimesInWindowsFormatWhenSaving = _emitNtfsTimes; + baseDir.EmitTimesInUnixFormatWhenSaving = _emitUnixTimes; + + // add the directory only if it does not exist. + // It's not an error if it already exists. + if (!_entries.ContainsKey(baseDir.FileName)) + { + InternalAddEntry(baseDir.FileName,baseDir); + AfterAddEntry(baseDir); + } + dirForEntries = baseDir.FileName; + } + + if (!_addOperationCanceled) + { + + String[] filenames = Directory.GetFiles(directoryName); + + if (recurse) + { + // add the files: + foreach (String filename in filenames) + { + if (_addOperationCanceled) break; + if (action == AddOrUpdateAction.AddOnly) + AddFile(filename, dirForEntries); + else + UpdateFile(filename, dirForEntries); + } + + if (!_addOperationCanceled) + { + // add the subdirectories: + String[] dirnames = Directory.GetDirectories(directoryName); + foreach (String dir in dirnames) + { + // workitem 8617: Optionally traverse reparse points +#if SILVERLIGHT +#elif NETCF + FileAttributes fileAttrs = (FileAttributes) NetCfFile.GetAttributes(dir); +#else + FileAttributes fileAttrs = System.IO.File.GetAttributes(dir); +#endif + if (this.AddDirectoryWillTraverseReparsePoints +#if !SILVERLIGHT + || ((fileAttrs & FileAttributes.ReparsePoint) == 0) +#endif + ) + AddOrUpdateDirectoryImpl(dir, rootDirectoryPathInArchive, action, recurse, level + 1); + + } + + } + } + } + + if (level == 0) + OnAddCompleted(); + + return baseDir; + } + + } + +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Check.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Check.cs new file mode 100644 index 00000000..6d5499e7 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Check.cs @@ -0,0 +1,352 @@ +// ZipFile.Check.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009-2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-31 14:40:50> +// +// ------------------------------------------------------------------ +// +// This module defines the methods for doing Checks on zip files. +// These are not necessary to include in the Reduced or CF +// version of the library. +// +// ------------------------------------------------------------------ +// + + +using System; +using System.IO; +using System.Collections.Generic; + +namespace Ionic.Zip +{ + public partial class ZipFile + { + /// + /// Checks a zip file to see if its directory is consistent. + /// + /// + /// + /// + /// + /// In cases of data error, the directory within a zip file can get out + /// of synch with the entries in the zip file. This method checks the + /// given zip file and returns true if this has occurred. + /// + /// + /// This method may take a long time to run for large zip files. + /// + /// + /// This method is not supported in the Reduced or Compact Framework + /// versions of DotNetZip. + /// + /// + /// + /// Developers using COM can use the ComHelper.CheckZip(String) + /// method. + /// + /// + /// + /// + /// The filename to of the zip file to check. + /// + /// true if the named zip file checks OK. Otherwise, false. + /// + /// + /// + public static bool CheckZip(string zipFileName) + { + return CheckZip(zipFileName, false, null); + } + + + /// + /// Checks a zip file to see if its directory is consistent, + /// and optionally fixes the directory if necessary. + /// + /// + /// + /// + /// + /// In cases of data error, the directory within a zip file can get out of + /// synch with the entries in the zip file. This method checks the given + /// zip file, and returns true if this has occurred. It also optionally + /// fixes the zipfile, saving the fixed copy in Name_Fixed.zip. + /// + /// + /// + /// This method may take a long time to run for large zip files. It + /// will take even longer if the file actually needs to be fixed, and if + /// fixIfNecessary is true. + /// + /// + /// + /// This method is not supported in the Reduced or Compact + /// Framework versions of DotNetZip. + /// + /// + /// + /// + /// The filename to of the zip file to check. + /// + /// If true, the method will fix the zip file if + /// necessary. + /// + /// + /// a TextWriter in which messages generated while checking will be written. + /// + /// + /// true if the named zip is OK; false if the file needs to be fixed. + /// + /// + /// + public static bool CheckZip(string zipFileName, bool fixIfNecessary, + TextWriter writer) + + { + ZipFile zip1 = null, zip2 = null; + bool isOk = true; + try + { + zip1 = new ZipFile(); + zip1.FullScan = true; + zip1.Initialize(zipFileName); + + zip2 = ZipFile.Read(zipFileName); + + foreach (var e1 in zip1) + { + foreach (var e2 in zip2) + { + if (e1.FileName == e2.FileName) + { + if (e1._RelativeOffsetOfLocalHeader != e2._RelativeOffsetOfLocalHeader) + { + isOk = false; + if (writer != null) + writer.WriteLine("{0}: mismatch in RelativeOffsetOfLocalHeader (0x{1:X16} != 0x{2:X16})", + e1.FileName, e1._RelativeOffsetOfLocalHeader, + e2._RelativeOffsetOfLocalHeader); + } + if (e1._CompressedSize != e2._CompressedSize) + { + isOk = false; + if (writer != null) + writer.WriteLine("{0}: mismatch in CompressedSize (0x{1:X16} != 0x{2:X16})", + e1.FileName, e1._CompressedSize, + e2._CompressedSize); + } + if (e1._UncompressedSize != e2._UncompressedSize) + { + isOk = false; + if (writer != null) + writer.WriteLine("{0}: mismatch in UncompressedSize (0x{1:X16} != 0x{2:X16})", + e1.FileName, e1._UncompressedSize, + e2._UncompressedSize); + } + if (e1.CompressionMethod != e2.CompressionMethod) + { + isOk = false; + if (writer != null) + writer.WriteLine("{0}: mismatch in CompressionMethod (0x{1:X4} != 0x{2:X4})", + e1.FileName, e1.CompressionMethod, + e2.CompressionMethod); + } + if (e1.Crc != e2.Crc) + { + isOk = false; + if (writer != null) + writer.WriteLine("{0}: mismatch in Crc32 (0x{1:X4} != 0x{2:X4})", + e1.FileName, e1.Crc, + e2.Crc); + } + + // found a match, so stop the inside loop + break; + } + } + } + + zip2.Dispose(); + zip2 = null; + + if (!isOk && fixIfNecessary) + { + string newFileName = Path.GetFileNameWithoutExtension(zipFileName); + newFileName = System.String.Format("{0}_fixed.zip", newFileName); + zip1.Save(newFileName); + } + } + finally + { + if (zip1 != null) zip1.Dispose(); + if (zip2 != null) zip2.Dispose(); + } + return isOk; + } + + + + /// + /// Rewrite the directory within a zipfile. + /// + /// + /// + /// + /// + /// In cases of data error, the directory in a zip file can get out of + /// synch with the entries in the zip file. This method attempts to fix + /// the zip file if this has occurred. + /// + /// + /// This can take a long time for large zip files. + /// + /// This won't work if the zip file uses a non-standard + /// code page - neither IBM437 nor UTF-8. + /// + /// + /// This method is not supported in the Reduced or Compact Framework + /// versions of DotNetZip. + /// + /// + /// + /// Developers using COM can use the ComHelper.FixZipDirectory(String) + /// method. + /// + /// + /// + /// + /// The filename to of the zip file to fix. + /// + /// + /// + public static void FixZipDirectory(string zipFileName) + { + using (var zip = new ZipFile()) + { + zip.FullScan = true; + zip.Initialize(zipFileName); + zip.Save(zipFileName); + } + } + + + + /// + /// Verify the password on a zip file. + /// + /// + /// + /// + /// Keep in mind that passwords in zipfiles are applied to + /// zip entries, not to the entire zip file. So testing a + /// zipfile for a particular password doesn't work in the + /// general case. On the other hand, it's often the case + /// that a single password will be used on all entries in a + /// zip file. This method works for that case. + /// + /// + /// There is no way to check a password without doing the + /// decryption. So this code decrypts and extracts the given + /// zipfile into + /// + /// + /// + /// The filename to of the zip file to fix. + /// + /// The password to check. + /// + /// a bool indicating whether the password matches. + public static bool CheckZipPassword(string zipFileName, string password) + { + // workitem 13664 + bool success = false; + try + { + using (ZipFile zip1 = ZipFile.Read(zipFileName)) + { + foreach (var e in zip1) + { + if (!e.IsDirectory && e.UsesEncryption) + { + e.ExtractWithPassword(System.IO.Stream.Null, password); + } + } + } + success = true; + } + catch(Ionic.Zip.BadPasswordException) { } + return success; + } + + + /// + /// Provides a human-readable string with information about the ZipFile. + /// + /// + /// + /// + /// The information string contains 10 lines or so, about each ZipEntry, + /// describing whether encryption is in use, the compressed and uncompressed + /// length of the entry, the offset of the entry, and so on. As a result the + /// information string can be very long for zip files that contain many + /// entries. + /// + /// + /// This information is mostly useful for diagnostic purposes. + /// + /// + public string Info + { + get + { + var builder = new System.Text.StringBuilder(); + builder.Append(string.Format(" ZipFile: {0}\n", this.Name)); + if (!string.IsNullOrEmpty(this._Comment)) + { + builder.Append(string.Format(" Comment: {0}\n", this._Comment)); + } + if (this._versionMadeBy != 0) + { + builder.Append(string.Format(" version made by: 0x{0:X4}\n", this._versionMadeBy)); + } + if (this._versionNeededToExtract != 0) + { + builder.Append(string.Format("needed to extract: 0x{0:X4}\n", this._versionNeededToExtract)); + } + + builder.Append(string.Format(" uses ZIP64: {0}\n", this.InputUsesZip64)); + + builder.Append(string.Format(" disk with CD: {0}\n", this._diskNumberWithCd)); + if (this._OffsetOfCentralDirectory == 0xFFFFFFFF) + builder.Append(string.Format(" CD64 offset: 0x{0:X16}\n", this._OffsetOfCentralDirectory64)); + else + builder.Append(string.Format(" CD offset: 0x{0:X8}\n", this._OffsetOfCentralDirectory)); + builder.Append("\n"); + foreach (ZipEntry entry in this._entries.Values) + { + builder.Append(entry.Info); + } + return builder.ToString(); + } + } + + + } + +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Events.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Events.cs new file mode 100644 index 00000000..21784741 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Events.cs @@ -0,0 +1,1219 @@ +// ZipFile.Events.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2008, 2009, 2011 Dino Chiesa . +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-09 08:42:35> +// +// ------------------------------------------------------------------ +// +// This module defines the methods for issuing events from the ZipFile class. +// +// ------------------------------------------------------------------ +// + +using System; +using System.IO; + +namespace Ionic.Zip +{ + public partial class ZipFile + { + private string ArchiveNameForEvent + { + get + { + return (_name != null) ? _name : "(stream)"; + } + } + + #region Save + + /// + /// An event handler invoked when a Save() starts, before and after each + /// entry has been written to the archive, when a Save() completes, and + /// during other Save events. + /// + /// + /// + /// + /// Depending on the particular event, different properties on the parameter are set. The following + /// table summarizes the available EventTypes and the conditions under + /// which this event handler is invoked with a + /// SaveProgressEventArgs with the given EventType. + /// + /// + /// + /// + /// value of EntryType + /// Meaning and conditions + /// + /// + /// + /// ZipProgressEventType.Saving_Started + /// Fired when ZipFile.Save() begins. + /// + /// + /// + /// + /// ZipProgressEventType.Saving_BeforeSaveEntry + /// + /// Fired within ZipFile.Save(), just before writing data for each + /// particular entry. + /// + /// + /// + /// + /// ZipProgressEventType.Saving_AfterSaveEntry + /// + /// Fired within ZipFile.Save(), just after having finished writing data + /// for each particular entry. + /// + /// + /// + /// + /// ZipProgressEventType.Saving_Completed + /// Fired when ZipFile.Save() has completed. + /// + /// + /// + /// + /// ZipProgressEventType.Saving_AfterSaveTempArchive + /// + /// Fired after the temporary file has been created. This happens only + /// when saving to a disk file. This event will not be invoked when + /// saving to a stream. + /// + /// + /// + /// + /// ZipProgressEventType.Saving_BeforeRenameTempArchive + /// + /// Fired just before renaming the temporary file to the permanent + /// location. This happens only when saving to a disk file. This event + /// will not be invoked when saving to a stream. + /// + /// + /// + /// + /// ZipProgressEventType.Saving_AfterRenameTempArchive + /// + /// Fired just after renaming the temporary file to the permanent + /// location. This happens only when saving to a disk file. This event + /// will not be invoked when saving to a stream. + /// + /// + /// + /// + /// ZipProgressEventType.Saving_AfterCompileSelfExtractor + /// + /// Fired after a self-extracting archive has finished compiling. This + /// EventType is used only within SaveSelfExtractor(). + /// + /// + /// + /// + /// ZipProgressEventType.Saving_BytesRead + /// + /// Set during the save of a particular entry, to update progress of the + /// Save(). When this EventType is set, the BytesTransferred is the + /// number of bytes that have been read from the source stream. The + /// TotalBytesToTransfer is the number of bytes in the uncompressed + /// file. + /// + /// + /// + /// + /// + /// + /// + /// + /// This example uses an anonymous method to handle the + /// SaveProgress event, by updating a progress bar. + /// + /// + /// progressBar1.Value = 0; + /// progressBar1.Max = listbox1.Items.Count; + /// using (ZipFile zip = new ZipFile()) + /// { + /// // listbox1 contains a list of filenames + /// zip.AddFiles(listbox1.Items); + /// + /// // do the progress bar: + /// zip.SaveProgress += (sender, e) => { + /// if (e.EventType == ZipProgressEventType.Saving_BeforeWriteEntry) { + /// progressBar1.PerformStep(); + /// } + /// }; + /// + /// zip.Save(fs); + /// } + /// + /// + /// + /// + /// This example uses a named method as the + /// SaveProgress event handler, to update the user, in a + /// console-based application. + /// + /// + /// static bool justHadByteUpdate= false; + /// public static void SaveProgress(object sender, SaveProgressEventArgs e) + /// { + /// if (e.EventType == ZipProgressEventType.Saving_Started) + /// Console.WriteLine("Saving: {0}", e.ArchiveName); + /// + /// else if (e.EventType == ZipProgressEventType.Saving_Completed) + /// { + /// justHadByteUpdate= false; + /// Console.WriteLine(); + /// Console.WriteLine("Done: {0}", e.ArchiveName); + /// } + /// + /// else if (e.EventType == ZipProgressEventType.Saving_BeforeWriteEntry) + /// { + /// if (justHadByteUpdate) + /// Console.WriteLine(); + /// Console.WriteLine(" Writing: {0} ({1}/{2})", + /// e.CurrentEntry.FileName, e.EntriesSaved, e.EntriesTotal); + /// justHadByteUpdate= false; + /// } + /// + /// else if (e.EventType == ZipProgressEventType.Saving_EntryBytesRead) + /// { + /// if (justHadByteUpdate) + /// Console.SetCursorPosition(0, Console.CursorTop); + /// Console.Write(" {0}/{1} ({2:N0}%)", e.BytesTransferred, e.TotalBytesToTransfer, + /// e.BytesTransferred / (0.01 * e.TotalBytesToTransfer )); + /// justHadByteUpdate= true; + /// } + /// } + /// + /// public static ZipUp(string targetZip, string directory) + /// { + /// using (var zip = new ZipFile()) { + /// zip.SaveProgress += SaveProgress; + /// zip.AddDirectory(directory); + /// zip.Save(targetZip); + /// } + /// } + /// + /// + /// + /// + /// Public Sub ZipUp(ByVal targetZip As String, ByVal directory As String) + /// Using zip As ZipFile = New ZipFile + /// AddHandler zip.SaveProgress, AddressOf MySaveProgress + /// zip.AddDirectory(directory) + /// zip.Save(targetZip) + /// End Using + /// End Sub + /// + /// Private Shared justHadByteUpdate As Boolean = False + /// + /// Public Shared Sub MySaveProgress(ByVal sender As Object, ByVal e As SaveProgressEventArgs) + /// If (e.EventType Is ZipProgressEventType.Saving_Started) Then + /// Console.WriteLine("Saving: {0}", e.ArchiveName) + /// + /// ElseIf (e.EventType Is ZipProgressEventType.Saving_Completed) Then + /// justHadByteUpdate = False + /// Console.WriteLine + /// Console.WriteLine("Done: {0}", e.ArchiveName) + /// + /// ElseIf (e.EventType Is ZipProgressEventType.Saving_BeforeWriteEntry) Then + /// If justHadByteUpdate Then + /// Console.WriteLine + /// End If + /// Console.WriteLine(" Writing: {0} ({1}/{2})", e.CurrentEntry.FileName, e.EntriesSaved, e.EntriesTotal) + /// justHadByteUpdate = False + /// + /// ElseIf (e.EventType Is ZipProgressEventType.Saving_EntryBytesRead) Then + /// If justHadByteUpdate Then + /// Console.SetCursorPosition(0, Console.CursorTop) + /// End If + /// Console.Write(" {0}/{1} ({2:N0}%)", e.BytesTransferred, _ + /// e.TotalBytesToTransfer, _ + /// (CDbl(e.BytesTransferred) / (0.01 * e.TotalBytesToTransfer))) + /// justHadByteUpdate = True + /// End If + /// End Sub + /// + /// + /// + /// + /// + /// This is a more complete example of using the SaveProgress + /// events in a Windows Forms application, with a + /// Thread object. + /// + /// + /// delegate void SaveEntryProgress(SaveProgressEventArgs e); + /// delegate void ButtonClick(object sender, EventArgs e); + /// + /// public class WorkerOptions + /// { + /// public string ZipName; + /// public string Folder; + /// public string Encoding; + /// public string Comment; + /// public int ZipFlavor; + /// public Zip64Option Zip64; + /// } + /// + /// private int _progress2MaxFactor; + /// private bool _saveCanceled; + /// private long _totalBytesBeforeCompress; + /// private long _totalBytesAfterCompress; + /// private Thread _workerThread; + /// + /// + /// private void btnZipup_Click(object sender, EventArgs e) + /// { + /// KickoffZipup(); + /// } + /// + /// private void btnCancel_Click(object sender, EventArgs e) + /// { + /// if (this.lblStatus.InvokeRequired) + /// { + /// this.lblStatus.Invoke(new ButtonClick(this.btnCancel_Click), new object[] { sender, e }); + /// } + /// else + /// { + /// _saveCanceled = true; + /// lblStatus.Text = "Canceled..."; + /// ResetState(); + /// } + /// } + /// + /// private void KickoffZipup() + /// { + /// _folderName = tbDirName.Text; + /// + /// if (_folderName == null || _folderName == "") return; + /// if (this.tbZipName.Text == null || this.tbZipName.Text == "") return; + /// + /// // check for existence of the zip file: + /// if (System.IO.File.Exists(this.tbZipName.Text)) + /// { + /// var dlgResult = MessageBox.Show(String.Format("The file you have specified ({0}) already exists." + + /// " Do you want to overwrite this file?", this.tbZipName.Text), + /// "Confirmation is Required", MessageBoxButtons.YesNo, MessageBoxIcon.Question); + /// if (dlgResult != DialogResult.Yes) return; + /// System.IO.File.Delete(this.tbZipName.Text); + /// } + /// + /// _saveCanceled = false; + /// _nFilesCompleted = 0; + /// _totalBytesAfterCompress = 0; + /// _totalBytesBeforeCompress = 0; + /// this.btnOk.Enabled = false; + /// this.btnOk.Text = "Zipping..."; + /// this.btnCancel.Enabled = true; + /// lblStatus.Text = "Zipping..."; + /// + /// var options = new WorkerOptions + /// { + /// ZipName = this.tbZipName.Text, + /// Folder = _folderName, + /// Encoding = "ibm437" + /// }; + /// + /// if (this.comboBox1.SelectedIndex != 0) + /// { + /// options.Encoding = this.comboBox1.SelectedItem.ToString(); + /// } + /// + /// if (this.radioFlavorSfxCmd.Checked) + /// options.ZipFlavor = 2; + /// else if (this.radioFlavorSfxGui.Checked) + /// options.ZipFlavor = 1; + /// else options.ZipFlavor = 0; + /// + /// if (this.radioZip64AsNecessary.Checked) + /// options.Zip64 = Zip64Option.AsNecessary; + /// else if (this.radioZip64Always.Checked) + /// options.Zip64 = Zip64Option.Always; + /// else options.Zip64 = Zip64Option.Never; + /// + /// options.Comment = String.Format("Encoding:{0} || Flavor:{1} || ZIP64:{2}\r\nCreated at {3} || {4}\r\n", + /// options.Encoding, + /// FlavorToString(options.ZipFlavor), + /// options.Zip64.ToString(), + /// System.DateTime.Now.ToString("yyyy-MMM-dd HH:mm:ss"), + /// this.Text); + /// + /// if (this.tbComment.Text != TB_COMMENT_NOTE) + /// options.Comment += this.tbComment.Text; + /// + /// _workerThread = new Thread(this.DoSave); + /// _workerThread.Name = "Zip Saver thread"; + /// _workerThread.Start(options); + /// this.Cursor = Cursors.WaitCursor; + /// } + /// + /// + /// private void DoSave(Object p) + /// { + /// WorkerOptions options = p as WorkerOptions; + /// try + /// { + /// using (var zip1 = new ZipFile()) + /// { + /// zip1.ProvisionalAlternateEncoding = System.Text.Encoding.GetEncoding(options.Encoding); + /// zip1.Comment = options.Comment; + /// zip1.AddDirectory(options.Folder); + /// _entriesToZip = zip1.EntryFileNames.Count; + /// SetProgressBars(); + /// zip1.SaveProgress += this.zip1_SaveProgress; + /// + /// zip1.UseZip64WhenSaving = options.Zip64; + /// + /// if (options.ZipFlavor == 1) + /// zip1.SaveSelfExtractor(options.ZipName, SelfExtractorFlavor.WinFormsApplication); + /// else if (options.ZipFlavor == 2) + /// zip1.SaveSelfExtractor(options.ZipName, SelfExtractorFlavor.ConsoleApplication); + /// else + /// zip1.Save(options.ZipName); + /// } + /// } + /// catch (System.Exception exc1) + /// { + /// MessageBox.Show(String.Format("Exception while zipping: {0}", exc1.Message)); + /// btnCancel_Click(null, null); + /// } + /// } + /// + /// + /// + /// void zip1_SaveProgress(object sender, SaveProgressEventArgs e) + /// { + /// switch (e.EventType) + /// { + /// case ZipProgressEventType.Saving_AfterWriteEntry: + /// StepArchiveProgress(e); + /// break; + /// case ZipProgressEventType.Saving_EntryBytesRead: + /// StepEntryProgress(e); + /// break; + /// case ZipProgressEventType.Saving_Completed: + /// SaveCompleted(); + /// break; + /// case ZipProgressEventType.Saving_AfterSaveTempArchive: + /// // this event only occurs when saving an SFX file + /// TempArchiveSaved(); + /// break; + /// } + /// if (_saveCanceled) + /// e.Cancel = true; + /// } + /// + /// + /// + /// private void StepArchiveProgress(SaveProgressEventArgs e) + /// { + /// if (this.progressBar1.InvokeRequired) + /// { + /// this.progressBar1.Invoke(new SaveEntryProgress(this.StepArchiveProgress), new object[] { e }); + /// } + /// else + /// { + /// if (!_saveCanceled) + /// { + /// _nFilesCompleted++; + /// this.progressBar1.PerformStep(); + /// _totalBytesAfterCompress += e.CurrentEntry.CompressedSize; + /// _totalBytesBeforeCompress += e.CurrentEntry.UncompressedSize; + /// + /// // reset the progress bar for the entry: + /// this.progressBar2.Value = this.progressBar2.Maximum = 1; + /// + /// this.Update(); + /// } + /// } + /// } + /// + /// + /// private void StepEntryProgress(SaveProgressEventArgs e) + /// { + /// if (this.progressBar2.InvokeRequired) + /// { + /// this.progressBar2.Invoke(new SaveEntryProgress(this.StepEntryProgress), new object[] { e }); + /// } + /// else + /// { + /// if (!_saveCanceled) + /// { + /// if (this.progressBar2.Maximum == 1) + /// { + /// // reset + /// Int64 max = e.TotalBytesToTransfer; + /// _progress2MaxFactor = 0; + /// while (max > System.Int32.MaxValue) + /// { + /// max /= 2; + /// _progress2MaxFactor++; + /// } + /// this.progressBar2.Maximum = (int)max; + /// lblStatus.Text = String.Format("{0} of {1} files...({2})", + /// _nFilesCompleted + 1, _entriesToZip, e.CurrentEntry.FileName); + /// } + /// + /// int xferred = e.BytesTransferred >> _progress2MaxFactor; + /// + /// this.progressBar2.Value = (xferred >= this.progressBar2.Maximum) + /// ? this.progressBar2.Maximum + /// : xferred; + /// + /// this.Update(); + /// } + /// } + /// } + /// + /// private void SaveCompleted() + /// { + /// if (this.lblStatus.InvokeRequired) + /// { + /// this.lblStatus.Invoke(new MethodInvoker(this.SaveCompleted)); + /// } + /// else + /// { + /// lblStatus.Text = String.Format("Done, Compressed {0} files, {1:N0}% of original.", + /// _nFilesCompleted, (100.00 * _totalBytesAfterCompress) / _totalBytesBeforeCompress); + /// ResetState(); + /// } + /// } + /// + /// private void ResetState() + /// { + /// this.btnCancel.Enabled = false; + /// this.btnOk.Enabled = true; + /// this.btnOk.Text = "Zip it!"; + /// this.progressBar1.Value = 0; + /// this.progressBar2.Value = 0; + /// this.Cursor = Cursors.Default; + /// if (!_workerThread.IsAlive) + /// _workerThread.Join(); + /// } + /// + /// + /// + /// + /// + /// + /// + public event EventHandler SaveProgress; + + + internal bool OnSaveBlock(ZipEntry entry, Int64 bytesXferred, Int64 totalBytesToXfer) + { + EventHandler sp = SaveProgress; + if (sp != null) + { + var e = SaveProgressEventArgs.ByteUpdate(ArchiveNameForEvent, entry, + bytesXferred, totalBytesToXfer); + sp(this, e); + if (e.Cancel) + _saveOperationCanceled = true; + } + return _saveOperationCanceled; + } + + private void OnSaveEntry(int current, ZipEntry entry, bool before) + { + EventHandler sp = SaveProgress; + if (sp != null) + { + var e = new SaveProgressEventArgs(ArchiveNameForEvent, before, _entries.Count, current, entry); + sp(this, e); + if (e.Cancel) + _saveOperationCanceled = true; + } + } + + private void OnSaveEvent(ZipProgressEventType eventFlavor) + { + EventHandler sp = SaveProgress; + if (sp != null) + { + var e = new SaveProgressEventArgs(ArchiveNameForEvent, eventFlavor); + sp(this, e); + if (e.Cancel) + _saveOperationCanceled = true; + } + } + + private void OnSaveStarted() + { + EventHandler sp = SaveProgress; + if (sp != null) + { + var e = SaveProgressEventArgs.Started(ArchiveNameForEvent); + sp(this, e); + if (e.Cancel) + _saveOperationCanceled = true; + } + } + private void OnSaveCompleted() + { + EventHandler sp = SaveProgress; + if (sp != null) + { + var e = SaveProgressEventArgs.Completed(ArchiveNameForEvent); + sp(this, e); + } + } + #endregion + + + #region Read + /// + /// An event handler invoked before, during, and after the reading of a zip archive. + /// + /// + /// + /// + /// Depending on the particular event being signaled, different properties on the + /// parameter are set. The following table + /// summarizes the available EventTypes and the conditions under which this + /// event handler is invoked with a ReadProgressEventArgs with the given EventType. + /// + /// + /// + /// + /// value of EntryType + /// Meaning and conditions + /// + /// + /// + /// ZipProgressEventType.Reading_Started + /// Fired just as ZipFile.Read() begins. Meaningful properties: ArchiveName. + /// + /// + /// + /// + /// ZipProgressEventType.Reading_Completed + /// Fired when ZipFile.Read() has completed. Meaningful properties: ArchiveName. + /// + /// + /// + /// + /// ZipProgressEventType.Reading_ArchiveBytesRead + /// Fired while reading, updates the number of bytes read for the entire archive. + /// Meaningful properties: ArchiveName, CurrentEntry, BytesTransferred, TotalBytesToTransfer. + /// + /// + /// + /// + /// ZipProgressEventType.Reading_BeforeReadEntry + /// Indicates an entry is about to be read from the archive. + /// Meaningful properties: ArchiveName, EntriesTotal. + /// + /// + /// + /// + /// ZipProgressEventType.Reading_AfterReadEntry + /// Indicates an entry has just been read from the archive. + /// Meaningful properties: ArchiveName, EntriesTotal, CurrentEntry. + /// + /// + /// + /// + /// + /// + /// + /// + /// + public event EventHandler ReadProgress; + + private void OnReadStarted() + { + EventHandler rp = ReadProgress; + if (rp != null) + { + var e = ReadProgressEventArgs.Started(ArchiveNameForEvent); + rp(this, e); + } + } + + private void OnReadCompleted() + { + EventHandler rp = ReadProgress; + if (rp != null) + { + var e = ReadProgressEventArgs.Completed(ArchiveNameForEvent); + rp(this, e); + } + } + + internal void OnReadBytes(ZipEntry entry) + { + EventHandler rp = ReadProgress; + if (rp != null) + { + var e = ReadProgressEventArgs.ByteUpdate(ArchiveNameForEvent, + entry, + ReadStream.Position, + LengthOfReadStream); + rp(this, e); + } + } + + internal void OnReadEntry(bool before, ZipEntry entry) + { + EventHandler rp = ReadProgress; + if (rp != null) + { + ReadProgressEventArgs e = (before) + ? ReadProgressEventArgs.Before(ArchiveNameForEvent, _entries.Count) + : ReadProgressEventArgs.After(ArchiveNameForEvent, entry, _entries.Count); + rp(this, e); + } + } + + private Int64 _lengthOfReadStream = -99; + private Int64 LengthOfReadStream + { + get + { + if (_lengthOfReadStream == -99) + { + _lengthOfReadStream = (_ReadStreamIsOurs) + ? SharedUtilities.GetFileLength(_name) + : -1L; + } + return _lengthOfReadStream; + } + } + #endregion + + + #region Extract + /// + /// An event handler invoked before, during, and after extraction of + /// entries in the zip archive. + /// + /// + /// + /// + /// Depending on the particular event, different properties on the parameter are set. The following + /// table summarizes the available EventTypes and the conditions under + /// which this event handler is invoked with a + /// ExtractProgressEventArgs with the given EventType. + /// + /// + /// + /// + /// value of EntryType + /// Meaning and conditions + /// + /// + /// + /// ZipProgressEventType.Extracting_BeforeExtractAll + /// + /// Set when ExtractAll() begins. The ArchiveName, Overwrite, and + /// ExtractLocation properties are meaningful. + /// + /// + /// + /// ZipProgressEventType.Extracting_AfterExtractAll + /// + /// Set when ExtractAll() has completed. The ArchiveName, Overwrite, + /// and ExtractLocation properties are meaningful. + /// + /// + /// + /// + /// ZipProgressEventType.Extracting_BeforeExtractEntry + /// + /// Set when an Extract() on an entry in the ZipFile has begun. + /// Properties that are meaningful: ArchiveName, EntriesTotal, + /// CurrentEntry, Overwrite, ExtractLocation, EntriesExtracted. + /// + /// + /// + /// + /// ZipProgressEventType.Extracting_AfterExtractEntry + /// + /// Set when an Extract() on an entry in the ZipFile has completed. + /// Properties that are meaningful: ArchiveName, EntriesTotal, + /// CurrentEntry, Overwrite, ExtractLocation, EntriesExtracted. + /// + /// + /// + /// + /// ZipProgressEventType.Extracting_EntryBytesWritten + /// + /// Set within a call to Extract() on an entry in the ZipFile, as data + /// is extracted for the entry. Properties that are meaningful: + /// ArchiveName, CurrentEntry, BytesTransferred, TotalBytesToTransfer. + /// + /// + /// + /// + /// ZipProgressEventType.Extracting_ExtractEntryWouldOverwrite + /// + /// Set within a call to Extract() on an entry in the ZipFile, when the + /// extraction would overwrite an existing file. This event type is used + /// only when ExtractExistingFileAction on the ZipFile or + /// ZipEntry is set to InvokeExtractProgressEvent. + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// private static bool justHadByteUpdate = false; + /// public static void ExtractProgress(object sender, ExtractProgressEventArgs e) + /// { + /// if(e.EventType == ZipProgressEventType.Extracting_EntryBytesWritten) + /// { + /// if (justHadByteUpdate) + /// Console.SetCursorPosition(0, Console.CursorTop); + /// + /// Console.Write(" {0}/{1} ({2:N0}%)", e.BytesTransferred, e.TotalBytesToTransfer, + /// e.BytesTransferred / (0.01 * e.TotalBytesToTransfer )); + /// justHadByteUpdate = true; + /// } + /// else if(e.EventType == ZipProgressEventType.Extracting_BeforeExtractEntry) + /// { + /// if (justHadByteUpdate) + /// Console.WriteLine(); + /// Console.WriteLine("Extracting: {0}", e.CurrentEntry.FileName); + /// justHadByteUpdate= false; + /// } + /// } + /// + /// public static ExtractZip(string zipToExtract, string directory) + /// { + /// string TargetDirectory= "extract"; + /// using (var zip = ZipFile.Read(zipToExtract)) { + /// zip.ExtractProgress += ExtractProgress; + /// foreach (var e in zip1) + /// { + /// e.Extract(TargetDirectory, true); + /// } + /// } + /// } + /// + /// + /// + /// Public Shared Sub Main(ByVal args As String()) + /// Dim ZipToUnpack As String = "C1P3SML.zip" + /// Dim TargetDir As String = "ExtractTest_Extract" + /// Console.WriteLine("Extracting file {0} to {1}", ZipToUnpack, TargetDir) + /// Using zip1 As ZipFile = ZipFile.Read(ZipToUnpack) + /// AddHandler zip1.ExtractProgress, AddressOf MyExtractProgress + /// Dim e As ZipEntry + /// For Each e In zip1 + /// e.Extract(TargetDir, True) + /// Next + /// End Using + /// End Sub + /// + /// Private Shared justHadByteUpdate As Boolean = False + /// + /// Public Shared Sub MyExtractProgress(ByVal sender As Object, ByVal e As ExtractProgressEventArgs) + /// If (e.EventType = ZipProgressEventType.Extracting_EntryBytesWritten) Then + /// If ExtractTest.justHadByteUpdate Then + /// Console.SetCursorPosition(0, Console.CursorTop) + /// End If + /// Console.Write(" {0}/{1} ({2:N0}%)", e.BytesTransferred, e.TotalBytesToTransfer, (CDbl(e.BytesTransferred) / (0.01 * e.TotalBytesToTransfer))) + /// ExtractTest.justHadByteUpdate = True + /// ElseIf (e.EventType = ZipProgressEventType.Extracting_BeforeExtractEntry) Then + /// If ExtractTest.justHadByteUpdate Then + /// Console.WriteLine + /// End If + /// Console.WriteLine("Extracting: {0}", e.CurrentEntry.FileName) + /// ExtractTest.justHadByteUpdate = False + /// End If + /// End Sub + /// + /// + /// + /// + /// + /// + public event EventHandler ExtractProgress; + + + + private void OnExtractEntry(int current, bool before, ZipEntry currentEntry, string path) + { + EventHandler ep = ExtractProgress; + if (ep != null) + { + var e = new ExtractProgressEventArgs(ArchiveNameForEvent, before, _entries.Count, current, currentEntry, path); + ep(this, e); + if (e.Cancel) + _extractOperationCanceled = true; + } + } + + + // Can be called from within ZipEntry._ExtractOne. + internal bool OnExtractBlock(ZipEntry entry, Int64 bytesWritten, Int64 totalBytesToWrite) + { + EventHandler ep = ExtractProgress; + if (ep != null) + { + var e = ExtractProgressEventArgs.ByteUpdate(ArchiveNameForEvent, entry, + bytesWritten, totalBytesToWrite); + ep(this, e); + if (e.Cancel) + _extractOperationCanceled = true; + } + return _extractOperationCanceled; + } + + + // Can be called from within ZipEntry.InternalExtract. + internal bool OnSingleEntryExtract(ZipEntry entry, string path, bool before) + { + EventHandler ep = ExtractProgress; + if (ep != null) + { + var e = (before) + ? ExtractProgressEventArgs.BeforeExtractEntry(ArchiveNameForEvent, entry, path) + : ExtractProgressEventArgs.AfterExtractEntry(ArchiveNameForEvent, entry, path); + ep(this, e); + if (e.Cancel) + _extractOperationCanceled = true; + } + return _extractOperationCanceled; + } + + internal bool OnExtractExisting(ZipEntry entry, string path) + { + EventHandler ep = ExtractProgress; + if (ep != null) + { + var e = ExtractProgressEventArgs.ExtractExisting(ArchiveNameForEvent, entry, path); + ep(this, e); + if (e.Cancel) + _extractOperationCanceled = true; + } + return _extractOperationCanceled; + } + + + private void OnExtractAllCompleted(string path) + { + EventHandler ep = ExtractProgress; + if (ep != null) + { + var e = ExtractProgressEventArgs.ExtractAllCompleted(ArchiveNameForEvent, + path ); + ep(this, e); + } + } + + + private void OnExtractAllStarted(string path) + { + EventHandler ep = ExtractProgress; + if (ep != null) + { + var e = ExtractProgressEventArgs.ExtractAllStarted(ArchiveNameForEvent, + path ); + ep(this, e); + } + } + + + #endregion + + + + #region Add + /// + /// An event handler invoked before, during, and after Adding entries to a zip archive. + /// + /// + /// + /// Adding a large number of entries to a zip file can take a long + /// time. For example, when calling on a + /// directory that contains 50,000 files, it could take 3 minutes or so. + /// This event handler allws an application to track the progress of the Add + /// operation, and to optionally cancel a lengthy Add operation. + /// + /// + /// + /// + /// + /// int _numEntriesToAdd= 0; + /// int _numEntriesAdded= 0; + /// void AddProgressHandler(object sender, AddProgressEventArgs e) + /// { + /// switch (e.EventType) + /// { + /// case ZipProgressEventType.Adding_Started: + /// Console.WriteLine("Adding files to the zip..."); + /// break; + /// case ZipProgressEventType.Adding_AfterAddEntry: + /// _numEntriesAdded++; + /// Console.WriteLine(String.Format("Adding file {0}/{1} :: {2}", + /// _numEntriesAdded, _numEntriesToAdd, e.CurrentEntry.FileName)); + /// break; + /// case ZipProgressEventType.Adding_Completed: + /// Console.WriteLine("Added all files"); + /// break; + /// } + /// } + /// + /// void CreateTheZip() + /// { + /// using (ZipFile zip = new ZipFile()) + /// { + /// zip.AddProgress += AddProgressHandler; + /// zip.AddDirectory(System.IO.Path.GetFileName(DirToZip)); + /// zip.Save(ZipFileToCreate); + /// } + /// } + /// + /// + /// + /// + /// + /// Private Sub AddProgressHandler(ByVal sender As Object, ByVal e As AddProgressEventArgs) + /// Select Case e.EventType + /// Case ZipProgressEventType.Adding_Started + /// Console.WriteLine("Adding files to the zip...") + /// Exit Select + /// Case ZipProgressEventType.Adding_AfterAddEntry + /// Console.WriteLine(String.Format("Adding file {0}", e.CurrentEntry.FileName)) + /// Exit Select + /// Case ZipProgressEventType.Adding_Completed + /// Console.WriteLine("Added all files") + /// Exit Select + /// End Select + /// End Sub + /// + /// Sub CreateTheZip() + /// Using zip as ZipFile = New ZipFile + /// AddHandler zip.AddProgress, AddressOf AddProgressHandler + /// zip.AddDirectory(System.IO.Path.GetFileName(DirToZip)) + /// zip.Save(ZipFileToCreate); + /// End Using + /// End Sub + /// + /// + /// + /// + /// + /// + /// + /// + public event EventHandler AddProgress; + + private void OnAddStarted() + { + EventHandler ap = AddProgress; + if (ap != null) + { + var e = AddProgressEventArgs.Started(ArchiveNameForEvent); + ap(this, e); + if (e.Cancel) // workitem 13371 + _addOperationCanceled = true; + } + } + + private void OnAddCompleted() + { + EventHandler ap = AddProgress; + if (ap != null) + { + var e = AddProgressEventArgs.Completed(ArchiveNameForEvent); + ap(this, e); + } + } + + internal void AfterAddEntry(ZipEntry entry) + { + EventHandler ap = AddProgress; + if (ap != null) + { + var e = AddProgressEventArgs.AfterEntry(ArchiveNameForEvent, entry, _entries.Count); + ap(this, e); + if (e.Cancel) // workitem 13371 + _addOperationCanceled = true; + } + } + + #endregion + + + + #region Error + /// + /// An event that is raised when an error occurs during open or read of files + /// while saving a zip archive. + /// + /// + /// + /// + /// Errors can occur as a file is being saved to the zip archive. For + /// example, the File.Open may fail, or a File.Read may fail, because of + /// lock conflicts or other reasons. If you add a handler to this event, + /// you can handle such errors in your own code. If you don't add a + /// handler, the library will throw an exception if it encounters an I/O + /// error during a call to Save(). + /// + /// + /// + /// Setting a handler implicitly sets to + /// ZipErrorAction.InvokeErrorEvent. + /// + /// + /// + /// The handler you add applies to all items that are + /// subsequently added to the ZipFile instance. If you set this + /// property after you have added items to the ZipFile, but before you + /// have called Save(), errors that occur while saving those items + /// will not cause the error handler to be invoked. + /// + /// + /// + /// If you want to handle any errors that occur with any entry in the zip + /// file using the same error handler, then add your error handler once, + /// before adding any entries to the zip archive. + /// + /// + /// + /// In the error handler method, you need to set the property on the + /// ZipErrorEventArgs.CurrentEntry. This communicates back to + /// DotNetZip what you would like to do with this particular error. Within + /// an error handler, if you set the ZipEntry.ZipErrorAction property + /// on the ZipEntry to ZipErrorAction.InvokeErrorEvent or if + /// you don't set it at all, the library will throw the exception. (It is the + /// same as if you had set the ZipEntry.ZipErrorAction property on the + /// ZipEntry to ZipErrorAction.Throw.) If you set the + /// ZipErrorEventArgs.Cancel to true, the entire Save() will be + /// canceled. + /// + /// + /// + /// In the case that you use ZipErrorAction.Skip, implying that + /// you want to skip the entry for which there's been an error, DotNetZip + /// tries to seek backwards in the output stream, and truncate all bytes + /// written on behalf of that particular entry. This works only if the + /// output stream is seekable. It will not work, for example, when using + /// ASPNET's Response.OutputStream. + /// + /// + /// + /// + /// + /// + /// This example shows how to use an event handler to handle + /// errors during save of the zip file. + /// + /// + /// public static void MyZipError(object sender, ZipErrorEventArgs e) + /// { + /// Console.WriteLine("Error saving {0}...", e.FileName); + /// Console.WriteLine(" Exception: {0}", e.exception); + /// ZipEntry entry = e.CurrentEntry; + /// string response = null; + /// // Ask the user whether he wants to skip this error or not + /// do + /// { + /// Console.Write("Retry, Skip, Throw, or Cancel ? (R/S/T/C) "); + /// response = Console.ReadLine(); + /// Console.WriteLine(); + /// + /// } while (response != null && + /// response[0]!='S' && response[0]!='s' && + /// response[0]!='R' && response[0]!='r' && + /// response[0]!='T' && response[0]!='t' && + /// response[0]!='C' && response[0]!='c'); + /// + /// e.Cancel = (response[0]=='C' || response[0]=='c'); + /// + /// if (response[0]=='S' || response[0]=='s') + /// entry.ZipErrorAction = ZipErrorAction.Skip; + /// else if (response[0]=='R' || response[0]=='r') + /// entry.ZipErrorAction = ZipErrorAction.Retry; + /// else if (response[0]=='T' || response[0]=='t') + /// entry.ZipErrorAction = ZipErrorAction.Throw; + /// } + /// + /// public void SaveTheFile() + /// { + /// string directoryToZip = "fodder"; + /// string directoryInArchive = "files"; + /// string zipFileToCreate = "Archive.zip"; + /// using (var zip = new ZipFile()) + /// { + /// // set the event handler before adding any entries + /// zip.ZipError += MyZipError; + /// zip.AddDirectory(directoryToZip, directoryInArchive); + /// zip.Save(zipFileToCreate); + /// } + /// } + /// + /// + /// + /// Private Sub MyZipError(ByVal sender As Object, ByVal e As Ionic.Zip.ZipErrorEventArgs) + /// ' At this point, the application could prompt the user for an action to take. + /// ' But in this case, this application will simply automatically skip the file, in case of error. + /// Console.WriteLine("Zip Error, entry {0}", e.CurrentEntry.FileName) + /// Console.WriteLine(" Exception: {0}", e.exception) + /// ' set the desired ZipErrorAction on the CurrentEntry to communicate that to DotNetZip + /// e.CurrentEntry.ZipErrorAction = Zip.ZipErrorAction.Skip + /// End Sub + /// + /// Public Sub SaveTheFile() + /// Dim directoryToZip As String = "fodder" + /// Dim directoryInArchive As String = "files" + /// Dim zipFileToCreate as String = "Archive.zip" + /// Using zipArchive As ZipFile = New ZipFile + /// ' set the event handler before adding any entries + /// AddHandler zipArchive.ZipError, AddressOf MyZipError + /// zipArchive.AddDirectory(directoryToZip, directoryInArchive) + /// zipArchive.Save(zipFileToCreate) + /// End Using + /// End Sub + /// + /// + /// + /// + /// + public event EventHandler ZipError; + + internal bool OnZipErrorSaving(ZipEntry entry, Exception exc) + { + if (ZipError != null) + { + lock (LOCK) + { + var e = ZipErrorEventArgs.Saving(this.Name, entry, exc); + ZipError(this, e); + if (e.Cancel) + _saveOperationCanceled = true; + } + } + return _saveOperationCanceled; + } + #endregion + + } +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Extract.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Extract.cs new file mode 100644 index 00000000..199d3c2b --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Extract.cs @@ -0,0 +1,298 @@ +// ZipFile.Extract.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-31 14:45:18> +// +// ------------------------------------------------------------------ +// +// This module defines the methods for Extract operations on zip files. +// +// ------------------------------------------------------------------ +// + + +using System; +using System.IO; +using System.Collections.Generic; + +namespace Ionic.Zip +{ + + public partial class ZipFile + { + + /// + /// Extracts all of the items in the zip archive, to the specified path in the + /// filesystem. The path can be relative or fully-qualified. + /// + /// + /// + /// + /// This method will extract all entries in the ZipFile to the + /// specified path. + /// + /// + /// + /// If an extraction of a file from the zip archive would overwrite an + /// existing file in the filesystem, the action taken is dictated by the + /// ExtractExistingFile property, which overrides any setting you may have + /// made on individual ZipEntry instances. By default, if you have not + /// set that property on the ZipFile instance, the entry will not + /// be extracted, the existing file will not be overwritten and an + /// exception will be thrown. To change this, set the property, or use the + /// overload that allows you to + /// specify an ExtractExistingFileAction parameter. + /// + /// + /// + /// The action to take when an extract would overwrite an existing file + /// applies to all entries. If you want to set this on a per-entry basis, + /// then you must use one of the ZipEntry.Extract methods. + /// + /// + /// + /// This method will send verbose output messages to the , if it is set on the ZipFile + /// instance. + /// + /// + /// + /// You may wish to take advantage of the ExtractProgress event. + /// + /// + /// + /// About timestamps: When extracting a file entry from a zip archive, the + /// extracted file gets the last modified time of the entry as stored in + /// the archive. The archive may also store extended file timestamp + /// information, including last accessed and created times. If these are + /// present in the ZipEntry, then the extracted file will also get + /// these times. + /// + /// + /// + /// A Directory entry is somewhat different. It will get the times as + /// described for a file entry, but, if there are file entries in the zip + /// archive that, when extracted, appear in the just-created directory, + /// then when those file entries are extracted, the last modified and last + /// accessed times of the directory will change, as a side effect. The + /// result is that after an extraction of a directory and a number of + /// files within the directory, the last modified and last accessed + /// timestamps on the directory will reflect the time that the last file + /// was extracted into the directory, rather than the time stored in the + /// zip archive for the directory. + /// + /// + /// + /// To compensate, when extracting an archive with ExtractAll, + /// DotNetZip will extract all the file and directory entries as described + /// above, but it will then make a second pass on the directories, and + /// reset the times on the directories to reflect what is stored in the + /// zip archive. + /// + /// + /// + /// This compensation is performed only within the context of an + /// ExtractAll. If you call ZipEntry.Extract on a directory + /// entry, the timestamps on directory in the filesystem will reflect the + /// times stored in the zip. If you then call ZipEntry.Extract on + /// a file entry, which is extracted into the directory, the timestamps on + /// the directory will be updated to the current time. + /// + /// + /// + /// + /// This example extracts all the entries in a zip archive file, to the + /// specified target directory. The extraction will overwrite any + /// existing files silently. + /// + /// + /// String TargetDirectory= "unpack"; + /// using(ZipFile zip= ZipFile.Read(ZipFileToExtract)) + /// { + /// zip.ExtractExistingFile= ExtractExistingFileAction.OverwriteSilently; + /// zip.ExtractAll(TargetDirectory); + /// } + /// + /// + /// + /// Dim TargetDirectory As String = "unpack" + /// Using zip As ZipFile = ZipFile.Read(ZipFileToExtract) + /// zip.ExtractExistingFile= ExtractExistingFileAction.OverwriteSilently + /// zip.ExtractAll(TargetDirectory) + /// End Using + /// + /// + /// + /// + /// + /// + /// + /// The path to which the contents of the zipfile will be extracted. + /// The path can be relative or fully-qualified. + /// + /// + public void ExtractAll(string path) + { + _InternalExtractAll(path, true); + } + + + + /// + /// Extracts all of the items in the zip archive, to the specified path in the + /// filesystem, using the specified behavior when extraction would overwrite an + /// existing file. + /// + /// + /// + /// + /// + /// This method will extract all entries in the ZipFile to the specified + /// path. For an extraction that would overwrite an existing file, the behavior + /// is dictated by , which overrides any + /// setting you may have made on individual ZipEntry instances. + /// + /// + /// + /// The action to take when an extract would overwrite an existing file + /// applies to all entries. If you want to set this on a per-entry basis, + /// then you must use or one of the similar methods. + /// + /// + /// + /// Calling this method is equivalent to setting the property and then calling . + /// + /// + /// + /// This method will send verbose output messages to the + /// , if it is set on the ZipFile instance. + /// + /// + /// + /// + /// This example extracts all the entries in a zip archive file, to the + /// specified target directory. It does not overwrite any existing files. + /// + /// String TargetDirectory= "c:\\unpack"; + /// using(ZipFile zip= ZipFile.Read(ZipFileToExtract)) + /// { + /// zip.ExtractAll(TargetDirectory, ExtractExistingFileAction.DontOverwrite); + /// } + /// + /// + /// + /// Dim TargetDirectory As String = "c:\unpack" + /// Using zip As ZipFile = ZipFile.Read(ZipFileToExtract) + /// zip.ExtractAll(TargetDirectory, ExtractExistingFileAction.DontOverwrite) + /// End Using + /// + /// + /// + /// + /// The path to which the contents of the zipfile will be extracted. + /// The path can be relative or fully-qualified. + /// + /// + /// + /// The action to take if extraction would overwrite an existing file. + /// + /// + public void ExtractAll(string path, ExtractExistingFileAction extractExistingFile) + { + ExtractExistingFile = extractExistingFile; + _InternalExtractAll(path, true); + } + + + private void _InternalExtractAll(string path, bool overrideExtractExistingProperty) + { + bool header = Verbose; + _inExtractAll = true; + try + { + OnExtractAllStarted(path); + + int n = 0; + foreach (ZipEntry e in _entries.Values) + { + if (header) + { + StatusMessageTextWriter.WriteLine("\n{1,-22} {2,-8} {3,4} {4,-8} {0}", + "Name", "Modified", "Size", "Ratio", "Packed"); + StatusMessageTextWriter.WriteLine(new System.String('-', 72)); + header = false; + } + if (Verbose) + { + StatusMessageTextWriter.WriteLine("{1,-22} {2,-8} {3,4:F0}% {4,-8} {0}", + e.FileName, + e.LastModified.ToString("yyyy-MM-dd HH:mm:ss"), + e.UncompressedSize, + e.CompressionRatio, + e.CompressedSize); + if (!String.IsNullOrEmpty(e.Comment)) + StatusMessageTextWriter.WriteLine(" Comment: {0}", e.Comment); + } + e.Password = _Password; // this may be null + OnExtractEntry(n, true, e, path); + if (overrideExtractExistingProperty) + e.ExtractExistingFile = this.ExtractExistingFile; + e.Extract(path); + n++; + OnExtractEntry(n, false, e, path); + if (_extractOperationCanceled) + break; + } + + if (!_extractOperationCanceled) + { + // workitem 8264: + // now, set times on directory entries, again. + // The problem is, extracting a file changes the times on the parent + // directory. So after all files have been extracted, we have to + // run through the directories again. + foreach (ZipEntry e in _entries.Values) + { + // check if it is a directory + if ((e.IsDirectory) || (e.FileName.EndsWith("/"))) + { + string outputFile = (e.FileName.StartsWith("/")) + ? Path.Combine(path, e.FileName.Substring(1)) + : Path.Combine(path, e.FileName); + + e._SetTimes(outputFile, false); + } + } + OnExtractAllCompleted(path); + } + + } + finally + { + + _inExtractAll = false; + } + } + + + } +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Read.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Read.cs new file mode 100644 index 00000000..7411c1a8 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Read.cs @@ -0,0 +1,1110 @@ +// ZipFile.Read.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009-2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-August-05 11:38:59> +// +// ------------------------------------------------------------------ +// +// This module defines the methods for Reading zip files. +// +// ------------------------------------------------------------------ +// + + +using System; +using System.IO; +using System.Collections.Generic; + +namespace Ionic.Zip +{ + /// + /// A class for collecting the various options that can be used when + /// Reading zip files for extraction or update. + /// + /// + /// + /// + /// When reading a zip file, there are several options an + /// application can set, to modify how the file is read, or what + /// the library does while reading. This class collects those + /// options into one container. + /// + /// + /// + /// Pass an instance of the ReadOptions class into the + /// ZipFile.Read() method. + /// + /// + /// . + /// . + /// + public class ReadOptions + { + /// + /// An event handler for Read operations. When opening large zip + /// archives, you may want to display a progress bar or other + /// indicator of status progress while reading. This parameter + /// allows you to specify a ReadProgress Event Handler directly. + /// When you call Read(), the progress event is invoked as + /// necessary. + /// + public EventHandler ReadProgress { get; set; } + + /// + /// The System.IO.TextWriter to use for writing verbose status messages + /// during operations on the zip archive. A console application may wish to + /// pass System.Console.Out to get messages on the Console. A graphical + /// or headless application may wish to capture the messages in a different + /// TextWriter, such as a System.IO.StringWriter. + /// + public TextWriter StatusMessageWriter { get; set; } + + /// + /// The System.Text.Encoding to use when reading in the zip archive. Be + /// careful specifying the encoding. If the value you use here is not the same + /// as the Encoding used when the zip archive was created (possibly by a + /// different archiver) you will get unexpected results and possibly exceptions. + /// + /// + /// + /// + public System.Text.Encoding @Encoding { get; set; } + } + + + public partial class ZipFile + { + /// + /// Reads a zip file archive and returns the instance. + /// + /// + /// + /// + /// The stream is read using the default System.Text.Encoding, which is the + /// IBM437 codepage. + /// + /// + /// + /// + /// Thrown if the ZipFile cannot be read. The implementation of this method + /// relies on System.IO.File.OpenRead, which can throw a variety of exceptions, + /// including specific exceptions if a file is not found, an unauthorized access + /// exception, exceptions for poorly formatted filenames, and so on. + /// + /// + /// + /// The name of the zip archive to open. This can be a fully-qualified or relative + /// pathname. + /// + /// + /// . + /// + /// The instance read from the zip archive. + /// + public static ZipFile Read(string fileName) + { + return ZipFile.Read(fileName, null, null, null); + } + + + /// + /// Reads a zip file archive from the named filesystem file using the + /// specified options. + /// + /// + /// + /// + /// This version of the Read() method allows the caller to pass + /// in a TextWriter an Encoding, via an instance of the + /// ReadOptions class. The ZipFile is read in using the + /// specified encoding for entries where UTF-8 encoding is not + /// explicitly specified. + /// + /// + /// + /// + /// + /// + /// This example shows how to read a zip file using the Big-5 Chinese + /// code page (950), and extract each entry in the zip file, while + /// sending status messages out to the Console. + /// + /// + /// + /// For this code to work as intended, the zipfile must have been + /// created using the big5 code page (CP950). This is typical, for + /// example, when using WinRar on a machine with CP950 set as the + /// default code page. In that case, the names of entries within the + /// Zip archive will be stored in that code page, and reading the zip + /// archive must be done using that code page. If the application did + /// not use the correct code page in ZipFile.Read(), then names of + /// entries within the zip archive would not be correctly retrieved. + /// + /// + /// + /// string zipToExtract = "MyArchive.zip"; + /// string extractDirectory = "extract"; + /// var options = new ReadOptions + /// { + /// StatusMessageWriter = System.Console.Out, + /// Encoding = System.Text.Encoding.GetEncoding(950) + /// }; + /// using (ZipFile zip = ZipFile.Read(zipToExtract, options)) + /// { + /// foreach (ZipEntry e in zip) + /// { + /// e.Extract(extractDirectory); + /// } + /// } + /// + /// + /// + /// + /// Dim zipToExtract as String = "MyArchive.zip" + /// Dim extractDirectory as String = "extract" + /// Dim options as New ReadOptions + /// options.Encoding = System.Text.Encoding.GetEncoding(950) + /// options.StatusMessageWriter = System.Console.Out + /// Using zip As ZipFile = ZipFile.Read(zipToExtract, options) + /// Dim e As ZipEntry + /// For Each e In zip + /// e.Extract(extractDirectory) + /// Next + /// End Using + /// + /// + /// + /// + /// + /// + /// + /// This example shows how to read a zip file using the default + /// code page, to remove entries that have a modified date before a given threshold, + /// sending status messages out to a StringWriter. + /// + /// + /// + /// var options = new ReadOptions + /// { + /// StatusMessageWriter = new System.IO.StringWriter() + /// }; + /// using (ZipFile zip = ZipFile.Read("PackedDocuments.zip", options)) + /// { + /// var Threshold = new DateTime(2007,7,4); + /// // We cannot remove the entry from the list, within the context of + /// // an enumeration of said list. + /// // So we add the doomed entry to a list to be removed later. + /// // pass 1: mark the entries for removal + /// var MarkedEntries = new System.Collections.Generic.List<ZipEntry>(); + /// foreach (ZipEntry e in zip) + /// { + /// if (e.LastModified < Threshold) + /// MarkedEntries.Add(e); + /// } + /// // pass 2: actually remove the entry. + /// foreach (ZipEntry zombie in MarkedEntries) + /// zip.RemoveEntry(zombie); + /// zip.Comment = "This archive has been updated."; + /// zip.Save(); + /// } + /// // can now use contents of sw, eg store in an audit log + /// + /// + /// + /// Dim options as New ReadOptions + /// options.StatusMessageWriter = New System.IO.StringWriter + /// Using zip As ZipFile = ZipFile.Read("PackedDocuments.zip", options) + /// Dim Threshold As New DateTime(2007, 7, 4) + /// ' We cannot remove the entry from the list, within the context of + /// ' an enumeration of said list. + /// ' So we add the doomed entry to a list to be removed later. + /// ' pass 1: mark the entries for removal + /// Dim MarkedEntries As New System.Collections.Generic.List(Of ZipEntry) + /// Dim e As ZipEntry + /// For Each e In zip + /// If (e.LastModified < Threshold) Then + /// MarkedEntries.Add(e) + /// End If + /// Next + /// ' pass 2: actually remove the entry. + /// Dim zombie As ZipEntry + /// For Each zombie In MarkedEntries + /// zip.RemoveEntry(zombie) + /// Next + /// zip.Comment = "This archive has been updated." + /// zip.Save + /// End Using + /// ' can now use contents of sw, eg store in an audit log + /// + /// + /// + /// + /// Thrown if the zipfile cannot be read. The implementation of + /// this method relies on System.IO.File.OpenRead, which + /// can throw a variety of exceptions, including specific + /// exceptions if a file is not found, an unauthorized access + /// exception, exceptions for poorly formatted filenames, and so + /// on. + /// + /// + /// + /// The name of the zip archive to open. + /// This can be a fully-qualified or relative pathname. + /// + /// + /// + /// The set of options to use when reading the zip file. + /// + /// + /// The ZipFile instance read from the zip archive. + /// + /// + /// + public static ZipFile Read(string fileName, + ReadOptions options) + { + if (options == null) + throw new ArgumentNullException("options"); + return Read(fileName, + options.StatusMessageWriter, + options.Encoding, + options.ReadProgress); + } + + /// + /// Reads a zip file archive using the specified text encoding, the specified + /// TextWriter for status messages, and the specified ReadProgress event handler, + /// and returns the instance. + /// + /// + /// + /// The name of the zip archive to open. + /// This can be a fully-qualified or relative pathname. + /// + /// + /// + /// An event handler for Read operations. + /// + /// + /// + /// The System.IO.TextWriter to use for writing verbose status messages + /// during operations on the zip archive. A console application may wish to + /// pass System.Console.Out to get messages on the Console. A graphical + /// or headless application may wish to capture the messages in a different + /// TextWriter, such as a System.IO.StringWriter. + /// + /// + /// + /// The System.Text.Encoding to use when reading in the zip archive. Be + /// careful specifying the encoding. If the value you use here is not the same + /// as the Encoding used when the zip archive was created (possibly by a + /// different archiver) you will get unexpected results and possibly exceptions. + /// + /// + /// The instance read from the zip archive. + /// + private static ZipFile Read(string fileName, + TextWriter statusMessageWriter, + System.Text.Encoding encoding, + EventHandler readProgress) + { + ZipFile zf = new ZipFile(); + zf.AlternateEncoding = encoding ?? DefaultEncoding; + zf.AlternateEncodingUsage = ZipOption.Always; + zf._StatusMessageTextWriter = statusMessageWriter; + zf._name = fileName; + if (readProgress != null) + zf.ReadProgress = readProgress; + + if (zf.Verbose) zf._StatusMessageTextWriter.WriteLine("reading from {0}...", fileName); + + ReadIntoInstance(zf); + zf._fileAlreadyExists = true; + + return zf; + } + + /// + /// Reads a zip archive from a stream. + /// + /// + /// + /// + /// + /// When reading from a file, it's probably easier to just use + /// ZipFile.Read(String, ReadOptions). This + /// overload is useful when when the zip archive content is + /// available from an already-open stream. The stream must be + /// open and readable and seekable when calling this method. The + /// stream is left open when the reading is completed. + /// + /// + /// + /// Using this overload, the stream is read using the default + /// System.Text.Encoding, which is the IBM437 + /// codepage. If you want to specify the encoding to use when + /// reading the zipfile content, see + /// ZipFile.Read(Stream, ReadOptions). This + /// + /// + /// + /// Reading of zip content begins at the current position in the + /// stream. This means if you have a stream that concatenates + /// regular data and zip data, if you position the open, readable + /// stream at the start of the zip data, you will be able to read + /// the zip archive using this constructor, or any of the ZipFile + /// constructors that accept a as + /// input. Some examples of where this might be useful: the zip + /// content is concatenated at the end of a regular EXE file, as + /// some self-extracting archives do. (Note: SFX files produced + /// by DotNetZip do not work this way; they can be read as normal + /// ZIP files). Another example might be a stream being read from + /// a database, where the zip content is embedded within an + /// aggregate stream of data. + /// + /// + /// + /// + /// + /// + /// This example shows how to Read zip content from a stream, and + /// extract one entry into a different stream. In this example, + /// the filename "NameOfEntryInArchive.doc", refers only to the + /// name of the entry within the zip archive. A file by that + /// name is not created in the filesystem. The I/O is done + /// strictly with the given streams. + /// + /// + /// + /// using (ZipFile zip = ZipFile.Read(InputStream)) + /// { + /// zip.Extract("NameOfEntryInArchive.doc", OutputStream); + /// } + /// + /// + /// + /// Using zip as ZipFile = ZipFile.Read(InputStream) + /// zip.Extract("NameOfEntryInArchive.doc", OutputStream) + /// End Using + /// + /// + /// + /// the stream containing the zip data. + /// + /// The ZipFile instance read from the stream + /// + public static ZipFile Read(Stream zipStream) + { + return Read(zipStream, null, null, null); + } + + /// + /// Reads a zip file archive from the given stream using the + /// specified options. + /// + /// + /// + /// + /// + /// When reading from a file, it's probably easier to just use + /// ZipFile.Read(String, ReadOptions). This + /// overload is useful when when the zip archive content is + /// available from an already-open stream. The stream must be + /// open and readable and seekable when calling this method. The + /// stream is left open when the reading is completed. + /// + /// + /// + /// Reading of zip content begins at the current position in the + /// stream. This means if you have a stream that concatenates + /// regular data and zip data, if you position the open, readable + /// stream at the start of the zip data, you will be able to read + /// the zip archive using this constructor, or any of the ZipFile + /// constructors that accept a as + /// input. Some examples of where this might be useful: the zip + /// content is concatenated at the end of a regular EXE file, as + /// some self-extracting archives do. (Note: SFX files produced + /// by DotNetZip do not work this way; they can be read as normal + /// ZIP files). Another example might be a stream being read from + /// a database, where the zip content is embedded within an + /// aggregate stream of data. + /// + /// + /// + /// the stream containing the zip data. + /// + /// + /// The set of options to use when reading the zip file. + /// + /// + /// + /// Thrown if the zip archive cannot be read. + /// + /// + /// The ZipFile instance read from the stream. + /// + /// + /// + public static ZipFile Read(Stream zipStream, ReadOptions options) + { + if (options == null) + throw new ArgumentNullException("options"); + + return Read(zipStream, + options.StatusMessageWriter, + options.Encoding, + options.ReadProgress); + } + + + + /// + /// Reads a zip archive from a stream, using the specified text Encoding, the + /// specified TextWriter for status messages, + /// and the specified ReadProgress event handler. + /// + /// + /// + /// + /// Reading of zip content begins at the current position in the stream. This + /// means if you have a stream that concatenates regular data and zip data, if + /// you position the open, readable stream at the start of the zip data, you + /// will be able to read the zip archive using this constructor, or any of the + /// ZipFile constructors that accept a as + /// input. Some examples of where this might be useful: the zip content is + /// concatenated at the end of a regular EXE file, as some self-extracting + /// archives do. (Note: SFX files produced by DotNetZip do not work this + /// way). Another example might be a stream being read from a database, where + /// the zip content is embedded within an aggregate stream of data. + /// + /// + /// + /// the stream containing the zip data. + /// + /// + /// The System.IO.TextWriter to which verbose status messages are written + /// during operations on the ZipFile. For example, in a console + /// application, System.Console.Out works, and will get a message for each entry + /// added to the ZipFile. If the TextWriter is null, no verbose messages + /// are written. + /// + /// + /// + /// The text encoding to use when reading entries that do not have the UTF-8 + /// encoding bit set. Be careful specifying the encoding. If the value you use + /// here is not the same as the Encoding used when the zip archive was created + /// (possibly by a different archiver) you will get unexpected results and + /// possibly exceptions. See the + /// property for more information. + /// + /// + /// + /// An event handler for Read operations. + /// + /// + /// an instance of ZipFile + private static ZipFile Read(Stream zipStream, + TextWriter statusMessageWriter, + System.Text.Encoding encoding, + EventHandler readProgress) + { + if (zipStream == null) + throw new ArgumentNullException("zipStream"); + + ZipFile zf = new ZipFile(); + zf._StatusMessageTextWriter = statusMessageWriter; + zf._alternateEncoding = encoding ?? ZipFile.DefaultEncoding; + zf._alternateEncodingUsage = ZipOption.Always; + if (readProgress != null) + zf.ReadProgress += readProgress; + zf._readstream = (zipStream.Position == 0L) + ? zipStream + : new OffsetStream(zipStream); + zf._ReadStreamIsOurs = false; + if (zf.Verbose) zf._StatusMessageTextWriter.WriteLine("reading from stream..."); + + ReadIntoInstance(zf); + return zf; + } + + + + private static void ReadIntoInstance(ZipFile zf) + { + Stream s = zf.ReadStream; + try + { + zf._readName = zf._name; // workitem 13915 + if (!s.CanSeek) + { + ReadIntoInstance_Orig(zf); + return; + } + + zf.OnReadStarted(); + + // change for workitem 8098 + //zf._originPosition = s.Position; + + // Try reading the central directory, rather than scanning the file. + + uint datum = ReadFirstFourBytes(s); + + if (datum == ZipConstants.EndOfCentralDirectorySignature) + return; + + + // start at the end of the file... + // seek backwards a bit, then look for the EoCD signature. + int nTries = 0; + bool success = false; + + // The size of the end-of-central-directory-footer plus 2 bytes is 18. + // This implies an archive comment length of 0. We'll add a margin of + // safety and start "in front" of that, when looking for the + // EndOfCentralDirectorySignature + long posn = s.Length - 64; + long maxSeekback = Math.Max(s.Length - 0x4000, 10); + do + { + if (posn < 0) posn = 0; // BOF + s.Seek(posn, SeekOrigin.Begin); + long bytesRead = SharedUtilities.FindSignature(s, (int)ZipConstants.EndOfCentralDirectorySignature); + if (bytesRead != -1) + success = true; + else + { + if (posn==0) break; // started at the BOF and found nothing + nTries++; + // Weird: with NETCF, negative offsets from SeekOrigin.End DO + // NOT WORK. So rather than seek a negative offset, we seek + // from SeekOrigin.Begin using a smaller number. + posn -= (32 * (nTries + 1) * nTries); + } + } + while (!success && posn > maxSeekback); + + if (success) + { + // workitem 8299 + zf._locEndOfCDS = s.Position - 4; + + byte[] block = new byte[16]; + s.Read(block, 0, block.Length); + + zf._diskNumberWithCd = BitConverter.ToUInt16(block, 2); + + if (zf._diskNumberWithCd == 0xFFFF) + throw new ZipException("Spanned archives with more than 65534 segments are not supported at this time."); + + zf._diskNumberWithCd++; // I think the number in the file differs from reality by 1 + + int i = 12; + + uint offset32 = (uint) BitConverter.ToUInt32(block, i); + if (offset32 == 0xFFFFFFFF) + { + Zip64SeekToCentralDirectory(zf); + } + else + { + zf._OffsetOfCentralDirectory = offset32; + // change for workitem 8098 + s.Seek(offset32, SeekOrigin.Begin); + } + + ReadCentralDirectory(zf); + } + else + { + // Could not find the central directory. + // Fallback to the old method. + // workitem 8098: ok + //s.Seek(zf._originPosition, SeekOrigin.Begin); + s.Seek(0L, SeekOrigin.Begin); + ReadIntoInstance_Orig(zf); + } + } + catch (Exception ex1) + { + if (zf._ReadStreamIsOurs && zf._readstream != null) + { + try + { +#if NETCF + zf._readstream.Close(); +#else + zf._readstream.Dispose(); +#endif + zf._readstream = null; + } + finally { } + } + + throw new ZipException("Cannot read that as a ZipFile", ex1); + } + + // the instance has been read in + zf._contentsChanged = false; + } + + + + private static void Zip64SeekToCentralDirectory(ZipFile zf) + { + Stream s = zf.ReadStream; + byte[] block = new byte[16]; + + // seek back to find the ZIP64 EoCD. + // I think this might not work for .NET CF ? + s.Seek(-40, SeekOrigin.Current); + s.Read(block, 0, 16); + + Int64 offset64 = BitConverter.ToInt64(block, 8); + zf._OffsetOfCentralDirectory = 0xFFFFFFFF; + zf._OffsetOfCentralDirectory64 = offset64; + // change for workitem 8098 + s.Seek(offset64, SeekOrigin.Begin); + //zf.SeekFromOrigin(Offset64); + + uint datum = (uint)Ionic.Zip.SharedUtilities.ReadInt(s); + if (datum != ZipConstants.Zip64EndOfCentralDirectoryRecordSignature) + throw new BadReadException(String.Format(" Bad signature (0x{0:X8}) looking for ZIP64 EoCD Record at position 0x{1:X8}", datum, s.Position)); + + s.Read(block, 0, 8); + Int64 Size = BitConverter.ToInt64(block, 0); + + block = new byte[Size]; + s.Read(block, 0, block.Length); + + offset64 = BitConverter.ToInt64(block, 36); + // change for workitem 8098 + s.Seek(offset64, SeekOrigin.Begin); + //zf.SeekFromOrigin(Offset64); + } + + + private static uint ReadFirstFourBytes(Stream s) + { + uint datum = (uint)Ionic.Zip.SharedUtilities.ReadInt(s); + return datum; + } + + + + private static void ReadCentralDirectory(ZipFile zf) + { + // We must have the central directory footer record, in order to properly + // read zip dir entries from the central directory. This because the logic + // knows when to open a spanned file when the volume number for the central + // directory differs from the volume number for the zip entry. The + // _diskNumberWithCd was set when originally finding the offset for the + // start of the Central Directory. + + // workitem 9214 + bool inputUsesZip64 = false; + ZipEntry de; + // in lieu of hashset, use a dictionary + var previouslySeen = new Dictionary(); + while ((de = ZipEntry.ReadDirEntry(zf, previouslySeen)) != null) + { + de.ResetDirEntry(); + zf.OnReadEntry(true, null); + + if (zf.Verbose) + zf.StatusMessageTextWriter.WriteLine("entry {0}", de.FileName); + + zf._entries.Add(de.FileName,de); + + // workitem 9214 + if (de._InputUsesZip64) inputUsesZip64 = true; + previouslySeen.Add(de.FileName, null); // to prevent dupes + } + + // workitem 9214; auto-set the zip64 flag + if (inputUsesZip64) zf.UseZip64WhenSaving = Zip64Option.Always; + + // workitem 8299 + if (zf._locEndOfCDS > 0) + zf.ReadStream.Seek(zf._locEndOfCDS, SeekOrigin.Begin); + + ReadCentralDirectoryFooter(zf); + + if (zf.Verbose && !String.IsNullOrEmpty(zf.Comment)) + zf.StatusMessageTextWriter.WriteLine("Zip file Comment: {0}", zf.Comment); + + // We keep the read stream open after reading. + + if (zf.Verbose) + zf.StatusMessageTextWriter.WriteLine("read in {0} entries.", zf._entries.Count); + + zf.OnReadCompleted(); + } + + + + + // build the TOC by reading each entry in the file. + private static void ReadIntoInstance_Orig(ZipFile zf) + { + zf.OnReadStarted(); + //zf._entries = new System.Collections.Generic.List(); + zf._entries = new System.Collections.Generic.Dictionary(); + + ZipEntry e; + if (zf.Verbose) + if (zf.Name == null) + zf.StatusMessageTextWriter.WriteLine("Reading zip from stream..."); + else + zf.StatusMessageTextWriter.WriteLine("Reading zip {0}...", zf.Name); + + // work item 6647: PK00 (packed to removable disk) + bool firstEntry = true; + ZipContainer zc = new ZipContainer(zf); + while ((e = ZipEntry.ReadEntry(zc, firstEntry)) != null) + { + if (zf.Verbose) + zf.StatusMessageTextWriter.WriteLine(" {0}", e.FileName); + + zf._entries.Add(e.FileName,e); + firstEntry = false; + } + + // read the zipfile's central directory structure here. + // workitem 9912 + // But, because it may be corrupted, ignore errors. + try + { + ZipEntry de; + // in lieu of hashset, use a dictionary + var previouslySeen = new Dictionary(); + while ((de = ZipEntry.ReadDirEntry(zf, previouslySeen)) != null) + { + // Housekeeping: Since ZipFile exposes ZipEntry elements in the enumerator, + // we need to copy the comment that we grab from the ZipDirEntry + // into the ZipEntry, so the application can access the comment. + // Also since ZipEntry is used to Write zip files, we need to copy the + // file attributes to the ZipEntry as appropriate. + ZipEntry e1 = zf._entries[de.FileName]; + if (e1 != null) + { + e1._Comment = de.Comment; + if (de.IsDirectory) e1.MarkAsDirectory(); + } + previouslySeen.Add(de.FileName,null); // to prevent dupes + } + + // workitem 8299 + if (zf._locEndOfCDS > 0) + zf.ReadStream.Seek(zf._locEndOfCDS, SeekOrigin.Begin); + + ReadCentralDirectoryFooter(zf); + + if (zf.Verbose && !String.IsNullOrEmpty(zf.Comment)) + zf.StatusMessageTextWriter.WriteLine("Zip file Comment: {0}", zf.Comment); + } + catch (ZipException) { } + catch (IOException) { } + + zf.OnReadCompleted(); + } + + + + + private static void ReadCentralDirectoryFooter(ZipFile zf) + { + Stream s = zf.ReadStream; + int signature = Ionic.Zip.SharedUtilities.ReadSignature(s); + + byte[] block = null; + int j = 0; + if (signature == ZipConstants.Zip64EndOfCentralDirectoryRecordSignature) + { + // We have a ZIP64 EOCD + // This data block is 4 bytes sig, 8 bytes size, 44 bytes fixed data, + // followed by a variable-sized extension block. We have read the sig already. + // 8 - datasize (64 bits) + // 2 - version made by + // 2 - version needed to extract + // 4 - number of this disk + // 4 - number of the disk with the start of the CD + // 8 - total number of entries in the CD on this disk + // 8 - total number of entries in the CD + // 8 - size of the CD + // 8 - offset of the CD + // ----------------------- + // 52 bytes + + block = new byte[8 + 44]; + s.Read(block, 0, block.Length); + + Int64 DataSize = BitConverter.ToInt64(block, 0); // == 44 + the variable length + + if (DataSize < 44) + throw new ZipException("Bad size in the ZIP64 Central Directory."); + + zf._versionMadeBy = BitConverter.ToUInt16(block, j); + j += 2; + zf._versionNeededToExtract = BitConverter.ToUInt16(block, j); + j += 2; + zf._diskNumberWithCd = BitConverter.ToUInt32(block, j); + j += 2; + + //zf._diskNumberWithCd++; // hack!! + + // read the extended block + block = new byte[DataSize - 44]; + s.Read(block, 0, block.Length); + // discard the result + + signature = Ionic.Zip.SharedUtilities.ReadSignature(s); + if (signature != ZipConstants.Zip64EndOfCentralDirectoryLocatorSignature) + throw new ZipException("Inconsistent metadata in the ZIP64 Central Directory."); + + block = new byte[16]; + s.Read(block, 0, block.Length); + // discard the result + + signature = Ionic.Zip.SharedUtilities.ReadSignature(s); + } + + // Throw if this is not a signature for "end of central directory record" + // This is a sanity check. + if (signature != ZipConstants.EndOfCentralDirectorySignature) + { + s.Seek(-4, SeekOrigin.Current); + throw new BadReadException(String.Format("Bad signature ({0:X8}) at position 0x{1:X8}", + signature, s.Position)); + } + + // read the End-of-Central-Directory-Record + block = new byte[16]; + zf.ReadStream.Read(block, 0, block.Length); + + // off sz data + // ------------------------------------------------------- + // 0 4 end of central dir signature (0x06054b50) + // 4 2 number of this disk + // 6 2 number of the disk with start of the central directory + // 8 2 total number of entries in the central directory on this disk + // 10 2 total number of entries in the central directory + // 12 4 size of the central directory + // 16 4 offset of start of central directory with respect to the starting disk number + // 20 2 ZIP file comment length + // 22 ?? ZIP file comment + + if (zf._diskNumberWithCd == 0) + { + zf._diskNumberWithCd = BitConverter.ToUInt16(block, 2); + //zf._diskNumberWithCd++; // hack!! + } + + // read the comment here + ReadZipFileComment(zf); + } + + + + private static void ReadZipFileComment(ZipFile zf) + { + // read the comment here + byte[] block = new byte[2]; + zf.ReadStream.Read(block, 0, block.Length); + + Int16 commentLength = (short)(block[0] + block[1] * 256); + if (commentLength > 0) + { + block = new byte[commentLength]; + zf.ReadStream.Read(block, 0, block.Length); + + // workitem 10392 - prefer ProvisionalAlternateEncoding, + // first. The fix for workitem 6513 tried to use UTF8 + // only as necessary, but that is impossible to test + // for, in this direction. There's no way to know what + // characters the already-encoded bytes refer + // to. Therefore, must do what the user tells us. + + string s1 = zf.AlternateEncoding.GetString(block, 0, block.Length); + zf.Comment = s1; + } + } + + + // private static bool BlocksAreEqual(byte[] a, byte[] b) + // { + // if (a.Length != b.Length) return false; + // for (int i = 0; i < a.Length; i++) + // { + // if (a[i] != b[i]) return false; + // } + // return true; + // } + + + + /// + /// Checks the given file to see if it appears to be a valid zip file. + /// + /// + /// + /// + /// Calling this method is equivalent to calling with the testExtract parameter set to false. + /// + /// + /// + /// The file to check. + /// true if the file appears to be a zip file. + public static bool IsZipFile(string fileName) + { + return IsZipFile(fileName, false); + } + + + /// + /// Checks a file to see if it is a valid zip file. + /// + /// + /// + /// + /// This method opens the specified zip file, reads in the zip archive, + /// verifying the ZIP metadata as it reads. + /// + /// + /// + /// If everything succeeds, then the method returns true. If anything fails - + /// for example if an incorrect signature or CRC is found, indicating a + /// corrupt file, the the method returns false. This method also returns + /// false for a file that does not exist. + /// + /// + /// + /// If is true, as part of its check, this + /// method reads in the content for each entry, expands it, and checks CRCs. + /// This provides an additional check beyond verifying the zip header and + /// directory data. + /// + /// + /// + /// If is true, and if any of the zip entries + /// are protected with a password, this method will return false. If you want + /// to verify a ZipFile that has entries which are protected with a + /// password, you will need to do that manually. + /// + /// + /// + /// + /// The zip file to check. + /// true if the caller wants to extract each entry. + /// true if the file contains a valid zip file. + public static bool IsZipFile(string fileName, bool testExtract) + { + bool result = false; + try + { + if (!File.Exists(fileName)) return false; + + using (var s = File.Open(fileName, FileMode.Open, FileAccess.Read, FileShare.ReadWrite)) + { + result = IsZipFile(s, testExtract); + } + } + catch (IOException) { } + catch (ZipException) { } + return result; + } + + + /// + /// Checks a stream to see if it contains a valid zip archive. + /// + /// + /// + /// + /// This method reads the zip archive contained in the specified stream, verifying + /// the ZIP metadata as it reads. If testExtract is true, this method also extracts + /// each entry in the archive, dumping all the bits into . + /// + /// + /// + /// If everything succeeds, then the method returns true. If anything fails - + /// for example if an incorrect signature or CRC is found, indicating a corrupt + /// file, the the method returns false. This method also returns false for a + /// file that does not exist. + /// + /// + /// + /// If testExtract is true, this method reads in the content for each + /// entry, expands it, and checks CRCs. This provides an additional check + /// beyond verifying the zip header data. + /// + /// + /// + /// If testExtract is true, and if any of the zip entries are protected + /// with a password, this method will return false. If you want to verify a + /// ZipFile that has entries which are protected with a password, you will need + /// to do that manually. + /// + /// + /// + /// + /// + /// The stream to check. + /// true if the caller wants to extract each entry. + /// true if the stream contains a valid zip archive. + public static bool IsZipFile(Stream stream, bool testExtract) + { + if (stream == null) + throw new ArgumentNullException("stream"); + + bool result = false; + try + { + if (!stream.CanRead) return false; + + var bitBucket = Stream.Null; + + using (ZipFile zip1 = ZipFile.Read(stream, null, null, null)) + { + if (testExtract) + { + foreach (var e in zip1) + { + if (!e.IsDirectory) + { + e.Extract(bitBucket); + } + } + } + } + result = true; + } + catch (IOException) { } + catch (ZipException) { } + return result; + } + + + + + } + +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Save.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Save.cs new file mode 100644 index 00000000..ddfaee49 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Save.cs @@ -0,0 +1,964 @@ +// ZipFile.Save.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-August-05 13:31:23> +// +// ------------------------------------------------------------------ +// +// This module defines the methods for Save operations on zip files. +// +// ------------------------------------------------------------------ +// + + +using System; +using System.IO; +using System.Collections.Generic; + +namespace Ionic.Zip +{ + + public partial class ZipFile + { + + /// + /// Delete file with retry on UnauthorizedAccessException. + /// + /// + /// + /// + /// When calling File.Delete() on a file that has been "recently" + /// created, the call sometimes fails with + /// UnauthorizedAccessException. This method simply retries the Delete 3 + /// times with a sleep between tries. + /// + /// + /// + /// the name of the file to be deleted + private void DeleteFileWithRetry(string filename) + { + bool done = false; + int nRetries = 3; + for (int i=0; i < nRetries && !done; i++) + { + try + { + File.Delete(filename); + done = true; + } + catch (System.UnauthorizedAccessException) + { + Console.WriteLine("************************************************** Retry delete."); + System.Threading.Thread.Sleep(200+i*200); + } + } + } + + + /// + /// Saves the Zip archive to a file, specified by the Name property of the + /// ZipFile. + /// + /// + /// + /// + /// The ZipFile instance is written to storage, typically a zip file + /// in a filesystem, only when the caller calls Save. In the typical + /// case, the Save operation writes the zip content to a temporary file, and + /// then renames the temporary file to the desired name. If necessary, this + /// method will delete a pre-existing file before the rename. + /// + /// + /// + /// The property is specified either explicitly, + /// or implicitly using one of the parameterized ZipFile constructors. For + /// COM Automation clients, the Name property must be set explicitly, + /// because COM Automation clients cannot call parameterized constructors. + /// + /// + /// + /// When using a filesystem file for the Zip output, it is possible to call + /// Save multiple times on the ZipFile instance. With each + /// call the zip content is re-written to the same output file. + /// + /// + /// + /// Data for entries that have been added to the ZipFile instance is + /// written to the output when the Save method is called. This means + /// that the input streams for those entries must be available at the time + /// the application calls Save. If, for example, the application + /// adds entries with AddEntry using a dynamically-allocated + /// MemoryStream, the memory stream must not have been disposed + /// before the call to Save. See the property for more discussion of the + /// availability requirements of the input stream for an entry, and an + /// approach for providing just-in-time stream lifecycle management. + /// + /// + /// + /// + /// + /// + /// + /// Thrown if you haven't specified a location or stream for saving the zip, + /// either in the constructor or by setting the Name property, or if you try + /// to save a regular zip archive to a filename with a .exe extension. + /// + /// + /// + /// Thrown if is non-zero, and the number + /// of segments that would be generated for the spanned zip file during the + /// save operation exceeds 99. If this happens, you need to increase the + /// segment size. + /// + /// + public void Save() + { + try + { + bool thisSaveUsedZip64 = false; + _saveOperationCanceled = false; + _numberOfSegmentsForMostRecentSave = 0; + OnSaveStarted(); + + if (WriteStream == null) + throw new BadStateException("You haven't specified where to save the zip."); + + if (_name != null && _name.EndsWith(".exe") && !_SavingSfx) + throw new BadStateException("You specified an EXE for a plain zip file."); + + // check if modified, before saving. + if (!_contentsChanged) + { + OnSaveCompleted(); + if (Verbose) StatusMessageTextWriter.WriteLine("No save is necessary...."); + return; + } + + Reset(true); + + if (Verbose) StatusMessageTextWriter.WriteLine("saving...."); + + // validate the number of entries + if (_entries.Count >= 0xFFFF && _zip64 == Zip64Option.Never) + throw new ZipException("The number of entries is 65535 or greater. Consider setting the UseZip64WhenSaving property on the ZipFile instance."); + + + // write an entry in the zip for each file + int n = 0; + // workitem 9831 + ICollection c = (SortEntriesBeforeSaving) ? EntriesSorted : Entries; + foreach (ZipEntry e in c) // _entries.Values + { + OnSaveEntry(n, e, true); + e.Write(WriteStream); + if (_saveOperationCanceled) + break; + + n++; + OnSaveEntry(n, e, false); + if (_saveOperationCanceled) + break; + + // Some entries can be skipped during the save. + if (e.IncludedInMostRecentSave) + thisSaveUsedZip64 |= e.OutputUsedZip64.Value; + } + + + + if (_saveOperationCanceled) + return; + + var zss = WriteStream as ZipSegmentedStream; + + _numberOfSegmentsForMostRecentSave = (zss!=null) + ? zss.CurrentSegment + : 1; + + bool directoryNeededZip64 = + ZipOutput.WriteCentralDirectoryStructure + (WriteStream, + c, + _numberOfSegmentsForMostRecentSave, + _zip64, + Comment, + new ZipContainer(this)); + + OnSaveEvent(ZipProgressEventType.Saving_AfterSaveTempArchive); + + _hasBeenSaved = true; + _contentsChanged = false; + + thisSaveUsedZip64 |= directoryNeededZip64; + _OutputUsesZip64 = new Nullable(thisSaveUsedZip64); + + + // do the rename as necessary + if (_name != null && + (_temporaryFileName!=null || zss != null)) + { + // _temporaryFileName may remain null if we are writing to a stream. + // only close the stream if there is a file behind it. +#if NETCF + WriteStream.Close(); +#else + WriteStream.Dispose(); +#endif + if (_saveOperationCanceled) + return; + + if (_fileAlreadyExists && this._readstream != null) + { + // This means we opened and read a zip file. + // If we are now saving to the same file, we need to close the + // orig file, first. + this._readstream.Close(); + this._readstream = null; + // the archiveStream for each entry needs to be null + foreach (var e in c) + { + var zss1 = e._archiveStream as ZipSegmentedStream; + if (zss1 != null) +#if NETCF + zss1.Close(); +#else + zss1.Dispose(); +#endif + e._archiveStream = null; + } + } + + string tmpName = null; + if (File.Exists(_name)) + { + // the steps: + // + // 1. Delete tmpName + // 2. move existing zip to tmpName + // 3. rename (File.Move) working file to name of existing zip + // 4. delete tmpName + // + // This series of steps avoids the exception, + // System.IO.IOException: + // "Cannot create a file when that file already exists." + // + // Cannot just call File.Replace() here because + // there is a possibility that the TEMP volume is different + // that the volume for the final file (c:\ vs d:\). + // So we need to do a Delete+Move pair. + // + // But, when doing the delete, Windows allows a process to + // delete the file, even though it is held open by, say, a + // virus scanner. It gets internally marked as "delete + // pending". The file does not actually get removed from the + // file system, it is still there after the File.Delete + // call. + // + // Therefore, we need to move the existing zip, which may be + // held open, to some other name. Then rename our working + // file to the desired name, then delete (possibly delete + // pending) the "other name". + // + // Ideally this would be transactional. It's possible that the + // delete succeeds and the move fails. Lacking transactions, if + // this kind of failure happens, we're hosed, and this logic will + // throw on the next File.Move(). + // + //File.Delete(_name); + // workitem 10447 +#if NETCF || SILVERLIGHT + tmpName = _name + "." + SharedUtilities.GenerateRandomStringImpl(8,0) + ".tmp"; +#else + tmpName = _name + "." + Path.GetRandomFileName(); +#endif + if (File.Exists(tmpName)) + DeleteFileWithRetry(tmpName); + File.Move(_name, tmpName); + } + + OnSaveEvent(ZipProgressEventType.Saving_BeforeRenameTempArchive); + File.Move((zss != null) ? zss.CurrentTempName : _temporaryFileName, + _name); + + OnSaveEvent(ZipProgressEventType.Saving_AfterRenameTempArchive); + + if (tmpName != null) + { + try + { + // not critical + if (File.Exists(tmpName)) + File.Delete(tmpName); + } + catch + { + // don't care about exceptions here. + } + + } + _fileAlreadyExists = true; + } + + NotifyEntriesSaveComplete(c); + OnSaveCompleted(); + _JustSaved = true; + } + + // workitem 5043 + finally + { + CleanupAfterSaveOperation(); + } + + return; + } + + + + private static void NotifyEntriesSaveComplete(ICollection c) + { + foreach (ZipEntry e in c) + { + e.NotifySaveComplete(); + } + } + + + private void RemoveTempFile() + { + try + { + if (File.Exists(_temporaryFileName)) + { + File.Delete(_temporaryFileName); + } + } + catch (IOException ex1) + { + if (Verbose) + StatusMessageTextWriter.WriteLine("ZipFile::Save: could not delete temp file: {0}.", ex1.Message); + } + } + + + private void CleanupAfterSaveOperation() + { + if (_name != null) + { + // close the stream if there is a file behind it. + if (_writestream != null) + { + try + { + // workitem 7704 +#if NETCF + _writestream.Close(); +#else + _writestream.Dispose(); +#endif + } + catch (System.IO.IOException) { } + } + _writestream = null; + + if (_temporaryFileName != null) + { + RemoveTempFile(); + _temporaryFileName = null; + } + } + } + + + /// + /// Save the file to a new zipfile, with the given name. + /// + /// + /// + /// + /// This method allows the application to explicitly specify the name of the zip + /// file when saving. Use this when creating a new zip file, or when + /// updating a zip archive. + /// + /// + /// + /// An application can also save a zip archive in several places by calling this + /// method multiple times in succession, with different filenames. + /// + /// + /// + /// The ZipFile instance is written to storage, typically a zip file in a + /// filesystem, only when the caller calls Save. The Save operation writes + /// the zip content to a temporary file, and then renames the temporary file + /// to the desired name. If necessary, this method will delete a pre-existing file + /// before the rename. + /// + /// + /// + /// + /// + /// Thrown if you specify a directory for the filename. + /// + /// + /// + /// The name of the zip archive to save to. Existing files will + /// be overwritten with great prejudice. + /// + /// + /// + /// This example shows how to create and Save a zip file. + /// + /// using (ZipFile zip = new ZipFile()) + /// { + /// zip.AddDirectory(@"c:\reports\January"); + /// zip.Save("January.zip"); + /// } + /// + /// + /// + /// Using zip As New ZipFile() + /// zip.AddDirectory("c:\reports\January") + /// zip.Save("January.zip") + /// End Using + /// + /// + /// + /// + /// + /// This example shows how to update a zip file. + /// + /// using (ZipFile zip = ZipFile.Read("ExistingArchive.zip")) + /// { + /// zip.AddFile("NewData.csv"); + /// zip.Save("UpdatedArchive.zip"); + /// } + /// + /// + /// + /// Using zip As ZipFile = ZipFile.Read("ExistingArchive.zip") + /// zip.AddFile("NewData.csv") + /// zip.Save("UpdatedArchive.zip") + /// End Using + /// + /// + /// + public void Save(String fileName) + { + // Check for the case where we are re-saving a zip archive + // that was originally instantiated with a stream. In that case, + // the _name will be null. If so, we set _writestream to null, + // which insures that we'll cons up a new WriteStream (with a filesystem + // file backing it) in the Save() method. + if (_name == null) + _writestream = null; + + else _readName = _name; // workitem 13915 + + _name = fileName; + if (Directory.Exists(_name)) + throw new ZipException("Bad Directory", new System.ArgumentException("That name specifies an existing directory. Please specify a filename.", "fileName")); + _contentsChanged = true; + _fileAlreadyExists = File.Exists(_name); + Save(); + } + + + /// + /// Save the zip archive to the specified stream. + /// + /// + /// + /// + /// The ZipFile instance is written to storage - typically a zip file + /// in a filesystem, but using this overload, the storage can be anything + /// accessible via a writable stream - only when the caller calls Save. + /// + /// + /// + /// Use this method to save the zip content to a stream directly. A common + /// scenario is an ASP.NET application that dynamically generates a zip file + /// and allows the browser to download it. The application can call + /// Save(Response.OutputStream) to write a zipfile directly to the + /// output stream, without creating a zip file on the disk on the ASP.NET + /// server. + /// + /// + /// + /// Be careful when saving a file to a non-seekable stream, including + /// Response.OutputStream. When DotNetZip writes to a non-seekable + /// stream, the zip archive is formatted in such a way that may not be + /// compatible with all zip tools on all platforms. It's a perfectly legal + /// and compliant zip file, but some people have reported problems opening + /// files produced this way using the Mac OS archive utility. + /// + /// + /// + /// + /// + /// + /// This example saves the zipfile content into a MemoryStream, and + /// then gets the array of bytes from that MemoryStream. + /// + /// + /// using (var zip = new Ionic.Zip.ZipFile()) + /// { + /// zip.CompressionLevel= Ionic.Zlib.CompressionLevel.BestCompression; + /// zip.Password = "VerySecret."; + /// zip.Encryption = EncryptionAlgorithm.WinZipAes128; + /// zip.AddFile(sourceFileName); + /// MemoryStream output = new MemoryStream(); + /// zip.Save(output); + /// + /// byte[] zipbytes = output.ToArray(); + /// } + /// + /// + /// + /// + /// + /// This example shows a pitfall you should avoid. DO NOT read + /// from a stream, then try to save to the same stream. DO + /// NOT DO THIS: + /// + /// + /// + /// using (var fs = new FileSteeam(filename, FileMode.Open)) + /// { + /// using (var zip = Ionic.Zip.ZipFile.Read(inputStream)) + /// { + /// zip.AddEntry("Name1.txt", "this is the content"); + /// zip.Save(inputStream); // NO NO NO!! + /// } + /// } + /// + /// + /// + /// Better like this: + /// + /// + /// + /// using (var zip = Ionic.Zip.ZipFile.Read(filename)) + /// { + /// zip.AddEntry("Name1.txt", "this is the content"); + /// zip.Save(); // YES! + /// } + /// + /// + /// + /// + /// + /// The System.IO.Stream to write to. It must be + /// writable. If you created the ZipFile instanct by calling + /// ZipFile.Read(), this stream must not be the same stream + /// you passed to ZipFile.Read(). + /// + public void Save(Stream outputStream) + { + if (outputStream == null) + throw new ArgumentNullException("outputStream"); + if (!outputStream.CanWrite) + throw new ArgumentException("Must be a writable stream.", "outputStream"); + + // if we had a filename to save to, we are now obliterating it. + _name = null; + + _writestream = new CountingStream(outputStream); + + _contentsChanged = true; + _fileAlreadyExists = false; + Save(); + } + + + } + + + + internal static class ZipOutput + { + public static bool WriteCentralDirectoryStructure(Stream s, + ICollection entries, + uint numSegments, + Zip64Option zip64, + String comment, + ZipContainer container) + { + var zss = s as ZipSegmentedStream; + if (zss != null) + zss.ContiguousWrite = true; + + // write to a memory stream in order to keep the + // CDR contiguous + Int64 aLength = 0; + using (var ms = new MemoryStream()) + { + foreach (ZipEntry e in entries) + { + if (e.IncludedInMostRecentSave) + { + // this writes a ZipDirEntry corresponding to the ZipEntry + e.WriteCentralDirectoryEntry(ms); + } + } + var a = ms.ToArray(); + s.Write(a, 0, a.Length); + aLength = a.Length; + } + + + // We need to keep track of the start and + // Finish of the Central Directory Structure. + + // Cannot always use WriteStream.Length or Position; some streams do + // not support these. (eg, ASP.NET Response.OutputStream) In those + // cases we have a CountingStream. + + // Also, we cannot just set Start as s.Position bfore the write, and Finish + // as s.Position after the write. In a split zip, the write may actually + // flip to the next segment. In that case, Start will be zero. But we + // don't know that til after we know the size of the thing to write. So the + // answer is to compute the directory, then ask the ZipSegmentedStream which + // segment that directory would fall in, it it were written. Then, include + // that data into the directory, and finally, write the directory to the + // output stream. + + var output = s as CountingStream; + long Finish = (output != null) ? output.ComputedPosition : s.Position; // BytesWritten + long Start = Finish - aLength; + + // need to know which segment the EOCD record starts in + UInt32 startSegment = (zss != null) + ? zss.CurrentSegment + : 0; + + Int64 SizeOfCentralDirectory = Finish - Start; + + int countOfEntries = CountEntries(entries); + + bool needZip64CentralDirectory = + zip64 == Zip64Option.Always || + countOfEntries >= 0xFFFF || + SizeOfCentralDirectory > 0xFFFFFFFF || + Start > 0xFFFFFFFF; + + byte[] a2 = null; + + // emit ZIP64 extensions as required + if (needZip64CentralDirectory) + { + if (zip64 == Zip64Option.Never) + { +#if NETCF + throw new ZipException("The archive requires a ZIP64 Central Directory. Consider enabling ZIP64 extensions."); +#else + System.Diagnostics.StackFrame sf = new System.Diagnostics.StackFrame(1); + if (sf.GetMethod().DeclaringType == typeof(ZipFile)) + throw new ZipException("The archive requires a ZIP64 Central Directory. Consider setting the ZipFile.UseZip64WhenSaving property."); + else + throw new ZipException("The archive requires a ZIP64 Central Directory. Consider setting the ZipOutputStream.EnableZip64 property."); +#endif + + } + + var a = GenZip64EndOfCentralDirectory(Start, Finish, countOfEntries, numSegments); + a2 = GenCentralDirectoryFooter(Start, Finish, zip64, countOfEntries, comment, container); + if (startSegment != 0) + { + UInt32 thisSegment = zss.ComputeSegment(a.Length + a2.Length); + int i = 16; + // number of this disk + Array.Copy(BitConverter.GetBytes(thisSegment), 0, a, i, 4); + i += 4; + // number of the disk with the start of the central directory + //Array.Copy(BitConverter.GetBytes(startSegment), 0, a, i, 4); + Array.Copy(BitConverter.GetBytes(thisSegment), 0, a, i, 4); + + i = 60; + // offset 60 + // number of the disk with the start of the zip64 eocd + Array.Copy(BitConverter.GetBytes(thisSegment), 0, a, i, 4); + i += 4; + i += 8; + + // offset 72 + // total number of disks + Array.Copy(BitConverter.GetBytes(thisSegment), 0, a, i, 4); + } + s.Write(a, 0, a.Length); + } + else + a2 = GenCentralDirectoryFooter(Start, Finish, zip64, countOfEntries, comment, container); + + + // now, the regular footer + if (startSegment != 0) + { + // The assumption is the central directory is never split across + // segment boundaries. + + UInt16 thisSegment = (UInt16) zss.ComputeSegment(a2.Length); + int i = 4; + // number of this disk + Array.Copy(BitConverter.GetBytes(thisSegment), 0, a2, i, 2); + i += 2; + // number of the disk with the start of the central directory + //Array.Copy(BitConverter.GetBytes((UInt16)startSegment), 0, a2, i, 2); + Array.Copy(BitConverter.GetBytes(thisSegment), 0, a2, i, 2); + i += 2; + } + + s.Write(a2, 0, a2.Length); + + // reset the contiguous write property if necessary + if (zss != null) + zss.ContiguousWrite = false; + + return needZip64CentralDirectory; + } + + + private static System.Text.Encoding GetEncoding(ZipContainer container, string t) + { + switch (container.AlternateEncodingUsage) + { + case ZipOption.Always: + return container.AlternateEncoding; + case ZipOption.Never: + return container.DefaultEncoding; + } + + // AsNecessary is in force + var e = container.DefaultEncoding; + if (t == null) return e; + + var bytes = e.GetBytes(t); + var t2 = e.GetString(bytes,0,bytes.Length); + if (t2.Equals(t)) return e; + return container.AlternateEncoding; + } + + + + private static byte[] GenCentralDirectoryFooter(long StartOfCentralDirectory, + long EndOfCentralDirectory, + Zip64Option zip64, + int entryCount, + string comment, + ZipContainer container) + { + System.Text.Encoding encoding = GetEncoding(container, comment); + int j = 0; + int bufferLength = 22; + byte[] block = null; + Int16 commentLength = 0; + if ((comment != null) && (comment.Length != 0)) + { + block = encoding.GetBytes(comment); + commentLength = (Int16)block.Length; + } + bufferLength += commentLength; + byte[] bytes = new byte[bufferLength]; + + int i = 0; + // signature + byte[] sig = BitConverter.GetBytes(ZipConstants.EndOfCentralDirectorySignature); + Array.Copy(sig, 0, bytes, i, 4); + i+=4; + + // number of this disk + // (this number may change later) + bytes[i++] = 0; + bytes[i++] = 0; + + // number of the disk with the start of the central directory + // (this number may change later) + bytes[i++] = 0; + bytes[i++] = 0; + + // handle ZIP64 extensions for the end-of-central-directory + if (entryCount >= 0xFFFF || zip64 == Zip64Option.Always) + { + // the ZIP64 version. + for (j = 0; j < 4; j++) + bytes[i++] = 0xFF; + } + else + { + // the standard version. + // total number of entries in the central dir on this disk + bytes[i++] = (byte)(entryCount & 0x00FF); + bytes[i++] = (byte)((entryCount & 0xFF00) >> 8); + + // total number of entries in the central directory + bytes[i++] = (byte)(entryCount & 0x00FF); + bytes[i++] = (byte)((entryCount & 0xFF00) >> 8); + } + + // size of the central directory + Int64 SizeOfCentralDirectory = EndOfCentralDirectory - StartOfCentralDirectory; + + if (SizeOfCentralDirectory >= 0xFFFFFFFF || StartOfCentralDirectory >= 0xFFFFFFFF) + { + // The actual data is in the ZIP64 central directory structure + for (j = 0; j < 8; j++) + bytes[i++] = 0xFF; + } + else + { + // size of the central directory (we just get the low 4 bytes) + bytes[i++] = (byte)(SizeOfCentralDirectory & 0x000000FF); + bytes[i++] = (byte)((SizeOfCentralDirectory & 0x0000FF00) >> 8); + bytes[i++] = (byte)((SizeOfCentralDirectory & 0x00FF0000) >> 16); + bytes[i++] = (byte)((SizeOfCentralDirectory & 0xFF000000) >> 24); + + // offset of the start of the central directory (we just get the low 4 bytes) + bytes[i++] = (byte)(StartOfCentralDirectory & 0x000000FF); + bytes[i++] = (byte)((StartOfCentralDirectory & 0x0000FF00) >> 8); + bytes[i++] = (byte)((StartOfCentralDirectory & 0x00FF0000) >> 16); + bytes[i++] = (byte)((StartOfCentralDirectory & 0xFF000000) >> 24); + } + + + // zip archive comment + if ((comment == null) || (comment.Length == 0)) + { + // no comment! + bytes[i++] = (byte)0; + bytes[i++] = (byte)0; + } + else + { + // the size of our buffer defines the max length of the comment we can write + if (commentLength + i + 2 > bytes.Length) commentLength = (Int16)(bytes.Length - i - 2); + bytes[i++] = (byte)(commentLength & 0x00FF); + bytes[i++] = (byte)((commentLength & 0xFF00) >> 8); + + if (commentLength != 0) + { + // now actually write the comment itself into the byte buffer + for (j = 0; (j < commentLength) && (i + j < bytes.Length); j++) + { + bytes[i + j] = block[j]; + } + i += j; + } + } + + // s.Write(bytes, 0, i); + return bytes; + } + + + + private static byte[] GenZip64EndOfCentralDirectory(long StartOfCentralDirectory, + long EndOfCentralDirectory, + int entryCount, + uint numSegments) + { + const int bufferLength = 12 + 44 + 20; + + byte[] bytes = new byte[bufferLength]; + + int i = 0; + // signature + byte[] sig = BitConverter.GetBytes(ZipConstants.Zip64EndOfCentralDirectoryRecordSignature); + Array.Copy(sig, 0, bytes, i, 4); + i+=4; + + // There is a possibility to include "Extensible" data in the zip64 + // end-of-central-dir record. I cannot figure out what it might be used to + // store, so the size of this record is always fixed. Maybe it is used for + // strong encryption data? That is for another day. + long DataSize = 44; + Array.Copy(BitConverter.GetBytes(DataSize), 0, bytes, i, 8); + i += 8; + + // offset 12 + // VersionMadeBy = 45; + bytes[i++] = 45; + bytes[i++] = 0x00; + + // VersionNeededToExtract = 45; + bytes[i++] = 45; + bytes[i++] = 0x00; + + // offset 16 + // number of the disk, and the disk with the start of the central dir. + // (this may change later) + for (int j = 0; j < 8; j++) + bytes[i++] = 0x00; + + // offset 24 + long numberOfEntries = entryCount; + Array.Copy(BitConverter.GetBytes(numberOfEntries), 0, bytes, i, 8); + i += 8; + Array.Copy(BitConverter.GetBytes(numberOfEntries), 0, bytes, i, 8); + i += 8; + + // offset 40 + Int64 SizeofCentraldirectory = EndOfCentralDirectory - StartOfCentralDirectory; + Array.Copy(BitConverter.GetBytes(SizeofCentraldirectory), 0, bytes, i, 8); + i += 8; + Array.Copy(BitConverter.GetBytes(StartOfCentralDirectory), 0, bytes, i, 8); + i += 8; + + // offset 56 + // now, the locator + // signature + sig = BitConverter.GetBytes(ZipConstants.Zip64EndOfCentralDirectoryLocatorSignature); + Array.Copy(sig, 0, bytes, i, 4); + i+=4; + + // offset 60 + // number of the disk with the start of the zip64 eocd + // (this will change later) (it will?) + uint x2 = (numSegments==0)?0:(uint)(numSegments-1); + Array.Copy(BitConverter.GetBytes(x2), 0, bytes, i, 4); + i+=4; + + // offset 64 + // relative offset of the zip64 eocd + Array.Copy(BitConverter.GetBytes(EndOfCentralDirectory), 0, bytes, i, 8); + i += 8; + + // offset 72 + // total number of disks + // (this will change later) + Array.Copy(BitConverter.GetBytes(numSegments), 0, bytes, i, 4); + i+=4; + + return bytes; + } + + + + private static int CountEntries(ICollection _entries) + { + // Cannot just emit _entries.Count, because some of the entries + // may have been skipped. + int count = 0; + foreach (var entry in _entries) + if (entry.IncludedInMostRecentSave) count++; + return count; + } + + + + + } +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.SaveSelfExtractor.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.SaveSelfExtractor.cs new file mode 100644 index 00000000..98e92c7b --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.SaveSelfExtractor.cs @@ -0,0 +1,1100 @@ +// ZipFile.saveSelfExtractor.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2008-2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-August-03 16:42:15> +// +// ------------------------------------------------------------------ +// +// This is a the source module that implements the stuff for saving to a +// self-extracting Zip archive. +// +// ZipFile is set up as a "partial class" - defined in multiple .cs source modules. +// This is one of the source modules for the ZipFile class. +// +// Here's the design: The self-extracting zip file is just a regular managed EXE +// file, with embedded resources. The managed code logic instantiates a ZipFile, and +// then extracts each entry. The embedded resources include the zip archive content, +// as well as the Zip library itself. The latter is required so that self-extracting +// can work on any machine, whether or not it has the DotNetZip library installed on +// it. +// +// What we need to do is create the animal I just described, within a method on the +// ZipFile class. This source module provides that capability. The method is +// SaveSelfExtractor(). +// +// The way the method works: it uses the programmatic interface to the csc.exe +// compiler, Microsoft.CSharp.CSharpCodeProvider, to compile "boilerplate" +// extraction logic into a new assembly. As part of that compile, we embed within +// that assembly the zip archive itself, as well as the Zip library. +// +// Therefore we need to first save to a temporary zip file, then produce the exe. +// +// There are a few twists. +// +// The Visual Studio Project structure is a little weird. There are code files +// that ARE NOT compiled during a normal build of the VS Solution. They are +// marked as embedded resources. These are the various "boilerplate" modules that +// are used in the self-extractor. These modules are: WinFormsSelfExtractorStub.cs +// WinFormsSelfExtractorStub.Designer.cs CommandLineSelfExtractorStub.cs +// PasswordDialog.cs PasswordDialog.Designer.cs +// +// At design time, if you want to modify the way the GUI looks, you have to +// mark those modules to have a "compile" build action. Then tweak em, test, +// etc. Then again mark them as "Embedded resource". +// +// ------------------------------------------------------------------ + +using System; +using System.Reflection; +using System.IO; +using System.Collections.Generic; + + +namespace Ionic.Zip +{ +#if !NO_SFX + /// + /// An enum that provides the different self-extractor flavors + /// + public enum SelfExtractorFlavor + { + /// + /// A self-extracting zip archive that runs from the console or + /// command line. + /// + ConsoleApplication = 0, + + /// + /// A self-extracting zip archive that presents a graphical user + /// interface when it is executed. + /// + WinFormsApplication, + } + + /// + /// The options for generating a self-extracting archive. + /// + public class SelfExtractorSaveOptions + { + /// + /// The type of SFX to create. + /// + public SelfExtractorFlavor Flavor + { + get; + set; + } + + /// + /// The command to run after extraction. + /// + /// + /// + /// + /// This is optional. Leave it empty (null in C# or Nothing in + /// VB) to run no command after extraction. + /// + /// + /// + /// If it is non-empty, the SFX will execute the command specified in this + /// string on the user's machine, and using the extract directory as the + /// working directory for the process, after unpacking the archive. The + /// program to execute can include a path, if you like. If you want to execute + /// a program that accepts arguments, specify the program name, followed by a + /// space, and then the arguments for the program, each separated by a space, + /// just as you would on a normal command line. Example: program.exe arg1 + /// arg2. The string prior to the first space will be taken as the + /// program name, and the string following the first space specifies the + /// arguments to the program. + /// + /// + /// + /// If you want to execute a program that has a space in the name or path of + /// the file, surround the program name in double-quotes. The first character + /// of the command line should be a double-quote character, and there must be + /// a matching double-quote following the end of the program file name. Any + /// optional arguments to the program follow that, separated by + /// spaces. Example: "c:\project files\program name.exe" arg1 arg2. + /// + /// + /// + /// If the flavor of the SFX is SelfExtractorFlavor.ConsoleApplication, + /// then the SFX starts a new process, using this string as the post-extract + /// command line. The SFX waits for the process to exit. The exit code of + /// the post-extract command line is returned as the exit code of the + /// command-line self-extractor exe. A non-zero exit code is typically used to + /// indicated a failure by the program. In the case of an SFX, a non-zero exit + /// code may indicate a failure during extraction, OR, it may indicate a + /// failure of the run-after-extract program if specified, OR, it may indicate + /// the run-after-extract program could not be fuond. There is no way to + /// distinguish these conditions from the calling shell, aside from parsing + /// the output of the SFX. If you have Quiet set to true, you may not + /// see error messages, if a problem occurs. + /// + /// + /// + /// If the flavor of the SFX is + /// SelfExtractorFlavor.WinFormsApplication, then the SFX starts a new + /// process, using this string as the post-extract command line, and using the + /// extract directory as the working directory for the process. The SFX does + /// not wait for the command to complete, and does not check the exit code of + /// the program. If the run-after-extract program cannot be fuond, a message + /// box is displayed indicating that fact. + /// + /// + /// + /// You can specify environment variables within this string, with a format like + /// %NAME%. The value of these variables will be expanded at the time + /// the SFX is run. Example: %WINDIR%\system32\xcopy.exe may expand at + /// runtime to c:\Windows\System32\xcopy.exe. + /// + /// + /// + /// By combining this with the RemoveUnpackedFilesAfterExecute + /// flag, you can create an SFX that extracts itself, runs a file that + /// was extracted, then deletes all the files that were extracted. If + /// you want it to run "invisibly" then set Flavor to + /// SelfExtractorFlavor.ConsoleApplication, and set Quiet + /// to true. The user running such an EXE will see a console window + /// appear, then disappear quickly. You may also want to specify the + /// default extract location, with DefaultExtractDirectory. + /// + /// + /// + /// If you set Flavor to + /// SelfExtractorFlavor.WinFormsApplication, and set Quiet to + /// true, then a GUI with progressbars is displayed, but it is + /// "non-interactive" - it accepts no input from the user. Instead the SFX + /// just automatically unpacks and exits. + /// + /// + /// + public String PostExtractCommandLine + { + get; + set; + } + + /// + /// The default extract directory the user will see when + /// running the self-extracting archive. + /// + /// + /// + /// + /// Passing null (or Nothing in VB) here will cause the Self Extractor to use + /// the the user's personal directory () for the default extract + /// location. + /// + /// + /// + /// This is only a default location. The actual extract location will be + /// settable on the command line when the SFX is executed. + /// + /// + /// + /// You can specify environment variables within this string, + /// with %NAME%. The value of these variables will be + /// expanded at the time the SFX is run. Example: + /// %USERPROFILE%\Documents\unpack may expand at runtime to + /// c:\users\melvin\Documents\unpack. + /// + /// + public String DefaultExtractDirectory + { + get; + set; + } + + /// + /// The name of an .ico file in the filesystem to use for the application icon + /// for the generated SFX. + /// + /// + /// + /// + /// Normally, DotNetZip will embed an "zipped folder" icon into the generated + /// SFX. If you prefer to use a different icon, you can specify it here. It + /// should be a .ico file. This file is passed as the /win32icon + /// option to the csc.exe compiler when constructing the SFX file. + /// + /// + /// + public string IconFile + { + get; + set; + } + + /// + /// Whether the ConsoleApplication SFX will be quiet during extraction. + /// + /// + /// + /// + /// This option affects the way the generated SFX runs. By default it is + /// false. When you set it to true,... + /// + /// + /// + /// + /// Flavor + /// Behavior + /// + /// + /// + /// ConsoleApplication + /// no messages will be emitted during successful + /// operation. Double-clicking the SFX in Windows + /// Explorer or as an attachment in an email will cause a console + /// window to appear briefly, before it disappears. If you run the + /// ConsoleApplication SFX from the cmd.exe prompt, it runs as a + /// normal console app; by default, because it is quiet, it displays + /// no messages to the console. If you pass the -v+ command line + /// argument to the Console SFX when you run it, you will get verbose + /// messages to the console. + /// + /// + /// + /// + /// WinFormsApplication + /// the SFX extracts automatically when the application + /// is launched, with no additional user input. + /// + /// + /// + /// + /// + /// + /// When you set it to false,... + /// + /// + /// + /// + /// Flavor + /// Behavior + /// + /// + /// + /// ConsoleApplication + /// the extractor will emit a + /// message to the console for each entry extracted. + /// + /// When double-clicking to launch the SFX, the console window will + /// remain, and the SFX will emit a message for each file as it + /// extracts. The messages fly by quickly, they won't be easily + /// readable, unless the extracted files are fairly large. + /// + /// + /// + /// + /// + /// WinFormsApplication + /// the SFX presents a forms UI and allows the user to select + /// options before extracting. + /// + /// + /// + /// + /// + /// + public bool Quiet + { + get; + set; + } + + + /// + /// Specify what the self-extractor will do when extracting an entry + /// would overwrite an existing file. + /// + /// + /// + /// The default behavvior is to Throw. + /// + /// + public Ionic.Zip.ExtractExistingFileAction ExtractExistingFile + { + get; + set; + } + + + /// + /// Whether to remove the files that have been unpacked, after executing the + /// PostExtractCommandLine. + /// + /// + /// + /// + /// If true, and if there is a + /// PostExtractCommandLine, and if the command runs successfully, + /// then the files that the SFX unpacked will be removed, afterwards. If + /// the command does not complete successfully (non-zero return code), + /// that is interpreted as a failure, and the extracted files will not be + /// removed. + /// + /// + /// + /// Setting this flag, and setting Flavor to + /// SelfExtractorFlavor.ConsoleApplication, and setting Quiet to + /// true, results in an SFX that extracts itself, runs a file that was + /// extracted, then deletes all the files that were extracted, with no + /// intervention by the user. You may also want to specify the default + /// extract location, with DefaultExtractDirectory. + /// + /// + /// + public bool RemoveUnpackedFilesAfterExecute + { + get; + set; + } + + + /// + /// The file version number to embed into the generated EXE. It will show up, for + /// example, during a mouseover in Windows Explorer. + /// + /// + public Version FileVersion + { + get; + set; + } + + /// + /// The product version to embed into the generated EXE. It will show up, for + /// example, during a mouseover in Windows Explorer. + /// + /// + /// + /// You can use any arbitrary string, but a human-readable version number is + /// recommended. For example "v1.2 alpha" or "v4.2 RC2". If you specify nothing, + /// then there is no product version embedded into the EXE. + /// + /// + public String ProductVersion + { + get; + set; + } + + /// + /// The copyright notice, if any, to embed into the generated EXE. + /// + /// + /// + /// It will show up, for example, while viewing properties of the file in + /// Windows Explorer. You can use any arbitrary string, but typically you + /// want something like "Copyright © Dino Chiesa 2011". + /// + /// + public String Copyright + { + get; + set; + } + + + /// + /// The description to embed into the generated EXE. + /// + /// + /// + /// Use any arbitrary string. This text will be displayed during a + /// mouseover in Windows Explorer. If you specify nothing, then the string + /// "DotNetZip SFX Archive" is embedded into the EXE as the description. + /// + /// + public String Description + { + get; + set; + } + + /// + /// The product name to embed into the generated EXE. + /// + /// + /// + /// Use any arbitrary string. This text will be displayed + /// while viewing properties of the EXE file in + /// Windows Explorer. + /// + /// + public String ProductName + { + get; + set; + } + + /// + /// The title to display in the Window of a GUI SFX, while it extracts. + /// + /// + /// + /// + /// By default the title show in the GUI window of a self-extractor + /// is "DotNetZip Self-extractor (http://DotNetZip.codeplex.com/)". + /// You can change that by setting this property before saving the SFX. + /// + /// + /// + /// This property has an effect only when producing a Self-extractor + /// of flavor SelfExtractorFlavor.WinFormsApplication. + /// + /// + /// + public String SfxExeWindowTitle + { + // workitem 12608 + get; + set; + } + + /// + /// Additional options for the csc.exe compiler, when producing the SFX + /// EXE. + /// + /// + public string AdditionalCompilerSwitches + { + get; set; + } + } + + + + + partial class ZipFile + { + class ExtractorSettings + { + public SelfExtractorFlavor Flavor; + public List ReferencedAssemblies; + public List CopyThroughResources; + public List ResourcesToCompile; + } + + + private static ExtractorSettings[] SettingsList = { + new ExtractorSettings() { + Flavor = SelfExtractorFlavor.WinFormsApplication, + ReferencedAssemblies= new List{ + "System.dll", "System.Windows.Forms.dll", "System.Drawing.dll"}, + CopyThroughResources = new List{ + "Ionic.Zip.WinFormsSelfExtractorStub.resources", + "Ionic.Zip.Forms.PasswordDialog.resources", + "Ionic.Zip.Forms.ZipContentsDialog.resources"}, + ResourcesToCompile = new List{ + "WinFormsSelfExtractorStub.cs", + "WinFormsSelfExtractorStub.Designer.cs", // .Designer.cs? + "PasswordDialog.cs", + "PasswordDialog.Designer.cs", //.Designer.cs" + "ZipContentsDialog.cs", + "ZipContentsDialog.Designer.cs", //.Designer.cs" + "FolderBrowserDialogEx.cs", + } + }, + new ExtractorSettings() { + Flavor = SelfExtractorFlavor.ConsoleApplication, + ReferencedAssemblies= new List { "System.dll", }, + CopyThroughResources = null, + ResourcesToCompile = new List{"CommandLineSelfExtractorStub.cs"} + } + }; + + + + //string _defaultExtractLocation; + //string _postExtractCmdLine; + // string _SetDefaultLocationCode = + // "namespace Ionic.Zip { public partial class WinFormsSelfExtractorStub { partial void _SetDefaultExtractLocation() {" + + // " txtExtractDirectory.Text = \"@@VALUE\"; } }}"; + + + + /// + /// Saves the ZipFile instance to a self-extracting zip archive. + /// + /// + /// + /// + /// + /// The generated exe image will execute on any machine that has the .NET + /// Framework 2.0 installed on it. The generated exe image is also a + /// valid ZIP file, readable with DotNetZip or another Zip library or tool + /// such as WinZip. + /// + /// + /// + /// There are two "flavors" of self-extracting archive. The + /// WinFormsApplication version will pop up a GUI and allow the + /// user to select a target directory into which to extract. There's also + /// a checkbox allowing the user to specify to overwrite existing files, + /// and another checkbox to allow the user to request that Explorer be + /// opened to see the extracted files after extraction. The other flavor + /// is ConsoleApplication. A self-extractor generated with that + /// flavor setting will run from the command line. It accepts command-line + /// options to set the overwrite behavior, and to specify the target + /// extraction directory. + /// + /// + /// + /// There are a few temporary files created during the saving to a + /// self-extracting zip. These files are created in the directory pointed + /// to by , which defaults to . These temporary files are + /// removed upon successful completion of this method. + /// + /// + /// + /// When a user runs the WinForms SFX, the user's personal directory (Environment.SpecialFolder.Personal) + /// will be used as the default extract location. If you want to set the + /// default extract location, you should use the other overload of + /// SaveSelfExtractor()/ The user who runs the SFX will have the + /// opportunity to change the extract directory before extracting. When + /// the user runs the Command-Line SFX, the user must explicitly specify + /// the directory to which to extract. The .NET Framework 2.0 is required + /// on the computer when the self-extracting archive is run. + /// + /// + /// + /// NB: This method is not available in the version of DotNetZip build for + /// the .NET Compact Framework, nor in the "Reduced" DotNetZip library. + /// + /// + /// + /// + /// + /// + /// string DirectoryPath = "c:\\Documents\\Project7"; + /// using (ZipFile zip = new ZipFile()) + /// { + /// zip.AddDirectory(DirectoryPath, System.IO.Path.GetFileName(DirectoryPath)); + /// zip.Comment = "This will be embedded into a self-extracting console-based exe"; + /// zip.SaveSelfExtractor("archive.exe", SelfExtractorFlavor.ConsoleApplication); + /// } + /// + /// + /// Dim DirectoryPath As String = "c:\Documents\Project7" + /// Using zip As New ZipFile() + /// zip.AddDirectory(DirectoryPath, System.IO.Path.GetFileName(DirectoryPath)) + /// zip.Comment = "This will be embedded into a self-extracting console-based exe" + /// zip.SaveSelfExtractor("archive.exe", SelfExtractorFlavor.ConsoleApplication) + /// End Using + /// + /// + /// + /// + /// a pathname, possibly fully qualified, to be created. Typically it + /// will end in an .exe extension. + /// + /// Indicates whether a Winforms or Console self-extractor is + /// desired. + public void SaveSelfExtractor(string exeToGenerate, SelfExtractorFlavor flavor) + { + SelfExtractorSaveOptions options = new SelfExtractorSaveOptions(); + options.Flavor = flavor; + SaveSelfExtractor(exeToGenerate, options); + } + + + + /// + /// Saves the ZipFile instance to a self-extracting zip archive, using + /// the specified save options. + /// + /// + /// + /// + /// This method saves a self extracting archive, using the specified save + /// options. These options include the flavor of the SFX, the default extract + /// directory, the icon file, and so on. See the documentation + /// for for more + /// details. + /// + /// + /// + /// The user who runs the SFX will have the opportunity to change the extract + /// directory before extracting. If at the time of extraction, the specified + /// directory does not exist, the SFX will create the directory before + /// extracting the files. + /// + /// + /// + /// + /// + /// This example saves a WinForms-based self-extracting archive EXE that + /// will use c:\ExtractHere as the default extract location. The C# code + /// shows syntax for .NET 3.0, which uses an object initializer for + /// the SelfExtractorOptions object. + /// + /// string DirectoryPath = "c:\\Documents\\Project7"; + /// using (ZipFile zip = new ZipFile()) + /// { + /// zip.AddDirectory(DirectoryPath, System.IO.Path.GetFileName(DirectoryPath)); + /// zip.Comment = "This will be embedded into a self-extracting WinForms-based exe"; + /// var options = new SelfExtractorOptions + /// { + /// Flavor = SelfExtractorFlavor.WinFormsApplication, + /// DefaultExtractDirectory = "%USERPROFILE%\\ExtractHere", + /// PostExtractCommandLine = ExeToRunAfterExtract, + /// SfxExeWindowTitle = "My Custom Window Title", + /// RemoveUnpackedFilesAfterExecute = true + /// }; + /// zip.SaveSelfExtractor("archive.exe", options); + /// } + /// + /// + /// Dim DirectoryPath As String = "c:\Documents\Project7" + /// Using zip As New ZipFile() + /// zip.AddDirectory(DirectoryPath, System.IO.Path.GetFileName(DirectoryPath)) + /// zip.Comment = "This will be embedded into a self-extracting console-based exe" + /// Dim options As New SelfExtractorOptions() + /// options.Flavor = SelfExtractorFlavor.WinFormsApplication + /// options.DefaultExtractDirectory = "%USERPROFILE%\\ExtractHere" + /// options.PostExtractCommandLine = ExeToRunAfterExtract + /// options.SfxExeWindowTitle = "My Custom Window Title" + /// options.RemoveUnpackedFilesAfterExecute = True + /// zip.SaveSelfExtractor("archive.exe", options) + /// End Using + /// + /// + /// + /// The name of the EXE to generate. + /// provides the options for creating the + /// Self-extracting archive. + public void SaveSelfExtractor(string exeToGenerate, SelfExtractorSaveOptions options) + { + // Save an SFX that is both an EXE and a ZIP. + + // Check for the case where we are re-saving a zip archive + // that was originally instantiated with a stream. In that case, + // the _name will be null. If so, we set _writestream to null, + // which insures that we'll cons up a new WriteStream (with a filesystem + // file backing it) in the Save() method. + if (_name == null) + _writestream = null; + + _SavingSfx = true; + _name = exeToGenerate; + if (Directory.Exists(_name)) + throw new ZipException("Bad Directory", new System.ArgumentException("That name specifies an existing directory. Please specify a filename.", "exeToGenerate")); + _contentsChanged = true; + _fileAlreadyExists = File.Exists(_name); + + _SaveSfxStub(exeToGenerate, options); + + Save(); + _SavingSfx = false; + } + + + + + private static void ExtractResourceToFile(Assembly a, string resourceName, string filename) + { + int n = 0; + byte[] bytes = new byte[1024]; + using (Stream instream = a.GetManifestResourceStream(resourceName)) + { + if (instream == null) + throw new ZipException(String.Format("missing resource '{0}'", resourceName)); + + using (FileStream outstream = File.OpenWrite(filename)) + { + do + { + n = instream.Read(bytes, 0, bytes.Length); + outstream.Write(bytes, 0, n); + } while (n > 0); + } + } + } + + + private void _SaveSfxStub(string exeToGenerate, SelfExtractorSaveOptions options) + { + string nameOfIconFile = null; + string stubExe = null; + string unpackedResourceDir = null; + string tmpDir = null; + try + { + if (File.Exists(exeToGenerate)) + { + if (Verbose) StatusMessageTextWriter.WriteLine("The existing file ({0}) will be overwritten.", exeToGenerate); + } + if (!exeToGenerate.EndsWith(".exe")) + { + if (Verbose) StatusMessageTextWriter.WriteLine("Warning: The generated self-extracting file will not have an .exe extension."); + } + + // workitem 10553 + tmpDir = TempFileFolder ?? Path.GetDirectoryName(exeToGenerate); + stubExe = GenerateTempPathname(tmpDir, "exe"); + + // get the Ionic.Zip assembly + Assembly a1 = typeof(ZipFile).Assembly; + + using (var csharp = new Microsoft.CSharp.CSharpCodeProvider()) + { + // The following is a perfect opportunity for a linq query, but + // I cannot use it. The generated SFX needs to run on .NET 2.0, + // and using LINQ would break that. Here's what it would look + // like: + // + // var settings = (from x in SettingsList + // where x.Flavor == flavor + // select x).First(); + + ExtractorSettings settings = null; + foreach (var x in SettingsList) + { + if (x.Flavor == options.Flavor) + { + settings = x; + break; + } + } + + // sanity check; should never happen + if (settings == null) + throw new BadStateException(String.Format("While saving a Self-Extracting Zip, Cannot find that flavor ({0})?", options.Flavor)); + + // This is the list of referenced assemblies. Ionic.Zip is + // needed here. Also if it is the winforms (gui) extractor, we + // need other referenced assemblies, like + // System.Windows.Forms.dll, etc. + var cp = new System.CodeDom.Compiler.CompilerParameters(); + cp.ReferencedAssemblies.Add(a1.Location); + if (settings.ReferencedAssemblies != null) + foreach (string ra in settings.ReferencedAssemblies) + cp.ReferencedAssemblies.Add(ra); + + cp.GenerateInMemory = false; + cp.GenerateExecutable = true; + cp.IncludeDebugInformation = false; + cp.CompilerOptions = ""; + + Assembly a2 = Assembly.GetExecutingAssembly(); + + // Use this to concatenate all the source code resources into a + // single module. + var sb = new System.Text.StringBuilder(); + + // In case there are compiler errors later, we allocate a source + // file name now. If errors are detected, we'll spool the source + // code as well as the errors (in comments) into that filename, + // and throw an exception with the filename. Makes it easier to + // diagnose. This should be rare; most errors happen only + // during devlpmt of DotNetZip itself, but there are rare + // occasions when they occur in other cases. + string sourceFile = GenerateTempPathname(tmpDir, "cs"); + + + // // debugging: enumerate the resources in this assembly + // Console.WriteLine("Resources in this assembly:"); + // foreach (string rsrc in a2.GetManifestResourceNames()) + // { + // Console.WriteLine(rsrc); + // } + // Console.WriteLine(); + + + // all the source code is embedded in the DLL as a zip file. + using (ZipFile zip = ZipFile.Read(a2.GetManifestResourceStream("Ionic.Zip.Resources.ZippedResources.zip"))) + { + // // debugging: enumerate the files in the embedded zip + // Console.WriteLine("Entries in the embbedded zip:"); + // foreach (ZipEntry entry in zip) + // { + // Console.WriteLine(entry.FileName); + // } + // Console.WriteLine(); + + unpackedResourceDir = GenerateTempPathname(tmpDir, "tmp"); + + if (String.IsNullOrEmpty(options.IconFile)) + { + // Use the ico file that is embedded into the Ionic.Zip + // DLL itself. To do this we must unpack the icon to + // the filesystem, in order to specify it on the cmdline + // of csc.exe. This method will remove the unpacked + // file later. + System.IO.Directory.CreateDirectory(unpackedResourceDir); + ZipEntry e = zip["zippedFile.ico"]; + // Must not extract a readonly file - it will be impossible to + // delete later. + if ((e.Attributes & FileAttributes.ReadOnly) == FileAttributes.ReadOnly) + e.Attributes ^= FileAttributes.ReadOnly; + e.Extract(unpackedResourceDir); + nameOfIconFile = Path.Combine(unpackedResourceDir, "zippedFile.ico"); + cp.CompilerOptions += String.Format("/win32icon:\"{0}\"", nameOfIconFile); + } + else + cp.CompilerOptions += String.Format("/win32icon:\"{0}\"", options.IconFile); + + cp.OutputAssembly = stubExe; + + if (options.Flavor == SelfExtractorFlavor.WinFormsApplication) + cp.CompilerOptions += " /target:winexe"; + + if (!String.IsNullOrEmpty(options.AdditionalCompilerSwitches)) + cp.CompilerOptions += " " + options.AdditionalCompilerSwitches; + + if (String.IsNullOrEmpty(cp.CompilerOptions)) + cp.CompilerOptions = null; + + if ((settings.CopyThroughResources != null) && (settings.CopyThroughResources.Count != 0)) + { + if (!Directory.Exists(unpackedResourceDir)) System.IO.Directory.CreateDirectory(unpackedResourceDir); + foreach (string re in settings.CopyThroughResources) + { + string filename = Path.Combine(unpackedResourceDir, re); + + ExtractResourceToFile(a2, re, filename); + // add the file into the target assembly as an embedded resource + cp.EmbeddedResources.Add(filename); + } + } + + // add the Ionic.Utils.Zip DLL as an embedded resource + cp.EmbeddedResources.Add(a1.Location); + + // file header + sb.Append("// " + Path.GetFileName(sourceFile) + "\n") + .Append("// --------------------------------------------\n//\n") + .Append("// This SFX source file was generated by DotNetZip ") + .Append(ZipFile.LibraryVersion.ToString()) + .Append("\n// at ") + .Append(System.DateTime.Now.ToString("yyyy MMMM dd HH:mm:ss")) + .Append("\n//\n// --------------------------------------------\n\n\n"); + + // assembly attributes + if (!String.IsNullOrEmpty(options.Description)) + sb.Append("[assembly: System.Reflection.AssemblyTitle(\"" + + options.Description.Replace("\"", "") + + "\")]\n"); + else + sb.Append("[assembly: System.Reflection.AssemblyTitle(\"DotNetZip SFX Archive\")]\n"); + + if (!String.IsNullOrEmpty(options.ProductVersion)) + sb.Append("[assembly: System.Reflection.AssemblyInformationalVersion(\"" + + options.ProductVersion.Replace("\"", "") + + "\")]\n"); + + // workitem + string copyright = + (String.IsNullOrEmpty(options.Copyright)) + ? "Extractor: Copyright © Dino Chiesa 2008-2011" + : options.Copyright.Replace("\"", ""); + + if (!String.IsNullOrEmpty(options.ProductName)) + sb.Append("[assembly: System.Reflection.AssemblyProduct(\"") + .Append(options.ProductName.Replace("\"", "")) + .Append("\")]\n"); + else + sb.Append("[assembly: System.Reflection.AssemblyProduct(\"DotNetZip\")]\n"); + + + sb.Append("[assembly: System.Reflection.AssemblyCopyright(\"" + copyright + "\")]\n") + .Append(String.Format("[assembly: System.Reflection.AssemblyVersion(\"{0}\")]\n", ZipFile.LibraryVersion.ToString())); + if (options.FileVersion != null) + sb.Append(String.Format("[assembly: System.Reflection.AssemblyFileVersion(\"{0}\")]\n", + options.FileVersion.ToString())); + + sb.Append("\n\n\n"); + + // Set the default extract location if it is available + string extractLoc = options.DefaultExtractDirectory; + if (extractLoc != null) + { + // remove double-quotes and replace slash with double-slash. + // This, because the value is going to be embedded into a + // cs file as a quoted string, and it needs to be escaped. + extractLoc = extractLoc.Replace("\"", "").Replace("\\", "\\\\"); + } + + string postExCmdLine = options.PostExtractCommandLine; + if (postExCmdLine != null) + { + postExCmdLine = postExCmdLine.Replace("\\", "\\\\"); + postExCmdLine = postExCmdLine.Replace("\"", "\\\""); + } + + + foreach (string rc in settings.ResourcesToCompile) + { + using (Stream s = zip[rc].OpenReader()) + { + if (s == null) + throw new ZipException(String.Format("missing resource '{0}'", rc)); + using (StreamReader sr = new StreamReader(s)) + { + while (sr.Peek() >= 0) + { + string line = sr.ReadLine(); + if (extractLoc != null) + line = line.Replace("@@EXTRACTLOCATION", extractLoc); + + line = line.Replace("@@REMOVE_AFTER_EXECUTE", options.RemoveUnpackedFilesAfterExecute.ToString()); + line = line.Replace("@@QUIET", options.Quiet.ToString()); + if (!String.IsNullOrEmpty(options.SfxExeWindowTitle)) + + line = line.Replace("@@SFX_EXE_WINDOW_TITLE", options.SfxExeWindowTitle); + + line = line.Replace("@@EXTRACT_EXISTING_FILE", ((int)options.ExtractExistingFile).ToString()); + + if (postExCmdLine != null) + line = line.Replace("@@POST_UNPACK_CMD_LINE", postExCmdLine); + + sb.Append(line).Append("\n"); + } + } + sb.Append("\n\n"); + } + } + } + + string LiteralSource = sb.ToString(); + +#if DEBUGSFX + // for debugging only + string sourceModule = GenerateTempPathname(tmpDir, "cs"); + using (StreamWriter sw = File.CreateText(sourceModule)) + { + sw.Write(LiteralSource); + } + Console.WriteLine("source: {0}", sourceModule); +#endif + + var cr = csharp.CompileAssemblyFromSource(cp, LiteralSource); + + + if (cr == null) + throw new SfxGenerationException("Cannot compile the extraction logic!"); + + if (Verbose) + foreach (string output in cr.Output) + StatusMessageTextWriter.WriteLine(output); + + if (cr.Errors.Count != 0) + { + using (TextWriter tw = new StreamWriter(sourceFile)) + { + // first, the source we compiled + tw.Write(LiteralSource); + + // now, append the compile errors + tw.Write("\n\n\n// ------------------------------------------------------------------\n"); + tw.Write("// Errors during compilation: \n//\n"); + string p = Path.GetFileName(sourceFile); + + foreach (System.CodeDom.Compiler.CompilerError error in cr.Errors) + { + tw.Write(String.Format("// {0}({1},{2}): {3} {4}: {5}\n//\n", + p, // 0 + error.Line, // 1 + error.Column, // 2 + error.IsWarning ? "Warning" : "error", // 3 + error.ErrorNumber, // 4 + error.ErrorText)); // 5 + } + } + throw new SfxGenerationException(String.Format("Errors compiling the extraction logic! {0}", sourceFile)); + } + + OnSaveEvent(ZipProgressEventType.Saving_AfterCompileSelfExtractor); + + // Now, copy the resulting EXE image to the _writestream. + // Because this stub exe is being saved first, the effect will be to + // concatenate the exe and the zip data together. + using (System.IO.Stream input = System.IO.File.OpenRead(stubExe)) + { + byte[] buffer = new byte[4000]; + int n = 1; + while (n != 0) + { + n = input.Read(buffer, 0, buffer.Length); + if (n != 0) + WriteStream.Write(buffer, 0, n); + } + } + } + + OnSaveEvent(ZipProgressEventType.Saving_AfterSaveTempArchive); + } + finally + { + try + { + if (Directory.Exists(unpackedResourceDir)) + { + try { Directory.Delete(unpackedResourceDir, true); } + catch (System.IO.IOException exc1) + { + StatusMessageTextWriter.WriteLine("Warning: Exception: {0}", exc1); + } + } + if (File.Exists(stubExe)) + { + try { File.Delete(stubExe); } + catch (System.IO.IOException exc1) + { + StatusMessageTextWriter.WriteLine("Warning: Exception: {0}", exc1); + } + } + } + catch (System.IO.IOException) { } + } + + return; + + } + + + + internal static string GenerateTempPathname(string dir, string extension) + { + string candidate = null; + String AppName = System.Reflection.Assembly.GetExecutingAssembly().GetName().Name; + do + { + // workitem 13475 + string uuid = System.Guid.NewGuid().ToString(); + + string Name = String.Format("{0}-{1}-{2}.{3}", + AppName, System.DateTime.Now.ToString("yyyyMMMdd-HHmmss"), + uuid, extension); + candidate = System.IO.Path.Combine(dir, Name); + } while (System.IO.File.Exists(candidate) || System.IO.Directory.Exists(candidate)); + + // The candidate path does not exist as a file or directory. + // It can now be created, as a file or directory. + return candidate; + } + + } +#endif +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Selector.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Selector.cs new file mode 100644 index 00000000..47339f3e --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.Selector.cs @@ -0,0 +1,1464 @@ +// ZipFile.Selector.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009-2010 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-August-06 09:35:58> +// +// ------------------------------------------------------------------ +// +// This module defines methods in the ZipFile class associated to the FileFilter +// capability - selecting files to add into the archive, or selecting entries to +// retrieve from the archive based on criteria including the filename, size, date, or +// attributes. It is something like a "poor man's LINQ". I included it into DotNetZip +// because not everyone has .NET 3.5 yet. When using DotNetZip on .NET 3.5, the LINQ +// query/selection will be superior. +// +// These methods are segregated into a different module to facilitate easy exclusion for +// those people who wish to have a smaller library without this function. +// +// ------------------------------------------------------------------ + + +using System; +using System.IO; +using System.Collections.Generic; + +namespace Ionic.Zip +{ + + partial class ZipFile + { + /// + /// Adds to the ZipFile a set of files from the current working directory on + /// disk, that conform to the specified criteria. + /// + /// + /// + /// + /// This method selects files from the the current working directory matching + /// the specified criteria, and adds them to the ZipFile. + /// + /// + /// + /// Specify the criteria in statements of 3 elements: a noun, an operator, and + /// a value. Consider the string "name != *.doc" . The noun is "name". The + /// operator is "!=", implying "Not Equal". The value is "*.doc". That + /// criterion, in English, says "all files with a name that does not end in + /// the .doc extension." + /// + /// + /// + /// Supported nouns include "name" (or "filename") for the filename; "atime", + /// "mtime", and "ctime" for last access time, last modfied time, and created + /// time of the file, respectively; "attributes" (or "attrs") for the file + /// attributes; "size" (or "length") for the file length (uncompressed), and + /// "type" for the type of object, either a file or a directory. The + /// "attributes", "name" and "type" nouns both support = and != as operators. + /// The "size", "atime", "mtime", and "ctime" nouns support = and !=, and + /// >, >=, <, <= as well. The times are taken to be expressed in + /// local time. + /// + /// + /// + /// Specify values for the file attributes as a string with one or more of the + /// characters H,R,S,A,I,L in any order, implying file attributes of Hidden, + /// ReadOnly, System, Archive, NotContextIndexed, and ReparsePoint (symbolic + /// link) respectively. + /// + /// + /// + /// To specify a time, use YYYY-MM-DD-HH:mm:ss or YYYY/MM/DD-HH:mm:ss as the + /// format. If you omit the HH:mm:ss portion, it is assumed to be 00:00:00 + /// (midnight). + /// + /// + /// + /// The value for a size criterion is expressed in integer quantities of bytes, + /// kilobytes (use k or kb after the number), megabytes (m or mb), or gigabytes + /// (g or gb). + /// + /// + /// + /// The value for a name is a pattern to match against the filename, potentially + /// including wildcards. The pattern follows CMD.exe glob rules: * implies one + /// or more of any character, while ? implies one character. If the name + /// pattern contains any slashes, it is matched to the entire filename, + /// including the path; otherwise, it is matched against only the filename + /// without the path. This means a pattern of "*\*.*" matches all files one + /// directory level deep, while a pattern of "*.*" matches all files in all + /// directories. + /// + /// + /// + /// To specify a name pattern that includes spaces, use single quotes around the + /// pattern. A pattern of "'* *.*'" will match all files that have spaces in + /// the filename. The full criteria string for that would be "name = '* *.*'" . + /// + /// + /// + /// The value for a type criterion is either F (implying a file) or D (implying + /// a directory). + /// + /// + /// + /// Some examples: + /// + /// + /// + /// + /// criteria + /// Files retrieved + /// + /// + /// + /// name != *.xls + /// any file with an extension that is not .xls + /// + /// + /// + /// + /// name = *.mp3 + /// any file with a .mp3 extension. + /// + /// + /// + /// + /// *.mp3 + /// (same as above) any file with a .mp3 extension. + /// + /// + /// + /// + /// attributes = A + /// all files whose attributes include the Archive bit. + /// + /// + /// + /// + /// attributes != H + /// all files whose attributes do not include the Hidden bit. + /// + /// + /// + /// + /// mtime > 2009-01-01 + /// all files with a last modified time after January 1st, 2009. + /// + /// + /// + /// + /// size > 2gb + /// all files whose uncompressed size is greater than 2gb. + /// + /// + /// + /// + /// type = D + /// all directories in the filesystem. + /// + /// + /// + /// + /// + /// You can combine criteria with the conjunctions AND or OR. Using a string + /// like "name = *.txt AND size >= 100k" for the selectionCriteria retrieves + /// entries whose names end in .txt, and whose uncompressed size is greater than + /// or equal to 100 kilobytes. + /// + /// + /// + /// For more complex combinations of criteria, you can use parenthesis to group + /// clauses in the boolean logic. Without parenthesis, the precedence of the + /// criterion atoms is determined by order of appearance. Unlike the C# + /// language, the AND conjunction does not take precendence over the logical OR. + /// This is important only in strings that contain 3 or more criterion atoms. + /// In other words, "name = *.txt and size > 1000 or attributes = H" implies + /// "((name = *.txt AND size > 1000) OR attributes = H)" while "attributes = + /// H OR name = *.txt and size > 1000" evaluates to "((attributes = H OR name + /// = *.txt) AND size > 1000)". When in doubt, use parenthesis. + /// + /// + /// + /// Using time properties requires some extra care. If you want to retrieve all + /// entries that were last updated on 2009 February 14, specify a time range + /// like so:"mtime >= 2009-02-14 AND mtime < 2009-02-15". Read this to + /// say: all files updated after 12:00am on February 14th, until 12:00am on + /// February 15th. You can use the same bracketing approach to specify any time + /// period - a year, a month, a week, and so on. + /// + /// + /// + /// The syntax allows one special case: if you provide a string with no spaces, it is + /// treated as a pattern to match for the filename. Therefore a string like "*.xls" + /// will be equivalent to specifying "name = *.xls". + /// + /// + /// + /// There is no logic in this method that insures that the file inclusion + /// criteria are internally consistent. For example, it's possible to specify + /// criteria that says the file must have a size of less than 100 bytes, as well + /// as a size that is greater than 1000 bytes. Obviously no file will ever + /// satisfy such criteria, but this method does not detect such logical + /// inconsistencies. The caller is responsible for insuring the criteria are + /// sensible. + /// + /// + /// + /// Using this method, the file selection does not recurse into + /// subdirectories, and the full path of the selected files is included in the + /// entries added into the zip archive. If you don't like these behaviors, + /// see the other overloads of this method. + /// + /// + /// + /// + /// This example zips up all *.csv files in the current working directory. + /// + /// using (ZipFile zip = new ZipFile()) + /// { + /// // To just match on filename wildcards, + /// // use the shorthand form of the selectionCriteria string. + /// zip.AddSelectedFiles("*.csv"); + /// zip.Save(PathToZipArchive); + /// } + /// + /// + /// Using zip As ZipFile = New ZipFile() + /// zip.AddSelectedFiles("*.csv") + /// zip.Save(PathToZipArchive) + /// End Using + /// + /// + /// + /// The criteria for file selection + public void AddSelectedFiles(String selectionCriteria) + { + this.AddSelectedFiles(selectionCriteria, ".", null, false); + } + + /// + /// Adds to the ZipFile a set of files from the disk that conform to the + /// specified criteria, optionally recursing into subdirectories. + /// + /// + /// + /// + /// This method selects files from the the current working directory matching + /// the specified criteria, and adds them to the ZipFile. If + /// recurseDirectories is true, files are also selected from + /// subdirectories, and the directory structure in the filesystem is + /// reproduced in the zip archive, rooted at the current working directory. + /// + /// + /// + /// Using this method, the full path of the selected files is included in the + /// entries added into the zip archive. If you don't want this behavior, use + /// one of the overloads of this method that allows the specification of a + /// directoryInArchive. + /// + /// + /// + /// For details on the syntax for the selectionCriteria parameter, see . + /// + /// + /// + /// + /// + /// + /// This example zips up all *.xml files in the current working directory, or any + /// subdirectory, that are larger than 1mb. + /// + /// + /// using (ZipFile zip = new ZipFile()) + /// { + /// // Use a compound expression in the selectionCriteria string. + /// zip.AddSelectedFiles("name = *.xml and size > 1024kb", true); + /// zip.Save(PathToZipArchive); + /// } + /// + /// + /// Using zip As ZipFile = New ZipFile() + /// ' Use a compound expression in the selectionCriteria string. + /// zip.AddSelectedFiles("name = *.xml and size > 1024kb", true) + /// zip.Save(PathToZipArchive) + /// End Using + /// + /// + /// + /// The criteria for file selection + /// + /// + /// If true, the file selection will recurse into subdirectories. + /// + public void AddSelectedFiles(String selectionCriteria, bool recurseDirectories) + { + this.AddSelectedFiles(selectionCriteria, ".", null, recurseDirectories); + } + + /// + /// Adds to the ZipFile a set of files from a specified directory in the + /// filesystem, that conform to the specified criteria. + /// + /// + /// + /// + /// This method selects files that conform to the specified criteria, from the + /// the specified directory on disk, and adds them to the ZipFile. The search + /// does not recurse into subdirectores. + /// + /// + /// + /// Using this method, the full filesystem path of the files on disk is + /// reproduced on the entries added to the zip file. If you don't want this + /// behavior, use one of the other overloads of this method. + /// + /// + /// + /// For details on the syntax for the selectionCriteria parameter, see . + /// + /// + /// + /// + /// + /// + /// This example zips up all *.xml files larger than 1mb in the directory + /// given by "d:\rawdata". + /// + /// + /// using (ZipFile zip = new ZipFile()) + /// { + /// // Use a compound expression in the selectionCriteria string. + /// zip.AddSelectedFiles("name = *.xml and size > 1024kb", "d:\\rawdata"); + /// zip.Save(PathToZipArchive); + /// } + /// + /// + /// + /// Using zip As ZipFile = New ZipFile() + /// ' Use a compound expression in the selectionCriteria string. + /// zip.AddSelectedFiles("name = *.xml and size > 1024kb", "d:\rawdata) + /// zip.Save(PathToZipArchive) + /// End Using + /// + /// + /// + /// The criteria for file selection + /// + /// + /// The name of the directory on the disk from which to select files. + /// + public void AddSelectedFiles(String selectionCriteria, String directoryOnDisk) + { + this.AddSelectedFiles(selectionCriteria, directoryOnDisk, null, false); + } + + + /// + /// Adds to the ZipFile a set of files from the specified directory on disk, + /// that conform to the specified criteria. + /// + /// + /// + /// + /// + /// This method selects files from the the specified disk directory matching + /// the specified selection criteria, and adds them to the ZipFile. If + /// recurseDirectories is true, files are also selected from + /// subdirectories. + /// + /// + /// + /// The full directory structure in the filesystem is reproduced on the + /// entries added to the zip archive. If you don't want this behavior, use + /// one of the overloads of this method that allows the specification of a + /// directoryInArchive. + /// + /// + /// + /// For details on the syntax for the selectionCriteria parameter, see . + /// + /// + /// + /// + /// + /// This example zips up all *.csv files in the "files" directory, or any + /// subdirectory, that have been saved since 2009 February 14th. + /// + /// + /// using (ZipFile zip = new ZipFile()) + /// { + /// // Use a compound expression in the selectionCriteria string. + /// zip.AddSelectedFiles("name = *.csv and mtime > 2009-02-14", "files", true); + /// zip.Save(PathToZipArchive); + /// } + /// + /// + /// Using zip As ZipFile = New ZipFile() + /// ' Use a compound expression in the selectionCriteria string. + /// zip.AddSelectedFiles("name = *.csv and mtime > 2009-02-14", "files", true) + /// zip.Save(PathToZipArchive) + /// End Using + /// + /// + /// + /// + /// This example zips up all files in the current working + /// directory, and all its child directories, except those in + /// the excludethis subdirectory. + /// + /// Using Zip As ZipFile = New ZipFile(zipfile) + /// Zip.AddSelectedFfiles("name != 'excludethis\*.*'", datapath, True) + /// Zip.Save() + /// End Using + /// + /// + /// + /// The criteria for file selection + /// + /// + /// The filesystem path from which to select files. + /// + /// + /// + /// If true, the file selection will recurse into subdirectories. + /// + public void AddSelectedFiles(String selectionCriteria, String directoryOnDisk, bool recurseDirectories) + { + this.AddSelectedFiles(selectionCriteria, directoryOnDisk, null, recurseDirectories); + } + + + /// + /// Adds to the ZipFile a selection of files from the specified directory on + /// disk, that conform to the specified criteria, and using a specified root + /// path for entries added to the zip archive. + /// + /// + /// + /// + /// This method selects files from the specified disk directory matching the + /// specified selection criteria, and adds those files to the ZipFile, using + /// the specified directory path in the archive. The search does not recurse + /// into subdirectories. For details on the syntax for the selectionCriteria + /// parameter, see . + /// + /// + /// + /// + /// + /// + /// This example zips up all *.psd files in the "photos" directory that have + /// been saved since 2009 February 14th, and puts them all in a zip file, + /// using the directory name of "content" in the zip archive itself. When the + /// zip archive is unzipped, the folder containing the .psd files will be + /// named "content". + /// + /// + /// using (ZipFile zip = new ZipFile()) + /// { + /// // Use a compound expression in the selectionCriteria string. + /// zip.AddSelectedFiles("name = *.psd and mtime > 2009-02-14", "photos", "content"); + /// zip.Save(PathToZipArchive); + /// } + /// + /// + /// Using zip As ZipFile = New ZipFile + /// zip.AddSelectedFiles("name = *.psd and mtime > 2009-02-14", "photos", "content") + /// zip.Save(PathToZipArchive) + /// End Using + /// + /// + /// + /// + /// The criteria for selection of files to add to the ZipFile. + /// + /// + /// + /// The path to the directory in the filesystem from which to select files. + /// + /// + /// + /// Specifies a directory path to use to in place of the + /// directoryOnDisk. This path may, or may not, correspond to a real + /// directory in the current filesystem. If the files within the zip are + /// later extracted, this is the path used for the extracted file. Passing + /// null (nothing in VB) will use the path on the file name, if any; in other + /// words it would use directoryOnDisk, plus any subdirectory. Passing + /// the empty string ("") will insert the item at the root path within the + /// archive. + /// + public void AddSelectedFiles(String selectionCriteria, + String directoryOnDisk, + String directoryPathInArchive) + { + this.AddSelectedFiles(selectionCriteria, directoryOnDisk, directoryPathInArchive, false); + } + + /// + /// Adds to the ZipFile a selection of files from the specified directory on + /// disk, that conform to the specified criteria, optionally recursing through + /// subdirectories, and using a specified root path for entries added to the + /// zip archive. + /// + /// + /// + /// This method selects files from the specified disk directory that match the + /// specified selection criteria, and adds those files to the ZipFile, using + /// the specified directory path in the archive. If recurseDirectories + /// is true, files are also selected from subdirectories, and the directory + /// structure in the filesystem is reproduced in the zip archive, rooted at + /// the directory specified by directoryOnDisk. For details on the + /// syntax for the selectionCriteria parameter, see . + /// + /// + /// + /// + /// This example zips up all files that are NOT *.pst files, in the current + /// working directory and any subdirectories. + /// + /// + /// using (ZipFile zip = new ZipFile()) + /// { + /// zip.AddSelectedFiles("name != *.pst", SourceDirectory, "backup", true); + /// zip.Save(PathToZipArchive); + /// } + /// + /// + /// Using zip As ZipFile = New ZipFile + /// zip.AddSelectedFiles("name != *.pst", SourceDirectory, "backup", true) + /// zip.Save(PathToZipArchive) + /// End Using + /// + /// + /// + /// + /// The criteria for selection of files to add to the ZipFile. + /// + /// + /// + /// The path to the directory in the filesystem from which to select files. + /// + /// + /// + /// Specifies a directory path to use to in place of the + /// directoryOnDisk. This path may, or may not, correspond to a real + /// directory in the current filesystem. If the files within the zip are + /// later extracted, this is the path used for the extracted file. Passing + /// null (nothing in VB) will use the path on the file name, if any; in other + /// words it would use directoryOnDisk, plus any subdirectory. Passing + /// the empty string ("") will insert the item at the root path within the + /// archive. + /// + /// + /// + /// If true, the method also scans subdirectories for files matching the + /// criteria. + /// + public void AddSelectedFiles(String selectionCriteria, + String directoryOnDisk, + String directoryPathInArchive, + bool recurseDirectories) + { + _AddOrUpdateSelectedFiles(selectionCriteria, + directoryOnDisk, + directoryPathInArchive, + recurseDirectories, + false); + } + + /// + /// Updates the ZipFile with a selection of files from the disk that conform + /// to the specified criteria. + /// + /// + /// + /// This method selects files from the specified disk directory that match the + /// specified selection criteria, and Updates the ZipFile with those + /// files, using the specified directory path in the archive. If + /// recurseDirectories is true, files are also selected from + /// subdirectories, and the directory structure in the filesystem is + /// reproduced in the zip archive, rooted at the directory specified by + /// directoryOnDisk. For details on the syntax for the + /// selectionCriteria parameter, see . + /// + /// + /// + /// The criteria for selection of files to add to the ZipFile. + /// + /// + /// + /// The path to the directory in the filesystem from which to select files. + /// + /// + /// + /// Specifies a directory path to use to in place of the + /// directoryOnDisk. This path may, or may not, correspond to a + /// real directory in the current filesystem. If the files within the zip + /// are later extracted, this is the path used for the extracted file. + /// Passing null (nothing in VB) will use the path on the file name, if + /// any; in other words it would use directoryOnDisk, plus any + /// subdirectory. Passing the empty string ("") will insert the item at + /// the root path within the archive. + /// + /// + /// + /// If true, the method also scans subdirectories for files matching the criteria. + /// + /// + /// + public void UpdateSelectedFiles(String selectionCriteria, + String directoryOnDisk, + String directoryPathInArchive, + bool recurseDirectories) + { + _AddOrUpdateSelectedFiles(selectionCriteria, + directoryOnDisk, + directoryPathInArchive, + recurseDirectories, + true); + } + + + private string EnsureendInSlash(string s) + { + if (s.EndsWith("\\")) return s; + return s + "\\"; + } + + private void _AddOrUpdateSelectedFiles(String selectionCriteria, + String directoryOnDisk, + String directoryPathInArchive, + bool recurseDirectories, + bool wantUpdate) + { + if (directoryOnDisk == null && (Directory.Exists(selectionCriteria))) + { + directoryOnDisk = selectionCriteria; + selectionCriteria = "*.*"; + } + else if (String.IsNullOrEmpty(directoryOnDisk)) + { + directoryOnDisk = "."; + } + + // workitem 9176 + while (directoryOnDisk.EndsWith("\\")) directoryOnDisk = directoryOnDisk.Substring(0, directoryOnDisk.Length - 1); + if (Verbose) StatusMessageTextWriter.WriteLine("adding selection '{0}' from dir '{1}'...", + selectionCriteria, directoryOnDisk); + Ionic.FileSelector ff = new Ionic.FileSelector(selectionCriteria, + AddDirectoryWillTraverseReparsePoints); + var itemsToAdd = ff.SelectFiles(directoryOnDisk, recurseDirectories); + + if (Verbose) StatusMessageTextWriter.WriteLine("found {0} files...", itemsToAdd.Count); + + OnAddStarted(); + + AddOrUpdateAction action = (wantUpdate) ? AddOrUpdateAction.AddOrUpdate : AddOrUpdateAction.AddOnly; + foreach (var item in itemsToAdd) + { + // workitem 10153 + string dirInArchive = (directoryPathInArchive == null) + ? null + // workitem 12260 + : ReplaceLeadingDirectory(Path.GetDirectoryName(item), + directoryOnDisk, + directoryPathInArchive); + + if (File.Exists(item)) + { + if (wantUpdate) + this.UpdateFile(item, dirInArchive); + else + this.AddFile(item, dirInArchive); + } + else + { + // this adds "just" the directory, without recursing to the contained files + AddOrUpdateDirectoryImpl(item, dirInArchive, action, false, 0); + } + } + + OnAddCompleted(); + } + + + // workitem 12260 + private static string ReplaceLeadingDirectory(string original, + string pattern, + string replacement) + { + string upperString = original.ToUpper(); + string upperPattern = pattern.ToUpper(); + int p1 = upperString.IndexOf(upperPattern); + if (p1 != 0) return original; + return replacement + original.Substring(upperPattern.Length); + } + +#if NOT + private static string ReplaceEx(string original, + string pattern, + string replacement) + { + int count, position0, position1; + count = position0 = position1 = 0; + string upperString = original.ToUpper(); + string upperPattern = pattern.ToUpper(); + int inc = (original.Length/pattern.Length) * + (replacement.Length-pattern.Length); + char [] chars = new char[original.Length + Math.Max(0, inc)]; + while( (position1 = upperString.IndexOf(upperPattern, + position0)) != -1 ) + { + for ( int i=position0 ; i < position1 ; ++i ) + chars[count++] = original[i]; + for ( int i=0 ; i < replacement.Length ; ++i ) + chars[count++] = replacement[i]; + position0 = position1+pattern.Length; + } + if ( position0 == 0 ) return original; + for ( int i=position0 ; i < original.Length ; ++i ) + chars[count++] = original[i]; + return new string(chars, 0, count); + } +#endif + + /// + /// Retrieve entries from the zipfile by specified criteria. + /// + /// + /// + /// + /// This method allows callers to retrieve the collection of entries from the zipfile + /// that fit the specified criteria. The criteria are described in a string format, and + /// can include patterns for the filename; constraints on the size of the entry; + /// constraints on the last modified, created, or last accessed time for the file + /// described by the entry; or the attributes of the entry. + /// + /// + /// + /// For details on the syntax for the selectionCriteria parameter, see . + /// + /// + /// + /// This method is intended for use with a ZipFile that has been read from storage. + /// When creating a new ZipFile, this method will work only after the ZipArchive has + /// been Saved to the disk (the ZipFile class subsequently and implicitly reads the Zip + /// archive from storage.) Calling SelectEntries on a ZipFile that has not yet been + /// saved will deliver undefined results. + /// + /// + /// + /// + /// Thrown if selectionCriteria has an invalid syntax. + /// + /// + /// + /// This example selects all the PhotoShop files from within an archive, and extracts them + /// to the current working directory. + /// + /// using (ZipFile zip1 = ZipFile.Read(ZipFileName)) + /// { + /// var PhotoShopFiles = zip1.SelectEntries("*.psd"); + /// foreach (ZipEntry psd in PhotoShopFiles) + /// { + /// psd.Extract(); + /// } + /// } + /// + /// + /// Using zip1 As ZipFile = ZipFile.Read(ZipFileName) + /// Dim PhotoShopFiles as ICollection(Of ZipEntry) + /// PhotoShopFiles = zip1.SelectEntries("*.psd") + /// Dim psd As ZipEntry + /// For Each psd In PhotoShopFiles + /// psd.Extract + /// Next + /// End Using + /// + /// + /// the string that specifies which entries to select + /// a collection of ZipEntry objects that conform to the inclusion spec + public ICollection SelectEntries(String selectionCriteria) + { + Ionic.FileSelector ff = new Ionic.FileSelector(selectionCriteria, + AddDirectoryWillTraverseReparsePoints); + return ff.SelectEntries(this); + } + + + /// + /// Retrieve entries from the zipfile by specified criteria. + /// + /// + /// + /// + /// This method allows callers to retrieve the collection of entries from the zipfile + /// that fit the specified criteria. The criteria are described in a string format, and + /// can include patterns for the filename; constraints on the size of the entry; + /// constraints on the last modified, created, or last accessed time for the file + /// described by the entry; or the attributes of the entry. + /// + /// + /// + /// For details on the syntax for the selectionCriteria parameter, see . + /// + /// + /// + /// This method is intended for use with a ZipFile that has been read from storage. + /// When creating a new ZipFile, this method will work only after the ZipArchive has + /// been Saved to the disk (the ZipFile class subsequently and implicitly reads the Zip + /// archive from storage.) Calling SelectEntries on a ZipFile that has not yet been + /// saved will deliver undefined results. + /// + /// + /// + /// + /// Thrown if selectionCriteria has an invalid syntax. + /// + /// + /// + /// + /// using (ZipFile zip1 = ZipFile.Read(ZipFileName)) + /// { + /// var UpdatedPhotoShopFiles = zip1.SelectEntries("*.psd", "UpdatedFiles"); + /// foreach (ZipEntry e in UpdatedPhotoShopFiles) + /// { + /// // prompt for extract here + /// if (WantExtract(e.FileName)) + /// e.Extract(); + /// } + /// } + /// + /// + /// Using zip1 As ZipFile = ZipFile.Read(ZipFileName) + /// Dim UpdatedPhotoShopFiles As ICollection(Of ZipEntry) = zip1.SelectEntries("*.psd", "UpdatedFiles") + /// Dim e As ZipEntry + /// For Each e In UpdatedPhotoShopFiles + /// ' prompt for extract here + /// If Me.WantExtract(e.FileName) Then + /// e.Extract + /// End If + /// Next + /// End Using + /// + /// + /// the string that specifies which entries to select + /// + /// + /// the directory in the archive from which to select entries. If null, then + /// all directories in the archive are used. + /// + /// + /// a collection of ZipEntry objects that conform to the inclusion spec + public ICollection SelectEntries(String selectionCriteria, string directoryPathInArchive) + { + Ionic.FileSelector ff = new Ionic.FileSelector(selectionCriteria, + AddDirectoryWillTraverseReparsePoints); + return ff.SelectEntries(this, directoryPathInArchive); + } + + + + /// + /// Remove entries from the zipfile by specified criteria. + /// + /// + /// + /// + /// This method allows callers to remove the collection of entries from the zipfile + /// that fit the specified criteria. The criteria are described in a string format, and + /// can include patterns for the filename; constraints on the size of the entry; + /// constraints on the last modified, created, or last accessed time for the file + /// described by the entry; or the attributes of the entry. + /// + /// + /// + /// For details on the syntax for the selectionCriteria parameter, see . + /// + /// + /// + /// This method is intended for use with a ZipFile that has been read from storage. + /// When creating a new ZipFile, this method will work only after the ZipArchive has + /// been Saved to the disk (the ZipFile class subsequently and implicitly reads the Zip + /// archive from storage.) Calling SelectEntries on a ZipFile that has not yet been + /// saved will deliver undefined results. + /// + /// + /// + /// + /// Thrown if selectionCriteria has an invalid syntax. + /// + /// + /// + /// This example removes all entries in a zip file that were modified prior to January 1st, 2008. + /// + /// using (ZipFile zip1 = ZipFile.Read(ZipFileName)) + /// { + /// // remove all entries from prior to Jan 1, 2008 + /// zip1.RemoveEntries("mtime < 2008-01-01"); + /// // don't forget to save the archive! + /// zip1.Save(); + /// } + /// + /// + /// Using zip As ZipFile = ZipFile.Read(ZipFileName) + /// ' remove all entries from prior to Jan 1, 2008 + /// zip1.RemoveEntries("mtime < 2008-01-01") + /// ' do not forget to save the archive! + /// zip1.Save + /// End Using + /// + /// + /// the string that specifies which entries to select + /// the number of entries removed + public int RemoveSelectedEntries(String selectionCriteria) + { + var selection = this.SelectEntries(selectionCriteria); + this.RemoveEntries(selection); + return selection.Count; + } + + + /// + /// Remove entries from the zipfile by specified criteria, and within the specified + /// path in the archive. + /// + /// + /// + /// + /// This method allows callers to remove the collection of entries from the zipfile + /// that fit the specified criteria. The criteria are described in a string format, and + /// can include patterns for the filename; constraints on the size of the entry; + /// constraints on the last modified, created, or last accessed time for the file + /// described by the entry; or the attributes of the entry. + /// + /// + /// + /// For details on the syntax for the selectionCriteria parameter, see . + /// + /// + /// + /// This method is intended for use with a ZipFile that has been read from storage. + /// When creating a new ZipFile, this method will work only after the ZipArchive has + /// been Saved to the disk (the ZipFile class subsequently and implicitly reads the Zip + /// archive from storage.) Calling SelectEntries on a ZipFile that has not yet been + /// saved will deliver undefined results. + /// + /// + /// + /// + /// Thrown if selectionCriteria has an invalid syntax. + /// + /// + /// + /// + /// using (ZipFile zip1 = ZipFile.Read(ZipFileName)) + /// { + /// // remove all entries from prior to Jan 1, 2008 + /// zip1.RemoveEntries("mtime < 2008-01-01", "documents"); + /// // a call to ZipFile.Save will make the modifications permanent + /// zip1.Save(); + /// } + /// + /// + /// Using zip As ZipFile = ZipFile.Read(ZipFileName) + /// ' remove all entries from prior to Jan 1, 2008 + /// zip1.RemoveEntries("mtime < 2008-01-01", "documents") + /// ' a call to ZipFile.Save will make the modifications permanent + /// zip1.Save + /// End Using + /// + /// + /// + /// the string that specifies which entries to select + /// + /// the directory in the archive from which to select entries. If null, then + /// all directories in the archive are used. + /// + /// the number of entries removed + public int RemoveSelectedEntries(String selectionCriteria, string directoryPathInArchive) + { + var selection = this.SelectEntries(selectionCriteria, directoryPathInArchive); + this.RemoveEntries(selection); + return selection.Count; + } + + + /// + /// Selects and Extracts a set of Entries from the ZipFile. + /// + /// + /// + /// + /// The entries are extracted into the current working directory. + /// + /// + /// + /// If any of the files to be extracted already exist, then the action taken is as + /// specified in the property on the + /// corresponding ZipEntry instance. By default, the action taken in this case is to + /// throw an exception. + /// + /// + /// + /// For information on the syntax of the selectionCriteria string, + /// see . + /// + /// + /// + /// + /// This example shows how extract all XML files modified after 15 January 2009. + /// + /// using (ZipFile zip = ZipFile.Read(zipArchiveName)) + /// { + /// zip.ExtractSelectedEntries("name = *.xml and mtime > 2009-01-15"); + /// } + /// + /// + /// the selection criteria for entries to extract. + /// + /// + public void ExtractSelectedEntries(String selectionCriteria) + { + foreach (ZipEntry e in SelectEntries(selectionCriteria)) + { + e.Password = _Password; // possibly null + e.Extract(); + } + } + + + /// + /// Selects and Extracts a set of Entries from the ZipFile. + /// + /// + /// + /// + /// The entries are extracted into the current working directory. When extraction would would + /// overwrite an existing filesystem file, the action taken is as specified in the + /// parameter. + /// + /// + /// + /// For information on the syntax of the string describing the entry selection criteria, + /// see . + /// + /// + /// + /// + /// This example shows how extract all XML files modified after 15 January 2009, + /// overwriting any existing files. + /// + /// using (ZipFile zip = ZipFile.Read(zipArchiveName)) + /// { + /// zip.ExtractSelectedEntries("name = *.xml and mtime > 2009-01-15", + /// ExtractExistingFileAction.OverwriteSilently); + /// } + /// + /// + /// + /// the selection criteria for entries to extract. + /// + /// + /// The action to take if extraction would overwrite an existing file. + /// + public void ExtractSelectedEntries(String selectionCriteria, ExtractExistingFileAction extractExistingFile) + { + foreach (ZipEntry e in SelectEntries(selectionCriteria)) + { + e.Password = _Password; // possibly null + e.Extract(extractExistingFile); + } + } + + + /// + /// Selects and Extracts a set of Entries from the ZipFile. + /// + /// + /// + /// + /// The entries are selected from the specified directory within the archive, and then + /// extracted into the current working directory. + /// + /// + /// + /// If any of the files to be extracted already exist, then the action taken is as + /// specified in the property on the + /// corresponding ZipEntry instance. By default, the action taken in this case is to + /// throw an exception. + /// + /// + /// + /// For information on the syntax of the string describing the entry selection criteria, + /// see . + /// + /// + /// + /// + /// This example shows how extract all XML files modified after 15 January 2009, + /// and writes them to the "unpack" directory. + /// + /// using (ZipFile zip = ZipFile.Read(zipArchiveName)) + /// { + /// zip.ExtractSelectedEntries("name = *.xml and mtime > 2009-01-15","unpack"); + /// } + /// + /// + /// + /// the selection criteria for entries to extract. + /// + /// + /// the directory in the archive from which to select entries. If null, then + /// all directories in the archive are used. + /// + /// + /// + public void ExtractSelectedEntries(String selectionCriteria, String directoryPathInArchive) + { + foreach (ZipEntry e in SelectEntries(selectionCriteria, directoryPathInArchive)) + { + e.Password = _Password; // possibly null + e.Extract(); + } + } + + + /// + /// Selects and Extracts a set of Entries from the ZipFile. + /// + /// + /// + /// + /// The entries are extracted into the specified directory. If any of the files to be + /// extracted already exist, an exception will be thrown. + /// + /// + /// For information on the syntax of the string describing the entry selection criteria, + /// see . + /// + /// + /// + /// the selection criteria for entries to extract. + /// + /// + /// the directory in the archive from which to select entries. If null, then + /// all directories in the archive are used. + /// + /// + /// + /// the directory on the disk into which to extract. It will be created + /// if it does not exist. + /// + public void ExtractSelectedEntries(String selectionCriteria, string directoryInArchive, string extractDirectory) + { + foreach (ZipEntry e in SelectEntries(selectionCriteria, directoryInArchive)) + { + e.Password = _Password; // possibly null + e.Extract(extractDirectory); + } + } + + + /// + /// Selects and Extracts a set of Entries from the ZipFile. + /// + /// + /// + /// + /// The entries are extracted into the specified directory. When extraction would would + /// overwrite an existing filesystem file, the action taken is as specified in the + /// parameter. + /// + /// + /// + /// For information on the syntax of the string describing the entry selection criteria, + /// see . + /// + /// + /// + /// + /// This example shows how extract all files with an XML extension or with a size larger than 100,000 bytes, + /// and puts them in the unpack directory. For any files that already exist in + /// that destination directory, they will not be overwritten. + /// + /// using (ZipFile zip = ZipFile.Read(zipArchiveName)) + /// { + /// zip.ExtractSelectedEntries("name = *.xml or size > 100000", + /// null, + /// "unpack", + /// ExtractExistingFileAction.DontOverwrite); + /// } + /// + /// + /// + /// the selection criteria for entries to extract. + /// + /// + /// The directory on the disk into which to extract. It will be created if it does not exist. + /// + /// + /// + /// The directory in the archive from which to select entries. If null, then + /// all directories in the archive are used. + /// + /// + /// + /// The action to take if extraction would overwrite an existing file. + /// + /// + public void ExtractSelectedEntries(String selectionCriteria, string directoryPathInArchive, string extractDirectory, ExtractExistingFileAction extractExistingFile) + { + foreach (ZipEntry e in SelectEntries(selectionCriteria, directoryPathInArchive)) + { + e.Password = _Password; // possibly null + e.Extract(extractDirectory, extractExistingFile); + } + } + + } + +} + + + +namespace Ionic +{ + internal abstract partial class SelectionCriterion + { + internal abstract bool Evaluate(Ionic.Zip.ZipEntry entry); + } + + + internal partial class NameCriterion : SelectionCriterion + { + internal override bool Evaluate(Ionic.Zip.ZipEntry entry) + { + // swap forward slashes in the entry.FileName for backslashes + string transformedFileName = entry.FileName.Replace("/", "\\"); + + return _Evaluate(transformedFileName); + } + } + + + internal partial class SizeCriterion : SelectionCriterion + { + internal override bool Evaluate(Ionic.Zip.ZipEntry entry) + { + return _Evaluate(entry.UncompressedSize); + } + } + + internal partial class TimeCriterion : SelectionCriterion + { + internal override bool Evaluate(Ionic.Zip.ZipEntry entry) + { + DateTime x; + switch (Which) + { + case WhichTime.atime: + x = entry.AccessedTime; + break; + case WhichTime.mtime: + x = entry.ModifiedTime; + break; + case WhichTime.ctime: + x = entry.CreationTime; + break; + default: throw new ArgumentException("??time"); + } + return _Evaluate(x); + } + } + + + internal partial class TypeCriterion : SelectionCriterion + { + internal override bool Evaluate(Ionic.Zip.ZipEntry entry) + { + bool result = (ObjectType == 'D') + ? entry.IsDirectory + : !entry.IsDirectory; + + if (Operator != ComparisonOperator.EqualTo) + result = !result; + return result; + } + } + +#if !SILVERLIGHT + internal partial class AttributesCriterion : SelectionCriterion + { + internal override bool Evaluate(Ionic.Zip.ZipEntry entry) + { + FileAttributes fileAttrs = entry.Attributes; + return _Evaluate(fileAttrs); + } + } +#endif + + internal partial class CompoundCriterion : SelectionCriterion + { + internal override bool Evaluate(Ionic.Zip.ZipEntry entry) + { + bool result = Left.Evaluate(entry); + switch (Conjunction) + { + case LogicalConjunction.AND: + if (result) + result = Right.Evaluate(entry); + break; + case LogicalConjunction.OR: + if (!result) + result = Right.Evaluate(entry); + break; + case LogicalConjunction.XOR: + result ^= Right.Evaluate(entry); + break; + } + return result; + } + } + + + + public partial class FileSelector + { + private bool Evaluate(Ionic.Zip.ZipEntry entry) + { + bool result = _Criterion.Evaluate(entry); + return result; + } + + /// + /// Retrieve the ZipEntry items in the ZipFile that conform to the specified criteria. + /// + /// + /// + /// + /// This method applies the criteria set in the FileSelector instance (as described in + /// the ) to the specified ZipFile. Using this + /// method, for example, you can retrieve all entries from the given ZipFile that + /// have filenames ending in .txt. + /// + /// + /// + /// Normally, applications would not call this method directly. This method is used + /// by the ZipFile class. + /// + /// + /// + /// Using the appropriate SelectionCriteria, you can retrieve entries based on size, + /// time, and attributes. See for a + /// description of the syntax of the SelectionCriteria string. + /// + /// + /// + /// + /// The ZipFile from which to retrieve entries. + /// + /// a collection of ZipEntry objects that conform to the criteria. + public ICollection SelectEntries(Ionic.Zip.ZipFile zip) + { + if (zip == null) + throw new ArgumentNullException("zip"); + + var list = new List(); + + foreach (Ionic.Zip.ZipEntry e in zip) + { + if (this.Evaluate(e)) + list.Add(e); + } + + return list; + } + + + /// + /// Retrieve the ZipEntry items in the ZipFile that conform to the specified criteria. + /// + /// + /// + /// + /// This method applies the criteria set in the FileSelector instance (as described in + /// the ) to the specified ZipFile. Using this + /// method, for example, you can retrieve all entries from the given ZipFile that + /// have filenames ending in .txt. + /// + /// + /// + /// Normally, applications would not call this method directly. This method is used + /// by the ZipFile class. + /// + /// + /// + /// This overload allows the selection of ZipEntry instances from the ZipFile to be restricted + /// to entries contained within a particular directory in the ZipFile. + /// + /// + /// + /// Using the appropriate SelectionCriteria, you can retrieve entries based on size, + /// time, and attributes. See for a + /// description of the syntax of the SelectionCriteria string. + /// + /// + /// + /// + /// The ZipFile from which to retrieve entries. + /// + /// + /// the directory in the archive from which to select entries. If null, then + /// all directories in the archive are used. + /// + /// + /// a collection of ZipEntry objects that conform to the criteria. + public ICollection SelectEntries(Ionic.Zip.ZipFile zip, string directoryPathInArchive) + { + if (zip == null) + throw new ArgumentNullException("zip"); + + var list = new List(); + // workitem 8559 + string slashSwapped = (directoryPathInArchive == null) ? null : directoryPathInArchive.Replace("/", "\\"); + // workitem 9174 + if (slashSwapped != null) + { + while (slashSwapped.EndsWith("\\")) + slashSwapped = slashSwapped.Substring(0, slashSwapped.Length - 1); + } + foreach (Ionic.Zip.ZipEntry e in zip) + { + if (directoryPathInArchive == null || (Path.GetDirectoryName(e.FileName) == directoryPathInArchive) + || (Path.GetDirectoryName(e.FileName) == slashSwapped)) // workitem 8559 + if (this.Evaluate(e)) + list.Add(e); + } + + return list; + } + + } +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.cs new file mode 100644 index 00000000..d1b12fce --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.cs @@ -0,0 +1,3910 @@ +// ZipFile.cs +// +// Copyright (c) 2006-2010 Dino Chiesa +// All rights reserved. +// +// This module is part of DotNetZip, a zipfile class library. +// The class library reads and writes zip files, according to the format +// described by PKware, at: +// http://www.pkware.com/business_and_developers/developer/popups/appnote.txt +// +// +// There are other Zip class libraries available. +// +// - it is possible to read and write zip files within .NET via the J# runtime. +// But some people don't like to install the extra DLL, which is no longer +// supported by MS. And also, the J# libraries don't support advanced zip +// features, like ZIP64, spanned archives, or AES encryption. +// +// - There are third-party GPL and LGPL libraries available. Some people don't +// like the license, and some of them don't support all the ZIP features, like AES. +// +// - Finally, there are commercial tools (From ComponentOne, XCeed, etc). But +// some people don't want to incur the cost. +// +// This alternative implementation is **not** GPL licensed. It is free of cost, and +// does not require J#. It does require .NET 2.0. It balances a good set of +// features, with ease of use and speed of performance. +// +// This code is released under the Microsoft Public License . +// See the License.txt for details. +// +// +// NB: This implementation originally relied on the +// System.IO.Compression.DeflateStream base class in the .NET Framework +// v2.0 base class library, but now includes a managed-code port of Zlib. +// +// Thu, 08 Oct 2009 17:04 +// + + +using System; +using System.IO; +using System.Collections.Generic; +using Interop = System.Runtime.InteropServices; + + +namespace Ionic.Zip +{ + /// + /// The ZipFile type represents a zip archive file. + /// + /// + /// + /// + /// This is the main type in the DotNetZip class library. This class reads and + /// writes zip files, as defined in the specification + /// for zip files described by PKWare. The compression for this + /// implementation is provided by a managed-code version of Zlib, included with + /// DotNetZip in the classes in the Ionic.Zlib namespace. + /// + /// + /// + /// This class provides a general purpose zip file capability. Use it to read, + /// create, or update zip files. When you want to create zip files using a + /// Stream type to write the zip file, you may want to consider the class. + /// + /// + /// + /// Both the ZipOutputStream class and the ZipFile class can + /// be used to create zip files. Both of them support many of the common zip + /// features, including Unicode, different compression methods and levels, + /// and ZIP64. They provide very similar performance when creating zip + /// files. + /// + /// + /// + /// The ZipFile class is generally easier to use than + /// ZipOutputStream and should be considered a higher-level interface. For + /// example, when creating a zip file via calls to the PutNextEntry() and + /// Write() methods on the ZipOutputStream class, the caller is + /// responsible for opening the file, reading the bytes from the file, writing + /// those bytes into the ZipOutputStream, setting the attributes on the + /// ZipEntry, and setting the created, last modified, and last accessed + /// timestamps on the zip entry. All of these things are done automatically by a + /// call to ZipFile.AddFile(). + /// For this reason, the ZipOutputStream is generally recommended for use + /// only when your application emits arbitrary data, not necessarily data from a + /// filesystem file, directly into a zip file, and does so using a Stream + /// metaphor. + /// + /// + /// + /// Aside from the differences in programming model, there are other + /// differences in capability between the two classes. + /// + /// + /// + /// + /// ZipFile can be used to read and extract zip files, in addition to + /// creating zip files. ZipOutputStream cannot read zip files. If you want + /// to use a stream to read zip files, check out the class. + /// + /// + /// + /// ZipOutputStream does not support the creation of segmented or spanned + /// zip files. + /// + /// + /// + /// ZipOutputStream cannot produce a self-extracting archive. + /// + /// + /// + /// + /// Be aware that the ZipFile class implements the interface. In order for ZipFile to + /// produce a valid zip file, you use use it within a using clause (Using + /// in VB), or call the Dispose() method explicitly. See the examples + /// for how to employ a using clause. + /// + /// + /// + [Interop.GuidAttribute("ebc25cf6-9120-4283-b972-0e5520d00005")] + [Interop.ComVisible(true)] +#if !NETCF + [Interop.ClassInterface(Interop.ClassInterfaceType.AutoDispatch)] +#endif + public partial class ZipFile : + System.Collections.IEnumerable, + System.Collections.Generic.IEnumerable, + IDisposable + { + + #region public properties + + /// + /// Indicates whether to perform a full scan of the zip file when reading it. + /// + /// + /// + /// + /// + /// You almost never want to use this property. + /// + /// + /// + /// When reading a zip file, if this flag is true (True in + /// VB), the entire zip archive will be scanned and searched for entries. + /// For large archives, this can take a very, long time. The much more + /// efficient default behavior is to read the zip directory, which is + /// stored at the end of the zip file. But, in some cases the directory is + /// corrupted and you need to perform a full scan of the zip file to + /// determine the contents of the zip file. This property lets you do + /// that, when necessary. + /// + /// + /// + /// This flag is effective only when calling . Normally you would read a ZipFile with the + /// static ZipFile.Read + /// method. But you can't set the FullScan property on the + /// ZipFile instance when you use a static factory method like + /// ZipFile.Read. + /// + /// + /// + /// + /// + /// + /// This example shows how to read a zip file using the full scan approach, + /// and then save it, thereby producing a corrected zip file. + /// + /// + /// using (var zip = new ZipFile()) + /// { + /// zip.FullScan = true; + /// zip.Initialize(zipFileName); + /// zip.Save(newName); + /// } + /// + /// + /// + /// Using zip As New ZipFile + /// zip.FullScan = True + /// zip.Initialize(zipFileName) + /// zip.Save(newName) + /// End Using + /// + /// + /// + public bool FullScan + { + get; + set; + } + + + /// + /// Whether to sort the ZipEntries before saving the file. + /// + /// + /// + /// The default is false. If you have a large number of zip entries, the sort + /// alone can consume significant time. + /// + /// + /// + /// + /// using (var zip = new ZipFile()) + /// { + /// zip.AddFiles(filesToAdd); + /// zip.SortEntriesBeforeSaving = true; + /// zip.Save(name); + /// } + /// + /// + /// + /// Using zip As New ZipFile + /// zip.AddFiles(filesToAdd) + /// zip.SortEntriesBeforeSaving = True + /// zip.Save(name) + /// End Using + /// + /// + /// + public bool SortEntriesBeforeSaving + { + get; + set; + } + + + + /// + /// Indicates whether NTFS Reparse Points, like junctions, should be + /// traversed during calls to AddDirectory(). + /// + /// + /// + /// By default, calls to AddDirectory() will traverse NTFS reparse + /// points, like mounted volumes, and directory junctions. An example + /// of a junction is the "My Music" directory in Windows Vista. In some + /// cases you may not want DotNetZip to traverse those directories. In + /// that case, set this property to false. + /// + /// + /// + /// + /// using (var zip = new ZipFile()) + /// { + /// zip.AddDirectoryWillTraverseReparsePoints = false; + /// zip.AddDirectory(dirToZip,"fodder"); + /// zip.Save(zipFileToCreate); + /// } + /// + /// + public bool AddDirectoryWillTraverseReparsePoints { get; set; } + + + /// + /// Size of the IO buffer used while saving. + /// + /// + /// + /// + /// + /// First, let me say that you really don't need to bother with this. It is + /// here to allow for optimizations that you probably won't make! It will work + /// fine if you don't set or get this property at all. Ok? + /// + /// + /// + /// Now that we have that out of the way, the fine print: This + /// property affects the size of the buffer that is used for I/O for each + /// entry contained in the zip file. When a file is read in to be compressed, + /// it uses a buffer given by the size here. When you update a zip file, the + /// data for unmodified entries is copied from the first zip file to the + /// other, through a buffer given by the size here. + /// + /// + /// + /// Changing the buffer size affects a few things: first, for larger buffer + /// sizes, the memory used by the ZipFile, obviously, will be larger + /// during I/O operations. This may make operations faster for very much + /// larger files. Last, for any given entry, when you use a larger buffer + /// there will be fewer progress events during I/O operations, because there's + /// one progress event generated for each time the buffer is filled and then + /// emptied. + /// + /// + /// + /// The default buffer size is 8k. Increasing the buffer size may speed + /// things up as you compress larger files. But there are no hard-and-fast + /// rules here, eh? You won't know til you test it. And there will be a + /// limit where ever larger buffers actually slow things down. So as I said + /// in the beginning, it's probably best if you don't set or get this property + /// at all. + /// + /// + /// + /// + /// + /// This example shows how you might set a large buffer size for efficiency when + /// dealing with zip entries that are larger than 1gb. + /// + /// using (ZipFile zip = new ZipFile()) + /// { + /// zip.SaveProgress += this.zip1_SaveProgress; + /// zip.AddDirectory(directoryToZip, ""); + /// zip.UseZip64WhenSaving = Zip64Option.Always; + /// zip.BufferSize = 65536*8; // 65536 * 8 = 512k + /// zip.Save(ZipFileToCreate); + /// } + /// + /// + + public int BufferSize + { + get { return _BufferSize; } + set { _BufferSize = value; } + } + + /// + /// Size of the work buffer to use for the ZLIB codec during compression. + /// + /// + /// + /// + /// When doing ZLIB or Deflate compression, the library fills a buffer, + /// then passes it to the compressor for compression. Then the library + /// reads out the compressed bytes. This happens repeatedly until there + /// is no more uncompressed data to compress. This property sets the + /// size of the buffer that will be used for chunk-wise compression. In + /// order for the setting to take effect, your application needs to set + /// this property before calling one of the ZipFile.Save() + /// overloads. + /// + /// + /// Setting this affects the performance and memory efficiency of + /// compression and decompression. For larger files, setting this to a + /// larger size may improve compression performance, but the exact + /// numbers vary depending on available memory, the size of the streams + /// you are compressing, and a bunch of other variables. I don't have + /// good firm recommendations on how to set it. You'll have to test it + /// yourself. Or just leave it alone and accept the default. + /// + /// + public int CodecBufferSize + { + get; + set; + } + + /// + /// Indicates whether extracted files should keep their paths as + /// stored in the zip archive. + /// + /// + /// + /// + /// This property affects Extraction. It is not used when creating zip + /// archives. + /// + /// + /// + /// With this property set to false, the default, extracting entries + /// from a zip file will create files in the filesystem that have the full + /// path associated to the entry within the zip file. With this property set + /// to true, extracting entries from the zip file results in files + /// with no path: the folders are "flattened." + /// + /// + /// + /// An example: suppose the zip file contains entries /directory1/file1.txt and + /// /directory2/file2.txt. With FlattenFoldersOnExtract set to false, + /// the files created will be \directory1\file1.txt and \directory2\file2.txt. + /// With the property set to true, the files created are file1.txt and file2.txt. + /// + /// + /// + public bool FlattenFoldersOnExtract + { + get; + set; + } + + + /// + /// The compression strategy to use for all entries. + /// + /// + /// + /// Set the Strategy used by the ZLIB-compatible compressor, when + /// compressing entries using the DEFLATE method. Different compression + /// strategies work better on different sorts of data. The strategy + /// parameter can affect the compression ratio and the speed of + /// compression but not the correctness of the compresssion. For more + /// information see Ionic.Zlib.CompressionStrategy. + /// + public Ionic.Zlib.CompressionStrategy Strategy + { + get { return _Strategy; } + set { _Strategy = value; } + } + + + /// + /// The name of the ZipFile, on disk. + /// + /// + /// + /// + /// + /// When the ZipFile instance was created by reading an archive using + /// one of the ZipFile.Read methods, this property represents the name + /// of the zip file that was read. When the ZipFile instance was + /// created by using the no-argument constructor, this value is null + /// (Nothing in VB). + /// + /// + /// + /// If you use the no-argument constructor, and you then explicitly set this + /// property, when you call , this name will + /// specify the name of the zip file created. Doing so is equivalent to + /// calling . When instantiating a + /// ZipFile by reading from a stream or byte array, the Name + /// property remains null. When saving to a stream, the Name + /// property is implicitly set to null. + /// + /// + public string Name + { + get { return _name; } + set { _name = value; } + } + + + /// + /// Sets the compression level to be used for entries subsequently added to + /// the zip archive. + /// + /// + /// + /// + /// Varying the compression level used on entries can affect the + /// size-vs-speed tradeoff when compression and decompressing data streams + /// or files. + /// + /// + /// + /// As with some other properties on the ZipFile class, like , , and , setting this property on a ZipFile + /// instance will cause the specified CompressionLevel to be used on all + /// items that are subsequently added to the + /// ZipFile instance. If you set this property after you have added + /// items to the ZipFile, but before you have called Save(), + /// those items will not use the specified compression level. + /// + /// + /// + /// If you do not set this property, the default compression level is used, + /// which normally gives a good balance of compression efficiency and + /// compression speed. In some tests, using BestCompression can + /// double the time it takes to compress, while delivering just a small + /// increase in compression efficiency. This behavior will vary with the + /// type of data you compress. If you are in doubt, just leave this setting + /// alone, and accept the default. + /// + /// + public Ionic.Zlib.CompressionLevel CompressionLevel + { + get; + set; + } + + /// + /// The compression method for the zipfile. + /// + /// + /// + /// By default, the compression method is CompressionMethod.Deflate. + /// + /// + /// + public Ionic.Zip.CompressionMethod CompressionMethod + { + get + { + return _compressionMethod; + } + set + { + _compressionMethod = value; + } + } + + + + /// + /// A comment attached to the zip archive. + /// + /// + /// + /// + /// + /// This property is read/write. It allows the application to specify a + /// comment for the ZipFile, or read the comment for the + /// ZipFile. After setting this property, changes are only made + /// permanent when you call a Save() method. + /// + /// + /// + /// According to PKWARE's + /// zip specification, the comment is not encrypted, even if there is a + /// password set on the zip file. + /// + /// + /// + /// The specification does not describe how to indicate the encoding used + /// on a comment string. Many "compliant" zip tools and libraries use + /// IBM437 as the code page for comments; DotNetZip, too, follows that + /// practice. On the other hand, there are situations where you want a + /// Comment to be encoded with something else, for example using code page + /// 950 "Big-5 Chinese". To fill that need, DotNetZip will encode the + /// comment following the same procedure it follows for encoding + /// filenames: (a) if is + /// Never, it uses the default encoding (IBM437). (b) if is Always, it always uses the + /// alternate encoding (). (c) if is AsNecessary, it uses the + /// alternate encoding only if the default encoding is not sufficient for + /// encoding the comment - in other words if decoding the result does not + /// produce the original string. This decision is taken at the time of + /// the call to ZipFile.Save(). + /// + /// + /// + /// When creating a zip archive using this library, it is possible to change + /// the value of between each + /// entry you add, and between adding entries and the call to + /// Save(). Don't do this. It will likely result in a zip file that is + /// not readable by any tool or application. For best interoperability, leave + /// alone, or specify it only + /// once, before adding any entries to the ZipFile instance. + /// + /// + /// + public string Comment + { + get { return _Comment; } + set + { + _Comment = value; + _contentsChanged = true; + } + } + + + + + /// + /// Specifies whether the Creation, Access, and Modified times for entries + /// added to the zip file will be emitted in “Windows format” + /// when the zip archive is saved. + /// + /// + /// + /// + /// An application creating a zip archive can use this flag to explicitly + /// specify that the file times for the entries should or should not be stored + /// in the zip archive in the format used by Windows. By default this flag is + /// true, meaning the Windows-format times are stored in the zip + /// archive. + /// + /// + /// + /// When adding an entry from a file or directory, the Creation (), Access (), and Modified () times for the given entry are + /// automatically set from the filesystem values. When adding an entry from a + /// stream or string, all three values are implicitly set to + /// DateTime.Now. Applications can also explicitly set those times by + /// calling . + /// + /// + /// + /// PKWARE's + /// zip specification describes multiple ways to format these times in a + /// zip file. One is the format Windows applications normally use: 100ns ticks + /// since January 1, 1601 UTC. The other is a format Unix applications typically + /// use: seconds since January 1, 1970 UTC. Each format can be stored in an + /// "extra field" in the zip entry when saving the zip archive. The former + /// uses an extra field with a Header Id of 0x000A, while the latter uses a + /// header ID of 0x5455, although you probably don't need to know that. + /// + /// + /// + /// Not all tools and libraries can interpret these fields. Windows + /// compressed folders is one that can read the Windows Format timestamps, + /// while I believe the Infozip + /// tools can read the Unix format timestamps. Some tools and libraries + /// may be able to read only one or the other. DotNetZip can read or write + /// times in either or both formats. + /// + /// + /// + /// The times stored are taken from , , and . + /// + /// + /// + /// The value set here applies to all entries subsequently added to the + /// ZipFile. + /// + /// + /// + /// This property is not mutually exclusive of the property. It is possible and + /// legal and valid to produce a zip file that contains timestamps encoded in + /// the Unix format as well as in the Windows format, in addition to the LastModified time attached to each + /// entry in the archive, a time that is always stored in "DOS format". And, + /// notwithstanding the names PKWare uses for these time formats, any of them + /// can be read and written by any computer, on any operating system. But, + /// there are no guarantees that a program running on Mac or Linux will + /// gracefully handle a zip file with "Windows" formatted times, or that an + /// application that does not use DotNetZip but runs on Windows will be able to + /// handle file times in Unix format. + /// + /// + /// + /// When in doubt, test. Sorry, I haven't got a complete list of tools and + /// which sort of timestamps they can use and will tolerate. If you get any + /// good information and would like to pass it on, please do so and I will + /// include that information in this documentation. + /// + /// + /// + /// + /// This example shows how to save a zip file that contains file timestamps + /// in a format normally used by Unix. + /// + /// using (var zip = new ZipFile()) + /// { + /// // produce a zip file the Mac will like + /// zip.EmitTimesInWindowsFormatWhenSaving = false; + /// zip.EmitTimesInUnixFormatWhenSaving = true; + /// zip.AddDirectory(directoryToZip, "files"); + /// zip.Save(outputFile); + /// } + /// + /// + /// + /// Using zip As New ZipFile + /// '' produce a zip file the Mac will like + /// zip.EmitTimesInWindowsFormatWhenSaving = False + /// zip.EmitTimesInUnixFormatWhenSaving = True + /// zip.AddDirectory(directoryToZip, "files") + /// zip.Save(outputFile) + /// End Using + /// + /// + /// + /// + /// + public bool EmitTimesInWindowsFormatWhenSaving + { + get + { + return _emitNtfsTimes; + } + set + { + _emitNtfsTimes = value; + } + } + + + /// + /// Specifies whether the Creation, Access, and Modified times + /// for entries added to the zip file will be emitted in "Unix(tm) + /// format" when the zip archive is saved. + /// + /// + /// + /// + /// An application creating a zip archive can use this flag to explicitly + /// specify that the file times for the entries should or should not be stored + /// in the zip archive in the format used by Unix. By default this flag is + /// false, meaning the Unix-format times are not stored in the zip + /// archive. + /// + /// + /// + /// When adding an entry from a file or directory, the Creation (), Access (), and Modified () times for the given entry are + /// automatically set from the filesystem values. When adding an entry from a + /// stream or string, all three values are implicitly set to DateTime.Now. + /// Applications can also explicitly set those times by calling . + /// + /// + /// + /// PKWARE's + /// zip specification describes multiple ways to format these times in a + /// zip file. One is the format Windows applications normally use: 100ns ticks + /// since January 1, 1601 UTC. The other is a format Unix applications + /// typically use: seconds since January 1, 1970 UTC. Each format can be + /// stored in an "extra field" in the zip entry when saving the zip + /// archive. The former uses an extra field with a Header Id of 0x000A, while + /// the latter uses a header ID of 0x5455, although you probably don't need to + /// know that. + /// + /// + /// + /// Not all tools and libraries can interpret these fields. Windows + /// compressed folders is one that can read the Windows Format timestamps, + /// while I believe the Infozip + /// tools can read the Unix format timestamps. Some tools and libraries may be + /// able to read only one or the other. DotNetZip can read or write times in + /// either or both formats. + /// + /// + /// + /// The times stored are taken from , , and . + /// + /// + /// + /// This property is not mutually exclusive of the property. It is possible and + /// legal and valid to produce a zip file that contains timestamps encoded in + /// the Unix format as well as in the Windows format, in addition to the LastModified time attached to each + /// entry in the zip archive, a time that is always stored in "DOS + /// format". And, notwithstanding the names PKWare uses for these time + /// formats, any of them can be read and written by any computer, on any + /// operating system. But, there are no guarantees that a program running on + /// Mac or Linux will gracefully handle a zip file with "Windows" formatted + /// times, or that an application that does not use DotNetZip but runs on + /// Windows will be able to handle file times in Unix format. + /// + /// + /// + /// When in doubt, test. Sorry, I haven't got a complete list of tools and + /// which sort of timestamps they can use and will tolerate. If you get any + /// good information and would like to pass it on, please do so and I will + /// include that information in this documentation. + /// + /// + /// + /// + /// + public bool EmitTimesInUnixFormatWhenSaving + { + get + { + return _emitUnixTimes; + } + set + { + _emitUnixTimes = value; + } + } + + + + /// + /// Indicates whether verbose output is sent to the during AddXxx() and + /// ReadXxx() operations. + /// + /// + /// + /// This is a synthetic property. It returns true if the is non-null. + /// + internal bool Verbose + { + get { return (_StatusMessageTextWriter != null); } + } + + + /// + /// Returns true if an entry by the given name exists in the ZipFile. + /// + /// + /// the name of the entry to find + /// true if an entry with the given name exists; otherwise false. + /// + public bool ContainsEntry(string name) + { + // workitem 12534 + return _entries.ContainsKey(SharedUtilities.NormalizePathForUseInZipFile(name)); + } + + + + /// + /// Indicates whether to perform case-sensitive matching on the filename when + /// retrieving entries in the zipfile via the string-based indexer. + /// + /// + /// + /// The default value is false, which means don't do case-sensitive + /// matching. In other words, retrieving zip["ReadMe.Txt"] is the same as + /// zip["readme.txt"]. It really makes sense to set this to true only + /// if you are not running on Windows, which has case-insensitive + /// filenames. But since this library is not built for non-Windows platforms, + /// in most cases you should just leave this property alone. + /// + public bool CaseSensitiveRetrieval + { + get + { + return _CaseSensitiveRetrieval; + } + + set + { + // workitem 9868 + if (value != _CaseSensitiveRetrieval) + { + _CaseSensitiveRetrieval = value; + _initEntriesDictionary(); + } + } + } + + + /// + /// Indicates whether to encode entry filenames and entry comments using Unicode + /// (UTF-8). + /// + /// + /// + /// + /// The + /// PKWare zip specification provides for encoding file names and file + /// comments in either the IBM437 code page, or in UTF-8. This flag selects + /// the encoding according to that specification. By default, this flag is + /// false, and filenames and comments are encoded into the zip file in the + /// IBM437 codepage. Setting this flag to true will specify that filenames + /// and comments that cannot be encoded with IBM437 will be encoded with + /// UTF-8. + /// + /// + /// + /// Zip files created with strict adherence to the PKWare specification with + /// respect to UTF-8 encoding can contain entries with filenames containing + /// any combination of Unicode characters, including the full range of + /// characters from Chinese, Latin, Hebrew, Greek, Cyrillic, and many other + /// alphabets. However, because at this time, the UTF-8 portion of the PKWare + /// specification is not broadly supported by other zip libraries and + /// utilities, such zip files may not be readable by your favorite zip tool or + /// archiver. In other words, interoperability will decrease if you set this + /// flag to true. + /// + /// + /// + /// In particular, Zip files created with strict adherence to the PKWare + /// specification with respect to UTF-8 encoding will not work well with + /// Explorer in Windows XP or Windows Vista, because Windows compressed + /// folders, as far as I know, do not support UTF-8 in zip files. Vista can + /// read the zip files, but shows the filenames incorrectly. Unpacking from + /// Windows Vista Explorer will result in filenames that have rubbish + /// characters in place of the high-order UTF-8 bytes. + /// + /// + /// + /// Also, zip files that use UTF-8 encoding will not work well with Java + /// applications that use the java.util.zip classes, as of v5.0 of the Java + /// runtime. The Java runtime does not correctly implement the PKWare + /// specification in this regard. + /// + /// + /// + /// As a result, we have the unfortunate situation that "correct" behavior by + /// the DotNetZip library with regard to Unicode encoding of filenames during + /// zip creation will result in zip files that are readable by strictly + /// compliant and current tools (for example the most recent release of the + /// commercial WinZip tool); but these zip files will not be readable by + /// various other tools or libraries, including Windows Explorer. + /// + /// + /// + /// The DotNetZip library can read and write zip files with UTF8-encoded + /// entries, according to the PKware spec. If you use DotNetZip for both + /// creating and reading the zip file, and you use UTF-8, there will be no + /// loss of information in the filenames. For example, using a self-extractor + /// created by this library will allow you to unpack files correctly with no + /// loss of information in the filenames. + /// + /// + /// + /// If you do not set this flag, it will remain false. If this flag is false, + /// your ZipFile will encode all filenames and comments using the + /// IBM437 codepage. This can cause "loss of information" on some filenames, + /// but the resulting zipfile will be more interoperable with other + /// utilities. As an example of the loss of information, diacritics can be + /// lost. The o-tilde character will be down-coded to plain o. The c with a + /// cedilla (Unicode 0xE7) used in Portugese will be downcoded to a c. + /// Likewise, the O-stroke character (Unicode 248), used in Danish and + /// Norwegian, will be down-coded to plain o. Chinese characters cannot be + /// represented in codepage IBM437; when using the default encoding, Chinese + /// characters in filenames will be represented as ?. These are all examples + /// of "information loss". + /// + /// + /// + /// The loss of information associated to the use of the IBM437 encoding is + /// inconvenient, and can also lead to runtime errors. For example, using + /// IBM437, any sequence of 4 Chinese characters will be encoded as ????. If + /// your application creates a ZipFile, then adds two files, each with + /// names of four Chinese characters each, this will result in a duplicate + /// filename exception. In the case where you add a single file with a name + /// containing four Chinese characters, calling Extract() on the entry that + /// has question marks in the filename will result in an exception, because + /// the question mark is not legal for use within filenames on Windows. These + /// are just a few examples of the problems associated to loss of information. + /// + /// + /// + /// This flag is independent of the encoding of the content within the entries + /// in the zip file. Think of the zip file as a container - it supports an + /// encoding. Within the container are other "containers" - the file entries + /// themselves. The encoding within those entries is independent of the + /// encoding of the zip archive container for those entries. + /// + /// + /// + /// Rather than specify the encoding in a binary fashion using this flag, an + /// application can specify an arbitrary encoding via the property. Setting the encoding + /// explicitly when creating zip archives will result in non-compliant zip + /// files that, curiously, are fairly interoperable. The challenge is, the + /// PKWare specification does not provide for a way to specify that an entry + /// in a zip archive uses a code page that is neither IBM437 nor UTF-8. + /// Therefore if you set the encoding explicitly when creating a zip archive, + /// you must take care upon reading the zip archive to use the same code page. + /// If you get it wrong, the behavior is undefined and may result in incorrect + /// filenames, exceptions, stomach upset, hair loss, and acne. + /// + /// + /// + [Obsolete("Beginning with v1.9.1.6 of DotNetZip, this property is obsolete. It will be removed in a future version of the library. Your applications should use AlternateEncoding and AlternateEncodingUsage instead.")] + public bool UseUnicodeAsNecessary + { + get + { + return (_alternateEncoding == System.Text.Encoding.GetEncoding("UTF-8")) && + (_alternateEncodingUsage == ZipOption.AsNecessary); + } + set + { + if (value) + { + _alternateEncoding = System.Text.Encoding.GetEncoding("UTF-8"); + _alternateEncodingUsage = ZipOption.AsNecessary; + + } + else + { + _alternateEncoding = Ionic.Zip.ZipFile.DefaultEncoding; + _alternateEncodingUsage = ZipOption.Never; + } + } + } + + + /// + /// Specify whether to use ZIP64 extensions when saving a zip archive. + /// + /// + /// + /// + /// + /// When creating a zip file, the default value for the property is . is + /// safest, in the sense that you will not get an Exception if a pre-ZIP64 + /// limit is exceeded. + /// + /// + /// + /// You may set the property at any time before calling Save(). + /// + /// + /// + /// When reading a zip file via the Zipfile.Read() method, DotNetZip + /// will properly read ZIP64-endowed zip archives, regardless of the value of + /// this property. DotNetZip will always read ZIP64 archives. This property + /// governs only whether DotNetZip will write them. Therefore, when updating + /// archives, be careful about setting this property after reading an archive + /// that may use ZIP64 extensions. + /// + /// + /// + /// An interesting question is, if you have set this property to + /// AsNecessary, and then successfully saved, does the resulting + /// archive use ZIP64 extensions or not? To learn this, check the property, after calling Save(). + /// + /// + /// + /// Have you thought about + /// donating? + /// + /// + /// + /// + public Zip64Option UseZip64WhenSaving + { + get + { + return _zip64; + } + set + { + _zip64 = value; + } + } + + + + /// + /// Indicates whether the archive requires ZIP64 extensions. + /// + /// + /// + /// + /// + /// This property is null (or Nothing in VB) if the archive has + /// not been saved, and there are fewer than 65334 ZipEntry items + /// contained in the archive. + /// + /// + /// + /// The Value is true if any of the following four conditions holds: + /// the uncompressed size of any entry is larger than 0xFFFFFFFF; the + /// compressed size of any entry is larger than 0xFFFFFFFF; the relative + /// offset of any entry within the zip archive is larger than 0xFFFFFFFF; or + /// there are more than 65534 entries in the archive. (0xFFFFFFFF = + /// 4,294,967,295). The result may not be known until a Save() is attempted + /// on the zip archive. The Value of this + /// property may be set only AFTER one of the Save() methods has been called. + /// + /// + /// + /// If none of the four conditions holds, and the archive has been saved, then + /// the Value is false. + /// + /// + /// + /// A Value of false does not indicate that the zip archive, as saved, + /// does not use ZIP64. It merely indicates that ZIP64 is not required. An + /// archive may use ZIP64 even when not required if the property is set to , or if the property is set to and the output stream was not + /// seekable. Use the property to determine if + /// the most recent Save() method resulted in an archive that utilized + /// the ZIP64 extensions. + /// + /// + /// + /// + /// + public Nullable RequiresZip64 + { + get + { + if (_entries.Count > 65534) + return new Nullable(true); + + // If the ZipFile has not been saved or if the contents have changed, then + // it is not known if ZIP64 is required. + if (!_hasBeenSaved || _contentsChanged) return null; + + // Whether ZIP64 is required is knowable. + foreach (ZipEntry e in _entries.Values) + { + if (e.RequiresZip64.Value) return new Nullable(true); + } + + return new Nullable(false); + } + } + + + /// + /// Indicates whether the most recent Save() operation used ZIP64 extensions. + /// + /// + /// + /// + /// The use of ZIP64 extensions within an archive is not always necessary, and + /// for interoperability concerns, it may be desired to NOT use ZIP64 if + /// possible. The property can be + /// set to use ZIP64 extensions only when necessary. In those cases, + /// Sometimes applications want to know whether a Save() actually used ZIP64 + /// extensions. Applications can query this read-only property to learn + /// whether ZIP64 has been used in a just-saved ZipFile. + /// + /// + /// + /// The value is null (or Nothing in VB) if the archive has not + /// been saved. + /// + /// + /// + /// Non-null values (HasValue is true) indicate whether ZIP64 + /// extensions were used during the most recent Save() operation. The + /// ZIP64 extensions may have been used as required by any particular entry + /// because of its uncompressed or compressed size, or because the archive is + /// larger than 4294967295 bytes, or because there are more than 65534 entries + /// in the archive, or because the UseZip64WhenSaving property was set + /// to , or because the + /// UseZip64WhenSaving property was set to and the output stream was not seekable. + /// The value of this property does not indicate the reason the ZIP64 + /// extensions were used. + /// + /// + /// + /// + /// + public Nullable OutputUsedZip64 + { + get + { + return _OutputUsesZip64; + } + } + + + /// + /// Indicates whether the most recent Read() operation read a zip file that uses + /// ZIP64 extensions. + /// + /// + /// + /// This property will return null (Nothing in VB) if you've added an entry after reading + /// the zip file. + /// + public Nullable InputUsesZip64 + { + get + { + if (_entries.Count > 65534) + return true; + + foreach (ZipEntry e in this) + { + // if any entry was added after reading the zip file, then the result is null + if (e.Source != ZipEntrySource.ZipFile) return null; + + // if any entry read from the zip used zip64, then the result is true + if (e._InputUsesZip64) return true; + } + return false; + } + } + + + /// + /// The text encoding to use when writing new entries to the ZipFile, + /// for those entries that cannot be encoded with the default (IBM437) + /// encoding; or, the text encoding that was used when reading the entries + /// from the ZipFile. + /// + /// + /// + /// + /// In its + /// zip specification, PKWare describes two options for encoding + /// filenames and comments: using IBM437 or UTF-8. But, some archiving tools + /// or libraries do not follow the specification, and instead encode + /// characters using the system default code page. For example, WinRAR when + /// run on a machine in Shanghai may encode filenames with the Big-5 Chinese + /// (950) code page. This behavior is contrary to the Zip specification, but + /// it occurs anyway. + /// + /// + /// + /// When using DotNetZip to write zip archives that will be read by one of + /// these other archivers, set this property to specify the code page to use + /// when encoding the and for each ZipEntry in the zip file, for + /// values that cannot be encoded with the default codepage for zip files, + /// IBM437. This is why this property is "provisional". In all cases, IBM437 + /// is used where possible, in other words, where no loss of data would + /// result. It is possible, therefore, to have a given entry with a + /// Comment encoded in IBM437 and a FileName encoded with the + /// specified "provisional" codepage. + /// + /// + /// + /// Be aware that a zip file created after you've explicitly set the property to a value other than + /// IBM437 may not be compliant to the PKWare specification, and may not be + /// readable by compliant archivers. On the other hand, many (most?) + /// archivers are non-compliant and can read zip files created in arbitrary + /// code pages. The trick is to use or specify the proper codepage when + /// reading the zip. + /// + /// + /// + /// When creating a zip archive using this library, it is possible to change + /// the value of between each + /// entry you add, and between adding entries and the call to + /// Save(). Don't do this. It will likely result in a zipfile that is + /// not readable. For best interoperability, either leave alone, or specify it only once, + /// before adding any entries to the ZipFile instance. There is one + /// exception to this recommendation, described later. + /// + /// + /// + /// When using an arbitrary, non-UTF8 code page for encoding, there is no + /// standard way for the creator application - whether DotNetZip, WinZip, + /// WinRar, or something else - to formally specify in the zip file which + /// codepage has been used for the entries. As a result, readers of zip files + /// are not able to inspect the zip file and determine the codepage that was + /// used for the entries contained within it. It is left to the application + /// or user to determine the necessary codepage when reading zip files encoded + /// this way. In other words, if you explicitly specify the codepage when you + /// create the zipfile, you must explicitly specify the same codepage when + /// reading the zipfile. + /// + /// + /// + /// The way you specify the code page to use when reading a zip file varies + /// depending on the tool or library you use to read the zip. In DotNetZip, + /// you use a ZipFile.Read() method that accepts an encoding parameter. It + /// isn't possible with Windows Explorer, as far as I know, to specify an + /// explicit codepage to use when reading a zip. If you use an incorrect + /// codepage when reading a zipfile, you will get entries with filenames that + /// are incorrect, and the incorrect filenames may even contain characters + /// that are not legal for use within filenames in Windows. Extracting entries + /// with illegal characters in the filenames will lead to exceptions. It's too + /// bad, but this is just the way things are with code pages in zip + /// files. Caveat Emptor. + /// + /// + /// + /// Example: Suppose you create a zipfile that contains entries with + /// filenames that have Danish characters. If you use equal to "iso-8859-1" (cp 28591), + /// the filenames will be correctly encoded in the zip. But, to read that + /// zipfile correctly, you have to specify the same codepage at the time you + /// read it. If try to read that zip file with Windows Explorer or another + /// application that is not flexible with respect to the codepage used to + /// decode filenames in zipfiles, you will get a filename like "Inf°.txt". + /// + /// + /// + /// When using DotNetZip to read a zip archive, and the zip archive uses an + /// arbitrary code page, you must specify the encoding to use before or when + /// the Zipfile is READ. This means you must use a ZipFile.Read() + /// method that allows you to specify a System.Text.Encoding parameter. Setting + /// the ProvisionalAlternateEncoding property after your application has read in + /// the zip archive will not affect the entry names of entries that have already + /// been read in. + /// + /// + /// + /// And now, the exception to the rule described above. One strategy for + /// specifying the code page for a given zip file is to describe the code page + /// in a human-readable form in the Zip comment. For example, the comment may + /// read "Entries in this archive are encoded in the Big5 code page". For + /// maximum interoperability, the zip comment in this case should be encoded + /// in the default, IBM437 code page. In this case, the zip comment is + /// encoded using a different page than the filenames. To do this, Specify + /// ProvisionalAlternateEncoding to your desired region-specific code + /// page, once before adding any entries, and then reset + /// ProvisionalAlternateEncoding to IBM437 before setting the property and calling Save(). + /// + /// + /// + /// + /// This example shows how to read a zip file using the Big-5 Chinese code page + /// (950), and extract each entry in the zip file. For this code to work as + /// desired, the Zipfile must have been created using the big5 code page + /// (CP950). This is typical, for example, when using WinRar on a machine with + /// CP950 set as the default code page. In that case, the names of entries + /// within the Zip archive will be stored in that code page, and reading the zip + /// archive must be done using that code page. If the application did not use + /// the correct code page in ZipFile.Read(), then names of entries within the + /// zip archive would not be correctly retrieved. + /// + /// using (var zip = ZipFile.Read(zipFileName, System.Text.Encoding.GetEncoding("big5"))) + /// { + /// // retrieve and extract an entry using a name encoded with CP950 + /// zip[MyDesiredEntry].Extract("unpack"); + /// } + /// + /// + /// + /// Using zip As ZipFile = ZipFile.Read(ZipToExtract, System.Text.Encoding.GetEncoding("big5")) + /// ' retrieve and extract an entry using a name encoded with CP950 + /// zip(MyDesiredEntry).Extract("unpack") + /// End Using + /// + /// + /// + /// DefaultEncoding + [Obsolete("use AlternateEncoding instead.")] + public System.Text.Encoding ProvisionalAlternateEncoding + { + get + { + if (_alternateEncodingUsage == ZipOption.AsNecessary) + return _alternateEncoding; + return null; + } + set + { + _alternateEncoding = value; + _alternateEncodingUsage = ZipOption.AsNecessary; + } + } + + + /// + /// A Text Encoding to use when encoding the filenames and comments for + /// all the ZipEntry items, during a ZipFile.Save() operation. + /// + /// + /// + /// Whether the encoding specified here is used during the save depends + /// on . + /// + /// + public System.Text.Encoding AlternateEncoding + { + get + { + return _alternateEncoding; + } + set + { + _alternateEncoding = value; + } + } + + + /// + /// A flag that tells if and when this instance should apply + /// AlternateEncoding to encode the filenames and comments associated to + /// of ZipEntry objects contained within this instance. + /// + public ZipOption AlternateEncodingUsage + { + get + { + return _alternateEncodingUsage; + } + set + { + _alternateEncodingUsage = value; + } + } + + + /// + /// The default text encoding used in zip archives. It is numeric 437, also + /// known as IBM437. + /// + /// + public static System.Text.Encoding DefaultEncoding + { + get + { + return _defaultEncoding; + } + } + + + /// + /// Gets or sets the TextWriter to which status messages are delivered + /// for the instance. + /// + /// + /// + /// If the TextWriter is set to a non-null value, then verbose output is sent + /// to the TextWriter during Add, Read, Save and + /// Extract operations. Typically, console applications might use + /// Console.Out and graphical or headless applications might use a + /// System.IO.StringWriter. The output of this is suitable for viewing + /// by humans. + /// + /// + /// + /// + /// In this example, a console application instantiates a ZipFile, then + /// sets the StatusMessageTextWriter to Console.Out. At that + /// point, all verbose status messages for that ZipFile are sent to the + /// console. + /// + /// + /// + /// using (ZipFile zip= ZipFile.Read(FilePath)) + /// { + /// zip.StatusMessageTextWriter= System.Console.Out; + /// // messages are sent to the console during extraction + /// zip.ExtractAll(); + /// } + /// + /// + /// + /// Using zip As ZipFile = ZipFile.Read(FilePath) + /// zip.StatusMessageTextWriter= System.Console.Out + /// 'Status Messages will be sent to the console during extraction + /// zip.ExtractAll() + /// End Using + /// + /// + /// + /// In this example, a Windows Forms application instantiates a + /// ZipFile, then sets the StatusMessageTextWriter to a + /// StringWriter. At that point, all verbose status messages for that + /// ZipFile are sent to the StringWriter. + /// + /// + /// + /// var sw = new System.IO.StringWriter(); + /// using (ZipFile zip= ZipFile.Read(FilePath)) + /// { + /// zip.StatusMessageTextWriter= sw; + /// zip.ExtractAll(); + /// } + /// Console.WriteLine("{0}", sw.ToString()); + /// + /// + /// + /// Dim sw as New System.IO.StringWriter + /// Using zip As ZipFile = ZipFile.Read(FilePath) + /// zip.StatusMessageTextWriter= sw + /// zip.ExtractAll() + /// End Using + /// 'Status Messages are now available in sw + /// + /// + /// + public TextWriter StatusMessageTextWriter + { + get { return _StatusMessageTextWriter; } + set { _StatusMessageTextWriter = value; } + } + + + + + /// + /// Gets or sets the name for the folder to store the temporary file + /// this library writes when saving a zip archive. + /// + /// + /// + /// + /// This library will create a temporary file when saving a Zip archive to a + /// file. This file is written when calling one of the Save() methods + /// that does not save to a stream, or one of the SaveSelfExtractor() + /// methods. + /// + /// + /// + /// By default, the library will create the temporary file in the directory + /// specified for the file itself, via the property or via + /// the method. + /// + /// + /// + /// Setting this property allows applications to override this default + /// behavior, so that the library will create the temporary file in the + /// specified folder. For example, to have the library create the temporary + /// file in the current working directory, regardless where the ZipFile + /// is saved, specfy ".". To revert to the default behavior, set this + /// property to null (Nothing in VB). + /// + /// + /// + /// When setting the property to a non-null value, the folder specified must + /// exist; if it does not an exception is thrown. The application should have + /// write and delete permissions on the folder. The permissions are not + /// explicitly checked ahead of time; if the application does not have the + /// appropriate rights, an exception will be thrown at the time Save() + /// is called. + /// + /// + /// + /// There is no temporary file created when reading a zip archive. When + /// saving to a Stream, there is no temporary file created. For example, if + /// the application is an ASP.NET application and calls Save() + /// specifying the Response.OutputStream as the output stream, there is + /// no temporary file created. + /// + /// + /// + /// + /// Thrown when setting the property if the directory does not exist. + /// + /// + public String TempFileFolder + { + get { return _TempFileFolder; } + + set + { + _TempFileFolder = value; + if (value == null) return; + + if (!Directory.Exists(value)) + throw new FileNotFoundException(String.Format("That directory ({0}) does not exist.", value)); + + } + } + + /// + /// Sets the password to be used on the ZipFile instance. + /// + /// + /// + /// + /// + /// When writing a zip archive, this password is applied to the entries, not + /// to the zip archive itself. It applies to any ZipEntry subsequently + /// added to the ZipFile, using one of the AddFile, + /// AddDirectory, AddEntry, or AddItem methods, etc. + /// When reading a zip archive, this property applies to any entry + /// subsequently extracted from the ZipFile using one of the Extract + /// methods on the ZipFile class. + /// + /// + /// + /// When writing a zip archive, keep this in mind: though the password is set + /// on the ZipFile object, according to the Zip spec, the "directory" of the + /// archive - in other words the list of entries or files contained in the archive - is + /// not encrypted with the password, or protected in any way. If you set the + /// Password property, the password actually applies to individual entries + /// that are added to the archive, subsequent to the setting of this property. + /// The list of filenames in the archive that is eventually created will + /// appear in clear text, but the contents of the individual files are + /// encrypted. This is how Zip encryption works. + /// + /// + /// + /// One simple way around this limitation is to simply double-wrap sensitive + /// filenames: Store the files in a zip file, and then store that zip file + /// within a second, "outer" zip file. If you apply a password to the outer + /// zip file, then readers will be able to see that the outer zip file + /// contains an inner zip file. But readers will not be able to read the + /// directory or file list of the inner zip file. + /// + /// + /// + /// If you set the password on the ZipFile, and then add a set of files + /// to the archive, then each entry is encrypted with that password. You may + /// also want to change the password between adding different entries. If you + /// set the password, add an entry, then set the password to null + /// (Nothing in VB), and add another entry, the first entry is + /// encrypted and the second is not. If you call AddFile(), then set + /// the Password property, then call ZipFile.Save, the file + /// added will not be password-protected, and no warning will be generated. + /// + /// + /// + /// When setting the Password, you may also want to explicitly set the property, to specify how to encrypt the entries added + /// to the ZipFile. If you set the Password to a non-null value and do not + /// set , then PKZip 2.0 ("Weak") encryption is used. + /// This encryption is relatively weak but is very interoperable. If you set + /// the password to a null value (Nothing in VB), Encryption is + /// reset to None. + /// + /// + /// + /// All of the preceding applies to writing zip archives, in other words when + /// you use one of the Save methods. To use this property when reading or an + /// existing ZipFile, do the following: set the Password property on the + /// ZipFile, then call one of the Extract() overloads on the . In this case, the entry is extracted using the + /// Password that is specified on the ZipFile instance. If you + /// have not set the Password property, then the password is + /// null, and the entry is extracted with no password. + /// + /// + /// + /// If you set the Password property on the ZipFile, then call + /// Extract() an entry that has not been encrypted with a password, the + /// password is not used for that entry, and the ZipEntry is extracted + /// as normal. In other words, the password is used only if necessary. + /// + /// + /// + /// The class also has a Password property. It takes precedence + /// over this property on the ZipFile. Typically, you would use the + /// per-entry Password when most entries in the zip archive use one password, + /// and a few entries use a different password. If all entries in the zip + /// file use the same password, then it is simpler to just set this property + /// on the ZipFile itself, whether creating a zip archive or extracting + /// a zip archive. + /// + /// + /// + /// + /// + /// + /// This example creates a zip file, using password protection for the + /// entries, and then extracts the entries from the zip file. When creating + /// the zip file, the Readme.txt file is not protected with a password, but + /// the other two are password-protected as they are saved. During extraction, + /// each file is extracted with the appropriate password. + /// + /// + /// // create a file with encryption + /// using (ZipFile zip = new ZipFile()) + /// { + /// zip.AddFile("ReadMe.txt"); + /// zip.Password= "!Secret1"; + /// zip.AddFile("MapToTheSite-7440-N49th.png"); + /// zip.AddFile("2008-Regional-Sales-Report.pdf"); + /// zip.Save("EncryptedArchive.zip"); + /// } + /// + /// // extract entries that use encryption + /// using (ZipFile zip = ZipFile.Read("EncryptedArchive.zip")) + /// { + /// zip.Password= "!Secret1"; + /// zip.ExtractAll("extractDir"); + /// } + /// + /// + /// + /// + /// Using zip As New ZipFile + /// zip.AddFile("ReadMe.txt") + /// zip.Password = "123456!" + /// zip.AddFile("MapToTheSite-7440-N49th.png") + /// zip.Password= "!Secret1"; + /// zip.AddFile("2008-Regional-Sales-Report.pdf") + /// zip.Save("EncryptedArchive.zip") + /// End Using + /// + /// + /// ' extract entries that use encryption + /// Using (zip as ZipFile = ZipFile.Read("EncryptedArchive.zip")) + /// zip.Password= "!Secret1" + /// zip.ExtractAll("extractDir") + /// End Using + /// + /// + /// + /// + /// + /// ZipFile.Encryption + /// ZipEntry.Password + public String Password + { + set + { + _Password = value; + if (_Password == null) + { + Encryption = EncryptionAlgorithm.None; + } + else if (Encryption == EncryptionAlgorithm.None) + { + Encryption = EncryptionAlgorithm.PkzipWeak; + } + } + private get + { + return _Password; + } + } + + + + + + /// + /// The action the library should take when extracting a file that already + /// exists. + /// + /// + /// + /// + /// This property affects the behavior of the Extract methods (one of the + /// Extract() or ExtractWithPassword() overloads), when + /// extraction would would overwrite an existing filesystem file. If you do + /// not set this property, the library throws an exception when extracting an + /// entry would overwrite an existing file. + /// + /// + /// + /// This property has no effect when extracting to a stream, or when the file + /// to be extracted does not already exist. + /// + /// + /// + public ExtractExistingFileAction ExtractExistingFile + { + get; + set; + } + + + /// + /// The action the library should take when an error is encountered while + /// opening or reading files as they are saved into a zip archive. + /// + /// + /// + /// + /// Errors can occur as a file is being saved to the zip archive. For + /// example, the File.Open may fail, or a File.Read may fail, because of + /// lock conflicts or other reasons. + /// + /// + /// + /// The first problem might occur after having called AddDirectory() on a + /// directory that contains a Clipper .dbf file; the file is locked by + /// Clipper and cannot be opened for read by another process. An example of + /// the second problem might occur when trying to zip a .pst file that is in + /// use by Microsoft Outlook. Outlook locks a range on the file, which allows + /// other processes to open the file, but not read it in its entirety. + /// + /// + /// + /// This property tells DotNetZip what you would like to do in the case of + /// these errors. The primary options are: ZipErrorAction.Throw to + /// throw an exception (this is the default behavior if you don't set this + /// property); ZipErrorAction.Skip to Skip the file for which there + /// was an error and continue saving; ZipErrorAction.Retry to Retry + /// the entry that caused the problem; or + /// ZipErrorAction.InvokeErrorEvent to invoke an event handler. + /// + /// + /// + /// This property is implicitly set to ZipErrorAction.InvokeErrorEvent + /// if you add a handler to the event. If you set + /// this property to something other than + /// ZipErrorAction.InvokeErrorEvent, then the ZipError + /// event is implicitly cleared. What it means is you can set one or the + /// other (or neither), depending on what you want, but you never need to set + /// both. + /// + /// + /// + /// As with some other properties on the ZipFile class, like , , and , setting this property on a ZipFile + /// instance will cause the specified ZipErrorAction to be used on all + /// items that are subsequently added to the + /// ZipFile instance. If you set this property after you have added + /// items to the ZipFile, but before you have called Save(), + /// those items will not use the specified error handling action. + /// + /// + /// + /// If you want to handle any errors that occur with any entry in the zip + /// file in the same way, then set this property once, before adding any + /// entries to the zip archive. + /// + /// + /// + /// If you set this property to ZipErrorAction.Skip and you'd like to + /// learn which files may have been skipped after a Save(), you can + /// set the on the ZipFile before + /// calling Save(). A message will be emitted into that writer for + /// each skipped file, if any. + /// + /// + /// + /// + /// + /// This example shows how to tell DotNetZip to skip any files for which an + /// error is generated during the Save(). + /// + /// Public Sub SaveZipFile() + /// Dim SourceFolder As String = "fodder" + /// Dim DestFile As String = "eHandler.zip" + /// Dim sw as New StringWriter + /// Using zipArchive As ZipFile = New ZipFile + /// ' Tell DotNetZip to skip any files for which it encounters an error + /// zipArchive.ZipErrorAction = ZipErrorAction.Skip + /// zipArchive.StatusMessageTextWriter = sw + /// zipArchive.AddDirectory(SourceFolder) + /// zipArchive.Save(DestFile) + /// End Using + /// ' examine sw here to see any messages + /// End Sub + /// + /// + /// + /// + /// + /// + + public ZipErrorAction ZipErrorAction + { + get + { + if (ZipError != null) + _zipErrorAction = ZipErrorAction.InvokeErrorEvent; + return _zipErrorAction; + } + set + { + _zipErrorAction = value; + if (_zipErrorAction != ZipErrorAction.InvokeErrorEvent && ZipError != null) + ZipError = null; + } + } + + + /// + /// The Encryption to use for entries added to the ZipFile. + /// + /// + /// + /// + /// Set this when creating a zip archive, or when updating a zip archive. The + /// specified Encryption is applied to the entries subsequently added to the + /// ZipFile instance. Applications do not need to set the + /// Encryption property when reading or extracting a zip archive. + /// + /// + /// + /// If you set this to something other than EncryptionAlgorithm.None, you + /// will also need to set the . + /// + /// + /// + /// As with some other properties on the ZipFile class, like and , setting this + /// property on a ZipFile instance will cause the specified + /// EncryptionAlgorithm to be used on all items + /// that are subsequently added to the ZipFile instance. In other + /// words, if you set this property after you have added items to the + /// ZipFile, but before you have called Save(), those items will + /// not be encrypted or protected with a password in the resulting zip + /// archive. To get a zip archive with encrypted entries, set this property, + /// along with the property, before calling + /// AddFile, AddItem, or AddDirectory (etc.) on the + /// ZipFile instance. + /// + /// + /// + /// If you read a ZipFile, you can modify the Encryption on an + /// encrypted entry, only by setting the Encryption property on the + /// ZipEntry itself. Setting the Encryption property on the + /// ZipFile, once it has been created via a call to + /// ZipFile.Read(), does not affect entries that were previously read. + /// + /// + /// + /// For example, suppose you read a ZipFile, and there is an encrypted + /// entry. Setting the Encryption property on that ZipFile and + /// then calling Save() on the ZipFile does not update the + /// Encryption used for the entries in the archive. Neither is an + /// exception thrown. Instead, what happens during the Save() is that + /// all previously existing entries are copied through to the new zip archive, + /// with whatever encryption and password that was used when originally + /// creating the zip archive. Upon re-reading that archive, to extract + /// entries, applications should use the original password or passwords, if + /// any. + /// + /// + /// + /// Suppose an application reads a ZipFile, and there is an encrypted + /// entry. Setting the Encryption property on that ZipFile and + /// then adding new entries (via AddFile(), AddEntry(), etc) + /// and then calling Save() on the ZipFile does not update the + /// Encryption on any of the entries that had previously been in the + /// ZipFile. The Encryption property applies only to the + /// newly-added entries. + /// + /// + /// + /// + /// + /// + /// This example creates a zip archive that uses encryption, and then extracts + /// entries from the archive. When creating the zip archive, the ReadMe.txt + /// file is zipped without using a password or encryption. The other files + /// use encryption. + /// + /// + /// + /// // Create a zip archive with AES Encryption. + /// using (ZipFile zip = new ZipFile()) + /// { + /// zip.AddFile("ReadMe.txt"); + /// zip.Encryption= EncryptionAlgorithm.WinZipAes256; + /// zip.Password= "Top.Secret.No.Peeking!"; + /// zip.AddFile("7440-N49th.png"); + /// zip.AddFile("2008-Regional-Sales-Report.pdf"); + /// zip.Save("EncryptedArchive.zip"); + /// } + /// + /// // Extract a zip archive that uses AES Encryption. + /// // You do not need to specify the algorithm during extraction. + /// using (ZipFile zip = ZipFile.Read("EncryptedArchive.zip")) + /// { + /// zip.Password= "Top.Secret.No.Peeking!"; + /// zip.ExtractAll("extractDirectory"); + /// } + /// + /// + /// + /// ' Create a zip that uses Encryption. + /// Using zip As New ZipFile() + /// zip.Encryption= EncryptionAlgorithm.WinZipAes256 + /// zip.Password= "Top.Secret.No.Peeking!" + /// zip.AddFile("ReadMe.txt") + /// zip.AddFile("7440-N49th.png") + /// zip.AddFile("2008-Regional-Sales-Report.pdf") + /// zip.Save("EncryptedArchive.zip") + /// End Using + /// + /// ' Extract a zip archive that uses AES Encryption. + /// ' You do not need to specify the algorithm during extraction. + /// Using (zip as ZipFile = ZipFile.Read("EncryptedArchive.zip")) + /// zip.Password= "Top.Secret.No.Peeking!" + /// zip.ExtractAll("extractDirectory") + /// End Using + /// + /// + /// + /// + /// ZipFile.Password + /// ZipEntry.Encryption + public EncryptionAlgorithm Encryption + { + get + { + return _Encryption; + } + set + { + if (value == EncryptionAlgorithm.Unsupported) + throw new InvalidOperationException("You may not set Encryption to that value."); + _Encryption = value; + } + } + + + + /// + /// A callback that allows the application to specify the compression level + /// to use for entries subsequently added to the zip archive. + /// + /// + /// + /// + /// + /// With this callback, the DotNetZip library allows the application to + /// determine whether compression will be used, at the time of the + /// Save. This may be useful if the application wants to favor + /// speed over size, and wants to defer the decision until the time of + /// Save. + /// + /// + /// + /// Typically applications set the property on + /// the ZipFile or on each ZipEntry to determine the level of + /// compression used. This is done at the time the entry is added to the + /// ZipFile. Setting the property to + /// Ionic.Zlib.CompressionLevel.None means no compression will be used. + /// + /// + /// + /// This callback allows the application to defer the decision on the + /// CompressionLevel to use, until the time of the call to + /// ZipFile.Save(). The callback is invoked once per ZipEntry, + /// at the time the data for the entry is being written out as part of a + /// Save() operation. The application can use whatever criteria it + /// likes in determining the level to return. For example, an application may + /// wish that no .mp3 files should be compressed, because they are already + /// compressed and the extra compression is not worth the CPU time incurred, + /// and so can return None for all .mp3 entries. + /// + /// + /// + /// The library determines whether compression will be attempted for an entry + /// this way: If the entry is a zero length file, or a directory, no + /// compression is used. Otherwise, if this callback is set, it is invoked + /// and the CompressionLevel is set to the return value. If this + /// callback has not been set, then the previously set value for + /// CompressionLevel is used. + /// + /// + /// + public SetCompressionCallback SetCompression + { + get; + set; + } + + + /// + /// The maximum size of an output segment, when saving a split Zip file. + /// + /// + /// + /// Set this to a non-zero value before calling or to specify that the ZipFile should be saved as a + /// split archive, also sometimes called a spanned archive. Some also + /// call them multi-file archives. + /// + /// + /// + /// A split zip archive is saved in a set of discrete filesystem files, + /// rather than in a single file. This is handy when transmitting the + /// archive in email or some other mechanism that has a limit to the size of + /// each file. The first file in a split archive will be named + /// basename.z01, the second will be named basename.z02, and + /// so on. The final file is named basename.zip. According to the zip + /// specification from PKWare, the minimum value is 65536, for a 64k segment + /// size. The maximum number of segments allows in a split archive is 99. + /// + /// + /// + /// The value of this property determines the maximum size of a split + /// segment when writing a split archive. For example, suppose you have a + /// ZipFile that would save to a single file of 200k. If you set the + /// MaxOutputSegmentSize to 65536 before calling Save(), you + /// will get four distinct output files. On the other hand if you set this + /// property to 256k, then you will get a single-file archive for that + /// ZipFile. + /// + /// + /// + /// The size of each split output file will be as large as possible, up to + /// the maximum size set here. The zip specification requires that some data + /// fields in a zip archive may not span a split boundary, and an output + /// segment may be smaller than the maximum if necessary to avoid that + /// problem. Also, obviously the final segment of the archive may be smaller + /// than the maximum segment size. Segments will never be larger than the + /// value set with this property. + /// + /// + /// + /// You can save a split Zip file only when saving to a regular filesystem + /// file. It's not possible to save a split zip file as a self-extracting + /// archive, nor is it possible to save a split zip file to a stream. When + /// saving to a SFX or to a Stream, this property is ignored. + /// + /// + /// + /// About interoperability: Split or spanned zip files produced by DotNetZip + /// can be read by WinZip or PKZip, and vice-versa. Segmented zip files may + /// not be readable by other tools, if those other tools don't support zip + /// spanning or splitting. When in doubt, test. I don't believe Windows + /// Explorer can extract a split archive. + /// + /// + /// + /// This property has no effect when reading a split archive. You can read + /// a split archive in the normal way with DotNetZip. + /// + /// + /// + /// When saving a zip file, if you want a regular zip file rather than a + /// split zip file, don't set this property, or set it to Zero. + /// + /// + /// + /// If you read a split archive, with and + /// then subsequently call ZipFile.Save(), unless you set this + /// property before calling Save(), you will get a normal, + /// single-file archive. + /// + /// + /// + /// + public Int32 MaxOutputSegmentSize + { + get + { + return _maxOutputSegmentSize; + } + set + { + if (value < 65536 && value != 0) + throw new ZipException("The minimum acceptable segment size is 65536."); + _maxOutputSegmentSize = value; + } + } + + + /// + /// Returns the number of segments used in the most recent Save() operation. + /// + /// + /// + /// This is normally zero, unless you have set the property. If you have set , and then you save a file, after the call to + /// Save() completes, you can read this value to learn the number of segments that + /// were created. + /// + /// + /// If you call Save("Archive.zip"), and it creates 5 segments, then you + /// will have filesystem files named Archive.z01, Archive.z02, Archive.z03, + /// Archive.z04, and Archive.zip, and the value of this property will be 5. + /// + /// + /// + public Int32 NumberOfSegmentsForMostRecentSave + { + get + { + return unchecked((Int32)_numberOfSegmentsForMostRecentSave + 1); + } + } + + +#if !NETCF + /// + /// The size threshold for an entry, above which a parallel deflate is used. + /// + /// + /// + /// + /// + /// DotNetZip will use multiple threads to compress any ZipEntry, + /// if the entry is larger than the given size. Zero means "always + /// use parallel deflate", while -1 means "never use parallel + /// deflate". The default value for this property is 512k. Aside + /// from the special values of 0 and 1, the minimum value is 65536. + /// + /// + /// + /// If the entry size cannot be known before compression, as with a + /// read-forward stream, then Parallel deflate will never be + /// performed, unless the value of this property is zero. + /// + /// + /// + /// A parallel deflate operations will speed up the compression of + /// large files, on computers with multiple CPUs or multiple CPU + /// cores. For files above 1mb, on a dual core or dual-cpu (2p) + /// machine, the time required to compress the file can be 70% of the + /// single-threaded deflate. For very large files on 4p machines the + /// compression can be done in 30% of the normal time. The downside + /// is that parallel deflate consumes extra memory during the deflate, + /// and the deflation is not as effective. + /// + /// + /// + /// Parallel deflate tends to yield slightly less compression when + /// compared to as single-threaded deflate; this is because the original + /// data stream is split into multiple independent buffers, each of which + /// is compressed in parallel. But because they are treated + /// independently, there is no opportunity to share compression + /// dictionaries. For that reason, a deflated stream may be slightly + /// larger when compressed using parallel deflate, as compared to a + /// traditional single-threaded deflate. Sometimes the increase over the + /// normal deflate is as much as 5% of the total compressed size. For + /// larger files it can be as small as 0.1%. + /// + /// + /// + /// Multi-threaded compression does not give as much an advantage when + /// using Encryption. This is primarily because encryption tends to slow + /// down the entire pipeline. Also, multi-threaded compression gives less + /// of an advantage when using lower compression levels, for example . You may have to + /// perform some tests to determine the best approach for your situation. + /// + /// + /// + /// + /// + /// + public long ParallelDeflateThreshold + { + set + { + if ((value != 0) && (value != -1) && (value < 64 * 1024)) + throw new ArgumentOutOfRangeException("ParallelDeflateThreshold should be -1, 0, or > 65536"); + _ParallelDeflateThreshold = value; + } + get + { + return _ParallelDeflateThreshold; + } + } + + /// + /// The maximum number of buffer pairs to use when performing + /// parallel compression. + /// + /// + /// + /// + /// This property sets an upper limit on the number of memory + /// buffer pairs to create when performing parallel + /// compression. The implementation of the parallel + /// compression stream allocates multiple buffers to + /// facilitate parallel compression. As each buffer fills up, + /// the stream uses + /// ThreadPool.QueueUserWorkItem() to compress those + /// buffers in a background threadpool thread. After a buffer + /// is compressed, it is re-ordered and written to the output + /// stream. + /// + /// + /// + /// A higher number of buffer pairs enables a higher degree of + /// parallelism, which tends to increase the speed of compression on + /// multi-cpu computers. On the other hand, a higher number of buffer + /// pairs also implies a larger memory consumption, more active worker + /// threads, and a higher cpu utilization for any compression. This + /// property enables the application to limit its memory consumption and + /// CPU utilization behavior depending on requirements. + /// + /// + /// + /// For each compression "task" that occurs in parallel, there are 2 + /// buffers allocated: one for input and one for output. This property + /// sets a limit for the number of pairs. The total amount of storage + /// space allocated for buffering will then be (N*S*2), where N is the + /// number of buffer pairs, S is the size of each buffer (). By default, DotNetZip allocates 4 buffer + /// pairs per CPU core, so if your machine has 4 cores, and you retain + /// the default buffer size of 128k, then the + /// ParallelDeflateOutputStream will use 4 * 4 * 2 * 128kb of buffer + /// memory in total, or 4mb, in blocks of 128kb. If you then set this + /// property to 8, then the number will be 8 * 2 * 128kb of buffer + /// memory, or 2mb. + /// + /// + /// + /// CPU utilization will also go up with additional buffers, because a + /// larger number of buffer pairs allows a larger number of background + /// threads to compress in parallel. If you find that parallel + /// compression is consuming too much memory or CPU, you can adjust this + /// value downward. + /// + /// + /// + /// The default value is 16. Different values may deliver better or + /// worse results, depending on your priorities and the dynamic + /// performance characteristics of your storage and compute resources. + /// + /// + /// + /// This property is not the number of buffer pairs to use; it is an + /// upper limit. An illustration: Suppose you have an application that + /// uses the default value of this property (which is 16), and it runs + /// on a machine with 2 CPU cores. In that case, DotNetZip will allocate + /// 4 buffer pairs per CPU core, for a total of 8 pairs. The upper + /// limit specified by this property has no effect. + /// + /// + /// + /// The application can set this value at any time + /// before calling ZipFile.Save(). + /// + /// + /// + /// + /// + public int ParallelDeflateMaxBufferPairs + { + get + { + return _maxBufferPairs; + } + set + { + if (value < 4) + throw new ArgumentOutOfRangeException("ParallelDeflateMaxBufferPairs", + "Value must be 4 or greater."); + _maxBufferPairs = value; + } + } +#endif + + + /// Provides a string representation of the instance. + /// a string representation of the instance. + public override String ToString() + { + return String.Format("ZipFile::{0}", Name); + } + + + /// + /// Returns the version number on the DotNetZip assembly. + /// + /// + /// + /// + /// This property is exposed as a convenience. Callers could also get the + /// version value by retrieving GetName().Version on the + /// System.Reflection.Assembly object pointing to the DotNetZip + /// assembly. But sometimes it is not clear which assembly is being loaded. + /// This property makes it clear. + /// + /// + /// This static property is primarily useful for diagnostic purposes. + /// + /// + public static System.Version LibraryVersion + { + get + { + return System.Reflection.Assembly.GetExecutingAssembly().GetName().Version; + } + } + + internal void NotifyEntryChanged() + { + _contentsChanged = true; + } + + + internal Stream StreamForDiskNumber(uint diskNumber) + { + if (diskNumber + 1 == this._diskNumberWithCd || + (diskNumber == 0 && this._diskNumberWithCd == 0)) + { + //return (this.ReadStream as FileStream); + return this.ReadStream; + } + return ZipSegmentedStream.ForReading(this._readName ?? this._name, + diskNumber, _diskNumberWithCd); + } + + + + // called by ZipEntry in ZipEntry.Extract(), when there is no stream set for the + // ZipEntry. + internal void Reset(bool whileSaving) + { + if (_JustSaved) + { + // read in the just-saved zip archive + using (ZipFile x = new ZipFile()) + { + // workitem 10735 + x._readName = x._name = whileSaving + ? (this._readName ?? this._name) + : this._name; + x.AlternateEncoding = this.AlternateEncoding; + x.AlternateEncodingUsage = this.AlternateEncodingUsage; + ReadIntoInstance(x); + // copy the contents of the entries. + // cannot just replace the entries - the app may be holding them + foreach (ZipEntry e1 in x) + { + foreach (ZipEntry e2 in this) + { + if (e1.FileName == e2.FileName) + { + e2.CopyMetaData(e1); + break; + } + } + } + } + _JustSaved = false; + } + } + + + #endregion + + #region Constructors + + /// + /// Creates a new ZipFile instance, using the specified filename. + /// + /// + /// + /// + /// Applications can use this constructor to create a new ZipFile for writing, + /// or to slurp in an existing zip archive for read and update purposes. + /// + /// + /// + /// To create a new zip archive, an application can call this constructor, + /// passing the name of a file that does not exist. The name may be a fully + /// qualified path. Then the application can add directories or files to the + /// ZipFile via AddDirectory(), AddFile(), AddItem() + /// and then write the zip archive to the disk by calling Save(). The + /// zip file is not actually opened and written to the disk until the + /// application calls ZipFile.Save(). At that point the new zip file + /// with the given name is created. + /// + /// + /// + /// If you won't know the name of the Zipfile until the time you call + /// ZipFile.Save(), or if you plan to save to a stream (which has no + /// name), then you should use the no-argument constructor. + /// + /// + /// + /// The application can also call this constructor to read an existing zip + /// archive. passing the name of a valid zip file that does exist. But, it's + /// better form to use the static method, + /// passing the name of the zip file, because using ZipFile.Read() in + /// your code communicates very clearly what you are doing. In either case, + /// the file is then read into the ZipFile instance. The app can then + /// enumerate the entries or can modify the zip file, for example adding + /// entries, removing entries, changing comments, and so on. + /// + /// + /// + /// One advantage to this parameterized constructor: it allows applications to + /// use the same code to add items to a zip archive, regardless of whether the + /// zip file exists. + /// + /// + /// + /// Instances of the ZipFile class are not multi-thread safe. You may + /// not party on a single instance with multiple threads. You may have + /// multiple threads that each use a distinct ZipFile instance, or you + /// can synchronize multi-thread access to a single instance. + /// + /// + /// + /// By the way, since DotNetZip is so easy to use, don't you think you should + /// donate $5 or $10? + /// + /// + /// + /// + /// + /// Thrown if name refers to an existing file that is not a valid zip file. + /// + /// + /// + /// This example shows how to create a zipfile, and add a few files into it. + /// + /// String ZipFileToCreate = "archive1.zip"; + /// String DirectoryToZip = "c:\\reports"; + /// using (ZipFile zip = new ZipFile()) + /// { + /// // Store all files found in the top level directory, into the zip archive. + /// String[] filenames = System.IO.Directory.GetFiles(DirectoryToZip); + /// zip.AddFiles(filenames, "files"); + /// zip.Save(ZipFileToCreate); + /// } + /// + /// + /// + /// Dim ZipFileToCreate As String = "archive1.zip" + /// Dim DirectoryToZip As String = "c:\reports" + /// Using zip As ZipFile = New ZipFile() + /// Dim filenames As String() = System.IO.Directory.GetFiles(DirectoryToZip) + /// zip.AddFiles(filenames, "files") + /// zip.Save(ZipFileToCreate) + /// End Using + /// + /// + /// + /// The filename to use for the new zip archive. + /// + public ZipFile(string fileName) + { + try + { + _InitInstance(fileName, null); + } + catch (Exception e1) + { + throw new ZipException(String.Format("Could not read {0} as a zip file", fileName), e1); + } + } + + + /// + /// Creates a new ZipFile instance, using the specified name for the + /// filename, and the specified Encoding. + /// + /// + /// + /// + /// See the documentation on the ZipFile + /// constructor that accepts a single string argument for basic + /// information on all the ZipFile constructors. + /// + /// + /// + /// The Encoding is used as the default alternate encoding for entries with + /// filenames or comments that cannot be encoded with the IBM437 code page. + /// This is equivalent to setting the property on the ZipFile + /// instance after construction. + /// + /// + /// + /// Instances of the ZipFile class are not multi-thread safe. You may + /// not party on a single instance with multiple threads. You may have + /// multiple threads that each use a distinct ZipFile instance, or you + /// can synchronize multi-thread access to a single instance. + /// + /// + /// + /// + /// + /// Thrown if name refers to an existing file that is not a valid zip file. + /// + /// + /// The filename to use for the new zip archive. + /// The Encoding is used as the default alternate + /// encoding for entries with filenames or comments that cannot be encoded + /// with the IBM437 code page. + public ZipFile(string fileName, System.Text.Encoding encoding) + { + try + { + AlternateEncoding = encoding; + AlternateEncodingUsage = ZipOption.Always; + _InitInstance(fileName, null); + } + catch (Exception e1) + { + throw new ZipException(String.Format("{0} is not a valid zip file", fileName), e1); + } + } + + + + /// + /// Create a zip file, without specifying a target filename or stream to save to. + /// + /// + /// + /// + /// See the documentation on the ZipFile + /// constructor that accepts a single string argument for basic + /// information on all the ZipFile constructors. + /// + /// + /// + /// After instantiating with this constructor and adding entries to the + /// archive, the application should call or + /// to save to a file or a + /// stream, respectively. The application can also set the + /// property and then call the no-argument method. (This + /// is the preferred approach for applications that use the library through + /// COM interop.) If you call the no-argument method + /// without having set the Name of the ZipFile, either through + /// the parameterized constructor or through the explicit property , the + /// Save() will throw, because there is no place to save the file. + /// + /// + /// Instances of the ZipFile class are not multi-thread safe. You may + /// have multiple threads that each use a distinct ZipFile instance, or + /// you can synchronize multi-thread access to a single instance. + /// + /// + /// + /// + /// This example creates a Zip archive called Backup.zip, containing all the files + /// in the directory DirectoryToZip. Files within subdirectories are not zipped up. + /// + /// using (ZipFile zip = new ZipFile()) + /// { + /// // Store all files found in the top level directory, into the zip archive. + /// // note: this code does not recurse subdirectories! + /// String[] filenames = System.IO.Directory.GetFiles(DirectoryToZip); + /// zip.AddFiles(filenames, "files"); + /// zip.Save("Backup.zip"); + /// } + /// + /// + /// + /// Using zip As New ZipFile + /// ' Store all files found in the top level directory, into the zip archive. + /// ' note: this code does not recurse subdirectories! + /// Dim filenames As String() = System.IO.Directory.GetFiles(DirectoryToZip) + /// zip.AddFiles(filenames, "files") + /// zip.Save("Backup.zip") + /// End Using + /// + /// + public ZipFile() + { + _InitInstance(null, null); + } + + + /// + /// Create a zip file, specifying a text Encoding, but without specifying a + /// target filename or stream to save to. + /// + /// + /// + /// + /// See the documentation on the ZipFile + /// constructor that accepts a single string argument for basic + /// information on all the ZipFile constructors. + /// + /// + /// + /// + /// + /// The Encoding is used as the default alternate encoding for entries with + /// filenames or comments that cannot be encoded with the IBM437 code page. + /// + public ZipFile(System.Text.Encoding encoding) + { + AlternateEncoding = encoding; + AlternateEncodingUsage = ZipOption.Always; + _InitInstance(null, null); + } + + + /// + /// Creates a new ZipFile instance, using the specified name for the + /// filename, and the specified status message writer. + /// + /// + /// + /// + /// See the documentation on the ZipFile + /// constructor that accepts a single string argument for basic + /// information on all the ZipFile constructors. + /// + /// + /// + /// This version of the constructor allows the caller to pass in a TextWriter, + /// to which verbose messages will be written during extraction or creation of + /// the zip archive. A console application may wish to pass + /// System.Console.Out to get messages on the Console. A graphical or headless + /// application may wish to capture the messages in a different + /// TextWriter, for example, a StringWriter, and then display + /// the messages in a TextBox, or generate an audit log of ZipFile operations. + /// + /// + /// + /// To encrypt the data for the files added to the ZipFile instance, + /// set the Password property after creating the ZipFile instance. + /// + /// + /// + /// Instances of the ZipFile class are not multi-thread safe. You may + /// not party on a single instance with multiple threads. You may have + /// multiple threads that each use a distinct ZipFile instance, or you + /// can synchronize multi-thread access to a single instance. + /// + /// + /// + /// + /// + /// Thrown if name refers to an existing file that is not a valid zip file. + /// + /// + /// + /// + /// using (ZipFile zip = new ZipFile("Backup.zip", Console.Out)) + /// { + /// // Store all files found in the top level directory, into the zip archive. + /// // note: this code does not recurse subdirectories! + /// // Status messages will be written to Console.Out + /// String[] filenames = System.IO.Directory.GetFiles(DirectoryToZip); + /// zip.AddFiles(filenames); + /// zip.Save(); + /// } + /// + /// + /// + /// Using zip As New ZipFile("Backup.zip", Console.Out) + /// ' Store all files found in the top level directory, into the zip archive. + /// ' note: this code does not recurse subdirectories! + /// ' Status messages will be written to Console.Out + /// Dim filenames As String() = System.IO.Directory.GetFiles(DirectoryToZip) + /// zip.AddFiles(filenames) + /// zip.Save() + /// End Using + /// + /// + /// + /// The filename to use for the new zip archive. + /// A TextWriter to use for writing + /// verbose status messages. + public ZipFile(string fileName, TextWriter statusMessageWriter) + { + try + { + _InitInstance(fileName, statusMessageWriter); + } + catch (Exception e1) + { + throw new ZipException(String.Format("{0} is not a valid zip file", fileName), e1); + } + } + + + /// + /// Creates a new ZipFile instance, using the specified name for the + /// filename, the specified status message writer, and the specified Encoding. + /// + /// + /// + /// + /// This constructor works like the ZipFile + /// constructor that accepts a single string argument. See that + /// reference for detail on what this constructor does. + /// + /// + /// + /// This version of the constructor allows the caller to pass in a + /// TextWriter, and an Encoding. The TextWriter will collect + /// verbose messages that are generated by the library during extraction or + /// creation of the zip archive. A console application may wish to pass + /// System.Console.Out to get messages on the Console. A graphical or + /// headless application may wish to capture the messages in a different + /// TextWriter, for example, a StringWriter, and then display + /// the messages in a TextBox, or generate an audit log of + /// ZipFile operations. + /// + /// + /// + /// The Encoding is used as the default alternate encoding for entries + /// with filenames or comments that cannot be encoded with the IBM437 code + /// page. This is a equivalent to setting the property on the ZipFile + /// instance after construction. + /// + /// + /// + /// To encrypt the data for the files added to the ZipFile instance, + /// set the Password property after creating the ZipFile + /// instance. + /// + /// + /// + /// Instances of the ZipFile class are not multi-thread safe. You may + /// not party on a single instance with multiple threads. You may have + /// multiple threads that each use a distinct ZipFile instance, or you + /// can synchronize multi-thread access to a single instance. + /// + /// + /// + /// + /// + /// Thrown if fileName refers to an existing file that is not a valid zip file. + /// + /// + /// The filename to use for the new zip archive. + /// A TextWriter to use for writing verbose + /// status messages. + /// + /// The Encoding is used as the default alternate encoding for entries with + /// filenames or comments that cannot be encoded with the IBM437 code page. + /// + public ZipFile(string fileName, TextWriter statusMessageWriter, + System.Text.Encoding encoding) + { + try + { + AlternateEncoding = encoding; + AlternateEncodingUsage = ZipOption.Always; + _InitInstance(fileName, statusMessageWriter); + } + catch (Exception e1) + { + throw new ZipException(String.Format("{0} is not a valid zip file", fileName), e1); + } + } + + + + + /// + /// Initialize a ZipFile instance by reading in a zip file. + /// + /// + /// + /// + /// + /// This method is primarily useful from COM Automation environments, when + /// reading or extracting zip files. In COM, it is not possible to invoke + /// parameterized constructors for a class. A COM Automation application can + /// update a zip file by using the default (no argument) + /// constructor, then calling Initialize() to read the contents + /// of an on-disk zip archive into the ZipFile instance. + /// + /// + /// + /// .NET applications are encouraged to use the ZipFile.Read() methods + /// for better clarity. + /// + /// + /// + /// the name of the existing zip file to read in. + public void Initialize(string fileName) + { + try + { + _InitInstance(fileName, null); + } + catch (Exception e1) + { + throw new ZipException(String.Format("{0} is not a valid zip file", fileName), e1); + } + } + + + + private void _initEntriesDictionary() + { + // workitem 9868 + StringComparer sc = (CaseSensitiveRetrieval) ? StringComparer.Ordinal : StringComparer.OrdinalIgnoreCase; + _entries = (_entries == null) + ? new Dictionary(sc) + : new Dictionary(_entries, sc); + } + + + private void _InitInstance(string zipFileName, TextWriter statusMessageWriter) + { + // create a new zipfile + _name = zipFileName; + _StatusMessageTextWriter = statusMessageWriter; + _contentsChanged = true; + AddDirectoryWillTraverseReparsePoints = true; // workitem 8617 + CompressionLevel = Ionic.Zlib.CompressionLevel.Default; +#if !NETCF + ParallelDeflateThreshold = 512 * 1024; +#endif + // workitem 7685, 9868 + _initEntriesDictionary(); + + if (File.Exists(_name)) + { + if (FullScan) + ReadIntoInstance_Orig(this); + else + ReadIntoInstance(this); + this._fileAlreadyExists = true; + } + + return; + } + #endregion + + + + #region Indexers and Collections + + private List ZipEntriesAsList + { + get + { + if (_zipEntriesAsList == null) + _zipEntriesAsList = new List(_entries.Values); + return _zipEntriesAsList; + } + } + + /// + /// This is an integer indexer into the Zip archive. + /// + /// + /// + /// + /// This property is read-only. + /// + /// + /// + /// Internally, the ZipEntry instances that belong to the + /// ZipFile are stored in a Dictionary. When you use this + /// indexer the first time, it creates a read-only + /// List<ZipEntry> from the Dictionary.Values Collection. + /// If at any time you modify the set of entries in the ZipFile, + /// either by adding an entry, removing an entry, or renaming an + /// entry, a new List will be created, and the numeric indexes for the + /// remaining entries may be different. + /// + /// + /// + /// This means you cannot rename any ZipEntry from + /// inside an enumeration of the zip file. + /// + /// + /// + /// The index value. + /// + /// + /// + /// + /// + /// The ZipEntry within the Zip archive at the specified index. If the + /// entry does not exist in the archive, this indexer throws. + /// + /// + public ZipEntry this[int ix] + { + // workitem 6402 + get + { + return ZipEntriesAsList[ix]; + } + } + + + /// + /// This is a name-based indexer into the Zip archive. + /// + /// + /// + /// + /// This property is read-only. + /// + /// + /// + /// The property on the ZipFile + /// determines whether retrieval via this indexer is done via case-sensitive + /// comparisons. By default, retrieval is not case sensitive. This makes + /// sense on Windows, in which filesystems are not case sensitive. + /// + /// + /// + /// Regardless of case-sensitivity, it is not always the case that + /// this[value].FileName == value. In other words, the FileName + /// property of the ZipEntry retrieved with this indexer, may or may + /// not be equal to the index value. + /// + /// + /// + /// This is because DotNetZip performs a normalization of filenames passed to + /// this indexer, before attempting to retrieve the item. That normalization + /// includes: removal of a volume letter and colon, swapping backward slashes + /// for forward slashes. So, zip["dir1\\entry1.txt"].FileName == + /// "dir1/entry.txt". + /// + /// + /// + /// Directory entries in the zip file may be retrieved via this indexer only + /// with names that have a trailing slash. DotNetZip automatically appends a + /// trailing slash to the names of any directory entries added to a zip. + /// + /// + /// + /// + /// + /// This example extracts only the entries in a zip file that are .txt files. + /// + /// using (ZipFile zip = ZipFile.Read("PackedDocuments.zip")) + /// { + /// foreach (string s1 in zip.EntryFilenames) + /// { + /// if (s1.EndsWith(".txt")) + /// zip[s1].Extract("textfiles"); + /// } + /// } + /// + /// + /// Using zip As ZipFile = ZipFile.Read("PackedDocuments.zip") + /// Dim s1 As String + /// For Each s1 In zip.EntryFilenames + /// If s1.EndsWith(".txt") Then + /// zip(s1).Extract("textfiles") + /// End If + /// Next + /// End Using + /// + /// + /// + /// + /// + /// Thrown if the caller attempts to assign a non-null value to the indexer. + /// + /// + /// + /// The name of the file, including any directory path, to retrieve from the + /// zip. The filename match is not case-sensitive by default; you can use the + /// property to change this behavior. The + /// pathname can use forward-slashes or backward slashes. + /// + /// + /// + /// The ZipEntry within the Zip archive, given by the specified + /// filename. If the named entry does not exist in the archive, this indexer + /// returns null (Nothing in VB). + /// + /// + public ZipEntry this[String fileName] + { + get + { + var key = SharedUtilities.NormalizePathForUseInZipFile(fileName); + if (_entries.ContainsKey(key)) + return _entries[key]; + // workitem 11056 + key = key.Replace("/", "\\"); + if (_entries.ContainsKey(key)) + return _entries[key]; + return null; + +#if MESSY + foreach (ZipEntry e in _entries.Values) + { + if (this.CaseSensitiveRetrieval) + { + // check for the file match with a case-sensitive comparison. + if (e.FileName == fileName) return e; + // also check for equivalence + if (fileName.Replace("\\", "/") == e.FileName) return e; + if (e.FileName.Replace("\\", "/") == fileName) return e; + + // check for a difference only in trailing slash + if (e.FileName.EndsWith("/")) + { + var fileNameNoSlash = e.FileName.Trim("/".ToCharArray()); + if (fileNameNoSlash == fileName) return e; + // also check for equivalence + if (fileName.Replace("\\", "/") == fileNameNoSlash) return e; + if (fileNameNoSlash.Replace("\\", "/") == fileName) return e; + } + + } + else + { + // check for the file match in a case-insensitive manner. + if (String.Compare(e.FileName, fileName, StringComparison.CurrentCultureIgnoreCase) == 0) return e; + // also check for equivalence + if (String.Compare(fileName.Replace("\\", "/"), e.FileName, StringComparison.CurrentCultureIgnoreCase) == 0) return e; + if (String.Compare(e.FileName.Replace("\\", "/"), fileName, StringComparison.CurrentCultureIgnoreCase) == 0) return e; + + // check for a difference only in trailing slash + if (e.FileName.EndsWith("/")) + { + var fileNameNoSlash = e.FileName.Trim("/".ToCharArray()); + + if (String.Compare(fileNameNoSlash, fileName, StringComparison.CurrentCultureIgnoreCase) == 0) return e; + // also check for equivalence + if (String.Compare(fileName.Replace("\\", "/"), fileNameNoSlash, StringComparison.CurrentCultureIgnoreCase) == 0) return e; + if (String.Compare(fileNameNoSlash.Replace("\\", "/"), fileName, StringComparison.CurrentCultureIgnoreCase) == 0) return e; + + } + + } + + } + return null; + +#endif + } + } + + + /// + /// The list of filenames for the entries contained within the zip archive. + /// + /// + /// + /// According to the ZIP specification, the names of the entries use forward + /// slashes in pathnames. If you are scanning through the list, you may have + /// to swap forward slashes for backslashes. + /// + /// + /// + /// + /// + /// This example shows one way to test if a filename is already contained + /// within a zip archive. + /// + /// String zipFileToRead= "PackedDocuments.zip"; + /// string candidate = "DatedMaterial.xps"; + /// using (ZipFile zip = new ZipFile(zipFileToRead)) + /// { + /// if (zip.EntryFilenames.Contains(candidate)) + /// Console.WriteLine("The file '{0}' exists in the zip archive '{1}'", + /// candidate, + /// zipFileName); + /// else + /// Console.WriteLine("The file, '{0}', does not exist in the zip archive '{1}'", + /// candidate, + /// zipFileName); + /// Console.WriteLine(); + /// } + /// + /// + /// Dim zipFileToRead As String = "PackedDocuments.zip" + /// Dim candidate As String = "DatedMaterial.xps" + /// Using zip As ZipFile.Read(ZipFileToRead) + /// If zip.EntryFilenames.Contains(candidate) Then + /// Console.WriteLine("The file '{0}' exists in the zip archive '{1}'", _ + /// candidate, _ + /// zipFileName) + /// Else + /// Console.WriteLine("The file, '{0}', does not exist in the zip archive '{1}'", _ + /// candidate, _ + /// zipFileName) + /// End If + /// Console.WriteLine + /// End Using + /// + /// + /// + /// + /// The list of strings for the filenames contained within the Zip archive. + /// + /// + public System.Collections.Generic.ICollection EntryFileNames + { + get + { + return _entries.Keys; + } + } + + + /// + /// Returns the readonly collection of entries in the Zip archive. + /// + /// + /// + /// + /// + /// If there are no entries in the current ZipFile, the value returned is a + /// non-null zero-element collection. If there are entries in the zip file, + /// the elements are returned in no particular order. + /// + /// + /// This is the implied enumerator on the ZipFile class. If you use a + /// ZipFile instance in a context that expects an enumerator, you will + /// get this collection. + /// + /// + /// + public System.Collections.Generic.ICollection Entries + { + get + { + return _entries.Values; + } + } + + + /// + /// Returns a readonly collection of entries in the Zip archive, sorted by FileName. + /// + /// + /// + /// If there are no entries in the current ZipFile, the value returned + /// is a non-null zero-element collection. If there are entries in the zip + /// file, the elements are returned sorted by the name of the entry. + /// + /// + /// + /// + /// This example fills a Windows Forms ListView with the entries in a zip file. + /// + /// + /// using (ZipFile zip = ZipFile.Read(zipFile)) + /// { + /// foreach (ZipEntry entry in zip.EntriesSorted) + /// { + /// ListViewItem item = new ListViewItem(n.ToString()); + /// n++; + /// string[] subitems = new string[] { + /// entry.FileName.Replace("/","\\"), + /// entry.LastModified.ToString("yyyy-MM-dd HH:mm:ss"), + /// entry.UncompressedSize.ToString(), + /// String.Format("{0,5:F0}%", entry.CompressionRatio), + /// entry.CompressedSize.ToString(), + /// (entry.UsesEncryption) ? "Y" : "N", + /// String.Format("{0:X8}", entry.Crc)}; + /// + /// foreach (String s in subitems) + /// { + /// ListViewItem.ListViewSubItem subitem = new ListViewItem.ListViewSubItem(); + /// subitem.Text = s; + /// item.SubItems.Add(subitem); + /// } + /// + /// this.listView1.Items.Add(item); + /// } + /// } + /// + /// + /// + /// + public System.Collections.Generic.ICollection EntriesSorted + { + get + { + var coll = new System.Collections.Generic.List(); + foreach (var e in this.Entries) + { + coll.Add(e); + } + StringComparison sc = (CaseSensitiveRetrieval) ? StringComparison.Ordinal : StringComparison.OrdinalIgnoreCase; + + coll.Sort((x, y) => { return String.Compare(x.FileName, y.FileName, sc); }); + return coll.AsReadOnly(); + } + } + + + /// + /// Returns the number of entries in the Zip archive. + /// + public int Count + { + get + { + return _entries.Count; + } + } + + + + /// + /// Removes the given ZipEntry from the zip archive. + /// + /// + /// + /// + /// After calling RemoveEntry, the application must call Save to + /// make the changes permanent. + /// + /// + /// + /// + /// Thrown if the specified ZipEntry does not exist in the ZipFile. + /// + /// + /// + /// In this example, all entries in the zip archive dating from before + /// December 31st, 2007, are removed from the archive. This is actually much + /// easier if you use the RemoveSelectedEntries method. But I needed an + /// example for RemoveEntry, so here it is. + /// + /// String ZipFileToRead = "ArchiveToModify.zip"; + /// System.DateTime Threshold = new System.DateTime(2007,12,31); + /// using (ZipFile zip = ZipFile.Read(ZipFileToRead)) + /// { + /// var EntriesToRemove = new System.Collections.Generic.List<ZipEntry>(); + /// foreach (ZipEntry e in zip) + /// { + /// if (e.LastModified < Threshold) + /// { + /// // We cannot remove the entry from the list, within the context of + /// // an enumeration of said list. + /// // So we add the doomed entry to a list to be removed later. + /// EntriesToRemove.Add(e); + /// } + /// } + /// + /// // actually remove the doomed entries. + /// foreach (ZipEntry zombie in EntriesToRemove) + /// zip.RemoveEntry(zombie); + /// + /// zip.Comment= String.Format("This zip archive was updated at {0}.", + /// System.DateTime.Now.ToString("G")); + /// + /// // save with a different name + /// zip.Save("Archive-Updated.zip"); + /// } + /// + /// + /// + /// Dim ZipFileToRead As String = "ArchiveToModify.zip" + /// Dim Threshold As New DateTime(2007, 12, 31) + /// Using zip As ZipFile = ZipFile.Read(ZipFileToRead) + /// Dim EntriesToRemove As New System.Collections.Generic.List(Of ZipEntry) + /// Dim e As ZipEntry + /// For Each e In zip + /// If (e.LastModified < Threshold) Then + /// ' We cannot remove the entry from the list, within the context of + /// ' an enumeration of said list. + /// ' So we add the doomed entry to a list to be removed later. + /// EntriesToRemove.Add(e) + /// End If + /// Next + /// + /// ' actually remove the doomed entries. + /// Dim zombie As ZipEntry + /// For Each zombie In EntriesToRemove + /// zip.RemoveEntry(zombie) + /// Next + /// zip.Comment = String.Format("This zip archive was updated at {0}.", DateTime.Now.ToString("G")) + /// 'save as a different name + /// zip.Save("Archive-Updated.zip") + /// End Using + /// + /// + /// + /// + /// The ZipEntry to remove from the zip. + /// + /// + /// + /// + public void RemoveEntry(ZipEntry entry) + { + //if (!_entries.Values.Contains(entry)) + // throw new ArgumentException("The entry you specified does not exist in the zip archive."); + if (entry == null) + throw new ArgumentNullException("entry"); + + _entries.Remove(SharedUtilities.NormalizePathForUseInZipFile(entry.FileName)); + _zipEntriesAsList = null; + +#if NOTNEEDED + if (_direntries != null) + { + bool FoundAndRemovedDirEntry = false; + foreach (ZipDirEntry de1 in _direntries) + { + if (entry.FileName == de1.FileName) + { + _direntries.Remove(de1); + FoundAndRemovedDirEntry = true; + break; + } + } + + if (!FoundAndRemovedDirEntry) + throw new BadStateException("The entry to be removed was not found in the directory."); + } +#endif + _contentsChanged = true; + } + + + + + /// + /// Removes the ZipEntry with the given filename from the zip archive. + /// + /// + /// + /// + /// After calling RemoveEntry, the application must call Save to + /// make the changes permanent. + /// + /// + /// + /// + /// + /// Thrown if the ZipFile is not updatable. + /// + /// + /// + /// Thrown if a ZipEntry with the specified filename does not exist in + /// the ZipFile. + /// + /// + /// + /// + /// This example shows one way to remove an entry with a given filename from + /// an existing zip archive. + /// + /// + /// String zipFileToRead= "PackedDocuments.zip"; + /// string candidate = "DatedMaterial.xps"; + /// using (ZipFile zip = ZipFile.Read(zipFileToRead)) + /// { + /// if (zip.EntryFilenames.Contains(candidate)) + /// { + /// zip.RemoveEntry(candidate); + /// zip.Comment= String.Format("The file '{0}' has been removed from this archive.", + /// Candidate); + /// zip.Save(); + /// } + /// } + /// + /// + /// Dim zipFileToRead As String = "PackedDocuments.zip" + /// Dim candidate As String = "DatedMaterial.xps" + /// Using zip As ZipFile = ZipFile.Read(zipFileToRead) + /// If zip.EntryFilenames.Contains(candidate) Then + /// zip.RemoveEntry(candidate) + /// zip.Comment = String.Format("The file '{0}' has been removed from this archive.", Candidate) + /// zip.Save + /// End If + /// End Using + /// + /// + /// + /// + /// The name of the file, including any directory path, to remove from the zip. + /// The filename match is not case-sensitive by default; you can use the + /// CaseSensitiveRetrieval property to change this behavior. The + /// pathname can use forward-slashes or backward slashes. + /// + /// + public void RemoveEntry(String fileName) + { + string modifiedName = ZipEntry.NameInArchive(fileName, null); + ZipEntry e = this[modifiedName]; + if (e == null) + throw new ArgumentException("The entry you specified was not found in the zip archive."); + + RemoveEntry(e); + } + + + #endregion + + #region Destructors and Disposers + + // /// + // /// This is the class Destructor, which gets called implicitly when the instance + // /// is destroyed. Because the ZipFile type implements IDisposable, this + // /// method calls Dispose(false). + // /// + // ~ZipFile() + // { + // // call Dispose with false. Since we're in the + // // destructor call, the managed resources will be + // // disposed of anyways. + // Dispose(false); + // } + + /// + /// Closes the read and write streams associated + /// to the ZipFile, if necessary. + /// + /// + /// + /// The Dispose() method is generally employed implicitly, via a using(..) {..} + /// statement. (Using...End Using in VB) If you do not employ a using + /// statement, insure that your application calls Dispose() explicitly. For + /// example, in a Powershell application, or an application that uses the COM + /// interop interface, you must call Dispose() explicitly. + /// + /// + /// + /// This example extracts an entry selected by name, from the Zip file to the + /// Console. + /// + /// using (ZipFile zip = ZipFile.Read(zipfile)) + /// { + /// foreach (ZipEntry e in zip) + /// { + /// if (WantThisEntry(e.FileName)) + /// zip.Extract(e.FileName, Console.OpenStandardOutput()); + /// } + /// } // Dispose() is called implicitly here. + /// + /// + /// + /// Using zip As ZipFile = ZipFile.Read(zipfile) + /// Dim e As ZipEntry + /// For Each e In zip + /// If WantThisEntry(e.FileName) Then + /// zip.Extract(e.FileName, Console.OpenStandardOutput()) + /// End If + /// Next + /// End Using ' Dispose is implicity called here + /// + /// + public void Dispose() + { + // dispose of the managed and unmanaged resources + Dispose(true); + + // tell the GC that the Finalize process no longer needs + // to be run for this object. + GC.SuppressFinalize(this); + } + + /// + /// Disposes any managed resources, if the flag is set, then marks the + /// instance disposed. This method is typically not called explicitly from + /// application code. + /// + /// + /// + /// Applications should call the no-arg Dispose method. + /// + /// + /// + /// indicates whether the method should dispose streams or not. + /// + protected virtual void Dispose(bool disposeManagedResources) + { + if (!this._disposed) + { + if (disposeManagedResources) + { + // dispose managed resources + if (_ReadStreamIsOurs) + { + if (_readstream != null) + { + // workitem 7704 +#if NETCF + _readstream.Close(); +#else + _readstream.Dispose(); +#endif + _readstream = null; + } + } + // only dispose the writestream if there is a backing file + if ((_temporaryFileName != null) && (_name != null)) + if (_writestream != null) + { + // workitem 7704 +#if NETCF + _writestream.Close(); +#else + _writestream.Dispose(); +#endif + _writestream = null; + } + +#if !NETCF + // workitem 10030 + if (this.ParallelDeflater != null) + { + this.ParallelDeflater.Dispose(); + this.ParallelDeflater = null; + } +#endif + } + this._disposed = true; + } + } + #endregion + + + #region private properties + + internal Stream ReadStream + { + get + { + if (_readstream == null) + { + if (_readName != null || _name !=null) + { + _readstream = File.Open(_readName ?? _name, + FileMode.Open, + FileAccess.Read, + FileShare.Read | FileShare.Write); + _ReadStreamIsOurs = true; + } + } + return _readstream; + } + } + + + + private Stream WriteStream + { + // workitem 9763 + get + { + if (_writestream != null) return _writestream; + if (_name == null) return _writestream; + + if (_maxOutputSegmentSize != 0) + { + _writestream = ZipSegmentedStream.ForWriting(this._name, _maxOutputSegmentSize); + return _writestream; + } + + SharedUtilities.CreateAndOpenUniqueTempFile(TempFileFolder ?? Path.GetDirectoryName(_name), + out _writestream, + out _temporaryFileName); + return _writestream; + } + set + { + if (value != null) + throw new ZipException("Cannot set the stream to a non-null value."); + _writestream = null; + } + } + #endregion + + #region private fields + private TextWriter _StatusMessageTextWriter; + private bool _CaseSensitiveRetrieval; + private Stream _readstream; + private Stream _writestream; + private UInt16 _versionMadeBy; + private UInt16 _versionNeededToExtract; + private UInt32 _diskNumberWithCd; + private Int32 _maxOutputSegmentSize; + private UInt32 _numberOfSegmentsForMostRecentSave; + private ZipErrorAction _zipErrorAction; + private bool _disposed; + //private System.Collections.Generic.List _entries; + private System.Collections.Generic.Dictionary _entries; + private List _zipEntriesAsList; + private string _name; + private string _readName; + private string _Comment; + internal string _Password; + private bool _emitNtfsTimes = true; + private bool _emitUnixTimes; + private Ionic.Zlib.CompressionStrategy _Strategy = Ionic.Zlib.CompressionStrategy.Default; + private Ionic.Zip.CompressionMethod _compressionMethod = Ionic.Zip.CompressionMethod.Deflate; + private bool _fileAlreadyExists; + private string _temporaryFileName; + private bool _contentsChanged; + private bool _hasBeenSaved; + private String _TempFileFolder; + private bool _ReadStreamIsOurs = true; + private object LOCK = new object(); + private bool _saveOperationCanceled; + private bool _extractOperationCanceled; + private bool _addOperationCanceled; + private EncryptionAlgorithm _Encryption; + private bool _JustSaved; + private long _locEndOfCDS = -1; + private uint _OffsetOfCentralDirectory; + private Int64 _OffsetOfCentralDirectory64; + private Nullable _OutputUsesZip64; + internal bool _inExtractAll; + private System.Text.Encoding _alternateEncoding = System.Text.Encoding.GetEncoding("IBM437"); // UTF-8 + private ZipOption _alternateEncodingUsage = ZipOption.Never; + private static System.Text.Encoding _defaultEncoding = System.Text.Encoding.GetEncoding("IBM437"); + + private int _BufferSize = BufferSizeDefault; + +#if !NETCF + internal Ionic.Zlib.ParallelDeflateOutputStream ParallelDeflater; + private long _ParallelDeflateThreshold; + private int _maxBufferPairs = 16; +#endif + + internal Zip64Option _zip64 = Zip64Option.Default; +#pragma warning disable 649 + private bool _SavingSfx; +#pragma warning restore 649 + + /// + /// Default size of the buffer used for IO. + /// + public static readonly int BufferSizeDefault = 32768; + + #endregion + } + + /// + /// Options for using ZIP64 extensions when saving zip archives. + /// + /// + /// + /// + /// + /// Designed many years ago, the original zip + /// specification from PKWARE allowed for 32-bit quantities for the + /// compressed and uncompressed sizes of zip entries, as well as a 32-bit quantity + /// for specifying the length of the zip archive itself, and a maximum of 65535 + /// entries. These limits are now regularly exceeded in many backup and archival + /// scenarios. Recently, PKWare added extensions to the original zip spec, called + /// "ZIP64 extensions", to raise those limitations. This property governs whether + /// DotNetZip will use those extensions when writing zip archives. The use of + /// these extensions is optional and explicit in DotNetZip because, despite the + /// status of ZIP64 as a bona fide standard, many other zip tools and libraries do + /// not support ZIP64, and therefore a zip file with ZIP64 extensions may be + /// unreadable by some of those other tools. + /// + /// + /// + /// Set this property to to always use ZIP64 + /// extensions when saving, regardless of whether your zip archive needs it. + /// Suppose you add 5 files, each under 100k, to a ZipFile. If you specify Always + /// for this flag, you will get a ZIP64 archive, though the archive does not need + /// to use ZIP64 because none of the original zip limits had been exceeded. + /// + /// + /// + /// Set this property to to tell the DotNetZip + /// library to never use ZIP64 extensions. This is useful for maximum + /// compatibility and interoperability, at the expense of the capability of + /// handling large files or large archives. NB: Windows Explorer in Windows XP + /// and Windows Vista cannot currently extract files from a zip64 archive, so if + /// you want to guarantee that a zip archive produced by this library will work in + /// Windows Explorer, use Never. If you set this property to , and your application creates a zip that would + /// exceed one of the Zip limits, the library will throw an exception while saving + /// the zip file. + /// + /// + /// + /// Set this property to to tell the + /// DotNetZip library to use the ZIP64 extensions when required by the + /// entry. After the file is compressed, the original and compressed sizes are + /// checked, and if they exceed the limits described above, then zip64 can be + /// used. That is the general idea, but there is an additional wrinkle when saving + /// to a non-seekable device, like the ASP.NET Response.OutputStream, or + /// Console.Out. When using non-seekable streams for output, the entry + /// header - which indicates whether zip64 is in use - is emitted before it is + /// known if zip64 is necessary. It is only after all entries have been saved + /// that it can be known if ZIP64 will be required. On seekable output streams, + /// after saving all entries, the library can seek backward and re-emit the zip + /// file header to be consistent with the actual ZIP64 requirement. But using a + /// non-seekable output stream, the library cannot seek backward, so the header + /// can never be changed. In other words, the archive's use of ZIP64 extensions is + /// not alterable after the header is emitted. Therefore, when saving to + /// non-seekable streams, using is the same + /// as using : it will always produce a zip + /// archive that uses ZIP64 extensions. + /// + /// + /// + public enum Zip64Option + { + /// + /// The default behavior, which is "Never". + /// (For COM clients, this is a 0 (zero).) + /// + Default = 0, + /// + /// Do not use ZIP64 extensions when writing zip archives. + /// (For COM clients, this is a 0 (zero).) + /// + Never = 0, + /// + /// Use ZIP64 extensions when writing zip archives, as necessary. + /// For example, when a single entry exceeds 0xFFFFFFFF in size, or when the archive as a whole + /// exceeds 0xFFFFFFFF in size, or when there are more than 65535 entries in an archive. + /// (For COM clients, this is a 1.) + /// + AsNecessary = 1, + /// + /// Always use ZIP64 extensions when writing zip archives, even when unnecessary. + /// (For COM clients, this is a 2.) + /// + Always + } + + + /// + /// An enum representing the values on a three-way toggle switch + /// for various options in the library. This might be used to + /// specify whether to employ a particular text encoding, or to use + /// ZIP64 extensions, or some other option. + /// + public enum ZipOption + { + /// + /// The default behavior. This is the same as "Never". + /// (For COM clients, this is a 0 (zero).) + /// + Default = 0, + /// + /// Never use the associated option. + /// (For COM clients, this is a 0 (zero).) + /// + Never = 0, + /// + /// Use the associated behavior "as necessary." + /// (For COM clients, this is a 1.) + /// + AsNecessary = 1, + /// + /// Use the associated behavior Always, whether necessary or not. + /// (For COM clients, this is a 2.) + /// + Always + } + + + enum AddOrUpdateAction + { + AddOnly = 0, + AddOrUpdate + } + +} + + + +// ================================================================== +// +// Information on the ZIP format: +// +// From +// http://www.pkware.com/documents/casestudies/APPNOTE.TXT +// +// Overall .ZIP file format: +// +// [local file header 1] +// [file data 1] +// [data descriptor 1] ** sometimes +// . +// . +// . +// [local file header n] +// [file data n] +// [data descriptor n] ** sometimes +// [archive decryption header] +// [archive extra data record] +// [central directory] +// [zip64 end of central directory record] +// [zip64 end of central directory locator] +// [end of central directory record] +// +// Local File Header format: +// local file header signature ... 4 bytes (0x04034b50) +// version needed to extract ..... 2 bytes +// general purpose bit field ..... 2 bytes +// compression method ............ 2 bytes +// last mod file time ............ 2 bytes +// last mod file date............. 2 bytes +// crc-32 ........................ 4 bytes +// compressed size................ 4 bytes +// uncompressed size.............. 4 bytes +// file name length............... 2 bytes +// extra field length ............ 2 bytes +// file name varies +// extra field varies +// +// +// Data descriptor: (used only when bit 3 of the general purpose bitfield is set) +// (although, I have found zip files where bit 3 is not set, yet this descriptor is present!) +// local file header signature 4 bytes (0x08074b50) ** sometimes!!! Not always +// crc-32 4 bytes +// compressed size 4 bytes +// uncompressed size 4 bytes +// +// +// Central directory structure: +// +// [file header 1] +// . +// . +// . +// [file header n] +// [digital signature] +// +// +// File header: (This is a ZipDirEntry) +// central file header signature 4 bytes (0x02014b50) +// version made by 2 bytes +// version needed to extract 2 bytes +// general purpose bit flag 2 bytes +// compression method 2 bytes +// last mod file time 2 bytes +// last mod file date 2 bytes +// crc-32 4 bytes +// compressed size 4 bytes +// uncompressed size 4 bytes +// file name length 2 bytes +// extra field length 2 bytes +// file comment length 2 bytes +// disk number start 2 bytes +// internal file attributes ** 2 bytes +// external file attributes *** 4 bytes +// relative offset of local header 4 bytes +// file name (variable size) +// extra field (variable size) +// file comment (variable size) +// +// ** The internal file attributes, near as I can tell, +// uses 0x01 for a file and a 0x00 for a directory. +// +// ***The external file attributes follows the MS-DOS file attribute byte, described here: +// at http://support.microsoft.com/kb/q125019/ +// 0x0010 => directory +// 0x0020 => file +// +// +// End of central directory record: +// +// end of central dir signature 4 bytes (0x06054b50) +// number of this disk 2 bytes +// number of the disk with the +// start of the central directory 2 bytes +// total number of entries in the +// central directory on this disk 2 bytes +// total number of entries in +// the central directory 2 bytes +// size of the central directory 4 bytes +// offset of start of central +// directory with respect to +// the starting disk number 4 bytes +// .ZIP file comment length 2 bytes +// .ZIP file comment (variable size) +// +// date and time are packed values, as MSDOS did them +// time: bits 0-4 : seconds (divided by 2) +// 5-10: minute +// 11-15: hour +// date bits 0-4 : day +// 5-8: month +// 9-15 year (since 1980) +// +// see http://msdn.microsoft.com/en-us/library/ms724274(VS.85).aspx + diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.x-IEnumerable.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.x-IEnumerable.cs new file mode 100644 index 00000000..e8178d94 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipFile.x-IEnumerable.cs @@ -0,0 +1,154 @@ +// ZipFile.x-IEnumerable.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2006, 2007, 2008, 2009 Dino Chiesa and Microsoft Corporation. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2009-December-26 15:13:26> +// +// ------------------------------------------------------------------ +// +// This module defines smoe methods for IEnumerable support. It is +// particularly important for COM to have these things in a separate module. +// +// ------------------------------------------------------------------ + + +namespace Ionic.Zip +{ + + // For some weird reason, the method with the DispId(-4) attribute, which is used as + // the _NewEnum() method, and which is required to get enumeration to work from COM + // environments like VBScript and Javascript (etc) must be the LAST MEMBER in the + // source. In the event of Partial classes, it needs to be the last member defined + // in the last source module. The source modules are ordered alphabetically by + // filename. Not sure why this is true. In any case, we put the enumeration stuff + // here in this oddly-named module, for this reason. + // + + + + public partial class ZipFile + { + + + + + /// + /// Generic IEnumerator support, for use of a ZipFile in an enumeration. + /// + /// + /// + /// You probably do not want to call GetEnumerator explicitly. Instead + /// it is implicitly called when you use a loop in C#, or a + /// For Each loop in VB.NET. + /// + /// + /// + /// This example reads a zipfile of a given name, then enumerates the + /// entries in that zip file, and displays the information about each + /// entry on the Console. + /// + /// using (ZipFile zip = ZipFile.Read(zipfile)) + /// { + /// bool header = true; + /// foreach (ZipEntry e in zip) + /// { + /// if (header) + /// { + /// System.Console.WriteLine("Zipfile: {0}", zip.Name); + /// System.Console.WriteLine("Version Needed: 0x{0:X2}", e.VersionNeeded); + /// System.Console.WriteLine("BitField: 0x{0:X2}", e.BitField); + /// System.Console.WriteLine("Compression Method: 0x{0:X2}", e.CompressionMethod); + /// System.Console.WriteLine("\n{1,-22} {2,-6} {3,4} {4,-8} {0}", + /// "Filename", "Modified", "Size", "Ratio", "Packed"); + /// System.Console.WriteLine(new System.String('-', 72)); + /// header = false; + /// } + /// + /// System.Console.WriteLine("{1,-22} {2,-6} {3,4:F0}% {4,-8} {0}", + /// e.FileName, + /// e.LastModified.ToString("yyyy-MM-dd HH:mm:ss"), + /// e.UncompressedSize, + /// e.CompressionRatio, + /// e.CompressedSize); + /// + /// e.Extract(); + /// } + /// } + /// + /// + /// + /// Dim ZipFileToExtract As String = "c:\foo.zip" + /// Using zip As ZipFile = ZipFile.Read(ZipFileToExtract) + /// Dim header As Boolean = True + /// Dim e As ZipEntry + /// For Each e In zip + /// If header Then + /// Console.WriteLine("Zipfile: {0}", zip.Name) + /// Console.WriteLine("Version Needed: 0x{0:X2}", e.VersionNeeded) + /// Console.WriteLine("BitField: 0x{0:X2}", e.BitField) + /// Console.WriteLine("Compression Method: 0x{0:X2}", e.CompressionMethod) + /// Console.WriteLine(ChrW(10) & "{1,-22} {2,-6} {3,4} {4,-8} {0}", _ + /// "Filename", "Modified", "Size", "Ratio", "Packed" ) + /// Console.WriteLine(New String("-"c, 72)) + /// header = False + /// End If + /// Console.WriteLine("{1,-22} {2,-6} {3,4:F0}% {4,-8} {0}", _ + /// e.FileName, _ + /// e.LastModified.ToString("yyyy-MM-dd HH:mm:ss"), _ + /// e.UncompressedSize, _ + /// e.CompressionRatio, _ + /// e.CompressedSize ) + /// e.Extract + /// Next + /// End Using + /// + /// + /// + /// A generic enumerator suitable for use within a foreach loop. + public System.Collections.Generic.IEnumerator GetEnumerator() + { + foreach (ZipEntry e in _entries.Values) + yield return e; + } + + System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator() + { + return GetEnumerator(); + } + + + /// + /// An IEnumerator, for use of a ZipFile in a foreach construct. + /// + /// + /// + /// This method is included for COM support. An application generally does not call + /// this method directly. It is called implicitly by COM clients when enumerating + /// the entries in the ZipFile instance. In VBScript, this is done with a For Each + /// statement. In Javascript, this is done with new Enumerator(zipfile). + /// + /// + /// + /// The IEnumerator over the entries in the ZipFile. + /// + [System.Runtime.InteropServices.DispId(-4)] + public System.Collections.IEnumerator GetNewEnum() // the name of this method is not significant + { + return GetEnumerator(); + } + + } +} diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipInputStream.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipInputStream.cs new file mode 100644 index 00000000..9fa143b7 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipInputStream.cs @@ -0,0 +1,827 @@ +// ZipInputStream.cs +// +// ------------------------------------------------------------------ +// +// Copyright (c) 2009-2010 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-31 14:48:30> +// +// ------------------------------------------------------------------ +// +// This module defines the ZipInputStream class, which is a stream metaphor for +// reading zip files. This class does not depend on Ionic.Zip.ZipFile, but rather +// stands alongside it as an alternative "container" for ZipEntry, when reading zips. +// +// It adds one interesting method to the normal "stream" interface: GetNextEntry. +// +// ------------------------------------------------------------------ +// + +using System; +using System.Threading; +using System.Collections.Generic; +using System.IO; +using Ionic.Zip; + +namespace Ionic.Zip +{ + /// + /// Provides a stream metaphor for reading zip files. + /// + /// + /// + /// + /// This class provides an alternative programming model for reading zip files to + /// the one enabled by the class. Use this when reading zip + /// files, as an alternative to the class, when you would + /// like to use a Stream class to read the file. + /// + /// + /// + /// Some application designs require a readable stream for input. This stream can + /// be used to read a zip file, and extract entries. + /// + /// + /// + /// Both the ZipInputStream class and the ZipFile class can be used + /// to read and extract zip files. Both of them support many of the common zip + /// features, including Unicode, different compression levels, and ZIP64. The + /// programming models differ. For example, when extracting entries via calls to + /// the GetNextEntry() and Read() methods on the + /// ZipInputStream class, the caller is responsible for creating the file, + /// writing the bytes into the file, setting the attributes on the file, and + /// setting the created, last modified, and last accessed timestamps on the + /// file. All of these things are done automatically by a call to ZipEntry.Extract(). For this reason, the + /// ZipInputStream is generally recommended for when your application wants + /// to extract the data, without storing that data into a file. + /// + /// + /// + /// Aside from the obvious differences in programming model, there are some + /// differences in capability between the ZipFile class and the + /// ZipInputStream class. + /// + /// + /// + /// + /// ZipFile can be used to create or update zip files, or read and + /// extract zip files. ZipInputStream can be used only to read and + /// extract zip files. If you want to use a stream to create zip files, check + /// out the . + /// + /// + /// + /// ZipInputStream cannot read segmented or spanned + /// zip files. + /// + /// + /// + /// ZipInputStream will not read Zip file comments. + /// + /// + /// + /// When reading larger files, ZipInputStream will always underperform + /// ZipFile. This is because the ZipInputStream does a full scan on the + /// zip file, while the ZipFile class reads the central directory of the + /// zip file. + /// + /// + /// + /// + /// + public class ZipInputStream : Stream + { + /// + /// Create a ZipInputStream, wrapping it around an existing stream. + /// + /// + /// + /// + /// + /// While the class is generally easier + /// to use, this class provides an alternative to those + /// applications that want to read from a zipfile directly, + /// using a . + /// + /// + /// + /// Both the ZipInputStream class and the ZipFile class can be used + /// to read and extract zip files. Both of them support many of the common zip + /// features, including Unicode, different compression levels, and ZIP64. The + /// programming models differ. For example, when extracting entries via calls to + /// the GetNextEntry() and Read() methods on the + /// ZipInputStream class, the caller is responsible for creating the file, + /// writing the bytes into the file, setting the attributes on the file, and + /// setting the created, last modified, and last accessed timestamps on the + /// file. All of these things are done automatically by a call to ZipEntry.Extract(). For this reason, the + /// ZipInputStream is generally recommended for when your application wants + /// to extract the data, without storing that data into a file. + /// + /// + /// + /// Aside from the obvious differences in programming model, there are some + /// differences in capability between the ZipFile class and the + /// ZipInputStream class. + /// + /// + /// + /// + /// ZipFile can be used to create or update zip files, or read and extract + /// zip files. ZipInputStream can be used only to read and extract zip + /// files. If you want to use a stream to create zip files, check out the . + /// + /// + /// + /// ZipInputStream cannot read segmented or spanned + /// zip files. + /// + /// + /// + /// ZipInputStream will not read Zip file comments. + /// + /// + /// + /// When reading larger files, ZipInputStream will always underperform + /// ZipFile. This is because the ZipInputStream does a full scan on the + /// zip file, while the ZipFile class reads the central directory of the + /// zip file. + /// + /// + /// + /// + /// + /// + /// + /// The stream to read. It must be readable. This stream will be closed at + /// the time the ZipInputStream is closed. + /// + /// + /// + /// + /// This example shows how to read a zip file, and extract entries, using the + /// ZipInputStream class. + /// + /// + /// private void Unzip() + /// { + /// byte[] buffer= new byte[2048]; + /// int n; + /// using (var raw = File.Open(inputFileName, FileMode.Open, FileAccess.Read)) + /// { + /// using (var input= new ZipInputStream(raw)) + /// { + /// ZipEntry e; + /// while (( e = input.GetNextEntry()) != null) + /// { + /// if (e.IsDirectory) continue; + /// string outputPath = Path.Combine(extractDir, e.FileName); + /// using (var output = File.Open(outputPath, FileMode.Create, FileAccess.ReadWrite)) + /// { + /// while ((n= input.Read(buffer, 0, buffer.Length)) > 0) + /// { + /// output.Write(buffer,0,n); + /// } + /// } + /// } + /// } + /// } + /// } + /// + /// + /// + /// Private Sub UnZip() + /// Dim inputFileName As String = "MyArchive.zip" + /// Dim extractDir As String = "extract" + /// Dim buffer As Byte() = New Byte(2048) {} + /// Using raw As FileStream = File.Open(inputFileName, FileMode.Open, FileAccess.Read) + /// Using input As ZipInputStream = New ZipInputStream(raw) + /// Dim e As ZipEntry + /// Do While (Not e = input.GetNextEntry Is Nothing) + /// If Not e.IsDirectory Then + /// Using output As FileStream = File.Open(Path.Combine(extractDir, e.FileName), _ + /// FileMode.Create, FileAccess.ReadWrite) + /// Dim n As Integer + /// Do While (n = input.Read(buffer, 0, buffer.Length) > 0) + /// output.Write(buffer, 0, n) + /// Loop + /// End Using + /// End If + /// Loop + /// End Using + /// End Using + /// End Sub + /// + /// + public ZipInputStream(Stream stream) : this (stream, false) { } + + + + /// + /// Create a ZipInputStream, given the name of an existing zip file. + /// + /// + /// + /// + /// + /// This constructor opens a FileStream for the given zipfile, and + /// wraps a ZipInputStream around that. See the documentation for the + /// constructor for full details. + /// + /// + /// + /// While the class is generally easier + /// to use, this class provides an alternative to those + /// applications that want to read from a zipfile directly, + /// using a . + /// + /// + /// + /// + /// + /// The name of the filesystem file to read. + /// + /// + /// + /// + /// This example shows how to read a zip file, and extract entries, using the + /// ZipInputStream class. + /// + /// + /// private void Unzip() + /// { + /// byte[] buffer= new byte[2048]; + /// int n; + /// using (var input= new ZipInputStream(inputFileName)) + /// { + /// ZipEntry e; + /// while (( e = input.GetNextEntry()) != null) + /// { + /// if (e.IsDirectory) continue; + /// string outputPath = Path.Combine(extractDir, e.FileName); + /// using (var output = File.Open(outputPath, FileMode.Create, FileAccess.ReadWrite)) + /// { + /// while ((n= input.Read(buffer, 0, buffer.Length)) > 0) + /// { + /// output.Write(buffer,0,n); + /// } + /// } + /// } + /// } + /// } + /// + /// + /// + /// Private Sub UnZip() + /// Dim inputFileName As String = "MyArchive.zip" + /// Dim extractDir As String = "extract" + /// Dim buffer As Byte() = New Byte(2048) {} + /// Using input As ZipInputStream = New ZipInputStream(inputFileName) + /// Dim e As ZipEntry + /// Do While (Not e = input.GetNextEntry Is Nothing) + /// If Not e.IsDirectory Then + /// Using output As FileStream = File.Open(Path.Combine(extractDir, e.FileName), _ + /// FileMode.Create, FileAccess.ReadWrite) + /// Dim n As Integer + /// Do While (n = input.Read(buffer, 0, buffer.Length) > 0) + /// output.Write(buffer, 0, n) + /// Loop + /// End Using + /// End If + /// Loop + /// End Using + /// End Sub + /// + /// + public ZipInputStream(String fileName) + { + Stream stream = File.Open(fileName, FileMode.Open, FileAccess.Read, FileShare.Read ); + _Init(stream, false, fileName); + } + + + /// + /// Create a ZipInputStream, explicitly specifying whether to + /// keep the underlying stream open. + /// + /// + /// + /// See the documentation for the ZipInputStream(Stream) + /// constructor for a discussion of the class, and an example of how to use the class. + /// + /// + /// + /// The stream to read from. It must be readable. + /// + /// + /// + /// true if the application would like the stream + /// to remain open after the ZipInputStream has been closed. + /// + public ZipInputStream(Stream stream, bool leaveOpen) + { + _Init(stream, leaveOpen, null); + } + + private void _Init(Stream stream, bool leaveOpen, string name) + { + _inputStream = stream; + if (!_inputStream.CanRead) + throw new ZipException("The stream must be readable."); + _container= new ZipContainer(this); + _provisionalAlternateEncoding = System.Text.Encoding.GetEncoding("IBM437"); + _leaveUnderlyingStreamOpen = leaveOpen; + _findRequired= true; + _name = name ?? "(stream)"; + } + + + /// Provides a string representation of the instance. + /// + /// + /// This can be useful for debugging purposes. + /// + /// + /// a string representation of the instance. + public override String ToString() + { + return String.Format ("ZipInputStream::{0}(leaveOpen({1})))", _name, _leaveUnderlyingStreamOpen); + } + + + /// + /// The text encoding to use when reading entries into the zip archive, for + /// those entries whose filenames or comments cannot be encoded with the + /// default (IBM437) encoding. + /// + /// + /// + /// + /// In its + /// zip specification, PKWare describes two options for encoding + /// filenames and comments: using IBM437 or UTF-8. But, some archiving tools + /// or libraries do not follow the specification, and instead encode + /// characters using the system default code page. For example, WinRAR when + /// run on a machine in Shanghai may encode filenames with the Big-5 Chinese + /// (950) code page. This behavior is contrary to the Zip specification, but + /// it occurs anyway. + /// + /// + /// + /// When using DotNetZip to read zip archives that use something other than + /// UTF-8 or IBM437, set this property to specify the code page to use when + /// reading encoded filenames and comments for each ZipEntry in the zip + /// file. + /// + /// + /// + /// This property is "provisional". When the entry in the zip archive is not + /// explicitly marked as using UTF-8, then IBM437 is used to decode filenames + /// and comments. If a loss of data would result from using IBM436 - + /// specifically when encoding and decoding is not reflexive - the codepage + /// specified here is used. It is possible, therefore, to have a given entry + /// with a Comment encoded in IBM437 and a FileName encoded with + /// the specified "provisional" codepage. + /// + /// + /// + /// When a zip file uses an arbitrary, non-UTF8 code page for encoding, there + /// is no standard way for the reader application - whether DotNetZip, WinZip, + /// WinRar, or something else - to know which codepage has been used for the + /// entries. Readers of zip files are not able to inspect the zip file and + /// determine the codepage that was used for the entries contained within it. + /// It is left to the application or user to determine the necessary codepage + /// when reading zip files encoded this way. If you use an incorrect codepage + /// when reading a zipfile, you will get entries with filenames that are + /// incorrect, and the incorrect filenames may even contain characters that + /// are not legal for use within filenames in Windows. Extracting entries with + /// illegal characters in the filenames will lead to exceptions. It's too bad, + /// but this is just the way things are with code pages in zip files. Caveat + /// Emptor. + /// + /// + /// + public System.Text.Encoding ProvisionalAlternateEncoding + { + get + { + return _provisionalAlternateEncoding; + } + set + { + _provisionalAlternateEncoding = value; + } + } + + + /// + /// Size of the work buffer to use for the ZLIB codec during decompression. + /// + /// + /// + /// Setting this affects the performance and memory efficiency of compression + /// and decompression. For larger files, setting this to a larger size may + /// improve performance, but the exact numbers vary depending on available + /// memory, and a bunch of other variables. I don't have good firm + /// recommendations on how to set it. You'll have to test it yourself. Or + /// just leave it alone and accept the default. + /// + public int CodecBufferSize + { + get; + set; + } + + + /// + /// Sets the password to be used on the ZipInputStream instance. + /// + /// + /// + /// + /// + /// When reading a zip archive, this password is used to read and decrypt the + /// entries that are encrypted within the zip file. When entries within a zip + /// file use different passwords, set the appropriate password for the entry + /// before the first call to Read() for each entry. + /// + /// + /// + /// When reading an entry that is not encrypted, the value of this property is + /// ignored. + /// + /// + /// + /// + /// + /// + /// This example uses the ZipInputStream to read and extract entries from a + /// zip file, using a potentially different password for each entry. + /// + /// + /// byte[] buffer= new byte[2048]; + /// int n; + /// using (var raw = File.Open(_inputFileName, FileMode.Open, FileAccess.Read )) + /// { + /// using (var input= new ZipInputStream(raw)) + /// { + /// ZipEntry e; + /// while (( e = input.GetNextEntry()) != null) + /// { + /// input.Password = PasswordForEntry(e.FileName); + /// if (e.IsDirectory) continue; + /// string outputPath = Path.Combine(_extractDir, e.FileName); + /// using (var output = File.Open(outputPath, FileMode.Create, FileAccess.ReadWrite)) + /// { + /// while ((n= input.Read(buffer,0,buffer.Length)) > 0) + /// { + /// output.Write(buffer,0,n); + /// } + /// } + /// } + /// } + /// } + /// + /// + /// + public String Password + { + set + { + if (_closed) + { + _exceptionPending = true; + throw new System.InvalidOperationException("The stream has been closed."); + } + _Password = value; + } + } + + + private void SetupStream() + { + // Seek to the correct posn in the file, and open a + // stream that can be read. + _crcStream= _currentEntry.InternalOpenReader(_Password); + _LeftToRead = _crcStream.Length; + _needSetup = false; + } + + + + internal Stream ReadStream + { + get + { + return _inputStream; + } + } + + + /// + /// Read the data from the stream into the buffer. + /// + /// + /// + /// + /// The data for the zipentry will be decrypted and uncompressed, as + /// necessary, before being copied into the buffer. + /// + /// + /// + /// You must set the property before calling + /// Read() the first time for an encrypted entry. To determine if an + /// entry is encrypted and requires a password, check the ZipEntry.Encryption property. + /// + /// + /// + /// The buffer to hold the data read from the stream. + /// the offset within the buffer to copy the first byte read. + /// the number of bytes to read. + /// the number of bytes read, after decryption and decompression. + public override int Read(byte[] buffer, int offset, int count) + { + if (_closed) + { + _exceptionPending = true; + throw new System.InvalidOperationException("The stream has been closed."); + } + + if (_needSetup) + SetupStream(); + + if (_LeftToRead == 0) return 0; + + int len = (_LeftToRead > count) ? count : (int)_LeftToRead; + int n = _crcStream.Read(buffer, offset, len); + + _LeftToRead -= n; + + if (_LeftToRead == 0) + { + int CrcResult = _crcStream.Crc; + _currentEntry.VerifyCrcAfterExtract(CrcResult); + _inputStream.Seek(_endOfEntry, SeekOrigin.Begin); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(_inputStream); + } + + return n; + } + + + + /// + /// Read the next entry from the zip file. + /// + /// + /// + /// + /// Call this method just before calling , + /// to position the pointer in the zip file to the next entry that can be + /// read. Subsequent calls to Read(), will decrypt and decompress the + /// data in the zip file, until Read() returns 0. + /// + /// + /// + /// Each time you call GetNextEntry(), the pointer in the wrapped + /// stream is moved to the next entry in the zip file. If you call , and thus re-position the pointer within + /// the file, you will need to call GetNextEntry() again, to insure + /// that the file pointer is positioned at the beginning of a zip entry. + /// + /// + /// + /// This method returns the ZipEntry. Using a stream approach, you will + /// read the raw bytes for an entry in a zip file via calls to Read(). + /// Alternatively, you can extract an entry into a file, or a stream, by + /// calling , or one of its siblings. + /// + /// + /// + /// + /// + /// The ZipEntry read. Returns null (or Nothing in VB) if there are no more + /// entries in the zip file. + /// + /// + public ZipEntry GetNextEntry() + { + if (_findRequired) + { + // find the next signature + long d = SharedUtilities.FindSignature(_inputStream, ZipConstants.ZipEntrySignature); + if (d == -1) return null; + // back up 4 bytes: ReadEntry assumes the file pointer is positioned before the entry signature + _inputStream.Seek(-4, SeekOrigin.Current); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(_inputStream); + } + // workitem 10923 + else if (_firstEntry) + { + // we've already read one entry. + // Seek to the end of it. + _inputStream.Seek(_endOfEntry, SeekOrigin.Begin); + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(_inputStream); + } + + _currentEntry = ZipEntry.ReadEntry(_container, !_firstEntry); + // ReadEntry leaves the file position after all the entry + // data and the optional bit-3 data descriptpr. This is + // where the next entry would normally start. + _endOfEntry = _inputStream.Position; + _firstEntry = true; + _needSetup = true; + _findRequired= false; + return _currentEntry; + } + + + /// + /// Dispose the stream. + /// + /// + /// + /// + /// This method disposes the ZipInputStream. It may also close the + /// underlying stream, depending on which constructor was used. + /// + /// + /// + /// Typically the application will call Dispose() implicitly, via + /// a using statement in C#, or a Using statement in VB. + /// + /// + /// + /// Application code won't call this code directly. This method may + /// be invoked in two distinct scenarios. If disposing == true, the + /// method has been called directly or indirectly by a user's code, + /// for example via the public Dispose() method. In this case, both + /// managed and unmanaged resources can be referenced and disposed. + /// If disposing == false, the method has been called by the runtime + /// from inside the object finalizer and this method should not + /// reference other objects; in that case only unmanaged resources + /// must be referenced or disposed. + /// + /// + /// + /// + /// true if the Dispose method was invoked by user code. + /// + protected override void Dispose(bool disposing) + { + if (_closed) return; + + if (disposing) // not called from finalizer + { + // When ZipInputStream is used within a using clause, and an + // exception is thrown, Close() is invoked. But we don't want to + // try to write anything in that case. Eventually the exception + // will be propagated to the application. + if (_exceptionPending) return; + + if (!_leaveUnderlyingStreamOpen) + { +#if NETCF + _inputStream.Close(); +#else + _inputStream.Dispose(); +#endif + } + } + _closed= true; + } + + + /// + /// Always returns true. + /// + public override bool CanRead { get { return true; }} + + /// + /// Returns the value of CanSeek for the underlying (wrapped) stream. + /// + public override bool CanSeek { get { return _inputStream.CanSeek; } } + + /// + /// Always returns false. + /// + public override bool CanWrite { get { return false; } } + + /// + /// Returns the length of the underlying stream. + /// + public override long Length { get { return _inputStream.Length; }} + + /// + /// Gets or sets the position of the underlying stream. + /// + /// + /// Setting the position is equivalent to calling Seek(value, SeekOrigin.Begin). + /// + public override long Position + { + get { return _inputStream.Position;} + set { Seek(value, SeekOrigin.Begin); } + } + + /// + /// This is a no-op. + /// + public override void Flush() + { + throw new NotSupportedException("Flush"); + } + + + /// + /// This method always throws a NotSupportedException. + /// + /// ignored + /// ignored + /// ignored + public override void Write(byte[] buffer, int offset, int count) + { + throw new NotSupportedException("Write"); + } + + + /// + /// This method seeks in the underlying stream. + /// + /// + /// + /// + /// Call this method if you want to seek around within the zip file for random access. + /// + /// + /// + /// Applications can intermix calls to Seek() with calls to . After a call to Seek(), + /// GetNextEntry() will get the next ZipEntry that falls after + /// the current position in the input stream. You're on your own for finding + /// out just where to seek in the stream, to get to the various entries. + /// + /// + /// + /// + /// the offset point to seek to + /// the reference point from which to seek + /// The new position + public override long Seek(long offset, SeekOrigin origin) + { + _findRequired= true; + var x = _inputStream.Seek(offset, origin); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(_inputStream); + return x; + } + + /// + /// This method always throws a NotSupportedException. + /// + /// ignored + public override void SetLength(long value) + { + throw new NotSupportedException(); + } + + + private Stream _inputStream; + private System.Text.Encoding _provisionalAlternateEncoding; + private ZipEntry _currentEntry; + private bool _firstEntry; + private bool _needSetup; + private ZipContainer _container; + private Ionic.Crc.CrcCalculatorStream _crcStream; + private Int64 _LeftToRead; + internal String _Password; + private Int64 _endOfEntry; + private string _name; + + private bool _leaveUnderlyingStreamOpen; + private bool _closed; + private bool _findRequired; + private bool _exceptionPending; + } + + + +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipOutputStream.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipOutputStream.cs new file mode 100644 index 00000000..97d1f9cb --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipOutputStream.cs @@ -0,0 +1,1817 @@ +// ZipOutputStream.cs +// +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-28 06:34:30> +// +// ------------------------------------------------------------------ +// +// This module defines the ZipOutputStream class, which is a stream metaphor for +// generating zip files. This class does not depend on Ionic.Zip.ZipFile, but rather +// stands alongside it as an alternative "container" for ZipEntry. It replicates a +// subset of the properties, including these: +// +// - Comment +// - Encryption +// - Password +// - CodecBufferSize +// - CompressionLevel +// - CompressionMethod +// - EnableZip64 (UseZip64WhenSaving) +// - IgnoreCase (!CaseSensitiveRetrieval) +// +// It adds these novel methods: +// +// - PutNextEntry +// +// +// ------------------------------------------------------------------ +// + +using System; +using System.Threading; +using System.Collections.Generic; +using System.IO; +using Ionic.Zip; + +namespace Ionic.Zip +{ + /// + /// Provides a stream metaphor for generating zip files. + /// + /// + /// + /// + /// This class writes zip files, as defined in the specification + /// for zip files described by PKWare. The compression for this + /// implementation is provided by a managed-code version of Zlib, included with + /// DotNetZip in the classes in the Ionic.Zlib namespace. + /// + /// + /// + /// This class provides an alternative programming model to the one enabled by the + /// class. Use this when creating zip files, as an + /// alternative to the class, when you would like to use a + /// Stream type to write the zip file. + /// + /// + /// + /// Both the ZipOutputStream class and the ZipFile class can be used + /// to create zip files. Both of them support many of the common zip features, + /// including Unicode, different compression levels, and ZIP64. They provide + /// very similar performance when creating zip files. + /// + /// + /// + /// The ZipFile class is generally easier to use than + /// ZipOutputStream and should be considered a higher-level interface. For + /// example, when creating a zip file via calls to the PutNextEntry() and + /// Write() methods on the ZipOutputStream class, the caller is + /// responsible for opening the file, reading the bytes from the file, writing + /// those bytes into the ZipOutputStream, setting the attributes on the + /// ZipEntry, and setting the created, last modified, and last accessed + /// timestamps on the zip entry. All of these things are done automatically by a + /// call to ZipFile.AddFile(). + /// For this reason, the ZipOutputStream is generally recommended for use + /// only when your application emits arbitrary data, not necessarily data from a + /// filesystem file, directly into a zip file, and does so using a Stream + /// metaphor. + /// + /// + /// + /// Aside from the differences in programming model, there are other + /// differences in capability between the two classes. + /// + /// + /// + /// + /// ZipFile can be used to read and extract zip files, in addition to + /// creating zip files. ZipOutputStream cannot read zip files. If you want + /// to use a stream to read zip files, check out the class. + /// + /// + /// + /// ZipOutputStream does not support the creation of segmented or spanned + /// zip files. + /// + /// + /// + /// ZipOutputStream cannot produce a self-extracting archive. + /// + /// + /// + /// + /// Be aware that the ZipOutputStream class implements the interface. In order for + /// ZipOutputStream to produce a valid zip file, you use use it within + /// a using clause (Using in VB), or call the Dispose() method + /// explicitly. See the examples for how to employ a using clause. + /// + /// + /// + /// Also, a note regarding compression performance: On the desktop .NET + /// Framework, DotNetZip can use a multi-threaded compression implementation + /// that provides significant speed increases on large files, over 300k or so, + /// at the cost of increased memory use at runtime. (The output of the + /// compression is almost exactly the same size). But, the multi-threaded + /// approach incurs a performance hit on smaller files. There's no way for the + /// ZipOutputStream to know whether parallel compression will be beneficial, + /// because the ZipOutputStream does not know how much data you will write + /// through the stream. You may wish to set the property to zero, if you are compressing + /// large files through ZipOutputStream. This will cause parallel + /// compression to be used, always. + /// + /// + public class ZipOutputStream : Stream + { + /// + /// Create a ZipOutputStream, wrapping an existing stream. + /// + /// + /// + /// + /// The class is generally easier to use when creating + /// zip files. The ZipOutputStream offers a different metaphor for creating a + /// zip file, based on the class. + /// + /// + /// + /// + /// + /// The stream to wrap. It must be writable. This stream will be closed at + /// the time the ZipOutputStream is closed. + /// + /// + /// + /// + /// This example shows how to create a zip file, using the + /// ZipOutputStream class. + /// + /// + /// private void Zipup() + /// { + /// if (filesToZip.Count == 0) + /// { + /// System.Console.WriteLine("Nothing to do."); + /// return; + /// } + /// + /// using (var raw = File.Open(_outputFileName, FileMode.Create, FileAccess.ReadWrite )) + /// { + /// using (var output= new ZipOutputStream(raw)) + /// { + /// output.Password = "VerySecret!"; + /// output.Encryption = EncryptionAlgorithm.WinZipAes256; + /// + /// foreach (string inputFileName in filesToZip) + /// { + /// System.Console.WriteLine("file: {0}", inputFileName); + /// + /// output.PutNextEntry(inputFileName); + /// using (var input = File.Open(inputFileName, FileMode.Open, FileAccess.Read, FileShare.Read | FileShare.Write )) + /// { + /// byte[] buffer= new byte[2048]; + /// int n; + /// while ((n= input.Read(buffer,0,buffer.Length)) > 0) + /// { + /// output.Write(buffer,0,n); + /// } + /// } + /// } + /// } + /// } + /// } + /// + /// + /// + /// Private Sub Zipup() + /// Dim outputFileName As String = "XmlData.zip" + /// Dim filesToZip As String() = Directory.GetFiles(".", "*.xml") + /// If (filesToZip.Length = 0) Then + /// Console.WriteLine("Nothing to do.") + /// Else + /// Using raw As FileStream = File.Open(outputFileName, FileMode.Create, FileAccess.ReadWrite) + /// Using output As ZipOutputStream = New ZipOutputStream(raw) + /// output.Password = "VerySecret!" + /// output.Encryption = EncryptionAlgorithm.WinZipAes256 + /// Dim inputFileName As String + /// For Each inputFileName In filesToZip + /// Console.WriteLine("file: {0}", inputFileName) + /// output.PutNextEntry(inputFileName) + /// Using input As FileStream = File.Open(inputFileName, FileMode.Open, FileAccess.Read, FileShare.ReadWrite) + /// Dim n As Integer + /// Dim buffer As Byte() = New Byte(2048) {} + /// Do While (n = input.Read(buffer, 0, buffer.Length) > 0) + /// output.Write(buffer, 0, n) + /// Loop + /// End Using + /// Next + /// End Using + /// End Using + /// End If + /// End Sub + /// + /// + public ZipOutputStream(Stream stream) : this(stream, false) { } + + + /// + /// Create a ZipOutputStream that writes to a filesystem file. + /// + /// + /// + /// The class is generally easier to use when creating + /// zip files. The ZipOutputStream offers a different metaphor for creating a + /// zip file, based on the class. + /// + /// + /// + /// The name of the zip file to create. + /// + /// + /// + /// + /// This example shows how to create a zip file, using the + /// ZipOutputStream class. + /// + /// + /// private void Zipup() + /// { + /// if (filesToZip.Count == 0) + /// { + /// System.Console.WriteLine("Nothing to do."); + /// return; + /// } + /// + /// using (var output= new ZipOutputStream(outputFileName)) + /// { + /// output.Password = "VerySecret!"; + /// output.Encryption = EncryptionAlgorithm.WinZipAes256; + /// + /// foreach (string inputFileName in filesToZip) + /// { + /// System.Console.WriteLine("file: {0}", inputFileName); + /// + /// output.PutNextEntry(inputFileName); + /// using (var input = File.Open(inputFileName, FileMode.Open, FileAccess.Read, + /// FileShare.Read | FileShare.Write )) + /// { + /// byte[] buffer= new byte[2048]; + /// int n; + /// while ((n= input.Read(buffer,0,buffer.Length)) > 0) + /// { + /// output.Write(buffer,0,n); + /// } + /// } + /// } + /// } + /// } + /// + /// + /// + /// Private Sub Zipup() + /// Dim outputFileName As String = "XmlData.zip" + /// Dim filesToZip As String() = Directory.GetFiles(".", "*.xml") + /// If (filesToZip.Length = 0) Then + /// Console.WriteLine("Nothing to do.") + /// Else + /// Using output As ZipOutputStream = New ZipOutputStream(outputFileName) + /// output.Password = "VerySecret!" + /// output.Encryption = EncryptionAlgorithm.WinZipAes256 + /// Dim inputFileName As String + /// For Each inputFileName In filesToZip + /// Console.WriteLine("file: {0}", inputFileName) + /// output.PutNextEntry(inputFileName) + /// Using input As FileStream = File.Open(inputFileName, FileMode.Open, FileAccess.Read, FileShare.ReadWrite) + /// Dim n As Integer + /// Dim buffer As Byte() = New Byte(2048) {} + /// Do While (n = input.Read(buffer, 0, buffer.Length) > 0) + /// output.Write(buffer, 0, n) + /// Loop + /// End Using + /// Next + /// End Using + /// End If + /// End Sub + /// + /// + public ZipOutputStream(String fileName) + { + Stream stream = File.Open(fileName, FileMode.Create, FileAccess.ReadWrite, FileShare.None); + _Init(stream, false, fileName); + } + + + /// + /// Create a ZipOutputStream. + /// + /// + /// + /// See the documentation for the ZipOutputStream(Stream) + /// constructor for an example. + /// + /// + /// + /// The stream to wrap. It must be writable. + /// + /// + /// + /// true if the application would like the stream + /// to remain open after the ZipOutputStream has been closed. + /// + public ZipOutputStream(Stream stream, bool leaveOpen) + { + _Init(stream, leaveOpen, null); + } + + private void _Init(Stream stream, bool leaveOpen, string name) + { + // workitem 9307 + _outputStream = stream.CanRead ? stream : new CountingStream(stream); + CompressionLevel = Ionic.Zlib.CompressionLevel.Default; + CompressionMethod = Ionic.Zip.CompressionMethod.Deflate; + _encryption = EncryptionAlgorithm.None; + _entriesWritten = new Dictionary(StringComparer.Ordinal); + _zip64 = Zip64Option.Never; + _leaveUnderlyingStreamOpen = leaveOpen; + Strategy = Ionic.Zlib.CompressionStrategy.Default; + _name = name ?? "(stream)"; +#if !NETCF + ParallelDeflateThreshold = -1L; +#endif + } + + + /// Provides a string representation of the instance. + /// + /// + /// This can be useful for debugging purposes. + /// + /// + /// a string representation of the instance. + public override String ToString() + { + return String.Format ("ZipOutputStream::{0}(leaveOpen({1})))", _name, _leaveUnderlyingStreamOpen); + } + + + /// + /// Sets the password to be used on the ZipOutputStream instance. + /// + /// + /// + /// + /// + /// When writing a zip archive, this password is applied to the entries, not + /// to the zip archive itself. It applies to any ZipEntry subsequently + /// written to the ZipOutputStream. + /// + /// + /// + /// Using a password does not encrypt or protect the "directory" of the + /// archive - the list of entries contained in the archive. If you set the + /// Password property, the password actually applies to individual + /// entries that are added to the archive, subsequent to the setting of this + /// property. The list of filenames in the archive that is eventually created + /// will appear in clear text, but the contents of the individual files are + /// encrypted. This is how Zip encryption works. + /// + /// + /// + /// If you set this property, and then add a set of entries to the archive via + /// calls to PutNextEntry, then each entry is encrypted with that + /// password. You may also want to change the password between adding + /// different entries. If you set the password, add an entry, then set the + /// password to null (Nothing in VB), and add another entry, the + /// first entry is encrypted and the second is not. + /// + /// + /// + /// When setting the Password, you may also want to explicitly set the property, to specify how to encrypt the entries added + /// to the ZipFile. If you set the Password to a non-null value and do not + /// set , then PKZip 2.0 ("Weak") encryption is used. + /// This encryption is relatively weak but is very interoperable. If + /// you set the password to a null value (Nothing in VB), + /// Encryption is reset to None. + /// + /// + /// + /// Special case: if you wrap a ZipOutputStream around a non-seekable stream, + /// and use encryption, and emit an entry of zero bytes, the Close() or + /// PutNextEntry() following the entry will throw an exception. + /// + /// + /// + public String Password + { + set + { + if (_disposed) + { + _exceptionPending = true; + throw new System.InvalidOperationException("The stream has been closed."); + } + + _password = value; + if (_password == null) + { + _encryption = EncryptionAlgorithm.None; + } + else if (_encryption == EncryptionAlgorithm.None) + { + _encryption = EncryptionAlgorithm.PkzipWeak; + } + } + } + + + /// + /// The Encryption to use for entries added to the ZipOutputStream. + /// + /// + /// + /// + /// The specified Encryption is applied to the entries subsequently + /// written to the ZipOutputStream instance. + /// + /// + /// + /// If you set this to something other than + /// EncryptionAlgorithm.None, you will also need to set the + /// to a non-null, non-empty value in + /// order to actually get encryption on the entry. + /// + /// + /// + /// + /// ZipOutputStream.Password + /// ZipEntry.Encryption + public EncryptionAlgorithm Encryption + { + get + { + return _encryption; + } + set + { + if (_disposed) + { + _exceptionPending = true; + throw new System.InvalidOperationException("The stream has been closed."); + } + if (value == EncryptionAlgorithm.Unsupported) + { + _exceptionPending = true; + throw new InvalidOperationException("You may not set Encryption to that value."); + } + _encryption = value; + } + } + + + /// + /// Size of the work buffer to use for the ZLIB codec during compression. + /// + /// + /// + /// Setting this may affect performance. For larger files, setting this to a + /// larger size may improve performance, but I'm not sure. Sorry, I don't + /// currently have good recommendations on how to set it. You can test it if + /// you like. + /// + public int CodecBufferSize + { + get; + set; + } + + + /// + /// The compression strategy to use for all entries. + /// + /// + /// + /// Set the Strategy used by the ZLIB-compatible compressor, when compressing + /// data for the entries in the zip archive. Different compression strategies + /// work better on different sorts of data. The strategy parameter can affect + /// the compression ratio and the speed of compression but not the correctness + /// of the compresssion. For more information see . + /// + public Ionic.Zlib.CompressionStrategy Strategy + { + get; + set; + } + + + /// + /// The type of timestamp attached to the ZipEntry. + /// + /// + /// + /// Set this in order to specify the kind of timestamp that should be emitted + /// into the zip file for each entry. + /// + public ZipEntryTimestamp Timestamp + { + get + { + return _timestamp; + } + set + { + if (_disposed) + { + _exceptionPending = true; + throw new System.InvalidOperationException("The stream has been closed."); + } + _timestamp = value; + } + } + + + /// + /// Sets the compression level to be used for entries subsequently added to + /// the zip archive. + /// + /// + /// + /// + /// Varying the compression level used on entries can affect the + /// size-vs-speed tradeoff when compression and decompressing data streams + /// or files. + /// + /// + /// + /// As with some other properties on the ZipOutputStream class, like , and , + /// setting this property on a ZipOutputStream + /// instance will cause the specified CompressionLevel to be used on all + /// items that are subsequently added to the + /// ZipOutputStream instance. + /// + /// + /// + /// If you do not set this property, the default compression level is used, + /// which normally gives a good balance of compression efficiency and + /// compression speed. In some tests, using BestCompression can + /// double the time it takes to compress, while delivering just a small + /// increase in compression efficiency. This behavior will vary with the + /// type of data you compress. If you are in doubt, just leave this setting + /// alone, and accept the default. + /// + /// + public Ionic.Zlib.CompressionLevel CompressionLevel + { + get; + set; + } + + /// + /// The compression method used on each entry added to the ZipOutputStream. + /// + public Ionic.Zip.CompressionMethod CompressionMethod + { + get; + set; + } + + + /// + /// A comment attached to the zip archive. + /// + /// + /// + /// + /// + /// The application sets this property to specify a comment to be embedded + /// into the generated zip archive. + /// + /// + /// + /// According to PKWARE's + /// zip specification, the comment is not encrypted, even if there is a + /// password set on the zip file. + /// + /// + /// + /// The specification does not describe how to indicate the encoding used + /// on a comment string. Many "compliant" zip tools and libraries use + /// IBM437 as the code page for comments; DotNetZip, too, follows that + /// practice. On the other hand, there are situations where you want a + /// Comment to be encoded with something else, for example using code page + /// 950 "Big-5 Chinese". To fill that need, DotNetZip will encode the + /// comment following the same procedure it follows for encoding + /// filenames: (a) if is + /// Never, it uses the default encoding (IBM437). (b) if is Always, it always uses the + /// alternate encoding (). (c) if is AsNecessary, it uses the + /// alternate encoding only if the default encoding is not sufficient for + /// encoding the comment - in other words if decoding the result does not + /// produce the original string. This decision is taken at the time of + /// the call to ZipFile.Save(). + /// + /// + /// + public string Comment + { + get { return _comment; } + set + { + if (_disposed) + { + _exceptionPending = true; + throw new System.InvalidOperationException("The stream has been closed."); + } + _comment = value; + } + } + + + + /// + /// Specify whether to use ZIP64 extensions when saving a zip archive. + /// + /// + /// + /// + /// The default value for the property is . is + /// safest, in the sense that you will not get an Exception if a + /// pre-ZIP64 limit is exceeded. + /// + /// + /// + /// You must set this property before calling Write(). + /// + /// + /// + public Zip64Option EnableZip64 + { + get + { + return _zip64; + } + set + { + if (_disposed) + { + _exceptionPending = true; + throw new System.InvalidOperationException("The stream has been closed."); + } + _zip64 = value; + } + } + + + /// + /// Indicates whether ZIP64 extensions were used when saving the zip archive. + /// + /// + /// + /// The value is defined only after the ZipOutputStream has been closed. + /// + public bool OutputUsedZip64 + { + get + { + return _anyEntriesUsedZip64 || _directoryNeededZip64; + } + } + + + /// + /// Whether the ZipOutputStream should use case-insensitive comparisons when + /// checking for uniqueness of zip entries. + /// + /// + /// + /// + /// Though the zip specification doesn't prohibit zipfiles with duplicate + /// entries, Sane zip files have no duplicates, and the DotNetZip library + /// cannot create zip files with duplicate entries. If an application attempts + /// to call with a name that duplicates one + /// already used within the archive, the library will throw an Exception. + /// + /// + /// This property allows the application to specify whether the + /// ZipOutputStream instance considers ordinal case when checking for + /// uniqueness of zip entries. + /// + /// + public bool IgnoreCase + { + get + { + return !_DontIgnoreCase; + } + + set + { + _DontIgnoreCase = !value; + } + + } + + + /// + /// Indicates whether to encode entry filenames and entry comments using + /// Unicode (UTF-8). + /// + /// + /// + /// + /// The + /// PKWare zip specification provides for encoding file names and file + /// comments in either the IBM437 code page, or in UTF-8. This flag selects + /// the encoding according to that specification. By default, this flag is + /// false, and filenames and comments are encoded into the zip file in the + /// IBM437 codepage. Setting this flag to true will specify that filenames + /// and comments that cannot be encoded with IBM437 will be encoded with + /// UTF-8. + /// + /// + /// + /// Zip files created with strict adherence to the PKWare specification with + /// respect to UTF-8 encoding can contain entries with filenames containing + /// any combination of Unicode characters, including the full range of + /// characters from Chinese, Latin, Hebrew, Greek, Cyrillic, and many other + /// alphabets. However, because at this time, the UTF-8 portion of the PKWare + /// specification is not broadly supported by other zip libraries and + /// utilities, such zip files may not be readable by your favorite zip tool or + /// archiver. In other words, interoperability will decrease if you set this + /// flag to true. + /// + /// + /// + /// In particular, Zip files created with strict adherence to the PKWare + /// specification with respect to UTF-8 encoding will not work well with + /// Explorer in Windows XP or Windows Vista, because Windows compressed + /// folders, as far as I know, do not support UTF-8 in zip files. Vista can + /// read the zip files, but shows the filenames incorrectly. Unpacking from + /// Windows Vista Explorer will result in filenames that have rubbish + /// characters in place of the high-order UTF-8 bytes. + /// + /// + /// + /// Also, zip files that use UTF-8 encoding will not work well with Java + /// applications that use the java.util.zip classes, as of v5.0 of the Java + /// runtime. The Java runtime does not correctly implement the PKWare + /// specification in this regard. + /// + /// + /// + /// As a result, we have the unfortunate situation that "correct" behavior by + /// the DotNetZip library with regard to Unicode encoding of filenames during + /// zip creation will result in zip files that are readable by strictly + /// compliant and current tools (for example the most recent release of the + /// commercial WinZip tool); but these zip files will not be readable by + /// various other tools or libraries, including Windows Explorer. + /// + /// + /// + /// The DotNetZip library can read and write zip files with UTF8-encoded + /// entries, according to the PKware spec. If you use DotNetZip for both + /// creating and reading the zip file, and you use UTF-8, there will be no + /// loss of information in the filenames. For example, using a self-extractor + /// created by this library will allow you to unpack files correctly with no + /// loss of information in the filenames. + /// + /// + /// + /// If you do not set this flag, it will remain false. If this flag is false, + /// the ZipOutputStream will encode all filenames and comments using + /// the IBM437 codepage. This can cause "loss of information" on some + /// filenames, but the resulting zipfile will be more interoperable with other + /// utilities. As an example of the loss of information, diacritics can be + /// lost. The o-tilde character will be down-coded to plain o. The c with a + /// cedilla (Unicode 0xE7) used in Portugese will be downcoded to a c. + /// Likewise, the O-stroke character (Unicode 248), used in Danish and + /// Norwegian, will be down-coded to plain o. Chinese characters cannot be + /// represented in codepage IBM437; when using the default encoding, Chinese + /// characters in filenames will be represented as ?. These are all examples + /// of "information loss". + /// + /// + /// + /// The loss of information associated to the use of the IBM437 encoding is + /// inconvenient, and can also lead to runtime errors. For example, using + /// IBM437, any sequence of 4 Chinese characters will be encoded as ????. If + /// your application creates a ZipOutputStream, does not set the + /// encoding, then adds two files, each with names of four Chinese characters + /// each, this will result in a duplicate filename exception. In the case + /// where you add a single file with a name containing four Chinese + /// characters, the zipfile will save properly, but extracting that file + /// later, with any zip tool, will result in an error, because the question + /// mark is not legal for use within filenames on Windows. These are just a + /// few examples of the problems associated to loss of information. + /// + /// + /// + /// This flag is independent of the encoding of the content within the entries + /// in the zip file. Think of the zip file as a container - it supports an + /// encoding. Within the container are other "containers" - the file entries + /// themselves. The encoding within those entries is independent of the + /// encoding of the zip archive container for those entries. + /// + /// + /// + /// Rather than specify the encoding in a binary fashion using this flag, an + /// application can specify an arbitrary encoding via the property. Setting the encoding + /// explicitly when creating zip archives will result in non-compliant zip + /// files that, curiously, are fairly interoperable. The challenge is, the + /// PKWare specification does not provide for a way to specify that an entry + /// in a zip archive uses a code page that is neither IBM437 nor UTF-8. + /// Therefore if you set the encoding explicitly when creating a zip archive, + /// you must take care upon reading the zip archive to use the same code page. + /// If you get it wrong, the behavior is undefined and may result in incorrect + /// filenames, exceptions, stomach upset, hair loss, and acne. + /// + /// + /// + [Obsolete("Beginning with v1.9.1.6 of DotNetZip, this property is obsolete. It will be removed in a future version of the library. Use AlternateEncoding and AlternateEncodingUsage instead.")] + public bool UseUnicodeAsNecessary + { + get + { + return (_alternateEncoding == System.Text.Encoding.UTF8) && + (AlternateEncodingUsage == ZipOption.AsNecessary); + } + set + { + if (value) + { + _alternateEncoding = System.Text.Encoding.UTF8; + _alternateEncodingUsage = ZipOption.AsNecessary; + + } + else + { + _alternateEncoding = Ionic.Zip.ZipOutputStream.DefaultEncoding; + _alternateEncodingUsage = ZipOption.Never; + } + } + } + + + /// + /// The text encoding to use when emitting entries into the zip archive, for + /// those entries whose filenames or comments cannot be encoded with the + /// default (IBM437) encoding. + /// + /// + /// + /// + /// In its + /// zip specification, PKWare describes two options for encoding + /// filenames and comments: using IBM437 or UTF-8. But, some archiving tools + /// or libraries do not follow the specification, and instead encode + /// characters using the system default code page. For example, WinRAR when + /// run on a machine in Shanghai may encode filenames with the Big-5 Chinese + /// (950) code page. This behavior is contrary to the Zip specification, but + /// it occurs anyway. + /// + /// + /// + /// When using DotNetZip to write zip archives that will be read by one of + /// these other archivers, set this property to specify the code page to use + /// when encoding the and for each ZipEntry in the zip file, for + /// values that cannot be encoded with the default codepage for zip files, + /// IBM437. This is why this property is "provisional". In all cases, IBM437 + /// is used where possible, in other words, where no loss of data would + /// result. It is possible, therefore, to have a given entry with a + /// Comment encoded in IBM437 and a FileName encoded with the + /// specified "provisional" codepage. + /// + /// + /// + /// Be aware that a zip file created after you've explicitly set the + /// ProvisionalAlternateEncoding property to a value other than + /// IBM437 may not be compliant to the PKWare specification, and may not be + /// readable by compliant archivers. On the other hand, many (most?) + /// archivers are non-compliant and can read zip files created in arbitrary + /// code pages. The trick is to use or specify the proper codepage when + /// reading the zip. + /// + /// + /// + /// When creating a zip archive using this library, it is possible to change + /// the value of ProvisionalAlternateEncoding between each entry you + /// add, and between adding entries and the call to Close(). Don't do + /// this. It will likely result in a zipfile that is not readable. For best + /// interoperability, either leave ProvisionalAlternateEncoding + /// alone, or specify it only once, before adding any entries to the + /// ZipOutputStream instance. There is one exception to this + /// recommendation, described later. + /// + /// + /// + /// When using an arbitrary, non-UTF8 code page for encoding, there is no + /// standard way for the creator application - whether DotNetZip, WinZip, + /// WinRar, or something else - to formally specify in the zip file which + /// codepage has been used for the entries. As a result, readers of zip files + /// are not able to inspect the zip file and determine the codepage that was + /// used for the entries contained within it. It is left to the application + /// or user to determine the necessary codepage when reading zip files encoded + /// this way. If you use an incorrect codepage when reading a zipfile, you + /// will get entries with filenames that are incorrect, and the incorrect + /// filenames may even contain characters that are not legal for use within + /// filenames in Windows. Extracting entries with illegal characters in the + /// filenames will lead to exceptions. It's too bad, but this is just the way + /// things are with code pages in zip files. Caveat Emptor. + /// + /// + /// + /// One possible approach for specifying the code page for a given zip file is + /// to describe the code page in a human-readable form in the Zip comment. For + /// example, the comment may read "Entries in this archive are encoded in the + /// Big5 code page". For maximum interoperability, the zip comment in this + /// case should be encoded in the default, IBM437 code page. In this case, + /// the zip comment is encoded using a different page than the filenames. To + /// do this, Specify ProvisionalAlternateEncoding to your desired + /// region-specific code page, once before adding any entries, and then set + /// the property and reset + /// ProvisionalAlternateEncoding to IBM437 before calling Close(). + /// + /// + [Obsolete("use AlternateEncoding and AlternateEncodingUsage instead.")] + public System.Text.Encoding ProvisionalAlternateEncoding + { + get + { + if (_alternateEncodingUsage == ZipOption.AsNecessary) + return _alternateEncoding; + return null; + } + set + { + _alternateEncoding = value; + _alternateEncodingUsage = ZipOption.AsNecessary; + } + } + + /// + /// A Text Encoding to use when encoding the filenames and comments for + /// all the ZipEntry items, during a ZipFile.Save() operation. + /// + /// + /// + /// Whether the encoding specified here is used during the save depends + /// on . + /// + /// + public System.Text.Encoding AlternateEncoding + { + get + { + return _alternateEncoding; + } + set + { + _alternateEncoding = value; + } + } + + /// + /// A flag that tells if and when this instance should apply + /// AlternateEncoding to encode the filenames and comments associated to + /// of ZipEntry objects contained within this instance. + /// + public ZipOption AlternateEncodingUsage + { + get + { + return _alternateEncodingUsage; + } + set + { + _alternateEncodingUsage = value; + } + } + + /// + /// The default text encoding used in zip archives. It is numeric 437, also + /// known as IBM437. + /// + /// + public static System.Text.Encoding DefaultEncoding + { + get + { + return System.Text.Encoding.GetEncoding("IBM437"); + } + } + + +#if !NETCF + /// + /// The size threshold for an entry, above which a parallel deflate is used. + /// + /// + /// + /// + /// + /// DotNetZip will use multiple threads to compress any ZipEntry, when + /// the CompressionMethod is Deflate, and if the entry is + /// larger than the given size. Zero means "always use parallel + /// deflate", while -1 means "never use parallel deflate". + /// + /// + /// + /// If the entry size cannot be known before compression, as with any entry + /// added via a ZipOutputStream, then Parallel deflate will never be + /// performed, unless the value of this property is zero. + /// + /// + /// + /// A parallel deflate operations will speed up the compression of + /// large files, on computers with multiple CPUs or multiple CPU + /// cores. For files above 1mb, on a dual core or dual-cpu (2p) + /// machine, the time required to compress the file can be 70% of the + /// single-threaded deflate. For very large files on 4p machines the + /// compression can be done in 30% of the normal time. The downside + /// is that parallel deflate consumes extra memory during the deflate, + /// and the deflation is slightly less effective. + /// + /// + /// + /// Parallel deflate tends to not be as effective as single-threaded deflate + /// because the original data stream is split into multiple independent + /// buffers, each of which is compressed in parallel. But because they are + /// treated independently, there is no opportunity to share compression + /// dictionaries, and additional framing bytes must be added to the output + /// stream. For that reason, a deflated stream may be slightly larger when + /// compressed using parallel deflate, as compared to a traditional + /// single-threaded deflate. For files of about 512k, the increase over the + /// normal deflate is as much as 5% of the total compressed size. For larger + /// files, the difference can be as small as 0.1%. + /// + /// + /// + /// Multi-threaded compression does not give as much an advantage when using + /// Encryption. This is primarily because encryption tends to slow down + /// the entire pipeline. Also, multi-threaded compression gives less of an + /// advantage when using lower compression levels, for example . You may have to perform + /// some tests to determine the best approach for your situation. + /// + /// + /// + /// The default value for this property is -1, which means parallel + /// compression will not be performed unless you set it to zero. + /// + /// + /// + public long ParallelDeflateThreshold + { + set + { + if ((value != 0) && (value != -1) && (value < 64 * 1024)) + throw new ArgumentOutOfRangeException("value must be greater than 64k, or 0, or -1"); + _ParallelDeflateThreshold = value; + } + get + { + return _ParallelDeflateThreshold; + } + } + + + /// + /// The maximum number of buffer pairs to use when performing + /// parallel compression. + /// + /// + /// + /// + /// This property sets an upper limit on the number of memory + /// buffer pairs to create when performing parallel + /// compression. The implementation of the parallel + /// compression stream allocates multiple buffers to + /// facilitate parallel compression. As each buffer fills up, + /// the stream uses + /// ThreadPool.QueueUserWorkItem() to compress those + /// buffers in a background threadpool thread. After a buffer + /// is compressed, it is re-ordered and written to the output + /// stream. + /// + /// + /// + /// A higher number of buffer pairs enables a higher degree of + /// parallelism, which tends to increase the speed of compression on + /// multi-cpu computers. On the other hand, a higher number of buffer + /// pairs also implies a larger memory consumption, more active worker + /// threads, and a higher cpu utilization for any compression. This + /// property enables the application to limit its memory consumption and + /// CPU utilization behavior depending on requirements. + /// + /// + /// + /// For each compression "task" that occurs in parallel, there are 2 + /// buffers allocated: one for input and one for output. This property + /// sets a limit for the number of pairs. The total amount of storage + /// space allocated for buffering will then be (N*S*2), where N is the + /// number of buffer pairs, S is the size of each buffer (). By default, DotNetZip allocates 4 buffer + /// pairs per CPU core, so if your machine has 4 cores, and you retain + /// the default buffer size of 128k, then the + /// ParallelDeflateOutputStream will use 4 * 4 * 2 * 128kb of buffer + /// memory in total, or 4mb, in blocks of 128kb. If you then set this + /// property to 8, then the number will be 8 * 2 * 128kb of buffer + /// memory, or 2mb. + /// + /// + /// + /// CPU utilization will also go up with additional buffers, because a + /// larger number of buffer pairs allows a larger number of background + /// threads to compress in parallel. If you find that parallel + /// compression is consuming too much memory or CPU, you can adjust this + /// value downward. + /// + /// + /// + /// The default value is 16. Different values may deliver better or + /// worse results, depending on your priorities and the dynamic + /// performance characteristics of your storage and compute resources. + /// + /// + /// + /// This property is not the number of buffer pairs to use; it is an + /// upper limit. An illustration: Suppose you have an application that + /// uses the default value of this property (which is 16), and it runs + /// on a machine with 2 CPU cores. In that case, DotNetZip will allocate + /// 4 buffer pairs per CPU core, for a total of 8 pairs. The upper + /// limit specified by this property has no effect. + /// + /// + /// + /// The application can set this value at any time, but it is + /// effective only if set before calling + /// ZipOutputStream.Write() for the first time. + /// + /// + /// + /// + /// + public int ParallelDeflateMaxBufferPairs + { + get + { + return _maxBufferPairs; + } + set + { + if (value < 4) + throw new ArgumentOutOfRangeException("ParallelDeflateMaxBufferPairs", + "Value must be 4 or greater."); + _maxBufferPairs = value; + } + } +#endif + + + private void InsureUniqueEntry(ZipEntry ze1) + { + if (_entriesWritten.ContainsKey(ze1.FileName)) + { + _exceptionPending = true; + throw new ArgumentException(String.Format("The entry '{0}' already exists in the zip archive.", ze1.FileName)); + } + } + + + internal Stream OutputStream + { + get + { + return _outputStream; + } + } + + internal String Name + { + get + { + return _name; + } + } + + /// + /// Returns true if an entry by the given name has already been written + /// to the ZipOutputStream. + /// + /// + /// + /// The name of the entry to scan for. + /// + /// + /// + /// true if an entry by the given name has already been written. + /// + public bool ContainsEntry(string name) + { + return _entriesWritten.ContainsKey(SharedUtilities.NormalizePathForUseInZipFile(name)); + } + + + /// + /// Write the data from the buffer to the stream. + /// + /// + /// + /// As the application writes data into this stream, the data may be + /// compressed and encrypted before being written out to the underlying + /// stream, depending on the settings of the + /// and the properties. + /// + /// + /// The buffer holding data to write to the stream. + /// the offset within that data array to find the first byte to write. + /// the number of bytes to write. + public override void Write(byte[] buffer, int offset, int count) + { + if (_disposed) + { + _exceptionPending = true; + throw new System.InvalidOperationException("The stream has been closed."); + } + + if (buffer==null) + { + _exceptionPending = true; + throw new System.ArgumentNullException("buffer"); + } + + if (_currentEntry == null) + { + _exceptionPending = true; + throw new System.InvalidOperationException("You must call PutNextEntry() before calling Write()."); + } + + if (_currentEntry.IsDirectory) + { + _exceptionPending = true; + throw new System.InvalidOperationException("You cannot Write() data for an entry that is a directory."); + } + + if (_needToWriteEntryHeader) + _InitiateCurrentEntry(false); + + if (count != 0) + _entryOutputStream.Write(buffer, offset, count); + } + + + + /// + /// Specify the name of the next entry that will be written to the zip file. + /// + /// + /// + /// + /// Call this method just before calling , to + /// specify the name of the entry that the next set of bytes written to + /// the ZipOutputStream belongs to. All subsequent calls to Write, + /// until the next call to PutNextEntry, + /// will be inserted into the named entry in the zip file. + /// + /// + /// + /// If the used in PutNextEntry() ends in + /// a slash, then the entry added is marked as a directory. Because directory + /// entries do not contain data, a call to Write(), before an + /// intervening additional call to PutNextEntry(), will throw an + /// exception. + /// + /// + /// + /// If you don't call Write() between two calls to + /// PutNextEntry(), the first entry is inserted into the zip file as a + /// file of zero size. This may be what you want. + /// + /// + /// + /// Because PutNextEntry() closes out the prior entry, if any, this + /// method may throw if there is a problem with the prior entry. + /// + /// + /// + /// This method returns the ZipEntry. You can modify public properties + /// on the ZipEntry, such as , , and so on, until the first call to + /// ZipOutputStream.Write(), or until the next call to + /// PutNextEntry(). If you modify the ZipEntry after + /// having called Write(), you may get a runtime exception, or you may + /// silently get an invalid zip archive. + /// + /// + /// + /// + /// + /// + /// This example shows how to create a zip file, using the + /// ZipOutputStream class. + /// + /// + /// private void Zipup() + /// { + /// using (FileStream fs raw = File.Open(_outputFileName, FileMode.Create, FileAccess.ReadWrite )) + /// { + /// using (var output= new ZipOutputStream(fs)) + /// { + /// output.Password = "VerySecret!"; + /// output.Encryption = EncryptionAlgorithm.WinZipAes256; + /// output.PutNextEntry("entry1.txt"); + /// byte[] buffer= System.Text.Encoding.ASCII.GetBytes("This is the content for entry #1."); + /// output.Write(buffer,0,buffer.Length); + /// output.PutNextEntry("entry2.txt"); // this will be zero length + /// output.PutNextEntry("entry3.txt"); + /// buffer= System.Text.Encoding.ASCII.GetBytes("This is the content for entry #3."); + /// output.Write(buffer,0,buffer.Length); + /// } + /// } + /// } + /// + /// + /// + /// + /// The name of the entry to be added, including any path to be used + /// within the zip file. + /// + /// + /// + /// The ZipEntry created. + /// + /// + public ZipEntry PutNextEntry(String entryName) + { + if (String.IsNullOrEmpty(entryName)) + throw new ArgumentNullException("entryName"); + + if (_disposed) + { + _exceptionPending = true; + throw new System.InvalidOperationException("The stream has been closed."); + } + + _FinishCurrentEntry(); + _currentEntry = ZipEntry.CreateForZipOutputStream(entryName); + _currentEntry._container = new ZipContainer(this); + _currentEntry._BitField |= 0x0008; // workitem 8932 + _currentEntry.SetEntryTimes(DateTime.Now, DateTime.Now, DateTime.Now); + _currentEntry.CompressionLevel = this.CompressionLevel; + _currentEntry.CompressionMethod = this.CompressionMethod; + _currentEntry.Password = _password; // workitem 13909 + _currentEntry.Encryption = this.Encryption; + // workitem 12634 + _currentEntry.AlternateEncoding = this.AlternateEncoding; + _currentEntry.AlternateEncodingUsage = this.AlternateEncodingUsage; + + if (entryName.EndsWith("/")) _currentEntry.MarkAsDirectory(); + + _currentEntry.EmitTimesInWindowsFormatWhenSaving = ((_timestamp & ZipEntryTimestamp.Windows) != 0); + _currentEntry.EmitTimesInUnixFormatWhenSaving = ((_timestamp & ZipEntryTimestamp.Unix) != 0); + InsureUniqueEntry(_currentEntry); + _needToWriteEntryHeader = true; + + return _currentEntry; + } + + + + private void _InitiateCurrentEntry(bool finishing) + { + // If finishing==true, this means we're initiating the entry at the time of + // Close() or PutNextEntry(). If this happens, it means no data was written + // for the entry - Write() was never called. (The usual case us to call + // _InitiateCurrentEntry(bool) from within Write().) If finishing==true, + // the entry could be either a zero-byte file or a directory. + + _entriesWritten.Add(_currentEntry.FileName,_currentEntry); + _entryCount++; // could use _entriesWritten.Count, but I don't want to incur + // the cost. + + if (_entryCount > 65534 && _zip64 == Zip64Option.Never) + { + _exceptionPending = true; + throw new System.InvalidOperationException("Too many entries. Consider setting ZipOutputStream.EnableZip64."); + } + + // Write out the header. + // + // If finishing, and encryption is in use, then we don't want to emit the + // normal encryption header. Signal that with a cycle=99 to turn off + // encryption for zero-byte entries or directories. + // + // If finishing, then we know the stream length is zero. Else, unknown + // stream length. Passing stream length == 0 allows an optimization so as + // not to setup an encryption or deflation stream, when stream length is + // zero. + + _currentEntry.WriteHeader(_outputStream, finishing ? 99 : 0); + _currentEntry.StoreRelativeOffset(); + + if (!_currentEntry.IsDirectory) + { + _currentEntry.WriteSecurityMetadata(_outputStream); + _currentEntry.PrepOutputStream(_outputStream, + finishing ? 0 : -1, + out _outputCounter, + out _encryptor, + out _deflater, + out _entryOutputStream); + } + _needToWriteEntryHeader = false; + } + + + + private void _FinishCurrentEntry() + { + if (_currentEntry != null) + { + if (_needToWriteEntryHeader) + _InitiateCurrentEntry(true); // an empty entry - no writes + + _currentEntry.FinishOutputStream(_outputStream, _outputCounter, _encryptor, _deflater, _entryOutputStream); + _currentEntry.PostProcessOutput(_outputStream); + // workitem 12964 + if (_currentEntry.OutputUsedZip64!=null) + _anyEntriesUsedZip64 |= _currentEntry.OutputUsedZip64.Value; + + // reset all the streams + _outputCounter = null; _encryptor = _deflater = null; _entryOutputStream = null; + } + } + + + + /// + /// Dispose the stream + /// + /// + /// + /// + /// This method writes the Zip Central directory, then closes the stream. The + /// application must call Dispose() (or Close) in order to produce a valid zip file. + /// + /// + /// + /// Typically the application will call Dispose() implicitly, via a using + /// statement in C#, or a Using statement in VB. + /// + /// + /// + /// + /// set this to true, always. + protected override void Dispose(bool disposing) + { + if (_disposed) return; + + if (disposing) // not called from finalizer + { + // handle pending exceptions + if (!_exceptionPending) + { + _FinishCurrentEntry(); + _directoryNeededZip64 = ZipOutput.WriteCentralDirectoryStructure(_outputStream, + _entriesWritten.Values, + 1, // _numberOfSegmentsForMostRecentSave, + _zip64, + Comment, + new ZipContainer(this)); + Stream wrappedStream = null; + CountingStream cs = _outputStream as CountingStream; + if (cs != null) + { + wrappedStream = cs.WrappedStream; +#if NETCF + cs.Close(); +#else + cs.Dispose(); +#endif + } + else + { + wrappedStream = _outputStream; + } + + if (!_leaveUnderlyingStreamOpen) + { +#if NETCF + wrappedStream.Close(); +#else + wrappedStream.Dispose(); +#endif + } + _outputStream = null; + } + } + _disposed = true; + } + + + + /// + /// Always returns false. + /// + public override bool CanRead { get { return false; } } + + /// + /// Always returns false. + /// + public override bool CanSeek { get { return false; } } + + /// + /// Always returns true. + /// + public override bool CanWrite { get { return true; } } + + /// + /// Always returns a NotSupportedException. + /// + public override long Length { get { throw new NotSupportedException(); } } + + /// + /// Setting this property always returns a NotSupportedException. Getting it + /// returns the value of the Position on the underlying stream. + /// + public override long Position + { + get { return _outputStream.Position; } + set { throw new NotSupportedException(); } + } + + /// + /// This is a no-op. + /// + public override void Flush() { } + + /// + /// This method always throws a NotSupportedException. + /// + /// ignored + /// ignored + /// ignored + /// nothing + public override int Read(byte[] buffer, int offset, int count) + { + throw new NotSupportedException("Read"); + } + + /// + /// This method always throws a NotSupportedException. + /// + /// ignored + /// ignored + /// nothing + public override long Seek(long offset, SeekOrigin origin) + { + throw new NotSupportedException("Seek"); + } + + /// + /// This method always throws a NotSupportedException. + /// + /// ignored + public override void SetLength(long value) + { + throw new NotSupportedException(); + } + + + private EncryptionAlgorithm _encryption; + private ZipEntryTimestamp _timestamp; + internal String _password; + private String _comment; + private Stream _outputStream; + private ZipEntry _currentEntry; + internal Zip64Option _zip64; + private Dictionary _entriesWritten; + private int _entryCount; + private ZipOption _alternateEncodingUsage = ZipOption.Never; + private System.Text.Encoding _alternateEncoding + = System.Text.Encoding.GetEncoding("IBM437"); // default = IBM437 + + private bool _leaveUnderlyingStreamOpen; + private bool _disposed; + private bool _exceptionPending; // **see note below + private bool _anyEntriesUsedZip64, _directoryNeededZip64; + private CountingStream _outputCounter; + private Stream _encryptor; + private Stream _deflater; + private Ionic.Crc.CrcCalculatorStream _entryOutputStream; + private bool _needToWriteEntryHeader; + private string _name; + private bool _DontIgnoreCase; +#if !NETCF + internal Ionic.Zlib.ParallelDeflateOutputStream ParallelDeflater; + private long _ParallelDeflateThreshold; + private int _maxBufferPairs = 16; +#endif + + // **Note regarding exceptions: + + // When ZipOutputStream is employed within a using clause, which + // is the typical scenario, and an exception is thrown within + // the scope of the using, Close()/Dispose() is invoked + // implicitly before processing the initial exception. In that + // case, _exceptionPending is true, and we don't want to try to + // write anything in the Close/Dispose logic. Doing so can + // cause additional exceptions that mask the original one. So, + // the _exceptionPending flag is used to track that, and to + // allow the original exception to be propagated to the + // application without extra "noise." + + } + + + + internal class ZipContainer + { + private ZipFile _zf; + private ZipOutputStream _zos; + private ZipInputStream _zis; + + public ZipContainer(Object o) + { + _zf = (o as ZipFile); + _zos = (o as ZipOutputStream); + _zis = (o as ZipInputStream); + } + + public ZipFile ZipFile + { + get { return _zf; } + } + + public ZipOutputStream ZipOutputStream + { + get { return _zos; } + } + + public string Name + { + get + { + if (_zf != null) return _zf.Name; + if (_zis != null) throw new NotSupportedException(); + return _zos.Name; + } + } + + public string Password + { + get + { + if (_zf != null) return _zf._Password; + if (_zis != null) return _zis._Password; + return _zos._password; + } + } + + public Zip64Option Zip64 + { + get + { + if (_zf != null) return _zf._zip64; + if (_zis != null) throw new NotSupportedException(); + return _zos._zip64; + } + } + + public int BufferSize + { + get + { + if (_zf != null) return _zf.BufferSize; + if (_zis != null) throw new NotSupportedException(); + return 0; + } + } + +#if !NETCF + public Ionic.Zlib.ParallelDeflateOutputStream ParallelDeflater + { + get + { + if (_zf != null) return _zf.ParallelDeflater; + if (_zis != null) return null; + return _zos.ParallelDeflater; + } + set + { + if (_zf != null) _zf.ParallelDeflater = value; + else if (_zos != null) _zos.ParallelDeflater = value; + } + } + + public long ParallelDeflateThreshold + { + get + { + if (_zf != null) return _zf.ParallelDeflateThreshold; + return _zos.ParallelDeflateThreshold; + } + } + public int ParallelDeflateMaxBufferPairs + { + get + { + if (_zf != null) return _zf.ParallelDeflateMaxBufferPairs; + return _zos.ParallelDeflateMaxBufferPairs; + } + } +#endif + + public int CodecBufferSize + { + get + { + if (_zf != null) return _zf.CodecBufferSize; + if (_zis != null) return _zis.CodecBufferSize; + return _zos.CodecBufferSize; + } + } + + public Ionic.Zlib.CompressionStrategy Strategy + { + get + { + if (_zf != null) return _zf.Strategy; + return _zos.Strategy; + } + } + + public Zip64Option UseZip64WhenSaving + { + get + { + if (_zf != null) return _zf.UseZip64WhenSaving; + return _zos.EnableZip64; + } + } + + public System.Text.Encoding AlternateEncoding + { + get + { + if (_zf != null) return _zf.AlternateEncoding; + if (_zos!=null) return _zos.AlternateEncoding; + return null; + } + } + public System.Text.Encoding DefaultEncoding + { + get + { + if (_zf != null) return ZipFile.DefaultEncoding; + if (_zos!=null) return ZipOutputStream.DefaultEncoding; + return null; + } + } + public ZipOption AlternateEncodingUsage + { + get + { + if (_zf != null) return _zf.AlternateEncodingUsage; + if (_zos!=null) return _zos.AlternateEncodingUsage; + return ZipOption.Never; // n/a + } + } + + public Stream ReadStream + { + get + { + if (_zf != null) return _zf.ReadStream; + return _zis.ReadStream; + } + } + } + +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/Zip/ZipSegmentedStream.cs b/Resources/Libraries/DotNetZip/Source/Zip/ZipSegmentedStream.cs new file mode 100644 index 00000000..bb27b12d --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zip/ZipSegmentedStream.cs @@ -0,0 +1,571 @@ +// ZipSegmentedStream.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009-2011 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-13 22:25:45> +// +// ------------------------------------------------------------------ +// +// This module defines logic for zip streams that span disk files. +// +// ------------------------------------------------------------------ + + +using System; +using System.Collections.Generic; +using System.IO; + +namespace Ionic.Zip +{ + internal class ZipSegmentedStream : System.IO.Stream + { + enum RwMode + { + None = 0, + ReadOnly = 1, + Write = 2, + //Update = 3 + } + + private RwMode rwMode; + private bool _exceptionPending; // **see note below + private string _baseName; + private string _baseDir; + //private bool _isDisposed; + private string _currentName; + private string _currentTempName; + private uint _currentDiskNumber; + private uint _maxDiskNumber; + private int _maxSegmentSize; + private System.IO.Stream _innerStream; + + // **Note regarding exceptions: + // + // When ZipSegmentedStream is employed within a using clause, + // which is the typical scenario, and an exception is thrown + // within the scope of the using, Dispose() is invoked + // implicitly before processing the initial exception. If that + // happens, this class sets _exceptionPending to true, and then + // within the Dispose(bool), takes special action as + // appropriate. Need to be careful: any additional exceptions + // will mask the original one. + + private ZipSegmentedStream() : base() + { + _exceptionPending = false; + } + + public static ZipSegmentedStream ForReading(string name, + uint initialDiskNumber, + uint maxDiskNumber) + { + ZipSegmentedStream zss = new ZipSegmentedStream() + { + rwMode = RwMode.ReadOnly, + CurrentSegment = initialDiskNumber, + _maxDiskNumber = maxDiskNumber, + _baseName = name, + }; + + // Console.WriteLine("ZSS: ForReading ({0})", + // Path.GetFileName(zss.CurrentName)); + + zss._SetReadStream(); + + return zss; + } + + + public static ZipSegmentedStream ForWriting(string name, int maxSegmentSize) + { + ZipSegmentedStream zss = new ZipSegmentedStream() + { + rwMode = RwMode.Write, + CurrentSegment = 0, + _baseName = name, + _maxSegmentSize = maxSegmentSize, + _baseDir = Path.GetDirectoryName(name) + }; + + // workitem 9522 + if (zss._baseDir=="") zss._baseDir="."; + + zss._SetWriteStream(0); + + // Console.WriteLine("ZSS: ForWriting ({0})", + // Path.GetFileName(zss.CurrentName)); + + return zss; + } + + + /// + /// Sort-of like a factory method, ForUpdate is used only when + /// the application needs to update the zip entry metadata for + /// a segmented zip file, when the starting segment is earlier + /// than the ending segment, for a particular entry. + /// + /// + /// + /// The update is always contiguous, never rolls over. As a + /// result, this method doesn't need to return a ZSS; it can + /// simply return a FileStream. That's why it's "sort of" + /// like a Factory method. + /// + /// + /// Caller must Close/Dispose the stream object returned by + /// this method. + /// + /// + public static Stream ForUpdate(string name, uint diskNumber) + { + if (diskNumber >= 99) + throw new ArgumentOutOfRangeException("diskNumber"); + + string fname = + String.Format("{0}.z{1:D2}", + Path.Combine(Path.GetDirectoryName(name), + Path.GetFileNameWithoutExtension(name)), + diskNumber + 1); + + // Console.WriteLine("ZSS: ForUpdate ({0})", + // Path.GetFileName(fname)); + + // This class assumes that the update will not expand the + // size of the segment. Update is used only for an in-place + // update of zip metadata. It never will try to write beyond + // the end of a segment. + + return File.Open(fname, + FileMode.Open, + FileAccess.ReadWrite, + FileShare.None); + } + + public bool ContiguousWrite + { + get; + set; + } + + + public UInt32 CurrentSegment + { + get + { + return _currentDiskNumber; + } + private set + { + _currentDiskNumber = value; + _currentName = null; // it will get updated next time referenced + } + } + + /// + /// Name of the filesystem file corresponding to the current segment. + /// + /// + /// + /// The name is not always the name currently being used in the + /// filesystem. When rwMode is RwMode.Write, the filesystem file has a + /// temporary name until the stream is closed or until the next segment is + /// started. + /// + /// + public String CurrentName + { + get + { + if (_currentName==null) + _currentName = _NameForSegment(CurrentSegment); + + return _currentName; + } + } + + + public String CurrentTempName + { + get + { + return _currentTempName; + } + } + + private string _NameForSegment(uint diskNumber) + { + if (diskNumber >= 99) + { + _exceptionPending = true; + throw new OverflowException("The number of zip segments would exceed 99."); + } + + return String.Format("{0}.z{1:D2}", + Path.Combine(Path.GetDirectoryName(_baseName), + Path.GetFileNameWithoutExtension(_baseName)), + diskNumber + 1); + } + + + // Returns the segment that WILL be current if writing + // a block of the given length. + // This isn't exactly true. It could roll over beyond + // this number. + public UInt32 ComputeSegment(int length) + { + if (_innerStream.Position + length > _maxSegmentSize) + // the block will go AT LEAST into the next segment + return CurrentSegment + 1; + + // it will fit in the current segment + return CurrentSegment; + } + + + public override String ToString() + { + return String.Format("{0}[{1}][{2}], pos=0x{3:X})", + "ZipSegmentedStream", CurrentName, + rwMode.ToString(), + this.Position); + } + + + private void _SetReadStream() + { + if (_innerStream != null) + { +#if NETCF + _innerStream.Close(); +#else + _innerStream.Dispose(); +#endif + } + + if (CurrentSegment + 1 == _maxDiskNumber) + _currentName = _baseName; + + // Console.WriteLine("ZSS: SRS ({0})", + // Path.GetFileName(CurrentName)); + + _innerStream = File.OpenRead(CurrentName); + } + + + /// + /// Read from the stream + /// + /// the buffer to read + /// the offset at which to start + /// the number of bytes to read + /// the number of bytes actually read + public override int Read(byte[] buffer, int offset, int count) + { + if (rwMode != RwMode.ReadOnly) + { + _exceptionPending = true; + throw new InvalidOperationException("Stream Error: Cannot Read."); + } + + int r = _innerStream.Read(buffer, offset, count); + int r1 = r; + + while (r1 != count) + { + if (_innerStream.Position != _innerStream.Length) + { + _exceptionPending = true; + throw new ZipException(String.Format("Read error in file {0}", CurrentName)); + + } + + if (CurrentSegment + 1 == _maxDiskNumber) + return r; // no more to read + + CurrentSegment++; + _SetReadStream(); + offset += r1; + count -= r1; + r1 = _innerStream.Read(buffer, offset, count); + r += r1; + } + return r; + } + + + + private void _SetWriteStream(uint increment) + { + if (_innerStream != null) + { +#if NETCF + _innerStream.Close(); +#else + _innerStream.Dispose(); +#endif + if (File.Exists(CurrentName)) + File.Delete(CurrentName); + File.Move(_currentTempName, CurrentName); + // Console.WriteLine("ZSS: SWS close ({0})", + // Path.GetFileName(CurrentName)); + } + + if (increment > 0) + CurrentSegment += increment; + + SharedUtilities.CreateAndOpenUniqueTempFile(_baseDir, + out _innerStream, + out _currentTempName); + + // Console.WriteLine("ZSS: SWS open ({0})", + // Path.GetFileName(_currentTempName)); + + if (CurrentSegment == 0) + _innerStream.Write(BitConverter.GetBytes(ZipConstants.SplitArchiveSignature), 0, 4); + } + + + /// + /// Write to the stream. + /// + /// the buffer from which to write + /// the offset at which to start writing + /// the number of bytes to write + public override void Write(byte[] buffer, int offset, int count) + { + if (rwMode != RwMode.Write) + { + _exceptionPending = true; + throw new InvalidOperationException("Stream Error: Cannot Write."); + } + + + if (ContiguousWrite) + { + // enough space for a contiguous write? + if (_innerStream.Position + count > _maxSegmentSize) + _SetWriteStream(1); + } + else + { + while (_innerStream.Position + count > _maxSegmentSize) + { + int c = unchecked(_maxSegmentSize - (int)_innerStream.Position); + _innerStream.Write(buffer, offset, c); + _SetWriteStream(1); + count -= c; + offset += c; + } + } + + _innerStream.Write(buffer, offset, count); + } + + + public long TruncateBackward(uint diskNumber, long offset) + { + // Console.WriteLine("***ZSS.Trunc to disk {0}", diskNumber); + // Console.WriteLine("***ZSS.Trunc: current disk {0}", CurrentSegment); + if (diskNumber >= 99) + throw new ArgumentOutOfRangeException("diskNumber"); + + if (rwMode != RwMode.Write) + { + _exceptionPending = true; + throw new ZipException("bad state."); + } + + // Seek back in the segmented stream to a (maybe) prior segment. + + // Check if it is the same segment. If it is, very simple. + if (diskNumber == CurrentSegment) + { + var x =_innerStream.Seek(offset, SeekOrigin.Begin); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(_innerStream); + return x; + } + + // Seeking back to a prior segment. + // The current segment and any intervening segments must be removed. + // First, close the current segment, and then remove it. + if (_innerStream != null) + { +#if NETCF + _innerStream.Close(); +#else + _innerStream.Dispose(); +#endif + if (File.Exists(_currentTempName)) + File.Delete(_currentTempName); + } + + // Now, remove intervening segments. + for (uint j= CurrentSegment-1; j > diskNumber; j--) + { + string s = _NameForSegment(j); + // Console.WriteLine("***ZSS.Trunc: removing file {0}", s); + if (File.Exists(s)) + File.Delete(s); + } + + // now, open the desired segment. It must exist. + CurrentSegment = diskNumber; + + // get a new temp file, try 3 times: + for (int i = 0; i < 3; i++) + { + try + { + _currentTempName = SharedUtilities.InternalGetTempFileName(); + // move the .z0x file back to a temp name + File.Move(CurrentName, _currentTempName); + break; // workitem 12403 + } + catch(IOException) + { + if (i == 2) throw; + } + } + + // open it + _innerStream = new FileStream(_currentTempName, FileMode.Open); + + var r = _innerStream.Seek(offset, SeekOrigin.Begin); + + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(_innerStream); + + return r; + } + + + + public override bool CanRead + { + get + { + return (rwMode == RwMode.ReadOnly && + (_innerStream != null) && + _innerStream.CanRead); + } + } + + + public override bool CanSeek + { + get + { + return (_innerStream != null) && + _innerStream.CanSeek; + } + } + + + public override bool CanWrite + { + get + { + return (rwMode == RwMode.Write) && + (_innerStream != null) && + _innerStream.CanWrite; + } + } + + public override void Flush() + { + _innerStream.Flush(); + } + + public override long Length + { + get + { + return _innerStream.Length; + } + } + + public override long Position + { + get { return _innerStream.Position; } + set { _innerStream.Position = value; } + } + + public override long Seek(long offset, System.IO.SeekOrigin origin) + { + var x = _innerStream.Seek(offset, origin); + // workitem 10178 + Ionic.Zip.SharedUtilities.Workaround_Ladybug318918(_innerStream); + return x; + } + + public override void SetLength(long value) + { + if (rwMode != RwMode.Write) + { + _exceptionPending = true; + throw new InvalidOperationException(); + } + _innerStream.SetLength(value); + } + + + protected override void Dispose(bool disposing) + { + // this gets called by Stream.Close() + + // if (_isDisposed) return; + // _isDisposed = true; + //Console.WriteLine("Dispose (mode={0})\n", rwMode.ToString()); + + try + { + if (_innerStream != null) + { +#if NETCF + _innerStream.Close(); +#else + _innerStream.Dispose(); +#endif + //_innerStream = null; + if (rwMode == RwMode.Write) + { + if (_exceptionPending) + { + // possibly could try to clean up all the + // temp files created so far... + } + else + { + // // move the final temp file to the .zNN name + // if (File.Exists(CurrentName)) + // File.Delete(CurrentName); + // if (File.Exists(_currentTempName)) + // File.Move(_currentTempName, CurrentName); + } + } + } + } + finally + { + base.Dispose(disposing); + } + } + + } + +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/Zlib/Deflate.cs b/Resources/Libraries/DotNetZip/Source/Zlib/Deflate.cs new file mode 100644 index 00000000..be401b8d --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zlib/Deflate.cs @@ -0,0 +1,1879 @@ +// Deflate.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa and Microsoft Corporation. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-August-03 19:52:15> +// +// ------------------------------------------------------------------ +// +// This module defines logic for handling the Deflate or compression. +// +// This code is based on multiple sources: +// - the original zlib v1.2.3 source, which is Copyright (C) 1995-2005 Jean-loup Gailly. +// - the original jzlib, which is Copyright (c) 2000-2003 ymnk, JCraft,Inc. +// +// However, this code is significantly different from both. +// The object model is not the same, and many of the behaviors are different. +// +// In keeping with the license for these other works, the copyrights for +// jzlib and zlib are here. +// +// ----------------------------------------------------------------------- +// Copyright (c) 2000,2001,2002,2003 ymnk, JCraft,Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// 1. Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// +// 2. Redistributions in binary form must reproduce the above copyright +// notice, this list of conditions and the following disclaimer in +// the documentation and/or other materials provided with the distribution. +// +// 3. The names of the authors may not be used to endorse or promote products +// derived from this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, +// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND +// FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JCRAFT, +// INC. OR ANY CONTRIBUTORS TO THIS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, +// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, +// OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +// EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// ----------------------------------------------------------------------- +// +// This program is based on zlib-1.1.3; credit to authors +// Jean-loup Gailly(jloup@gzip.org) and Mark Adler(madler@alumni.caltech.edu) +// and contributors of zlib. +// +// ----------------------------------------------------------------------- + + +using System; + +namespace Ionic.Zlib +{ + + internal enum BlockState + { + NeedMore = 0, // block not completed, need more input or more output + BlockDone, // block flush performed + FinishStarted, // finish started, need only more output at next deflate + FinishDone // finish done, accept no more input or output + } + + internal enum DeflateFlavor + { + Store, + Fast, + Slow + } + + internal sealed class DeflateManager + { + private static readonly int MEM_LEVEL_MAX = 9; + private static readonly int MEM_LEVEL_DEFAULT = 8; + + internal delegate BlockState CompressFunc(FlushType flush); + + internal class Config + { + // Use a faster search when the previous match is longer than this + internal int GoodLength; // reduce lazy search above this match length + + // Attempt to find a better match only when the current match is + // strictly smaller than this value. This mechanism is used only for + // compression levels >= 4. For levels 1,2,3: MaxLazy is actually + // MaxInsertLength. (See DeflateFast) + + internal int MaxLazy; // do not perform lazy search above this match length + + internal int NiceLength; // quit search above this match length + + // To speed up deflation, hash chains are never searched beyond this + // length. A higher limit improves compression ratio but degrades the speed. + + internal int MaxChainLength; + + internal DeflateFlavor Flavor; + + private Config(int goodLength, int maxLazy, int niceLength, int maxChainLength, DeflateFlavor flavor) + { + this.GoodLength = goodLength; + this.MaxLazy = maxLazy; + this.NiceLength = niceLength; + this.MaxChainLength = maxChainLength; + this.Flavor = flavor; + } + + public static Config Lookup(CompressionLevel level) + { + return Table[(int)level]; + } + + + static Config() + { + Table = new Config[] { + new Config(0, 0, 0, 0, DeflateFlavor.Store), + new Config(4, 4, 8, 4, DeflateFlavor.Fast), + new Config(4, 5, 16, 8, DeflateFlavor.Fast), + new Config(4, 6, 32, 32, DeflateFlavor.Fast), + + new Config(4, 4, 16, 16, DeflateFlavor.Slow), + new Config(8, 16, 32, 32, DeflateFlavor.Slow), + new Config(8, 16, 128, 128, DeflateFlavor.Slow), + new Config(8, 32, 128, 256, DeflateFlavor.Slow), + new Config(32, 128, 258, 1024, DeflateFlavor.Slow), + new Config(32, 258, 258, 4096, DeflateFlavor.Slow), + }; + } + + private static readonly Config[] Table; + } + + + private CompressFunc DeflateFunction; + + private static readonly System.String[] _ErrorMessage = new System.String[] + { + "need dictionary", + "stream end", + "", + "file error", + "stream error", + "data error", + "insufficient memory", + "buffer error", + "incompatible version", + "" + }; + + // preset dictionary flag in zlib header + private static readonly int PRESET_DICT = 0x20; + + private static readonly int INIT_STATE = 42; + private static readonly int BUSY_STATE = 113; + private static readonly int FINISH_STATE = 666; + + // The deflate compression method + private static readonly int Z_DEFLATED = 8; + + private static readonly int STORED_BLOCK = 0; + private static readonly int STATIC_TREES = 1; + private static readonly int DYN_TREES = 2; + + // The three kinds of block type + private static readonly int Z_BINARY = 0; + private static readonly int Z_ASCII = 1; + private static readonly int Z_UNKNOWN = 2; + + private static readonly int Buf_size = 8 * 2; + + private static readonly int MIN_MATCH = 3; + private static readonly int MAX_MATCH = 258; + + private static readonly int MIN_LOOKAHEAD = (MAX_MATCH + MIN_MATCH + 1); + + private static readonly int HEAP_SIZE = (2 * InternalConstants.L_CODES + 1); + + private static readonly int END_BLOCK = 256; + + internal ZlibCodec _codec; // the zlib encoder/decoder + internal int status; // as the name implies + internal byte[] pending; // output still pending - waiting to be compressed + internal int nextPending; // index of next pending byte to output to the stream + internal int pendingCount; // number of bytes in the pending buffer + + internal sbyte data_type; // UNKNOWN, BINARY or ASCII + internal int last_flush; // value of flush param for previous deflate call + + internal int w_size; // LZ77 window size (32K by default) + internal int w_bits; // log2(w_size) (8..16) + internal int w_mask; // w_size - 1 + + //internal byte[] dictionary; + internal byte[] window; + + // Sliding window. Input bytes are read into the second half of the window, + // and move to the first half later to keep a dictionary of at least wSize + // bytes. With this organization, matches are limited to a distance of + // wSize-MAX_MATCH bytes, but this ensures that IO is always + // performed with a length multiple of the block size. + // + // To do: use the user input buffer as sliding window. + + internal int window_size; + // Actual size of window: 2*wSize, except when the user input buffer + // is directly used as sliding window. + + internal short[] prev; + // Link to older string with same hash index. To limit the size of this + // array to 64K, this link is maintained only for the last 32K strings. + // An index in this array is thus a window index modulo 32K. + + internal short[] head; // Heads of the hash chains or NIL. + + internal int ins_h; // hash index of string to be inserted + internal int hash_size; // number of elements in hash table + internal int hash_bits; // log2(hash_size) + internal int hash_mask; // hash_size-1 + + // Number of bits by which ins_h must be shifted at each input + // step. It must be such that after MIN_MATCH steps, the oldest + // byte no longer takes part in the hash key, that is: + // hash_shift * MIN_MATCH >= hash_bits + internal int hash_shift; + + // Window position at the beginning of the current output block. Gets + // negative when the window is moved backwards. + + internal int block_start; + + Config config; + internal int match_length; // length of best match + internal int prev_match; // previous match + internal int match_available; // set if previous match exists + internal int strstart; // start of string to insert into.....???? + internal int match_start; // start of matching string + internal int lookahead; // number of valid bytes ahead in window + + // Length of the best match at previous step. Matches not greater than this + // are discarded. This is used in the lazy match evaluation. + internal int prev_length; + + // Insert new strings in the hash table only if the match length is not + // greater than this length. This saves time but degrades compression. + // max_insert_length is used only for compression levels <= 3. + + internal CompressionLevel compressionLevel; // compression level (1..9) + internal CompressionStrategy compressionStrategy; // favor or force Huffman coding + + + internal short[] dyn_ltree; // literal and length tree + internal short[] dyn_dtree; // distance tree + internal short[] bl_tree; // Huffman tree for bit lengths + + internal Tree treeLiterals = new Tree(); // desc for literal tree + internal Tree treeDistances = new Tree(); // desc for distance tree + internal Tree treeBitLengths = new Tree(); // desc for bit length tree + + // number of codes at each bit length for an optimal tree + internal short[] bl_count = new short[InternalConstants.MAX_BITS + 1]; + + // heap used to build the Huffman trees + internal int[] heap = new int[2 * InternalConstants.L_CODES + 1]; + + internal int heap_len; // number of elements in the heap + internal int heap_max; // element of largest frequency + + // The sons of heap[n] are heap[2*n] and heap[2*n+1]. heap[0] is not used. + // The same heap array is used to build all trees. + + // Depth of each subtree used as tie breaker for trees of equal frequency + internal sbyte[] depth = new sbyte[2 * InternalConstants.L_CODES + 1]; + + internal int _lengthOffset; // index for literals or lengths + + + // Size of match buffer for literals/lengths. There are 4 reasons for + // limiting lit_bufsize to 64K: + // - frequencies can be kept in 16 bit counters + // - if compression is not successful for the first block, all input + // data is still in the window so we can still emit a stored block even + // when input comes from standard input. (This can also be done for + // all blocks if lit_bufsize is not greater than 32K.) + // - if compression is not successful for a file smaller than 64K, we can + // even emit a stored file instead of a stored block (saving 5 bytes). + // This is applicable only for zip (not gzip or zlib). + // - creating new Huffman trees less frequently may not provide fast + // adaptation to changes in the input data statistics. (Take for + // example a binary file with poorly compressible code followed by + // a highly compressible string table.) Smaller buffer sizes give + // fast adaptation but have of course the overhead of transmitting + // trees more frequently. + + internal int lit_bufsize; + + internal int last_lit; // running index in l_buf + + // Buffer for distances. To simplify the code, d_buf and l_buf have + // the same number of elements. To use different lengths, an extra flag + // array would be necessary. + + internal int _distanceOffset; // index into pending; points to distance data?? + + internal int opt_len; // bit length of current block with optimal trees + internal int static_len; // bit length of current block with static trees + internal int matches; // number of string matches in current block + internal int last_eob_len; // bit length of EOB code for last block + + // Output buffer. bits are inserted starting at the bottom (least + // significant bits). + internal short bi_buf; + + // Number of valid bits in bi_buf. All bits above the last valid bit + // are always zero. + internal int bi_valid; + + + internal DeflateManager() + { + dyn_ltree = new short[HEAP_SIZE * 2]; + dyn_dtree = new short[(2 * InternalConstants.D_CODES + 1) * 2]; // distance tree + bl_tree = new short[(2 * InternalConstants.BL_CODES + 1) * 2]; // Huffman tree for bit lengths + } + + + // lm_init + private void _InitializeLazyMatch() + { + window_size = 2 * w_size; + + // clear the hash - workitem 9063 + Array.Clear(head, 0, hash_size); + //for (int i = 0; i < hash_size; i++) head[i] = 0; + + config = Config.Lookup(compressionLevel); + SetDeflater(); + + strstart = 0; + block_start = 0; + lookahead = 0; + match_length = prev_length = MIN_MATCH - 1; + match_available = 0; + ins_h = 0; + } + + // Initialize the tree data structures for a new zlib stream. + private void _InitializeTreeData() + { + treeLiterals.dyn_tree = dyn_ltree; + treeLiterals.staticTree = StaticTree.Literals; + + treeDistances.dyn_tree = dyn_dtree; + treeDistances.staticTree = StaticTree.Distances; + + treeBitLengths.dyn_tree = bl_tree; + treeBitLengths.staticTree = StaticTree.BitLengths; + + bi_buf = 0; + bi_valid = 0; + last_eob_len = 8; // enough lookahead for inflate + + // Initialize the first block of the first file: + _InitializeBlocks(); + } + + internal void _InitializeBlocks() + { + // Initialize the trees. + for (int i = 0; i < InternalConstants.L_CODES; i++) + dyn_ltree[i * 2] = 0; + for (int i = 0; i < InternalConstants.D_CODES; i++) + dyn_dtree[i * 2] = 0; + for (int i = 0; i < InternalConstants.BL_CODES; i++) + bl_tree[i * 2] = 0; + + dyn_ltree[END_BLOCK * 2] = 1; + opt_len = static_len = 0; + last_lit = matches = 0; + } + + // Restore the heap property by moving down the tree starting at node k, + // exchanging a node with the smallest of its two sons if necessary, stopping + // when the heap property is re-established (each father smaller than its + // two sons). + internal void pqdownheap(short[] tree, int k) + { + int v = heap[k]; + int j = k << 1; // left son of k + while (j <= heap_len) + { + // Set j to the smallest of the two sons: + if (j < heap_len && _IsSmaller(tree, heap[j + 1], heap[j], depth)) + { + j++; + } + // Exit if v is smaller than both sons + if (_IsSmaller(tree, v, heap[j], depth)) + break; + + // Exchange v with the smallest son + heap[k] = heap[j]; k = j; + // And continue down the tree, setting j to the left son of k + j <<= 1; + } + heap[k] = v; + } + + internal static bool _IsSmaller(short[] tree, int n, int m, sbyte[] depth) + { + short tn2 = tree[n * 2]; + short tm2 = tree[m * 2]; + return (tn2 < tm2 || (tn2 == tm2 && depth[n] <= depth[m])); + } + + + // Scan a literal or distance tree to determine the frequencies of the codes + // in the bit length tree. + internal void scan_tree(short[] tree, int max_code) + { + int n; // iterates over all tree elements + int prevlen = -1; // last emitted length + int curlen; // length of current code + int nextlen = (int)tree[0 * 2 + 1]; // length of next code + int count = 0; // repeat count of the current code + int max_count = 7; // max repeat count + int min_count = 4; // min repeat count + + if (nextlen == 0) + { + max_count = 138; min_count = 3; + } + tree[(max_code + 1) * 2 + 1] = (short)0x7fff; // guard //?? + + for (n = 0; n <= max_code; n++) + { + curlen = nextlen; nextlen = (int)tree[(n + 1) * 2 + 1]; + if (++count < max_count && curlen == nextlen) + { + continue; + } + else if (count < min_count) + { + bl_tree[curlen * 2] = (short)(bl_tree[curlen * 2] + count); + } + else if (curlen != 0) + { + if (curlen != prevlen) + bl_tree[curlen * 2]++; + bl_tree[InternalConstants.REP_3_6 * 2]++; + } + else if (count <= 10) + { + bl_tree[InternalConstants.REPZ_3_10 * 2]++; + } + else + { + bl_tree[InternalConstants.REPZ_11_138 * 2]++; + } + count = 0; prevlen = curlen; + if (nextlen == 0) + { + max_count = 138; min_count = 3; + } + else if (curlen == nextlen) + { + max_count = 6; min_count = 3; + } + else + { + max_count = 7; min_count = 4; + } + } + } + + // Construct the Huffman tree for the bit lengths and return the index in + // bl_order of the last bit length code to send. + internal int build_bl_tree() + { + int max_blindex; // index of last bit length code of non zero freq + + // Determine the bit length frequencies for literal and distance trees + scan_tree(dyn_ltree, treeLiterals.max_code); + scan_tree(dyn_dtree, treeDistances.max_code); + + // Build the bit length tree: + treeBitLengths.build_tree(this); + // opt_len now includes the length of the tree representations, except + // the lengths of the bit lengths codes and the 5+5+4 bits for the counts. + + // Determine the number of bit length codes to send. The pkzip format + // requires that at least 4 bit length codes be sent. (appnote.txt says + // 3 but the actual value used is 4.) + for (max_blindex = InternalConstants.BL_CODES - 1; max_blindex >= 3; max_blindex--) + { + if (bl_tree[Tree.bl_order[max_blindex] * 2 + 1] != 0) + break; + } + // Update opt_len to include the bit length tree and counts + opt_len += 3 * (max_blindex + 1) + 5 + 5 + 4; + + return max_blindex; + } + + + // Send the header for a block using dynamic Huffman trees: the counts, the + // lengths of the bit length codes, the literal tree and the distance tree. + // IN assertion: lcodes >= 257, dcodes >= 1, blcodes >= 4. + internal void send_all_trees(int lcodes, int dcodes, int blcodes) + { + int rank; // index in bl_order + + send_bits(lcodes - 257, 5); // not +255 as stated in appnote.txt + send_bits(dcodes - 1, 5); + send_bits(blcodes - 4, 4); // not -3 as stated in appnote.txt + for (rank = 0; rank < blcodes; rank++) + { + send_bits(bl_tree[Tree.bl_order[rank] * 2 + 1], 3); + } + send_tree(dyn_ltree, lcodes - 1); // literal tree + send_tree(dyn_dtree, dcodes - 1); // distance tree + } + + // Send a literal or distance tree in compressed form, using the codes in + // bl_tree. + internal void send_tree(short[] tree, int max_code) + { + int n; // iterates over all tree elements + int prevlen = -1; // last emitted length + int curlen; // length of current code + int nextlen = tree[0 * 2 + 1]; // length of next code + int count = 0; // repeat count of the current code + int max_count = 7; // max repeat count + int min_count = 4; // min repeat count + + if (nextlen == 0) + { + max_count = 138; min_count = 3; + } + + for (n = 0; n <= max_code; n++) + { + curlen = nextlen; nextlen = tree[(n + 1) * 2 + 1]; + if (++count < max_count && curlen == nextlen) + { + continue; + } + else if (count < min_count) + { + do + { + send_code(curlen, bl_tree); + } + while (--count != 0); + } + else if (curlen != 0) + { + if (curlen != prevlen) + { + send_code(curlen, bl_tree); count--; + } + send_code(InternalConstants.REP_3_6, bl_tree); + send_bits(count - 3, 2); + } + else if (count <= 10) + { + send_code(InternalConstants.REPZ_3_10, bl_tree); + send_bits(count - 3, 3); + } + else + { + send_code(InternalConstants.REPZ_11_138, bl_tree); + send_bits(count - 11, 7); + } + count = 0; prevlen = curlen; + if (nextlen == 0) + { + max_count = 138; min_count = 3; + } + else if (curlen == nextlen) + { + max_count = 6; min_count = 3; + } + else + { + max_count = 7; min_count = 4; + } + } + } + + // Output a block of bytes on the stream. + // IN assertion: there is enough room in pending_buf. + private void put_bytes(byte[] p, int start, int len) + { + Array.Copy(p, start, pending, pendingCount, len); + pendingCount += len; + } + +#if NOTNEEDED + private void put_byte(byte c) + { + pending[pendingCount++] = c; + } + internal void put_short(int b) + { + unchecked + { + pending[pendingCount++] = (byte)b; + pending[pendingCount++] = (byte)(b >> 8); + } + } + internal void putShortMSB(int b) + { + unchecked + { + pending[pendingCount++] = (byte)(b >> 8); + pending[pendingCount++] = (byte)b; + } + } +#endif + + internal void send_code(int c, short[] tree) + { + int c2 = c * 2; + send_bits((tree[c2] & 0xffff), (tree[c2 + 1] & 0xffff)); + } + + internal void send_bits(int value, int length) + { + int len = length; + unchecked + { + if (bi_valid > (int)Buf_size - len) + { + //int val = value; + // bi_buf |= (val << bi_valid); + + bi_buf |= (short)((value << bi_valid) & 0xffff); + //put_short(bi_buf); + pending[pendingCount++] = (byte)bi_buf; + pending[pendingCount++] = (byte)(bi_buf >> 8); + + + bi_buf = (short)((uint)value >> (Buf_size - bi_valid)); + bi_valid += len - Buf_size; + } + else + { + // bi_buf |= (value) << bi_valid; + bi_buf |= (short)((value << bi_valid) & 0xffff); + bi_valid += len; + } + } + } + + // Send one empty static block to give enough lookahead for inflate. + // This takes 10 bits, of which 7 may remain in the bit buffer. + // The current inflate code requires 9 bits of lookahead. If the + // last two codes for the previous block (real code plus EOB) were coded + // on 5 bits or less, inflate may have only 5+3 bits of lookahead to decode + // the last real code. In this case we send two empty static blocks instead + // of one. (There are no problems if the previous block is stored or fixed.) + // To simplify the code, we assume the worst case of last real code encoded + // on one bit only. + internal void _tr_align() + { + send_bits(STATIC_TREES << 1, 3); + send_code(END_BLOCK, StaticTree.lengthAndLiteralsTreeCodes); + + bi_flush(); + + // Of the 10 bits for the empty block, we have already sent + // (10 - bi_valid) bits. The lookahead for the last real code (before + // the EOB of the previous block) was thus at least one plus the length + // of the EOB plus what we have just sent of the empty static block. + if (1 + last_eob_len + 10 - bi_valid < 9) + { + send_bits(STATIC_TREES << 1, 3); + send_code(END_BLOCK, StaticTree.lengthAndLiteralsTreeCodes); + bi_flush(); + } + last_eob_len = 7; + } + + + // Save the match info and tally the frequency counts. Return true if + // the current block must be flushed. + internal bool _tr_tally(int dist, int lc) + { + pending[_distanceOffset + last_lit * 2] = unchecked((byte) ( (uint)dist >> 8 ) ); + pending[_distanceOffset + last_lit * 2 + 1] = unchecked((byte)dist); + pending[_lengthOffset + last_lit] = unchecked((byte)lc); + last_lit++; + + if (dist == 0) + { + // lc is the unmatched char + dyn_ltree[lc * 2]++; + } + else + { + matches++; + // Here, lc is the match length - MIN_MATCH + dist--; // dist = match distance - 1 + dyn_ltree[(Tree.LengthCode[lc] + InternalConstants.LITERALS + 1) * 2]++; + dyn_dtree[Tree.DistanceCode(dist) * 2]++; + } + + if ((last_lit & 0x1fff) == 0 && (int)compressionLevel > 2) + { + // Compute an upper bound for the compressed length + int out_length = last_lit << 3; + int in_length = strstart - block_start; + int dcode; + for (dcode = 0; dcode < InternalConstants.D_CODES; dcode++) + { + out_length = (int)(out_length + (int)dyn_dtree[dcode * 2] * (5L + Tree.ExtraDistanceBits[dcode])); + } + out_length >>= 3; + if ((matches < (last_lit / 2)) && out_length < in_length / 2) + return true; + } + + return (last_lit == lit_bufsize - 1) || (last_lit == lit_bufsize); + // dinoch - wraparound? + // We avoid equality with lit_bufsize because of wraparound at 64K + // on 16 bit machines and because stored blocks are restricted to + // 64K-1 bytes. + } + + + + // Send the block data compressed using the given Huffman trees + internal void send_compressed_block(short[] ltree, short[] dtree) + { + int distance; // distance of matched string + int lc; // match length or unmatched char (if dist == 0) + int lx = 0; // running index in l_buf + int code; // the code to send + int extra; // number of extra bits to send + + if (last_lit != 0) + { + do + { + int ix = _distanceOffset + lx * 2; + distance = ((pending[ix] << 8) & 0xff00) | + (pending[ix + 1] & 0xff); + lc = (pending[_lengthOffset + lx]) & 0xff; + lx++; + + if (distance == 0) + { + send_code(lc, ltree); // send a literal byte + } + else + { + // literal or match pair + // Here, lc is the match length - MIN_MATCH + code = Tree.LengthCode[lc]; + + // send the length code + send_code(code + InternalConstants.LITERALS + 1, ltree); + extra = Tree.ExtraLengthBits[code]; + if (extra != 0) + { + // send the extra length bits + lc -= Tree.LengthBase[code]; + send_bits(lc, extra); + } + distance--; // dist is now the match distance - 1 + code = Tree.DistanceCode(distance); + + // send the distance code + send_code(code, dtree); + + extra = Tree.ExtraDistanceBits[code]; + if (extra != 0) + { + // send the extra distance bits + distance -= Tree.DistanceBase[code]; + send_bits(distance, extra); + } + } + + // Check that the overlay between pending and d_buf+l_buf is ok: + } + while (lx < last_lit); + } + + send_code(END_BLOCK, ltree); + last_eob_len = ltree[END_BLOCK * 2 + 1]; + } + + + + // Set the data type to ASCII or BINARY, using a crude approximation: + // binary if more than 20% of the bytes are <= 6 or >= 128, ascii otherwise. + // IN assertion: the fields freq of dyn_ltree are set and the total of all + // frequencies does not exceed 64K (to fit in an int on 16 bit machines). + internal void set_data_type() + { + int n = 0; + int ascii_freq = 0; + int bin_freq = 0; + while (n < 7) + { + bin_freq += dyn_ltree[n * 2]; n++; + } + while (n < 128) + { + ascii_freq += dyn_ltree[n * 2]; n++; + } + while (n < InternalConstants.LITERALS) + { + bin_freq += dyn_ltree[n * 2]; n++; + } + data_type = (sbyte)(bin_freq > (ascii_freq >> 2) ? Z_BINARY : Z_ASCII); + } + + + + // Flush the bit buffer, keeping at most 7 bits in it. + internal void bi_flush() + { + if (bi_valid == 16) + { + pending[pendingCount++] = (byte)bi_buf; + pending[pendingCount++] = (byte)(bi_buf >> 8); + bi_buf = 0; + bi_valid = 0; + } + else if (bi_valid >= 8) + { + //put_byte((byte)bi_buf); + pending[pendingCount++] = (byte)bi_buf; + bi_buf >>= 8; + bi_valid -= 8; + } + } + + // Flush the bit buffer and align the output on a byte boundary + internal void bi_windup() + { + if (bi_valid > 8) + { + pending[pendingCount++] = (byte)bi_buf; + pending[pendingCount++] = (byte)(bi_buf >> 8); + } + else if (bi_valid > 0) + { + //put_byte((byte)bi_buf); + pending[pendingCount++] = (byte)bi_buf; + } + bi_buf = 0; + bi_valid = 0; + } + + // Copy a stored block, storing first the length and its + // one's complement if requested. + internal void copy_block(int buf, int len, bool header) + { + bi_windup(); // align on byte boundary + last_eob_len = 8; // enough lookahead for inflate + + if (header) + unchecked + { + //put_short((short)len); + pending[pendingCount++] = (byte)len; + pending[pendingCount++] = (byte)(len >> 8); + //put_short((short)~len); + pending[pendingCount++] = (byte)~len; + pending[pendingCount++] = (byte)(~len >> 8); + } + + put_bytes(window, buf, len); + } + + internal void flush_block_only(bool eof) + { + _tr_flush_block(block_start >= 0 ? block_start : -1, strstart - block_start, eof); + block_start = strstart; + _codec.flush_pending(); + } + + // Copy without compression as much as possible from the input stream, return + // the current block state. + // This function does not insert new strings in the dictionary since + // uncompressible data is probably not useful. This function is used + // only for the level=0 compression option. + // NOTE: this function should be optimized to avoid extra copying from + // window to pending_buf. + internal BlockState DeflateNone(FlushType flush) + { + // Stored blocks are limited to 0xffff bytes, pending is limited + // to pending_buf_size, and each stored block has a 5 byte header: + + int max_block_size = 0xffff; + int max_start; + + if (max_block_size > pending.Length - 5) + { + max_block_size = pending.Length - 5; + } + + // Copy as much as possible from input to output: + while (true) + { + // Fill the window as much as possible: + if (lookahead <= 1) + { + _fillWindow(); + if (lookahead == 0 && flush == FlushType.None) + return BlockState.NeedMore; + if (lookahead == 0) + break; // flush the current block + } + + strstart += lookahead; + lookahead = 0; + + // Emit a stored block if pending will be full: + max_start = block_start + max_block_size; + if (strstart == 0 || strstart >= max_start) + { + // strstart == 0 is possible when wraparound on 16-bit machine + lookahead = (int)(strstart - max_start); + strstart = (int)max_start; + + flush_block_only(false); + if (_codec.AvailableBytesOut == 0) + return BlockState.NeedMore; + } + + // Flush if we may have to slide, otherwise block_start may become + // negative and the data will be gone: + if (strstart - block_start >= w_size - MIN_LOOKAHEAD) + { + flush_block_only(false); + if (_codec.AvailableBytesOut == 0) + return BlockState.NeedMore; + } + } + + flush_block_only(flush == FlushType.Finish); + if (_codec.AvailableBytesOut == 0) + return (flush == FlushType.Finish) ? BlockState.FinishStarted : BlockState.NeedMore; + + return flush == FlushType.Finish ? BlockState.FinishDone : BlockState.BlockDone; + } + + + // Send a stored block + internal void _tr_stored_block(int buf, int stored_len, bool eof) + { + send_bits((STORED_BLOCK << 1) + (eof ? 1 : 0), 3); // send block type + copy_block(buf, stored_len, true); // with header + } + + // Determine the best encoding for the current block: dynamic trees, static + // trees or store, and output the encoded block to the zip file. + internal void _tr_flush_block(int buf, int stored_len, bool eof) + { + int opt_lenb, static_lenb; // opt_len and static_len in bytes + int max_blindex = 0; // index of last bit length code of non zero freq + + // Build the Huffman trees unless a stored block is forced + if (compressionLevel > 0) + { + // Check if the file is ascii or binary + if (data_type == Z_UNKNOWN) + set_data_type(); + + // Construct the literal and distance trees + treeLiterals.build_tree(this); + + treeDistances.build_tree(this); + + // At this point, opt_len and static_len are the total bit lengths of + // the compressed block data, excluding the tree representations. + + // Build the bit length tree for the above two trees, and get the index + // in bl_order of the last bit length code to send. + max_blindex = build_bl_tree(); + + // Determine the best encoding. Compute first the block length in bytes + opt_lenb = (opt_len + 3 + 7) >> 3; + static_lenb = (static_len + 3 + 7) >> 3; + + if (static_lenb <= opt_lenb) + opt_lenb = static_lenb; + } + else + { + opt_lenb = static_lenb = stored_len + 5; // force a stored block + } + + if (stored_len + 4 <= opt_lenb && buf != -1) + { + // 4: two words for the lengths + // The test buf != NULL is only necessary if LIT_BUFSIZE > WSIZE. + // Otherwise we can't have processed more than WSIZE input bytes since + // the last block flush, because compression would have been + // successful. If LIT_BUFSIZE <= WSIZE, it is never too late to + // transform a block into a stored block. + _tr_stored_block(buf, stored_len, eof); + } + else if (static_lenb == opt_lenb) + { + send_bits((STATIC_TREES << 1) + (eof ? 1 : 0), 3); + send_compressed_block(StaticTree.lengthAndLiteralsTreeCodes, StaticTree.distTreeCodes); + } + else + { + send_bits((DYN_TREES << 1) + (eof ? 1 : 0), 3); + send_all_trees(treeLiterals.max_code + 1, treeDistances.max_code + 1, max_blindex + 1); + send_compressed_block(dyn_ltree, dyn_dtree); + } + + // The above check is made mod 2^32, for files larger than 512 MB + // and uLong implemented on 32 bits. + + _InitializeBlocks(); + + if (eof) + { + bi_windup(); + } + } + + // Fill the window when the lookahead becomes insufficient. + // Updates strstart and lookahead. + // + // IN assertion: lookahead < MIN_LOOKAHEAD + // OUT assertions: strstart <= window_size-MIN_LOOKAHEAD + // At least one byte has been read, or avail_in == 0; reads are + // performed for at least two bytes (required for the zip translate_eol + // option -- not supported here). + private void _fillWindow() + { + int n, m; + int p; + int more; // Amount of free space at the end of the window. + + do + { + more = (window_size - lookahead - strstart); + + // Deal with !@#$% 64K limit: + if (more == 0 && strstart == 0 && lookahead == 0) + { + more = w_size; + } + else if (more == -1) + { + // Very unlikely, but possible on 16 bit machine if strstart == 0 + // and lookahead == 1 (input done one byte at time) + more--; + + // If the window is almost full and there is insufficient lookahead, + // move the upper half to the lower one to make room in the upper half. + } + else if (strstart >= w_size + w_size - MIN_LOOKAHEAD) + { + Array.Copy(window, w_size, window, 0, w_size); + match_start -= w_size; + strstart -= w_size; // we now have strstart >= MAX_DIST + block_start -= w_size; + + // Slide the hash table (could be avoided with 32 bit values + // at the expense of memory usage). We slide even when level == 0 + // to keep the hash table consistent if we switch back to level > 0 + // later. (Using level 0 permanently is not an optimal usage of + // zlib, so we don't care about this pathological case.) + + n = hash_size; + p = n; + do + { + m = (head[--p] & 0xffff); + head[p] = (short)((m >= w_size) ? (m - w_size) : 0); + } + while (--n != 0); + + n = w_size; + p = n; + do + { + m = (prev[--p] & 0xffff); + prev[p] = (short)((m >= w_size) ? (m - w_size) : 0); + // If n is not on any hash chain, prev[n] is garbage but + // its value will never be used. + } + while (--n != 0); + more += w_size; + } + + if (_codec.AvailableBytesIn == 0) + return; + + // If there was no sliding: + // strstart <= WSIZE+MAX_DIST-1 && lookahead <= MIN_LOOKAHEAD - 1 && + // more == window_size - lookahead - strstart + // => more >= window_size - (MIN_LOOKAHEAD-1 + WSIZE + MAX_DIST-1) + // => more >= window_size - 2*WSIZE + 2 + // In the BIG_MEM or MMAP case (not yet supported), + // window_size == input_size + MIN_LOOKAHEAD && + // strstart + s->lookahead <= input_size => more >= MIN_LOOKAHEAD. + // Otherwise, window_size == 2*WSIZE so more >= 2. + // If there was sliding, more >= WSIZE. So in all cases, more >= 2. + + n = _codec.read_buf(window, strstart + lookahead, more); + lookahead += n; + + // Initialize the hash value now that we have some input: + if (lookahead >= MIN_MATCH) + { + ins_h = window[strstart] & 0xff; + ins_h = (((ins_h) << hash_shift) ^ (window[strstart + 1] & 0xff)) & hash_mask; + } + // If the whole input has less than MIN_MATCH bytes, ins_h is garbage, + // but this is not important since only literal bytes will be emitted. + } + while (lookahead < MIN_LOOKAHEAD && _codec.AvailableBytesIn != 0); + } + + // Compress as much as possible from the input stream, return the current + // block state. + // This function does not perform lazy evaluation of matches and inserts + // new strings in the dictionary only for unmatched strings or for short + // matches. It is used only for the fast compression options. + internal BlockState DeflateFast(FlushType flush) + { + // short hash_head = 0; // head of the hash chain + int hash_head = 0; // head of the hash chain + bool bflush; // set if current block must be flushed + + while (true) + { + // Make sure that we always have enough lookahead, except + // at the end of the input file. We need MAX_MATCH bytes + // for the next match, plus MIN_MATCH bytes to insert the + // string following the next match. + if (lookahead < MIN_LOOKAHEAD) + { + _fillWindow(); + if (lookahead < MIN_LOOKAHEAD && flush == FlushType.None) + { + return BlockState.NeedMore; + } + if (lookahead == 0) + break; // flush the current block + } + + // Insert the string window[strstart .. strstart+2] in the + // dictionary, and set hash_head to the head of the hash chain: + if (lookahead >= MIN_MATCH) + { + ins_h = (((ins_h) << hash_shift) ^ (window[(strstart) + (MIN_MATCH - 1)] & 0xff)) & hash_mask; + + // prev[strstart&w_mask]=hash_head=head[ins_h]; + hash_head = (head[ins_h] & 0xffff); + prev[strstart & w_mask] = head[ins_h]; + head[ins_h] = unchecked((short)strstart); + } + + // Find the longest match, discarding those <= prev_length. + // At this point we have always match_length < MIN_MATCH + + if (hash_head != 0L && ((strstart - hash_head) & 0xffff) <= w_size - MIN_LOOKAHEAD) + { + // To simplify the code, we prevent matches with the string + // of window index 0 (in particular we have to avoid a match + // of the string with itself at the start of the input file). + if (compressionStrategy != CompressionStrategy.HuffmanOnly) + { + match_length = longest_match(hash_head); + } + // longest_match() sets match_start + } + if (match_length >= MIN_MATCH) + { + // check_match(strstart, match_start, match_length); + + bflush = _tr_tally(strstart - match_start, match_length - MIN_MATCH); + + lookahead -= match_length; + + // Insert new strings in the hash table only if the match length + // is not too large. This saves time but degrades compression. + if (match_length <= config.MaxLazy && lookahead >= MIN_MATCH) + { + match_length--; // string at strstart already in hash table + do + { + strstart++; + + ins_h = ((ins_h << hash_shift) ^ (window[(strstart) + (MIN_MATCH - 1)] & 0xff)) & hash_mask; + // prev[strstart&w_mask]=hash_head=head[ins_h]; + hash_head = (head[ins_h] & 0xffff); + prev[strstart & w_mask] = head[ins_h]; + head[ins_h] = unchecked((short)strstart); + + // strstart never exceeds WSIZE-MAX_MATCH, so there are + // always MIN_MATCH bytes ahead. + } + while (--match_length != 0); + strstart++; + } + else + { + strstart += match_length; + match_length = 0; + ins_h = window[strstart] & 0xff; + + ins_h = (((ins_h) << hash_shift) ^ (window[strstart + 1] & 0xff)) & hash_mask; + // If lookahead < MIN_MATCH, ins_h is garbage, but it does not + // matter since it will be recomputed at next deflate call. + } + } + else + { + // No match, output a literal byte + + bflush = _tr_tally(0, window[strstart] & 0xff); + lookahead--; + strstart++; + } + if (bflush) + { + flush_block_only(false); + if (_codec.AvailableBytesOut == 0) + return BlockState.NeedMore; + } + } + + flush_block_only(flush == FlushType.Finish); + if (_codec.AvailableBytesOut == 0) + { + if (flush == FlushType.Finish) + return BlockState.FinishStarted; + else + return BlockState.NeedMore; + } + return flush == FlushType.Finish ? BlockState.FinishDone : BlockState.BlockDone; + } + + // Same as above, but achieves better compression. We use a lazy + // evaluation for matches: a match is finally adopted only if there is + // no better match at the next window position. + internal BlockState DeflateSlow(FlushType flush) + { + // short hash_head = 0; // head of hash chain + int hash_head = 0; // head of hash chain + bool bflush; // set if current block must be flushed + + // Process the input block. + while (true) + { + // Make sure that we always have enough lookahead, except + // at the end of the input file. We need MAX_MATCH bytes + // for the next match, plus MIN_MATCH bytes to insert the + // string following the next match. + + if (lookahead < MIN_LOOKAHEAD) + { + _fillWindow(); + if (lookahead < MIN_LOOKAHEAD && flush == FlushType.None) + return BlockState.NeedMore; + + if (lookahead == 0) + break; // flush the current block + } + + // Insert the string window[strstart .. strstart+2] in the + // dictionary, and set hash_head to the head of the hash chain: + + if (lookahead >= MIN_MATCH) + { + ins_h = (((ins_h) << hash_shift) ^ (window[(strstart) + (MIN_MATCH - 1)] & 0xff)) & hash_mask; + // prev[strstart&w_mask]=hash_head=head[ins_h]; + hash_head = (head[ins_h] & 0xffff); + prev[strstart & w_mask] = head[ins_h]; + head[ins_h] = unchecked((short)strstart); + } + + // Find the longest match, discarding those <= prev_length. + prev_length = match_length; + prev_match = match_start; + match_length = MIN_MATCH - 1; + + if (hash_head != 0 && prev_length < config.MaxLazy && + ((strstart - hash_head) & 0xffff) <= w_size - MIN_LOOKAHEAD) + { + // To simplify the code, we prevent matches with the string + // of window index 0 (in particular we have to avoid a match + // of the string with itself at the start of the input file). + + if (compressionStrategy != CompressionStrategy.HuffmanOnly) + { + match_length = longest_match(hash_head); + } + // longest_match() sets match_start + + if (match_length <= 5 && (compressionStrategy == CompressionStrategy.Filtered || + (match_length == MIN_MATCH && strstart - match_start > 4096))) + { + + // If prev_match is also MIN_MATCH, match_start is garbage + // but we will ignore the current match anyway. + match_length = MIN_MATCH - 1; + } + } + + // If there was a match at the previous step and the current + // match is not better, output the previous match: + if (prev_length >= MIN_MATCH && match_length <= prev_length) + { + int max_insert = strstart + lookahead - MIN_MATCH; + // Do not insert strings in hash table beyond this. + + // check_match(strstart-1, prev_match, prev_length); + + bflush = _tr_tally(strstart - 1 - prev_match, prev_length - MIN_MATCH); + + // Insert in hash table all strings up to the end of the match. + // strstart-1 and strstart are already inserted. If there is not + // enough lookahead, the last two strings are not inserted in + // the hash table. + lookahead -= (prev_length - 1); + prev_length -= 2; + do + { + if (++strstart <= max_insert) + { + ins_h = (((ins_h) << hash_shift) ^ (window[(strstart) + (MIN_MATCH - 1)] & 0xff)) & hash_mask; + //prev[strstart&w_mask]=hash_head=head[ins_h]; + hash_head = (head[ins_h] & 0xffff); + prev[strstart & w_mask] = head[ins_h]; + head[ins_h] = unchecked((short)strstart); + } + } + while (--prev_length != 0); + match_available = 0; + match_length = MIN_MATCH - 1; + strstart++; + + if (bflush) + { + flush_block_only(false); + if (_codec.AvailableBytesOut == 0) + return BlockState.NeedMore; + } + } + else if (match_available != 0) + { + + // If there was no match at the previous position, output a + // single literal. If there was a match but the current match + // is longer, truncate the previous match to a single literal. + + bflush = _tr_tally(0, window[strstart - 1] & 0xff); + + if (bflush) + { + flush_block_only(false); + } + strstart++; + lookahead--; + if (_codec.AvailableBytesOut == 0) + return BlockState.NeedMore; + } + else + { + // There is no previous match to compare with, wait for + // the next step to decide. + + match_available = 1; + strstart++; + lookahead--; + } + } + + if (match_available != 0) + { + bflush = _tr_tally(0, window[strstart - 1] & 0xff); + match_available = 0; + } + flush_block_only(flush == FlushType.Finish); + + if (_codec.AvailableBytesOut == 0) + { + if (flush == FlushType.Finish) + return BlockState.FinishStarted; + else + return BlockState.NeedMore; + } + + return flush == FlushType.Finish ? BlockState.FinishDone : BlockState.BlockDone; + } + + + internal int longest_match(int cur_match) + { + int chain_length = config.MaxChainLength; // max hash chain length + int scan = strstart; // current string + int match; // matched string + int len; // length of current match + int best_len = prev_length; // best match length so far + int limit = strstart > (w_size - MIN_LOOKAHEAD) ? strstart - (w_size - MIN_LOOKAHEAD) : 0; + + int niceLength = config.NiceLength; + + // Stop when cur_match becomes <= limit. To simplify the code, + // we prevent matches with the string of window index 0. + + int wmask = w_mask; + + int strend = strstart + MAX_MATCH; + byte scan_end1 = window[scan + best_len - 1]; + byte scan_end = window[scan + best_len]; + + // The code is optimized for HASH_BITS >= 8 and MAX_MATCH-2 multiple of 16. + // It is easy to get rid of this optimization if necessary. + + // Do not waste too much time if we already have a good match: + if (prev_length >= config.GoodLength) + { + chain_length >>= 2; + } + + // Do not look for matches beyond the end of the input. This is necessary + // to make deflate deterministic. + if (niceLength > lookahead) + niceLength = lookahead; + + do + { + match = cur_match; + + // Skip to next match if the match length cannot increase + // or if the match length is less than 2: + if (window[match + best_len] != scan_end || + window[match + best_len - 1] != scan_end1 || + window[match] != window[scan] || + window[++match] != window[scan + 1]) + continue; + + // The check at best_len-1 can be removed because it will be made + // again later. (This heuristic is not always a win.) + // It is not necessary to compare scan[2] and match[2] since they + // are always equal when the other bytes match, given that + // the hash keys are equal and that HASH_BITS >= 8. + scan += 2; match++; + + // We check for insufficient lookahead only every 8th comparison; + // the 256th check will be made at strstart+258. + do + { + } + while (window[++scan] == window[++match] && + window[++scan] == window[++match] && + window[++scan] == window[++match] && + window[++scan] == window[++match] && + window[++scan] == window[++match] && + window[++scan] == window[++match] && + window[++scan] == window[++match] && + window[++scan] == window[++match] && scan < strend); + + len = MAX_MATCH - (int)(strend - scan); + scan = strend - MAX_MATCH; + + if (len > best_len) + { + match_start = cur_match; + best_len = len; + if (len >= niceLength) + break; + scan_end1 = window[scan + best_len - 1]; + scan_end = window[scan + best_len]; + } + } + while ((cur_match = (prev[cur_match & wmask] & 0xffff)) > limit && --chain_length != 0); + + if (best_len <= lookahead) + return best_len; + return lookahead; + } + + + private bool Rfc1950BytesEmitted = false; + private bool _WantRfc1950HeaderBytes = true; + internal bool WantRfc1950HeaderBytes + { + get { return _WantRfc1950HeaderBytes; } + set { _WantRfc1950HeaderBytes = value; } + } + + + internal int Initialize(ZlibCodec codec, CompressionLevel level) + { + return Initialize(codec, level, ZlibConstants.WindowBitsMax); + } + + internal int Initialize(ZlibCodec codec, CompressionLevel level, int bits) + { + return Initialize(codec, level, bits, MEM_LEVEL_DEFAULT, CompressionStrategy.Default); + } + + internal int Initialize(ZlibCodec codec, CompressionLevel level, int bits, CompressionStrategy compressionStrategy) + { + return Initialize(codec, level, bits, MEM_LEVEL_DEFAULT, compressionStrategy); + } + + internal int Initialize(ZlibCodec codec, CompressionLevel level, int windowBits, int memLevel, CompressionStrategy strategy) + { + _codec = codec; + _codec.Message = null; + + // validation + if (windowBits < 9 || windowBits > 15) + throw new ZlibException("windowBits must be in the range 9..15."); + + if (memLevel < 1 || memLevel > MEM_LEVEL_MAX) + throw new ZlibException(String.Format("memLevel must be in the range 1.. {0}", MEM_LEVEL_MAX)); + + _codec.dstate = this; + + w_bits = windowBits; + w_size = 1 << w_bits; + w_mask = w_size - 1; + + hash_bits = memLevel + 7; + hash_size = 1 << hash_bits; + hash_mask = hash_size - 1; + hash_shift = ((hash_bits + MIN_MATCH - 1) / MIN_MATCH); + + window = new byte[w_size * 2]; + prev = new short[w_size]; + head = new short[hash_size]; + + // for memLevel==8, this will be 16384, 16k + lit_bufsize = 1 << (memLevel + 6); + + // Use a single array as the buffer for data pending compression, + // the output distance codes, and the output length codes (aka tree). + // orig comment: This works just fine since the average + // output size for (length,distance) codes is <= 24 bits. + pending = new byte[lit_bufsize * 4]; + _distanceOffset = lit_bufsize; + _lengthOffset = (1 + 2) * lit_bufsize; + + // So, for memLevel 8, the length of the pending buffer is 65536. 64k. + // The first 16k are pending bytes. + // The middle slice, of 32k, is used for distance codes. + // The final 16k are length codes. + + this.compressionLevel = level; + this.compressionStrategy = strategy; + + Reset(); + return ZlibConstants.Z_OK; + } + + + internal void Reset() + { + _codec.TotalBytesIn = _codec.TotalBytesOut = 0; + _codec.Message = null; + //strm.data_type = Z_UNKNOWN; + + pendingCount = 0; + nextPending = 0; + + Rfc1950BytesEmitted = false; + + status = (WantRfc1950HeaderBytes) ? INIT_STATE : BUSY_STATE; + _codec._Adler32 = Adler.Adler32(0, null, 0, 0); + + last_flush = (int)FlushType.None; + + _InitializeTreeData(); + _InitializeLazyMatch(); + } + + + internal int End() + { + if (status != INIT_STATE && status != BUSY_STATE && status != FINISH_STATE) + { + return ZlibConstants.Z_STREAM_ERROR; + } + // Deallocate in reverse order of allocations: + pending = null; + head = null; + prev = null; + window = null; + // free + // dstate=null; + return status == BUSY_STATE ? ZlibConstants.Z_DATA_ERROR : ZlibConstants.Z_OK; + } + + + private void SetDeflater() + { + switch (config.Flavor) + { + case DeflateFlavor.Store: + DeflateFunction = DeflateNone; + break; + case DeflateFlavor.Fast: + DeflateFunction = DeflateFast; + break; + case DeflateFlavor.Slow: + DeflateFunction = DeflateSlow; + break; + } + } + + + internal int SetParams(CompressionLevel level, CompressionStrategy strategy) + { + int result = ZlibConstants.Z_OK; + + if (compressionLevel != level) + { + Config newConfig = Config.Lookup(level); + + // change in the deflate flavor (Fast vs slow vs none)? + if (newConfig.Flavor != config.Flavor && _codec.TotalBytesIn != 0) + { + // Flush the last buffer: + result = _codec.Deflate(FlushType.Partial); + } + + compressionLevel = level; + config = newConfig; + SetDeflater(); + } + + // no need to flush with change in strategy? Really? + compressionStrategy = strategy; + + return result; + } + + + internal int SetDictionary(byte[] dictionary) + { + int length = dictionary.Length; + int index = 0; + + if (dictionary == null || status != INIT_STATE) + throw new ZlibException("Stream error."); + + _codec._Adler32 = Adler.Adler32(_codec._Adler32, dictionary, 0, dictionary.Length); + + if (length < MIN_MATCH) + return ZlibConstants.Z_OK; + if (length > w_size - MIN_LOOKAHEAD) + { + length = w_size - MIN_LOOKAHEAD; + index = dictionary.Length - length; // use the tail of the dictionary + } + Array.Copy(dictionary, index, window, 0, length); + strstart = length; + block_start = length; + + // Insert all strings in the hash table (except for the last two bytes). + // s->lookahead stays null, so s->ins_h will be recomputed at the next + // call of fill_window. + + ins_h = window[0] & 0xff; + ins_h = (((ins_h) << hash_shift) ^ (window[1] & 0xff)) & hash_mask; + + for (int n = 0; n <= length - MIN_MATCH; n++) + { + ins_h = (((ins_h) << hash_shift) ^ (window[(n) + (MIN_MATCH - 1)] & 0xff)) & hash_mask; + prev[n & w_mask] = head[ins_h]; + head[ins_h] = (short)n; + } + return ZlibConstants.Z_OK; + } + + + + internal int Deflate(FlushType flush) + { + int old_flush; + + if (_codec.OutputBuffer == null || + (_codec.InputBuffer == null && _codec.AvailableBytesIn != 0) || + (status == FINISH_STATE && flush != FlushType.Finish)) + { + _codec.Message = _ErrorMessage[ZlibConstants.Z_NEED_DICT - (ZlibConstants.Z_STREAM_ERROR)]; + throw new ZlibException(String.Format("Something is fishy. [{0}]", _codec.Message)); + } + if (_codec.AvailableBytesOut == 0) + { + _codec.Message = _ErrorMessage[ZlibConstants.Z_NEED_DICT - (ZlibConstants.Z_BUF_ERROR)]; + throw new ZlibException("OutputBuffer is full (AvailableBytesOut == 0)"); + } + + old_flush = last_flush; + last_flush = (int)flush; + + // Write the zlib (rfc1950) header bytes + if (status == INIT_STATE) + { + int header = (Z_DEFLATED + ((w_bits - 8) << 4)) << 8; + int level_flags = (((int)compressionLevel - 1) & 0xff) >> 1; + + if (level_flags > 3) + level_flags = 3; + header |= (level_flags << 6); + if (strstart != 0) + header |= PRESET_DICT; + header += 31 - (header % 31); + + status = BUSY_STATE; + //putShortMSB(header); + unchecked + { + pending[pendingCount++] = (byte)(header >> 8); + pending[pendingCount++] = (byte)header; + } + // Save the adler32 of the preset dictionary: + if (strstart != 0) + { + pending[pendingCount++] = (byte)((_codec._Adler32 & 0xFF000000) >> 24); + pending[pendingCount++] = (byte)((_codec._Adler32 & 0x00FF0000) >> 16); + pending[pendingCount++] = (byte)((_codec._Adler32 & 0x0000FF00) >> 8); + pending[pendingCount++] = (byte)(_codec._Adler32 & 0x000000FF); + } + _codec._Adler32 = Adler.Adler32(0, null, 0, 0); + } + + // Flush as much pending output as possible + if (pendingCount != 0) + { + _codec.flush_pending(); + if (_codec.AvailableBytesOut == 0) + { + //System.out.println(" avail_out==0"); + // Since avail_out is 0, deflate will be called again with + // more output space, but possibly with both pending and + // avail_in equal to zero. There won't be anything to do, + // but this is not an error situation so make sure we + // return OK instead of BUF_ERROR at next call of deflate: + last_flush = -1; + return ZlibConstants.Z_OK; + } + + // Make sure there is something to do and avoid duplicate consecutive + // flushes. For repeated and useless calls with Z_FINISH, we keep + // returning Z_STREAM_END instead of Z_BUFF_ERROR. + } + else if (_codec.AvailableBytesIn == 0 && + (int)flush <= old_flush && + flush != FlushType.Finish) + { + // workitem 8557 + // + // Not sure why this needs to be an error. pendingCount == 0, which + // means there's nothing to deflate. And the caller has not asked + // for a FlushType.Finish, but... that seems very non-fatal. We + // can just say "OK" and do nothing. + + // _codec.Message = z_errmsg[ZlibConstants.Z_NEED_DICT - (ZlibConstants.Z_BUF_ERROR)]; + // throw new ZlibException("AvailableBytesIn == 0 && flush<=old_flush && flush != FlushType.Finish"); + + return ZlibConstants.Z_OK; + } + + // User must not provide more input after the first FINISH: + if (status == FINISH_STATE && _codec.AvailableBytesIn != 0) + { + _codec.Message = _ErrorMessage[ZlibConstants.Z_NEED_DICT - (ZlibConstants.Z_BUF_ERROR)]; + throw new ZlibException("status == FINISH_STATE && _codec.AvailableBytesIn != 0"); + } + + // Start a new block or continue the current one. + if (_codec.AvailableBytesIn != 0 || lookahead != 0 || (flush != FlushType.None && status != FINISH_STATE)) + { + BlockState bstate = DeflateFunction(flush); + + if (bstate == BlockState.FinishStarted || bstate == BlockState.FinishDone) + { + status = FINISH_STATE; + } + if (bstate == BlockState.NeedMore || bstate == BlockState.FinishStarted) + { + if (_codec.AvailableBytesOut == 0) + { + last_flush = -1; // avoid BUF_ERROR next call, see above + } + return ZlibConstants.Z_OK; + // If flush != Z_NO_FLUSH && avail_out == 0, the next call + // of deflate should use the same flush parameter to make sure + // that the flush is complete. So we don't have to output an + // empty block here, this will be done at next call. This also + // ensures that for a very small output buffer, we emit at most + // one empty block. + } + + if (bstate == BlockState.BlockDone) + { + if (flush == FlushType.Partial) + { + _tr_align(); + } + else + { + // FlushType.Full or FlushType.Sync + _tr_stored_block(0, 0, false); + // For a full flush, this empty block will be recognized + // as a special marker by inflate_sync(). + if (flush == FlushType.Full) + { + // clear hash (forget the history) + for (int i = 0; i < hash_size; i++) + head[i] = 0; + } + } + _codec.flush_pending(); + if (_codec.AvailableBytesOut == 0) + { + last_flush = -1; // avoid BUF_ERROR at next call, see above + return ZlibConstants.Z_OK; + } + } + } + + if (flush != FlushType.Finish) + return ZlibConstants.Z_OK; + + if (!WantRfc1950HeaderBytes || Rfc1950BytesEmitted) + return ZlibConstants.Z_STREAM_END; + + // Write the zlib trailer (adler32) + pending[pendingCount++] = (byte)((_codec._Adler32 & 0xFF000000) >> 24); + pending[pendingCount++] = (byte)((_codec._Adler32 & 0x00FF0000) >> 16); + pending[pendingCount++] = (byte)((_codec._Adler32 & 0x0000FF00) >> 8); + pending[pendingCount++] = (byte)(_codec._Adler32 & 0x000000FF); + //putShortMSB((int)(SharedUtils.URShift(_codec._Adler32, 16))); + //putShortMSB((int)(_codec._Adler32 & 0xffff)); + + _codec.flush_pending(); + + // If avail_out is zero, the application will call deflate again + // to flush the rest. + + Rfc1950BytesEmitted = true; // write the trailer only once! + + return pendingCount != 0 ? ZlibConstants.Z_OK : ZlibConstants.Z_STREAM_END; + } + + } +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/Zlib/DeflateStream.cs b/Resources/Libraries/DotNetZip/Source/Zlib/DeflateStream.cs new file mode 100644 index 00000000..45e972b2 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zlib/DeflateStream.cs @@ -0,0 +1,740 @@ +// DeflateStream.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009-2010 Dino Chiesa. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-31 14:48:11> +// +// ------------------------------------------------------------------ +// +// This module defines the DeflateStream class, which can be used as a replacement for +// the System.IO.Compression.DeflateStream class in the .NET BCL. +// +// ------------------------------------------------------------------ + + +using System; + +namespace Ionic.Zlib +{ + /// + /// A class for compressing and decompressing streams using the Deflate algorithm. + /// + /// + /// + /// + /// + /// The DeflateStream is a Decorator on a . It adds DEFLATE compression or decompression to any + /// stream. + /// + /// + /// + /// Using this stream, applications can compress or decompress data via stream + /// Read and Write operations. Either compresssion or decompression + /// can occur through either reading or writing. The compression format used is + /// DEFLATE, which is documented in IETF RFC 1951, "DEFLATE + /// Compressed Data Format Specification version 1.3.". + /// + /// + /// + /// This class is similar to , except that + /// ZlibStream adds the RFC + /// 1950 - ZLIB framing bytes to a compressed stream when compressing, or + /// expects the RFC1950 framing bytes when decompressing. The DeflateStream + /// does not. + /// + /// + /// + /// + /// + /// + public class DeflateStream : System.IO.Stream + { + internal ZlibBaseStream _baseStream; + internal System.IO.Stream _innerStream; + bool _disposed; + + /// + /// Create a DeflateStream using the specified CompressionMode. + /// + /// + /// + /// When mode is CompressionMode.Compress, the DeflateStream will use + /// the default compression level. The "captive" stream will be closed when + /// the DeflateStream is closed. + /// + /// + /// + /// This example uses a DeflateStream to compress data from a file, and writes + /// the compressed data to another file. + /// + /// using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress)) + /// { + /// using (var raw = System.IO.File.Create(fileToCompress + ".deflated")) + /// { + /// using (Stream compressor = new DeflateStream(raw, CompressionMode.Compress)) + /// { + /// byte[] buffer = new byte[WORKING_BUFFER_SIZE]; + /// int n; + /// while ((n= input.Read(buffer, 0, buffer.Length)) != 0) + /// { + /// compressor.Write(buffer, 0, n); + /// } + /// } + /// } + /// } + /// + /// + /// + /// Using input As Stream = File.OpenRead(fileToCompress) + /// Using raw As FileStream = File.Create(fileToCompress & ".deflated") + /// Using compressor As Stream = New DeflateStream(raw, CompressionMode.Compress) + /// Dim buffer As Byte() = New Byte(4096) {} + /// Dim n As Integer = -1 + /// Do While (n <> 0) + /// If (n > 0) Then + /// compressor.Write(buffer, 0, n) + /// End If + /// n = input.Read(buffer, 0, buffer.Length) + /// Loop + /// End Using + /// End Using + /// End Using + /// + /// + /// The stream which will be read or written. + /// Indicates whether the DeflateStream will compress or decompress. + public DeflateStream(System.IO.Stream stream, CompressionMode mode) + : this(stream, mode, CompressionLevel.Default, false) + { + } + + /// + /// Create a DeflateStream using the specified CompressionMode and the specified CompressionLevel. + /// + /// + /// + /// + /// + /// When mode is CompressionMode.Decompress, the level parameter is + /// ignored. The "captive" stream will be closed when the DeflateStream is + /// closed. + /// + /// + /// + /// + /// + /// + /// This example uses a DeflateStream to compress data from a file, and writes + /// the compressed data to another file. + /// + /// + /// using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress)) + /// { + /// using (var raw = System.IO.File.Create(fileToCompress + ".deflated")) + /// { + /// using (Stream compressor = new DeflateStream(raw, + /// CompressionMode.Compress, + /// CompressionLevel.BestCompression)) + /// { + /// byte[] buffer = new byte[WORKING_BUFFER_SIZE]; + /// int n= -1; + /// while (n != 0) + /// { + /// if (n > 0) + /// compressor.Write(buffer, 0, n); + /// n= input.Read(buffer, 0, buffer.Length); + /// } + /// } + /// } + /// } + /// + /// + /// + /// Using input As Stream = File.OpenRead(fileToCompress) + /// Using raw As FileStream = File.Create(fileToCompress & ".deflated") + /// Using compressor As Stream = New DeflateStream(raw, CompressionMode.Compress, CompressionLevel.BestCompression) + /// Dim buffer As Byte() = New Byte(4096) {} + /// Dim n As Integer = -1 + /// Do While (n <> 0) + /// If (n > 0) Then + /// compressor.Write(buffer, 0, n) + /// End If + /// n = input.Read(buffer, 0, buffer.Length) + /// Loop + /// End Using + /// End Using + /// End Using + /// + /// + /// The stream to be read or written while deflating or inflating. + /// Indicates whether the DeflateStream will compress or decompress. + /// A tuning knob to trade speed for effectiveness. + public DeflateStream(System.IO.Stream stream, CompressionMode mode, CompressionLevel level) + : this(stream, mode, level, false) + { + } + + /// + /// Create a DeflateStream using the specified + /// CompressionMode, and explicitly specify whether the + /// stream should be left open after Deflation or Inflation. + /// + /// + /// + /// + /// + /// This constructor allows the application to request that the captive stream + /// remain open after the deflation or inflation occurs. By default, after + /// Close() is called on the stream, the captive stream is also + /// closed. In some cases this is not desired, for example if the stream is a + /// memory stream that will be re-read after compression. Specify true for + /// the parameter to leave the stream open. + /// + /// + /// + /// The DeflateStream will use the default compression level. + /// + /// + /// + /// See the other overloads of this constructor for example code. + /// + /// + /// + /// + /// The stream which will be read or written. This is called the + /// "captive" stream in other places in this documentation. + /// + /// + /// + /// Indicates whether the DeflateStream will compress or decompress. + /// + /// + /// true if the application would like the stream to + /// remain open after inflation/deflation. + public DeflateStream(System.IO.Stream stream, CompressionMode mode, bool leaveOpen) + : this(stream, mode, CompressionLevel.Default, leaveOpen) + { + } + + /// + /// Create a DeflateStream using the specified CompressionMode + /// and the specified CompressionLevel, and explicitly specify whether + /// the stream should be left open after Deflation or Inflation. + /// + /// + /// + /// + /// + /// When mode is CompressionMode.Decompress, the level parameter is ignored. + /// + /// + /// + /// This constructor allows the application to request that the captive stream + /// remain open after the deflation or inflation occurs. By default, after + /// Close() is called on the stream, the captive stream is also + /// closed. In some cases this is not desired, for example if the stream is a + /// that will be re-read after + /// compression. Specify true for the parameter + /// to leave the stream open. + /// + /// + /// + /// + /// + /// + /// This example shows how to use a DeflateStream to compress data from + /// a file, and store the compressed data into another file. + /// + /// + /// using (var output = System.IO.File.Create(fileToCompress + ".deflated")) + /// { + /// using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress)) + /// { + /// using (Stream compressor = new DeflateStream(output, CompressionMode.Compress, CompressionLevel.BestCompression, true)) + /// { + /// byte[] buffer = new byte[WORKING_BUFFER_SIZE]; + /// int n= -1; + /// while (n != 0) + /// { + /// if (n > 0) + /// compressor.Write(buffer, 0, n); + /// n= input.Read(buffer, 0, buffer.Length); + /// } + /// } + /// } + /// // can write additional data to the output stream here + /// } + /// + /// + /// + /// Using output As FileStream = File.Create(fileToCompress & ".deflated") + /// Using input As Stream = File.OpenRead(fileToCompress) + /// Using compressor As Stream = New DeflateStream(output, CompressionMode.Compress, CompressionLevel.BestCompression, True) + /// Dim buffer As Byte() = New Byte(4096) {} + /// Dim n As Integer = -1 + /// Do While (n <> 0) + /// If (n > 0) Then + /// compressor.Write(buffer, 0, n) + /// End If + /// n = input.Read(buffer, 0, buffer.Length) + /// Loop + /// End Using + /// End Using + /// ' can write additional data to the output stream here. + /// End Using + /// + /// + /// The stream which will be read or written. + /// Indicates whether the DeflateStream will compress or decompress. + /// true if the application would like the stream to remain open after inflation/deflation. + /// A tuning knob to trade speed for effectiveness. + public DeflateStream(System.IO.Stream stream, CompressionMode mode, CompressionLevel level, bool leaveOpen) + { + _innerStream = stream; + _baseStream = new ZlibBaseStream(stream, mode, level, ZlibStreamFlavor.DEFLATE, leaveOpen); + } + + #region Zlib properties + + /// + /// This property sets the flush behavior on the stream. + /// + /// See the ZLIB documentation for the meaning of the flush behavior. + /// + virtual public FlushType FlushMode + { + get { return (this._baseStream._flushMode); } + set + { + if (_disposed) throw new ObjectDisposedException("DeflateStream"); + this._baseStream._flushMode = value; + } + } + + /// + /// The size of the working buffer for the compression codec. + /// + /// + /// + /// + /// The working buffer is used for all stream operations. The default size is + /// 1024 bytes. The minimum size is 128 bytes. You may get better performance + /// with a larger buffer. Then again, you might not. You would have to test + /// it. + /// + /// + /// + /// Set this before the first call to Read() or Write() on the + /// stream. If you try to set it afterwards, it will throw. + /// + /// + public int BufferSize + { + get + { + return this._baseStream._bufferSize; + } + set + { + if (_disposed) throw new ObjectDisposedException("DeflateStream"); + if (this._baseStream._workingBuffer != null) + throw new ZlibException("The working buffer is already set."); + if (value < ZlibConstants.WorkingBufferSizeMin) + throw new ZlibException(String.Format("Don't be silly. {0} bytes?? Use a bigger buffer, at least {1}.", value, ZlibConstants.WorkingBufferSizeMin)); + this._baseStream._bufferSize = value; + } + } + + /// + /// The ZLIB strategy to be used during compression. + /// + /// + /// + /// By tweaking this parameter, you may be able to optimize the compression for + /// data with particular characteristics. + /// + public CompressionStrategy Strategy + { + get + { + return this._baseStream.Strategy; + } + set + { + if (_disposed) throw new ObjectDisposedException("DeflateStream"); + this._baseStream.Strategy = value; + } + } + + /// Returns the total number of bytes input so far. + virtual public long TotalIn + { + get + { + return this._baseStream._z.TotalBytesIn; + } + } + + /// Returns the total number of bytes output so far. + virtual public long TotalOut + { + get + { + return this._baseStream._z.TotalBytesOut; + } + } + + #endregion + + #region System.IO.Stream methods + /// + /// Dispose the stream. + /// + /// + /// + /// This may or may not result in a Close() call on the captive + /// stream. See the constructors that have a leaveOpen parameter + /// for more information. + /// + /// + /// Application code won't call this code directly. This method may be + /// invoked in two distinct scenarios. If disposing == true, the method + /// has been called directly or indirectly by a user's code, for example + /// via the public Dispose() method. In this case, both managed and + /// unmanaged resources can be referenced and disposed. If disposing == + /// false, the method has been called by the runtime from inside the + /// object finalizer and this method should not reference other objects; + /// in that case only unmanaged resources must be referenced or + /// disposed. + /// + /// + /// + /// true if the Dispose method was invoked by user code. + /// + protected override void Dispose(bool disposing) + { + try + { + if (!_disposed) + { + if (disposing && (this._baseStream != null)) + this._baseStream.Close(); + _disposed = true; + } + } + finally + { + base.Dispose(disposing); + } + } + + + + /// + /// Indicates whether the stream can be read. + /// + /// + /// The return value depends on whether the captive stream supports reading. + /// + public override bool CanRead + { + get + { + if (_disposed) throw new ObjectDisposedException("DeflateStream"); + return _baseStream._stream.CanRead; + } + } + + /// + /// Indicates whether the stream supports Seek operations. + /// + /// + /// Always returns false. + /// + public override bool CanSeek + { + get { return false; } + } + + + /// + /// Indicates whether the stream can be written. + /// + /// + /// The return value depends on whether the captive stream supports writing. + /// + public override bool CanWrite + { + get + { + if (_disposed) throw new ObjectDisposedException("DeflateStream"); + return _baseStream._stream.CanWrite; + } + } + + /// + /// Flush the stream. + /// + public override void Flush() + { + if (_disposed) throw new ObjectDisposedException("DeflateStream"); + _baseStream.Flush(); + } + + /// + /// Reading this property always throws a . + /// + public override long Length + { + get { throw new NotImplementedException(); } + } + + /// + /// The position of the stream pointer. + /// + /// + /// + /// Setting this property always throws a . Reading will return the total bytes + /// written out, if used in writing, or the total bytes read in, if used in + /// reading. The count may refer to compressed bytes or uncompressed bytes, + /// depending on how you've used the stream. + /// + public override long Position + { + get + { + if (this._baseStream._streamMode == Ionic.Zlib.ZlibBaseStream.StreamMode.Writer) + return this._baseStream._z.TotalBytesOut; + if (this._baseStream._streamMode == Ionic.Zlib.ZlibBaseStream.StreamMode.Reader) + return this._baseStream._z.TotalBytesIn; + return 0; + } + set { throw new NotImplementedException(); } + } + + /// + /// Read data from the stream. + /// + /// + /// + /// + /// If you wish to use the DeflateStream to compress data while + /// reading, you can create a DeflateStream with + /// CompressionMode.Compress, providing an uncompressed data stream. + /// Then call Read() on that DeflateStream, and the data read will be + /// compressed as you read. If you wish to use the DeflateStream to + /// decompress data while reading, you can create a DeflateStream with + /// CompressionMode.Decompress, providing a readable compressed data + /// stream. Then call Read() on that DeflateStream, and the data read + /// will be decompressed as you read. + /// + /// + /// + /// A DeflateStream can be used for Read() or Write(), but not both. + /// + /// + /// + /// The buffer into which the read data should be placed. + /// the offset within that data array to put the first byte read. + /// the number of bytes to read. + /// the number of bytes actually read + public override int Read(byte[] buffer, int offset, int count) + { + if (_disposed) throw new ObjectDisposedException("DeflateStream"); + return _baseStream.Read(buffer, offset, count); + } + + + /// + /// Calling this method always throws a . + /// + /// this is irrelevant, since it will always throw! + /// this is irrelevant, since it will always throw! + /// irrelevant! + public override long Seek(long offset, System.IO.SeekOrigin origin) + { + throw new NotImplementedException(); + } + + /// + /// Calling this method always throws a . + /// + /// this is irrelevant, since it will always throw! + public override void SetLength(long value) + { + throw new NotImplementedException(); + } + + /// + /// Write data to the stream. + /// + /// + /// + /// + /// If you wish to use the DeflateStream to compress data while + /// writing, you can create a DeflateStream with + /// CompressionMode.Compress, and a writable output stream. Then call + /// Write() on that DeflateStream, providing uncompressed data + /// as input. The data sent to the output stream will be the compressed form + /// of the data written. If you wish to use the DeflateStream to + /// decompress data while writing, you can create a DeflateStream with + /// CompressionMode.Decompress, and a writable output stream. Then + /// call Write() on that stream, providing previously compressed + /// data. The data sent to the output stream will be the decompressed form of + /// the data written. + /// + /// + /// + /// A DeflateStream can be used for Read() or Write(), + /// but not both. + /// + /// + /// + /// + /// The buffer holding data to write to the stream. + /// the offset within that data array to find the first byte to write. + /// the number of bytes to write. + public override void Write(byte[] buffer, int offset, int count) + { + if (_disposed) throw new ObjectDisposedException("DeflateStream"); + _baseStream.Write(buffer, offset, count); + } + #endregion + + + + + /// + /// Compress a string into a byte array using DEFLATE (RFC 1951). + /// + /// + /// + /// Uncompress it with . + /// + /// + /// DeflateStream.UncompressString(byte[]) + /// DeflateStream.CompressBuffer(byte[]) + /// GZipStream.CompressString(string) + /// ZlibStream.CompressString(string) + /// + /// + /// A string to compress. The string will first be encoded + /// using UTF8, then compressed. + /// + /// + /// The string in compressed form + public static byte[] CompressString(String s) + { + using (var ms = new System.IO.MemoryStream()) + { + System.IO.Stream compressor = + new DeflateStream(ms, CompressionMode.Compress, CompressionLevel.BestCompression); + ZlibBaseStream.CompressString(s, compressor); + return ms.ToArray(); + } + } + + + /// + /// Compress a byte array into a new byte array using DEFLATE. + /// + /// + /// + /// Uncompress it with . + /// + /// + /// DeflateStream.CompressString(string) + /// DeflateStream.UncompressBuffer(byte[]) + /// GZipStream.CompressBuffer(byte[]) + /// ZlibStream.CompressBuffer(byte[]) + /// + /// + /// A buffer to compress. + /// + /// + /// The data in compressed form + public static byte[] CompressBuffer(byte[] b) + { + using (var ms = new System.IO.MemoryStream()) + { + System.IO.Stream compressor = + new DeflateStream( ms, CompressionMode.Compress, CompressionLevel.BestCompression ); + + ZlibBaseStream.CompressBuffer(b, compressor); + return ms.ToArray(); + } + } + + + /// + /// Uncompress a DEFLATE'd byte array into a single string. + /// + /// + /// DeflateStream.CompressString(String) + /// DeflateStream.UncompressBuffer(byte[]) + /// GZipStream.UncompressString(byte[]) + /// ZlibStream.UncompressString(byte[]) + /// + /// + /// A buffer containing DEFLATE-compressed data. + /// + /// + /// The uncompressed string + public static String UncompressString(byte[] compressed) + { + using (var input = new System.IO.MemoryStream(compressed)) + { + System.IO.Stream decompressor = + new DeflateStream(input, CompressionMode.Decompress); + + return ZlibBaseStream.UncompressString(compressed, decompressor); + } + } + + + /// + /// Uncompress a DEFLATE'd byte array into a byte array. + /// + /// + /// DeflateStream.CompressBuffer(byte[]) + /// DeflateStream.UncompressString(byte[]) + /// GZipStream.UncompressBuffer(byte[]) + /// ZlibStream.UncompressBuffer(byte[]) + /// + /// + /// A buffer containing data that has been compressed with DEFLATE. + /// + /// + /// The data in uncompressed form + public static byte[] UncompressBuffer(byte[] compressed) + { + using (var input = new System.IO.MemoryStream(compressed)) + { + System.IO.Stream decompressor = + new DeflateStream( input, CompressionMode.Decompress ); + + return ZlibBaseStream.UncompressBuffer(compressed, decompressor); + } + } + + } + +} + diff --git a/Resources/Libraries/DotNetZip/Source/Zlib/GZipStream.cs b/Resources/Libraries/DotNetZip/Source/Zlib/GZipStream.cs new file mode 100644 index 00000000..297065cb --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zlib/GZipStream.cs @@ -0,0 +1,1029 @@ +// GZipStream.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa and Microsoft Corporation. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-11 21:42:34> +// +// ------------------------------------------------------------------ +// +// This module defines the GZipStream class, which can be used as a replacement for +// the System.IO.Compression.GZipStream class in the .NET BCL. NB: The design is not +// completely OO clean: there is some intelligence in the ZlibBaseStream that reads the +// GZip header. +// +// ------------------------------------------------------------------ + + +using System; +using System.IO; + +namespace Ionic.Zlib +{ + /// + /// A class for compressing and decompressing GZIP streams. + /// + /// + /// + /// + /// The GZipStream is a Decorator on a + /// . It adds GZIP compression or decompression to any + /// stream. + /// + /// + /// + /// Like the System.IO.Compression.GZipStream in the .NET Base Class Library, the + /// Ionic.Zlib.GZipStream can compress while writing, or decompress while + /// reading, but not vice versa. The compression method used is GZIP, which is + /// documented in IETF RFC + /// 1952, "GZIP file format specification version 4.3". + /// + /// + /// A GZipStream can be used to decompress data (through Read()) or + /// to compress data (through Write()), but not both. + /// + /// + /// + /// If you wish to use the GZipStream to compress data, you must wrap it + /// around a write-able stream. As you call Write() on the GZipStream, the + /// data will be compressed into the GZIP format. If you want to decompress data, + /// you must wrap the GZipStream around a readable stream that contains an + /// IETF RFC 1952-compliant stream. The data will be decompressed as you call + /// Read() on the GZipStream. + /// + /// + /// + /// Though the GZIP format allows data from multiple files to be concatenated + /// together, this stream handles only a single segment of GZIP format, typically + /// representing a single file. + /// + /// + /// + /// This class is similar to and . + /// ZlibStream handles RFC1950-compliant streams. + /// handles RFC1951-compliant streams. This class handles RFC1952-compliant streams. + /// + /// + /// + /// + /// + /// + public class GZipStream : System.IO.Stream + { + // GZip format + // source: http://tools.ietf.org/html/rfc1952 + // + // header id: 2 bytes 1F 8B + // compress method 1 byte 8= DEFLATE (none other supported) + // flag 1 byte bitfield (See below) + // mtime 4 bytes time_t (seconds since jan 1, 1970 UTC of the file. + // xflg 1 byte 2 = max compress used , 4 = max speed (can be ignored) + // OS 1 byte OS for originating archive. set to 0xFF in compression. + // extra field length 2 bytes optional - only if FEXTRA is set. + // extra field varies + // filename varies optional - if FNAME is set. zero terminated. ISO-8859-1. + // file comment varies optional - if FCOMMENT is set. zero terminated. ISO-8859-1. + // crc16 1 byte optional - present only if FHCRC bit is set + // compressed data varies + // CRC32 4 bytes + // isize 4 bytes data size modulo 2^32 + // + // FLG (FLaGs) + // bit 0 FTEXT - indicates file is ASCII text (can be safely ignored) + // bit 1 FHCRC - there is a CRC16 for the header immediately following the header + // bit 2 FEXTRA - extra fields are present + // bit 3 FNAME - the zero-terminated filename is present. encoding; ISO-8859-1. + // bit 4 FCOMMENT - a zero-terminated file comment is present. encoding: ISO-8859-1 + // bit 5 reserved + // bit 6 reserved + // bit 7 reserved + // + // On consumption: + // Extra field is a bunch of nonsense and can be safely ignored. + // Header CRC and OS, likewise. + // + // on generation: + // all optional fields get 0, except for the OS, which gets 255. + // + + + + /// + /// The comment on the GZIP stream. + /// + /// + /// + /// + /// The GZIP format allows for each file to optionally have an associated + /// comment stored with the file. The comment is encoded with the ISO-8859-1 + /// code page. To include a comment in a GZIP stream you create, set this + /// property before calling Write() for the first time on the + /// GZipStream. + /// + /// + /// + /// When using GZipStream to decompress, you can retrieve this property + /// after the first call to Read(). If no comment has been set in the + /// GZIP bytestream, the Comment property will return null + /// (Nothing in VB). + /// + /// + public String Comment + { + get + { + return _Comment; + } + set + { + if (_disposed) throw new ObjectDisposedException("GZipStream"); + _Comment = value; + } + } + + /// + /// The FileName for the GZIP stream. + /// + /// + /// + /// + /// + /// The GZIP format optionally allows each file to have an associated + /// filename. When compressing data (through Write()), set this + /// FileName before calling Write() the first time on the GZipStream. + /// The actual filename is encoded into the GZIP bytestream with the + /// ISO-8859-1 code page, according to RFC 1952. It is the application's + /// responsibility to insure that the FileName can be encoded and decoded + /// correctly with this code page. + /// + /// + /// + /// When decompressing (through Read()), you can retrieve this value + /// any time after the first Read(). In the case where there was no filename + /// encoded into the GZIP bytestream, the property will return null (Nothing + /// in VB). + /// + /// + public String FileName + { + get { return _FileName; } + set + { + if (_disposed) throw new ObjectDisposedException("GZipStream"); + _FileName = value; + if (_FileName == null) return; + if (_FileName.IndexOf("/") != -1) + { + _FileName = _FileName.Replace("/", "\\"); + } + if (_FileName.EndsWith("\\")) + throw new Exception("Illegal filename"); + if (_FileName.IndexOf("\\") != -1) + { + // trim any leading path + _FileName = Path.GetFileName(_FileName); + } + } + } + + /// + /// The last modified time for the GZIP stream. + /// + /// + /// + /// GZIP allows the storage of a last modified time with each GZIP entry. + /// When compressing data, you can set this before the first call to + /// Write(). When decompressing, you can retrieve this value any time + /// after the first call to Read(). + /// + public DateTime? LastModified; + + /// + /// The CRC on the GZIP stream. + /// + /// + /// This is used for internal error checking. You probably don't need to look at this property. + /// + public int Crc32 { get { return _Crc32; } } + + private int _headerByteCount; + internal ZlibBaseStream _baseStream; + bool _disposed; + bool _firstReadDone; + string _FileName; + string _Comment; + int _Crc32; + + + /// + /// Create a GZipStream using the specified CompressionMode. + /// + /// + /// + /// + /// When mode is CompressionMode.Compress, the GZipStream will use the + /// default compression level. + /// + /// + /// + /// As noted in the class documentation, the CompressionMode (Compress + /// or Decompress) also establishes the "direction" of the stream. A + /// GZipStream with CompressionMode.Compress works only through + /// Write(). A GZipStream with + /// CompressionMode.Decompress works only through Read(). + /// + /// + /// + /// + /// + /// This example shows how to use a GZipStream to compress data. + /// + /// using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress)) + /// { + /// using (var raw = System.IO.File.Create(outputFile)) + /// { + /// using (Stream compressor = new GZipStream(raw, CompressionMode.Compress)) + /// { + /// byte[] buffer = new byte[WORKING_BUFFER_SIZE]; + /// int n; + /// while ((n= input.Read(buffer, 0, buffer.Length)) != 0) + /// { + /// compressor.Write(buffer, 0, n); + /// } + /// } + /// } + /// } + /// + /// + /// Dim outputFile As String = (fileToCompress & ".compressed") + /// Using input As Stream = File.OpenRead(fileToCompress) + /// Using raw As FileStream = File.Create(outputFile) + /// Using compressor As Stream = New GZipStream(raw, CompressionMode.Compress) + /// Dim buffer As Byte() = New Byte(4096) {} + /// Dim n As Integer = -1 + /// Do While (n <> 0) + /// If (n > 0) Then + /// compressor.Write(buffer, 0, n) + /// End If + /// n = input.Read(buffer, 0, buffer.Length) + /// Loop + /// End Using + /// End Using + /// End Using + /// + /// + /// + /// + /// This example shows how to use a GZipStream to uncompress a file. + /// + /// private void GunZipFile(string filename) + /// { + /// if (!filename.EndsWith(".gz)) + /// throw new ArgumentException("filename"); + /// var DecompressedFile = filename.Substring(0,filename.Length-3); + /// byte[] working = new byte[WORKING_BUFFER_SIZE]; + /// int n= 1; + /// using (System.IO.Stream input = System.IO.File.OpenRead(filename)) + /// { + /// using (Stream decompressor= new Ionic.Zlib.GZipStream(input, CompressionMode.Decompress, true)) + /// { + /// using (var output = System.IO.File.Create(DecompressedFile)) + /// { + /// while (n !=0) + /// { + /// n= decompressor.Read(working, 0, working.Length); + /// if (n > 0) + /// { + /// output.Write(working, 0, n); + /// } + /// } + /// } + /// } + /// } + /// } + /// + /// + /// + /// Private Sub GunZipFile(ByVal filename as String) + /// If Not (filename.EndsWith(".gz)) Then + /// Throw New ArgumentException("filename") + /// End If + /// Dim DecompressedFile as String = filename.Substring(0,filename.Length-3) + /// Dim working(WORKING_BUFFER_SIZE) as Byte + /// Dim n As Integer = 1 + /// Using input As Stream = File.OpenRead(filename) + /// Using decompressor As Stream = new Ionic.Zlib.GZipStream(input, CompressionMode.Decompress, True) + /// Using output As Stream = File.Create(UncompressedFile) + /// Do + /// n= decompressor.Read(working, 0, working.Length) + /// If n > 0 Then + /// output.Write(working, 0, n) + /// End IF + /// Loop While (n > 0) + /// End Using + /// End Using + /// End Using + /// End Sub + /// + /// + /// + /// The stream which will be read or written. + /// Indicates whether the GZipStream will compress or decompress. + public GZipStream(Stream stream, CompressionMode mode) + : this(stream, mode, CompressionLevel.Default, false) + { + } + + /// + /// Create a GZipStream using the specified CompressionMode and + /// the specified CompressionLevel. + /// + /// + /// + /// + /// The CompressionMode (Compress or Decompress) also establishes the + /// "direction" of the stream. A GZipStream with + /// CompressionMode.Compress works only through Write(). A + /// GZipStream with CompressionMode.Decompress works only + /// through Read(). + /// + /// + /// + /// + /// + /// + /// This example shows how to use a GZipStream to compress a file into a .gz file. + /// + /// + /// using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress)) + /// { + /// using (var raw = System.IO.File.Create(fileToCompress + ".gz")) + /// { + /// using (Stream compressor = new GZipStream(raw, + /// CompressionMode.Compress, + /// CompressionLevel.BestCompression)) + /// { + /// byte[] buffer = new byte[WORKING_BUFFER_SIZE]; + /// int n; + /// while ((n= input.Read(buffer, 0, buffer.Length)) != 0) + /// { + /// compressor.Write(buffer, 0, n); + /// } + /// } + /// } + /// } + /// + /// + /// + /// Using input As Stream = File.OpenRead(fileToCompress) + /// Using raw As FileStream = File.Create(fileToCompress & ".gz") + /// Using compressor As Stream = New GZipStream(raw, CompressionMode.Compress, CompressionLevel.BestCompression) + /// Dim buffer As Byte() = New Byte(4096) {} + /// Dim n As Integer = -1 + /// Do While (n <> 0) + /// If (n > 0) Then + /// compressor.Write(buffer, 0, n) + /// End If + /// n = input.Read(buffer, 0, buffer.Length) + /// Loop + /// End Using + /// End Using + /// End Using + /// + /// + /// The stream to be read or written while deflating or inflating. + /// Indicates whether the GZipStream will compress or decompress. + /// A tuning knob to trade speed for effectiveness. + public GZipStream(Stream stream, CompressionMode mode, CompressionLevel level) + : this(stream, mode, level, false) + { + } + + /// + /// Create a GZipStream using the specified CompressionMode, and + /// explicitly specify whether the stream should be left open after Deflation + /// or Inflation. + /// + /// + /// + /// + /// This constructor allows the application to request that the captive stream + /// remain open after the deflation or inflation occurs. By default, after + /// Close() is called on the stream, the captive stream is also + /// closed. In some cases this is not desired, for example if the stream is a + /// memory stream that will be re-read after compressed data has been written + /// to it. Specify true for the parameter to leave + /// the stream open. + /// + /// + /// + /// The (Compress or Decompress) also + /// establishes the "direction" of the stream. A GZipStream with + /// CompressionMode.Compress works only through Write(). A GZipStream + /// with CompressionMode.Decompress works only through Read(). + /// + /// + /// + /// The GZipStream will use the default compression level. If you want + /// to specify the compression level, see . + /// + /// + /// + /// See the other overloads of this constructor for example code. + /// + /// + /// + /// + /// + /// The stream which will be read or written. This is called the "captive" + /// stream in other places in this documentation. + /// + /// + /// Indicates whether the GZipStream will compress or decompress. + /// + /// + /// + /// true if the application would like the base stream to remain open after + /// inflation/deflation. + /// + public GZipStream(Stream stream, CompressionMode mode, bool leaveOpen) + : this(stream, mode, CompressionLevel.Default, leaveOpen) + { + } + + /// + /// Create a GZipStream using the specified CompressionMode and the + /// specified CompressionLevel, and explicitly specify whether the + /// stream should be left open after Deflation or Inflation. + /// + /// + /// + /// + /// + /// This constructor allows the application to request that the captive stream + /// remain open after the deflation or inflation occurs. By default, after + /// Close() is called on the stream, the captive stream is also + /// closed. In some cases this is not desired, for example if the stream is a + /// memory stream that will be re-read after compressed data has been written + /// to it. Specify true for the parameter to + /// leave the stream open. + /// + /// + /// + /// As noted in the class documentation, the CompressionMode (Compress + /// or Decompress) also establishes the "direction" of the stream. A + /// GZipStream with CompressionMode.Compress works only through + /// Write(). A GZipStream with CompressionMode.Decompress works only + /// through Read(). + /// + /// + /// + /// + /// + /// This example shows how to use a GZipStream to compress data. + /// + /// using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress)) + /// { + /// using (var raw = System.IO.File.Create(outputFile)) + /// { + /// using (Stream compressor = new GZipStream(raw, CompressionMode.Compress, CompressionLevel.BestCompression, true)) + /// { + /// byte[] buffer = new byte[WORKING_BUFFER_SIZE]; + /// int n; + /// while ((n= input.Read(buffer, 0, buffer.Length)) != 0) + /// { + /// compressor.Write(buffer, 0, n); + /// } + /// } + /// } + /// } + /// + /// + /// Dim outputFile As String = (fileToCompress & ".compressed") + /// Using input As Stream = File.OpenRead(fileToCompress) + /// Using raw As FileStream = File.Create(outputFile) + /// Using compressor As Stream = New GZipStream(raw, CompressionMode.Compress, CompressionLevel.BestCompression, True) + /// Dim buffer As Byte() = New Byte(4096) {} + /// Dim n As Integer = -1 + /// Do While (n <> 0) + /// If (n > 0) Then + /// compressor.Write(buffer, 0, n) + /// End If + /// n = input.Read(buffer, 0, buffer.Length) + /// Loop + /// End Using + /// End Using + /// End Using + /// + /// + /// The stream which will be read or written. + /// Indicates whether the GZipStream will compress or decompress. + /// true if the application would like the stream to remain open after inflation/deflation. + /// A tuning knob to trade speed for effectiveness. + public GZipStream(Stream stream, CompressionMode mode, CompressionLevel level, bool leaveOpen) + { + _baseStream = new ZlibBaseStream(stream, mode, level, ZlibStreamFlavor.GZIP, leaveOpen); + } + + #region Zlib properties + + /// + /// This property sets the flush behavior on the stream. + /// + virtual public FlushType FlushMode + { + get { return (this._baseStream._flushMode); } + set { + if (_disposed) throw new ObjectDisposedException("GZipStream"); + this._baseStream._flushMode = value; + } + } + + /// + /// The size of the working buffer for the compression codec. + /// + /// + /// + /// + /// The working buffer is used for all stream operations. The default size is + /// 1024 bytes. The minimum size is 128 bytes. You may get better performance + /// with a larger buffer. Then again, you might not. You would have to test + /// it. + /// + /// + /// + /// Set this before the first call to Read() or Write() on the + /// stream. If you try to set it afterwards, it will throw. + /// + /// + public int BufferSize + { + get + { + return this._baseStream._bufferSize; + } + set + { + if (_disposed) throw new ObjectDisposedException("GZipStream"); + if (this._baseStream._workingBuffer != null) + throw new ZlibException("The working buffer is already set."); + if (value < ZlibConstants.WorkingBufferSizeMin) + throw new ZlibException(String.Format("Don't be silly. {0} bytes?? Use a bigger buffer, at least {1}.", value, ZlibConstants.WorkingBufferSizeMin)); + this._baseStream._bufferSize = value; + } + } + + + /// Returns the total number of bytes input so far. + virtual public long TotalIn + { + get + { + return this._baseStream._z.TotalBytesIn; + } + } + + /// Returns the total number of bytes output so far. + virtual public long TotalOut + { + get + { + return this._baseStream._z.TotalBytesOut; + } + } + + #endregion + + #region Stream methods + + /// + /// Dispose the stream. + /// + /// + /// + /// This may or may not result in a Close() call on the captive + /// stream. See the constructors that have a leaveOpen parameter + /// for more information. + /// + /// + /// This method may be invoked in two distinct scenarios. If disposing + /// == true, the method has been called directly or indirectly by a + /// user's code, for example via the public Dispose() method. In this + /// case, both managed and unmanaged resources can be referenced and + /// disposed. If disposing == false, the method has been called by the + /// runtime from inside the object finalizer and this method should not + /// reference other objects; in that case only unmanaged resources must + /// be referenced or disposed. + /// + /// + /// + /// indicates whether the Dispose method was invoked by user code. + /// + protected override void Dispose(bool disposing) + { + try + { + if (!_disposed) + { + if (disposing && (this._baseStream != null)) + { + this._baseStream.Close(); + this._Crc32 = _baseStream.Crc32; + } + _disposed = true; + } + } + finally + { + base.Dispose(disposing); + } + } + + + /// + /// Indicates whether the stream can be read. + /// + /// + /// The return value depends on whether the captive stream supports reading. + /// + public override bool CanRead + { + get + { + if (_disposed) throw new ObjectDisposedException("GZipStream"); + return _baseStream._stream.CanRead; + } + } + + /// + /// Indicates whether the stream supports Seek operations. + /// + /// + /// Always returns false. + /// + public override bool CanSeek + { + get { return false; } + } + + + /// + /// Indicates whether the stream can be written. + /// + /// + /// The return value depends on whether the captive stream supports writing. + /// + public override bool CanWrite + { + get + { + if (_disposed) throw new ObjectDisposedException("GZipStream"); + return _baseStream._stream.CanWrite; + } + } + + /// + /// Flush the stream. + /// + public override void Flush() + { + if (_disposed) throw new ObjectDisposedException("GZipStream"); + _baseStream.Flush(); + } + + /// + /// Reading this property always throws a . + /// + public override long Length + { + get { throw new NotImplementedException(); } + } + + /// + /// The position of the stream pointer. + /// + /// + /// + /// Setting this property always throws a . Reading will return the total bytes + /// written out, if used in writing, or the total bytes read in, if used in + /// reading. The count may refer to compressed bytes or uncompressed bytes, + /// depending on how you've used the stream. + /// + public override long Position + { + get + { + if (this._baseStream._streamMode == Ionic.Zlib.ZlibBaseStream.StreamMode.Writer) + return this._baseStream._z.TotalBytesOut + _headerByteCount; + if (this._baseStream._streamMode == Ionic.Zlib.ZlibBaseStream.StreamMode.Reader) + return this._baseStream._z.TotalBytesIn + this._baseStream._gzipHeaderByteCount; + return 0; + } + + set { throw new NotImplementedException(); } + } + + /// + /// Read and decompress data from the source stream. + /// + /// + /// + /// With a GZipStream, decompression is done through reading. + /// + /// + /// + /// + /// byte[] working = new byte[WORKING_BUFFER_SIZE]; + /// using (System.IO.Stream input = System.IO.File.OpenRead(_CompressedFile)) + /// { + /// using (Stream decompressor= new Ionic.Zlib.GZipStream(input, CompressionMode.Decompress, true)) + /// { + /// using (var output = System.IO.File.Create(_DecompressedFile)) + /// { + /// int n; + /// while ((n= decompressor.Read(working, 0, working.Length)) !=0) + /// { + /// output.Write(working, 0, n); + /// } + /// } + /// } + /// } + /// + /// + /// The buffer into which the decompressed data should be placed. + /// the offset within that data array to put the first byte read. + /// the number of bytes to read. + /// the number of bytes actually read + public override int Read(byte[] buffer, int offset, int count) + { + if (_disposed) throw new ObjectDisposedException("GZipStream"); + int n = _baseStream.Read(buffer, offset, count); + + // Console.WriteLine("GZipStream::Read(buffer, off({0}), c({1}) = {2}", offset, count, n); + // Console.WriteLine( Util.FormatByteArray(buffer, offset, n) ); + + if (!_firstReadDone) + { + _firstReadDone = true; + FileName = _baseStream._GzipFileName; + Comment = _baseStream._GzipComment; + } + return n; + } + + + + /// + /// Calling this method always throws a . + /// + /// irrelevant; it will always throw! + /// irrelevant; it will always throw! + /// irrelevant! + public override long Seek(long offset, SeekOrigin origin) + { + throw new NotImplementedException(); + } + + /// + /// Calling this method always throws a . + /// + /// irrelevant; this method will always throw! + public override void SetLength(long value) + { + throw new NotImplementedException(); + } + + /// + /// Write data to the stream. + /// + /// + /// + /// + /// If you wish to use the GZipStream to compress data while writing, + /// you can create a GZipStream with CompressionMode.Compress, and a + /// writable output stream. Then call Write() on that GZipStream, + /// providing uncompressed data as input. The data sent to the output stream + /// will be the compressed form of the data written. + /// + /// + /// + /// A GZipStream can be used for Read() or Write(), but not + /// both. Writing implies compression. Reading implies decompression. + /// + /// + /// + /// The buffer holding data to write to the stream. + /// the offset within that data array to find the first byte to write. + /// the number of bytes to write. + public override void Write(byte[] buffer, int offset, int count) + { + if (_disposed) throw new ObjectDisposedException("GZipStream"); + if (_baseStream._streamMode == Ionic.Zlib.ZlibBaseStream.StreamMode.Undefined) + { + //Console.WriteLine("GZipStream: First write"); + if (_baseStream._wantCompress) + { + // first write in compression, therefore, emit the GZIP header + _headerByteCount = EmitHeader(); + } + else + { + throw new InvalidOperationException(); + } + } + + _baseStream.Write(buffer, offset, count); + } + #endregion + + + internal static readonly System.DateTime _unixEpoch = new System.DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc); + internal static readonly System.Text.Encoding iso8859dash1 = System.Text.Encoding.GetEncoding("iso-8859-1"); + + + private int EmitHeader() + { + byte[] commentBytes = (Comment == null) ? null : iso8859dash1.GetBytes(Comment); + byte[] filenameBytes = (FileName == null) ? null : iso8859dash1.GetBytes(FileName); + + int cbLength = (Comment == null) ? 0 : commentBytes.Length + 1; + int fnLength = (FileName == null) ? 0 : filenameBytes.Length + 1; + + int bufferLength = 10 + cbLength + fnLength; + byte[] header = new byte[bufferLength]; + int i = 0; + // ID + header[i++] = 0x1F; + header[i++] = 0x8B; + + // compression method + header[i++] = 8; + byte flag = 0; + if (Comment != null) + flag ^= 0x10; + if (FileName != null) + flag ^= 0x8; + + // flag + header[i++] = flag; + + // mtime + if (!LastModified.HasValue) LastModified = DateTime.Now; + System.TimeSpan delta = LastModified.Value - _unixEpoch; + Int32 timet = (Int32)delta.TotalSeconds; + Array.Copy(BitConverter.GetBytes(timet), 0, header, i, 4); + i += 4; + + // xflg + header[i++] = 0; // this field is totally useless + // OS + header[i++] = 0xFF; // 0xFF == unspecified + + // extra field length - only if FEXTRA is set, which it is not. + //header[i++]= 0; + //header[i++]= 0; + + // filename + if (fnLength != 0) + { + Array.Copy(filenameBytes, 0, header, i, fnLength - 1); + i += fnLength - 1; + header[i++] = 0; // terminate + } + + // comment + if (cbLength != 0) + { + Array.Copy(commentBytes, 0, header, i, cbLength - 1); + i += cbLength - 1; + header[i++] = 0; // terminate + } + + _baseStream._stream.Write(header, 0, header.Length); + + return header.Length; // bytes written + } + + + + /// + /// Compress a string into a byte array using GZip. + /// + /// + /// + /// Uncompress it with . + /// + /// + /// + /// + /// + /// + /// A string to compress. The string will first be encoded + /// using UTF8, then compressed. + /// + /// + /// The string in compressed form + public static byte[] CompressString(String s) + { + using (var ms = new MemoryStream()) + { + System.IO.Stream compressor = + new GZipStream(ms, CompressionMode.Compress, CompressionLevel.BestCompression); + ZlibBaseStream.CompressString(s, compressor); + return ms.ToArray(); + } + } + + + /// + /// Compress a byte array into a new byte array using GZip. + /// + /// + /// + /// Uncompress it with . + /// + /// + /// + /// + /// + /// + /// A buffer to compress. + /// + /// + /// The data in compressed form + public static byte[] CompressBuffer(byte[] b) + { + using (var ms = new MemoryStream()) + { + System.IO.Stream compressor = + new GZipStream( ms, CompressionMode.Compress, CompressionLevel.BestCompression ); + + ZlibBaseStream.CompressBuffer(b, compressor); + return ms.ToArray(); + } + } + + + /// + /// Uncompress a GZip'ed byte array into a single string. + /// + /// + /// + /// + /// + /// + /// A buffer containing GZIP-compressed data. + /// + /// + /// The uncompressed string + public static String UncompressString(byte[] compressed) + { + using (var input = new MemoryStream(compressed)) + { + Stream decompressor = new GZipStream(input, CompressionMode.Decompress); + return ZlibBaseStream.UncompressString(compressed, decompressor); + } + } + + + /// + /// Uncompress a GZip'ed byte array into a byte array. + /// + /// + /// + /// + /// + /// + /// A buffer containing data that has been compressed with GZip. + /// + /// + /// The data in uncompressed form + public static byte[] UncompressBuffer(byte[] compressed) + { + using (var input = new System.IO.MemoryStream(compressed)) + { + System.IO.Stream decompressor = + new GZipStream( input, CompressionMode.Decompress ); + + return ZlibBaseStream.UncompressBuffer(compressed, decompressor); + } + } + + + } +} diff --git a/Resources/Libraries/DotNetZip/Source/Zlib/InfTree.cs b/Resources/Libraries/DotNetZip/Source/Zlib/InfTree.cs new file mode 100644 index 00000000..ffc5bb6f --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zlib/InfTree.cs @@ -0,0 +1,436 @@ +// Inftree.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa and Microsoft Corporation. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2009-October-28 12:43:54> +// +// ------------------------------------------------------------------ +// +// This module defines classes used in decompression. This code is derived +// from the jzlib implementation of zlib. In keeping with the license for jzlib, +// the copyright to that code is below. +// +// ------------------------------------------------------------------ +// +// Copyright (c) 2000,2001,2002,2003 ymnk, JCraft,Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// 1. Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// +// 2. Redistributions in binary form must reproduce the above copyright +// notice, this list of conditions and the following disclaimer in +// the documentation and/or other materials provided with the distribution. +// +// 3. The names of the authors may not be used to endorse or promote products +// derived from this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, +// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND +// FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JCRAFT, +// INC. OR ANY CONTRIBUTORS TO THIS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, +// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, +// OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +// EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// ----------------------------------------------------------------------- +// +// This program is based on zlib-1.1.3; credit to authors +// Jean-loup Gailly(jloup@gzip.org) and Mark Adler(madler@alumni.caltech.edu) +// and contributors of zlib. +// +// ----------------------------------------------------------------------- + + + +using System; +namespace Ionic.Zlib +{ + + sealed class InfTree + { + + private const int MANY = 1440; + + private const int Z_OK = 0; + private const int Z_STREAM_END = 1; + private const int Z_NEED_DICT = 2; + private const int Z_ERRNO = - 1; + private const int Z_STREAM_ERROR = - 2; + private const int Z_DATA_ERROR = - 3; + private const int Z_MEM_ERROR = - 4; + private const int Z_BUF_ERROR = - 5; + private const int Z_VERSION_ERROR = - 6; + + internal const int fixed_bl = 9; + internal const int fixed_bd = 5; + + //UPGRADE_NOTE: Final was removed from the declaration of 'fixed_tl'. "ms-help://MS.VSCC.v80/dv_commoner/local/redirect.htm?index='!DefaultContextWindowIndex'&keyword='jlca1003'" + internal static readonly int[] fixed_tl = new int[]{96, 7, 256, 0, 8, 80, 0, 8, 16, 84, 8, 115, 82, 7, 31, 0, 8, 112, 0, 8, 48, 0, 9, 192, 80, 7, 10, 0, 8, 96, 0, 8, 32, 0, 9, 160, 0, 8, 0, 0, 8, 128, 0, 8, 64, 0, 9, 224, 80, 7, 6, 0, 8, 88, 0, 8, 24, 0, 9, 144, 83, 7, 59, 0, 8, 120, 0, 8, 56, 0, 9, 208, 81, 7, 17, 0, 8, 104, 0, 8, 40, 0, 9, 176, 0, 8, 8, 0, 8, 136, 0, 8, 72, 0, 9, 240, 80, 7, 4, 0, 8, 84, 0, 8, 20, 85, 8, 227, 83, 7, 43, 0, 8, 116, 0, 8, 52, 0, 9, 200, 81, 7, 13, 0, 8, 100, 0, 8, 36, 0, 9, 168, 0, 8, 4, 0, 8, 132, 0, 8, 68, 0, 9, 232, 80, 7, 8, 0, 8, 92, 0, 8, 28, 0, 9, 152, 84, 7, 83, 0, 8, 124, 0, 8, 60, 0, 9, 216, 82, 7, 23, 0, 8, 108, 0, 8, 44, 0, 9, 184, 0, 8, 12, 0, 8, 140, 0, 8, 76, 0, 9, 248, 80, 7, 3, 0, 8, 82, 0, 8, 18, 85, 8, 163, 83, 7, 35, 0, 8, 114, 0, 8, 50, 0, 9, 196, 81, 7, 11, 0, 8, 98, 0, 8, 34, 0, 9, 164, 0, 8, 2, 0, 8, 130, 0, 8, 66, 0, 9, 228, 80, 7, 7, 0, 8, 90, 0, 8, 26, 0, 9, 148, 84, 7, 67, 0, 8, 122, 0, 8, 58, 0, 9, 212, 82, 7, 19, 0, 8, 106, 0, 8, 42, 0, 9, 180, 0, 8, 10, 0, 8, 138, 0, 8, 74, 0, 9, 244, 80, 7, 5, 0, 8, 86, 0, 8, 22, 192, 8, 0, 83, 7, 51, 0, 8, 118, 0, 8, 54, 0, 9, 204, 81, 7, 15, 0, 8, 102, 0, 8, 38, 0, 9, 172, 0, 8, 6, 0, 8, 134, 0, 8, 70, 0, 9, 236, 80, 7, 9, 0, 8, 94, 0, 8, 30, 0, 9, 156, 84, 7, 99, 0, 8, 126, 0, 8, 62, 0, 9, 220, 82, 7, 27, 0, 8, 110, 0, 8, 46, 0, 9, 188, 0, 8, 14, 0, 8, 142, 0, 8, 78, 0, 9, 252, 96, 7, 256, 0, 8, 81, 0, 8, 17, 85, 8, 131, 82, 7, 31, 0, 8, 113, 0, 8, 49, 0, 9, 194, 80, 7, 10, 0, 8, 97, 0, 8, 33, 0, 9, 162, 0, 8, 1, 0, 8, 129, 0, 8, 65, 0, 9, 226, 80, 7, 6, 0, 8, 89, 0, 8, 25, 0, 9, 146, 83, 7, 59, 0, 8, 121, 0, 8, 57, 0, 9, 210, 81, 7, 17, 0, 8, 105, 0, 8, 41, 0, 9, 178, 0, 8, 9, 0, 8, 137, 0, 8, 73, 0, 9, 242, 80, 7, 4, 0, 8, 85, 0, 8, 21, 80, 8, 258, 83, 7, 43, 0, 8, 117, 0, 8, 53, 0, 9, 202, 81, 7, 13, 0, 8, 101, 0, 8, 37, 0, 9, 170, 0, 8, 5, 0, 8, 133, 0, 8, 69, 0, 9, 234, 80, 7, 8, 0, 8, 93, 0, 8, 29, 0, 9, 154, 84, 7, 83, 0, 8, 125, 0, 8, 61, 0, 9, 218, 82, 7, 23, 0, 8, 109, 0, 8, 45, 0, 9, 186, + 0, 8, 13, 0, 8, 141, 0, 8, 77, 0, 9, 250, 80, 7, 3, 0, 8, 83, 0, 8, 19, 85, 8, 195, 83, 7, 35, 0, 8, 115, 0, 8, 51, 0, 9, 198, 81, 7, 11, 0, 8, 99, 0, 8, 35, 0, 9, 166, 0, 8, 3, 0, 8, 131, 0, 8, 67, 0, 9, 230, 80, 7, 7, 0, 8, 91, 0, 8, 27, 0, 9, 150, 84, 7, 67, 0, 8, 123, 0, 8, 59, 0, 9, 214, 82, 7, 19, 0, 8, 107, 0, 8, 43, 0, 9, 182, 0, 8, 11, 0, 8, 139, 0, 8, 75, 0, 9, 246, 80, 7, 5, 0, 8, 87, 0, 8, 23, 192, 8, 0, 83, 7, 51, 0, 8, 119, 0, 8, 55, 0, 9, 206, 81, 7, 15, 0, 8, 103, 0, 8, 39, 0, 9, 174, 0, 8, 7, 0, 8, 135, 0, 8, 71, 0, 9, 238, 80, 7, 9, 0, 8, 95, 0, 8, 31, 0, 9, 158, 84, 7, 99, 0, 8, 127, 0, 8, 63, 0, 9, 222, 82, 7, 27, 0, 8, 111, 0, 8, 47, 0, 9, 190, 0, 8, 15, 0, 8, 143, 0, 8, 79, 0, 9, 254, 96, 7, 256, 0, 8, 80, 0, 8, 16, 84, 8, 115, 82, 7, 31, 0, 8, 112, 0, 8, 48, 0, 9, 193, 80, 7, 10, 0, 8, 96, 0, 8, 32, 0, 9, 161, 0, 8, 0, 0, 8, 128, 0, 8, 64, 0, 9, 225, 80, 7, 6, 0, 8, 88, 0, 8, 24, 0, 9, 145, 83, 7, 59, 0, 8, 120, 0, 8, 56, 0, 9, 209, 81, 7, 17, 0, 8, 104, 0, 8, 40, 0, 9, 177, 0, 8, 8, 0, 8, 136, 0, 8, 72, 0, 9, 241, 80, 7, 4, 0, 8, 84, 0, 8, 20, 85, 8, 227, 83, 7, 43, 0, 8, 116, 0, 8, 52, 0, 9, 201, 81, 7, 13, 0, 8, 100, 0, 8, 36, 0, 9, 169, 0, 8, 4, 0, 8, 132, 0, 8, 68, 0, 9, 233, 80, 7, 8, 0, 8, 92, 0, 8, 28, 0, 9, 153, 84, 7, 83, 0, 8, 124, 0, 8, 60, 0, 9, 217, 82, 7, 23, 0, 8, 108, 0, 8, 44, 0, 9, 185, 0, 8, 12, 0, 8, 140, 0, 8, 76, 0, 9, 249, 80, 7, 3, 0, 8, 82, 0, 8, 18, 85, 8, 163, 83, 7, 35, 0, 8, 114, 0, 8, 50, 0, 9, 197, 81, 7, 11, 0, 8, 98, 0, 8, 34, 0, 9, 165, 0, 8, 2, 0, 8, 130, 0, 8, 66, 0, 9, 229, 80, 7, 7, 0, 8, 90, 0, 8, 26, 0, 9, 149, 84, 7, 67, 0, 8, 122, 0, 8, 58, 0, 9, 213, 82, 7, 19, 0, 8, 106, 0, 8, 42, 0, 9, 181, 0, 8, 10, 0, 8, 138, 0, 8, 74, 0, 9, 245, 80, 7, 5, 0, 8, 86, 0, 8, 22, 192, 8, 0, 83, 7, 51, 0, 8, 118, 0, 8, 54, 0, 9, 205, 81, 7, 15, 0, 8, 102, 0, 8, 38, 0, 9, 173, 0, 8, 6, 0, 8, 134, 0, 8, 70, 0, 9, 237, 80, 7, 9, 0, 8, 94, 0, 8, 30, 0, 9, 157, 84, 7, 99, 0, 8, 126, 0, 8, 62, 0, 9, 221, 82, 7, 27, 0, 8, 110, 0, 8, 46, 0, 9, 189, 0, 8, + 14, 0, 8, 142, 0, 8, 78, 0, 9, 253, 96, 7, 256, 0, 8, 81, 0, 8, 17, 85, 8, 131, 82, 7, 31, 0, 8, 113, 0, 8, 49, 0, 9, 195, 80, 7, 10, 0, 8, 97, 0, 8, 33, 0, 9, 163, 0, 8, 1, 0, 8, 129, 0, 8, 65, 0, 9, 227, 80, 7, 6, 0, 8, 89, 0, 8, 25, 0, 9, 147, 83, 7, 59, 0, 8, 121, 0, 8, 57, 0, 9, 211, 81, 7, 17, 0, 8, 105, 0, 8, 41, 0, 9, 179, 0, 8, 9, 0, 8, 137, 0, 8, 73, 0, 9, 243, 80, 7, 4, 0, 8, 85, 0, 8, 21, 80, 8, 258, 83, 7, 43, 0, 8, 117, 0, 8, 53, 0, 9, 203, 81, 7, 13, 0, 8, 101, 0, 8, 37, 0, 9, 171, 0, 8, 5, 0, 8, 133, 0, 8, 69, 0, 9, 235, 80, 7, 8, 0, 8, 93, 0, 8, 29, 0, 9, 155, 84, 7, 83, 0, 8, 125, 0, 8, 61, 0, 9, 219, 82, 7, 23, 0, 8, 109, 0, 8, 45, 0, 9, 187, 0, 8, 13, 0, 8, 141, 0, 8, 77, 0, 9, 251, 80, 7, 3, 0, 8, 83, 0, 8, 19, 85, 8, 195, 83, 7, 35, 0, 8, 115, 0, 8, 51, 0, 9, 199, 81, 7, 11, 0, 8, 99, 0, 8, 35, 0, 9, 167, 0, 8, 3, 0, 8, 131, 0, 8, 67, 0, 9, 231, 80, 7, 7, 0, 8, 91, 0, 8, 27, 0, 9, 151, 84, 7, 67, 0, 8, 123, 0, 8, 59, 0, 9, 215, 82, 7, 19, 0, 8, 107, 0, 8, 43, 0, 9, 183, 0, 8, 11, 0, 8, 139, 0, 8, 75, 0, 9, 247, 80, 7, 5, 0, 8, 87, 0, 8, 23, 192, 8, 0, 83, 7, 51, 0, 8, 119, 0, 8, 55, 0, 9, 207, 81, 7, 15, 0, 8, 103, 0, 8, 39, 0, 9, 175, 0, 8, 7, 0, 8, 135, 0, 8, 71, 0, 9, 239, 80, 7, 9, 0, 8, 95, 0, 8, 31, 0, 9, 159, 84, 7, 99, 0, 8, 127, 0, 8, 63, 0, 9, 223, 82, 7, 27, 0, 8, 111, 0, 8, 47, 0, 9, 191, 0, 8, 15, 0, 8, 143, 0, 8, 79, 0, 9, 255}; + //UPGRADE_NOTE: Final was removed from the declaration of 'fixed_td'. "ms-help://MS.VSCC.v80/dv_commoner/local/redirect.htm?index='!DefaultContextWindowIndex'&keyword='jlca1003'" + internal static readonly int[] fixed_td = new int[]{80, 5, 1, 87, 5, 257, 83, 5, 17, 91, 5, 4097, 81, 5, 5, 89, 5, 1025, 85, 5, 65, 93, 5, 16385, 80, 5, 3, 88, 5, 513, 84, 5, 33, 92, 5, 8193, 82, 5, 9, 90, 5, 2049, 86, 5, 129, 192, 5, 24577, 80, 5, 2, 87, 5, 385, 83, 5, 25, 91, 5, 6145, 81, 5, 7, 89, 5, 1537, 85, 5, 97, 93, 5, 24577, 80, 5, 4, 88, 5, 769, 84, 5, 49, 92, 5, 12289, 82, 5, 13, 90, 5, 3073, 86, 5, 193, 192, 5, 24577}; + + // Tables for deflate from PKZIP's appnote.txt. + //UPGRADE_NOTE: Final was removed from the declaration of 'cplens'. "ms-help://MS.VSCC.v80/dv_commoner/local/redirect.htm?index='!DefaultContextWindowIndex'&keyword='jlca1003'" + internal static readonly int[] cplens = new int[]{3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 15, 17, 19, 23, 27, 31, 35, 43, 51, 59, 67, 83, 99, 115, 131, 163, 195, 227, 258, 0, 0}; + + // see note #13 above about 258 + //UPGRADE_NOTE: Final was removed from the declaration of 'cplext'. "ms-help://MS.VSCC.v80/dv_commoner/local/redirect.htm?index='!DefaultContextWindowIndex'&keyword='jlca1003'" + internal static readonly int[] cplext = new int[]{0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0, 112, 112}; + + //UPGRADE_NOTE: Final was removed from the declaration of 'cpdist'. "ms-help://MS.VSCC.v80/dv_commoner/local/redirect.htm?index='!DefaultContextWindowIndex'&keyword='jlca1003'" + internal static readonly int[] cpdist = new int[]{1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49, 65, 97, 129, 193, 257, 385, 513, 769, 1025, 1537, 2049, 3073, 4097, 6145, 8193, 12289, 16385, 24577}; + + //UPGRADE_NOTE: Final was removed from the declaration of 'cpdext'. "ms-help://MS.VSCC.v80/dv_commoner/local/redirect.htm?index='!DefaultContextWindowIndex'&keyword='jlca1003'" + internal static readonly int[] cpdext = new int[]{0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13}; + + // If BMAX needs to be larger than 16, then h and x[] should be uLong. + internal const int BMAX = 15; // maximum bit length of any code + + internal int[] hn = null; // hufts used in space + internal int[] v = null; // work area for huft_build + internal int[] c = null; // bit length count table + internal int[] r = null; // table entry for structure assignment + internal int[] u = null; // table stack + internal int[] x = null; // bit offsets, then code stack + + private int huft_build(int[] b, int bindex, int n, int s, int[] d, int[] e, int[] t, int[] m, int[] hp, int[] hn, int[] v) + { + // Given a list of code lengths and a maximum table size, make a set of + // tables to decode that set of codes. Return Z_OK on success, Z_BUF_ERROR + // if the given code set is incomplete (the tables are still built in this + // case), Z_DATA_ERROR if the input is invalid (an over-subscribed set of + // lengths), or Z_MEM_ERROR if not enough memory. + + int a; // counter for codes of length k + int f; // i repeats in table every f entries + int g; // maximum code length + int h; // table level + int i; // counter, current code + int j; // counter + int k; // number of bits in current code + int l; // bits per table (returned in m) + int mask; // (1 << w) - 1, to avoid cc -O bug on HP + int p; // pointer into c[], b[], or v[] + int q; // points to current table + int w; // bits before this table == (l * h) + int xp; // pointer into x + int y; // number of dummy codes added + int z; // number of entries in current table + + // Generate counts for each bit length + + p = 0; i = n; + do + { + c[b[bindex + p]]++; p++; i--; // assume all entries <= BMAX + } + while (i != 0); + + if (c[0] == n) + { + // null input--all zero length codes + t[0] = - 1; + m[0] = 0; + return Z_OK; + } + + // Find minimum and maximum length, bound *m by those + l = m[0]; + for (j = 1; j <= BMAX; j++) + if (c[j] != 0) + break; + k = j; // minimum code length + if (l < j) + { + l = j; + } + for (i = BMAX; i != 0; i--) + { + if (c[i] != 0) + break; + } + g = i; // maximum code length + if (l > i) + { + l = i; + } + m[0] = l; + + // Adjust last length count to fill out codes, if needed + for (y = 1 << j; j < i; j++, y <<= 1) + { + if ((y -= c[j]) < 0) + { + return Z_DATA_ERROR; + } + } + if ((y -= c[i]) < 0) + { + return Z_DATA_ERROR; + } + c[i] += y; + + // Generate starting offsets into the value table for each length + x[1] = j = 0; + p = 1; xp = 2; + while (--i != 0) + { + // note that i == g from above + x[xp] = (j += c[p]); + xp++; + p++; + } + + // Make a table of values in order of bit lengths + i = 0; p = 0; + do + { + if ((j = b[bindex + p]) != 0) + { + v[x[j]++] = i; + } + p++; + } + while (++i < n); + n = x[g]; // set n to length of v + + // Generate the Huffman codes and for each, make the table entries + x[0] = i = 0; // first Huffman code is zero + p = 0; // grab values in bit order + h = - 1; // no tables yet--level -1 + w = - l; // bits decoded == (l * h) + u[0] = 0; // just to keep compilers happy + q = 0; // ditto + z = 0; // ditto + + // go through the bit lengths (k already is bits in shortest code) + for (; k <= g; k++) + { + a = c[k]; + while (a-- != 0) + { + // here i is the Huffman code of length k bits for value *p + // make tables up to required level + while (k > w + l) + { + h++; + w += l; // previous table always l bits + // compute minimum size table less than or equal to l bits + z = g - w; + z = (z > l)?l:z; // table size upper limit + if ((f = 1 << (j = k - w)) > a + 1) + { + // try a k-w bit table + // too few codes for k-w bit table + f -= (a + 1); // deduct codes from patterns left + xp = k; + if (j < z) + { + while (++j < z) + { + // try smaller tables up to z bits + if ((f <<= 1) <= c[++xp]) + break; // enough codes to use up j bits + f -= c[xp]; // else deduct codes from patterns + } + } + } + z = 1 << j; // table entries for j-bit table + + // allocate new table + if (hn[0] + z > MANY) + { + // (note: doesn't matter for fixed) + return Z_DATA_ERROR; // overflow of MANY + } + u[h] = q = hn[0]; // DEBUG + hn[0] += z; + + // connect to last table, if there is one + if (h != 0) + { + x[h] = i; // save pattern for backing up + r[0] = (sbyte) j; // bits in this table + r[1] = (sbyte) l; // bits to dump before this table + j = SharedUtils.URShift(i, (w - l)); + r[2] = (int) (q - u[h - 1] - j); // offset to this table + Array.Copy(r, 0, hp, (u[h - 1] + j) * 3, 3); // connect to last table + } + else + { + t[0] = q; // first table is returned result + } + } + + // set up table entry in r + r[1] = (sbyte) (k - w); + if (p >= n) + { + r[0] = 128 + 64; // out of values--invalid code + } + else if (v[p] < s) + { + r[0] = (sbyte) (v[p] < 256?0:32 + 64); // 256 is end-of-block + r[2] = v[p++]; // simple code is just the value + } + else + { + r[0] = (sbyte) (e[v[p] - s] + 16 + 64); // non-simple--look up in lists + r[2] = d[v[p++] - s]; + } + + // fill code-like entries with r + f = 1 << (k - w); + for (j = SharedUtils.URShift(i, w); j < z; j += f) + { + Array.Copy(r, 0, hp, (q + j) * 3, 3); + } + + // backwards increment the k-bit code i + for (j = 1 << (k - 1); (i & j) != 0; j = SharedUtils.URShift(j, 1)) + { + i ^= j; + } + i ^= j; + + // backup over finished tables + mask = (1 << w) - 1; // needed on HP, cc -O bug + while ((i & mask) != x[h]) + { + h--; // don't need to update q + w -= l; + mask = (1 << w) - 1; + } + } + } + // Return Z_BUF_ERROR if we were given an incomplete table + return y != 0 && g != 1?Z_BUF_ERROR:Z_OK; + } + + internal int inflate_trees_bits(int[] c, int[] bb, int[] tb, int[] hp, ZlibCodec z) + { + int result; + initWorkArea(19); + hn[0] = 0; + result = huft_build(c, 0, 19, 19, null, null, tb, bb, hp, hn, v); + + if (result == Z_DATA_ERROR) + { + z.Message = "oversubscribed dynamic bit lengths tree"; + } + else if (result == Z_BUF_ERROR || bb[0] == 0) + { + z.Message = "incomplete dynamic bit lengths tree"; + result = Z_DATA_ERROR; + } + return result; + } + + internal int inflate_trees_dynamic(int nl, int nd, int[] c, int[] bl, int[] bd, int[] tl, int[] td, int[] hp, ZlibCodec z) + { + int result; + + // build literal/length tree + initWorkArea(288); + hn[0] = 0; + result = huft_build(c, 0, nl, 257, cplens, cplext, tl, bl, hp, hn, v); + if (result != Z_OK || bl[0] == 0) + { + if (result == Z_DATA_ERROR) + { + z.Message = "oversubscribed literal/length tree"; + } + else if (result != Z_MEM_ERROR) + { + z.Message = "incomplete literal/length tree"; + result = Z_DATA_ERROR; + } + return result; + } + + // build distance tree + initWorkArea(288); + result = huft_build(c, nl, nd, 0, cpdist, cpdext, td, bd, hp, hn, v); + + if (result != Z_OK || (bd[0] == 0 && nl > 257)) + { + if (result == Z_DATA_ERROR) + { + z.Message = "oversubscribed distance tree"; + } + else if (result == Z_BUF_ERROR) + { + z.Message = "incomplete distance tree"; + result = Z_DATA_ERROR; + } + else if (result != Z_MEM_ERROR) + { + z.Message = "empty distance tree with lengths"; + result = Z_DATA_ERROR; + } + return result; + } + + return Z_OK; + } + + internal static int inflate_trees_fixed(int[] bl, int[] bd, int[][] tl, int[][] td, ZlibCodec z) + { + bl[0] = fixed_bl; + bd[0] = fixed_bd; + tl[0] = fixed_tl; + td[0] = fixed_td; + return Z_OK; + } + + private void initWorkArea(int vsize) + { + if (hn == null) + { + hn = new int[1]; + v = new int[vsize]; + c = new int[BMAX + 1]; + r = new int[3]; + u = new int[BMAX]; + x = new int[BMAX + 1]; + } + else + { + if (v.Length < vsize) + { + v = new int[vsize]; + } + Array.Clear(v,0,vsize); + Array.Clear(c,0,BMAX+1); + r[0]=0; r[1]=0; r[2]=0; + // for(int i=0; i +// +// ------------------------------------------------------------------ +// +// This module defines classes for decompression. This code is derived +// from the jzlib implementation of zlib, but significantly modified. +// The object model is not the same, and many of the behaviors are +// different. Nonetheless, in keeping with the license for jzlib, I am +// reproducing the copyright to that code here. +// +// ------------------------------------------------------------------ +// +// Copyright (c) 2000,2001,2002,2003 ymnk, JCraft,Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// 1. Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// +// 2. Redistributions in binary form must reproduce the above copyright +// notice, this list of conditions and the following disclaimer in +// the documentation and/or other materials provided with the distribution. +// +// 3. The names of the authors may not be used to endorse or promote products +// derived from this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, +// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND +// FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JCRAFT, +// INC. OR ANY CONTRIBUTORS TO THIS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, +// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, +// OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +// EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// ----------------------------------------------------------------------- +// +// This program is based on zlib-1.1.3; credit to authors +// Jean-loup Gailly(jloup@gzip.org) and Mark Adler(madler@alumni.caltech.edu) +// and contributors of zlib. +// +// ----------------------------------------------------------------------- + + +using System; +namespace Ionic.Zlib +{ + sealed class InflateBlocks + { + private const int MANY = 1440; + + // Table for deflate from PKZIP's appnote.txt. + internal static readonly int[] border = new int[] + { 16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15 }; + + private enum InflateBlockMode + { + TYPE = 0, // get type bits (3, including end bit) + LENS = 1, // get lengths for stored + STORED = 2, // processing stored block + TABLE = 3, // get table lengths + BTREE = 4, // get bit lengths tree for a dynamic block + DTREE = 5, // get length, distance trees for a dynamic block + CODES = 6, // processing fixed or dynamic block + DRY = 7, // output remaining window bytes + DONE = 8, // finished last block, done + BAD = 9, // ot a data error--stuck here + } + + private InflateBlockMode mode; // current inflate_block mode + + internal int left; // if STORED, bytes left to copy + + internal int table; // table lengths (14 bits) + internal int index; // index into blens (or border) + internal int[] blens; // bit lengths of codes + internal int[] bb = new int[1]; // bit length tree depth + internal int[] tb = new int[1]; // bit length decoding tree + + internal InflateCodes codes = new InflateCodes(); // if CODES, current state + + internal int last; // true if this block is the last block + + internal ZlibCodec _codec; // pointer back to this zlib stream + + // mode independent information + internal int bitk; // bits in bit buffer + internal int bitb; // bit buffer + internal int[] hufts; // single malloc for tree space + internal byte[] window; // sliding window + internal int end; // one byte after sliding window + internal int readAt; // window read pointer + internal int writeAt; // window write pointer + internal System.Object checkfn; // check function + internal uint check; // check on output + + internal InfTree inftree = new InfTree(); + + internal InflateBlocks(ZlibCodec codec, System.Object checkfn, int w) + { + _codec = codec; + hufts = new int[MANY * 3]; + window = new byte[w]; + end = w; + this.checkfn = checkfn; + mode = InflateBlockMode.TYPE; + Reset(); + } + + internal uint Reset() + { + uint oldCheck = check; + mode = InflateBlockMode.TYPE; + bitk = 0; + bitb = 0; + readAt = writeAt = 0; + + if (checkfn != null) + _codec._Adler32 = check = Adler.Adler32(0, null, 0, 0); + return oldCheck; + } + + + internal int Process(int r) + { + int t; // temporary storage + int b; // bit buffer + int k; // bits in bit buffer + int p; // input data pointer + int n; // bytes available there + int q; // output window write pointer + int m; // bytes to end of window or read pointer + + // copy input/output information to locals (UPDATE macro restores) + + p = _codec.NextIn; + n = _codec.AvailableBytesIn; + b = bitb; + k = bitk; + + q = writeAt; + m = (int)(q < readAt ? readAt - q - 1 : end - q); + + + // process input based on current state + while (true) + { + switch (mode) + { + case InflateBlockMode.TYPE: + + while (k < (3)) + { + if (n != 0) + { + r = ZlibConstants.Z_OK; + } + else + { + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + + n--; + b |= (_codec.InputBuffer[p++] & 0xff) << k; + k += 8; + } + t = (int)(b & 7); + last = t & 1; + + switch ((uint)t >> 1) + { + case 0: // stored + b >>= 3; k -= (3); + t = k & 7; // go to byte boundary + b >>= t; k -= t; + mode = InflateBlockMode.LENS; // get length of stored block + break; + + case 1: // fixed + int[] bl = new int[1]; + int[] bd = new int[1]; + int[][] tl = new int[1][]; + int[][] td = new int[1][]; + InfTree.inflate_trees_fixed(bl, bd, tl, td, _codec); + codes.Init(bl[0], bd[0], tl[0], 0, td[0], 0); + b >>= 3; k -= 3; + mode = InflateBlockMode.CODES; + break; + + case 2: // dynamic + b >>= 3; k -= 3; + mode = InflateBlockMode.TABLE; + break; + + case 3: // illegal + b >>= 3; k -= 3; + mode = InflateBlockMode.BAD; + _codec.Message = "invalid block type"; + r = ZlibConstants.Z_DATA_ERROR; + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + break; + + case InflateBlockMode.LENS: + + while (k < (32)) + { + if (n != 0) + { + r = ZlibConstants.Z_OK; + } + else + { + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + ; + n--; + b |= (_codec.InputBuffer[p++] & 0xff) << k; + k += 8; + } + + if ( ( ((~b)>>16) & 0xffff) != (b & 0xffff)) + { + mode = InflateBlockMode.BAD; + _codec.Message = "invalid stored block lengths"; + r = ZlibConstants.Z_DATA_ERROR; + + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + left = (b & 0xffff); + b = k = 0; // dump bits + mode = left != 0 ? InflateBlockMode.STORED : (last != 0 ? InflateBlockMode.DRY : InflateBlockMode.TYPE); + break; + + case InflateBlockMode.STORED: + if (n == 0) + { + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + + if (m == 0) + { + if (q == end && readAt != 0) + { + q = 0; m = (int)(q < readAt ? readAt - q - 1 : end - q); + } + if (m == 0) + { + writeAt = q; + r = Flush(r); + q = writeAt; m = (int)(q < readAt ? readAt - q - 1 : end - q); + if (q == end && readAt != 0) + { + q = 0; m = (int)(q < readAt ? readAt - q - 1 : end - q); + } + if (m == 0) + { + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + } + } + r = ZlibConstants.Z_OK; + + t = left; + if (t > n) + t = n; + if (t > m) + t = m; + Array.Copy(_codec.InputBuffer, p, window, q, t); + p += t; n -= t; + q += t; m -= t; + if ((left -= t) != 0) + break; + mode = last != 0 ? InflateBlockMode.DRY : InflateBlockMode.TYPE; + break; + + case InflateBlockMode.TABLE: + + while (k < (14)) + { + if (n != 0) + { + r = ZlibConstants.Z_OK; + } + else + { + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + + n--; + b |= (_codec.InputBuffer[p++] & 0xff) << k; + k += 8; + } + + table = t = (b & 0x3fff); + if ((t & 0x1f) > 29 || ((t >> 5) & 0x1f) > 29) + { + mode = InflateBlockMode.BAD; + _codec.Message = "too many length or distance symbols"; + r = ZlibConstants.Z_DATA_ERROR; + + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + t = 258 + (t & 0x1f) + ((t >> 5) & 0x1f); + if (blens == null || blens.Length < t) + { + blens = new int[t]; + } + else + { + Array.Clear(blens, 0, t); + // for (int i = 0; i < t; i++) + // { + // blens[i] = 0; + // } + } + + b >>= 14; + k -= 14; + + + index = 0; + mode = InflateBlockMode.BTREE; + goto case InflateBlockMode.BTREE; + + case InflateBlockMode.BTREE: + while (index < 4 + (table >> 10)) + { + while (k < (3)) + { + if (n != 0) + { + r = ZlibConstants.Z_OK; + } + else + { + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + + n--; + b |= (_codec.InputBuffer[p++] & 0xff) << k; + k += 8; + } + + blens[border[index++]] = b & 7; + + b >>= 3; k -= 3; + } + + while (index < 19) + { + blens[border[index++]] = 0; + } + + bb[0] = 7; + t = inftree.inflate_trees_bits(blens, bb, tb, hufts, _codec); + if (t != ZlibConstants.Z_OK) + { + r = t; + if (r == ZlibConstants.Z_DATA_ERROR) + { + blens = null; + mode = InflateBlockMode.BAD; + } + + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + + index = 0; + mode = InflateBlockMode.DTREE; + goto case InflateBlockMode.DTREE; + + case InflateBlockMode.DTREE: + while (true) + { + t = table; + if (!(index < 258 + (t & 0x1f) + ((t >> 5) & 0x1f))) + { + break; + } + + int i, j, c; + + t = bb[0]; + + while (k < t) + { + if (n != 0) + { + r = ZlibConstants.Z_OK; + } + else + { + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + + n--; + b |= (_codec.InputBuffer[p++] & 0xff) << k; + k += 8; + } + + t = hufts[(tb[0] + (b & InternalInflateConstants.InflateMask[t])) * 3 + 1]; + c = hufts[(tb[0] + (b & InternalInflateConstants.InflateMask[t])) * 3 + 2]; + + if (c < 16) + { + b >>= t; k -= t; + blens[index++] = c; + } + else + { + // c == 16..18 + i = c == 18 ? 7 : c - 14; + j = c == 18 ? 11 : 3; + + while (k < (t + i)) + { + if (n != 0) + { + r = ZlibConstants.Z_OK; + } + else + { + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + + n--; + b |= (_codec.InputBuffer[p++] & 0xff) << k; + k += 8; + } + + b >>= t; k -= t; + + j += (b & InternalInflateConstants.InflateMask[i]); + + b >>= i; k -= i; + + i = index; + t = table; + if (i + j > 258 + (t & 0x1f) + ((t >> 5) & 0x1f) || (c == 16 && i < 1)) + { + blens = null; + mode = InflateBlockMode.BAD; + _codec.Message = "invalid bit length repeat"; + r = ZlibConstants.Z_DATA_ERROR; + + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + + c = (c == 16) ? blens[i-1] : 0; + do + { + blens[i++] = c; + } + while (--j != 0); + index = i; + } + } + + tb[0] = -1; + { + int[] bl = new int[] { 9 }; // must be <= 9 for lookahead assumptions + int[] bd = new int[] { 6 }; // must be <= 9 for lookahead assumptions + int[] tl = new int[1]; + int[] td = new int[1]; + + t = table; + t = inftree.inflate_trees_dynamic(257 + (t & 0x1f), 1 + ((t >> 5) & 0x1f), blens, bl, bd, tl, td, hufts, _codec); + + if (t != ZlibConstants.Z_OK) + { + if (t == ZlibConstants.Z_DATA_ERROR) + { + blens = null; + mode = InflateBlockMode.BAD; + } + r = t; + + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + codes.Init(bl[0], bd[0], hufts, tl[0], hufts, td[0]); + } + mode = InflateBlockMode.CODES; + goto case InflateBlockMode.CODES; + + case InflateBlockMode.CODES: + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + + r = codes.Process(this, r); + if (r != ZlibConstants.Z_STREAM_END) + { + return Flush(r); + } + + r = ZlibConstants.Z_OK; + p = _codec.NextIn; + n = _codec.AvailableBytesIn; + b = bitb; + k = bitk; + q = writeAt; + m = (int)(q < readAt ? readAt - q - 1 : end - q); + + if (last == 0) + { + mode = InflateBlockMode.TYPE; + break; + } + mode = InflateBlockMode.DRY; + goto case InflateBlockMode.DRY; + + case InflateBlockMode.DRY: + writeAt = q; + r = Flush(r); + q = writeAt; m = (int)(q < readAt ? readAt - q - 1 : end - q); + if (readAt != writeAt) + { + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + mode = InflateBlockMode.DONE; + goto case InflateBlockMode.DONE; + + case InflateBlockMode.DONE: + r = ZlibConstants.Z_STREAM_END; + bitb = b; + bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + + case InflateBlockMode.BAD: + r = ZlibConstants.Z_DATA_ERROR; + + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + + + default: + r = ZlibConstants.Z_STREAM_ERROR; + + bitb = b; bitk = k; + _codec.AvailableBytesIn = n; + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + writeAt = q; + return Flush(r); + } + } + } + + + internal void Free() + { + Reset(); + window = null; + hufts = null; + } + + internal void SetDictionary(byte[] d, int start, int n) + { + Array.Copy(d, start, window, 0, n); + readAt = writeAt = n; + } + + // Returns true if inflate is currently at the end of a block generated + // by Z_SYNC_FLUSH or Z_FULL_FLUSH. + internal int SyncPoint() + { + return mode == InflateBlockMode.LENS ? 1 : 0; + } + + // copy as much as possible from the sliding window to the output area + internal int Flush(int r) + { + int nBytes; + + for (int pass=0; pass < 2; pass++) + { + if (pass==0) + { + // compute number of bytes to copy as far as end of window + nBytes = (int)((readAt <= writeAt ? writeAt : end) - readAt); + } + else + { + // compute bytes to copy + nBytes = writeAt - readAt; + } + + // workitem 8870 + if (nBytes == 0) + { + if (r == ZlibConstants.Z_BUF_ERROR) + r = ZlibConstants.Z_OK; + return r; + } + + if (nBytes > _codec.AvailableBytesOut) + nBytes = _codec.AvailableBytesOut; + + if (nBytes != 0 && r == ZlibConstants.Z_BUF_ERROR) + r = ZlibConstants.Z_OK; + + // update counters + _codec.AvailableBytesOut -= nBytes; + _codec.TotalBytesOut += nBytes; + + // update check information + if (checkfn != null) + _codec._Adler32 = check = Adler.Adler32(check, window, readAt, nBytes); + + // copy as far as end of window + Array.Copy(window, readAt, _codec.OutputBuffer, _codec.NextOut, nBytes); + _codec.NextOut += nBytes; + readAt += nBytes; + + // see if more to copy at beginning of window + if (readAt == end && pass == 0) + { + // wrap pointers + readAt = 0; + if (writeAt == end) + writeAt = 0; + } + else pass++; + } + + // done + return r; + } + } + + + internal static class InternalInflateConstants + { + // And'ing with mask[n] masks the lower n bits + internal static readonly int[] InflateMask = new int[] { + 0x00000000, 0x00000001, 0x00000003, 0x00000007, + 0x0000000f, 0x0000001f, 0x0000003f, 0x0000007f, + 0x000000ff, 0x000001ff, 0x000003ff, 0x000007ff, + 0x00000fff, 0x00001fff, 0x00003fff, 0x00007fff, 0x0000ffff }; + } + + + sealed class InflateCodes + { + // waiting for "i:"=input, + // "o:"=output, + // "x:"=nothing + private const int START = 0; // x: set up for LEN + private const int LEN = 1; // i: get length/literal/eob next + private const int LENEXT = 2; // i: getting length extra (have base) + private const int DIST = 3; // i: get distance next + private const int DISTEXT = 4; // i: getting distance extra + private const int COPY = 5; // o: copying bytes in window, waiting for space + private const int LIT = 6; // o: got literal, waiting for output space + private const int WASH = 7; // o: got eob, possibly still output waiting + private const int END = 8; // x: got eob and all data flushed + private const int BADCODE = 9; // x: got error + + internal int mode; // current inflate_codes mode + + // mode dependent information + internal int len; + + internal int[] tree; // pointer into tree + internal int tree_index = 0; + internal int need; // bits needed + + internal int lit; + + // if EXT or COPY, where and how much + internal int bitsToGet; // bits to get for extra + internal int dist; // distance back to copy from + + internal byte lbits; // ltree bits decoded per branch + internal byte dbits; // dtree bits decoder per branch + internal int[] ltree; // literal/length/eob tree + internal int ltree_index; // literal/length/eob tree + internal int[] dtree; // distance tree + internal int dtree_index; // distance tree + + internal InflateCodes() + { + } + + internal void Init(int bl, int bd, int[] tl, int tl_index, int[] td, int td_index) + { + mode = START; + lbits = (byte)bl; + dbits = (byte)bd; + ltree = tl; + ltree_index = tl_index; + dtree = td; + dtree_index = td_index; + tree = null; + } + + internal int Process(InflateBlocks blocks, int r) + { + int j; // temporary storage + int tindex; // temporary pointer + int e; // extra bits or operation + int b = 0; // bit buffer + int k = 0; // bits in bit buffer + int p = 0; // input data pointer + int n; // bytes available there + int q; // output window write pointer + int m; // bytes to end of window or read pointer + int f; // pointer to copy strings from + + ZlibCodec z = blocks._codec; + + // copy input/output information to locals (UPDATE macro restores) + p = z.NextIn; + n = z.AvailableBytesIn; + b = blocks.bitb; + k = blocks.bitk; + q = blocks.writeAt; m = q < blocks.readAt ? blocks.readAt - q - 1 : blocks.end - q; + + // process input and output based on current state + while (true) + { + switch (mode) + { + // waiting for "i:"=input, "o:"=output, "x:"=nothing + case START: // x: set up for LEN + if (m >= 258 && n >= 10) + { + blocks.bitb = b; blocks.bitk = k; + z.AvailableBytesIn = n; + z.TotalBytesIn += p - z.NextIn; + z.NextIn = p; + blocks.writeAt = q; + r = InflateFast(lbits, dbits, ltree, ltree_index, dtree, dtree_index, blocks, z); + + p = z.NextIn; + n = z.AvailableBytesIn; + b = blocks.bitb; + k = blocks.bitk; + q = blocks.writeAt; m = q < blocks.readAt ? blocks.readAt - q - 1 : blocks.end - q; + + if (r != ZlibConstants.Z_OK) + { + mode = (r == ZlibConstants.Z_STREAM_END) ? WASH : BADCODE; + break; + } + } + need = lbits; + tree = ltree; + tree_index = ltree_index; + + mode = LEN; + goto case LEN; + + case LEN: // i: get length/literal/eob next + j = need; + + while (k < j) + { + if (n != 0) + r = ZlibConstants.Z_OK; + else + { + blocks.bitb = b; blocks.bitk = k; + z.AvailableBytesIn = n; + z.TotalBytesIn += p - z.NextIn; + z.NextIn = p; + blocks.writeAt = q; + return blocks.Flush(r); + } + n--; + b |= (z.InputBuffer[p++] & 0xff) << k; + k += 8; + } + + tindex = (tree_index + (b & InternalInflateConstants.InflateMask[j])) * 3; + + b >>= (tree[tindex + 1]); + k -= (tree[tindex + 1]); + + e = tree[tindex]; + + if (e == 0) + { + // literal + lit = tree[tindex + 2]; + mode = LIT; + break; + } + if ((e & 16) != 0) + { + // length + bitsToGet = e & 15; + len = tree[tindex + 2]; + mode = LENEXT; + break; + } + if ((e & 64) == 0) + { + // next table + need = e; + tree_index = tindex / 3 + tree[tindex + 2]; + break; + } + if ((e & 32) != 0) + { + // end of block + mode = WASH; + break; + } + mode = BADCODE; // invalid code + z.Message = "invalid literal/length code"; + r = ZlibConstants.Z_DATA_ERROR; + + blocks.bitb = b; blocks.bitk = k; + z.AvailableBytesIn = n; + z.TotalBytesIn += p - z.NextIn; + z.NextIn = p; + blocks.writeAt = q; + return blocks.Flush(r); + + + case LENEXT: // i: getting length extra (have base) + j = bitsToGet; + + while (k < j) + { + if (n != 0) + r = ZlibConstants.Z_OK; + else + { + blocks.bitb = b; blocks.bitk = k; + z.AvailableBytesIn = n; z.TotalBytesIn += p - z.NextIn; z.NextIn = p; + blocks.writeAt = q; + return blocks.Flush(r); + } + n--; b |= (z.InputBuffer[p++] & 0xff) << k; + k += 8; + } + + len += (b & InternalInflateConstants.InflateMask[j]); + + b >>= j; + k -= j; + + need = dbits; + tree = dtree; + tree_index = dtree_index; + mode = DIST; + goto case DIST; + + case DIST: // i: get distance next + j = need; + + while (k < j) + { + if (n != 0) + r = ZlibConstants.Z_OK; + else + { + blocks.bitb = b; blocks.bitk = k; + z.AvailableBytesIn = n; z.TotalBytesIn += p - z.NextIn; z.NextIn = p; + blocks.writeAt = q; + return blocks.Flush(r); + } + n--; b |= (z.InputBuffer[p++] & 0xff) << k; + k += 8; + } + + tindex = (tree_index + (b & InternalInflateConstants.InflateMask[j])) * 3; + + b >>= tree[tindex + 1]; + k -= tree[tindex + 1]; + + e = (tree[tindex]); + if ((e & 0x10) != 0) + { + // distance + bitsToGet = e & 15; + dist = tree[tindex + 2]; + mode = DISTEXT; + break; + } + if ((e & 64) == 0) + { + // next table + need = e; + tree_index = tindex / 3 + tree[tindex + 2]; + break; + } + mode = BADCODE; // invalid code + z.Message = "invalid distance code"; + r = ZlibConstants.Z_DATA_ERROR; + + blocks.bitb = b; blocks.bitk = k; + z.AvailableBytesIn = n; z.TotalBytesIn += p - z.NextIn; z.NextIn = p; + blocks.writeAt = q; + return blocks.Flush(r); + + + case DISTEXT: // i: getting distance extra + j = bitsToGet; + + while (k < j) + { + if (n != 0) + r = ZlibConstants.Z_OK; + else + { + blocks.bitb = b; blocks.bitk = k; + z.AvailableBytesIn = n; z.TotalBytesIn += p - z.NextIn; z.NextIn = p; + blocks.writeAt = q; + return blocks.Flush(r); + } + n--; b |= (z.InputBuffer[p++] & 0xff) << k; + k += 8; + } + + dist += (b & InternalInflateConstants.InflateMask[j]); + + b >>= j; + k -= j; + + mode = COPY; + goto case COPY; + + case COPY: // o: copying bytes in window, waiting for space + f = q - dist; + while (f < 0) + { + // modulo window size-"while" instead + f += blocks.end; // of "if" handles invalid distances + } + while (len != 0) + { + if (m == 0) + { + if (q == blocks.end && blocks.readAt != 0) + { + q = 0; m = q < blocks.readAt ? blocks.readAt - q - 1 : blocks.end - q; + } + if (m == 0) + { + blocks.writeAt = q; r = blocks.Flush(r); + q = blocks.writeAt; m = q < blocks.readAt ? blocks.readAt - q - 1 : blocks.end - q; + + if (q == blocks.end && blocks.readAt != 0) + { + q = 0; m = q < blocks.readAt ? blocks.readAt - q - 1 : blocks.end - q; + } + + if (m == 0) + { + blocks.bitb = b; blocks.bitk = k; + z.AvailableBytesIn = n; + z.TotalBytesIn += p - z.NextIn; + z.NextIn = p; + blocks.writeAt = q; + return blocks.Flush(r); + } + } + } + + blocks.window[q++] = blocks.window[f++]; m--; + + if (f == blocks.end) + f = 0; + len--; + } + mode = START; + break; + + case LIT: // o: got literal, waiting for output space + if (m == 0) + { + if (q == blocks.end && blocks.readAt != 0) + { + q = 0; m = q < blocks.readAt ? blocks.readAt - q - 1 : blocks.end - q; + } + if (m == 0) + { + blocks.writeAt = q; r = blocks.Flush(r); + q = blocks.writeAt; m = q < blocks.readAt ? blocks.readAt - q - 1 : blocks.end - q; + + if (q == blocks.end && blocks.readAt != 0) + { + q = 0; m = q < blocks.readAt ? blocks.readAt - q - 1 : blocks.end - q; + } + if (m == 0) + { + blocks.bitb = b; blocks.bitk = k; + z.AvailableBytesIn = n; z.TotalBytesIn += p - z.NextIn; z.NextIn = p; + blocks.writeAt = q; + return blocks.Flush(r); + } + } + } + r = ZlibConstants.Z_OK; + + blocks.window[q++] = (byte)lit; m--; + + mode = START; + break; + + case WASH: // o: got eob, possibly more output + if (k > 7) + { + // return unused byte, if any + k -= 8; + n++; + p--; // can always return one + } + + blocks.writeAt = q; r = blocks.Flush(r); + q = blocks.writeAt; m = q < blocks.readAt ? blocks.readAt - q - 1 : blocks.end - q; + + if (blocks.readAt != blocks.writeAt) + { + blocks.bitb = b; blocks.bitk = k; + z.AvailableBytesIn = n; z.TotalBytesIn += p - z.NextIn; z.NextIn = p; + blocks.writeAt = q; + return blocks.Flush(r); + } + mode = END; + goto case END; + + case END: + r = ZlibConstants.Z_STREAM_END; + blocks.bitb = b; blocks.bitk = k; + z.AvailableBytesIn = n; z.TotalBytesIn += p - z.NextIn; z.NextIn = p; + blocks.writeAt = q; + return blocks.Flush(r); + + case BADCODE: // x: got error + + r = ZlibConstants.Z_DATA_ERROR; + + blocks.bitb = b; blocks.bitk = k; + z.AvailableBytesIn = n; z.TotalBytesIn += p - z.NextIn; z.NextIn = p; + blocks.writeAt = q; + return blocks.Flush(r); + + default: + r = ZlibConstants.Z_STREAM_ERROR; + + blocks.bitb = b; blocks.bitk = k; + z.AvailableBytesIn = n; z.TotalBytesIn += p - z.NextIn; z.NextIn = p; + blocks.writeAt = q; + return blocks.Flush(r); + } + } + } + + + // Called with number of bytes left to write in window at least 258 + // (the maximum string length) and number of input bytes available + // at least ten. The ten bytes are six bytes for the longest length/ + // distance pair plus four bytes for overloading the bit buffer. + + internal int InflateFast(int bl, int bd, int[] tl, int tl_index, int[] td, int td_index, InflateBlocks s, ZlibCodec z) + { + int t; // temporary pointer + int[] tp; // temporary pointer + int tp_index; // temporary pointer + int e; // extra bits or operation + int b; // bit buffer + int k; // bits in bit buffer + int p; // input data pointer + int n; // bytes available there + int q; // output window write pointer + int m; // bytes to end of window or read pointer + int ml; // mask for literal/length tree + int md; // mask for distance tree + int c; // bytes to copy + int d; // distance back to copy from + int r; // copy source pointer + + int tp_index_t_3; // (tp_index+t)*3 + + // load input, output, bit values + p = z.NextIn; n = z.AvailableBytesIn; b = s.bitb; k = s.bitk; + q = s.writeAt; m = q < s.readAt ? s.readAt - q - 1 : s.end - q; + + // initialize masks + ml = InternalInflateConstants.InflateMask[bl]; + md = InternalInflateConstants.InflateMask[bd]; + + // do until not enough input or output space for fast loop + do + { + // assume called with m >= 258 && n >= 10 + // get literal/length code + while (k < (20)) + { + // max bits for literal/length code + n--; + b |= (z.InputBuffer[p++] & 0xff) << k; k += 8; + } + + t = b & ml; + tp = tl; + tp_index = tl_index; + tp_index_t_3 = (tp_index + t) * 3; + if ((e = tp[tp_index_t_3]) == 0) + { + b >>= (tp[tp_index_t_3 + 1]); k -= (tp[tp_index_t_3 + 1]); + + s.window[q++] = (byte)tp[tp_index_t_3 + 2]; + m--; + continue; + } + do + { + + b >>= (tp[tp_index_t_3 + 1]); k -= (tp[tp_index_t_3 + 1]); + + if ((e & 16) != 0) + { + e &= 15; + c = tp[tp_index_t_3 + 2] + ((int)b & InternalInflateConstants.InflateMask[e]); + + b >>= e; k -= e; + + // decode distance base of block to copy + while (k < 15) + { + // max bits for distance code + n--; + b |= (z.InputBuffer[p++] & 0xff) << k; k += 8; + } + + t = b & md; + tp = td; + tp_index = td_index; + tp_index_t_3 = (tp_index + t) * 3; + e = tp[tp_index_t_3]; + + do + { + + b >>= (tp[tp_index_t_3 + 1]); k -= (tp[tp_index_t_3 + 1]); + + if ((e & 16) != 0) + { + // get extra bits to add to distance base + e &= 15; + while (k < e) + { + // get extra bits (up to 13) + n--; + b |= (z.InputBuffer[p++] & 0xff) << k; k += 8; + } + + d = tp[tp_index_t_3 + 2] + (b & InternalInflateConstants.InflateMask[e]); + + b >>= e; k -= e; + + // do the copy + m -= c; + if (q >= d) + { + // offset before dest + // just copy + r = q - d; + if (q - r > 0 && 2 > (q - r)) + { + s.window[q++] = s.window[r++]; // minimum count is three, + s.window[q++] = s.window[r++]; // so unroll loop a little + c -= 2; + } + else + { + Array.Copy(s.window, r, s.window, q, 2); + q += 2; r += 2; c -= 2; + } + } + else + { + // else offset after destination + r = q - d; + do + { + r += s.end; // force pointer in window + } + while (r < 0); // covers invalid distances + e = s.end - r; + if (c > e) + { + // if source crosses, + c -= e; // wrapped copy + if (q - r > 0 && e > (q - r)) + { + do + { + s.window[q++] = s.window[r++]; + } + while (--e != 0); + } + else + { + Array.Copy(s.window, r, s.window, q, e); + q += e; r += e; e = 0; + } + r = 0; // copy rest from start of window + } + } + + // copy all or what's left + if (q - r > 0 && c > (q - r)) + { + do + { + s.window[q++] = s.window[r++]; + } + while (--c != 0); + } + else + { + Array.Copy(s.window, r, s.window, q, c); + q += c; r += c; c = 0; + } + break; + } + else if ((e & 64) == 0) + { + t += tp[tp_index_t_3 + 2]; + t += (b & InternalInflateConstants.InflateMask[e]); + tp_index_t_3 = (tp_index + t) * 3; + e = tp[tp_index_t_3]; + } + else + { + z.Message = "invalid distance code"; + + c = z.AvailableBytesIn - n; c = (k >> 3) < c ? k >> 3 : c; n += c; p -= c; k -= (c << 3); + + s.bitb = b; s.bitk = k; + z.AvailableBytesIn = n; z.TotalBytesIn += p - z.NextIn; z.NextIn = p; + s.writeAt = q; + + return ZlibConstants.Z_DATA_ERROR; + } + } + while (true); + break; + } + + if ((e & 64) == 0) + { + t += tp[tp_index_t_3 + 2]; + t += (b & InternalInflateConstants.InflateMask[e]); + tp_index_t_3 = (tp_index + t) * 3; + if ((e = tp[tp_index_t_3]) == 0) + { + b >>= (tp[tp_index_t_3 + 1]); k -= (tp[tp_index_t_3 + 1]); + s.window[q++] = (byte)tp[tp_index_t_3 + 2]; + m--; + break; + } + } + else if ((e & 32) != 0) + { + c = z.AvailableBytesIn - n; c = (k >> 3) < c ? k >> 3 : c; n += c; p -= c; k -= (c << 3); + + s.bitb = b; s.bitk = k; + z.AvailableBytesIn = n; z.TotalBytesIn += p - z.NextIn; z.NextIn = p; + s.writeAt = q; + + return ZlibConstants.Z_STREAM_END; + } + else + { + z.Message = "invalid literal/length code"; + + c = z.AvailableBytesIn - n; c = (k >> 3) < c ? k >> 3 : c; n += c; p -= c; k -= (c << 3); + + s.bitb = b; s.bitk = k; + z.AvailableBytesIn = n; z.TotalBytesIn += p - z.NextIn; z.NextIn = p; + s.writeAt = q; + + return ZlibConstants.Z_DATA_ERROR; + } + } + while (true); + } + while (m >= 258 && n >= 10); + + // not enough input or output--restore pointers and return + c = z.AvailableBytesIn - n; c = (k >> 3) < c ? k >> 3 : c; n += c; p -= c; k -= (c << 3); + + s.bitb = b; s.bitk = k; + z.AvailableBytesIn = n; z.TotalBytesIn += p - z.NextIn; z.NextIn = p; + s.writeAt = q; + + return ZlibConstants.Z_OK; + } + } + + + internal sealed class InflateManager + { + // preset dictionary flag in zlib header + private const int PRESET_DICT = 0x20; + + private const int Z_DEFLATED = 8; + + private enum InflateManagerMode + { + METHOD = 0, // waiting for method byte + FLAG = 1, // waiting for flag byte + DICT4 = 2, // four dictionary check bytes to go + DICT3 = 3, // three dictionary check bytes to go + DICT2 = 4, // two dictionary check bytes to go + DICT1 = 5, // one dictionary check byte to go + DICT0 = 6, // waiting for inflateSetDictionary + BLOCKS = 7, // decompressing blocks + CHECK4 = 8, // four check bytes to go + CHECK3 = 9, // three check bytes to go + CHECK2 = 10, // two check bytes to go + CHECK1 = 11, // one check byte to go + DONE = 12, // finished check, done + BAD = 13, // got an error--stay here + } + + private InflateManagerMode mode; // current inflate mode + internal ZlibCodec _codec; // pointer back to this zlib stream + + // mode dependent information + internal int method; // if FLAGS, method byte + + // if CHECK, check values to compare + internal uint computedCheck; // computed check value + internal uint expectedCheck; // stream check value + + // if BAD, inflateSync's marker bytes count + internal int marker; + + // mode independent information + //internal int nowrap; // flag for no wrapper + private bool _handleRfc1950HeaderBytes = true; + internal bool HandleRfc1950HeaderBytes + { + get { return _handleRfc1950HeaderBytes; } + set { _handleRfc1950HeaderBytes = value; } + } + internal int wbits; // log2(window size) (8..15, defaults to 15) + + internal InflateBlocks blocks; // current inflate_blocks state + + public InflateManager() { } + + public InflateManager(bool expectRfc1950HeaderBytes) + { + _handleRfc1950HeaderBytes = expectRfc1950HeaderBytes; + } + + internal int Reset() + { + _codec.TotalBytesIn = _codec.TotalBytesOut = 0; + _codec.Message = null; + mode = HandleRfc1950HeaderBytes ? InflateManagerMode.METHOD : InflateManagerMode.BLOCKS; + blocks.Reset(); + return ZlibConstants.Z_OK; + } + + internal int End() + { + if (blocks != null) + blocks.Free(); + blocks = null; + return ZlibConstants.Z_OK; + } + + internal int Initialize(ZlibCodec codec, int w) + { + _codec = codec; + _codec.Message = null; + blocks = null; + + // handle undocumented nowrap option (no zlib header or check) + //nowrap = 0; + //if (w < 0) + //{ + // w = - w; + // nowrap = 1; + //} + + // set window size + if (w < 8 || w > 15) + { + End(); + throw new ZlibException("Bad window size."); + + //return ZlibConstants.Z_STREAM_ERROR; + } + wbits = w; + + blocks = new InflateBlocks(codec, + HandleRfc1950HeaderBytes ? this : null, + 1 << w); + + // reset state + Reset(); + return ZlibConstants.Z_OK; + } + + + internal int Inflate(FlushType flush) + { + int b; + + if (_codec.InputBuffer == null) + throw new ZlibException("InputBuffer is null. "); + +// int f = (flush == FlushType.Finish) +// ? ZlibConstants.Z_BUF_ERROR +// : ZlibConstants.Z_OK; + + // workitem 8870 + int f = ZlibConstants.Z_OK; + int r = ZlibConstants.Z_BUF_ERROR; + + while (true) + { + switch (mode) + { + case InflateManagerMode.METHOD: + if (_codec.AvailableBytesIn == 0) return r; + r = f; + _codec.AvailableBytesIn--; + _codec.TotalBytesIn++; + if (((method = _codec.InputBuffer[_codec.NextIn++]) & 0xf) != Z_DEFLATED) + { + mode = InflateManagerMode.BAD; + _codec.Message = String.Format("unknown compression method (0x{0:X2})", method); + marker = 5; // can't try inflateSync + break; + } + if ((method >> 4) + 8 > wbits) + { + mode = InflateManagerMode.BAD; + _codec.Message = String.Format("invalid window size ({0})", (method >> 4) + 8); + marker = 5; // can't try inflateSync + break; + } + mode = InflateManagerMode.FLAG; + break; + + + case InflateManagerMode.FLAG: + if (_codec.AvailableBytesIn == 0) return r; + r = f; + _codec.AvailableBytesIn--; + _codec.TotalBytesIn++; + b = (_codec.InputBuffer[_codec.NextIn++]) & 0xff; + + if ((((method << 8) + b) % 31) != 0) + { + mode = InflateManagerMode.BAD; + _codec.Message = "incorrect header check"; + marker = 5; // can't try inflateSync + break; + } + + mode = ((b & PRESET_DICT) == 0) + ? InflateManagerMode.BLOCKS + : InflateManagerMode.DICT4; + break; + + case InflateManagerMode.DICT4: + if (_codec.AvailableBytesIn == 0) return r; + r = f; + _codec.AvailableBytesIn--; + _codec.TotalBytesIn++; + expectedCheck = (uint)((_codec.InputBuffer[_codec.NextIn++] << 24) & 0xff000000); + mode = InflateManagerMode.DICT3; + break; + + case InflateManagerMode.DICT3: + if (_codec.AvailableBytesIn == 0) return r; + r = f; + _codec.AvailableBytesIn--; + _codec.TotalBytesIn++; + expectedCheck += (uint)((_codec.InputBuffer[_codec.NextIn++] << 16) & 0x00ff0000); + mode = InflateManagerMode.DICT2; + break; + + case InflateManagerMode.DICT2: + + if (_codec.AvailableBytesIn == 0) return r; + r = f; + _codec.AvailableBytesIn--; + _codec.TotalBytesIn++; + expectedCheck += (uint)((_codec.InputBuffer[_codec.NextIn++] << 8) & 0x0000ff00); + mode = InflateManagerMode.DICT1; + break; + + + case InflateManagerMode.DICT1: + if (_codec.AvailableBytesIn == 0) return r; + r = f; + _codec.AvailableBytesIn--; _codec.TotalBytesIn++; + expectedCheck += (uint)(_codec.InputBuffer[_codec.NextIn++] & 0x000000ff); + _codec._Adler32 = expectedCheck; + mode = InflateManagerMode.DICT0; + return ZlibConstants.Z_NEED_DICT; + + + case InflateManagerMode.DICT0: + mode = InflateManagerMode.BAD; + _codec.Message = "need dictionary"; + marker = 0; // can try inflateSync + return ZlibConstants.Z_STREAM_ERROR; + + + case InflateManagerMode.BLOCKS: + r = blocks.Process(r); + if (r == ZlibConstants.Z_DATA_ERROR) + { + mode = InflateManagerMode.BAD; + marker = 0; // can try inflateSync + break; + } + + if (r == ZlibConstants.Z_OK) r = f; + + if (r != ZlibConstants.Z_STREAM_END) + return r; + + r = f; + computedCheck = blocks.Reset(); + if (!HandleRfc1950HeaderBytes) + { + mode = InflateManagerMode.DONE; + return ZlibConstants.Z_STREAM_END; + } + mode = InflateManagerMode.CHECK4; + break; + + case InflateManagerMode.CHECK4: + if (_codec.AvailableBytesIn == 0) return r; + r = f; + _codec.AvailableBytesIn--; + _codec.TotalBytesIn++; + expectedCheck = (uint)((_codec.InputBuffer[_codec.NextIn++] << 24) & 0xff000000); + mode = InflateManagerMode.CHECK3; + break; + + case InflateManagerMode.CHECK3: + if (_codec.AvailableBytesIn == 0) return r; + r = f; + _codec.AvailableBytesIn--; _codec.TotalBytesIn++; + expectedCheck += (uint)((_codec.InputBuffer[_codec.NextIn++] << 16) & 0x00ff0000); + mode = InflateManagerMode.CHECK2; + break; + + case InflateManagerMode.CHECK2: + if (_codec.AvailableBytesIn == 0) return r; + r = f; + _codec.AvailableBytesIn--; + _codec.TotalBytesIn++; + expectedCheck += (uint)((_codec.InputBuffer[_codec.NextIn++] << 8) & 0x0000ff00); + mode = InflateManagerMode.CHECK1; + break; + + case InflateManagerMode.CHECK1: + if (_codec.AvailableBytesIn == 0) return r; + r = f; + _codec.AvailableBytesIn--; _codec.TotalBytesIn++; + expectedCheck += (uint)(_codec.InputBuffer[_codec.NextIn++] & 0x000000ff); + if (computedCheck != expectedCheck) + { + mode = InflateManagerMode.BAD; + _codec.Message = "incorrect data check"; + marker = 5; // can't try inflateSync + break; + } + mode = InflateManagerMode.DONE; + return ZlibConstants.Z_STREAM_END; + + case InflateManagerMode.DONE: + return ZlibConstants.Z_STREAM_END; + + case InflateManagerMode.BAD: + throw new ZlibException(String.Format("Bad state ({0})", _codec.Message)); + + default: + throw new ZlibException("Stream error."); + + } + } + } + + + + internal int SetDictionary(byte[] dictionary) + { + int index = 0; + int length = dictionary.Length; + if (mode != InflateManagerMode.DICT0) + throw new ZlibException("Stream error."); + + if (Adler.Adler32(1, dictionary, 0, dictionary.Length) != _codec._Adler32) + { + return ZlibConstants.Z_DATA_ERROR; + } + + _codec._Adler32 = Adler.Adler32(0, null, 0, 0); + + if (length >= (1 << wbits)) + { + length = (1 << wbits) - 1; + index = dictionary.Length - length; + } + blocks.SetDictionary(dictionary, index, length); + mode = InflateManagerMode.BLOCKS; + return ZlibConstants.Z_OK; + } + + + private static readonly byte[] mark = new byte[] { 0, 0, 0xff, 0xff }; + + internal int Sync() + { + int n; // number of bytes to look at + int p; // pointer to bytes + int m; // number of marker bytes found in a row + long r, w; // temporaries to save total_in and total_out + + // set up + if (mode != InflateManagerMode.BAD) + { + mode = InflateManagerMode.BAD; + marker = 0; + } + if ((n = _codec.AvailableBytesIn) == 0) + return ZlibConstants.Z_BUF_ERROR; + p = _codec.NextIn; + m = marker; + + // search + while (n != 0 && m < 4) + { + if (_codec.InputBuffer[p] == mark[m]) + { + m++; + } + else if (_codec.InputBuffer[p] != 0) + { + m = 0; + } + else + { + m = 4 - m; + } + p++; n--; + } + + // restore + _codec.TotalBytesIn += p - _codec.NextIn; + _codec.NextIn = p; + _codec.AvailableBytesIn = n; + marker = m; + + // return no joy or set up to restart on a new block + if (m != 4) + { + return ZlibConstants.Z_DATA_ERROR; + } + r = _codec.TotalBytesIn; + w = _codec.TotalBytesOut; + Reset(); + _codec.TotalBytesIn = r; + _codec.TotalBytesOut = w; + mode = InflateManagerMode.BLOCKS; + return ZlibConstants.Z_OK; + } + + + // Returns true if inflate is currently at the end of a block generated + // by Z_SYNC_FLUSH or Z_FULL_FLUSH. This function is used by one PPP + // implementation to provide an additional safety check. PPP uses Z_SYNC_FLUSH + // but removes the length bytes of the resulting empty stored block. When + // decompressing, PPP checks that at the end of input packet, inflate is + // waiting for these length bytes. + internal int SyncPoint(ZlibCodec z) + { + return blocks.SyncPoint(); + } + } +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/Zlib/ParallelDeflateOutputStream.cs b/Resources/Libraries/DotNetZip/Source/Zlib/ParallelDeflateOutputStream.cs new file mode 100644 index 00000000..8373983f --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zlib/ParallelDeflateOutputStream.cs @@ -0,0 +1,1386 @@ +//#define Trace + +// ParallelDeflateOutputStream.cs +// ------------------------------------------------------------------ +// +// A DeflateStream that does compression only, it uses a +// divide-and-conquer approach with multiple threads to exploit multiple +// CPUs for the DEFLATE computation. +// +// last saved: <2011-July-31 14:49:40> +// +// ------------------------------------------------------------------ +// +// Copyright (c) 2009-2011 by Dino Chiesa +// All rights reserved! +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ + +using System; +using System.Collections.Generic; +using System.Threading; +using Ionic.Zlib; +using System.IO; + + +namespace Ionic.Zlib +{ + internal class WorkItem + { + public byte[] buffer; + public byte[] compressed; + public int crc; + public int index; + public int ordinal; + public int inputBytesAvailable; + public int compressedBytesAvailable; + public ZlibCodec compressor; + + public WorkItem(int size, + Ionic.Zlib.CompressionLevel compressLevel, + CompressionStrategy strategy, + int ix) + { + this.buffer= new byte[size]; + // alloc 5 bytes overhead for every block (margin of safety= 2) + int n = size + ((size / 32768)+1) * 5 * 2; + this.compressed = new byte[n]; + this.compressor = new ZlibCodec(); + this.compressor.InitializeDeflate(compressLevel, false); + this.compressor.OutputBuffer = this.compressed; + this.compressor.InputBuffer = this.buffer; + this.index = ix; + } + } + + /// + /// A class for compressing streams using the + /// Deflate algorithm with multiple threads. + /// + /// + /// + /// + /// This class performs DEFLATE compression through writing. For + /// more information on the Deflate algorithm, see IETF RFC 1951, + /// "DEFLATE Compressed Data Format Specification version 1.3." + /// + /// + /// + /// This class is similar to , except + /// that this class is for compression only, and this implementation uses an + /// approach that employs multiple worker threads to perform the DEFLATE. On + /// a multi-cpu or multi-core computer, the performance of this class can be + /// significantly higher than the single-threaded DeflateStream, particularly + /// for larger streams. How large? Anything over 10mb is a good candidate + /// for parallel compression. + /// + /// + /// + /// The tradeoff is that this class uses more memory and more CPU than the + /// vanilla DeflateStream, and also is less efficient as a compressor. For + /// large files the size of the compressed data stream can be less than 1% + /// larger than the size of a compressed data stream from the vanialla + /// DeflateStream. For smaller files the difference can be larger. The + /// difference will also be larger if you set the BufferSize to be lower than + /// the default value. Your mileage may vary. Finally, for small files, the + /// ParallelDeflateOutputStream can be much slower than the vanilla + /// DeflateStream, because of the overhead associated to using the thread + /// pool. + /// + /// + /// + /// + public class ParallelDeflateOutputStream : System.IO.Stream + { + + private static readonly int IO_BUFFER_SIZE_DEFAULT = 64 * 1024; // 128k + private static readonly int BufferPairsPerCore = 4; + + private System.Collections.Generic.List _pool; + private bool _leaveOpen; + private bool emitting; + private System.IO.Stream _outStream; + private int _maxBufferPairs; + private int _bufferSize = IO_BUFFER_SIZE_DEFAULT; + private AutoResetEvent _newlyCompressedBlob; + //private ManualResetEvent _writingDone; + //private ManualResetEvent _sessionReset; + private object _outputLock = new object(); + private bool _isClosed; + private bool _firstWriteDone; + private int _currentlyFilling; + private int _lastFilled; + private int _lastWritten; + private int _latestCompressed; + private int _Crc32; + private Ionic.Crc.CRC32 _runningCrc; + private object _latestLock = new object(); + private System.Collections.Generic.Queue _toWrite; + private System.Collections.Generic.Queue _toFill; + private Int64 _totalBytesProcessed; + private Ionic.Zlib.CompressionLevel _compressLevel; + private volatile Exception _pendingException; + private bool _handlingException; + private object _eLock = new Object(); // protects _pendingException + + // This bitfield is used only when Trace is defined. + //private TraceBits _DesiredTrace = TraceBits.Write | TraceBits.WriteBegin | + //TraceBits.WriteDone | TraceBits.Lifecycle | TraceBits.Fill | TraceBits.Flush | + //TraceBits.Session; + + //private TraceBits _DesiredTrace = TraceBits.WriteBegin | TraceBits.WriteDone | TraceBits.Synch | TraceBits.Lifecycle | TraceBits.Session ; + + private TraceBits _DesiredTrace = + TraceBits.Session | + TraceBits.Compress | + TraceBits.WriteTake | + TraceBits.WriteEnter | + TraceBits.EmitEnter | + TraceBits.EmitDone | + TraceBits.EmitLock | + TraceBits.EmitSkip | + TraceBits.EmitBegin; + + /// + /// Create a ParallelDeflateOutputStream. + /// + /// + /// + /// + /// This stream compresses data written into it via the DEFLATE + /// algorithm (see RFC 1951), and writes out the compressed byte stream. + /// + /// + /// + /// The instance will use the default compression level, the default + /// buffer sizes and the default number of threads and buffers per + /// thread. + /// + /// + /// + /// This class is similar to , + /// except that this implementation uses an approach that employs + /// multiple worker threads to perform the DEFLATE. On a multi-cpu or + /// multi-core computer, the performance of this class can be + /// significantly higher than the single-threaded DeflateStream, + /// particularly for larger streams. How large? Anything over 10mb is + /// a good candidate for parallel compression. + /// + /// + /// + /// + /// + /// + /// This example shows how to use a ParallelDeflateOutputStream to compress + /// data. It reads a file, compresses it, and writes the compressed data to + /// a second, output file. + /// + /// + /// byte[] buffer = new byte[WORKING_BUFFER_SIZE]; + /// int n= -1; + /// String outputFile = fileToCompress + ".compressed"; + /// using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress)) + /// { + /// using (var raw = System.IO.File.Create(outputFile)) + /// { + /// using (Stream compressor = new ParallelDeflateOutputStream(raw)) + /// { + /// while ((n= input.Read(buffer, 0, buffer.Length)) != 0) + /// { + /// compressor.Write(buffer, 0, n); + /// } + /// } + /// } + /// } + /// + /// + /// Dim buffer As Byte() = New Byte(4096) {} + /// Dim n As Integer = -1 + /// Dim outputFile As String = (fileToCompress & ".compressed") + /// Using input As Stream = File.OpenRead(fileToCompress) + /// Using raw As FileStream = File.Create(outputFile) + /// Using compressor As Stream = New ParallelDeflateOutputStream(raw) + /// Do While (n <> 0) + /// If (n > 0) Then + /// compressor.Write(buffer, 0, n) + /// End If + /// n = input.Read(buffer, 0, buffer.Length) + /// Loop + /// End Using + /// End Using + /// End Using + /// + /// + /// The stream to which compressed data will be written. + public ParallelDeflateOutputStream(System.IO.Stream stream) + : this(stream, CompressionLevel.Default, CompressionStrategy.Default, false) + { + } + + /// + /// Create a ParallelDeflateOutputStream using the specified CompressionLevel. + /// + /// + /// See the + /// constructor for example code. + /// + /// The stream to which compressed data will be written. + /// A tuning knob to trade speed for effectiveness. + public ParallelDeflateOutputStream(System.IO.Stream stream, CompressionLevel level) + : this(stream, level, CompressionStrategy.Default, false) + { + } + + /// + /// Create a ParallelDeflateOutputStream and specify whether to leave the captive stream open + /// when the ParallelDeflateOutputStream is closed. + /// + /// + /// See the + /// constructor for example code. + /// + /// The stream to which compressed data will be written. + /// + /// true if the application would like the stream to remain open after inflation/deflation. + /// + public ParallelDeflateOutputStream(System.IO.Stream stream, bool leaveOpen) + : this(stream, CompressionLevel.Default, CompressionStrategy.Default, leaveOpen) + { + } + + /// + /// Create a ParallelDeflateOutputStream and specify whether to leave the captive stream open + /// when the ParallelDeflateOutputStream is closed. + /// + /// + /// See the + /// constructor for example code. + /// + /// The stream to which compressed data will be written. + /// A tuning knob to trade speed for effectiveness. + /// + /// true if the application would like the stream to remain open after inflation/deflation. + /// + public ParallelDeflateOutputStream(System.IO.Stream stream, CompressionLevel level, bool leaveOpen) + : this(stream, CompressionLevel.Default, CompressionStrategy.Default, leaveOpen) + { + } + + /// + /// Create a ParallelDeflateOutputStream using the specified + /// CompressionLevel and CompressionStrategy, and specifying whether to + /// leave the captive stream open when the ParallelDeflateOutputStream is + /// closed. + /// + /// + /// See the + /// constructor for example code. + /// + /// The stream to which compressed data will be written. + /// A tuning knob to trade speed for effectiveness. + /// + /// By tweaking this parameter, you may be able to optimize the compression for + /// data with particular characteristics. + /// + /// + /// true if the application would like the stream to remain open after inflation/deflation. + /// + public ParallelDeflateOutputStream(System.IO.Stream stream, + CompressionLevel level, + CompressionStrategy strategy, + bool leaveOpen) + { + TraceOutput(TraceBits.Lifecycle | TraceBits.Session, "-------------------------------------------------------"); + TraceOutput(TraceBits.Lifecycle | TraceBits.Session, "Create {0:X8}", this.GetHashCode()); + _outStream = stream; + _compressLevel= level; + Strategy = strategy; + _leaveOpen = leaveOpen; + this.MaxBufferPairs = 16; // default + } + + + /// + /// The ZLIB strategy to be used during compression. + /// + /// + public CompressionStrategy Strategy + { + get; + private set; + } + + /// + /// The maximum number of buffer pairs to use. + /// + /// + /// + /// + /// This property sets an upper limit on the number of memory buffer + /// pairs to create. The implementation of this stream allocates + /// multiple buffers to facilitate parallel compression. As each buffer + /// fills up, this stream uses + /// ThreadPool.QueueUserWorkItem() + /// to compress those buffers in a background threadpool thread. After a + /// buffer is compressed, it is re-ordered and written to the output + /// stream. + /// + /// + /// + /// A higher number of buffer pairs enables a higher degree of + /// parallelism, which tends to increase the speed of compression on + /// multi-cpu computers. On the other hand, a higher number of buffer + /// pairs also implies a larger memory consumption, more active worker + /// threads, and a higher cpu utilization for any compression. This + /// property enables the application to limit its memory consumption and + /// CPU utilization behavior depending on requirements. + /// + /// + /// + /// For each compression "task" that occurs in parallel, there are 2 + /// buffers allocated: one for input and one for output. This property + /// sets a limit for the number of pairs. The total amount of storage + /// space allocated for buffering will then be (N*S*2), where N is the + /// number of buffer pairs, S is the size of each buffer (). By default, DotNetZip allocates 4 buffer + /// pairs per CPU core, so if your machine has 4 cores, and you retain + /// the default buffer size of 128k, then the + /// ParallelDeflateOutputStream will use 4 * 4 * 2 * 128kb of buffer + /// memory in total, or 4mb, in blocks of 128kb. If you then set this + /// property to 8, then the number will be 8 * 2 * 128kb of buffer + /// memory, or 2mb. + /// + /// + /// + /// CPU utilization will also go up with additional buffers, because a + /// larger number of buffer pairs allows a larger number of background + /// threads to compress in parallel. If you find that parallel + /// compression is consuming too much memory or CPU, you can adjust this + /// value downward. + /// + /// + /// + /// The default value is 16. Different values may deliver better or + /// worse results, depending on your priorities and the dynamic + /// performance characteristics of your storage and compute resources. + /// + /// + /// + /// This property is not the number of buffer pairs to use; it is an + /// upper limit. An illustration: Suppose you have an application that + /// uses the default value of this property (which is 16), and it runs + /// on a machine with 2 CPU cores. In that case, DotNetZip will allocate + /// 4 buffer pairs per CPU core, for a total of 8 pairs. The upper + /// limit specified by this property has no effect. + /// + /// + /// + /// The application can set this value at any time, but it is effective + /// only before the first call to Write(), which is when the buffers are + /// allocated. + /// + /// + public int MaxBufferPairs + { + get + { + return _maxBufferPairs; + } + set + { + if (value < 4) + throw new ArgumentException("MaxBufferPairs", + "Value must be 4 or greater."); + _maxBufferPairs = value; + } + } + + /// + /// The size of the buffers used by the compressor threads. + /// + /// + /// + /// + /// The default buffer size is 128k. The application can set this value + /// at any time, but it is effective only before the first Write(). + /// + /// + /// + /// Larger buffer sizes implies larger memory consumption but allows + /// more efficient compression. Using smaller buffer sizes consumes less + /// memory but may result in less effective compression. For example, + /// using the default buffer size of 128k, the compression delivered is + /// within 1% of the compression delivered by the single-threaded . On the other hand, using a + /// BufferSize of 8k can result in a compressed data stream that is 5% + /// larger than that delivered by the single-threaded + /// DeflateStream. Excessively small buffer sizes can also cause + /// the speed of the ParallelDeflateOutputStream to drop, because of + /// larger thread scheduling overhead dealing with many many small + /// buffers. + /// + /// + /// + /// The total amount of storage space allocated for buffering will be + /// (N*S*2), where N is the number of buffer pairs, and S is the size of + /// each buffer (this property). There are 2 buffers used by the + /// compressor, one for input and one for output. By default, DotNetZip + /// allocates 4 buffer pairs per CPU core, so if your machine has 4 + /// cores, then the number of buffer pairs used will be 16. If you + /// accept the default value of this property, 128k, then the + /// ParallelDeflateOutputStream will use 16 * 2 * 128kb of buffer memory + /// in total, or 4mb, in blocks of 128kb. If you set this property to + /// 64kb, then the number will be 16 * 2 * 64kb of buffer memory, or + /// 2mb. + /// + /// + /// + public int BufferSize + { + get { return _bufferSize;} + set + { + if (value < 1024) + throw new ArgumentOutOfRangeException("BufferSize", + "BufferSize must be greater than 1024 bytes"); + _bufferSize = value; + } + } + + /// + /// The CRC32 for the data that was written out, prior to compression. + /// + /// + /// This value is meaningful only after a call to Close(). + /// + public int Crc32 { get { return _Crc32; } } + + + /// + /// The total number of uncompressed bytes processed by the ParallelDeflateOutputStream. + /// + /// + /// This value is meaningful only after a call to Close(). + /// + public Int64 BytesProcessed { get { return _totalBytesProcessed; } } + + + private void _InitializePoolOfWorkItems() + { + _toWrite = new Queue(); + _toFill = new Queue(); + _pool = new System.Collections.Generic.List(); + int nTasks = BufferPairsPerCore * Environment.ProcessorCount; + nTasks = Math.Min(nTasks, _maxBufferPairs); + for(int i=0; i < nTasks; i++) + { + _pool.Add(new WorkItem(_bufferSize, _compressLevel, Strategy, i)); + _toFill.Enqueue(i); + } + + _newlyCompressedBlob = new AutoResetEvent(false); + _runningCrc = new Ionic.Crc.CRC32(); + _currentlyFilling = -1; + _lastFilled = -1; + _lastWritten = -1; + _latestCompressed = -1; + } + + + + + /// + /// Write data to the stream. + /// + /// + /// + /// + /// + /// To use the ParallelDeflateOutputStream to compress data, create a + /// ParallelDeflateOutputStream with CompressionMode.Compress, passing a + /// writable output stream. Then call Write() on that + /// ParallelDeflateOutputStream, providing uncompressed data as input. The + /// data sent to the output stream will be the compressed form of the data + /// written. + /// + /// + /// + /// To decompress data, use the class. + /// + /// + /// + /// The buffer holding data to write to the stream. + /// the offset within that data array to find the first byte to write. + /// the number of bytes to write. + public override void Write(byte[] buffer, int offset, int count) + { + bool mustWait = false; + + // This method does this: + // 0. handles any pending exceptions + // 1. write any buffers that are ready to be written, + // 2. fills a work buffer; when full, flip state to 'Filled', + // 3. if more data to be written, goto step 1 + + if (_isClosed) + throw new InvalidOperationException(); + + // dispense any exceptions that occurred on the BG threads + if (_pendingException != null) + { + _handlingException = true; + var pe = _pendingException; + _pendingException = null; + throw pe; + } + + if (count == 0) return; + + if (!_firstWriteDone) + { + // Want to do this on first Write, first session, and not in the + // constructor. We want to allow MaxBufferPairs to + // change after construction, but before first Write. + _InitializePoolOfWorkItems(); + _firstWriteDone = true; + } + + + do + { + // may need to make buffers available + EmitPendingBuffers(false, mustWait); + + mustWait = false; + // use current buffer, or get a new buffer to fill + int ix = -1; + if (_currentlyFilling >= 0) + { + ix = _currentlyFilling; + TraceOutput(TraceBits.WriteTake, + "Write notake wi({0}) lf({1})", + ix, + _lastFilled); + } + else + { + TraceOutput(TraceBits.WriteTake, "Write take?"); + if (_toFill.Count == 0) + { + // no available buffers, so... need to emit + // compressed buffers. + mustWait = true; + continue; + } + + ix = _toFill.Dequeue(); + TraceOutput(TraceBits.WriteTake, + "Write take wi({0}) lf({1})", + ix, + _lastFilled); + ++_lastFilled; // TODO: consider rollover? + } + + WorkItem workitem = _pool[ix]; + + int limit = ((workitem.buffer.Length - workitem.inputBytesAvailable) > count) + ? count + : (workitem.buffer.Length - workitem.inputBytesAvailable); + + workitem.ordinal = _lastFilled; + + TraceOutput(TraceBits.Write, + "Write lock wi({0}) ord({1}) iba({2})", + workitem.index, + workitem.ordinal, + workitem.inputBytesAvailable + ); + + // copy from the provided buffer to our workitem, starting at + // the tail end of whatever data we might have in there currently. + Buffer.BlockCopy(buffer, + offset, + workitem.buffer, + workitem.inputBytesAvailable, + limit); + + count -= limit; + offset += limit; + workitem.inputBytesAvailable += limit; + if (workitem.inputBytesAvailable == workitem.buffer.Length) + { + // No need for interlocked.increment: the Write() + // method is documented as not multi-thread safe, so + // we can assume Write() calls come in from only one + // thread. + TraceOutput(TraceBits.Write, + "Write QUWI wi({0}) ord({1}) iba({2}) nf({3})", + workitem.index, + workitem.ordinal, + workitem.inputBytesAvailable ); + + if (!ThreadPool.QueueUserWorkItem( _DeflateOne, workitem )) + throw new Exception("Cannot enqueue workitem"); + + _currentlyFilling = -1; // will get a new buffer next time + } + else + _currentlyFilling = ix; + + if (count > 0) + TraceOutput(TraceBits.WriteEnter, "Write more"); + } + while (count > 0); // until no more to write + + TraceOutput(TraceBits.WriteEnter, "Write exit"); + return; + } + + + + private void _FlushFinish() + { + // After writing a series of compressed buffers, each one closed + // with Flush.Sync, we now write the final one as Flush.Finish, + // and then stop. + byte[] buffer = new byte[128]; + var compressor = new ZlibCodec(); + int rc = compressor.InitializeDeflate(_compressLevel, false); + compressor.InputBuffer = null; + compressor.NextIn = 0; + compressor.AvailableBytesIn = 0; + compressor.OutputBuffer = buffer; + compressor.NextOut = 0; + compressor.AvailableBytesOut = buffer.Length; + rc = compressor.Deflate(FlushType.Finish); + + if (rc != ZlibConstants.Z_STREAM_END && rc != ZlibConstants.Z_OK) + throw new Exception("deflating: " + compressor.Message); + + if (buffer.Length - compressor.AvailableBytesOut > 0) + { + TraceOutput(TraceBits.EmitBegin, + "Emit begin flush bytes({0})", + buffer.Length - compressor.AvailableBytesOut); + + _outStream.Write(buffer, 0, buffer.Length - compressor.AvailableBytesOut); + + TraceOutput(TraceBits.EmitDone, + "Emit done flush"); + } + + compressor.EndDeflate(); + + _Crc32 = _runningCrc.Crc32Result; + } + + + private void _Flush(bool lastInput) + { + if (_isClosed) + throw new InvalidOperationException(); + + if (emitting) return; + + // compress any partial buffer + if (_currentlyFilling >= 0) + { + WorkItem workitem = _pool[_currentlyFilling]; + _DeflateOne(workitem); + _currentlyFilling = -1; // get a new buffer next Write() + } + + if (lastInput) + { + EmitPendingBuffers(true, false); + _FlushFinish(); + } + else + { + EmitPendingBuffers(false, false); + } + } + + + + /// + /// Flush the stream. + /// + public override void Flush() + { + if (_pendingException != null) + { + _handlingException = true; + var pe = _pendingException; + _pendingException = null; + throw pe; + } + if (_handlingException) + return; + + _Flush(false); + } + + + /// + /// Close the stream. + /// + /// + /// You must call Close on the stream to guarantee that all of the data written in has + /// been compressed, and the compressed data has been written out. + /// + public override void Close() + { + TraceOutput(TraceBits.Session, "Close {0:X8}", this.GetHashCode()); + + if (_pendingException != null) + { + _handlingException = true; + var pe = _pendingException; + _pendingException = null; + throw pe; + } + + if (_handlingException) + return; + + if (_isClosed) return; + + _Flush(true); + + if (!_leaveOpen) + _outStream.Close(); + + _isClosed= true; + } + + + + // workitem 10030 - implement a new Dispose method + + /// Dispose the object + /// + /// + /// Because ParallelDeflateOutputStream is IDisposable, the + /// application must call this method when finished using the instance. + /// + /// + /// This method is generally called implicitly upon exit from + /// a using scope in C# (Using in VB). + /// + /// + new public void Dispose() + { + TraceOutput(TraceBits.Lifecycle, "Dispose {0:X8}", this.GetHashCode()); + Close(); + _pool = null; + Dispose(true); + } + + + + /// The Dispose method + /// + /// indicates whether the Dispose method was invoked by user code. + /// + protected override void Dispose(bool disposing) + { + base.Dispose(disposing); + } + + + /// + /// Resets the stream for use with another stream. + /// + /// + /// Because the ParallelDeflateOutputStream is expensive to create, it + /// has been designed so that it can be recycled and re-used. You have + /// to call Close() on the stream first, then you can call Reset() on + /// it, to use it again on another stream. + /// + /// + /// + /// The new output stream for this era. + /// + /// + /// + /// + /// ParallelDeflateOutputStream deflater = null; + /// foreach (var inputFile in listOfFiles) + /// { + /// string outputFile = inputFile + ".compressed"; + /// using (System.IO.Stream input = System.IO.File.OpenRead(inputFile)) + /// { + /// using (var outStream = System.IO.File.Create(outputFile)) + /// { + /// if (deflater == null) + /// deflater = new ParallelDeflateOutputStream(outStream, + /// CompressionLevel.Best, + /// CompressionStrategy.Default, + /// true); + /// deflater.Reset(outStream); + /// + /// while ((n= input.Read(buffer, 0, buffer.Length)) != 0) + /// { + /// deflater.Write(buffer, 0, n); + /// } + /// } + /// } + /// } + /// + /// + public void Reset(Stream stream) + { + TraceOutput(TraceBits.Session, "-------------------------------------------------------"); + TraceOutput(TraceBits.Session, "Reset {0:X8} firstDone({1})", this.GetHashCode(), _firstWriteDone); + + if (!_firstWriteDone) return; + + // reset all status + _toWrite.Clear(); + _toFill.Clear(); + foreach (var workitem in _pool) + { + _toFill.Enqueue(workitem.index); + workitem.ordinal = -1; + } + + _firstWriteDone = false; + _totalBytesProcessed = 0L; + _runningCrc = new Ionic.Crc.CRC32(); + _isClosed= false; + _currentlyFilling = -1; + _lastFilled = -1; + _lastWritten = -1; + _latestCompressed = -1; + _outStream = stream; + } + + + + + private void EmitPendingBuffers(bool doAll, bool mustWait) + { + // When combining parallel deflation with a ZipSegmentedStream, it's + // possible for the ZSS to throw from within this method. In that + // case, Close/Dispose will be called on this stream, if this stream + // is employed within a using or try/finally pair as required. But + // this stream is unaware of the pending exception, so the Close() + // method invokes this method AGAIN. This can lead to a deadlock. + // Therefore, failfast if re-entering. + + if (emitting) return; + emitting = true; + if (doAll || mustWait) + _newlyCompressedBlob.WaitOne(); + + do + { + int firstSkip = -1; + int millisecondsToWait = doAll ? 200 : (mustWait ? -1 : 0); + int nextToWrite = -1; + + do + { + if (Monitor.TryEnter(_toWrite, millisecondsToWait)) + { + nextToWrite = -1; + try + { + if (_toWrite.Count > 0) + nextToWrite = _toWrite.Dequeue(); + } + finally + { + Monitor.Exit(_toWrite); + } + + if (nextToWrite >= 0) + { + WorkItem workitem = _pool[nextToWrite]; + if (workitem.ordinal != _lastWritten + 1) + { + // out of order. requeue and try again. + TraceOutput(TraceBits.EmitSkip, + "Emit skip wi({0}) ord({1}) lw({2}) fs({3})", + workitem.index, + workitem.ordinal, + _lastWritten, + firstSkip); + + lock(_toWrite) + { + _toWrite.Enqueue(nextToWrite); + } + + if (firstSkip == nextToWrite) + { + // We went around the list once. + // None of the items in the list is the one we want. + // Now wait for a compressor to signal again. + _newlyCompressedBlob.WaitOne(); + firstSkip = -1; + } + else if (firstSkip == -1) + firstSkip = nextToWrite; + + continue; + } + + firstSkip = -1; + + TraceOutput(TraceBits.EmitBegin, + "Emit begin wi({0}) ord({1}) cba({2})", + workitem.index, + workitem.ordinal, + workitem.compressedBytesAvailable); + + _outStream.Write(workitem.compressed, 0, workitem.compressedBytesAvailable); + _runningCrc.Combine(workitem.crc, workitem.inputBytesAvailable); + _totalBytesProcessed += workitem.inputBytesAvailable; + workitem.inputBytesAvailable = 0; + + TraceOutput(TraceBits.EmitDone, + "Emit done wi({0}) ord({1}) cba({2}) mtw({3})", + workitem.index, + workitem.ordinal, + workitem.compressedBytesAvailable, + millisecondsToWait); + + _lastWritten = workitem.ordinal; + _toFill.Enqueue(workitem.index); + + // don't wait next time through + if (millisecondsToWait == -1) millisecondsToWait = 0; + } + } + else + nextToWrite = -1; + + } while (nextToWrite >= 0); + + } while (doAll && (_lastWritten != _latestCompressed)); + + emitting = false; + } + + + +#if OLD + private void _PerpetualWriterMethod(object state) + { + TraceOutput(TraceBits.WriterThread, "_PerpetualWriterMethod START"); + + try + { + do + { + // wait for the next session + TraceOutput(TraceBits.Synch | TraceBits.WriterThread, "Synch _sessionReset.WaitOne(begin) PWM"); + _sessionReset.WaitOne(); + TraceOutput(TraceBits.Synch | TraceBits.WriterThread, "Synch _sessionReset.WaitOne(done) PWM"); + + if (_isDisposed) break; + + TraceOutput(TraceBits.Synch | TraceBits.WriterThread, "Synch _sessionReset.Reset() PWM"); + _sessionReset.Reset(); + + // repeatedly write buffers as they become ready + WorkItem workitem = null; + Ionic.Zlib.CRC32 c= new Ionic.Zlib.CRC32(); + do + { + workitem = _pool[_nextToWrite % _pc]; + lock(workitem) + { + if (_noMoreInputForThisSegment) + TraceOutput(TraceBits.Write, + "Write drain wi({0}) stat({1}) canuse({2}) cba({3})", + workitem.index, + workitem.status, + (workitem.status == (int)WorkItem.Status.Compressed), + workitem.compressedBytesAvailable); + + do + { + if (workitem.status == (int)WorkItem.Status.Compressed) + { + TraceOutput(TraceBits.WriteBegin, + "Write begin wi({0}) stat({1}) cba({2})", + workitem.index, + workitem.status, + workitem.compressedBytesAvailable); + + workitem.status = (int)WorkItem.Status.Writing; + _outStream.Write(workitem.compressed, 0, workitem.compressedBytesAvailable); + c.Combine(workitem.crc, workitem.inputBytesAvailable); + _totalBytesProcessed += workitem.inputBytesAvailable; + _nextToWrite++; + workitem.inputBytesAvailable= 0; + workitem.status = (int)WorkItem.Status.Done; + + TraceOutput(TraceBits.WriteDone, + "Write done wi({0}) stat({1}) cba({2})", + workitem.index, + workitem.status, + workitem.compressedBytesAvailable); + + + Monitor.Pulse(workitem); + break; + } + else + { + int wcycles = 0; + // I've locked a workitem I cannot use. + // Therefore, wake someone else up, and then release the lock. + while (workitem.status != (int)WorkItem.Status.Compressed) + { + TraceOutput(TraceBits.WriteWait, + "Write waiting wi({0}) stat({1}) nw({2}) nf({3}) nomore({4})", + workitem.index, + workitem.status, + _nextToWrite, _nextToFill, + _noMoreInputForThisSegment ); + + if (_noMoreInputForThisSegment && _nextToWrite == _nextToFill) + break; + + wcycles++; + + // wake up someone else + Monitor.Pulse(workitem); + // release and wait + Monitor.Wait(workitem); + + if (workitem.status == (int)WorkItem.Status.Compressed) + TraceOutput(TraceBits.WriteWait, + "Write A-OK wi({0}) stat({1}) iba({2}) cba({3}) cyc({4})", + workitem.index, + workitem.status, + workitem.inputBytesAvailable, + workitem.compressedBytesAvailable, + wcycles); + } + + if (_noMoreInputForThisSegment && _nextToWrite == _nextToFill) + break; + + } + } + while (true); + } + + if (_noMoreInputForThisSegment) + TraceOutput(TraceBits.Write, + "Write nomore nw({0}) nf({1}) break({2})", + _nextToWrite, _nextToFill, (_nextToWrite == _nextToFill)); + + if (_noMoreInputForThisSegment && _nextToWrite == _nextToFill) + break; + + } while (true); + + + // Finish: + // After writing a series of buffers, closing each one with + // Flush.Sync, we now write the final one as Flush.Finish, and + // then stop. + byte[] buffer = new byte[128]; + ZlibCodec compressor = new ZlibCodec(); + int rc = compressor.InitializeDeflate(_compressLevel, false); + compressor.InputBuffer = null; + compressor.NextIn = 0; + compressor.AvailableBytesIn = 0; + compressor.OutputBuffer = buffer; + compressor.NextOut = 0; + compressor.AvailableBytesOut = buffer.Length; + rc = compressor.Deflate(FlushType.Finish); + + if (rc != ZlibConstants.Z_STREAM_END && rc != ZlibConstants.Z_OK) + throw new Exception("deflating: " + compressor.Message); + + if (buffer.Length - compressor.AvailableBytesOut > 0) + { + TraceOutput(TraceBits.WriteBegin, + "Write begin flush bytes({0})", + buffer.Length - compressor.AvailableBytesOut); + + _outStream.Write(buffer, 0, buffer.Length - compressor.AvailableBytesOut); + + TraceOutput(TraceBits.WriteBegin, + "Write done flush"); + } + + compressor.EndDeflate(); + + _Crc32 = c.Crc32Result; + + // signal that writing is complete: + TraceOutput(TraceBits.Synch, "Synch _writingDone.Set() PWM"); + _writingDone.Set(); + } + while (true); + } + catch (System.Exception exc1) + { + lock(_eLock) + { + // expose the exception to the main thread + if (_pendingException!=null) + _pendingException = exc1; + } + } + + TraceOutput(TraceBits.WriterThread, "_PerpetualWriterMethod FINIS"); + } +#endif + + + + + private void _DeflateOne(Object wi) + { + // compress one buffer + WorkItem workitem = (WorkItem) wi; + try + { + int myItem = workitem.index; + Ionic.Crc.CRC32 crc = new Ionic.Crc.CRC32(); + + // calc CRC on the buffer + crc.SlurpBlock(workitem.buffer, 0, workitem.inputBytesAvailable); + + // deflate it + DeflateOneSegment(workitem); + + // update status + workitem.crc = crc.Crc32Result; + TraceOutput(TraceBits.Compress, + "Compress wi({0}) ord({1}) len({2})", + workitem.index, + workitem.ordinal, + workitem.compressedBytesAvailable + ); + + lock(_latestLock) + { + if (workitem.ordinal > _latestCompressed) + _latestCompressed = workitem.ordinal; + } + lock (_toWrite) + { + _toWrite.Enqueue(workitem.index); + } + _newlyCompressedBlob.Set(); + } + catch (System.Exception exc1) + { + lock(_eLock) + { + // expose the exception to the main thread + if (_pendingException!=null) + _pendingException = exc1; + } + } + } + + + + + private bool DeflateOneSegment(WorkItem workitem) + { + ZlibCodec compressor = workitem.compressor; + int rc= 0; + compressor.ResetDeflate(); + compressor.NextIn = 0; + + compressor.AvailableBytesIn = workitem.inputBytesAvailable; + + // step 1: deflate the buffer + compressor.NextOut = 0; + compressor.AvailableBytesOut = workitem.compressed.Length; + do + { + compressor.Deflate(FlushType.None); + } + while (compressor.AvailableBytesIn > 0 || compressor.AvailableBytesOut == 0); + + // step 2: flush (sync) + rc = compressor.Deflate(FlushType.Sync); + + workitem.compressedBytesAvailable= (int) compressor.TotalBytesOut; + return true; + } + + + [System.Diagnostics.ConditionalAttribute("Trace")] + private void TraceOutput(TraceBits bits, string format, params object[] varParams) + { + if ((bits & _DesiredTrace) != 0) + { + lock(_outputLock) + { + int tid = Thread.CurrentThread.GetHashCode(); +#if !SILVERLIGHT + Console.ForegroundColor = (ConsoleColor) (tid % 8 + 8); +#endif + Console.Write("{0:000} PDOS ", tid); + Console.WriteLine(format, varParams); +#if !SILVERLIGHT + Console.ResetColor(); +#endif + } + } + } + + + // used only when Trace is defined + [Flags] + enum TraceBits : uint + { + None = 0, + NotUsed1 = 1, + EmitLock = 2, + EmitEnter = 4, // enter _EmitPending + EmitBegin = 8, // begin to write out + EmitDone = 16, // done writing out + EmitSkip = 32, // writer skipping a workitem + EmitAll = 58, // All Emit flags + Flush = 64, + Lifecycle = 128, // constructor/disposer + Session = 256, // Close/Reset + Synch = 512, // thread synchronization + Instance = 1024, // instance settings + Compress = 2048, // compress task + Write = 4096, // filling buffers, when caller invokes Write() + WriteEnter = 8192, // upon entry to Write() + WriteTake = 16384, // on _toFill.Take() + All = 0xffffffff, + } + + + + /// + /// Indicates whether the stream supports Seek operations. + /// + /// + /// Always returns false. + /// + public override bool CanSeek + { + get { return false; } + } + + + /// + /// Indicates whether the stream supports Read operations. + /// + /// + /// Always returns false. + /// + public override bool CanRead + { + get {return false;} + } + + /// + /// Indicates whether the stream supports Write operations. + /// + /// + /// Returns true if the provided stream is writable. + /// + public override bool CanWrite + { + get { return _outStream.CanWrite; } + } + + /// + /// Reading this property always throws a NotSupportedException. + /// + public override long Length + { + get { throw new NotSupportedException(); } + } + + /// + /// Returns the current position of the output stream. + /// + /// + /// + /// Because the output gets written by a background thread, + /// the value may change asynchronously. Setting this + /// property always throws a NotSupportedException. + /// + /// + public override long Position + { + get { return _outStream.Position; } + set { throw new NotSupportedException(); } + } + + /// + /// This method always throws a NotSupportedException. + /// + /// + /// The buffer into which data would be read, IF THIS METHOD + /// ACTUALLY DID ANYTHING. + /// + /// + /// The offset within that data array at which to insert the + /// data that is read, IF THIS METHOD ACTUALLY DID + /// ANYTHING. + /// + /// + /// The number of bytes to write, IF THIS METHOD ACTUALLY DID + /// ANYTHING. + /// + /// nothing. + public override int Read(byte[] buffer, int offset, int count) + { + throw new NotSupportedException(); + } + + /// + /// This method always throws a NotSupportedException. + /// + /// + /// The offset to seek to.... + /// IF THIS METHOD ACTUALLY DID ANYTHING. + /// + /// + /// The reference specifying how to apply the offset.... IF + /// THIS METHOD ACTUALLY DID ANYTHING. + /// + /// nothing. It always throws. + public override long Seek(long offset, System.IO.SeekOrigin origin) + { + throw new NotSupportedException(); + } + + /// + /// This method always throws a NotSupportedException. + /// + /// + /// The new value for the stream length.... IF + /// THIS METHOD ACTUALLY DID ANYTHING. + /// + public override void SetLength(long value) + { + throw new NotSupportedException(); + } + + } + +} + + diff --git a/Resources/Libraries/DotNetZip/Source/Zlib/Tree.cs b/Resources/Libraries/DotNetZip/Source/Zlib/Tree.cs new file mode 100644 index 00000000..954872aa --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zlib/Tree.cs @@ -0,0 +1,423 @@ +// Tree.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa and Microsoft Corporation. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2009-October-28 13:29:50> +// +// ------------------------------------------------------------------ +// +// This module defines classes for zlib compression and +// decompression. This code is derived from the jzlib implementation of +// zlib. In keeping with the license for jzlib, the copyright to that +// code is below. +// +// ------------------------------------------------------------------ +// +// Copyright (c) 2000,2001,2002,2003 ymnk, JCraft,Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// 1. Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// +// 2. Redistributions in binary form must reproduce the above copyright +// notice, this list of conditions and the following disclaimer in +// the documentation and/or other materials provided with the distribution. +// +// 3. The names of the authors may not be used to endorse or promote products +// derived from this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, +// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND +// FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JCRAFT, +// INC. OR ANY CONTRIBUTORS TO THIS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, +// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, +// OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +// EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// ----------------------------------------------------------------------- +// +// This program is based on zlib-1.1.3; credit to authors +// Jean-loup Gailly(jloup@gzip.org) and Mark Adler(madler@alumni.caltech.edu) +// and contributors of zlib. +// +// ----------------------------------------------------------------------- + + +using System; + +namespace Ionic.Zlib +{ + sealed class Tree + { + private static readonly int HEAP_SIZE = (2 * InternalConstants.L_CODES + 1); + + // extra bits for each length code + internal static readonly int[] ExtraLengthBits = new int[] + { + 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, + 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0 + }; + + // extra bits for each distance code + internal static readonly int[] ExtraDistanceBits = new int[] + { + 0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, + 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13 + }; + + // extra bits for each bit length code + internal static readonly int[] extra_blbits = new int[]{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 3, 7}; + + internal static readonly sbyte[] bl_order = new sbyte[]{16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15}; + + + // The lengths of the bit length codes are sent in order of decreasing + // probability, to avoid transmitting the lengths for unused bit + // length codes. + + internal const int Buf_size = 8 * 2; + + // see definition of array dist_code below + //internal const int DIST_CODE_LEN = 512; + + private static readonly sbyte[] _dist_code = new sbyte[] + { + 0, 1, 2, 3, 4, 4, 5, 5, 6, 6, 6, 6, 7, 7, 7, 7, + 8, 8, 8, 8, 8, 8, 8, 8, 9, 9, 9, 9, 9, 9, 9, 9, + 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, + 11, 11, 11, 11, 11, 11, 11, 11, 11, 11, 11, 11, 11, 11, 11, 11, + 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, + 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, + 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, + 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, + 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, + 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, + 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, + 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, + 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, + 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, + 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, + 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, + 0, 0, 16, 17, 18, 18, 19, 19, 20, 20, 20, 20, 21, 21, 21, 21, + 22, 22, 22, 22, 22, 22, 22, 22, 23, 23, 23, 23, 23, 23, 23, 23, + 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, + 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, + 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, + 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, + 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, + 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, + 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, + 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, + 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, + 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, + 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, + 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, + 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, + 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29 + }; + + internal static readonly sbyte[] LengthCode = new sbyte[] + { + 0, 1, 2, 3, 4, 5, 6, 7, 8, 8, 9, 9, 10, 10, 11, 11, + 12, 12, 12, 12, 13, 13, 13, 13, 14, 14, 14, 14, 15, 15, 15, 15, + 16, 16, 16, 16, 16, 16, 16, 16, 17, 17, 17, 17, 17, 17, 17, 17, + 18, 18, 18, 18, 18, 18, 18, 18, 19, 19, 19, 19, 19, 19, 19, 19, + 20, 20, 20, 20, 20, 20, 20, 20, 20, 20, 20, 20, 20, 20, 20, 20, + 21, 21, 21, 21, 21, 21, 21, 21, 21, 21, 21, 21, 21, 21, 21, 21, + 22, 22, 22, 22, 22, 22, 22, 22, 22, 22, 22, 22, 22, 22, 22, 22, + 23, 23, 23, 23, 23, 23, 23, 23, 23, 23, 23, 23, 23, 23, 23, 23, + 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, + 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, + 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, + 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, 25, + 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, + 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, 26, + 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, + 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 27, 28 + }; + + + internal static readonly int[] LengthBase = new int[] + { + 0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 12, 14, 16, 20, 24, 28, + 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 0 + }; + + + internal static readonly int[] DistanceBase = new int[] + { + 0, 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64, 96, 128, 192, + 256, 384, 512, 768, 1024, 1536, 2048, 3072, 4096, 6144, 8192, 12288, 16384, 24576 + }; + + + /// + /// Map from a distance to a distance code. + /// + /// + /// No side effects. _dist_code[256] and _dist_code[257] are never used. + /// + internal static int DistanceCode(int dist) + { + return (dist < 256) + ? _dist_code[dist] + : _dist_code[256 + SharedUtils.URShift(dist, 7)]; + } + + internal short[] dyn_tree; // the dynamic tree + internal int max_code; // largest code with non zero frequency + internal StaticTree staticTree; // the corresponding static tree + + // Compute the optimal bit lengths for a tree and update the total bit length + // for the current block. + // IN assertion: the fields freq and dad are set, heap[heap_max] and + // above are the tree nodes sorted by increasing frequency. + // OUT assertions: the field len is set to the optimal bit length, the + // array bl_count contains the frequencies for each bit length. + // The length opt_len is updated; static_len is also updated if stree is + // not null. + internal void gen_bitlen(DeflateManager s) + { + short[] tree = dyn_tree; + short[] stree = staticTree.treeCodes; + int[] extra = staticTree.extraBits; + int base_Renamed = staticTree.extraBase; + int max_length = staticTree.maxLength; + int h; // heap index + int n, m; // iterate over the tree elements + int bits; // bit length + int xbits; // extra bits + short f; // frequency + int overflow = 0; // number of elements with bit length too large + + for (bits = 0; bits <= InternalConstants.MAX_BITS; bits++) + s.bl_count[bits] = 0; + + // In a first pass, compute the optimal bit lengths (which may + // overflow in the case of the bit length tree). + tree[s.heap[s.heap_max] * 2 + 1] = 0; // root of the heap + + for (h = s.heap_max + 1; h < HEAP_SIZE; h++) + { + n = s.heap[h]; + bits = tree[tree[n * 2 + 1] * 2 + 1] + 1; + if (bits > max_length) + { + bits = max_length; overflow++; + } + tree[n * 2 + 1] = (short) bits; + // We overwrite tree[n*2+1] which is no longer needed + + if (n > max_code) + continue; // not a leaf node + + s.bl_count[bits]++; + xbits = 0; + if (n >= base_Renamed) + xbits = extra[n - base_Renamed]; + f = tree[n * 2]; + s.opt_len += f * (bits + xbits); + if (stree != null) + s.static_len += f * (stree[n * 2 + 1] + xbits); + } + if (overflow == 0) + return ; + + // This happens for example on obj2 and pic of the Calgary corpus + // Find the first bit length which could increase: + do + { + bits = max_length - 1; + while (s.bl_count[bits] == 0) + bits--; + s.bl_count[bits]--; // move one leaf down the tree + s.bl_count[bits + 1] = (short) (s.bl_count[bits + 1] + 2); // move one overflow item as its brother + s.bl_count[max_length]--; + // The brother of the overflow item also moves one step up, + // but this does not affect bl_count[max_length] + overflow -= 2; + } + while (overflow > 0); + + for (bits = max_length; bits != 0; bits--) + { + n = s.bl_count[bits]; + while (n != 0) + { + m = s.heap[--h]; + if (m > max_code) + continue; + if (tree[m * 2 + 1] != bits) + { + s.opt_len = (int) (s.opt_len + ((long) bits - (long) tree[m * 2 + 1]) * (long) tree[m * 2]); + tree[m * 2 + 1] = (short) bits; + } + n--; + } + } + } + + // Construct one Huffman tree and assigns the code bit strings and lengths. + // Update the total bit length for the current block. + // IN assertion: the field freq is set for all tree elements. + // OUT assertions: the fields len and code are set to the optimal bit length + // and corresponding code. The length opt_len is updated; static_len is + // also updated if stree is not null. The field max_code is set. + internal void build_tree(DeflateManager s) + { + short[] tree = dyn_tree; + short[] stree = staticTree.treeCodes; + int elems = staticTree.elems; + int n, m; // iterate over heap elements + int max_code = -1; // largest code with non zero frequency + int node; // new node being created + + // Construct the initial heap, with least frequent element in + // heap[1]. The sons of heap[n] are heap[2*n] and heap[2*n+1]. + // heap[0] is not used. + s.heap_len = 0; + s.heap_max = HEAP_SIZE; + + for (n = 0; n < elems; n++) + { + if (tree[n * 2] != 0) + { + s.heap[++s.heap_len] = max_code = n; + s.depth[n] = 0; + } + else + { + tree[n * 2 + 1] = 0; + } + } + + // The pkzip format requires that at least one distance code exists, + // and that at least one bit should be sent even if there is only one + // possible code. So to avoid special checks later on we force at least + // two codes of non zero frequency. + while (s.heap_len < 2) + { + node = s.heap[++s.heap_len] = (max_code < 2?++max_code:0); + tree[node * 2] = 1; + s.depth[node] = 0; + s.opt_len--; + if (stree != null) + s.static_len -= stree[node * 2 + 1]; + // node is 0 or 1 so it does not have extra bits + } + this.max_code = max_code; + + // The elements heap[heap_len/2+1 .. heap_len] are leaves of the tree, + // establish sub-heaps of increasing lengths: + + for (n = s.heap_len / 2; n >= 1; n--) + s.pqdownheap(tree, n); + + // Construct the Huffman tree by repeatedly combining the least two + // frequent nodes. + + node = elems; // next internal node of the tree + do + { + // n = node of least frequency + n = s.heap[1]; + s.heap[1] = s.heap[s.heap_len--]; + s.pqdownheap(tree, 1); + m = s.heap[1]; // m = node of next least frequency + + s.heap[--s.heap_max] = n; // keep the nodes sorted by frequency + s.heap[--s.heap_max] = m; + + // Create a new node father of n and m + tree[node * 2] = unchecked((short) (tree[n * 2] + tree[m * 2])); + s.depth[node] = (sbyte) (System.Math.Max((byte) s.depth[n], (byte) s.depth[m]) + 1); + tree[n * 2 + 1] = tree[m * 2 + 1] = (short) node; + + // and insert the new node in the heap + s.heap[1] = node++; + s.pqdownheap(tree, 1); + } + while (s.heap_len >= 2); + + s.heap[--s.heap_max] = s.heap[1]; + + // At this point, the fields freq and dad are set. We can now + // generate the bit lengths. + + gen_bitlen(s); + + // The field len is now set, we can generate the bit codes + gen_codes(tree, max_code, s.bl_count); + } + + // Generate the codes for a given tree and bit counts (which need not be + // optimal). + // IN assertion: the array bl_count contains the bit length statistics for + // the given tree and the field len is set for all tree elements. + // OUT assertion: the field code is set for all tree elements of non + // zero code length. + internal static void gen_codes(short[] tree, int max_code, short[] bl_count) + { + short[] next_code = new short[InternalConstants.MAX_BITS + 1]; // next code value for each bit length + short code = 0; // running code value + int bits; // bit index + int n; // code index + + // The distribution counts are first used to generate the code values + // without bit reversal. + for (bits = 1; bits <= InternalConstants.MAX_BITS; bits++) + unchecked { + next_code[bits] = code = (short) ((code + bl_count[bits - 1]) << 1); + } + + // Check that the bit counts in bl_count are consistent. The last code + // must be all ones. + //Assert (code + bl_count[MAX_BITS]-1 == (1<>= 1; //SharedUtils.URShift(code, 1); + res <<= 1; + } + while (--len > 0); + return res >> 1; + } + } +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/Zlib/Zlib.cs b/Resources/Libraries/DotNetZip/Source/Zlib/Zlib.cs new file mode 100644 index 00000000..6c51b1aa --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zlib/Zlib.cs @@ -0,0 +1,546 @@ +// Zlib.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009-2011 Dino Chiesa and Microsoft Corporation. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// Last Saved: <2011-August-03 19:52:28> +// +// ------------------------------------------------------------------ +// +// This module defines classes for ZLIB compression and +// decompression. This code is derived from the jzlib implementation of +// zlib, but significantly modified. The object model is not the same, +// and many of the behaviors are new or different. Nonetheless, in +// keeping with the license for jzlib, the copyright to that code is +// included below. +// +// ------------------------------------------------------------------ +// +// The following notice applies to jzlib: +// +// Copyright (c) 2000,2001,2002,2003 ymnk, JCraft,Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// 1. Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// +// 2. Redistributions in binary form must reproduce the above copyright +// notice, this list of conditions and the following disclaimer in +// the documentation and/or other materials provided with the distribution. +// +// 3. The names of the authors may not be used to endorse or promote products +// derived from this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, +// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND +// FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JCRAFT, +// INC. OR ANY CONTRIBUTORS TO THIS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, +// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, +// OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +// EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// ----------------------------------------------------------------------- +// +// jzlib is based on zlib-1.1.3. +// +// The following notice applies to zlib: +// +// ----------------------------------------------------------------------- +// +// Copyright (C) 1995-2004 Jean-loup Gailly and Mark Adler +// +// The ZLIB software is provided 'as-is', without any express or implied +// warranty. In no event will the authors be held liable for any damages +// arising from the use of this software. +// +// Permission is granted to anyone to use this software for any purpose, +// including commercial applications, and to alter it and redistribute it +// freely, subject to the following restrictions: +// +// 1. The origin of this software must not be misrepresented; you must not +// claim that you wrote the original software. If you use this software +// in a product, an acknowledgment in the product documentation would be +// appreciated but is not required. +// 2. Altered source versions must be plainly marked as such, and must not be +// misrepresented as being the original software. +// 3. This notice may not be removed or altered from any source distribution. +// +// Jean-loup Gailly jloup@gzip.org +// Mark Adler madler@alumni.caltech.edu +// +// ----------------------------------------------------------------------- + + + +using System; +using Interop=System.Runtime.InteropServices; + +namespace Ionic.Zlib +{ + + /// + /// Describes how to flush the current deflate operation. + /// + /// + /// The different FlushType values are useful when using a Deflate in a streaming application. + /// + public enum FlushType + { + /// No flush at all. + None = 0, + + /// Closes the current block, but doesn't flush it to + /// the output. Used internally only in hypothetical + /// scenarios. This was supposed to be removed by Zlib, but it is + /// still in use in some edge cases. + /// + Partial, + + /// + /// Use this during compression to specify that all pending output should be + /// flushed to the output buffer and the output should be aligned on a byte + /// boundary. You might use this in a streaming communication scenario, so that + /// the decompressor can get all input data available so far. When using this + /// with a ZlibCodec, AvailableBytesIn will be zero after the call if + /// enough output space has been provided before the call. Flushing will + /// degrade compression and so it should be used only when necessary. + /// + Sync, + + /// + /// Use this during compression to specify that all output should be flushed, as + /// with FlushType.Sync, but also, the compression state should be reset + /// so that decompression can restart from this point if previous compressed + /// data has been damaged or if random access is desired. Using + /// FlushType.Full too often can significantly degrade the compression. + /// + Full, + + /// Signals the end of the compression/decompression stream. + Finish, + } + + + /// + /// The compression level to be used when using a DeflateStream or ZlibStream with CompressionMode.Compress. + /// + public enum CompressionLevel + { + /// + /// None means that the data will be simply stored, with no change at all. + /// If you are producing ZIPs for use on Mac OSX, be aware that archives produced with CompressionLevel.None + /// cannot be opened with the default zip reader. Use a different CompressionLevel. + /// + None= 0, + /// + /// Same as None. + /// + Level0 = 0, + + /// + /// The fastest but least effective compression. + /// + BestSpeed = 1, + + /// + /// A synonym for BestSpeed. + /// + Level1 = 1, + + /// + /// A little slower, but better, than level 1. + /// + Level2 = 2, + + /// + /// A little slower, but better, than level 2. + /// + Level3 = 3, + + /// + /// A little slower, but better, than level 3. + /// + Level4 = 4, + + /// + /// A little slower than level 4, but with better compression. + /// + Level5 = 5, + + /// + /// The default compression level, with a good balance of speed and compression efficiency. + /// + Default = 6, + /// + /// A synonym for Default. + /// + Level6 = 6, + + /// + /// Pretty good compression! + /// + Level7 = 7, + + /// + /// Better compression than Level7! + /// + Level8 = 8, + + /// + /// The "best" compression, where best means greatest reduction in size of the input data stream. + /// This is also the slowest compression. + /// + BestCompression = 9, + + /// + /// A synonym for BestCompression. + /// + Level9 = 9, + } + + /// + /// Describes options for how the compression algorithm is executed. Different strategies + /// work better on different sorts of data. The strategy parameter can affect the compression + /// ratio and the speed of compression but not the correctness of the compresssion. + /// + public enum CompressionStrategy + { + /// + /// The default strategy is probably the best for normal data. + /// + Default = 0, + + /// + /// The Filtered strategy is intended to be used most effectively with data produced by a + /// filter or predictor. By this definition, filtered data consists mostly of small + /// values with a somewhat random distribution. In this case, the compression algorithm + /// is tuned to compress them better. The effect of Filtered is to force more Huffman + /// coding and less string matching; it is a half-step between Default and HuffmanOnly. + /// + Filtered = 1, + + /// + /// Using HuffmanOnly will force the compressor to do Huffman encoding only, with no + /// string matching. + /// + HuffmanOnly = 2, + } + + + /// + /// An enum to specify the direction of transcoding - whether to compress or decompress. + /// + public enum CompressionMode + { + /// + /// Used to specify that the stream should compress the data. + /// + Compress= 0, + /// + /// Used to specify that the stream should decompress the data. + /// + Decompress = 1, + } + + + /// + /// A general purpose exception class for exceptions in the Zlib library. + /// + [Interop.GuidAttribute("ebc25cf6-9120-4283-b972-0e5520d0000E")] + public class ZlibException : System.Exception + { + /// + /// The ZlibException class captures exception information generated + /// by the Zlib library. + /// + public ZlibException() + : base() + { + } + + /// + /// This ctor collects a message attached to the exception. + /// + /// the message for the exception. + public ZlibException(System.String s) + : base(s) + { + } + } + + + internal class SharedUtils + { + /// + /// Performs an unsigned bitwise right shift with the specified number + /// + /// Number to operate on + /// Ammount of bits to shift + /// The resulting number from the shift operation + public static int URShift(int number, int bits) + { + return (int)((uint)number >> bits); + } + +#if NOT + /// + /// Performs an unsigned bitwise right shift with the specified number + /// + /// Number to operate on + /// Ammount of bits to shift + /// The resulting number from the shift operation + public static long URShift(long number, int bits) + { + return (long) ((UInt64)number >> bits); + } +#endif + + /// + /// Reads a number of characters from the current source TextReader and writes + /// the data to the target array at the specified index. + /// + /// + /// The source TextReader to read from + /// Contains the array of characteres read from the source TextReader. + /// The starting index of the target array. + /// The maximum number of characters to read from the source TextReader. + /// + /// + /// The number of characters read. The number will be less than or equal to + /// count depending on the data available in the source TextReader. Returns -1 + /// if the end of the stream is reached. + /// + public static System.Int32 ReadInput(System.IO.TextReader sourceTextReader, byte[] target, int start, int count) + { + // Returns 0 bytes if not enough space in target + if (target.Length == 0) return 0; + + char[] charArray = new char[target.Length]; + int bytesRead = sourceTextReader.Read(charArray, start, count); + + // Returns -1 if EOF + if (bytesRead == 0) return -1; + + for (int index = start; index < start + bytesRead; index++) + target[index] = (byte)charArray[index]; + + return bytesRead; + } + + + internal static byte[] ToByteArray(System.String sourceString) + { + return System.Text.UTF8Encoding.UTF8.GetBytes(sourceString); + } + + + internal static char[] ToCharArray(byte[] byteArray) + { + return System.Text.UTF8Encoding.UTF8.GetChars(byteArray); + } + } + + internal static class InternalConstants + { + internal static readonly int MAX_BITS = 15; + internal static readonly int BL_CODES = 19; + internal static readonly int D_CODES = 30; + internal static readonly int LITERALS = 256; + internal static readonly int LENGTH_CODES = 29; + internal static readonly int L_CODES = (LITERALS + 1 + LENGTH_CODES); + + // Bit length codes must not exceed MAX_BL_BITS bits + internal static readonly int MAX_BL_BITS = 7; + + // repeat previous bit length 3-6 times (2 bits of repeat count) + internal static readonly int REP_3_6 = 16; + + // repeat a zero length 3-10 times (3 bits of repeat count) + internal static readonly int REPZ_3_10 = 17; + + // repeat a zero length 11-138 times (7 bits of repeat count) + internal static readonly int REPZ_11_138 = 18; + + } + + internal sealed class StaticTree + { + internal static readonly short[] lengthAndLiteralsTreeCodes = new short[] { + 12, 8, 140, 8, 76, 8, 204, 8, 44, 8, 172, 8, 108, 8, 236, 8, + 28, 8, 156, 8, 92, 8, 220, 8, 60, 8, 188, 8, 124, 8, 252, 8, + 2, 8, 130, 8, 66, 8, 194, 8, 34, 8, 162, 8, 98, 8, 226, 8, + 18, 8, 146, 8, 82, 8, 210, 8, 50, 8, 178, 8, 114, 8, 242, 8, + 10, 8, 138, 8, 74, 8, 202, 8, 42, 8, 170, 8, 106, 8, 234, 8, + 26, 8, 154, 8, 90, 8, 218, 8, 58, 8, 186, 8, 122, 8, 250, 8, + 6, 8, 134, 8, 70, 8, 198, 8, 38, 8, 166, 8, 102, 8, 230, 8, + 22, 8, 150, 8, 86, 8, 214, 8, 54, 8, 182, 8, 118, 8, 246, 8, + 14, 8, 142, 8, 78, 8, 206, 8, 46, 8, 174, 8, 110, 8, 238, 8, + 30, 8, 158, 8, 94, 8, 222, 8, 62, 8, 190, 8, 126, 8, 254, 8, + 1, 8, 129, 8, 65, 8, 193, 8, 33, 8, 161, 8, 97, 8, 225, 8, + 17, 8, 145, 8, 81, 8, 209, 8, 49, 8, 177, 8, 113, 8, 241, 8, + 9, 8, 137, 8, 73, 8, 201, 8, 41, 8, 169, 8, 105, 8, 233, 8, + 25, 8, 153, 8, 89, 8, 217, 8, 57, 8, 185, 8, 121, 8, 249, 8, + 5, 8, 133, 8, 69, 8, 197, 8, 37, 8, 165, 8, 101, 8, 229, 8, + 21, 8, 149, 8, 85, 8, 213, 8, 53, 8, 181, 8, 117, 8, 245, 8, + 13, 8, 141, 8, 77, 8, 205, 8, 45, 8, 173, 8, 109, 8, 237, 8, + 29, 8, 157, 8, 93, 8, 221, 8, 61, 8, 189, 8, 125, 8, 253, 8, + 19, 9, 275, 9, 147, 9, 403, 9, 83, 9, 339, 9, 211, 9, 467, 9, + 51, 9, 307, 9, 179, 9, 435, 9, 115, 9, 371, 9, 243, 9, 499, 9, + 11, 9, 267, 9, 139, 9, 395, 9, 75, 9, 331, 9, 203, 9, 459, 9, + 43, 9, 299, 9, 171, 9, 427, 9, 107, 9, 363, 9, 235, 9, 491, 9, + 27, 9, 283, 9, 155, 9, 411, 9, 91, 9, 347, 9, 219, 9, 475, 9, + 59, 9, 315, 9, 187, 9, 443, 9, 123, 9, 379, 9, 251, 9, 507, 9, + 7, 9, 263, 9, 135, 9, 391, 9, 71, 9, 327, 9, 199, 9, 455, 9, + 39, 9, 295, 9, 167, 9, 423, 9, 103, 9, 359, 9, 231, 9, 487, 9, + 23, 9, 279, 9, 151, 9, 407, 9, 87, 9, 343, 9, 215, 9, 471, 9, + 55, 9, 311, 9, 183, 9, 439, 9, 119, 9, 375, 9, 247, 9, 503, 9, + 15, 9, 271, 9, 143, 9, 399, 9, 79, 9, 335, 9, 207, 9, 463, 9, + 47, 9, 303, 9, 175, 9, 431, 9, 111, 9, 367, 9, 239, 9, 495, 9, + 31, 9, 287, 9, 159, 9, 415, 9, 95, 9, 351, 9, 223, 9, 479, 9, + 63, 9, 319, 9, 191, 9, 447, 9, 127, 9, 383, 9, 255, 9, 511, 9, + 0, 7, 64, 7, 32, 7, 96, 7, 16, 7, 80, 7, 48, 7, 112, 7, + 8, 7, 72, 7, 40, 7, 104, 7, 24, 7, 88, 7, 56, 7, 120, 7, + 4, 7, 68, 7, 36, 7, 100, 7, 20, 7, 84, 7, 52, 7, 116, 7, + 3, 8, 131, 8, 67, 8, 195, 8, 35, 8, 163, 8, 99, 8, 227, 8 + }; + + internal static readonly short[] distTreeCodes = new short[] { + 0, 5, 16, 5, 8, 5, 24, 5, 4, 5, 20, 5, 12, 5, 28, 5, + 2, 5, 18, 5, 10, 5, 26, 5, 6, 5, 22, 5, 14, 5, 30, 5, + 1, 5, 17, 5, 9, 5, 25, 5, 5, 5, 21, 5, 13, 5, 29, 5, + 3, 5, 19, 5, 11, 5, 27, 5, 7, 5, 23, 5 }; + + internal static readonly StaticTree Literals; + internal static readonly StaticTree Distances; + internal static readonly StaticTree BitLengths; + + internal short[] treeCodes; // static tree or null + internal int[] extraBits; // extra bits for each code or null + internal int extraBase; // base index for extra_bits + internal int elems; // max number of elements in the tree + internal int maxLength; // max bit length for the codes + + private StaticTree(short[] treeCodes, int[] extraBits, int extraBase, int elems, int maxLength) + { + this.treeCodes = treeCodes; + this.extraBits = extraBits; + this.extraBase = extraBase; + this.elems = elems; + this.maxLength = maxLength; + } + static StaticTree() + { + Literals = new StaticTree(lengthAndLiteralsTreeCodes, Tree.ExtraLengthBits, InternalConstants.LITERALS + 1, InternalConstants.L_CODES, InternalConstants.MAX_BITS); + Distances = new StaticTree(distTreeCodes, Tree.ExtraDistanceBits, 0, InternalConstants.D_CODES, InternalConstants.MAX_BITS); + BitLengths = new StaticTree(null, Tree.extra_blbits, 0, InternalConstants.BL_CODES, InternalConstants.MAX_BL_BITS); + } + } + + + + /// + /// Computes an Adler-32 checksum. + /// + /// + /// The Adler checksum is similar to a CRC checksum, but faster to compute, though less + /// reliable. It is used in producing RFC1950 compressed streams. The Adler checksum + /// is a required part of the "ZLIB" standard. Applications will almost never need to + /// use this class directly. + /// + /// + /// + public sealed class Adler + { + // largest prime smaller than 65536 + private static readonly uint BASE = 65521; + // NMAX is the largest n such that 255n(n+1)/2 + (n+1)(BASE-1) <= 2^32-1 + private static readonly int NMAX = 5552; + + +#pragma warning disable 3001 +#pragma warning disable 3002 + + /// + /// Calculates the Adler32 checksum. + /// + /// + /// + /// This is used within ZLIB. You probably don't need to use this directly. + /// + /// + /// + /// To compute an Adler32 checksum on a byte array: + /// + /// var adler = Adler.Adler32(0, null, 0, 0); + /// adler = Adler.Adler32(adler, buffer, index, length); + /// + /// + public static uint Adler32(uint adler, byte[] buf, int index, int len) + { + if (buf == null) + return 1; + + uint s1 = (uint) (adler & 0xffff); + uint s2 = (uint) ((adler >> 16) & 0xffff); + + while (len > 0) + { + int k = len < NMAX ? len : NMAX; + len -= k; + while (k >= 16) + { + //s1 += (buf[index++] & 0xff); s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + s1 += buf[index++]; s2 += s1; + k -= 16; + } + if (k != 0) + { + do + { + s1 += buf[index++]; + s2 += s1; + } + while (--k != 0); + } + s1 %= BASE; + s2 %= BASE; + } + return (uint)((s2 << 16) | s1); + } +#pragma warning restore 3001 +#pragma warning restore 3002 + + } + +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/Zlib/ZlibBaseStream.cs b/Resources/Libraries/DotNetZip/Source/Zlib/ZlibBaseStream.cs new file mode 100644 index 00000000..8243eeca --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zlib/ZlibBaseStream.cs @@ -0,0 +1,627 @@ +// ZlibBaseStream.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa and Microsoft Corporation. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-August-06 21:22:38> +// +// ------------------------------------------------------------------ +// +// This module defines the ZlibBaseStream class, which is an intnernal +// base class for DeflateStream, ZlibStream and GZipStream. +// +// ------------------------------------------------------------------ + +using System; +using System.IO; + +namespace Ionic.Zlib +{ + + internal enum ZlibStreamFlavor { ZLIB = 1950, DEFLATE = 1951, GZIP = 1952 } + + internal class ZlibBaseStream : System.IO.Stream + { + protected internal ZlibCodec _z = null; // deferred init... new ZlibCodec(); + + protected internal StreamMode _streamMode = StreamMode.Undefined; + protected internal FlushType _flushMode; + protected internal ZlibStreamFlavor _flavor; + protected internal CompressionMode _compressionMode; + protected internal CompressionLevel _level; + protected internal bool _leaveOpen; + protected internal byte[] _workingBuffer; + protected internal int _bufferSize = ZlibConstants.WorkingBufferSizeDefault; + protected internal byte[] _buf1 = new byte[1]; + + protected internal System.IO.Stream _stream; + protected internal CompressionStrategy Strategy = CompressionStrategy.Default; + + // workitem 7159 + Ionic.Crc.CRC32 crc; + protected internal string _GzipFileName; + protected internal string _GzipComment; + protected internal DateTime _GzipMtime; + protected internal int _gzipHeaderByteCount; + + internal int Crc32 { get { if (crc == null) return 0; return crc.Crc32Result; } } + + public ZlibBaseStream(System.IO.Stream stream, + CompressionMode compressionMode, + CompressionLevel level, + ZlibStreamFlavor flavor, + bool leaveOpen) + : base() + { + this._flushMode = FlushType.None; + //this._workingBuffer = new byte[WORKING_BUFFER_SIZE_DEFAULT]; + this._stream = stream; + this._leaveOpen = leaveOpen; + this._compressionMode = compressionMode; + this._flavor = flavor; + this._level = level; + // workitem 7159 + if (flavor == ZlibStreamFlavor.GZIP) + { + this.crc = new Ionic.Crc.CRC32(); + } + } + + + protected internal bool _wantCompress + { + get + { + return (this._compressionMode == CompressionMode.Compress); + } + } + + private ZlibCodec z + { + get + { + if (_z == null) + { + bool wantRfc1950Header = (this._flavor == ZlibStreamFlavor.ZLIB); + _z = new ZlibCodec(); + if (this._compressionMode == CompressionMode.Decompress) + { + _z.InitializeInflate(wantRfc1950Header); + } + else + { + _z.Strategy = Strategy; + _z.InitializeDeflate(this._level, wantRfc1950Header); + } + } + return _z; + } + } + + + + private byte[] workingBuffer + { + get + { + if (_workingBuffer == null) + _workingBuffer = new byte[_bufferSize]; + return _workingBuffer; + } + } + + + + public override void Write(System.Byte[] buffer, int offset, int count) + { + // workitem 7159 + // calculate the CRC on the unccompressed data (before writing) + if (crc != null) + crc.SlurpBlock(buffer, offset, count); + + if (_streamMode == StreamMode.Undefined) + _streamMode = StreamMode.Writer; + else if (_streamMode != StreamMode.Writer) + throw new ZlibException("Cannot Write after Reading."); + + if (count == 0) + return; + + // first reference of z property will initialize the private var _z + z.InputBuffer = buffer; + _z.NextIn = offset; + _z.AvailableBytesIn = count; + bool done = false; + do + { + _z.OutputBuffer = workingBuffer; + _z.NextOut = 0; + _z.AvailableBytesOut = _workingBuffer.Length; + int rc = (_wantCompress) + ? _z.Deflate(_flushMode) + : _z.Inflate(_flushMode); + if (rc != ZlibConstants.Z_OK && rc != ZlibConstants.Z_STREAM_END) + throw new ZlibException((_wantCompress ? "de" : "in") + "flating: " + _z.Message); + + //if (_workingBuffer.Length - _z.AvailableBytesOut > 0) + _stream.Write(_workingBuffer, 0, _workingBuffer.Length - _z.AvailableBytesOut); + + done = _z.AvailableBytesIn == 0 && _z.AvailableBytesOut != 0; + + // If GZIP and de-compress, we're done when 8 bytes remain. + if (_flavor == ZlibStreamFlavor.GZIP && !_wantCompress) + done = (_z.AvailableBytesIn == 8 && _z.AvailableBytesOut != 0); + + } + while (!done); + } + + + + private void finish() + { + if (_z == null) return; + + if (_streamMode == StreamMode.Writer) + { + bool done = false; + do + { + _z.OutputBuffer = workingBuffer; + _z.NextOut = 0; + _z.AvailableBytesOut = _workingBuffer.Length; + int rc = (_wantCompress) + ? _z.Deflate(FlushType.Finish) + : _z.Inflate(FlushType.Finish); + + if (rc != ZlibConstants.Z_STREAM_END && rc != ZlibConstants.Z_OK) + { + string verb = (_wantCompress ? "de" : "in") + "flating"; + if (_z.Message == null) + throw new ZlibException(String.Format("{0}: (rc = {1})", verb, rc)); + else + throw new ZlibException(verb + ": " + _z.Message); + } + + if (_workingBuffer.Length - _z.AvailableBytesOut > 0) + { + _stream.Write(_workingBuffer, 0, _workingBuffer.Length - _z.AvailableBytesOut); + } + + done = _z.AvailableBytesIn == 0 && _z.AvailableBytesOut != 0; + // If GZIP and de-compress, we're done when 8 bytes remain. + if (_flavor == ZlibStreamFlavor.GZIP && !_wantCompress) + done = (_z.AvailableBytesIn == 8 && _z.AvailableBytesOut != 0); + + } + while (!done); + + Flush(); + + // workitem 7159 + if (_flavor == ZlibStreamFlavor.GZIP) + { + if (_wantCompress) + { + // Emit the GZIP trailer: CRC32 and size mod 2^32 + int c1 = crc.Crc32Result; + _stream.Write(BitConverter.GetBytes(c1), 0, 4); + int c2 = (Int32)(crc.TotalBytesRead & 0x00000000FFFFFFFF); + _stream.Write(BitConverter.GetBytes(c2), 0, 4); + } + else + { + throw new ZlibException("Writing with decompression is not supported."); + } + } + } + // workitem 7159 + else if (_streamMode == StreamMode.Reader) + { + if (_flavor == ZlibStreamFlavor.GZIP) + { + if (!_wantCompress) + { + // workitem 8501: handle edge case (decompress empty stream) + if (_z.TotalBytesOut == 0L) + return; + + // Read and potentially verify the GZIP trailer: + // CRC32 and size mod 2^32 + byte[] trailer = new byte[8]; + + // workitems 8679 & 12554 + if (_z.AvailableBytesIn < 8) + { + // Make sure we have read to the end of the stream + Array.Copy(_z.InputBuffer, _z.NextIn, trailer, 0, _z.AvailableBytesIn); + int bytesNeeded = 8 - _z.AvailableBytesIn; + int bytesRead = _stream.Read(trailer, + _z.AvailableBytesIn, + bytesNeeded); + if (bytesNeeded != bytesRead) + { + throw new ZlibException(String.Format("Missing or incomplete GZIP trailer. Expected 8 bytes, got {0}.", + _z.AvailableBytesIn + bytesRead)); + } + } + else + { + Array.Copy(_z.InputBuffer, _z.NextIn, trailer, 0, trailer.Length); + } + + Int32 crc32_expected = BitConverter.ToInt32(trailer, 0); + Int32 crc32_actual = crc.Crc32Result; + Int32 isize_expected = BitConverter.ToInt32(trailer, 4); + Int32 isize_actual = (Int32)(_z.TotalBytesOut & 0x00000000FFFFFFFF); + + if (crc32_actual != crc32_expected) + throw new ZlibException(String.Format("Bad CRC32 in GZIP trailer. (actual({0:X8})!=expected({1:X8}))", crc32_actual, crc32_expected)); + + if (isize_actual != isize_expected) + throw new ZlibException(String.Format("Bad size in GZIP trailer. (actual({0})!=expected({1}))", isize_actual, isize_expected)); + + } + else + { + throw new ZlibException("Reading with compression is not supported."); + } + } + } + } + + + private void end() + { + if (z == null) + return; + if (_wantCompress) + { + _z.EndDeflate(); + } + else + { + _z.EndInflate(); + } + _z = null; + } + + + public override void Close() + { + if (_stream == null) return; + try + { + finish(); + } + finally + { + end(); + if (!_leaveOpen) _stream.Close(); + _stream = null; + } + } + + public override void Flush() + { + _stream.Flush(); + } + + public override System.Int64 Seek(System.Int64 offset, System.IO.SeekOrigin origin) + { + throw new NotImplementedException(); + //_outStream.Seek(offset, origin); + } + public override void SetLength(System.Int64 value) + { + _stream.SetLength(value); + } + + +#if NOT + public int Read() + { + if (Read(_buf1, 0, 1) == 0) + return 0; + // calculate CRC after reading + if (crc!=null) + crc.SlurpBlock(_buf1,0,1); + return (_buf1[0] & 0xFF); + } +#endif + + private bool nomoreinput = false; + + + + private string ReadZeroTerminatedString() + { + var list = new System.Collections.Generic.List(); + bool done = false; + do + { + // workitem 7740 + int n = _stream.Read(_buf1, 0, 1); + if (n != 1) + throw new ZlibException("Unexpected EOF reading GZIP header."); + else + { + if (_buf1[0] == 0) + done = true; + else + list.Add(_buf1[0]); + } + } while (!done); + byte[] a = list.ToArray(); + return GZipStream.iso8859dash1.GetString(a, 0, a.Length); + } + + + private int _ReadAndValidateGzipHeader() + { + int totalBytesRead = 0; + // read the header on the first read + byte[] header = new byte[10]; + int n = _stream.Read(header, 0, header.Length); + + // workitem 8501: handle edge case (decompress empty stream) + if (n == 0) + return 0; + + if (n != 10) + throw new ZlibException("Not a valid GZIP stream."); + + if (header[0] != 0x1F || header[1] != 0x8B || header[2] != 8) + throw new ZlibException("Bad GZIP header."); + + Int32 timet = BitConverter.ToInt32(header, 4); + _GzipMtime = GZipStream._unixEpoch.AddSeconds(timet); + totalBytesRead += n; + if ((header[3] & 0x04) == 0x04) + { + // read and discard extra field + n = _stream.Read(header, 0, 2); // 2-byte length field + totalBytesRead += n; + + Int16 extraLength = (Int16)(header[0] + header[1] * 256); + byte[] extra = new byte[extraLength]; + n = _stream.Read(extra, 0, extra.Length); + if (n != extraLength) + throw new ZlibException("Unexpected end-of-file reading GZIP header."); + totalBytesRead += n; + } + if ((header[3] & 0x08) == 0x08) + _GzipFileName = ReadZeroTerminatedString(); + if ((header[3] & 0x10) == 0x010) + _GzipComment = ReadZeroTerminatedString(); + if ((header[3] & 0x02) == 0x02) + Read(_buf1, 0, 1); // CRC16, ignore + + return totalBytesRead; + } + + + + public override System.Int32 Read(System.Byte[] buffer, System.Int32 offset, System.Int32 count) + { + // According to MS documentation, any implementation of the IO.Stream.Read function must: + // (a) throw an exception if offset & count reference an invalid part of the buffer, + // or if count < 0, or if buffer is null + // (b) return 0 only upon EOF, or if count = 0 + // (c) if not EOF, then return at least 1 byte, up to bytes + + if (_streamMode == StreamMode.Undefined) + { + if (!this._stream.CanRead) throw new ZlibException("The stream is not readable."); + // for the first read, set up some controls. + _streamMode = StreamMode.Reader; + // (The first reference to _z goes through the private accessor which + // may initialize it.) + z.AvailableBytesIn = 0; + if (_flavor == ZlibStreamFlavor.GZIP) + { + _gzipHeaderByteCount = _ReadAndValidateGzipHeader(); + // workitem 8501: handle edge case (decompress empty stream) + if (_gzipHeaderByteCount == 0) + return 0; + } + } + + if (_streamMode != StreamMode.Reader) + throw new ZlibException("Cannot Read after Writing."); + + if (count == 0) return 0; + if (nomoreinput && _wantCompress) return 0; // workitem 8557 + if (buffer == null) throw new ArgumentNullException("buffer"); + if (count < 0) throw new ArgumentOutOfRangeException("count"); + if (offset < buffer.GetLowerBound(0)) throw new ArgumentOutOfRangeException("offset"); + if ((offset + count) > buffer.GetLength(0)) throw new ArgumentOutOfRangeException("count"); + + int rc = 0; + + // set up the output of the deflate/inflate codec: + _z.OutputBuffer = buffer; + _z.NextOut = offset; + _z.AvailableBytesOut = count; + + // This is necessary in case _workingBuffer has been resized. (new byte[]) + // (The first reference to _workingBuffer goes through the private accessor which + // may initialize it.) + _z.InputBuffer = workingBuffer; + + do + { + // need data in _workingBuffer in order to deflate/inflate. Here, we check if we have any. + if ((_z.AvailableBytesIn == 0) && (!nomoreinput)) + { + // No data available, so try to Read data from the captive stream. + _z.NextIn = 0; + _z.AvailableBytesIn = _stream.Read(_workingBuffer, 0, _workingBuffer.Length); + if (_z.AvailableBytesIn == 0) + nomoreinput = true; + + } + // we have data in InputBuffer; now compress or decompress as appropriate + rc = (_wantCompress) + ? _z.Deflate(_flushMode) + : _z.Inflate(_flushMode); + + if (nomoreinput && (rc == ZlibConstants.Z_BUF_ERROR)) + return 0; + + if (rc != ZlibConstants.Z_OK && rc != ZlibConstants.Z_STREAM_END) + throw new ZlibException(String.Format("{0}flating: rc={1} msg={2}", (_wantCompress ? "de" : "in"), rc, _z.Message)); + + if ((nomoreinput || rc == ZlibConstants.Z_STREAM_END) && (_z.AvailableBytesOut == count)) + break; // nothing more to read + } + //while (_z.AvailableBytesOut == count && rc == ZlibConstants.Z_OK); + while (_z.AvailableBytesOut > 0 && !nomoreinput && rc == ZlibConstants.Z_OK); + + + // workitem 8557 + // is there more room in output? + if (_z.AvailableBytesOut > 0) + { + if (rc == ZlibConstants.Z_OK && _z.AvailableBytesIn == 0) + { + // deferred + } + + // are we completely done reading? + if (nomoreinput) + { + // and in compression? + if (_wantCompress) + { + // no more input data available; therefore we flush to + // try to complete the read + rc = _z.Deflate(FlushType.Finish); + + if (rc != ZlibConstants.Z_OK && rc != ZlibConstants.Z_STREAM_END) + throw new ZlibException(String.Format("Deflating: rc={0} msg={1}", rc, _z.Message)); + } + } + } + + + rc = (count - _z.AvailableBytesOut); + + // calculate CRC after reading + if (crc != null) + crc.SlurpBlock(buffer, offset, rc); + + return rc; + } + + + + public override System.Boolean CanRead + { + get { return this._stream.CanRead; } + } + + public override System.Boolean CanSeek + { + get { return this._stream.CanSeek; } + } + + public override System.Boolean CanWrite + { + get { return this._stream.CanWrite; } + } + + public override System.Int64 Length + { + get { return _stream.Length; } + } + + public override long Position + { + get { throw new NotImplementedException(); } + set { throw new NotImplementedException(); } + } + + internal enum StreamMode + { + Writer, + Reader, + Undefined, + } + + + public static void CompressString(String s, Stream compressor) + { + byte[] uncompressed = System.Text.Encoding.UTF8.GetBytes(s); + using (compressor) + { + compressor.Write(uncompressed, 0, uncompressed.Length); + } + } + + public static void CompressBuffer(byte[] b, Stream compressor) + { + // workitem 8460 + using (compressor) + { + compressor.Write(b, 0, b.Length); + } + } + + public static String UncompressString(byte[] compressed, Stream decompressor) + { + // workitem 8460 + byte[] working = new byte[1024]; + var encoding = System.Text.Encoding.UTF8; + using (var output = new MemoryStream()) + { + using (decompressor) + { + int n; + while ((n = decompressor.Read(working, 0, working.Length)) != 0) + { + output.Write(working, 0, n); + } + } + + // reset to allow read from start + output.Seek(0, SeekOrigin.Begin); + var sr = new StreamReader(output, encoding); + return sr.ReadToEnd(); + } + } + + public static byte[] UncompressBuffer(byte[] compressed, Stream decompressor) + { + // workitem 8460 + byte[] working = new byte[1024]; + using (var output = new MemoryStream()) + { + using (decompressor) + { + int n; + while ((n = decompressor.Read(working, 0, working.Length)) != 0) + { + output.Write(working, 0, n); + } + } + return output.ToArray(); + } + } + + } + + +} diff --git a/Resources/Libraries/DotNetZip/Source/Zlib/ZlibCodec.cs b/Resources/Libraries/DotNetZip/Source/Zlib/ZlibCodec.cs new file mode 100644 index 00000000..813d2481 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zlib/ZlibCodec.cs @@ -0,0 +1,717 @@ +// ZlibCodec.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa and Microsoft Corporation. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2009-November-03 15:40:51> +// +// ------------------------------------------------------------------ +// +// This module defines a Codec for ZLIB compression and +// decompression. This code extends code that was based the jzlib +// implementation of zlib, but this code is completely novel. The codec +// class is new, and encapsulates some behaviors that are new, and some +// that were present in other classes in the jzlib code base. In +// keeping with the license for jzlib, the copyright to the jzlib code +// is included below. +// +// ------------------------------------------------------------------ +// +// Copyright (c) 2000,2001,2002,2003 ymnk, JCraft,Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// 1. Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// +// 2. Redistributions in binary form must reproduce the above copyright +// notice, this list of conditions and the following disclaimer in +// the documentation and/or other materials provided with the distribution. +// +// 3. The names of the authors may not be used to endorse or promote products +// derived from this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, +// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND +// FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JCRAFT, +// INC. OR ANY CONTRIBUTORS TO THIS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, +// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, +// OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +// EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// ----------------------------------------------------------------------- +// +// This program is based on zlib-1.1.3; credit to authors +// Jean-loup Gailly(jloup@gzip.org) and Mark Adler(madler@alumni.caltech.edu) +// and contributors of zlib. +// +// ----------------------------------------------------------------------- + + +using System; +using Interop=System.Runtime.InteropServices; + +namespace Ionic.Zlib +{ + /// + /// Encoder and Decoder for ZLIB and DEFLATE (IETF RFC1950 and RFC1951). + /// + /// + /// + /// This class compresses and decompresses data according to the Deflate algorithm + /// and optionally, the ZLIB format, as documented in RFC 1950 - ZLIB and RFC 1951 - DEFLATE. + /// + [Interop.GuidAttribute("ebc25cf6-9120-4283-b972-0e5520d0000D")] + [Interop.ComVisible(true)] +#if !NETCF + [Interop.ClassInterface(Interop.ClassInterfaceType.AutoDispatch)] +#endif + sealed public class ZlibCodec + { + /// + /// The buffer from which data is taken. + /// + public byte[] InputBuffer; + + /// + /// An index into the InputBuffer array, indicating where to start reading. + /// + public int NextIn; + + /// + /// The number of bytes available in the InputBuffer, starting at NextIn. + /// + /// + /// Generally you should set this to InputBuffer.Length before the first Inflate() or Deflate() call. + /// The class will update this number as calls to Inflate/Deflate are made. + /// + public int AvailableBytesIn; + + /// + /// Total number of bytes read so far, through all calls to Inflate()/Deflate(). + /// + public long TotalBytesIn; + + /// + /// Buffer to store output data. + /// + public byte[] OutputBuffer; + + /// + /// An index into the OutputBuffer array, indicating where to start writing. + /// + public int NextOut; + + /// + /// The number of bytes available in the OutputBuffer, starting at NextOut. + /// + /// + /// Generally you should set this to OutputBuffer.Length before the first Inflate() or Deflate() call. + /// The class will update this number as calls to Inflate/Deflate are made. + /// + public int AvailableBytesOut; + + /// + /// Total number of bytes written to the output so far, through all calls to Inflate()/Deflate(). + /// + public long TotalBytesOut; + + /// + /// used for diagnostics, when something goes wrong! + /// + public System.String Message; + + internal DeflateManager dstate; + internal InflateManager istate; + + internal uint _Adler32; + + /// + /// The compression level to use in this codec. Useful only in compression mode. + /// + public CompressionLevel CompressLevel = CompressionLevel.Default; + + /// + /// The number of Window Bits to use. + /// + /// + /// This gauges the size of the sliding window, and hence the + /// compression effectiveness as well as memory consumption. It's best to just leave this + /// setting alone if you don't know what it is. The maximum value is 15 bits, which implies + /// a 32k window. + /// + public int WindowBits = ZlibConstants.WindowBitsDefault; + + /// + /// The compression strategy to use. + /// + /// + /// This is only effective in compression. The theory offered by ZLIB is that different + /// strategies could potentially produce significant differences in compression behavior + /// for different data sets. Unfortunately I don't have any good recommendations for how + /// to set it differently. When I tested changing the strategy I got minimally different + /// compression performance. It's best to leave this property alone if you don't have a + /// good feel for it. Or, you may want to produce a test harness that runs through the + /// different strategy options and evaluates them on different file types. If you do that, + /// let me know your results. + /// + public CompressionStrategy Strategy = CompressionStrategy.Default; + + + /// + /// The Adler32 checksum on the data transferred through the codec so far. You probably don't need to look at this. + /// + public int Adler32 { get { return (int)_Adler32; } } + + + /// + /// Create a ZlibCodec. + /// + /// + /// If you use this default constructor, you will later have to explicitly call + /// InitializeInflate() or InitializeDeflate() before using the ZlibCodec to compress + /// or decompress. + /// + public ZlibCodec() { } + + /// + /// Create a ZlibCodec that either compresses or decompresses. + /// + /// + /// Indicates whether the codec should compress (deflate) or decompress (inflate). + /// + public ZlibCodec(CompressionMode mode) + { + if (mode == CompressionMode.Compress) + { + int rc = InitializeDeflate(); + if (rc != ZlibConstants.Z_OK) throw new ZlibException("Cannot initialize for deflate."); + } + else if (mode == CompressionMode.Decompress) + { + int rc = InitializeInflate(); + if (rc != ZlibConstants.Z_OK) throw new ZlibException("Cannot initialize for inflate."); + } + else throw new ZlibException("Invalid ZlibStreamFlavor."); + } + + /// + /// Initialize the inflation state. + /// + /// + /// It is not necessary to call this before using the ZlibCodec to inflate data; + /// It is implicitly called when you call the constructor. + /// + /// Z_OK if everything goes well. + public int InitializeInflate() + { + return InitializeInflate(this.WindowBits); + } + + /// + /// Initialize the inflation state with an explicit flag to + /// govern the handling of RFC1950 header bytes. + /// + /// + /// + /// By default, the ZLIB header defined in RFC 1950 is expected. If + /// you want to read a zlib stream you should specify true for + /// expectRfc1950Header. If you have a deflate stream, you will want to specify + /// false. It is only necessary to invoke this initializer explicitly if you + /// want to specify false. + /// + /// + /// whether to expect an RFC1950 header byte + /// pair when reading the stream of data to be inflated. + /// + /// Z_OK if everything goes well. + public int InitializeInflate(bool expectRfc1950Header) + { + return InitializeInflate(this.WindowBits, expectRfc1950Header); + } + + /// + /// Initialize the ZlibCodec for inflation, with the specified number of window bits. + /// + /// The number of window bits to use. If you need to ask what that is, + /// then you shouldn't be calling this initializer. + /// Z_OK if all goes well. + public int InitializeInflate(int windowBits) + { + this.WindowBits = windowBits; + return InitializeInflate(windowBits, true); + } + + /// + /// Initialize the inflation state with an explicit flag to govern the handling of + /// RFC1950 header bytes. + /// + /// + /// + /// If you want to read a zlib stream you should specify true for + /// expectRfc1950Header. In this case, the library will expect to find a ZLIB + /// header, as defined in RFC + /// 1950, in the compressed stream. If you will be reading a DEFLATE or + /// GZIP stream, which does not have such a header, you will want to specify + /// false. + /// + /// + /// whether to expect an RFC1950 header byte pair when reading + /// the stream of data to be inflated. + /// The number of window bits to use. If you need to ask what that is, + /// then you shouldn't be calling this initializer. + /// Z_OK if everything goes well. + public int InitializeInflate(int windowBits, bool expectRfc1950Header) + { + this.WindowBits = windowBits; + if (dstate != null) throw new ZlibException("You may not call InitializeInflate() after calling InitializeDeflate()."); + istate = new InflateManager(expectRfc1950Header); + return istate.Initialize(this, windowBits); + } + + /// + /// Inflate the data in the InputBuffer, placing the result in the OutputBuffer. + /// + /// + /// You must have set InputBuffer and OutputBuffer, NextIn and NextOut, and AvailableBytesIn and + /// AvailableBytesOut before calling this method. + /// + /// + /// + /// private void InflateBuffer() + /// { + /// int bufferSize = 1024; + /// byte[] buffer = new byte[bufferSize]; + /// ZlibCodec decompressor = new ZlibCodec(); + /// + /// Console.WriteLine("\n============================================"); + /// Console.WriteLine("Size of Buffer to Inflate: {0} bytes.", CompressedBytes.Length); + /// MemoryStream ms = new MemoryStream(DecompressedBytes); + /// + /// int rc = decompressor.InitializeInflate(); + /// + /// decompressor.InputBuffer = CompressedBytes; + /// decompressor.NextIn = 0; + /// decompressor.AvailableBytesIn = CompressedBytes.Length; + /// + /// decompressor.OutputBuffer = buffer; + /// + /// // pass 1: inflate + /// do + /// { + /// decompressor.NextOut = 0; + /// decompressor.AvailableBytesOut = buffer.Length; + /// rc = decompressor.Inflate(FlushType.None); + /// + /// if (rc != ZlibConstants.Z_OK && rc != ZlibConstants.Z_STREAM_END) + /// throw new Exception("inflating: " + decompressor.Message); + /// + /// ms.Write(decompressor.OutputBuffer, 0, buffer.Length - decompressor.AvailableBytesOut); + /// } + /// while (decompressor.AvailableBytesIn > 0 || decompressor.AvailableBytesOut == 0); + /// + /// // pass 2: finish and flush + /// do + /// { + /// decompressor.NextOut = 0; + /// decompressor.AvailableBytesOut = buffer.Length; + /// rc = decompressor.Inflate(FlushType.Finish); + /// + /// if (rc != ZlibConstants.Z_STREAM_END && rc != ZlibConstants.Z_OK) + /// throw new Exception("inflating: " + decompressor.Message); + /// + /// if (buffer.Length - decompressor.AvailableBytesOut > 0) + /// ms.Write(buffer, 0, buffer.Length - decompressor.AvailableBytesOut); + /// } + /// while (decompressor.AvailableBytesIn > 0 || decompressor.AvailableBytesOut == 0); + /// + /// decompressor.EndInflate(); + /// } + /// + /// + /// + /// The flush to use when inflating. + /// Z_OK if everything goes well. + public int Inflate(FlushType flush) + { + if (istate == null) + throw new ZlibException("No Inflate State!"); + return istate.Inflate(flush); + } + + + /// + /// Ends an inflation session. + /// + /// + /// Call this after successively calling Inflate(). This will cause all buffers to be flushed. + /// After calling this you cannot call Inflate() without a intervening call to one of the + /// InitializeInflate() overloads. + /// + /// Z_OK if everything goes well. + public int EndInflate() + { + if (istate == null) + throw new ZlibException("No Inflate State!"); + int ret = istate.End(); + istate = null; + return ret; + } + + /// + /// I don't know what this does! + /// + /// Z_OK if everything goes well. + public int SyncInflate() + { + if (istate == null) + throw new ZlibException("No Inflate State!"); + return istate.Sync(); + } + + /// + /// Initialize the ZlibCodec for deflation operation. + /// + /// + /// The codec will use the MAX window bits and the default level of compression. + /// + /// + /// + /// int bufferSize = 40000; + /// byte[] CompressedBytes = new byte[bufferSize]; + /// byte[] DecompressedBytes = new byte[bufferSize]; + /// + /// ZlibCodec compressor = new ZlibCodec(); + /// + /// compressor.InitializeDeflate(CompressionLevel.Default); + /// + /// compressor.InputBuffer = System.Text.ASCIIEncoding.ASCII.GetBytes(TextToCompress); + /// compressor.NextIn = 0; + /// compressor.AvailableBytesIn = compressor.InputBuffer.Length; + /// + /// compressor.OutputBuffer = CompressedBytes; + /// compressor.NextOut = 0; + /// compressor.AvailableBytesOut = CompressedBytes.Length; + /// + /// while (compressor.TotalBytesIn != TextToCompress.Length && compressor.TotalBytesOut < bufferSize) + /// { + /// compressor.Deflate(FlushType.None); + /// } + /// + /// while (true) + /// { + /// int rc= compressor.Deflate(FlushType.Finish); + /// if (rc == ZlibConstants.Z_STREAM_END) break; + /// } + /// + /// compressor.EndDeflate(); + /// + /// + /// + /// Z_OK if all goes well. You generally don't need to check the return code. + public int InitializeDeflate() + { + return _InternalInitializeDeflate(true); + } + + /// + /// Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel. + /// + /// + /// The codec will use the maximum window bits (15) and the specified + /// CompressionLevel. It will emit a ZLIB stream as it compresses. + /// + /// The compression level for the codec. + /// Z_OK if all goes well. + public int InitializeDeflate(CompressionLevel level) + { + this.CompressLevel = level; + return _InternalInitializeDeflate(true); + } + + + /// + /// Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel, + /// and the explicit flag governing whether to emit an RFC1950 header byte pair. + /// + /// + /// The codec will use the maximum window bits (15) and the specified CompressionLevel. + /// If you want to generate a zlib stream, you should specify true for + /// wantRfc1950Header. In this case, the library will emit a ZLIB + /// header, as defined in RFC + /// 1950, in the compressed stream. + /// + /// The compression level for the codec. + /// whether to emit an initial RFC1950 byte pair in the compressed stream. + /// Z_OK if all goes well. + public int InitializeDeflate(CompressionLevel level, bool wantRfc1950Header) + { + this.CompressLevel = level; + return _InternalInitializeDeflate(wantRfc1950Header); + } + + + /// + /// Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel, + /// and the specified number of window bits. + /// + /// + /// The codec will use the specified number of window bits and the specified CompressionLevel. + /// + /// The compression level for the codec. + /// the number of window bits to use. If you don't know what this means, don't use this method. + /// Z_OK if all goes well. + public int InitializeDeflate(CompressionLevel level, int bits) + { + this.CompressLevel = level; + this.WindowBits = bits; + return _InternalInitializeDeflate(true); + } + + /// + /// Initialize the ZlibCodec for deflation operation, using the specified + /// CompressionLevel, the specified number of window bits, and the explicit flag + /// governing whether to emit an RFC1950 header byte pair. + /// + /// + /// The compression level for the codec. + /// whether to emit an initial RFC1950 byte pair in the compressed stream. + /// the number of window bits to use. If you don't know what this means, don't use this method. + /// Z_OK if all goes well. + public int InitializeDeflate(CompressionLevel level, int bits, bool wantRfc1950Header) + { + this.CompressLevel = level; + this.WindowBits = bits; + return _InternalInitializeDeflate(wantRfc1950Header); + } + + private int _InternalInitializeDeflate(bool wantRfc1950Header) + { + if (istate != null) throw new ZlibException("You may not call InitializeDeflate() after calling InitializeInflate()."); + dstate = new DeflateManager(); + dstate.WantRfc1950HeaderBytes = wantRfc1950Header; + + return dstate.Initialize(this, this.CompressLevel, this.WindowBits, this.Strategy); + } + + /// + /// Deflate one batch of data. + /// + /// + /// You must have set InputBuffer and OutputBuffer before calling this method. + /// + /// + /// + /// private void DeflateBuffer(CompressionLevel level) + /// { + /// int bufferSize = 1024; + /// byte[] buffer = new byte[bufferSize]; + /// ZlibCodec compressor = new ZlibCodec(); + /// + /// Console.WriteLine("\n============================================"); + /// Console.WriteLine("Size of Buffer to Deflate: {0} bytes.", UncompressedBytes.Length); + /// MemoryStream ms = new MemoryStream(); + /// + /// int rc = compressor.InitializeDeflate(level); + /// + /// compressor.InputBuffer = UncompressedBytes; + /// compressor.NextIn = 0; + /// compressor.AvailableBytesIn = UncompressedBytes.Length; + /// + /// compressor.OutputBuffer = buffer; + /// + /// // pass 1: deflate + /// do + /// { + /// compressor.NextOut = 0; + /// compressor.AvailableBytesOut = buffer.Length; + /// rc = compressor.Deflate(FlushType.None); + /// + /// if (rc != ZlibConstants.Z_OK && rc != ZlibConstants.Z_STREAM_END) + /// throw new Exception("deflating: " + compressor.Message); + /// + /// ms.Write(compressor.OutputBuffer, 0, buffer.Length - compressor.AvailableBytesOut); + /// } + /// while (compressor.AvailableBytesIn > 0 || compressor.AvailableBytesOut == 0); + /// + /// // pass 2: finish and flush + /// do + /// { + /// compressor.NextOut = 0; + /// compressor.AvailableBytesOut = buffer.Length; + /// rc = compressor.Deflate(FlushType.Finish); + /// + /// if (rc != ZlibConstants.Z_STREAM_END && rc != ZlibConstants.Z_OK) + /// throw new Exception("deflating: " + compressor.Message); + /// + /// if (buffer.Length - compressor.AvailableBytesOut > 0) + /// ms.Write(buffer, 0, buffer.Length - compressor.AvailableBytesOut); + /// } + /// while (compressor.AvailableBytesIn > 0 || compressor.AvailableBytesOut == 0); + /// + /// compressor.EndDeflate(); + /// + /// ms.Seek(0, SeekOrigin.Begin); + /// CompressedBytes = new byte[compressor.TotalBytesOut]; + /// ms.Read(CompressedBytes, 0, CompressedBytes.Length); + /// } + /// + /// + /// whether to flush all data as you deflate. Generally you will want to + /// use Z_NO_FLUSH here, in a series of calls to Deflate(), and then call EndDeflate() to + /// flush everything. + /// + /// Z_OK if all goes well. + public int Deflate(FlushType flush) + { + if (dstate == null) + throw new ZlibException("No Deflate State!"); + return dstate.Deflate(flush); + } + + /// + /// End a deflation session. + /// + /// + /// Call this after making a series of one or more calls to Deflate(). All buffers are flushed. + /// + /// Z_OK if all goes well. + public int EndDeflate() + { + if (dstate == null) + throw new ZlibException("No Deflate State!"); + // TODO: dinoch Tue, 03 Nov 2009 15:39 (test this) + //int ret = dstate.End(); + dstate = null; + return ZlibConstants.Z_OK; //ret; + } + + /// + /// Reset a codec for another deflation session. + /// + /// + /// Call this to reset the deflation state. For example if a thread is deflating + /// non-consecutive blocks, you can call Reset() after the Deflate(Sync) of the first + /// block and before the next Deflate(None) of the second block. + /// + /// Z_OK if all goes well. + public void ResetDeflate() + { + if (dstate == null) + throw new ZlibException("No Deflate State!"); + dstate.Reset(); + } + + + /// + /// Set the CompressionStrategy and CompressionLevel for a deflation session. + /// + /// the level of compression to use. + /// the strategy to use for compression. + /// Z_OK if all goes well. + public int SetDeflateParams(CompressionLevel level, CompressionStrategy strategy) + { + if (dstate == null) + throw new ZlibException("No Deflate State!"); + return dstate.SetParams(level, strategy); + } + + + /// + /// Set the dictionary to be used for either Inflation or Deflation. + /// + /// The dictionary bytes to use. + /// Z_OK if all goes well. + public int SetDictionary(byte[] dictionary) + { + if (istate != null) + return istate.SetDictionary(dictionary); + + if (dstate != null) + return dstate.SetDictionary(dictionary); + + throw new ZlibException("No Inflate or Deflate state!"); + } + + // Flush as much pending output as possible. All deflate() output goes + // through this function so some applications may wish to modify it + // to avoid allocating a large strm->next_out buffer and copying into it. + // (See also read_buf()). + internal void flush_pending() + { + int len = dstate.pendingCount; + + if (len > AvailableBytesOut) + len = AvailableBytesOut; + if (len == 0) + return; + + if (dstate.pending.Length <= dstate.nextPending || + OutputBuffer.Length <= NextOut || + dstate.pending.Length < (dstate.nextPending + len) || + OutputBuffer.Length < (NextOut + len)) + { + throw new ZlibException(String.Format("Invalid State. (pending.Length={0}, pendingCount={1})", + dstate.pending.Length, dstate.pendingCount)); + } + + Array.Copy(dstate.pending, dstate.nextPending, OutputBuffer, NextOut, len); + + NextOut += len; + dstate.nextPending += len; + TotalBytesOut += len; + AvailableBytesOut -= len; + dstate.pendingCount -= len; + if (dstate.pendingCount == 0) + { + dstate.nextPending = 0; + } + } + + // Read a new buffer from the current input stream, update the adler32 + // and total number of bytes read. All deflate() input goes through + // this function so some applications may wish to modify it to avoid + // allocating a large strm->next_in buffer and copying from it. + // (See also flush_pending()). + internal int read_buf(byte[] buf, int start, int size) + { + int len = AvailableBytesIn; + + if (len > size) + len = size; + if (len == 0) + return 0; + + AvailableBytesIn -= len; + + if (dstate.WantRfc1950HeaderBytes) + { + _Adler32 = Adler.Adler32(_Adler32, InputBuffer, NextIn, len); + } + Array.Copy(InputBuffer, NextIn, buf, start, len); + NextIn += len; + TotalBytesIn += len; + return len; + } + + } +} \ No newline at end of file diff --git a/Resources/Libraries/DotNetZip/Source/Zlib/ZlibConstants.cs b/Resources/Libraries/DotNetZip/Source/Zlib/ZlibConstants.cs new file mode 100644 index 00000000..7952ce20 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zlib/ZlibConstants.cs @@ -0,0 +1,128 @@ +// ZlibConstants.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa and Microsoft Corporation. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2009-November-03 18:50:19> +// +// ------------------------------------------------------------------ +// +// This module defines constants used by the zlib class library. This +// code is derived from the jzlib implementation of zlib, but +// significantly modified. In keeping with the license for jzlib, the +// copyright to that code is included here. +// +// ------------------------------------------------------------------ +// +// Copyright (c) 2000,2001,2002,2003 ymnk, JCraft,Inc. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// 1. Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// +// 2. Redistributions in binary form must reproduce the above copyright +// notice, this list of conditions and the following disclaimer in +// the documentation and/or other materials provided with the distribution. +// +// 3. The names of the authors may not be used to endorse or promote products +// derived from this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, +// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND +// FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JCRAFT, +// INC. OR ANY CONTRIBUTORS TO THIS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, +// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, +// OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +// EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// ----------------------------------------------------------------------- +// +// This program is based on zlib-1.1.3; credit to authors +// Jean-loup Gailly(jloup@gzip.org) and Mark Adler(madler@alumni.caltech.edu) +// and contributors of zlib. +// +// ----------------------------------------------------------------------- + + +using System; + +namespace Ionic.Zlib +{ + /// + /// A bunch of constants used in the Zlib interface. + /// + public static class ZlibConstants + { + /// + /// The maximum number of window bits for the Deflate algorithm. + /// + public const int WindowBitsMax = 15; // 32K LZ77 window + + /// + /// The default number of window bits for the Deflate algorithm. + /// + public const int WindowBitsDefault = WindowBitsMax; + + /// + /// indicates everything is A-OK + /// + public const int Z_OK = 0; + + /// + /// Indicates that the last operation reached the end of the stream. + /// + public const int Z_STREAM_END = 1; + + /// + /// The operation ended in need of a dictionary. + /// + public const int Z_NEED_DICT = 2; + + /// + /// There was an error with the stream - not enough data, not open and readable, etc. + /// + public const int Z_STREAM_ERROR = -2; + + /// + /// There was an error with the data - not enough data, bad data, etc. + /// + public const int Z_DATA_ERROR = -3; + + /// + /// There was an error with the working buffer. + /// + public const int Z_BUF_ERROR = -5; + + /// + /// The size of the working buffer used in the ZlibCodec class. Defaults to 8192 bytes. + /// +#if NETCF + public const int WorkingBufferSizeDefault = 8192; +#else + public const int WorkingBufferSizeDefault = 16384; +#endif + /// + /// The minimum size of the working buffer used in the ZlibCodec class. Currently it is 128 bytes. + /// + public const int WorkingBufferSizeMin = 1024; + } + +} + diff --git a/Resources/Libraries/DotNetZip/Source/Zlib/ZlibStream.cs b/Resources/Libraries/DotNetZip/Source/Zlib/ZlibStream.cs new file mode 100644 index 00000000..57b308c0 --- /dev/null +++ b/Resources/Libraries/DotNetZip/Source/Zlib/ZlibStream.cs @@ -0,0 +1,725 @@ +// ZlibStream.cs +// ------------------------------------------------------------------ +// +// Copyright (c) 2009 Dino Chiesa and Microsoft Corporation. +// All rights reserved. +// +// This code module is part of DotNetZip, a zipfile class library. +// +// ------------------------------------------------------------------ +// +// This code is licensed under the Microsoft Public License. +// See the file License.txt for the license details. +// More info on: http://dotnetzip.codeplex.com +// +// ------------------------------------------------------------------ +// +// last saved (in emacs): +// Time-stamp: <2011-July-31 14:53:33> +// +// ------------------------------------------------------------------ +// +// This module defines the ZlibStream class, which is similar in idea to +// the System.IO.Compression.DeflateStream and +// System.IO.Compression.GZipStream classes in the .NET BCL. +// +// ------------------------------------------------------------------ + +using System; +using System.IO; + +namespace Ionic.Zlib +{ + + /// + /// Represents a Zlib stream for compression or decompression. + /// + /// + /// + /// + /// The ZlibStream is a Decorator on a . It adds ZLIB compression or decompression to any + /// stream. + /// + /// + /// Using this stream, applications can compress or decompress data via + /// stream Read() and Write() operations. Either compresssion or + /// decompression can occur through either reading or writing. The compression + /// format used is ZLIB, which is documented in IETF RFC 1950, "ZLIB Compressed + /// Data Format Specification version 3.3". This implementation of ZLIB always uses + /// DEFLATE as the compression method. (see IETF RFC 1951, "DEFLATE + /// Compressed Data Format Specification version 1.3.") + /// + /// + /// The ZLIB format allows for varying compression methods, window sizes, and dictionaries. + /// This implementation always uses the DEFLATE compression method, a preset dictionary, + /// and 15 window bits by default. + /// + /// + /// + /// This class is similar to , except that it adds the + /// RFC1950 header and trailer bytes to a compressed stream when compressing, or expects + /// the RFC1950 header and trailer bytes when decompressing. It is also similar to the + /// . + /// + /// + /// + /// + public class ZlibStream : System.IO.Stream + { + internal ZlibBaseStream _baseStream; + bool _disposed; + + /// + /// Create a ZlibStream using the specified CompressionMode. + /// + /// + /// + /// + /// When mode is CompressionMode.Compress, the ZlibStream + /// will use the default compression level. The "captive" stream will be + /// closed when the ZlibStream is closed. + /// + /// + /// + /// + /// + /// This example uses a ZlibStream to compress a file, and writes the + /// compressed data to another file. + /// + /// using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress)) + /// { + /// using (var raw = System.IO.File.Create(fileToCompress + ".zlib")) + /// { + /// using (Stream compressor = new ZlibStream(raw, CompressionMode.Compress)) + /// { + /// byte[] buffer = new byte[WORKING_BUFFER_SIZE]; + /// int n; + /// while ((n= input.Read(buffer, 0, buffer.Length)) != 0) + /// { + /// compressor.Write(buffer, 0, n); + /// } + /// } + /// } + /// } + /// + /// + /// Using input As Stream = File.OpenRead(fileToCompress) + /// Using raw As FileStream = File.Create(fileToCompress & ".zlib") + /// Using compressor As Stream = New ZlibStream(raw, CompressionMode.Compress) + /// Dim buffer As Byte() = New Byte(4096) {} + /// Dim n As Integer = -1 + /// Do While (n <> 0) + /// If (n > 0) Then + /// compressor.Write(buffer, 0, n) + /// End If + /// n = input.Read(buffer, 0, buffer.Length) + /// Loop + /// End Using + /// End Using + /// End Using + /// + /// + /// + /// The stream which will be read or written. + /// Indicates whether the ZlibStream will compress or decompress. + public ZlibStream(System.IO.Stream stream, CompressionMode mode) + : this(stream, mode, CompressionLevel.Default, false) + { + } + + /// + /// Create a ZlibStream using the specified CompressionMode and + /// the specified CompressionLevel. + /// + /// + /// + /// + /// + /// When mode is CompressionMode.Decompress, the level parameter is ignored. + /// The "captive" stream will be closed when the ZlibStream is closed. + /// + /// + /// + /// + /// + /// This example uses a ZlibStream to compress data from a file, and writes the + /// compressed data to another file. + /// + /// + /// using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress)) + /// { + /// using (var raw = System.IO.File.Create(fileToCompress + ".zlib")) + /// { + /// using (Stream compressor = new ZlibStream(raw, + /// CompressionMode.Compress, + /// CompressionLevel.BestCompression)) + /// { + /// byte[] buffer = new byte[WORKING_BUFFER_SIZE]; + /// int n; + /// while ((n= input.Read(buffer, 0, buffer.Length)) != 0) + /// { + /// compressor.Write(buffer, 0, n); + /// } + /// } + /// } + /// } + /// + /// + /// + /// Using input As Stream = File.OpenRead(fileToCompress) + /// Using raw As FileStream = File.Create(fileToCompress & ".zlib") + /// Using compressor As Stream = New ZlibStream(raw, CompressionMode.Compress, CompressionLevel.BestCompression) + /// Dim buffer As Byte() = New Byte(4096) {} + /// Dim n As Integer = -1 + /// Do While (n <> 0) + /// If (n > 0) Then + /// compressor.Write(buffer, 0, n) + /// End If + /// n = input.Read(buffer, 0, buffer.Length) + /// Loop + /// End Using + /// End Using + /// End Using + /// + /// + /// + /// The stream to be read or written while deflating or inflating. + /// Indicates whether the ZlibStream will compress or decompress. + /// A tuning knob to trade speed for effectiveness. + public ZlibStream(System.IO.Stream stream, CompressionMode mode, CompressionLevel level) + : this(stream, mode, level, false) + { + } + + /// + /// Create a ZlibStream using the specified CompressionMode, and + /// explicitly specify whether the captive stream should be left open after + /// Deflation or Inflation. + /// + /// + /// + /// + /// + /// When mode is CompressionMode.Compress, the ZlibStream will use + /// the default compression level. + /// + /// + /// + /// This constructor allows the application to request that the captive stream + /// remain open after the deflation or inflation occurs. By default, after + /// Close() is called on the stream, the captive stream is also + /// closed. In some cases this is not desired, for example if the stream is a + /// that will be re-read after + /// compression. Specify true for the parameter to leave the stream + /// open. + /// + /// + /// + /// See the other overloads of this constructor for example code. + /// + /// + /// + /// + /// The stream which will be read or written. This is called the + /// "captive" stream in other places in this documentation. + /// Indicates whether the ZlibStream will compress or decompress. + /// true if the application would like the stream to remain + /// open after inflation/deflation. + public ZlibStream(System.IO.Stream stream, CompressionMode mode, bool leaveOpen) + : this(stream, mode, CompressionLevel.Default, leaveOpen) + { + } + + /// + /// Create a ZlibStream using the specified CompressionMode + /// and the specified CompressionLevel, and explicitly specify + /// whether the stream should be left open after Deflation or Inflation. + /// + /// + /// + /// + /// + /// This constructor allows the application to request that the captive + /// stream remain open after the deflation or inflation occurs. By + /// default, after Close() is called on the stream, the captive + /// stream is also closed. In some cases this is not desired, for example + /// if the stream is a that will be + /// re-read after compression. Specify true for the parameter to leave the stream open. + /// + /// + /// + /// When mode is CompressionMode.Decompress, the level parameter is + /// ignored. + /// + /// + /// + /// + /// + /// + /// This example shows how to use a ZlibStream to compress the data from a file, + /// and store the result into another file. The filestream remains open to allow + /// additional data to be written to it. + /// + /// + /// using (var output = System.IO.File.Create(fileToCompress + ".zlib")) + /// { + /// using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress)) + /// { + /// using (Stream compressor = new ZlibStream(output, CompressionMode.Compress, CompressionLevel.BestCompression, true)) + /// { + /// byte[] buffer = new byte[WORKING_BUFFER_SIZE]; + /// int n; + /// while ((n= input.Read(buffer, 0, buffer.Length)) != 0) + /// { + /// compressor.Write(buffer, 0, n); + /// } + /// } + /// } + /// // can write additional data to the output stream here + /// } + /// + /// + /// Using output As FileStream = File.Create(fileToCompress & ".zlib") + /// Using input As Stream = File.OpenRead(fileToCompress) + /// Using compressor As Stream = New ZlibStream(output, CompressionMode.Compress, CompressionLevel.BestCompression, True) + /// Dim buffer As Byte() = New Byte(4096) {} + /// Dim n As Integer = -1 + /// Do While (n <> 0) + /// If (n > 0) Then + /// compressor.Write(buffer, 0, n) + /// End If + /// n = input.Read(buffer, 0, buffer.Length) + /// Loop + /// End Using + /// End Using + /// ' can write additional data to the output stream here. + /// End Using + /// + /// + /// + /// The stream which will be read or written. + /// + /// Indicates whether the ZlibStream will compress or decompress. + /// + /// + /// true if the application would like the stream to remain open after + /// inflation/deflation. + /// + /// + /// + /// A tuning knob to trade speed for effectiveness. This parameter is + /// effective only when mode is CompressionMode.Compress. + /// + public ZlibStream(System.IO.Stream stream, CompressionMode mode, CompressionLevel level, bool leaveOpen) + { + _baseStream = new ZlibBaseStream(stream, mode, level, ZlibStreamFlavor.ZLIB, leaveOpen); + } + + #region Zlib properties + + /// + /// This property sets the flush behavior on the stream. + /// Sorry, though, not sure exactly how to describe all the various settings. + /// + virtual public FlushType FlushMode + { + get { return (this._baseStream._flushMode); } + set + { + if (_disposed) throw new ObjectDisposedException("ZlibStream"); + this._baseStream._flushMode = value; + } + } + + /// + /// The size of the working buffer for the compression codec. + /// + /// + /// + /// + /// The working buffer is used for all stream operations. The default size is + /// 1024 bytes. The minimum size is 128 bytes. You may get better performance + /// with a larger buffer. Then again, you might not. You would have to test + /// it. + /// + /// + /// + /// Set this before the first call to Read() or Write() on the + /// stream. If you try to set it afterwards, it will throw. + /// + /// + public int BufferSize + { + get + { + return this._baseStream._bufferSize; + } + set + { + if (_disposed) throw new ObjectDisposedException("ZlibStream"); + if (this._baseStream._workingBuffer != null) + throw new ZlibException("The working buffer is already set."); + if (value < ZlibConstants.WorkingBufferSizeMin) + throw new ZlibException(String.Format("Don't be silly. {0} bytes?? Use a bigger buffer, at least {1}.", value, ZlibConstants.WorkingBufferSizeMin)); + this._baseStream._bufferSize = value; + } + } + + /// Returns the total number of bytes input so far. + virtual public long TotalIn + { + get { return this._baseStream._z.TotalBytesIn; } + } + + /// Returns the total number of bytes output so far. + virtual public long TotalOut + { + get { return this._baseStream._z.TotalBytesOut; } + } + + #endregion + + #region System.IO.Stream methods + + /// + /// Dispose the stream. + /// + /// + /// + /// This may or may not result in a Close() call on the captive + /// stream. See the constructors that have a leaveOpen parameter + /// for more information. + /// + /// + /// This method may be invoked in two distinct scenarios. If disposing + /// == true, the method has been called directly or indirectly by a + /// user's code, for example via the public Dispose() method. In this + /// case, both managed and unmanaged resources can be referenced and + /// disposed. If disposing == false, the method has been called by the + /// runtime from inside the object finalizer and this method should not + /// reference other objects; in that case only unmanaged resources must + /// be referenced or disposed. + /// + /// + /// + /// indicates whether the Dispose method was invoked by user code. + /// + protected override void Dispose(bool disposing) + { + try + { + if (!_disposed) + { + if (disposing && (this._baseStream != null)) + this._baseStream.Close(); + _disposed = true; + } + } + finally + { + base.Dispose(disposing); + } + } + + + /// + /// Indicates whether the stream can be read. + /// + /// + /// The return value depends on whether the captive stream supports reading. + /// + public override bool CanRead + { + get + { + if (_disposed) throw new ObjectDisposedException("ZlibStream"); + return _baseStream._stream.CanRead; + } + } + + /// + /// Indicates whether the stream supports Seek operations. + /// + /// + /// Always returns false. + /// + public override bool CanSeek + { + get { return false; } + } + + /// + /// Indicates whether the stream can be written. + /// + /// + /// The return value depends on whether the captive stream supports writing. + /// + public override bool CanWrite + { + get + { + if (_disposed) throw new ObjectDisposedException("ZlibStream"); + return _baseStream._stream.CanWrite; + } + } + + /// + /// Flush the stream. + /// + public override void Flush() + { + if (_disposed) throw new ObjectDisposedException("ZlibStream"); + _baseStream.Flush(); + } + + /// + /// Reading this property always throws a . + /// + public override long Length + { + get { throw new NotSupportedException(); } + } + + /// + /// The position of the stream pointer. + /// + /// + /// + /// Setting this property always throws a . Reading will return the total bytes + /// written out, if used in writing, or the total bytes read in, if used in + /// reading. The count may refer to compressed bytes or uncompressed bytes, + /// depending on how you've used the stream. + /// + public override long Position + { + get + { + if (this._baseStream._streamMode == Ionic.Zlib.ZlibBaseStream.StreamMode.Writer) + return this._baseStream._z.TotalBytesOut; + if (this._baseStream._streamMode == Ionic.Zlib.ZlibBaseStream.StreamMode.Reader) + return this._baseStream._z.TotalBytesIn; + return 0; + } + + set { throw new NotSupportedException(); } + } + + /// + /// Read data from the stream. + /// + /// + /// + /// + /// + /// If you wish to use the ZlibStream to compress data while reading, + /// you can create a ZlibStream with CompressionMode.Compress, + /// providing an uncompressed data stream. Then call Read() on that + /// ZlibStream, and the data read will be compressed. If you wish to + /// use the ZlibStream to decompress data while reading, you can create + /// a ZlibStream with CompressionMode.Decompress, providing a + /// readable compressed data stream. Then call Read() on that + /// ZlibStream, and the data will be decompressed as it is read. + /// + /// + /// + /// A ZlibStream can be used for Read() or Write(), but + /// not both. + /// + /// + /// + /// + /// + /// The buffer into which the read data should be placed. + /// + /// + /// the offset within that data array to put the first byte read. + /// + /// the number of bytes to read. + /// + /// the number of bytes read + public override int Read(byte[] buffer, int offset, int count) + { + if (_disposed) throw new ObjectDisposedException("ZlibStream"); + return _baseStream.Read(buffer, offset, count); + } + + /// + /// Calling this method always throws a . + /// + /// + /// The offset to seek to.... + /// IF THIS METHOD ACTUALLY DID ANYTHING. + /// + /// + /// The reference specifying how to apply the offset.... IF + /// THIS METHOD ACTUALLY DID ANYTHING. + /// + /// + /// nothing. This method always throws. + public override long Seek(long offset, System.IO.SeekOrigin origin) + { + throw new NotSupportedException(); + } + + /// + /// Calling this method always throws a . + /// + /// + /// The new value for the stream length.... IF + /// THIS METHOD ACTUALLY DID ANYTHING. + /// + public override void SetLength(long value) + { + throw new NotSupportedException(); + } + + /// + /// Write data to the stream. + /// + /// + /// + /// + /// + /// If you wish to use the ZlibStream to compress data while writing, + /// you can create a ZlibStream with CompressionMode.Compress, + /// and a writable output stream. Then call Write() on that + /// ZlibStream, providing uncompressed data as input. The data sent to + /// the output stream will be the compressed form of the data written. If you + /// wish to use the ZlibStream to decompress data while writing, you + /// can create a ZlibStream with CompressionMode.Decompress, and a + /// writable output stream. Then call Write() on that stream, + /// providing previously compressed data. The data sent to the output stream + /// will be the decompressed form of the data written. + /// + /// + /// + /// A ZlibStream can be used for Read() or Write(), but not both. + /// + /// + /// The buffer holding data to write to the stream. + /// the offset within that data array to find the first byte to write. + /// the number of bytes to write. + public override void Write(byte[] buffer, int offset, int count) + { + if (_disposed) throw new ObjectDisposedException("ZlibStream"); + _baseStream.Write(buffer, offset, count); + } + #endregion + + + /// + /// Compress a string into a byte array using ZLIB. + /// + /// + /// + /// Uncompress it with . + /// + /// + /// + /// + /// + /// + /// + /// A string to compress. The string will first be encoded + /// using UTF8, then compressed. + /// + /// + /// The string in compressed form + public static byte[] CompressString(String s) + { + using (var ms = new MemoryStream()) + { + Stream compressor = + new ZlibStream(ms, CompressionMode.Compress, CompressionLevel.BestCompression); + ZlibBaseStream.CompressString(s, compressor); + return ms.ToArray(); + } + } + + + /// + /// Compress a byte array into a new byte array using ZLIB. + /// + /// + /// + /// Uncompress it with . + /// + /// + /// + /// + /// + /// + /// A buffer to compress. + /// + /// + /// The data in compressed form + public static byte[] CompressBuffer(byte[] b) + { + using (var ms = new MemoryStream()) + { + Stream compressor = + new ZlibStream( ms, CompressionMode.Compress, CompressionLevel.BestCompression ); + + ZlibBaseStream.CompressBuffer(b, compressor); + return ms.ToArray(); + } + } + + + /// + /// Uncompress a ZLIB-compressed byte array into a single string. + /// + /// + /// + /// + /// + /// + /// A buffer containing ZLIB-compressed data. + /// + /// + /// The uncompressed string + public static String UncompressString(byte[] compressed) + { + using (var input = new MemoryStream(compressed)) + { + Stream decompressor = + new ZlibStream(input, CompressionMode.Decompress); + + return ZlibBaseStream.UncompressString(compressed, decompressor); + } + } + + + /// + /// Uncompress a ZLIB-compressed byte array into a byte array. + /// + /// + /// + /// + /// + /// + /// A buffer containing ZLIB-compressed data. + /// + /// + /// The data in uncompressed form + public static byte[] UncompressBuffer(byte[] compressed) + { + using (var input = new MemoryStream(compressed)) + { + Stream decompressor = + new ZlibStream( input, CompressionMode.Decompress ); + + return ZlibBaseStream.UncompressBuffer(compressed, decompressor); + } + } + + } + + +} \ No newline at end of file diff --git a/Resources/Libraries/FJ.Core/FJ.Core.dll b/Resources/Libraries/FJ.Core/FJ.Core.dll new file mode 100644 index 00000000..b2a88282 Binary files /dev/null and b/Resources/Libraries/FJ.Core/FJ.Core.dll differ diff --git a/Resources/Libraries/FJ.Core/FJ.Core.pdb b/Resources/Libraries/FJ.Core/FJ.Core.pdb new file mode 100644 index 00000000..2932dfcf Binary files /dev/null and b/Resources/Libraries/FJ.Core/FJ.Core.pdb differ diff --git a/Resources/Libraries/LibTiff.NET/BitMiracle.LibTiff.NET.dll b/Resources/Libraries/LibTiff.NET/BitMiracle.LibTiff.NET.dll new file mode 100644 index 00000000..78d25cb8 Binary files /dev/null and b/Resources/Libraries/LibTiff.NET/BitMiracle.LibTiff.NET.dll differ diff --git a/Resources/Libraries/LibTiff.NET/BitMiracle.LibTiff.NET.xml b/Resources/Libraries/LibTiff.NET/BitMiracle.LibTiff.NET.xml new file mode 100644 index 00000000..5d74e514 --- /dev/null +++ b/Resources/Libraries/LibTiff.NET/BitMiracle.LibTiff.NET.xml @@ -0,0 +1,4264 @@ + + + + BitMiracle.LibTiff.NET + + + + + Regenerated line info.
+ Possible values for .CLEANFAXDATA tag. + + + + + No errors detected. + + + + + Receiver regenerated lines. + + + + + Uncorrected errors exist. + + + + + Color curve accuracy.
+ Possible values for .COLORRESPONSEUNIT tag. + + + + + Tenths of a unit. + + + + + Hundredths of a unit. + + + + + Thousandths of a unit. + + + + + Ten-thousandths of a unit. + + + + + Hundred-thousandths. + + + + + Compression scheme.
+ Possible values for .COMPRESSION tag. + + + + + Dump mode. + + + + + CCITT modified Huffman RLE. + + + + + CCITT Group 3 fax encoding. + + + + + CCITT T.4 (TIFF 6 name for CCITT Group 3 fax encoding). + + + + + CCITT Group 4 fax encoding. + + + + + CCITT T.6 (TIFF 6 name for CCITT Group 4 fax encoding). + + + + + Lempel-Ziv & Welch. + + + + + Original JPEG / Old-style JPEG (6.0). + + + + + JPEG DCT compression. Introduced post TIFF rev 6.0. + + + + + NeXT 2-bit RLE. + + + + + CCITT RLE. + + + + + Macintosh RLE. + + + + + ThunderScan RLE. + + + + + IT8 CT w/padding. Reserved for ANSI IT8 TIFF/IT. + + + + + IT8 Linework RLE. Reserved for ANSI IT8 TIFF/IT. + + + + + IT8 Monochrome picture. Reserved for ANSI IT8 TIFF/IT. + + + + + IT8 Binary line art. Reserved for ANSI IT8 TIFF/IT. + + + + + Pixar companded 10bit LZW. Reserved for Pixar. + + + + + Pixar companded 11bit ZIP. Reserved for Pixar. + + + + + Deflate compression. + + + + + Deflate compression, as recognized by Adobe. + + + + + Kodak DCS encoding. + Reserved for Oceana Matrix (dev@oceana.com). + + + + + ISO JBIG. + + + + + SGI Log Luminance RLE. + + + + + SGI Log 24-bit packed. + + + + + Leadtools JPEG2000. + + + + + Information about extra samples.
+ Possible values for .EXTRASAMPLES tag. + + + + + Unspecified data. + + + + + Associated alpha data. + + + + + Unassociated alpha data. + + + + + Group 3/4 format control.
+ Possible values for .FAXMODE tag. + + + + + Default, include RTC. + + + + + No RTC at end of data. + + + + + No EOL code at end of row. + + + + + Byte align row. + + + + + Word align row. + + + + + TIFF Class F. + + + + + Field bits (flags) for tags. + + + + + This value is used as a base (starting) value for codec-private tags. + + + + + This value is used to signify custom tags. + + + + + This value is used to signify tags that are to be processed + but otherwise ignored.
+ This permits antiquated tags to be quietly read and discarded. Note that + a bit is allocated for ignored tags; this is understood by the + directory reading logic which uses this fact to avoid special-case handling. + + + + + Last usable value for field bit. All tags values should be less than this value. + + + + + This value is used to signify pseudo-tags.
+ Pseudo-tags don't normally need field bits since they are not + written to an output file (by definition). The library also has + express logic to always query a codec for a pseudo-tag so allocating + a field bit for one is a waste. If codec wants to promote the notion + of a pseudo-tag being set or unset then it can do using + internal state flags without polluting the field bit space defined + for real tags. + + + + + Holds a value of a Tiff tag. + + + + + Retrieves value converted to byte array. + + Value converted to byte array. + + + + Retrieves value converted to byte. + + The value converted to byte. + + + + Retrieves value converted to array of bytes. + + Value converted to array of bytes. + + + + Retrieves value converted to double. + + The value converted to double. + + + + Retrieves value converted to array of double values. + + Value converted to array of double values. + + + + Retrieves value converted to float. + + The value converted to float. + + + + Retrieves value converted to array of float values. + + Value converted to array of float values. + + + + Retrieves value converted to int. + + The value converted to int. + + + + Retrieves value converted to array of int values. + + Value converted to array of int values. + + + + Retrieves value converted to short. + + The value converted to short. + + + + Retrieves value converted to array of short values. + + Value converted to array of short values. + + + + Retrieves value converted to string. + + + A that represents this instance. + + + + + Retrieves value converted to uint. + + The value converted to uint. + + + + Retrieves value converted to array of uint values. + + Value converted to array of uint values. + + + + Retrieves value converted to ushort. + + The value converted to ushort. + + + + Retrieves value converted to array of ushort values. + + Value converted to array of ushort values. + + + + Gets the value. + + + + + Subfile data descriptor.
+ Possible values for .SUBFILETYPE tag. + + + + + Reduced resolution version. + + + + + One page of many. + + + + + Transparency mask. + + + + + Data order within a byte.
+ Possible values for .FILLORDER tag. + + + + + Most significant -> least. + + + + + Least significant -> most. + + + + + Gray scale curve accuracy.
+ Possible values for .GRAYRESPONSEUNIT tag. + + + + + Tenths of a unit. + + + + + Hundredths of a unit. + + + + + Thousandths of a unit. + + + + + Ten-thousandths of a unit. + + + + + Hundred-thousandths. + + + + + Options for CCITT Group 3/4 fax encoding.
+ Possible values for .GROUP3OPTIONS / TiffTag.T4OPTIONS and + TiffTag.GROUP4OPTIONS / TiffTag.T6OPTIONS tags. + + + + + Unknown (uninitialized). + + + + + 2-dimensional coding. + + + + + Data not compressed. + + + + + Fill to byte boundary. + + + + + Inks in separated image.
+ Possible values for .INKSET tag. + + + + + Cyan-magenta-yellow-black color. + + + + + Multi-ink or hi-fi color. + + + + + Auto RGB<=>YCbCr convert.
+ Possible values for .JPEGCOLORMODE tag. + + + + + No conversion (default). + + + + + Do auto conversion. + + + + + JPEG processing algorithm.
+ Possible values for .JPEGPROC tag. + + + + + Baseline sequential. + + + + + Huffman coded lossless. + + + + + Jpeg Tables Mode.
+ Possible values for .JPEGTABLESMODE tag. + + + + + None. + + + + + Include quantization tables. + + + + + Include Huffman tables. + + + + + Kind of data in subfile.
+ Possible values for .OSUBFILETYPE tag. + + + + + Full resolution image data. + + + + + Reduced size image data. + + + + + One page of many. + + + + + Image orientation.
+ Possible values for .ORIENTATION tag. + + + + + Row 0 top, Column 0 lhs. + + + + + Row 0 top, Column 0 rhs. + + + + + Row 0 bottom, Column 0 rhs. + + + + + Row 0 bottom, Column 0 lhs. + + + + + Row 0 lhs, Column 0 top. + + + + + Row 0 rhs, Column 0 top. + + + + + Row 0 rhs, Column 0 bottom. + + + + + Row 0 lhs, Column 0 bottom. + + + + + Photometric interpretation.
+ Possible values for .PHOTOMETRIC tag. + + + + + Min value is white. + + + + + Min value is black. + + + + + RGB color model. + + + + + Color map indexed. + + + + + [obsoleted by TIFF rev. 6.0] Holdout mask. + + + + + Color separations. + + + + + CCIR 601. + + + + + 1976 CIE L*a*b*. + + + + + ICC L*a*b*. Introduced post TIFF rev 6.0 by Adobe TIFF Technote 4. + + + + + ITU L*a*b*. + + + + + CIE Log2(L). + + + + + CIE Log2(L) (u',v'). + + + + + Storage organization.
+ Possible values for .PLANARCONFIG tag. + + + + + Unknown (uninitialized). + + + + + Single image plane. + + + + + Separate planes of data. + + + + + Prediction scheme w/ LZW.
+ Possible values for .PREDICTOR tag. + + + + + No prediction scheme used. + + + + + Horizontal differencing. + + + + + Floating point predictor. + + + + + Units of resolutions.
+ Possible values for .RESOLUTIONUNIT tag. + + + + + No meaningful units. + + + + + English. + + + + + Metric. + + + + + Data sample format.
+ Possible values for .SAMPLEFORMAT tag. + + + + + Unsigned integer data + + + + + Signed integer data + + + + + IEEE floating point data + + + + + Untyped data + + + + + Complex signed int + + + + + Complex ieee floating + + + + + Thresholding used on data.
+ Possible values for .THRESHHOLDING tag. + + + + + B&W art scan. + + + + + Dithered scan. + + + + + Usually Floyd-Steinberg. + + + + + Tag Image File Format (TIFF) + + + + + Gets the version of the library's assembly. + + + + + Converts a byte buffer into array of 32-bit values. + + The byte buffer. + The zero-based offset in at + which to begin converting bytes. + The number of bytes to convert. + The array of 32-bit values. + + + + Converts a byte buffer into array of 16-bit values. + + The byte buffer. + The zero-based offset in at + which to begin converting bytes. + The number of bytes to convert. + The array of 16-bit values. + + + + Writes the current state of the TIFF directory into the file to make what is currently + in the file/stream readable. + + + true if the current directory was rewritten successfully; + otherwise, false + + + + Checks whether the specified (x, y, z, plane) coordinates are within the bounds of + the image. + + The x-coordinate. + The y-coordinate. + The z-coordinate. + The sample plane. + + true if the specified coordinates are within the bounds of the image; + otherwise, false. + + + + Returns the custom client data associated with this . + + The custom client data associated with this . + + + + Initializes new instance of class and opens a stream with TIFF data + for reading or writing. + + The name for the new instance of class. + The open mode. Specifies if the file is to be opened for + reading ("r"), writing ("w"), or appending ("a") and, optionally, whether to override + certain default aspects of library operation (see remarks for + method for the list of the mode flags). + Some client data. This data is passed as parameter to every + method of the object specified by the + parameter. + An instance of the class to use for + reading, writing and seeking of TIFF data. + The new instance of class if stream is successfully + opened; otherwise, null. + + + + Closes a previously opened TIFF file. + + + + + Compares specified number of elements in two arrays. + + The first array to compare. + The second array to compare. + The number of elements to compare. + + The difference between compared elements or 0 if all elements are equal. + + + + + Computes which strip contains the specified coordinates (row, plane). + + The row. + The sample plane. + The number of the strip that contains the specified coordinates. + + + + Computes which tile contains the specified coordinates (x, y, z, plane). + + The x-coordinate. + The y-coordinate. + The z-coordinate. + The sample plane. + The number of the tile that contains the specified coordinates. + + + + Creates a new directory within file/stream. + + + + + Gets the zero-based index of the current directory. + + The zero-based index of the current directory. + + + + Retrieves the file/stream offset of the current directory. + + The file/stream offset of the current directory. + + + + Gets the current row that is being read or written. + + The current row that is being read or written. + + + + Gets the current strip that is being read or written. + + The current strip that is being read or written. + + + + Gets the current tile that is being read or written. + + The current tile that is being read or written. + + + + Gets the number of bytes occupied by the item of given type. + + The type. + The number of bytes occupied by the or 0 if unknown + data type is supplied. + + + + Computes the number of rows for a reasonable-sized strip according to the current + settings of the , + and tags and any compression-specific requirements. + + The esimated value (may be zero). + The number of rows for a reasonable-sized strip according to the current + tag settings and compression-specific requirements. + + + + Computes the pixel width and height of a reasonable-sized tile suitable for setting + up the and tags. + + The proposed tile width upon the call / tile width to use + after the call. + The proposed tile height upon the call / tile height to use + after the call. + + + + Frees and releases all resources allocated by this . + + + + + Invokes the library-wide error handling methods to (normally) write an error message + to the . + + An instance of the class. Can be null. + The method where an error is detected. + A composite format string (see Remarks). + An object array that contains zero or more objects to format. + + + + Invokes the library-wide error handling methods to (normally) write an error message + to the . + + The method where an error is detected. + A composite format string (see Remarks). + An object array that contains zero or more objects to format. + + + + Invokes the library-wide error handling methods to (normally) write an error message + to the . + + An instance of the class. Can be null. + The client data to be passed to error handler. + The method where an error is detected. + A composite format string (see Remarks). + An object array that contains zero or more objects to format. + + + + Invokes the library-wide error handling methods to (normally) write an error message + to the . + + The client data to be passed to error handler. + The method where an error is detected. + A composite format string (see Remarks). + An object array that contains zero or more objects to format. + + + + Retrieves field information for the tag with specified name. + + The name of the tag to retrieve field information for. + The field information for specified tag or null if + the field information wasn't found. + + + + Retrieves field information for the specified tag. + + The tag to retrieve field information for. + The field information for specified tag or null if + the field information wasn't found. + + + + Gets the name of the file or ID string for this . + + The name of the file or ID string for this . + + + + Retrieves the codec registered for the specified compression scheme. + + The compression scheme. + The codec registered for the specified compression scheme or null + if there is no codec registered for the given scheme. + + + + Retrieves field information for the specified tag. + + The tag to retrieve field information for. + The tiff data type to use us additional filter. + The field information for specified tag with specified type or null if + the field information wasn't found. + + + + Retrieves field information for the tag with specified name. + + The name of the tag to retrieve field information for. + The tiff data type to use us additional filter. + The field information for specified tag with specified type or null if + the field information wasn't found. + + + + Flushes pending writes to an open TIFF file. + + + true if succeeded; otherwise, false + + + + Flushes any pending image data for the specified file to be written out. + + + true if succeeded; otherwise, false + + + + Releases storage associated with current directory. + + + + + Gets the A component from ABGR value returned by + ReadRGBAImage. + + The ABGR value. + The A component from ABGR value. + + + + Gets the B component from ABGR value returned by + ReadRGBAImage. + + The ABGR value. + The B component from ABGR value. + + + + Retrieves a bit reversal table. + + if set to true then bit reversal table will be + retrieved; otherwise, the table that do not reverse bit values will be retrieved. + The bit reversal table. + + + + Gets the extra information with specified name associated with this . + + Name of the extra information to retrieve. + The extra information with specified name associated with + this or null if extra information with specified + name was not found. + + + + Retrieves an array of configured codecs, both built-in and registered by user. + + An array of configured codecs. + + + + Gets the value(s) of a tag in an open TIFF file. + + The tag. + The value(s) of a tag in an open TIFF file as array of + objects or null if there is no such tag set. + + + + Gets the value(s) of a tag in an open TIFF file or default value(s) of a tag if a tag + is not defined in the current directory and it has a default value(s). + + The tag. + + The value(s) of a tag in an open TIFF file as array of + objects or null if there is no such tag set and + tag has no default value. + + + + + Gets the G component from ABGR value returned by + ReadRGBAImage. + + The ABGR value. + The G component from ABGR value. + + + + Gets the mode with which the underlying file or stream was opened. + + The mode with which the underlying file or stream was opened. + + + + Gets the R component from ABGR value returned by + ReadRGBAImage. + + The ABGR value. + The R component from ABGR value. + + + + Gets the tiff stream. + + The tiff stream. + + + + Gets the number of elements in the custom tag list. + + The number of elements in the custom tag list. + + + + Retrieves the custom tag with specified index. + + The zero-based index of a custom tag to retrieve. + The custom tag with specified index. + + + + Gets the currently used tag methods. + + The currently used tag methods. + + + + Gets the library version string. + + The library version string. + + + + Converts array of 32-bit values into array of bytes. + + The array of 32-bit values. + The zero-based offset in at + which to begin converting bytes. + The number of 32-bit values to convert. + The byte array to store converted values at. + The zero-based offset in at + which to begin storing converted values. + + + + Gets the value indicating whether given image data was written in big-endian order. + + + true if given image data was written in big-endian order; otherwise, false. + + + + + Gets the value indicating whether the image data was in a different byte-order than + the host computer. + + + true if the image data was in a different byte-order than the host + computer or false if the TIFF file/stream and local host byte-orders are the + same. + + + + Checks whether library has working codec for the specific compression scheme. + + The scheme to check. + + true if the codec is configured and working; otherwise, false. + + + + + Gets the value indicating whether the image data is being returned in MSB-to-LSB + bit order. + + + true if the data is being returned in MSB-to-LSB bit order (i.e with bit 0 as + the most significant bit); otherwise, false. + + + + + Gets the value indicating whether the image data of this has a + tiled organization. + + + true if the image data of this has a tiled organization or + false if the image data of this is organized in strips. + + + + + Gets the value indicating whether the image data returned through the read interface + methods is being up-sampled. + + + true if the data is returned up-sampled; otherwise, false. + + + + + Returns an indication of whether the current directory is the last directory + in the file. + + + true if current directory is the last directory in the file; + otherwise, false. + + + + Merges given field information to existing one. + + The array of objects. + The number of items to use from the array. + + + + Gets the number of directories in a file. + + The number of directories in a file. + + + + Retrives the number of strips in the image. + + The number of strips in the image. + + + + Retrives the number of tiles in the image. + + The number of tiles in the image. + + + + Initializes new instance of class and opens a TIFF file for + reading or writing. + + The name of the file to open. + The open mode. Specifies if the file is to be opened for + reading ("r"), writing ("w"), or appending ("a") and, optionally, whether to override + certain default aspects of library operation (see remarks). + The new instance of class if specified file is + successfully opened; otherwise, null. + + + + Prints formatted description of the contents of the current directory to the + specified stream. + + The stream. + + + + Prints formatted description of the contents of the current directory to the + specified stream using specified print (formatting) options. + + The stream. + The print (formatting) options. + + + + Calculates the size in bytes of a complete decoded and packed raster scanline. + + The size in bytes of a complete decoded and packed raster scanline. + + + + Computes the number of bytes in a raw (i.e. not decoded) strip. + + The zero-based index of a strip. + The number of bytes in a raw strip. + + + + Computes the number of bytes in a raw (i.e. not decoded) tile. + + The zero-based index of a tile. + The number of bytes in a raw tile. + + + + Sets up the data buffer used to read raw (encoded) data from a file. + + The data buffer. + The buffer size. + + + + Reads a custom directory from the arbitrary offset within file/stream. + + The directory offset. + The array of objects to merge to + existing field information. + The number of items to use from + the array. + + true if a custom directory was read successfully; + otherwise, false + + + + Reads the contents of the next TIFF directory in an open TIFF file/stream and makes + it the current directory. + + + true if directory was successfully read; otherwise, false if an + error was encountered, or if there are no more directories to be read. + + + + Reads a strip of data from an open TIFF file/stream, decompresses it and places + specified amount of decompressed bytes into the user supplied buffer. + + The zero-based index of the strip to read. + The buffer to place decompressed strip bytes to. + The zero-based byte offset in buffer at which to begin storing + decompressed strip bytes. + The maximum number of decompressed strip bytes to be stored + to buffer. + The actual number of bytes of data that were placed in buffer or -1 if an + error was encountered. + + + + Reads a tile of data from an open TIFF file/stream, decompresses it and places + specified amount of decompressed bytes into the user supplied buffer. + + The zero-based index of the tile to read. + The buffer to place decompressed tile bytes to. + The zero-based byte offset in buffer at which to begin storing + decompressed tile bytes. + The maximum number of decompressed tile bytes to be stored + to buffer. + The actual number of bytes of data that were placed in buffer or -1 if an + error was encountered. + + + + Reads an EXIF directory from the given offset within file/stream. + + The directory offset. + + true if an EXIF directory was read successfully; + otherwise, false + + + + Reads the undecoded contents of a strip of data from an open TIFF file/stream and + places specified amount of read bytes into the user supplied buffer. + + The zero-based index of the strip to read. + The buffer to place read bytes to. + The zero-based byte offset in buffer at which to begin storing + read bytes. + The maximum number of read bytes to be stored to buffer. + The actual number of bytes of data that were placed in buffer or -1 if an + error was encountered. + + + + Reads the undecoded contents of a tile of data from an open TIFF file/stream and places + specified amount of read bytes into the user supplied buffer. + + The zero-based index of the tile to read. + The buffer to place read tile bytes to. + The zero-based byte offset in buffer at which to begin storing + read tile bytes. + The maximum number of read tile bytes to be stored to buffer. + The actual number of bytes of data that were placed in buffer or -1 if an + error was encountered. + + + + Reads the image and decodes it into RGBA format raster. + + The raster width. + The raster height. + The raster (the buffer to place decoded image data to). + + true if the image was successfully read and converted; otherwise, + false is returned if an error was encountered. + + + + Reads the image and decodes it into RGBA format raster. + + The raster width. + The raster height. + The raster (the buffer to place decoded image data to). + if set to true then an error will terminate the + operation; otherwise method will continue processing data until all the possible data + in the image have been requested. + + true if the image was successfully read and converted; otherwise, false + is returned if an error was encountered and stopOnError is false. + + + + + Reads the image and decodes it into RGBA format raster using specified raster origin. + + The raster width. + The raster height. + The raster (the buffer to place decoded image data to). + The raster origin position. + + true if the image was successfully read and converted; otherwise, false + is returned if an error was encountered. + + + + + Reads the image and decodes it into RGBA format raster using specified raster origin. + + The raster width. + The raster height. + The raster (the buffer to place decoded image data to). + The raster origin position. + if set to true then an error will terminate the + operation; otherwise method will continue processing data until all the possible data + in the image have been requested. + + true if the image was successfully read and converted; otherwise, false + is returned if an error was encountered and stopOnError is false. + + + + + Reads a whole strip of a strip-based image, decodes it and converts it to RGBA format. + + The row. + The RGBA raster. + + true if the strip was successfully read and converted; otherwise, + false + + + + Reads a whole tile of a tile-based image, decodes it and converts it to RGBA format. + + The column. + The row. + The RGBA raster. + + true if the strip was successfully read and converted; otherwise, + false + + + + Reads and decodes a scanline of data from an open TIFF file/stream. + + The buffer to place read and decoded image data to. + The zero-based index of scanline (row) to read. + + true if image data were read and decoded successfully; otherwise, false + + + + Reads and decodes a scanline of data from an open TIFF file/stream. + + The buffer to place read and decoded image data to. + The zero-based index of scanline (row) to read. + The zero-based index of the sample plane. + + true if image data were read and decoded successfully; otherwise, false + + + + Reads and decodes a scanline of data from an open TIFF file/stream. + + The buffer to place read and decoded image data to. + The zero-based byte offset in at which + to begin storing read and decoded bytes. + The zero-based index of scanline (row) to read. + The zero-based index of the sample plane. + + true if image data were read and decoded successfully; otherwise, false + + + + Reads and decodes a tile of data from an open TIFF file/stream. + + The buffer to place read and decoded image data to. + The zero-based byte offset in at which + to begin storing read and decoded bytes. + The x-coordinate of the pixel within a tile to be read and decoded. + The y-coordinate of the pixel within a tile to be read and decoded. + The z-coordinate of the pixel within a tile to be read and decoded. + The zero-based index of the sample plane. + The number of bytes in the decoded tile or -1 if an error occurred. + + + + Allocates new byte array of specified size and copies data from the existing to + the new array. + + The existing array. + The number of elements in new array. + + The new byte array of specified size with data from the existing array. + + + + + Allocates new integer array of specified size and copies data from the existing to + the new array. + + The existing array. + The number of elements in new array. + + The new integer array of specified size with data from the existing array. + + + + + Adds specified codec to a list of registered codec. + + The codec to register. + + + + Replaces specified number of bytes in with the + equivalent bit-reversed bytes. + + The buffer to replace bytes in. + The number of bytes to process. + + + + Replaces specified number of bytes in with the + equivalent bit-reversed bytes starting at specified offset. + + The buffer to replace bytes in. + The zero-based offset in at + which to begin processing bytes. + The number of bytes to process. + + + + Rewrites the contents of the current directory to the file and setup to create a new + subfile (page) in the same file. + + + true if the current directory was rewritten successfully; + otherwise, false + + + + Check the image to see if it can be converted to RGBA format. + + The error message (if any) gets placed here. + + true if the image can be converted to RGBA format; otherwise, + false is returned and contains the reason why it + is being rejected. + + + + Calculates the size in bytes of a row of data as it would be returned in a call to + , or as it would be + expected in a call to . + + The size in bytes of a row of data. + + + + Asscociates a custom data with this . + + The data to associate. + The previously associated data. + + + + Associates extra information with this . + + The information to associate with this . + The name (label) of the information. + + + + Sets the directory with specified number as the current directory. + + The zero-based number of the directory to set as the + current directory. + + true if the specified directory was set as current successfully; + otherwise, false + + + + Sets an instance of the class as custom library-wide + error and warning handler. + + An instance of the class + to set as custom library-wide error and warning handler. + + Previous error handler or null if there was no error handler set. + + + + + Sets the value(s) of a tag in a TIFF file/stream open for writing. + + The tag. + The tag value(s). + + true if tag value(s) were set successfully; otherwise, false. + + + + Sets the new ID string for this . + + The ID string for this . + The previous file name or ID string for this . + + + + Sets the new mode for the underlying file or stream. + + The new mode for the underlying file or stream. + The previous mode with which the underlying file or stream was opened. + + + + Sets the directory at specified file/stream offset as the current directory. + + The offset from the beginnig of the file/stream to the directory + to set as the current directory. + + true if the directory at specified file offset was set as current + successfully; otherwise, false + + + + Sets the tag extender method. + + The tag extender method. + Previous tag extender method. + + + + Sets the new tag methods to use. + + Tag methods. + The previously used tag methods. + + + + Setups the strips. + + + true if setup successfully; otherwise, false + + + + Sets the current write offset. + + The write offset. + + + + Converts array of 16-bit values into array of bytes. + + The array of 16-bit values. + The zero-based offset in at + which to begin converting bytes. + The number of 16-bit values to convert. + The byte array to store converted values at. + The zero-based offset in at + which to begin storing converted values. + + + + Computes the number of bytes in a row-aligned strip. + + The number of bytes in a row-aligned strip + + + + Swaps the bytes in specified number of values in the array of double-precision + floating-point numbers. + + The array to swap bytes in. + The number of items to swap bytes in. + + + + Swaps the bytes in specified number of values in the array of double-precision + floating-point numbers starting at specified offset. + + The array to swap bytes in. + The zero-based offset in at + which to begin swapping bytes. + The number of items to swap bytes in. + + + + Swaps the bytes in specified number of values in the array of 32-bit items. + + The array to swap bytes in. + The number of items to swap bytes in. + + + + Swaps the bytes in specified number of values in the array of 32-bit items + starting at specified offset. + + The array to swap bytes in. + The zero-based offset in at + which to begin swapping bytes. + The number of items to swap bytes in. + + + + Swaps the bytes in specified number of values in the array of 16-bit items. + + The array to swap bytes in. + The number of items to swap bytes in. + + + + Swaps the bytes in specified number of values in the array of 16-bit items starting at + specified offset. + + The array to swap bytes in. + The zero-based offset in at + which to begin swapping bytes. + The number of items to swap bytes in. + + + + Swaps the bytes in specified number of values in the array of triples (24-bit items). + + The array to swap bytes in. + The number of items to swap bytes in. + + + + Swaps the bytes in specified number of values in the array of triples (24-bit items) + starting at specified offset. + + The array to swap bytes in. + The zero-based offset in at + which to begin swapping bytes. + The number of items to swap bytes in. + + + + Swaps the bytes in a single double-precision floating-point number. + + The value to swap bytes in. + + + + Swaps the bytes in a single 32-bit item. + + The value to swap bytes in. + + + + Swaps the bytes in a single 16-bit item. + + The value to swap bytes in. + + + + Compute the number of bytes in each row of a tile. + + The number of bytes in each row of a tile. + + + + Compute the number of bytes in a row-aligned tile. + + The number of bytes in a row-aligned tile. + + + + Unlinks the specified directory from the directory chain. + + The zero-based number of the directory to unlink. + + true if directory was unlinked successfully; otherwise, false. + + + + Removes specified codec from a list of registered codecs. + + The codec to remove from a list of registered codecs. + + + + Computes the number of bytes in a row-aligned strip with specified number of rows. + + The number of rows in a strip. + + The number of bytes in a row-aligned strip with specified number of rows. + + + + Computes the number of bytes in a row-aligned tile with specified number of rows. + + The number of rows in a tile. + + The number of bytes in a row-aligned tile with specified number of rows. + + + + Invokes the library-wide warning handling methods to (normally) write a warning message + to the . + + An instance of the class. Can be null. + The method in which a warning is detected. + A composite format string (see Remarks). + An object array that contains zero or more objects to format. + + + + Invokes the library-wide warning handling methods to (normally) write a warning message + to the . + + The method in which a warning is detected. + A composite format string (see Remarks). + An object array that contains zero or more objects to format. + + + + Invokes the library-wide warning handling methods to (normally) write a warning message + to the and passes client data to the warning handler. + + An instance of the class. Can be null. + The client data to be passed to warning handler. + The method in which a warning is detected. + A composite format string (see Remarks). + An object array that contains zero or more objects to format. + + + + Invokes the library-wide warning handling methods to (normally) write a warning message + to the and passes client data to the warning handler. + + The client data to be passed to warning handler. + The method in which a warning is detected. + A composite format string (see Remarks). + An object array that contains zero or more objects to format. + + + + Sets up the data buffer used to write raw (encoded) data to a file. + + The data buffer. + The buffer size. + + + + Verifies that file/stream is writable and that the directory information is + setup properly. + + If set to true then ability to write tiles will be verified; + otherwise, ability to write strips will be verified. + The name of the calling method. + + true if file/stream is writeable and the directory information is + setup properly; otherwise, false + + + + Writes the contents of the current directory to the file and setup to create a new + subfile (page) in the same file. + + + true if the current directory was written successfully; + otherwise, false + + + + Encodes and writes a strip of data to an open TIFF file/stream. + + The zero-based index of the strip to write. + The buffer with image data to be encoded and written. + The maximum number of strip bytes to be read from + . + + The number of encoded and written bytes or -1 if an error occurred. + + + + + Encodes and writes a strip of data to an open TIFF file/stream. + + The zero-based index of the strip to write. + The buffer with image data to be encoded and written. + The zero-based byte offset in at which + to begin reading bytes to be encoded and written. + The maximum number of strip bytes to be read from + . + The number of encoded and written bytes or -1 if an error occurred. + + + + Encodes and writes a tile of data to an open TIFF file/stream. + + The zero-based index of the tile to write. + The buffer with image data to be encoded and written. + The maximum number of tile bytes to be read from + . + + The number of encoded and written bytes or -1 if an error occurred. + + + + + Encodes and writes a tile of data to an open TIFF file/stream. + + The zero-based index of the tile to write. + The buffer with image data to be encoded and written. + The zero-based byte offset in at which + to begin reading bytes to be encoded and written. + The maximum number of tile bytes to be read from + . + The number of encoded and written bytes or -1 if an error occurred. + + + + Writes a strip of raw data to an open TIFF file/stream. + + The zero-based index of the strip to write. + The buffer with raw image data to be written. + The maximum number of strip bytes to be read from + . + + The number of written bytes or -1 if an error occurred. + + + + + Writes a strip of raw data to an open TIFF file/stream. + + The zero-based index of the strip to write. + The buffer with raw image data to be written. + The zero-based byte offset in at which + to begin reading bytes to be written. + The maximum number of strip bytes to be read from + . + The number of written bytes or -1 if an error occurred. + + + + Writes a tile of raw data to an open TIFF file/stream. + + The zero-based index of the tile to write. + The buffer with raw image data to be written. + The maximum number of tile bytes to be read from + . + + The number of written bytes or -1 if an error occurred. + + + + + Writes a tile of raw data to an open TIFF file/stream. + + The zero-based index of the tile to write. + The buffer with raw image data to be written. + The zero-based byte offset in at which + to begin reading bytes to be written. + The maximum number of tile bytes to be read from + . + The number of written bytes or -1 if an error occurred. + + + + Encodes and writes a scanline of data to an open TIFF file/stream. + + The buffer with image data to be encoded and written. + The zero-based index of scanline (row) to place encoded data at. + + true if image data were encoded and written successfully; otherwise, false + + + + Encodes and writes a scanline of data to an open TIFF file/stream. + + The buffer with image data to be encoded and written. + The zero-based index of scanline (row) to place encoded data at. + The zero-based index of the sample plane. + + true if image data were encoded and written successfully; otherwise, false + + + + Encodes and writes a scanline of data to an open TIFF file/stream. + + The buffer with image data to be encoded and written. + The zero-based byte offset in at which + to begin reading bytes. + The zero-based index of scanline (row) to place encoded data at. + The zero-based index of the sample plane. + + true if image data were encoded and written successfully; otherwise, false + + + + Encodes and writes a tile of data to an open TIFF file/stream. + + The buffer with image data to be encoded and written. + The x-coordinate of the pixel within a tile to be encoded and written. + The y-coordinate of the pixel within a tile to be encoded and written. + The z-coordinate of the pixel within a tile to be encoded and written. + The zero-based index of the sample plane. + + The number of encoded and written bytes or -1 if an error occurred. + + + + + Encodes and writes a tile of data to an open TIFF file/stream. + + The buffer with image data to be encoded and written. + The zero-based byte offset in at which + to begin reading bytes to be encoded and written. + The x-coordinate of the pixel within a tile to be encoded and written. + The y-coordinate of the pixel within a tile to be encoded and written. + The z-coordinate of the pixel within a tile to be encoded and written. + The zero-based index of the sample plane. + The number of encoded and written bytes or -1 if an error occurred. + + + + Delegate for a method used to image decoded spans. + + The buffer to place decoded image data to. + The zero-based byte offset in at + which to begin storing decoded bytes. + The array of black and white run lengths (white then black). + The zero-based offset in array at + which current row's run begins. + The zero-based offset in array at + which next row's run begins. + The width in pixels of the row. + + + + Delegate for LibTiff.Net extender method + + An instance of the class. + + + + Base class for all codecs within the library. + + + + + Initializes a new instance of the class. + + An instance of class. + The compression scheme for the codec. + The name of the codec. + + + + Gets a value indicating whether this codec can decode data. + + + + + Gets a value indicating whether this codec can encode data. + + + + + Cleanups the state of the codec. + + + + + Flushes any internal data buffers and terminates current operation. + + + + + Decodes one row of image data. + + The buffer to place decoded image data to. + The zero-based byte offset in at + which to begin storing decoded bytes. + The number of decoded bytes that should be placed + to . + The zero-based sample plane index. + + true if image data was decoded successfully; otherwise, false. + + + + + Decodes one strip of image data. + + The buffer to place decoded image data to. + The zero-based byte offset in at + which to begin storing decoded bytes. + The number of decoded bytes that should be placed + to . + The zero-based sample plane index. + + true if image data was decoded successfully; otherwise, false. + + + + + Decodes one tile of image data. + + The buffer to place decoded image data to. + The zero-based byte offset in at + which to begin storing decoded bytes. + The number of decoded bytes that should be placed + to . + The zero-based sample plane index. + + true if image data was decoded successfully; otherwise, false. + + + + + Calculates and/or constrains a strip size. + + The proposed strip size (may be zero or negative). + A strip size to use. + + + + Calculate and/or constrains a tile size + + The proposed tile width upon the call / tile width to use after the call. + The proposed tile height upon the call / tile height to use after the call. + + + + Encodes one row of image data. + + The buffer with image data to be encoded. + The zero-based byte offset in at + which to begin read image data. + The maximum number of encoded bytes that can be placed + to . + The zero-based sample plane index. + + true if image data was encoded successfully; otherwise, false. + + + + + Encodes one strip of image data. + + The buffer with image data to be encoded. + The zero-based byte offset in at + which to begin read image data. + The maximum number of encoded bytes that can be placed + to . + The zero-based sample plane index. + + true if image data was encoded successfully; otherwise, false. + + + + + Encodes one tile of image data. + + The buffer with image data to be encoded. + The zero-based byte offset in at + which to begin read image data. + The maximum number of encoded bytes that can be placed + to . + The zero-based sample plane index. + + true if image data was encoded successfully; otherwise, false. + + + + + Initializes this instance. + + + true if initialized successfully + + + + Codec name. + + + + + Compression scheme this codec impelements. + + + + + An instance of . + + + + + Performs any actions after encoding required by the codec. + + + true if all post-encode actions succeeded; otherwise, false + + + + Prepares the decoder part of the codec for a decoding. + + The zero-based sample plane index. + + true if this codec successfully prepared its decoder part and ready + to decode data; otherwise, false. + + + + Prepares the encoder part of the codec for a encoding. + + The zero-based sample plane index. + + true if this codec successfully prepared its encoder part and ready + to encode data; otherwise, false. + + + + Seeks the specified row in the strip being processed. + + The row to seek. + + true if specified row was successfully found; otherwise, false + + + + Setups the decoder part of the codec. + + + true if this codec successfully setup its decoder part and can decode data; + otherwise, false. + + + + + Setups the encoder part of the codec. + + + true if this codec successfully setup its encoder part and can encode data; + otherwise, false. + + + + + Default error handler implementation. + + + + Initializes a new instance of the class + + + + Handles an error by writing it text to the . + + An instance of the class. Can be null. + The method where an error is detected. + A composite format string (see Remarks). + An object array that contains zero or more objects to format. + + + + Handles an error by writing it text to the . + + An instance of the class. Can be null. + A client data. + The method where an error is detected. + A composite format string (see Remarks). + An object array that contains zero or more objects to format. + + + + Handles a warning by writing it text to the . + + An instance of the class. Can be null. + The method where a warning is detected. + A composite format string (see Remarks). + An object array that contains zero or more objects to format. + + + + Handles a warning by writing it text to the . + + An instance of the class. Can be null. + A client data. + The method where a warning is detected. + A composite format string (see Remarks). + An object array that contains zero or more objects to format. + + + + Represents a TIFF field information. + + + + + Initializes a new instance of the class. + + The tag to describe. + The number of values to read when reading field information or + one of , and . + The number of values to write when writing field information + or one of , and . + The type of the field value. + Index of the bit to use in "Set Fields Vector" when this instance + is merged into field info collection. Take a look at class. + If true, then it is permissible to set the tag's value even + after writing has commenced. + If true, then number of value elements should be passed to + method as second parameter (right after tag type AND + before value itself). + The name (description) of the tag this instance describes. + + + + Index of the bit to use in "Set Fields Vector" when this instance + is merged into field info collection. Take a look at class. + + + + + The name (or description) of the tag this instance describes. + + + + + If true, then it is permissible to set the tag's value even after writing has commenced. + + + + + If true, then number of value elements should be passed to + method as second parameter (right after tag type AND before values itself). + + + + + Number of values to read when reading field information or + one of , and . + + + + + marker for SamplesPerPixel-bound tags + + + + + The tag described by this instance. + + + + + Returns a that represents this instance. + + + A that represents this instance. + + + + + Type of the field values. + + + + + marker for variable length tags + + + + + marker for integer variable length tags + + + + + Number of values to write when writing field information or + one of , and . + + + + + Flags that can be passed to + method to control printing of data structures that are potentially very large. + + + + + no extra info + + + + + strips/tiles info + + + + + color/gray response curves + + + + + colormap + + + + + JPEG Q matrices + + + + + JPEG AC tables + + + + + JPEG DC tables + + + + + RGBA-style image support. Provides methods for decoding images into RGBA (or other) format. + + + + + Gets the type of alpha data present. + + + + + Gets the image bits per sample count. + + + + + Creates new instance of the class. + + + The instance of the class used to retrieve + image data. + + + if set to true then an error will terminate the conversion; otherwise "get" + methods will continue processing data until all the possible data in the image have + been requested. + + The error message (if any) gets placed here. + + New instance of the class if the image specified + by can be converted to RGBA format; otherwise, null is + returned and contains the reason why it is being + rejected. + + + + + Gets or sets the "get" method (the method that is called to produce RGBA raster). + + + + + Reads the underlaying TIFF image and decodes it into RGBA format raster. + + The raster (the buffer to place decoded image data to). + The zero-based byte offset in at which + to begin storing decoded bytes. + The raster width. + The raster height. + + true if the image was successfully read and decoded; otherwise, + false. + + + + Gets the image height. + + + + + Gets a value indicating whether image data has contiguous (packed) or separated samples. + + + + + Gets the image orientation. + + + + + Gets the photometric interpretation of the image data. + + + + + Gets or sets the "put" method (the method that is called to pack pixel data in the + raster) used when converting contiguously packed samples. + + + + + Gets or sets the "put" method (the method that is called to pack pixel data in the + raster) used when converting separated samples. + + + + + Gets or sets the requested orientation. + + + + + Gets the image samples per pixel count. + + + + + Gets the image width. + + + + + Delegate for "get" method (the method that is called to produce RGBA raster). + + An instance of the class. + The raster (the buffer to place decoded image data to). + The zero-based byte offset in at which + to begin storing decoded bytes. + The raster width. + The raster height. + + true if the image was successfully read and decoded; otherwise, + false. + + + + Delegate for "put" method (the method that is called to pack pixel data in the raster) + used when converting contiguously packed samples. + + An instance of the class. + The raster (the buffer to place decoded image data to). + The zero-based byte offset in at + which to begin storing decoded bytes. + The value that should be added to + after each row processed. + The x-coordinate of the first pixel in block of pixels to be decoded. + The y-coordinate of the first pixel in block of pixels to be decoded. + The block width. + The block height. + The buffer with image data. + The zero-based byte offset in at + which to begin reading image bytes. + The value that should be added to + after each row processed. + + + + Delegate for "put" method (the method that is called to pack pixel data in the raster) + used when converting separated samples. + + An instance of the class. + The raster (the buffer to place decoded image data to). + The zero-based byte offset in at + which to begin storing decoded bytes. + The value that should be added to + after each row processed. + The x-coordinate of the first pixel in block of pixels to be decoded. + The y-coordinate of the first pixel in block of pixels to be decoded. + The block width. + The block height. + The buffer with image data. + The zero-based byte offset in at + which to begin reading image bytes that constitute first sample plane. + The zero-based byte offset in at + which to begin reading image bytes that constitute second sample plane. + The zero-based byte offset in at + which to begin reading image bytes that constitute third sample plane. + The zero-based byte offset in at + which to begin reading image bytes that constitute fourth sample plane. + The value that should be added to , + , and + after each row processed. + + + + A stream used by the library for TIFF reading and writing. + + + + Initializes a new instance of the class + + + + Closes the current stream. + + A client data (by default, an underlying stream). + + + + Reads a sequence of bytes from the stream and advances the position within the stream + by the number of bytes read. + + A client data (by default, an underlying stream). + An array of bytes. When this method returns, the + contains the specified byte array with the values between + and ( + - 1) + replaced by the bytes read from the current source. + The zero-based byte offset in at which + to begin storing the data read from the current stream. + The maximum number of bytes to be read from the current stream. + The total number of bytes read into the . This can + be less than the number of bytes requested if that many bytes are not currently + available, or zero (0) if the end of the stream has been reached. + + + + Sets the position within the current stream. + + A client data (by default, an underlying stream). + A byte offset relative to the parameter. + A value of type indicating the + reference point used to obtain the new position. + The new position within the current stream. + + + + Gets the length in bytes of the stream. + + A client data (by default, an underlying stream). + The length of the stream in bytes. + + + + Writes a sequence of bytes to the current stream and advances the current position + within this stream by the number of bytes written. + + A client data (by default, an underlying stream). + An array of bytes. This method copies + bytes from to the current stream. + The zero-based byte offset in at which + to begin copying bytes to the current stream. + The number of bytes to be written to the current stream. + + + + TIFF tag definitions. + + + + + Tag placeholder + + + + + Subfile data descriptor. + For the list of possible values, see . + + + + + [obsoleted by TIFF rev. 5.0]
+ Kind of data in subfile. For the list of possible values, see . + + + + + Image width in pixels. + + + + + Image height in pixels. + + + + + Bits per channel (sample). + + + + + Data compression technique. + For the list of possible values, see . + + + + + Photometric interpretation. + For the list of possible values, see . + + + + + [obsoleted by TIFF rev. 5.0]
+ Thresholding used on data. For the list of possible values, see . + + + + + [obsoleted by TIFF rev. 5.0]
+ Dithering matrix width. + + + + + [obsoleted by TIFF rev. 5.0]
+ Dithering matrix height. + + + + + Data order within a byte. + For the list of possible values, see . + + + + + Name of document which holds for image. + + + + + Information about image. + + + + + Scanner manufacturer name. + + + + + Scanner model name/number. + + + + + Offsets to data strips. + + + + + [obsoleted by TIFF rev. 5.0]
+ Image orientation. For the list of possible values, see . + + + + + Samples per pixel. + + + + + Rows per strip of data. + + + + + Bytes counts for strips. + + + + + [obsoleted by TIFF rev. 5.0]
+ Minimum sample value. + + + + + [obsoleted by TIFF rev. 5.0]
+ Maximum sample value. + + + + + Pixels/resolution in x. + + + + + Pixels/resolution in y. + + + + + Storage organization. + For the list of possible values, see . + + + + + Page name image is from. + + + + + X page offset of image lhs. + + + + + Y page offset of image lhs. + + + + + [obsoleted by TIFF rev. 5.0]
+ Byte offset to free block. + + + + + [obsoleted by TIFF rev. 5.0]
+ Sizes of free blocks. + + + + + [obsoleted by TIFF rev. 6.0]
+ Gray scale curve accuracy. + For the list of possible values, see . + + + + + [obsoleted by TIFF rev. 6.0]
+ Gray scale response curve. + + + + + Options for CCITT Group 3 fax encoding. 32 flag bits. + For the list of possible values, see . + + + + + TIFF 6.0 proper name alias for GROUP3OPTIONS. + + + + + Options for CCITT Group 4 fax encoding. 32 flag bits. + For the list of possible values, see . + + + + + TIFF 6.0 proper name alias for GROUP4OPTIONS. + + + + + Units of resolutions. + For the list of possible values, see . + + + + + Page numbers of multi-page. + + + + + [obsoleted by TIFF rev. 6.0]
+ Color curve accuracy. + For the list of possible values, see . + + + + + Colorimetry info. + + + + + Name & release. + + + + + Creation date and time. + + + + + Creator of image. + + + + + Machine where created. + + + + + Prediction scheme w/ LZW. + For the list of possible values, see . + + + + + Image white point. + + + + + Primary chromaticities. + + + + + RGB map for pallette image. + + + + + Highlight + shadow info. + + + + + Tile width in pixels. + + + + + Tile height in pixels. + + + + + Offsets to data tiles. + + + + + Byte counts for tiles. + + + + + Lines with wrong pixel count. + + + + + Regenerated line info. + For the list of possible values, see . + + + + + Max consecutive bad lines. + + + + + Subimage descriptors. + + + + + Inks in separated image. + For the list of possible values, see . + + + + + ASCII names of inks. + + + + + Number of inks. + + + + + 0% and 100% dot codes. + + + + + Separation target. + + + + + Information about extra samples. + For the list of possible values, see . + + + + + Data sample format. + For the list of possible values, see . + + + + + Variable MinSampleValue. + + + + + Variable MaxSampleValue. + + + + + ClipPath. Introduced post TIFF rev 6.0 by Adobe TIFF technote 2. + + + + + XClipPathUnits. Introduced post TIFF rev 6.0 by Adobe TIFF technote 2. + + + + + YClipPathUnits. Introduced post TIFF rev 6.0 by Adobe TIFF technote 2. + + + + + Indexed. Introduced post TIFF rev 6.0 by Adobe TIFF Technote 3. + + + + + JPEG table stream. Introduced post TIFF rev 6.0. + + + + + OPI Proxy. Introduced post TIFF rev 6.0 by Adobe TIFF technote. + + + + + [obsoleted by Technical Note #2 which specifies a revised JPEG-in-TIFF scheme]
+ JPEG processing algorithm. + For the list of possible values, see . + + + + + [obsoleted by Technical Note #2 which specifies a revised JPEG-in-TIFF scheme]
+ Pointer to SOI marker. + + + + + [obsoleted by Technical Note #2 which specifies a revised JPEG-in-TIFF scheme]
+ JFIF stream length + + + + + [obsoleted by Technical Note #2 which specifies a revised JPEG-in-TIFF scheme]
+ Restart interval length. + + + + + [obsoleted by Technical Note #2 which specifies a revised JPEG-in-TIFF scheme]
+ Lossless proc predictor. + + + + + [obsoleted by Technical Note #2 which specifies a revised JPEG-in-TIFF scheme]
+ Lossless point transform. + + + + + [obsoleted by Technical Note #2 which specifies a revised JPEG-in-TIFF scheme]
+ Q matrice offsets. + + + + + [obsoleted by Technical Note #2 which specifies a revised JPEG-in-TIFF scheme]
+ DCT table offsets. + + + + + [obsoleted by Technical Note #2 which specifies a revised JPEG-in-TIFF scheme]
+ AC coefficient offsets. + + + + + RGB -> YCbCr transform. + + + + + YCbCr subsampling factors. + + + + + Subsample positioning. + For the list of possible values, see . + + + + + Colorimetry info. + + + + + XML packet. Introduced post TIFF rev 6.0 by Adobe XMP Specification, January 2004. + + + + + OPI ImageID. Introduced post TIFF rev 6.0 by Adobe TIFF technote. + + + + + Image reference points. Private tag registered to Island Graphics. + + + + + Region-xform tack point. Private tag registered to Island Graphics. + + + + + Warp quadrilateral. Private tag registered to Island Graphics. + + + + + Affine transformation matrix. Private tag registered to Island Graphics. + + + + + [obsoleted by TIFF rev. 6.0]
+ Use EXTRASAMPLE tag. Private tag registered to SGI. + + + + + [obsoleted by TIFF rev. 6.0]
+ Use SAMPLEFORMAT tag. Private tag registered to SGI. + + + + + Z depth of image. Private tag registered to SGI. + + + + + Z depth/data tile. Private tag registered to SGI. + + + + + Full image size in X. This tag is set when an image has been cropped out of a larger + image. It reflect width of the original uncropped image. The XPOSITION tag can be used + to determine the position of the smaller image in the larger one. + Private tag registered to Pixar. + + + + + Full image size in Y. This tag is set when an image has been cropped out of a larger + image. It reflect height of the original uncropped image. The YPOSITION can be used + to determine the position of the smaller image in the larger one. + Private tag registered to Pixar. + + + + + Texture map format. Used to identify special image modes and data used by Pixar's + texture formats. Private tag registered to Pixar. + + + + + S&T wrap modes. Used to identify special image modes and data used by Pixar's + texture formats. Private tag registered to Pixar. + + + + + Cotan(fov) for env. maps. Used to identify special image modes and data used by + Pixar's texture formats. Private tag registered to Pixar. + + + + + Used to identify special image modes and data used by Pixar's texture formats. + Private tag registered to Pixar. + + + + + Used to identify special image modes and data used by Pixar's texture formats. + Private tag registered to Pixar. + + + + + Device serial number. Private tag registered to Eastman Kodak. + + + + + Copyright string. This tag is listed in the TIFF rev. 6.0 w/ unknown ownership. + + + + + IPTC TAG from RichTIFF specifications. + + + + + Site name. Reserved for ANSI IT8 TIFF/IT. + + + + + Color seq. [RGB, CMYK, etc]. Reserved for ANSI IT8 TIFF/IT. + + + + + DDES Header. Reserved for ANSI IT8 TIFF/IT. + + + + + Raster scanline padding. Reserved for ANSI IT8 TIFF/IT. + + + + + The number of bits in short run. Reserved for ANSI IT8 TIFF/IT. + + + + + The number of bits in long run. Reserved for ANSI IT8 TIFF/IT. + + + + + LW colortable. Reserved for ANSI IT8 TIFF/IT. + + + + + BP/BL image color switch. Reserved for ANSI IT8 TIFF/IT. + + + + + BP/BL bg color switch. Reserved for ANSI IT8 TIFF/IT. + + + + + BP/BL image color value. Reserved for ANSI IT8 TIFF/IT. + + + + + BP/BL bg color value. Reserved for ANSI IT8 TIFF/IT. + + + + + MP pixel intensity value. Reserved for ANSI IT8 TIFF/IT. + + + + + HC transparency switch. Reserved for ANSI IT8 TIFF/IT. + + + + + Color characterization table. Reserved for ANSI IT8 TIFF/IT. + + + + + HC usage indicator. Reserved for ANSI IT8 TIFF/IT. + + + + + Trapping indicator (untrapped = 0, trapped = 1). Reserved for ANSI IT8 TIFF/IT. + + + + + CMYK color equivalents. + + + + + Sequence Frame Count. Private tag registered to Texas Instruments. + + + + + Private tag registered to Adobe for PhotoShop. + + + + + Pointer to EXIF private directory. This tag is documented in EXIF specification. + + + + + ICC profile data. ?? Private tag registered to Adobe. ?? + + + + + JBIG options. Private tag registered to Pixel Magic. + + + + + Pointer to GPS private directory. This tag is documented in EXIF specification. + + + + + Encoded Class 2 ses. params. Private tag registered to SGI. + + + + + Received SubAddr string. Private tag registered to SGI. + + + + + Receive time (secs). Private tag registered to SGI. + + + + + Encoded fax ses. params, Table 2/T.30. Private tag registered to SGI. + + + + + Sample value to Nits. Private tag registered to SGI. + + + + + Private tag registered to FedEx. + + + + + Pointer to Interoperability private directory. + This tag is documented in EXIF specification. + + + + + DNG version number. Introduced by Adobe DNG specification. + + + + + DNG compatibility version. Introduced by Adobe DNG specification. + + + + + Name for the camera model. Introduced by Adobe DNG specification. + + + + + Localized camera model name. Introduced by Adobe DNG specification. + + + + + CFAPattern->LinearRaw space mapping. Introduced by Adobe DNG specification. + + + + + Spatial layout of the CFA. Introduced by Adobe DNG specification. + + + + + Lookup table description. Introduced by Adobe DNG specification. + + + + + Repeat pattern size for the BlackLevel tag. Introduced by Adobe DNG specification. + + + + + Zero light encoding level. Introduced by Adobe DNG specification. + + + + + Zero light encoding level differences (columns). Introduced by Adobe DNG specification. + + + + + Zero light encoding level differences (rows). Introduced by Adobe DNG specification. + + + + + Fully saturated encoding level. Introduced by Adobe DNG specification. + + + + + Default scale factors. Introduced by Adobe DNG specification. + + + + + Origin of the final image area. Introduced by Adobe DNG specification. + + + + + Size of the final image area. Introduced by Adobe DNG specification. + + + + + XYZ->reference color space transformation matrix 1. + Introduced by Adobe DNG specification. + + + + + XYZ->reference color space transformation matrix 2. + Introduced by Adobe DNG specification. + + + + + Calibration matrix 1. Introduced by Adobe DNG specification. + + + + + Calibration matrix 2. Introduced by Adobe DNG specification. + + + + + Dimensionality reduction matrix 1. Introduced by Adobe DNG specification. + + + + + Dimensionality reduction matrix 2. Introduced by Adobe DNG specification. + + + + + Gain applied the stored raw values. Introduced by Adobe DNG specification. + + + + + Selected white balance in linear reference space. + Introduced by Adobe DNG specification. + + + + + Selected white balance in x-y chromaticity coordinates. + Introduced by Adobe DNG specification. + + + + + How much to move the zero point. Introduced by Adobe DNG specification. + + + + + Relative noise level. Introduced by Adobe DNG specification. + + + + + Relative amount of sharpening. Introduced by Adobe DNG specification. + + + + + How closely the values of the green pixels in the blue/green rows + track the values of the green pixels in the red/green rows. + Introduced by Adobe DNG specification. + + + + + Non-linear encoding range. Introduced by Adobe DNG specification. + + + + + Camera's serial number. Introduced by Adobe DNG specification. + + + + + Information about the lens. + + + + + Chroma blur radius. Introduced by Adobe DNG specification. + + + + + Relative strength of the camera's anti-alias filter. + Introduced by Adobe DNG specification. + + + + + Used by Adobe Camera Raw. Introduced by Adobe DNG specification. + + + + + Manufacturer's private data. Introduced by Adobe DNG specification. + + + + + Whether the EXIF MakerNote tag is safe to preserve along with the rest of the EXIF data. + Introduced by Adobe DNG specification. + + + + + Illuminant 1. Introduced by Adobe DNG specification. + + + + + Illuminant 2. Introduced by Adobe DNG specification. + + + + + Best quality multiplier. Introduced by Adobe DNG specification. + + + + + Unique identifier for the raw image data. Introduced by Adobe DNG specification. + + + + + File name of the original raw file. Introduced by Adobe DNG specification. + + + + + Contents of the original raw file. Introduced by Adobe DNG specification. + + + + + Active (non-masked) pixels of the sensor. Introduced by Adobe DNG specification. + + + + + List of coordinates of fully masked pixels. Introduced by Adobe DNG specification. + + + + + Used to map cameras's color space into ICC profile space. + Introduced by Adobe DNG specification. + + + + + Used to map cameras's color space into ICC profile space. + Introduced by Adobe DNG specification. + + + + + Introduced by Adobe DNG specification. + + + + + Introduced by Adobe DNG specification. + + + + + Undefined tag used by Eastman Kodak, hue shift correction data. + + + + + [pseudo tag. not written to file]
+ Group 3/4 format control. + For the list of possible values, see . + + + + + [pseudo tag. not written to file]
+ Compression quality level. Quality level is on the IJG 0-100 scale. Default value is 75. + + + + + [pseudo tag. not written to file]
+ Auto RGB<=>YCbCr convert. + For the list of possible values, see . + + + + + [pseudo tag. not written to file]
+ For the list of possible values, see . + Default is | . + + + + + [pseudo tag. not written to file]
+ G3/G4 fill function. + + + + + [pseudo tag. not written to file]
+ PixarLogCodec I/O data sz. + + + + + [pseudo tag. not written to file]
+ Imager mode & filter. + Allocated to Oceana Matrix (dev@oceana.com). + + + + + [pseudo tag. not written to file]
+ Interpolation mode. + Allocated to Oceana Matrix (dev@oceana.com). + + + + + [pseudo tag. not written to file]
+ Color balance values. + Allocated to Oceana Matrix (dev@oceana.com). + + + + + [pseudo tag. not written to file]
+ Color correction values. + Allocated to Oceana Matrix (dev@oceana.com). + + + + + [pseudo tag. not written to file]
+ Gamma value. + Allocated to Oceana Matrix (dev@oceana.com). + + + + + [pseudo tag. not written to file]
+ Toe & shoulder points. + Allocated to Oceana Matrix (dev@oceana.com). + + + + + [pseudo tag. not written to file]
+ Calibration file description. + + + + + [pseudo tag. not written to file]
+ Compression quality level. + Quality level is on the ZLIB 1-9 scale. Default value is -1. + + + + + [pseudo tag. not written to file]
+ PixarLog uses same scale. + + + + + [pseudo tag. not written to file]
+ Area of image to acquire. + Allocated to Oceana Matrix (dev@oceana.com). + + + + + [pseudo tag. not written to file]
+ SGILog user data format. + + + + + [pseudo tag. not written to file]
+ SGILog data encoding control. + + + + + Exposure time. + + + + + F number. + + + + + Exposure program. + + + + + Spectral sensitivity. + + + + + ISO speed rating. + + + + + Optoelectric conversion factor. + + + + + Exif version. + + + + + Date and time of original data generation. + + + + + Date and time of digital data generation. + + + + + Meaning of each component. + + + + + Image compression mode. + + + + + Shutter speed. + + + + + Aperture. + + + + + Brightness. + + + + + Exposure bias. + + + + + Maximum lens aperture. + + + + + Subject distance. + + + + + Metering mode. + + + + + Light source. + + + + + Flash. + + + + + Lens focal length. + + + + + Subject area. + + + + + Manufacturer notes. + + + + + User comments. + + + + + DateTime subseconds. + + + + + DateTimeOriginal subseconds. + + + + + DateTimeDigitized subseconds. + + + + + Supported Flashpix version. + + + + + Color space information. + + + + + Valid image width. + + + + + Valid image height. + + + + + Related audio file. + + + + + Flash energy. + + + + + Spatial frequency response. + + + + + Focal plane X resolution. + + + + + Focal plane Y resolution. + + + + + Focal plane resolution unit. + + + + + Subject location. + + + + + Exposure index. + + + + + Sensing method. + + + + + File source. + + + + + Scene type. + + + + + CFA pattern. + + + + + Custom image processing. + + + + + Exposure mode. + + + + + White balance. + + + + + Digital zoom ratio. + + + + + Focal length in 35 mm film. + + + + + Scene capture type. + + + + + Gain control. + + + + + Contrast. + + + + + Saturation. + + + + + Sharpness. + + + + + Device settings description. + + + + + Subject distance range. + + + + + Unique image ID. + + + + + Tiff tag methods. + + + + Initializes a new instance of the class + + + + Gets the value(s) of a tag in an open TIFF file. + + An instance of the class. + The tag. + The value(s) of a tag in an open TIFF file/stream as array of + objects or null if there is no such tag set. + + + + Prints formatted description of the contents of the current directory to the + specified stream using specified print (formatting) options. + + An instance of the class. + The stream to print to. + The print (formatting) options. + + + + Sets the value(s) of a tag in a TIFF file/stream open for writing. + + An instance of the class. + The tag. + The tag value(s). + + true if tag value(s) were set successfully; otherwise, false. + + + + + Tag data type. + + + + + Placeholder. + + + + + For field descriptor searching. + + + + + 8-bit unsigned integer. + + + + + 8-bit bytes with last byte null. + + + + + 16-bit unsigned integer. + + + + + 32-bit unsigned integer. + + + + + 64-bit unsigned fraction. + + + + + 8-bit signed integer. + + + + + 8-bit untyped data. + + + + + 16-bit signed integer. + + + + + 32-bit signed integer. + + + + + 64-bit signed fraction. + + + + + 32-bit IEEE floating point. + + + + + 64-bit IEEE floating point. + + + + + 32-bit unsigned integer (offset) + + + + + Subsample positioning.
+ Possible values for .YCBCRPOSITIONING tag. + + + + + As in PostScript Level 2 + + + + + As in CCIR 601-1 + + + + \ No newline at end of file diff --git a/Resources/Libraries/Quartz/C5.dll b/Resources/Libraries/Quartz/C5.dll new file mode 100644 index 00000000..2130d1fa Binary files /dev/null and b/Resources/Libraries/Quartz/C5.dll differ diff --git a/Resources/Libraries/Quartz/ClientProfile/Quartz.dll b/Resources/Libraries/Quartz/ClientProfile/Quartz.dll new file mode 100644 index 00000000..f04797f8 Binary files /dev/null and b/Resources/Libraries/Quartz/ClientProfile/Quartz.dll differ diff --git a/Resources/Libraries/Quartz/ClientProfile/Quartz.pdb b/Resources/Libraries/Quartz/ClientProfile/Quartz.pdb new file mode 100644 index 00000000..7dd4a17f Binary files /dev/null and b/Resources/Libraries/Quartz/ClientProfile/Quartz.pdb differ diff --git a/Resources/Libraries/Quartz/ClientProfile/Quartz.xml b/Resources/Libraries/Quartz/ClientProfile/Quartz.xml new file mode 100644 index 00000000..de320e2a --- /dev/null +++ b/Resources/Libraries/Quartz/ClientProfile/Quartz.xml @@ -0,0 +1,20066 @@ + + + + Quartz + + + + + A wrapper for generic HashSet that brings a common interface. + + + + + + Represents a collection ob objects that contains no duplicate elements. + + Marko Lahma (.NET) + + + + A sorted set. + + Marko Lahma (.NET) + + + + Returns a portion of the list whose elements are greater than the limit object parameter. + + The start element of the portion to extract. + The portion of the collection whose elements are greater than the limit object parameter. + + + + Returns the first item in the set. + + First object. + + + + Returns the object in the specified index. + + + + + + + Simple C5 wrapper for common interface. + + + + + + Default constructor. + + + + + Constructor that accepts comparer. + + Comparer to use. + + + + Constructor that prepolutates. + + + + + + Returns the first element. + + + + + + Return items from given range. + + + + + + + Indexer. + + + + + + + Only for backwards compatibility with serialization! + + + + + Responsible for creating the instances of + to be used within the instance. + + James House + Marko Lahma (.NET) + + + + Initialize the factory, providing a handle to the + that should be made available within the and + the s within it. + + + + + Called by the + to obtain instances of . + + + + + JobRunShell instances are responsible for providing the 'safe' environment + for s to run in, and for performing all of the work of + executing the , catching ANY thrown exceptions, updating + the with the 's completion code, + etc. + + A instance is created by a + on behalf of the which then runs the + shell in a thread from the configured when the + scheduler determines that a has been triggered. + + + + + + + James House + Marko Lahma (.NET) + + + + A helpful abstract base class for implementors of + . + + + The methods in this class are empty so you only need to override the + subset for the events you care about. + + Marko Lahma (.NET) + + + + + The interface to be implemented by classes that want to be informed of major + events. + + + + + James House + Marko Lahma (.NET) + + + + Called by the when a + is scheduled. + + + + + Called by the when a + is unscheduled. + + + + + + Called by the when a + has reached the condition in which it will never fire again. + + + + + Called by the a s has been paused. + + + + + Called by the a group of + s has been paused. + + + If a all groups were paused, then the parameter + will be null. + + The trigger group. + + + + Called by the when a + has been un-paused. + + + + + Called by the when a + group of s has been un-paused. + + + If all groups were resumed, then the parameter + will be null. + + The trigger group. + + + + Called by the when a + has been added. + + + + + + Called by the when a + has been deleted. + + + + + Called by the when a + has been paused. + + + + + Called by the when a + group of s has been paused. + + If all groups were paused, then the parameter will be + null. If all jobs were paused, then both parameters will be null. + + + The job group. + + + + Called by the when a + has been un-paused. + + + + + Called by the when a + has been un-paused. + + The job group. + + + + Called by the when a serious error has + occurred within the scheduler - such as repeated failures in the , + or the inability to instantiate a instance when its + has fired. + + + + + Called by the to inform the listener + that it has move to standby mode. + + + + + Called by the to inform the listener + that it has started. + + + + + Called by the to inform the listener + that it has Shutdown. + + + + + Called by the to inform the listener + that it has begun the shutdown sequence. + + + + + Called by the to inform the listener + that all jobs, triggers and calendars were deleted. + + + + + Get the for this + type's category. This should be used by subclasses for logging. + + + + + This interface should be implemented by any class whose instances are intended + to be executed by a thread. + + Marko Lahma (.NET) + + + + This method has to be implemented in order that starting of the thread causes the object's + run method to be called in that separately executing thread. + + + + + Create a JobRunShell instance with the given settings. + + The instance that should be made + available within the . + + + + + Initializes the job execution context with given scheduler and bundle. + + The scheduler. + + + + Requests the Shutdown. + + + + + This method has to be implemented in order that starting of the thread causes the object's + run method to be called in that separately executing thread. + + + + + Runs begin procedures on this instance. + + + + + Completes the execution. + + if set to true [successful execution]. + + + + Passivates this instance. + + + + + Completes the trigger retry loop. + + The trigger. + The job detail. + The inst code. + + + + + Vetoeds the job retry loop. + + The trigger. + The job detail. + The inst code. + + + + + Default concrete implementation of . + + + + + Client programs may be interested in the 'listener' interfaces that are + available from Quartz. The interface + provides notifications of Job executions. The + interface provides notifications of + firings. The + interface provides notifications of scheduler events and + errors. Listeners can be associated with local schedulers through the + interface. + + + + jhouse + 2.0 - previously listeners were managed directly on the Scheduler interface. + + + + Add the given to the, + and register it to receive events for Jobs that are matched by ANY of the + given Matchers. + + + If no matchers are provided, the will be used. + + + + + + + Add the given to the, + and register it to receive events for Jobs that are matched by ANY of the + given Matchers. + + + If no matchers are provided, the will be used. + + + + + + + Add the given Matcher to the set of matchers for which the listener + will receive events if ANY of the matchers match. + + + + the name of the listener to add the matcher to + the additional matcher to apply for selecting events + true if the identified listener was found and updated + + + + Remove the given Matcher to the set of matchers for which the listener + will receive events if ANY of the matchers match. + + + + the name of the listener to add the matcher to + the additional matcher to apply for selecting events + true if the given matcher was found and removed from the listener's list of matchers + + + + Set the set of Matchers for which the listener + will receive events if ANY of the matchers match. + + + Removes any existing matchers for the identified listener! + + the name of the listener to add the matcher to + the matchers to apply for selecting events + true if the given matcher was found and removed from the listener's list of matchers + + + + Get the set of Matchers for which the listener + will receive events if ANY of the matchers match. + + + + the name of the listener to add the matcher to + the matchers registered for selecting events for the identified listener + + + + Remove the identified from the. + + + + true if the identified listener was found in the list, and removed. + + + + Get a List containing all of the s in + the. + + + + + Get the that has the given name. + + + + + Add the given to the, + and register it to receive events for Triggers that are matched by ANY of the + given Matchers. + + + If no matcher is provided, the will be used. + + + + + + + Add the given to the, + and register it to receive events for Triggers that are matched by ANY of the + given Matchers. + + + If no matcher is provided, the will be used. + + + + + + + Add the given Matcher to the set of matchers for which the listener + will receive events if ANY of the matchers match. + + + + the name of the listener to add the matcher to + the additional matcher to apply for selecting events + true if the identified listener was found and updated + + + + Remove the given Matcher to the set of matchers for which the listener + will receive events if ANY of the matchers match. + + + + the name of the listener to add the matcher to + the additional matcher to apply for selecting events + true if the given matcher was found and removed from the listener's list of matchers + + + + Set the set of Matchers for which the listener + will receive events if ANY of the matchers match. + + + Removes any existing matchers for the identified listener! + + the name of the listener to add the matcher to + the matchers to apply for selecting events + true if the given matcher was found and removed from the listener's list of matchers + + + + Get the set of Matchers for which the listener + will receive events if ANY of the matchers match. + + + + the name of the listener to add the matcher to + the matchers registered for selecting events for the identified listener + + + + Remove the identified from the. + + + + true if the identified listener was found in the list, and + removed. + + + + Get a List containing all of the s + in the. + + + + + Get the that has the given name. + + + + + Register the given with the + . + + + + + Remove the given from the + . + + + + true if the identified listener was found in the list, and removed. + + + + Get a List containing all of the s + registered with the. + + + + + This is the heart of Quartz, an indirect implementation of the + interface, containing methods to schedule s, + register instances, etc. + + + + + + James House + Marko Lahma (.NET) + + + + Remote scheduler service interface. + + Marko Lahma (.NET) + + + + Starts this instance. + + + + + Standbies this instance. + + + + + Shutdowns this instance. + + + + + returns true if the given JobGroup + is paused + + + + + + + returns true if the given TriggerGroup + is paused + + + + + + + Initializes the class. + + + + + Register the given with the + 's list of internal listeners. + + + + + + Remove the given from the + 's list of internal listeners. + + + true if the identified listener was found in the list, andremoved. + + + + Create a with the given configuration + properties. + + + + + + Bind the scheduler to remoting infrastructure. + + + + + Un-bind the scheduler from remoting infrastructure. + + + + + Adds an object that should be kept as reference to prevent + it from being garbage collected. + + The obj. + + + + Removes the object from garbae collection protected list. + + The obj. + + + + + Starts the 's threads that fire s. + + All s that have misfired will + be passed to the appropriate TriggerListener(s). + + + + + + Temporarily halts the 's firing of s. + + The scheduler is not destroyed, and can be re-started at any time. + + + + + + Halts the 's firing of s, + and cleans up all resources associated with the QuartzScheduler. + Equivalent to . + + The scheduler cannot be re-started. + + + + + + Halts the 's firing of s, + and cleans up all resources associated with the QuartzScheduler. + + The scheduler cannot be re-started. + + + + if the scheduler will not allow this method + to return until all currently executing jobs have completed. + + + + + Validates the state. + + + + + Add the identified by the given + to the Scheduler, and + associate the given with it. + + If the given Trigger does not reference any , then it + will be set to reference the Job passed with it into this method. + + + + + + Schedule the given with the + identified by the 's settings. + + + + + Add the given to the Scheduler - with no associated + . The will be 'dormant' until + it is scheduled with a , or + is called for it. + + The must by definition be 'durable', if it is not, + SchedulerException will be thrown. + + + + + + Delete the identified from the Scheduler - and any + associated s. + + true if the Job was found and deleted. + + + + Remove the indicated from the + scheduler. + + + + + Remove (delete) the with the + given name, and store the new given one - which must be associated + with the same job. + + the key of the trigger + The new to be stored. + + if a with the given + name and group was not found and removed from the store, otherwise + the first fire time of the newly scheduled trigger. + + + + + Creates a new positive random number + + The last random obtained + Returns a new positive random number + + + + Trigger the identified (Execute it now) - with a non-volatile trigger. + + + + + Store and schedule the identified + + + + + + Pause the with the given name. + + + + + Pause all of the s in the given group. + + + + + Pause the with the given + name - by pausing all of its current s. + + + + + Pause all of the s in the + given group - by pausing all of their s. + + + + + Resume (un-pause) the with the given + name. + + If the missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Resume (un-pause) all of the s in the + matching groups. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Gets the paused trigger groups. + + + + + + Resume (un-pause) the with + the given name. + + If any of the 's s missed one + or more fire-times, then the 's misfire + instruction will be applied. + + + + + + Resume (un-pause) all of the s + in the matching groups. + + If any of the s had s that + missed one or more fire-times, then the 's + misfire instruction will be applied. + + + + + + Pause all triggers - equivalent of calling + with a matcher matching all known groups. + + When is called (to un-pause), trigger misfire + instructions WILL be applied. + + + + + + + + Resume (un-pause) all triggers - equivalent of calling + on every group. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + + Get the names of all known groups. + + + + + Get the names of all the s in the + given group. + + + + + Get all s that are associated with the + identified . + + + + + Get the names of all known + groups. + + + + + Get the names of all the s in + the matching groups. + + + + + Get the for the + instance with the given name and group. + + + + + Get the instance with the given name and + group. + + + + + Determine whether a with the given identifier already + exists within the scheduler. + + + + the identifier to check for + true if a Job exists with the given identifier + + + + Determine whether a with the given identifier already + exists within the scheduler. + + + + the identifier to check for + true if a Trigger exists with the given identifier + + + + Clears (deletes!) all scheduling data - all s, s + s. + + + + + Get the current state of the identified . + + + + + + Add (register) the given to the Scheduler. + + + + + Delete the identified from the Scheduler. + + true if the Calendar was found and deleted. + + + + Get the instance with the given name. + + + + + Get the names of all registered s. + + + + + Add the given to the + 's internal list. + + + + + + Remove the identified from the 's + list of internal listeners. + + + true if the identified listener was found in the list, and removed. + + + + Get the internal + that has the given name. + + + + + + + Add the given to the + 's internal list. + + + + + + Remove the identified from the 's + list of internal listeners. + + + true if the identified listener was found in the list, and removed. + + + + Get the internal that + has the given name. + + + + + + + Notifies the job store job complete. + + The trigger. + The detail. + The instruction code. + + + + Notifies the scheduler thread. + + + + + Notifies the trigger listeners about fired trigger. + + The job execution context. + + + + + Notifies the trigger listeners about misfired trigger. + + The trigger. + + + + Notifies the trigger listeners of completion. + + The job executution context. + The instruction code to report to triggers. + + + + Notifies the job listeners about job to be executed. + + The jec. + + + + Notifies the job listeners that job exucution was vetoed. + + The job execution context. + + + + Notifies the job listeners that job was executed. + + The jec. + The je. + + + + Notifies the scheduler listeners about scheduler error. + + The MSG. + The se. + + + + Notifies the scheduler listeners about job that was scheduled. + + The trigger. + + + + Notifies the scheduler listeners about job that was unscheduled. + + + + + Notifies the scheduler listeners about finalized trigger. + + The trigger. + + + + Notifies the scheduler listeners about paused trigger. + + The group. + + + + Notifies the scheduler listeners about paused trigger. + + + + + Notifies the scheduler listeners resumed trigger. + + The group. + + + + Notifies the scheduler listeners resumed trigger. + + + + + Notifies the scheduler listeners about paused job. + + + + + Notifies the scheduler listeners about paused job. + + The group. + + + + Notifies the scheduler listeners about resumed job. + + + + + Notifies the scheduler listeners about resumed job. + + The group. + + + + Notifies the scheduler listeners about scheduler shutdown. + + + + + Interrupt all instances of the identified InterruptableJob. + + + + + Interrupt all instances of the identified InterruptableJob executing in this Scheduler instance. + + + This method is not cluster aware. That is, it will only interrupt + instances of the identified InterruptableJob currently executing in this + Scheduler instance, not across the entire cluster. + + + + + + + + Obtains a lifetime service object to control the lifetime policy for this instance. + + + + + Gets the version of the Quartz Scheduler. + + The version. + + + + Gets the version major. + + The version major. + + + + Gets the version minor. + + The version minor. + + + + Gets the version iteration. + + The version iteration. + + + + Gets the scheduler signaler. + + The scheduler signaler. + + + + Returns the name of the . + + + + + Returns the instance Id of the . + + + + + Returns the of the . + + + + + Gets or sets a value indicating whether to signal on scheduling change. + + + true if schduler should signal on scheduling change; otherwise, false. + + + + + Reports whether the is paused. + + + + + Gets the job store class. + + The job store class. + + + + Gets the thread pool class. + + The thread pool class. + + + + Gets the size of the thread pool. + + The size of the thread pool. + + + + Reports whether the has been Shutdown. + + + + + Return a list of objects that + represent all currently executing Jobs in this Scheduler instance. + + This method is not cluster aware. That is, it will only return Jobs + currently executing in this Scheduler instance, not across the entire + cluster. + + + Note that the list returned is an 'instantaneous' snap-shot, and that as + soon as it's returned, the true list of executing jobs may be different. + + + + + + Get a List containing all of the internal s + registered with the . + + + + + Gets or sets the job factory. + + The job factory. + + + + Gets the running since. + + The running since. + + + + Gets the number of jobs executed. + + The number of jobs executed. + + + + Gets a value indicating whether this scheduler supports persistence. + + true if supports persistence; otherwise, false. + + + + Get a List containing all of the s + in the 's internal list. + + + + + + Get a list containing all of the s + in the 's internal list. + + + + + Helper class to start scheduler in a delayed fashion. + + + + + ErrorLogger - Scheduler Listener Class + + + + + The interface to be implemented by classes that want to be informed when a + executes. In general, applications that use a + will not have use for this mechanism. + + + + + + + + James House + Marko Lahma (.NET) + + + + Called by the when a + is about to be executed (an associated + has occurred). + + This method will not be invoked if the execution of the Job was vetoed + by a . + + + + + + + Called by the when a + was about to be executed (an associated + has occurred), but a vetoed it's + execution. + + + + + + Called by the after a + has been executed, and be for the associated 's + method has been called. + + + + + Get the name of the . + + + + + Contains all of the resources (,, + etc.) necessary to create a instance. + + + James House + Marko Lahma (.NET) + + + + Gets the unique identifier. + + Name of the scheduler. + The scheduler instance id. + + + + + Gets the unique identifier. + + + + + + Add the given for the + to use. This method expects the plugin's + "initialize" method to be invoked externally (either before or after + this method is called). + + + + + + Get or set the name for the . + + + if name is null or empty. + + + + + Get or set the instance Id for the . + + + if name is null or empty. + + + + + Get or set the name for the . + + + if name is null or empty. + + + + + Get or set the for the + to use. + + + if threadPool is null. + + + + + Get or set the for the + to use. + + + if jobStore is null. + + + + + Get or set the for the + to use. + + + if jobRunShellFactory is null. + + + + + Get the of all s for the + to use. + + + + + + Gets or sets a value indicating whether to make scheduler thread daemon. + + + true if scheduler should be thread daemon; otherwise, false. + + + + + Gets or sets the scheduler exporter. + + The scheduler exporter. + + + + The ThreadExecutor which runs the QuartzSchedulerThread. + + + + + Gets or sets the batch time window. + + + + + The thread responsible for performing the work of firing + s that are registered with the . + + + + + James House + Marko Lahma (.NET) + + + + Support class used to handle threads + + Marko Lahma (.NET) + + + + The instance of System.Threading.Thread + + + + + Initializes a new instance of the QuartzThread class + + + + + Initializes a new instance of the Thread class. + + The name of the thread + + + + This method has no functionality unless the method is overridden + + + + + Causes the operating system to change the state of the current thread instance to ThreadState.Running + + + + + Interrupts a thread that is in the WaitSleepJoin thread state + + + + + Blocks the calling thread until a thread terminates + + + + + Obtain a string that represents the current object + + A string that represents the current object + + + + Gets or sets the name of the thread + + + + + Gets or sets a value indicating the scheduling priority of a thread + + + + + Gets or sets a value indicating whether or not a thread is a background thread. + + + + + Gets the randomized idle wait time. + + The randomized idle wait time. + + + + Construct a new for the given + as a non-daemon + with normal priority. + + + + + Construct a new for the given + as a with the given + attributes. + + + + + Signals the main processing loop to pause at the next possible point. + + + + + Signals the main processing loop to pause at the next possible point. + + + + + Signals the main processing loop that a change in scheduling has been + made - in order to interrupt any sleeping that may be occuring while + waiting for the fire time to arrive. + + + the time when the newly scheduled trigger + will fire. If this method is being called do to some other even (rather + than scheduling a trigger), the caller should pass null. + + + + + The main processing loop of the . + + + + + Trigger retry loop that is executed on error condition. + + The bndle. + + + + Releases the trigger retry loop. + + The trigger. + + + + Gets the log. + + The log. + + + + Sets the idle wait time. + + The idle wait time. + + + + Gets a value indicating whether this is paused. + + true if paused; otherwise, false. + + + + Gets or sets the db failure retry interval. + + The db failure retry interval. + + + + An interface to be used by instances in order to + communicate signals back to the . + + James House + Marko Lahma (.NET) + + + + An interface to be used by instances in order to + communicate signals back to the . + + James House + Marko Lahma (.NET) + + + + Notifies the scheduler about misfired trigger. + + The trigger that misfired. + + + + Notifies the scheduler about finalized trigger. + + The trigger that has finalized. + + + + Signals the scheduling change. + + + + + Notifies the scheduler about misfired trigger. + + The trigger that misfired. + + + + Notifies the scheduler about finalized trigger. + + The trigger that has finalized. + + + + Signals the scheduling change. + + + + + Metadata information about specific ADO.NET driver library. Metadata is used to + create correct types of object instances to interact with the underlying + database. + + Marko Lahma + + + + Initializes this instance. Parses information and initializes startup + values. + + + + + Gets the name of the parameter which includes the parameter prefix for this + database. + + Name of the parameter. + + + Gets or sets the name of the assembly that holds the connection library. + The name of the assembly. + + + + Gets or sets the name of the product. + + The name of the product. + + + + Gets or sets the type of the connection. + + The type of the connection. + + + + Gets or sets the type of the command. + + The type of the command. + + + + Gets or sets the type of the parameter. + + The type of the parameter. + + + + Gets the type of the command builder. + + The type of the command builder. + + + Gets the command builder's derive parameters method. + The command builder derive parameters method. + + + + Gets or sets the parameter name prefix. + + The parameter name prefix. + + + + Gets or sets the type of the exception that is thrown when using driver + library. + + The type of the exception. + + + + Gets or sets a value indicating whether parameters are bind by name when using + ADO.NET parameters. + + true if parameters are bind by name; otherwise, false. + + + Gets or sets the type of the database parameters. + The type of the parameter db. + + + + Gets the parameter db type property. + + The parameter db type property. + + + + Gets the parameter is nullable property. + + The parameter is nullable property. + + + + Gets or sets the type of the db binary column. This is a string representation of + Enum element because this information is database driver specific. + + The type of the db binary. + + + Gets the type of the db binary. + The type of the db binary. + + + + Sets the name of the parameter db type property. + + The name of the parameter db type property. + + + + Gets or sets a value indicating whether [use parameter name prefix in parameter collection]. + + + true if [use parameter name prefix in parameter collection]; otherwise, false. + + + + + Concrete implementation of . + + Marko Lahma + + + + Data access provider interface. + + Marko Lahma + + + + Returns a new command object for executing SQL statments/Stored Procedures + against the database. + + An new + + + + Returns a new instance of the providers CommandBuilder class. + + In .NET 1.1 there was no common base class or interface + for command builders, hence the return signature is object to + be portable (but more loosely typed) across .NET 1.1/2.0 + A new Command Builder + + + + Returns a new connection object to communicate with the database. + + A new + + + + Returns a new parameter object for binding values to parameter + placeholders in SQL statements or Stored Procedure variables. + + A new + + + + Shutdowns this instance. + + + + + Connection string used to create connections. + + + + + Registers DB metadata information for given provider name. + + + + + + + Initializes a new instance of the class. + + Name of the db provider. + The connection string. + + + + Returns a new command object for executing SQL statments/Stored Procedures + against the database. + + An new + + + + Returns a new instance of the providers CommandBuilder class. + + A new Command Builder + In .NET 1.1 there was no common base class or interface + for command builders, hence the return signature is object to + be portable (but more loosely typed) across .NET 1.1/2.0 + + + + Returns a new connection object to communicate with the database. + + A new + + + + Returns a new parameter object for binding values to parameter + placeholders in SQL statements or Stored Procedure variables. + + A new + + + + Shutdowns this instance. + + + + + Connection string used to create connections. + + + + + + Gets the metadata. + + The metadata. + + + + This interface can be implemented by any + class that needs to use the constants contained herein. + + Jeffrey Wescott + James House + Marko Lahma(.NET) + + + + Simple Trigger type. + + + + + Cron Trigger type. + + + + + Calendar Interval Trigger type. + + + + + Daily Time Interval Trigger type. + + + + + A general blob Trigger type. + + + + + This class contains utility functions for use in all delegate classes. + + Jeffrey Wescott + Marko Lahma (.NET) + + + + Replace the table prefix in a query by replacing any occurrences of + "{0}" with the table prefix. + + The unsubstitued query + The table prefix + the scheduler name + The query, with proper table prefix substituted + + + + Common helper methods for working with ADO.NET. + + Marko Lahma + + + + Persist a CalendarIntervalTriggerImpl by converting internal fields to and from + SimplePropertiesTriggerProperties. + + + + + + + A base implementation of that persists + trigger fields in the "QRTZ_SIMPROP_TRIGGERS" table. This allows extending + concrete classes to simply implement a couple methods that do the work of + getting/setting the trigger's fields, and creating the + for the particular type of trigger. + + + jhouse + Marko Lahma (.NET) + + + + An interface which provides an implementation for storing a particular + type of 's extended properties. + + jhouse + + + + Initializes the persistence delegate. + + + + + Returns whether the trigger type can be handled by delegate. + + + + + Returns database discriminator value for trigger type. + + + + + Inserts trigger's special properties. + + + + + Updates trigger's special properties. + + + + + Deletes trigger's special properties. + + + + + Loads trigger's special properties. + + + + + Returns whether the trigger type can be handled by delegate. + + + + + Returns database discriminator value for trigger type. + + + + + Utility class to keep track of both active transaction + and connection. + + Marko Lahma + + + + Initializes a new instance of the class. + + The connection. + The transaction. + + + + Gets or sets the connection. + + The connection. + + + + Gets or sets the transaction. + + The transaction. + + + + Persist a CronTriggerImpl. + + + + + + + Persist a DailyTimeIntervalTrigger by converting internal fields to and from + SimplePropertiesTriggerProperties. + + + + Zemian Deng saltnlight5@gmail.com + Nuno Maia (.NET) + + + + + + + + + + Base class for database based lock handlers for providing thread/resource locking + in order to protect resources from being altered by multiple threads at the + same time. + + Marko Lahma (.NET) + + + + This class extends + to include the query string constants in use by the + class. + + Jeffrey Wescott + Marko Lahma (.NET) + + + + An interface for providing thread/resource locking in order to protect + resources from being altered by multiple threads at the same time. + + James House + Marko Lahma (.NET) + + + + Grants a lock on the identified resource to the calling thread (blocking + until it is available). + + true if the lock was obtained. + + + + Release the lock on the identified resource if it is held by the calling + thread. + + + + + Determine whether the calling thread owns a lock on the identified + resource. + + + + + Whether this Semaphore implementation requires a database connection for + its lock management operations. + + + + + + + + Interface for Quartz objects that need to know what the table prefix of + the tables used by a ADO.NET JobStore is. + + Marko Lahma (.NET) + + + + Table prefix to use. + + + + + Initializes a new instance of the class. + + The table prefix. + the scheduler name + The SQL. + The default SQL. + The db provider. + + + + Execute the SQL that will lock the proper database row. + + + + + + + + + Grants a lock on the identified resource to the calling thread (blocking + until it is available). + + + + + true if the lock was obtained. + + + + Release the lock on the identified resource if it is held by the calling + thread. + + + + + + + Determine whether the calling thread owns a lock on the identified + resource. + + + + + + + + Gets or sets the lock owners. + + The lock owners. + + + + Gets the log. + + The log. + + + + This Semaphore implementation does use the database. + + + + + Gets or sets the table prefix. + + The table prefix. + + + + Initialization argumens holder for implementations. + + + + + Whether simple should be used (for serialization safety). + + + + + The logger to use during execution. + + + + + The prefix of all table names. + + + + + The instance's name. + + + + + The instance id. + + + + + The db provider. + + + + + The type loading strategy. + + + + + Object serializer and deserializer strategy to use. + + + + + Custom driver delegate initialization. + + + initStrings are of the format: + settingName=settingValue|otherSettingName=otherSettingValue|... + + + + + Conveys the state of a fired-trigger record. + + James House + Marko Lahma (.NET) + + + + Gets or sets the fire instance id. + + The fire instance id. + + + + Gets or sets the fire timestamp. + + The fire timestamp. + + + + Gets or sets a value indicating whether job disallows concurrent execution. + + + + + Gets or sets the job key. + + The job key. + + + + Gets or sets the scheduler instance id. + + The scheduler instance id. + + + + Gets or sets the trigger key. + + The trigger key. + + + + Gets or sets the state of the fire instance. + + The state of the fire instance. + + + + Gets or sets a value indicating whether [job requests recovery]. + + true if [job requests recovery]; otherwise, false. + + + + Gets or sets the priority. + + The priority. + + + + Service interface or modifying parameters + and resultset values. + + + + + Prepares a to be used to access database. + + Connection and tranasction pair + SQL to run + + + + + Adds a parameter to . + + Command to add parameter to + Parameter's name + Parameter's value + + + + Adds a parameter to . + + Command to add parameter to + Parameter's name + Parameter's value + Parameter's data type + + + + Gets the db presentation for boolean value. Subclasses can overwrite this behaviour. + + Value to map to database. + + + + + Gets the boolean value from db presentation. Subclasses can overwrite this behaviour. + + Value to map from database. + + + + + Gets the db presentation for date/time value. Subclasses can overwrite this behaviour. + + Value to map to database. + + + + + Gets the date/time value from db presentation. Subclasses can overwrite this behaviour. + + Value to map from database. + + + + + Gets the db presentation for time span value. Subclasses can overwrite this behaviour. + + Value to map to database. + + + + + Gets the time span value from db presentation. Subclasses can overwrite this behaviour. + + Value to map from database. + + + + + This is the base interface for all driver delegate classes. + + + + This interface is very similar to the + interface except each method has an additional + parameter. + + + Unless a database driver has some extremely-DB-specific + requirements, any IDriverDelegate implementation classes should extend the + class. + + + Jeffrey Wescott + James House + Marko Lahma (.NET) + + + + Initializes the driver delegate with configuration data. + + + + + + Update all triggers having one of the two given states, to the given new + state. + + The DB Connection + The new state for the triggers + The first old state to update + The second old state to update + Number of rows updated + + + + Get the names of all of the triggers that have misfired - according to + the given timestamp. + + The DB Connection + The timestamp. + An array of objects + + + + Get the names of all of the triggers in the given state that have + misfired - according to the given timestamp. + + The DB Connection + The state. + The time stamp. + An array of objects + + + + Get the names of all of the triggers in the given group and state that + have misfired - according to the given timestamp. + + The DB Connection + Name of the group. + The state. + The timestamp. + An array of objects + + + + Select all of the triggers for jobs that are requesting recovery. The + returned trigger objects will have unique "recoverXXX" trigger names and + will be in the trigger group. + + + In order to preserve the ordering of the triggers, the fire time will be + set from the ColumnFiredTime column in the TableFiredTriggers + table. The caller is responsible for calling + on each returned trigger. It is also up to the caller to insert the + returned triggers to ensure that they are fired. + + The DB Connection + An array of objects + + + + Delete all fired triggers. + + The DB Connection + The number of rows deleted + + + + Delete all fired triggers of the given instance. + + The DB Connection + The instance id. + The number of rows deleted + + + + Insert the job detail record. + + The DB Connection + The job to insert. + Number of rows inserted. + + + + Update the job detail record. + + The DB Connection. + The job to update. + Number of rows updated. + + + + Get the names of all of the triggers associated with the given job. + + + + The DB Connection + The key identifying the job. + + + + Delete the job detail record for the given job. + + The DB Connection + The key identifying the job. + the number of rows deleted + + + + Check whether or not the given job is stateful. + + The DB Connection + The key identifying the job. + true if the job exists and is stateful, false otherwise + + + + Check whether or not the given job exists. + + The DB Connection + The key identifying the job. + true if the job exists, false otherwise + + + + Update the job data map for the given job. + + The DB Connection + The job. + the number of rows updated + + + + Select the JobDetail object for a given job name / group name. + + The DB Connection + The key identifying the job. + The class load helper. + The populated JobDetail object + + + + Select the total number of jobs stored. + + The DB Connection + the total number of jobs stored + + + + Select all of the job group names that are stored. + + The DB Connection. + an array of group names + + + + Select all of the jobs contained in a given group. + + The DB Connection + + an array of job names + + + + Insert the base trigger data. + + The DB Connection + The trigger to insert. + The state that the trigger should be stored in. + The job detail. + The number of rows inserted + + + + Insert the blob trigger data. + + The DB Connection + The trigger to insert + The number of rows inserted + + + + Update the base trigger data. + + the DB Connection + The trigger. + The state. + The job detail. + the number of rows updated + + + + Update the blob trigger data. + + the DB Connection + The trigger. + the number of rows updated + + + + Check whether or not a trigger exists. + + the DB Connection + The key identifying the trigger. + the number of rows updated + + + + Update the state for a given trigger. + + The DB Connection + The key identifying the trigger. + The new state for the trigger. + the number of rows updated + + + + Update the given trigger to the given new state, if it is in the given + old state. + + The DB connection + The key identifying the trigger. + The new state for the trigger + The old state the trigger must be in + int the number of rows updated + + + + Update the given trigger to the given new state, if it is one of the + given old states. + + The DB connection + The key identifying the trigger. + The new state for the trigger + One of the old state the trigger must be in + One of the old state the trigger must be in + One of the old state the trigger must be in + + int the number of rows updated + + SQLException + + + + Update all triggers in the given group to the given new state, if they + are in one of the given old states. + + The DB connection + + The new state for the trigger + One of the old state the trigger must be in + One of the old state the trigger must be in + One of the old state the trigger must be in + The number of rows updated + + + + Update all of the triggers of the given group to the given new state, if + they are in the given old state. + + The DB connection + + The new state for the trigger group + The old state the triggers must be in. + int the number of rows updated + + + + Update the states of all triggers associated with the given job. + + The DB Connection + The key identifying the job. + The new state for the triggers. + The number of rows updated + + + + Update the states of any triggers associated with the given job, that + are the given current state. + + The DB Connection + The key identifying the job. + The new state for the triggers + The old state of the triggers + the number of rows updated + + + + Delete the BLOB trigger data for a trigger. + + The DB Connection + The key identifying the trigger. + The number of rows deleted + + + + Delete the base trigger data for a trigger. + + The DB Connection + The key identifying the trigger. + the number of rows deleted + + + + Select the number of triggers associated with a given job. + + The DB Connection + The key identifying the job. + the number of triggers for the given job + + + + Select the job to which the trigger is associated. + + The DB Connection + The key identifying the trigger. + The load helper. + + The object associated with the given trigger + + + + + Select the triggers for a job> + + The DB Connection + The key identifying the job. + an array of objects associated with a given job. + + + + Select the triggers for a calendar + + The DB Connection. + Name of the calendar. + + An array of objects associated with a given job. + + + + + Select a trigger. + + The DB Connection. + The key identifying the trigger. + The object. + + + + + Select a trigger's JobDataMap. + + The DB Connection. + The key identifying the trigger. + The of the Trigger, never null, but possibly empty. + + + + Select a trigger's state value. + + The DB Connection. + The key identifying the trigger. + The object. + + + + Select a triggers status (state and next fire time). + + The DB Connection. + The key identifying the trigger. + A object, or null + + + + Select the total number of triggers stored. + + The DB Connection. + The total number of triggers stored. + + + + Select all of the trigger group names that are stored. + + The DB Connection. + An array of group names. + + + + Select all of the triggers contained in a given group. + + The DB Connection. + + An array of trigger names. + + + + Select all of the triggers in a given state. + + The DB Connection. + The state the triggers must be in. + An array of trigger s. + + + + Inserts the paused trigger group. + + The conn. + Name of the group. + + + + + Deletes the paused trigger group. + + The conn. + Name of the group. + + + + + Deletes all paused trigger groups. + + The conn. + + + + + Determines whether the specified trigger group is paused. + + The conn. + Name of the group. + + true if trigger group is paused; otherwise, false. + + + + + Selects the paused trigger groups. + + The DB Connection. + + + + + Determines whether given trigger group already exists. + + The conn. + Name of the group. + + true if trigger group exists; otherwise, false. + + + + + Insert a new calendar. + + The DB Connection. + The name for the new calendar. + The calendar. + The number of rows inserted. + + + + Update a calendar. + + The DB Connection. + The name for the new calendar. + The calendar. + The number of rows updated. + + + + Check whether or not a calendar exists. + + The DB Connection. + The name of the calendar. + true if the trigger exists, false otherwise. + + + + Select a calendar. + + The DB Connection. + The name of the calendar. + The Calendar. + + + + Check whether or not a calendar is referenced by any triggers. + + The DB Connection. + The name of the calendar. + true if any triggers reference the calendar, false otherwise + + + + Delete a calendar. + + The DB Connection + The name of the trigger. + The number of rows deleted. + + + + Select the total number of calendars stored. + + The DB Connection + The total number of calendars stored. + + + + Select all of the stored calendars. + + The DB Connection + An array of calendar names. + + + + Select the trigger that will be fired at the given fire time. + + The DB Connection + The time that the trigger will be fired. + + A representing the + trigger that will be fired at the given fire time, or null if no + trigger will be fired at that time + + + + + Insert a fired trigger. + + The DB Connection + The trigger. + The state that the trigger should be stored in. + The job detail. + The number of rows inserted. + + + + Select the states of all fired-trigger records for a given trigger, or + trigger group if trigger name is . + + The DB Connection + Name of the trigger. + Name of the group. + A list of FiredTriggerRecord objects. + + + + Select the states of all fired-trigger records for a given job, or job + group if job name is . + + The DB Connection + Name of the job. + Name of the group. + A List of FiredTriggerRecord objects. + + + + Select the states of all fired-trigger records for a given scheduler + instance. + + The DB Connection + Name of the instance. + A list of FiredTriggerRecord objects. + + + + Delete a fired trigger. + + The DB Connection + The fired trigger entry to delete. + The number of rows deleted. + + + + Get the number instances of the identified job currently executing. + + The DB Connection + The key identifying the job. + + The number instances of the identified job currently executing. + + + + + Insert a scheduler-instance state record. + + The DB Connection + The instance id. + The check in time. + The interval. + The number of inserted rows. + + + + Delete a scheduler-instance state record. + + The DB Connection + The instance id. + The number of deleted rows. + + + + Update a scheduler-instance state record. + + The DB Connection + The instance id. + The check in time. + The number of updated rows. + + + + A List of all current s. + + If instanceId is not null, then only the record for the identified + instance will be returned. + + + The DB Connection + The instance id. + + + + + Select the next trigger which will fire to fire between the two given timestamps + in ascending order of fire time, and then descending by priority. + + The conn. + highest value of of the triggers (exclusive) + highest value of of the triggers (inclusive) + maximum number of trigger keys allow to acquired in the returning list. + A (never null, possibly empty) list of the identifiers (Key objects) of the next triggers to be fired. + + + + Select the distinct instance names of all fired-trigger records. + + + This is useful when trying to identify orphaned fired triggers (a + fired trigger without a scheduler state record.) + + The conn. + + + + + Counts the misfired triggers in states. + + The conn. + The state1. + The ts. + + + + + Selects the misfired triggers in states. + + The conn. + The state1. + The ts. + The count. + The result list. + + + + + Clear (delete!) all scheduling data - all s, s + s. + + + + + + Exception class for when a driver delegate cannot be found for a given + configuration, or lack thereof. + + Jeffrey Wescott + Marko Lahma (.NET) + + + + Base class for exceptions thrown by the Quartz . + + + SchedulerExceptions may contain a reference to another + , which was the underlying cause of the SchedulerException. + + James House + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The MSG. + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + Initializes a new instance of the class. + + The cause. + + + + Initializes a new instance of the class. + + The MSG. + The cause. + + + + Creates and returns a string representation of the current exception. + + + A string representation of the current exception. + + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + is meant to be used in an application-server + or other software framework environment that provides + container-managed-transactions. No commit / rollback will be handled by this class. + + + If you need commit / rollback, use + instead. + + Jeffrey Wescott + James House + Srinivas Venkatarangaiah + Marko Lahma (.NET) + + + + Contains base functionality for ADO.NET-based JobStore implementations. + + Jeffrey Wescott + James House + Marko Lahma (.NET) + + + + The interface to be implemented by classes that want to provide a + and storage mechanism for the + 's use. + + + Storage of s and s should be keyed + on the combination of their name and group for uniqueness. + + + + + + + + James House + Marko Lahma (.NET) + + + + Called by the QuartzScheduler before the is + used, in order to give the it a chance to Initialize. + + + + + Called by the QuartzScheduler to inform the that + the scheduler has started. + + + + + Called by the QuartzScheduler to inform the JobStore that + the scheduler has been paused. + + + + + Called by the QuartzScheduler to inform the JobStore that + the scheduler has resumed after being paused. + + + + + Called by the QuartzScheduler to inform the that + it should free up all of it's resources because the scheduler is + shutting down. + + + + + Store the given and . + + The to be stored. + The to be stored. + ObjectAlreadyExistsException + + + + returns true if the given JobGroup is paused + + + + + + + returns true if the given TriggerGroup + is paused + + + + + + + Store the given . + + The to be stored. + + If , any existing in the + with the same name and group should be + over-written. + + + + + Remove (delete) the with the given + key, and any s that reference + it. + + + If removal of the results in an empty group, the + group should be removed from the 's list of + known group names. + + + if a with the given name and + group was found and removed from the store. + + + + + Retrieve the for the given + . + + + The desired , or null if there is no match. + + + + + Store the given . + + The to be stored. + If , any existing in + the with the same name and group should + be over-written. + ObjectAlreadyExistsException + + + + Remove (delete) the with the given key. + + + + If removal of the results in an empty group, the + group should be removed from the 's list of + known group names. + + + If removal of the results in an 'orphaned' + that is not 'durable', then the should be deleted + also. + + + + if a with the given + name and group was found and removed from the store. + + + + + Remove (delete) the with the + given name, and store the new given one - which must be associated + with the same job. + + The to be replaced. + The new to be stored. + + if a with the given + name and group was found and removed from the store. + + + + + Retrieve the given . + + + The desired , or null if there is no + match. + + + + + Determine whether a with the given identifier already + exists within the scheduler. + + + + the identifier to check for + true if a job exists with the given identifier + + + + Determine whether a with the given identifier already + exists within the scheduler. + + + + the identifier to check for + true if a trigger exists with the given identifier + + + + Clear (delete!) all scheduling data - all s, s + s. + + + + + + + Store the given . + + The name. + The to be stored. + If , any existing + in the with the same name and group + should be over-written. + If , any s existing + in the that reference an existing + Calendar with the same name with have their next fire time + re-computed with the new . + ObjectAlreadyExistsException + + + + Remove (delete) the with the + given name. + + + If removal of the would result in + s pointing to non-existent calendars, then a + will be thrown. + + The name of the to be removed. + + if a with the given name + was found and removed from the store. + + + + + Retrieve the given . + + The name of the to be retrieved. + + The desired , or null if there is no + match. + + + + + Get the number of s that are + stored in the . + + + + + + Get the number of s that are + stored in the . + + + + + + Get the number of s that are + stored in the . + + + + + + Get the names of all of the s that + have the given group name. + + If there are no jobs in the given group name, the result should be a + zero-length array (not ). + + + + + + + + Get the names of all of the s + that have the given group name. + + If there are no triggers in the given group name, the result should be a + zero-length array (not ). + + + + + + Get the names of all of the + groups. + + If there are no known group names, the result should be a zero-length + array (not ). + + + + + + Get the names of all of the + groups. + + If there are no known group names, the result should be a zero-length + array (not ). + + + + + + Get the names of all of the s + in the . + + + If there are no Calendars in the given group name, the result should be + a zero-length array (not ). + + + + + + Get all of the Triggers that are associated to the given Job. + + + If there are no matches, a zero-length array should be returned. + + + + + Get the current state of the identified . + + + + + + Pause the with the given key. + + + + + Pause all of the s in the + given group. + + + The JobStore should "remember" that the group is paused, and impose the + pause on any new triggers that are added to the group while the group is + paused. + + + + + Pause the with the given key - by + pausing all of its current s. + + + + + Pause all of the s in the given + group - by pausing all of their s. + + The JobStore should "remember" that the group is paused, and impose the + pause on any new jobs that are added to the group while the group is + paused. + + + + + + + + Resume (un-pause) the with the + given key. + + + If the missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + + + Resume (un-pause) all of the s + in the given group. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Gets the paused trigger groups. + + + + + + Resume (un-pause) the with the + given key. + + If any of the 's s missed one + or more fire-times, then the 's misfire + instruction will be applied. + + + + + + Resume (un-pause) all of the s in + the given group. + + If any of the s had s that + missed one or more fire-times, then the 's + misfire instruction will be applied. + + + + + + Pause all triggers - equivalent of calling + on every group. + + When is called (to un-pause), trigger misfire + instructions WILL be applied. + + + + + + + Resume (un-pause) all triggers - equivalent of calling + on every group. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + + + Get a handle to the next trigger to be fired, and mark it as 'reserved' + by the calling scheduler. + + If > 0, the JobStore should only return a Trigger + that will fire no later than the time represented in this value as + milliseconds. + + + + + + + + + Inform the that the scheduler no longer plans to + fire the given , that it had previously acquired + (reserved). + + + + + Inform the that the scheduler is now firing the + given (executing its associated ), + that it had previously acquired (reserved). + + + May return null if all the triggers or their calendars no longer exist, or + if the trigger was not successfully put into the 'executing' + state. Preference is to return an empty list if none of the triggers + could be fired. + + + + + Inform the that the scheduler has completed the + firing of the given (and the execution its + associated ), and that the + in the given should be updated if the + is stateful. + + + + + Indicates whether job store supports persistence. + + + + + + How long (in milliseconds) the implementation + estimates that it will take to release a trigger and acquire a new one. + + + + + Whether or not the implementation is clustered. + + + + + + Inform the of the Scheduler instance's Id, + prior to initialize being invoked. + + + + + Inform the of the Scheduler instance's name, + prior to initialize being invoked. + + + + + Tells the JobStore the pool size used to execute jobs. + + + + + Initializes a new instance of the class. + + + + + Gets the connection and starts a new transaction. + + + + + + Called by the QuartzScheduler before the is + used, in order to give it a chance to Initialize. + + + + + + + + Called by the QuartzScheduler to inform the JobStore that + the scheduler has been paused. + + + + + Called by the QuartzScheduler to inform the JobStore that + the scheduler has resumed after being paused. + + + + + Called by the QuartzScheduler to inform the that + it should free up all of it's resources because the scheduler is + shutting down. + + + + + Will recover any failed or misfired jobs and clean up the data store as + appropriate. + + + + + Will recover any failed or misfired jobs and clean up the data store as + appropriate. + + + + + Store the given and . + + Job to be stored. + Trigger to be stored. + + + + returns true if the given JobGroup + is paused + + + + + + + returns true if the given TriggerGroup + is paused + + + + + + + Stores the given . + + The to be stored. + + If , any existing in the + with the same name & group should be over-written. + + + + + Insert or update a job. + + + + + + Check existence of a given job. + + + + + Store the given . + + The to be stored. + + If , any existing in + the with the same name & group should + be over-written. + + + if a with the same name/group already + exists, and replaceExisting is set to false. + + + + + Insert or update a trigger. + + + + + Check existence of a given trigger. + + + + + Remove (delete) the with the given + name, and any s that reference + it. + + + + If removal of the results in an empty group, the + group should be removed from the 's list of + known group names. + + + if a with the given name & + group was found and removed from the store. + + + + + Delete a job and its listeners. + + + + + + + Delete a trigger, its listeners, and its Simple/Cron/BLOB sub-table entry. + + + + + + + + Retrieve the for the given + . + + The key identifying the job. + The desired , or null if there is no match. + + + + Remove (delete) the with the + given name. + + + + + If removal of the results in an empty group, the + group should be removed from the 's list of + known group names. + + + + If removal of the results in an 'orphaned' + that is not 'durable', then the should be deleted + also. + + + The key identifying the trigger. + + if a with the given + name & group was found and removed from the store. + + + + + + + + Retrieve the given . + + The key identifying the trigger. + The desired , or null if there is no match. + + + + Get the current state of the identified . + + + + + + + + + + Gets the state of the trigger. + + The conn. + The key identifying the trigger. + + + + + Store the given . + + The name of the calendar. + The to be stored. + + If , any existing + in the with the same name & group + should be over-written. + + + + if a with the same name already + exists, and replaceExisting is set to false. + + + + + Remove (delete) the with the given name. + + + If removal of the would result in + s pointing to non-existent calendars, then a + will be thrown. + + The name of the to be removed. + + if a with the given name + was found and removed from the store. + + + + + Retrieve the given . + + The name of the to be retrieved. + The desired , or null if there is no match. + + + + Get the number of s that are + stored in the . + + + + + Get the number of s that are + stored in the . + + + + + Get the number of s that are + stored in the . + + + + + Get the names of all of the s that + have the given group name. + + + If there are no jobs in the given group name, the result should be a + zero-length array (not ). + + + + + Determine whether a with the given identifier already + exists within the scheduler. + + + + the identifier to check for + true if a Job exists with the given identifier + + + + Determine whether a with the given identifier already + exists within the scheduler. + + + + the identifier to check for + true if a Trigger exists with the given identifier + + + + Clear (delete!) all scheduling data - all s, s + s. + + + + + + + Get the names of all of the s + that have the given group name. + + + If there are no triggers in the given group name, the result should be a + zero-length array (not ). + + + + + Get the names of all of the + groups. + + + + If there are no known group names, the result should be a zero-length + array (not ). + + + + + Get the names of all of the + groups. + + + + If there are no known group names, the result should be a zero-length + array (not ). + + + + + Get the names of all of the s + in the . + + + If there are no Calendars in the given group name, the result should be + a zero-length array (not ). + + + + + Get all of the Triggers that are associated to the given Job. + + + If there are no matches, a zero-length array should be returned. + + + + + Pause the with the given name. + + + + + Pause the with the given name. + + + + + Pause the with the given name - by + pausing all of its current s. + + + + + + Pause all of the s in the given + group - by pausing all of their s. + + + + + + Determines if a Trigger for the given job should be blocked. + State can only transition to StatePausedBlocked/StateBlocked from + StatePaused/StateWaiting respectively. + + StatePausedBlocked, StateBlocked, or the currentState. + + + + Resume (un-pause) the with the + given name. + + + If the missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + Resume (un-pause) the with the + given name. + + + If any of the 's s missed one + or more fire-times, then the 's misfire + instruction will be applied. + + + + + + Resume (un-pause) all of the s in + the given group. + + + If any of the s had s that + missed one or more fire-times, then the 's + misfire instruction will be applied. + + + + + + Pause all of the s in the given group. + + + + + + Pause all of the s in the given group. + + + + + Pause all of the s in the + given group. + + + + + Resume (un-pause) all of the s + in the given group. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Pause all triggers - equivalent of calling + on every group. + + When is called (to un-pause), trigger misfire + instructions WILL be applied. + + + + + + + + Resume (un-pause) all triggers - equivalent of calling + on every group. + + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Resume (un-pause) all triggers - equivalent of calling + on every group. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + + Get a handle to the next N triggers to be fired, and mark them as 'reserved' + by the calling scheduler. + + + + + + Inform the that the scheduler no longer plans to + fire the given , that it had previously acquired + (reserved). + + + + + Inform the that the scheduler has completed the + firing of the given (and the execution its + associated ), and that the + in the given should be updated if the + is stateful. + + + + + Get a list of all scheduler instances in the cluster that may have failed. + This includes this scheduler if it is checking in for the first time. + + + + + Create dummy objects for fired triggers + that have no scheduler state record. Checkin timestamp and interval are + left as zero on these dummy objects. + + + List of all current s + + + + Cleanup the given database connection. This means restoring + any modified auto commit or transaction isolation connection + attributes, and then closing the underlying connection. + + + + This is separate from closeConnection() because the Spring + integration relies on being able to overload closeConnection() and + expects the same connection back that it originally returned + from the datasource. + + + + + + Closes the supplied connection. + + (Optional) + + + + Rollback the supplied connection. + + (Optional) + + JobPersistenceException thrown if a SQLException occurs when the + connection is rolled back + + + + + Commit the supplied connection. + + The CTH. + if set to true opens a new transaction. + JobPersistenceException thrown if a SQLException occurs when the + + + + Execute the given callback in a transaction. Depending on the JobStore, + the surrounding transaction may be assumed to be already present + (managed). + + + This method just forwards to ExecuteInLock() with a null lockName. + + + + + + Execute the given callback having acquired the given lock. + Depending on the JobStore, the surrounding transaction may be + assumed to be already present (managed). This version is just a + handy wrapper around executeInLock that doesn't require a return + value. + + + The name of the lock to acquire, for example + "TRIGGER_ACCESS". If null, then no lock is acquired, but the + lockCallback is still executed in a transaction. + + + The callback to excute after having acquired the given lock. + + + + + + Execute the given callback having acquired the given lock. + Depending on the JobStore, the surrounding transaction may be + assumed to be already present (managed). + + + The name of the lock to acquire, for example + "TRIGGER_ACCESS". If null, then no lock is acquired, but the + lockCallback is still executed in a transaction. + + + The callback to excute after having acquired the given lock. + + + + + Execute the given callback having optionally acquired the given lock. + This uses the non-managed transaction connection. This version is just a + handy wrapper around executeInNonManagedTXLock that doesn't require a return + value. + + + The name of the lock to acquire, for example + "TRIGGER_ACCESS". If null, then no lock is acquired, but the + lockCallback is still executed in a non-managed transaction. + + + + The callback to excute after having acquired the given lock. + + + + + Execute the given callback having optionally acquired the given lock. + This uses the non-managed transaction connection. + + + The name of the lock to acquire, for example + "TRIGGER_ACCESS". If null, then no lock is acquired, but the + lockCallback is still executed in a non-managed transaction. + + + The callback to excute after having acquired the given lock. + + + + + Get or set the datasource name. + + + + + Gets the log. + + The log. + + + + Get or sets the prefix that should be pre-pended to all table names. + + + + + Set whether string-only properties will be handled in JobDataMaps. + + + + + Get or set the instance Id of the Scheduler (must be unique within a cluster). + + + + + Get or set the instance Id of the Scheduler (must be unique within this server instance). + + + + + Get or set whether this instance is part of a cluster. + + + + + Get or set the frequency at which this instance "checks-in" + with the other instances of the cluster. -- Affects the rate of + detecting failed instances. + + + + + Get or set the maximum number of misfired triggers that the misfire handling + thread will try to recover at one time (within one transaction). The + default is 20. + + + + + Gets or sets the database retry interval. + + The db retry interval. + + + + Get or set whether this instance should use database-based thread + synchronization. + + + + + Whether or not to obtain locks when inserting new jobs/triggers. + Defaults to , which is safest - some db's (such as + MS SQLServer) seem to require this to avoid deadlocks under high load, + while others seem to do fine without. + + + Setting this property to will provide a + significant performance increase during the addition of new jobs + and triggers. + + + + + The time span by which a trigger must have missed its + next-fire-time, in order for it to be considered "misfired" and thus + have its misfire instruction applied. + + + + + Don't call set autocommit(false) on connections obtained from the + DataSource. This can be helpfull in a few situations, such as if you + have a driver that complains if it is called when it is already off. + + + + + Set the transaction isolation level of DB connections to sequential. + + + + + Whether or not the query and update to acquire a Trigger for firing + should be performed after obtaining an explicit DB lock (to avoid + possible race conditions on the trigger's db row). This is + is considered unnecessary for most databases (due to the nature of + the SQL update that is performed), and therefore a superfluous performance hit. + + + However, if batch acquisition is used, it is important for this behavior + to be used for all dbs. + + + + + Get or set the ADO.NET driver delegate class name. + + + + + The driver delegate's initialization string. + + + + + set the SQL statement to use to select and lock a row in the "locks" + table. + + + + + + Get whether the threads spawned by this JobStore should be + marked as daemon. Possible threads include the + and the . + + + + + + Get whether to check to see if there are Triggers that have misfired + before actually acquiring the lock to recover them. This should be + set to false if the majority of the time, there are are misfired + Triggers. + + + + + + Get the driver delegate for DB operations. + + + + + Get whether String-only properties will be handled in JobDataMaps. + + + + + Indicates whether this job store supports persistence. + + + + + + + An interface for classes wishing to provide the service of loading classes + and resources within the scheduler... + + James House + Marko Lahma (.NET) + + + + Called to give the ClassLoadHelper a chance to Initialize itself, + including the oportunity to "steal" the class loader off of the calling + thread, which is the thread that is initializing Quartz. + + + + + Return the class with the given name. + + + + + Finds a resource with a given name. This method returns null if no + resource with this name is found. + + name of the desired resource + + a java.net.URL object + + + + + Finds a resource with a given name. This method returns null if no + resource with this name is found. + + name of the desired resource + + a java.io.InputStream object + + + + + Helper class for returning the composite result of trying + to recover misfired jobs. + + + + + Initializes a new instance of the class. + + if set to true [has more misfired triggers]. + The processed misfired trigger count. + + + + + Gets a value indicating whether this instance has more misfired triggers. + + + true if this instance has more misfired triggers; otherwise, false. + + + + + Gets the processed misfired trigger count. + + The processed misfired trigger count. + + + + Called by the QuartzScheduler before the is + used, in order to give the it a chance to Initialize. + + + + + + + Called by the QuartzScheduler to inform the that + it should free up all of it's resources because the scheduler is + shutting down. + + + + + Gets the non managed TX connection. + + + + + + Execute the given callback having optionally acquired the given lock. + Because CMT assumes that the connection is already part of a managed + transaction, it does not attempt to commit or rollback the + enclosing transaction. + + + + + + + The name of the lock to acquire, for example + "TRIGGER_ACCESS". If null, then no lock is acquired, but the + txCallback is still executed in a transaction. + + Callback to execute. + + + + is meant to be used in a standalone environment. + Both commit and rollback will be handled by this class. + + Jeffrey Wescott + James House + Marko Lahma (.NET) + + + + Called by the QuartzScheduler before the is + used, in order to give the it a chance to Initialize. + + + + + + + For , the non-managed TX connection is just + the normal connection because it is not CMT. + + + + + + Execute the given callback having optionally aquired the given lock. + For , because it manages its own transactions + and only has the one datasource, this is the same behavior as + . + + + The name of the lock to aquire, for example "TRIGGER_ACCESS". + If null, then no lock is aquired, but the lockCallback is still + executed in a transaction. + + Callback to execute. + + + + + + + + + Exception class for when there is a failure obtaining or releasing a + resource lock. + + + James House + Marko Lahma (.NET) + + + + An exception that is thrown to indicate that there has been a failure in the + scheduler's underlying persistence mechanism. + + James House + Marko Lahma (.NET) + + + + Create a with the given message. + + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + Create a with the given message + and cause. + + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + This is a driver delegate for the MySQL ADO.NET driver. + + Marko Lahma + + + + This is meant to be an abstract base class for most, if not all, + implementations. Subclasses should override only those methods that need + special handling for the DBMS driver in question. + + Jeffrey Wescott + James House + Marko Lahma (.NET) + + + + Initializes the driver delegate. + + + + + Insert the job detail record. + + the DB Connection + the new state for the triggers + the first old state to update + the second old state to update + number of rows updated + + + + Get the names of all of the triggers that have misfired. + + the DB Connection + The ts. + an array of objects + + + + Select all of the triggers in a given state. + + The DB Connection + The state the triggers must be in + an array of trigger s + + + + Get the names of all of the triggers in the given state that have + misfired - according to the given timestamp. + + The DB Connection + The state. + The time stamp. + An array of objects + + + + Get the names of all of the triggers in the given state that have + misfired - according to the given timestamp. No more than count will + be returned. + + The conn. + The state1. + The ts. + The most misfired triggers to return, negative for all + + Output parameter. A List of objects. Must not be null + + Whether there are more misfired triggers left to find beyond the given count. + + + + Get the number of triggers in the given state that have + misfired - according to the given timestamp. + + + + + + + + + Get the names of all of the triggers in the given group and state that + have misfired. + + The DB Connection + Name of the group. + The state. + The timestamp. + an array of objects + + + + Select all of the triggers for jobs that are requesting recovery. The + returned trigger objects will have unique "recoverXXX" trigger names and + will be in the + trigger group. + + + In order to preserve the ordering of the triggers, the fire time will be + set from the ColumnFiredTime column in the TableFiredTriggers + table. The caller is responsible for calling + on each returned trigger. It is also up to the caller to insert the + returned triggers to ensure that they are fired. + + The DB Connection + an array of objects + + + + Delete all fired triggers. + + The DB Connection. + The number of rows deleted. + + + + Delete all fired triggers of the given instance. + + The DB Connection + The instance id. + The number of rows deleted + + + + Clear (delete!) all scheduling data - all s, s + s. + + + + + + + Insert the job detail record. + + The DB Connection. + The job to insert. + Number of rows inserted. + + + + Gets the db presentation for boolean value. Subclasses can overwrite this behaviour. + + Value to map to database. + + + + + Gets the boolean value from db presentation. Subclasses can overwrite this behaviour. + + Value to map from database. + + + + + Gets the db presentation for date/time value. Subclasses can overwrite this behaviour. + + Value to map to database. + + + + + Gets the date/time value from db presentation. Subclasses can overwrite this behaviour. + + Value to map from database. + + + + + Gets the db presentation for time span value. Subclasses can overwrite this behaviour. + + Value to map to database. + + + + + Gets the time span value from db presentation. Subclasses can overwrite this behaviour. + + Value to map from database. + + + + + Update the job detail record. + + The DB Connection. + The job to update. + Number of rows updated. + + + + Get the names of all of the triggers associated with the given job. + + The DB Connection. + The key identifying the job. + An array of objects + + + + Delete the job detail record for the given job. + + the DB Connection + The key identifying the job. + the number of rows deleted + + + + Check whether or not the given job is stateful. + + the DB Connection + The key identifying the job. + + true if the job exists and is stateful, false otherwise + + + + + Check whether or not the given job exists. + + the DB Connection + The key identifying the job. + true if the job exists, false otherwise + + + + Update the job data map for the given job. + + The conn. + the job to update + the number of rows updated + + + + Select the JobDetail object for a given job name / group name. + + The DB Connection. + The key identifying the job. + The load helper. + The populated JobDetail object. + + + build Map from java.util.Properties encoding. + + + + Select the total number of jobs stored. + + The DB Connection. + The total number of jobs stored. + + + + Select all of the job group names that are stored. + + The DB Connection. + An array of group names. + + + + Select all of the jobs contained in a given group. + + The DB Connection. + + An array of job names. + + + + Insert the base trigger data. + + the DB Connection + the trigger to insert + the state that the trigger should be stored in + The job detail. + the number of rows inserted + + + + Insert the blob trigger data. + + The DB Connection. + The trigger to insert. + The number of rows inserted. + + + + Update the base trigger data. + + The DB Connection. + The trigger to insert. + The state that the trigger should be stored in. + The job detail. + The number of rows updated. + + + + Update the blob trigger data. + + The DB Connection. + The trigger to insert. + The number of rows updated. + + + + Check whether or not a trigger exists. + + The DB Connection. + the key of the trigger + true if the trigger exists, false otherwise + + + + Update the state for a given trigger. + + The DB Connection. + the key of the trigger + The new state for the trigger. + The number of rows updated. + + + + Update the given trigger to the given new state, if it is one of the + given old states. + + The DB connection. + the key of the trigger + The new state for the trigger. + One of the old state the trigger must be in. + One of the old state the trigger must be in. + One of the old state the trigger must be in. + The number of rows updated. + + + + Update all triggers in the given group to the given new state, if they + are in one of the given old states. + + The DB connection. + + The new state for the trigger. + One of the old state the trigger must be in. + One of the old state the trigger must be in. + One of the old state the trigger must be in. + The number of rows updated. + + + + Update the given trigger to the given new state, if it is in the given + old state. + + the DB connection + the key of the trigger + the new state for the trigger + the old state the trigger must be in + int the number of rows updated + + + + Update all of the triggers of the given group to the given new state, if + they are in the given old state. + + the DB connection + + the new state for the trigger group + the old state the triggers must be in + int the number of rows updated + + + + Update the states of all triggers associated with the given job. + + the DB Connection + the key of the job + the new state for the triggers + the number of rows updated + + + + Updates the state of the trigger states for job from other. + + The conn. + Key of the job. + The state. + The old state. + + + + + Delete the cron trigger data for a trigger. + + the DB Connection + the key of the trigger + the number of rows deleted + + + + Delete the base trigger data for a trigger. + + the DB Connection + the key of the trigger + the number of rows deleted + + + + Select the number of triggers associated with a given job. + + the DB Connection + the key of the job + the number of triggers for the given job + + + + Select the job to which the trigger is associated. + + the DB Connection + the key of the trigger + The load helper. + The object associated with the given trigger + + + + Select the triggers for a job + + the DB Connection + the key of the job + + an array of objects + associated with a given job. + + + + + Select the triggers for a calendar + + The DB Connection. + Name of the calendar. + + An array of objects associated with a given job. + + + + + Select a trigger. + + the DB Connection + the key of the trigger + The object + + + + Select a trigger's JobDataMap. + + the DB Connection + the key of the trigger + The of the Trigger, never null, but possibly empty. + + + + Select a trigger's state value. + + the DB Connection + the key of the trigger + The object + + + + Select a trigger status (state and next fire time). + + the DB Connection + the key of the trigger + + a object, or null + + + + + Select the total number of triggers stored. + + the DB Connection + the total number of triggers stored + + + + Select all of the trigger group names that are stored. + + the DB Connection + + an array of group names + + + + + Select all of the triggers contained in a given group. + + the DB Connection + + + an array of trigger names + + + + + Inserts the paused trigger group. + + The conn. + Name of the group. + + + + + Deletes the paused trigger group. + + The conn. + Name of the group. + + + + + Deletes all paused trigger groups. + + The conn. + + + + + Determines whether the specified trigger group is paused. + + The conn. + Name of the group. + + true if trigger group is paused; otherwise, false. + + + + + Determines whether given trigger group already exists. + + The conn. + Name of the group. + + true if trigger group exists; otherwise, false. + + + + + Insert a new calendar. + + the DB Connection + The name for the new calendar. + The calendar. + the number of rows inserted + IOException + + + + Update a calendar. + + the DB Connection + The name for the new calendar. + The calendar. + the number of rows updated + IOException + + + + Check whether or not a calendar exists. + + the DB Connection + The name of the calendar. + + true if the trigger exists, false otherwise + + + + + Select a calendar. + + the DB Connection + The name of the calendar. + the Calendar + ClassNotFoundException + IOException + + + + Check whether or not a calendar is referenced by any triggers. + + the DB Connection + The name of the calendar. + + true if any triggers reference the calendar, false otherwise + + + + + Delete a calendar. + + the DB Connection + The name of the trigger. + the number of rows deleted + + + + Select the total number of calendars stored. + + the DB Connection + the total number of calendars stored + + + + Select all of the stored calendars. + + the DB Connection + + an array of calendar names + + + + + Select the trigger that will be fired at the given fire time. + + the DB Connection + the time that the trigger will be fired + + a representing the + trigger that will be fired at the given fire time, or null if no + trigger will be fired at that time + + + + + Select the next trigger which will fire to fire between the two given timestamps + in ascending order of fire time, and then descending by priority. + + The conn. + highest value of of the triggers (exclusive) + highest value of of the triggers (inclusive) + maximum number of trigger keys allow to acquired in the returning list. + A (never null, possibly empty) list of the identifiers (Key objects) of the next triggers to be fired. + + + + Insert a fired trigger. + + the DB Connection + the trigger + the state that the trigger should be stored in + The job. + the number of rows inserted + + + + + Update a fired trigger. + + + + + + the DB Connection + + the trigger + + + the state that the trigger should be stored in + the number of rows inserted + + + + Select the states of all fired-trigger records for a given trigger, or + trigger group if trigger name is . + + The DB connection. + Name of the trigger. + Name of the group. + a List of objects. + + + + Select the states of all fired-trigger records for a given job, or job + group if job name is . + + The DB connection. + Name of the job. + Name of the group. + a List of objects. + + + + Select the states of all fired-trigger records for a given scheduler + instance. + + The DB Connection + Name of the instance. + A list of FiredTriggerRecord objects. + + + + Select the distinct instance names of all fired-trigger records. + + The conn. + + + This is useful when trying to identify orphaned fired triggers (a + fired trigger without a scheduler state record.) + + + + + Delete a fired trigger. + + the DB Connection + the fired trigger entry to delete + the number of rows deleted + + + + Selects the job execution count. + + The DB connection. + The key of the job. + + + + + Inserts the state of the scheduler. + + The conn. + The instance id. + The check in time. + The interval. + + + + + Deletes the state of the scheduler. + + The database connection. + The instance id. + + + + + Updates the state of the scheduler. + + The database connection. + The instance id. + The check in time. + + + + + A List of all current s. + + If instanceId is not null, then only the record for the identified + instance will be returned. + + + The DB Connection + The instance id. + + + + + Replace the table prefix in a query by replacing any occurrences of + "{0}" with the table prefix. + + The unsubstitued query + The query, with proper table prefix substituted + + + + Create a serialized version of an Object. + + the object to serialize + Serialized object as byte array. + + + + Remove the transient data from and then create a serialized + version of a and returns the underlying bytes. + + The data. + the serialized data as byte array + + + + serialize + + The data. + + + + + Convert the JobDataMap into a list of properties. + + + + + Convert the JobDataMap into a list of properties. + + + + + This method should be overridden by any delegate subclasses that need + special handling for BLOBs. The default implementation uses standard + ADO.NET operations. + + The data reader, already queued to the correct row. + The column index for the BLOB. + The deserialized object from the DataReader BLOB. + + + + This method should be overridden by any delegate subclasses that need + special handling for BLOBs for job details. + + The result set, already queued to the correct row. + The column index for the BLOB. + The deserialized Object from the ResultSet BLOB. + + + + Selects the paused trigger groups. + + The DB Connection. + + + + + Gets the select next trigger to acquire SQL clause. + MySQL version with LIMIT support. + + + + + + Exception class for when a driver delegate cannot be found for a given + configuration, or lack thereof. + + Jeffrey Wescott + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + This is a driver delegate for the Oracle database. + + Marko Lahma + + + + Creates the SQL for select next trigger to acquire. + + + + + Gets the db presentation for boolean value. For Oracle we use true/false of "1"/"0". + + Value to map to database. + + + + + Conveys a scheduler-instance state record. + + James House + Marko Lahma (.NET) + + + + Gets or sets the checkin interval. + + The checkin interval. + + + + Gets or sets the checkin timestamp. + + The checkin timestamp. + + + + Gets or sets the scheduler instance id. + + The scheduler instance id. + + + + Internal in-memory lock handler for providing thread/resource locking in + order to protect resources from being altered by multiple threads at the + same time. + + James House + Marko Lahma (.NET) + + + + Grants a lock on the identified resource to the calling thread (blocking + until it is available). + + True if the lock was obtained. + + + Release the lock on the identified resource if it is held by the calling + thread. + + + + + Determine whether the calling thread owns a lock on the identified + resource. + + + + + Gets the thread locks. + + The thread locks. + + + + Whether this Semaphore implementation requires a database connection for + its lock management operations. + + + + + + + + + This is a driver delegate for the SQLiteDelegate ADO.NET driver. + + Marko Lahma + + + + Gets the select next trigger to acquire SQL clause. + SQLite version with LIMIT support. + + + + + + A SQL Server specific driver delegate. + + Marko Lahma + + + + Gets the select next trigger to acquire SQL clause. + SQL Server specific version with TOP functionality + + + + + + Internal database based lock handler for providing thread/resource locking + in order to protect resources from being altered by multiple threads at the + same time. + + James House + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + The table prefix. + the scheduler name + The select with lock SQL. + + + + + Execute the SQL select for update that will lock the proper database row. + + + + + Property name and value holder for trigger state data. + + + + + Object representing a job or trigger key. + + James House + Marko Lahma (.NET) + + + + Construct a new TriggerStatus with the status name and nextFireTime. + + The trigger's status + The next time trigger will fire + + + + Return the string representation of the TriggerStatus. + + + + + + Provide thread/resource locking in order to protect + resources from being altered by multiple threads at the same time using + a db row update. + + + + Note: This Semaphore implementation is useful for databases that do + not support row locking via "SELECT FOR UPDATE" or SQL Server's type syntax. + + + As of Quartz.NET 2.0 version there is no need to use this implementation for + SQL Server databases. + + + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Execute the SQL that will lock the proper database row. + + + + + + + + + This implementation of the Calendar excludes a set of days of the year. You + may use it to exclude bank holidays which are on the same date every year. + + + + Juergen Donnerstag + Marko Lahma (.NET) + + + + This implementation of the Calendar may be used (you don't have to) as a + base class for more sophisticated one's. It merely implements the base + functionality required by each Calendar. + + + Regarded as base functionality is the treatment of base calendars. Base + calendar allow you to chain (stack) as much calendars as you may need. For + example to exclude weekends you may use WeeklyCalendar. In order to exclude + holidays as well you may define a WeeklyCalendar instance to be the base + calendar for HolidayCalendar instance. + + + Juergen Donnerstag + James House + Marko Lahma (.NET) + + + + An interface to be implemented by objects that define spaces of time during + which an associated may (not) fire. Calendars + do not define actual fire times, but rather are used to limit a + from firing on its normal schedule if necessary. Most + Calendars include all times by default and allow the user to specify times + to exclude. + + + As such, it is often useful to think of Calendars as being used to exclude a block + of time - as opposed to include a block of time. (i.e. the + schedule "fire every five minutes except on Sundays" could be + implemented with a and a + which excludes Sundays) + + Implementations MUST take care of being properly cloneable and Serializable. + + + James House + Juergen Donnerstag + Marko Lahma (.NET) + + + + Determine whether the given UTC time is 'included' by the + Calendar. + + + + + Determine the next UTC time that is 'included' by the + Calendar after the given UTC time. + + + + + Gets or sets a description for the instance - may be + useful for remembering/displaying the purpose of the calendar, though + the description has no meaning to Quartz. + + + + + Set a new base calendar or remove the existing one. + Get the base calendar. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The base calendar. + + + + Initializes a new instance of the class. + + The time zone. + + + + Initializes a new instance of the class. + + The base calendar. + The time zone. + + + + Serialization constructor. + + + + + + + checks whether two arrays have + the same length and + for any given place there are equal elements + in both arrays + + + + + + Get the base calendar. Will be null, if not set. + + + + + Check if date/time represented by timeStamp is included. If included + return true. The implementation of BaseCalendar simply calls the base + calendars IsTimeIncluded() method if base calendar is set. + + + + + + Determine the next UTC time (in milliseconds) that is 'included' by the + Calendar after the given time. Return the original value if timeStamp is + included. Return 0 if all days are excluded. + + + + + + Creates a new object that is a copy of the current instance. + + A new object that is a copy of this instance. + + + + Gets or sets the time zone. + + The time zone. + + + + Gets or sets the description given to the instance by + its creator (if any). + + + + + Set a new base calendar or remove the existing one + + + + + + Constructor + + + + + Constructor + + The base calendar. + + + + Serialization constructor. + + + + + + + Return true, if day is defined to be exluded. + + + + + Redefine a certain day to be excluded (true) or included (false). + + + + + Determine whether the given UTC time (in milliseconds) is 'included' by the + Calendar. + + Note that this Calendar is only has full-day precision. + + + + + + Determine the next UTC time (in milliseconds) that is 'included' by the + Calendar after the given time. Return the original value if timeStampUtc is + included. Return 0 if all days are excluded. + + Note that this Calendar is only has full-day precision. + + + + + + Get or the array which defines the exclude-value of each day of month. + Setting will redefine the array of days excluded. The array must of size greater or + equal 31. + + + + + This implementation of the Calendar excludes the set of times expressed by a + given CronExpression. + + + For example, you could use this calendar to exclude all but business hours (8AM - 5PM) every + day using the expression "* * 0-7,18-23 ? * *". + + It is important to remember that the cron expression here describes a set of + times to be excluded from firing. Whereas the cron expression in + CronTrigger describes a set of times that can + be included for firing. Thus, if a has a + given cron expression and is associated with a with + the same expression, the calendar will exclude all the times the + trigger includes, and they will cancel each other out. + + + Aaron Craven + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + a string representation of the desired cron expression + + + + Create a with the given cron expression and + . + + + the base calendar for this calendar instance + see BaseCalendar for more information on base + calendar functionality + + a string representation of the desired cron expression + + + + Create a with the given cron expression and + . + + + the base calendar for this calendar instance + see BaseCalendar for more information on base + calendar functionality + + a string representation of the desired cron expression + + + + + Serialization constructor. + + + + + + + Determine whether the given time is 'included' by the + Calendar. + + the time to test + a boolean indicating whether the specified time is 'included' by the CronCalendar + + + + Determine the next time that is 'included' by the + Calendar after the given time. Return the original value if timeStamp is + included. Return 0 if all days are excluded. + + + + + + + Creates a new object that is a copy of the current instance. + + A new object that is a copy of this instance. + + + + Returns a that represents the current . + + + A that represents the current . + + + + + Sets the cron expression for the calendar to a new value. + + The expression. + + + + Returns the object representation of the cron expression that defines the + dates and times this calendar excludes. + + + + + This implementation of the Calendar excludes (or includes - see below) a + specified time range each day. + + + For example, you could use this calendar to + exclude business hours (8AM - 5PM) every day. Each + only allows a single time range to be specified, and that time range may not + * cross daily boundaries (i.e. you cannot specify a time range from 8PM - 5AM). + If the property is (default), + the time range defines a range of times in which triggers are not allowed to + * fire. If is , the time range + is inverted: that is, all times outside the defined time range + are excluded. + + Note when using , it behaves on the same principals + as, for example, WeeklyCalendar defines a set of days that are + excluded every week. Likewise, defines a + set of times that are excluded every day. + + + Mike Funk + Aaron Craven + Marko Lahma (.NET) + + + + Create a with a time range defined by the + specified strings and no baseCalendar. + and + must be in the format "HH:MM[:SS[:mmm]]" where: +
    +
  • + HH is the hour of the specified time. The hour should be + specified using military (24-hour) time and must be in the range + 0 to 23. +
    • +
  • + MM is the minute of the specified time and must be in the range + 0 to 59. +
    • +
  • + SS is the second of the specified time and must be in the range + 0 to 59. +
    • +
  • + mmm is the millisecond of the specified time and must be in the + range 0 to 999. +
    • +
  • items enclosed in brackets ('[', ']') are optional.
    • +
  • + The time range starting time must be before the time range ending + time. Note this means that a time range may not cross daily + boundaries (10PM - 2AM) +
    • +
+ + + + + Create a with a time range defined by the + specified strings and the specified baseCalendar. + and + must be in the format "HH:MM[:SS[:mmm]]" where: +
    +
  • + HH is the hour of the specified time. The hour should be + specified using military (24-hour) time and must be in the range + 0 to 23. +
    • +
  • + MM is the minute of the specified time and must be in the range + 0 to 59. +
    • +
  • + SS is the second of the specified time and must be in the range + 0 to 59. +
    • +
  • + mmm is the millisecond of the specified time and must be in the + range 0 to 999. +
    • +
  • + items enclosed in brackets ('[', ']') are optional. +
    • +
  • + The time range starting time must be before the time range ending + time. Note this means that a time range may not cross daily + boundaries (10PM - 2AM) +
    • +
+ + The base calendar for this calendar instance see BaseCalendar for more + information on base calendar functionality. + + + + Create a with a time range defined by the + specified values and no baseCalendar. Values are subject to + the following validations: +
    +
  • + Hours must be in the range 0-23 and are expressed using military + (24-hour) time. +
    • +
  • Minutes must be in the range 0-59
    • +
  • Seconds must be in the range 0-59
    • +
  • Milliseconds must be in the range 0-999
    • +
  • + The time range starting time must be before the time range ending + time. Note this means that a time range may not cross daily + boundaries (10PM - 2AM) +
    • +
+ + The range starting hour of day. + The range starting minute. + The range starting second. + The range starting millis. + The range ending hour of day. + The range ending minute. + The range ending second. + The range ending millis. + + + + Create a with a time range defined by the + specified values and the specified . Values are + subject to the following validations: +
    +
  • + Hours must be in the range 0-23 and are expressed using military + (24-hour) time. +
    • +
  • Minutes must be in the range 0-59
    • +
  • Seconds must be in the range 0-59
    • +
  • Milliseconds must be in the range 0-999
    • +
  • + The time range starting time must be before the time range ending + time. Note this means that a time range may not cross daily + boundaries (10PM - 2AM) +
    • +
+ + The range starting hour of day. + The range starting minute. + The range starting second. + The range starting millis. + The range ending hour of day. + The range ending minute. + The range ending second. + The range ending millis. + + + + Create a with a time range defined by the + specified s and no + baseCalendar. The Calendars are subject to the following + considerations: +
    +
  • + Only the time-of-day fields of the specified Calendars will be + used (the date fields will be ignored) +
    • +
  • + The starting time must be before the ending time of the defined + time range. Note this means that a time range may not cross + daily boundaries (10PM - 2AM). (because only time fields are + are used, it is possible for two Calendars to represent a valid + time range and + rangeStartingCalendar.after(rangeEndingCalendar) == true) + +
    • +
+ + The range starting calendar. + The range ending calendar. + + + + Create a with a time range defined by the + specified s and the specified + . The Calendars are subject to the following + considerations: +
    +
  • + Only the time-of-day fields of the specified Calendars will be + used (the date fields will be ignored) +
    • +
  • + The starting time must be before the ending time of the defined + time range. Note this means that a time range may not cross + daily boundaries (10PM - 2AM). (because only time fields are + are used, it is possible for two Calendars to represent a valid + time range and + rangeStartingCalendarUtc > rangeEndingCalendarUtc == true) +
    • +
+ + The range starting calendar. + The range ending calendar. + + + + Create a with a time range defined by the + specified values and no baseCalendar. The values are + subject to the following considerations: +
    +
  • + Only the time-of-day portion of the specified values will be + used +
    • +
  • + The starting time must be before the ending time of the defined + time range. Note this means that a time range may not cross + daily boundaries (10PM - 2AM). (because only time value are + are used, it is possible for the two values to represent a valid + time range and rangeStartingTime > rangeEndingTime) +
    • +
+ + The range starting time in millis. + The range ending time in millis. + + + + Create a with a time range defined by the + specified values and the specified . The values + are subject to the following considerations: +
    +
  • + Only the time-of-day portion of the specified values will be + used +
    • +
  • + The starting time must be before the ending time of the defined + time range. Note this means that a time range may not cross + daily boundaries (10PM - 2AM). (because only time value are + are used, it is possible for the two values to represent a valid + time range and rangeStartingTime > rangeEndingTime) +
    • +
+ + The range starting time in millis. + The range ending time in millis. + + + + Serialization constructor. + + + + + + + Determine whether the given time is 'included' by the + Calendar. + + + + + + + Determine the next time (in milliseconds) that is 'included' by the + Calendar after the given time. Return the original value if timeStamp is + included. Return 0 if all days are excluded. + + + + + + + + Returns the start time of the time range of the day + specified in . + + + a DateTime representing the start time of the + time range for the specified date. + + + + + Returns the end time of the time range of the day + specified in + + + A DateTime representing the end time of the + time range for the specified date. + + + + + Returns a that represents the current . + + + A that represents the current . + + + + + Sets the time range for the to the times + represented in the specified Strings. + + The range starting time string. + The range ending time string. + + + + Sets the time range for the to the times + represented in the specified values. + + The range starting hour of day. + The range starting minute. + The range starting second. + The range starting millis. + The range ending hour of day. + The range ending minute. + The range ending second. + The range ending millis. + + + + Sets the time range for the to the times + represented in the specified s. + + The range starting calendar. + The range ending calendar. + + + + Sets the time range for the to the times + represented in the specified values. + + The range starting time. + The range ending time. + + + + Gets the start of day, practically zeroes time part. + + The time. + + + + + Gets the end of day, pratically sets time parts to maximum allowed values. + + The time. + + + + + Checks the specified values for validity as a set of time values. + + The hour of day. + The minute. + The second. + The millis. + + + + Indicates whether the time range represents an inverted time range (see + class description). + + true if invert time range; otherwise, false. + + + + This implementation of the Calendar stores a list of holidays (full days + that are excluded from scheduling). + + + The implementation DOES take the year into consideration, so if you want to + exclude July 4th for the next 10 years, you need to add 10 entries to the + exclude list. + + Sharada Jambula + Juergen Donnerstag + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The base calendar. + + + + Serialization constructor. + + + + + + + Determine whether the given time (in milliseconds) is 'included' by the + Calendar. + + Note that this Calendar is only has full-day precision. + + + + + + Determine the next time (in milliseconds) that is 'included' by the + Calendar after the given time. + + Note that this Calendar is only has full-day precision. + + + + + + Creates a new object that is a copy of the current instance. + + A new object that is a copy of this instance. + + + + Add the given Date to the list of excluded days. Only the month, day and + year of the returned dates are significant. + + + + + Removes the excluded date. + + The date to remove. + + + + Returns a of Dates representing the excluded + days. Only the month, day and year of the returned dates are + significant. + + + + + This implementation of the Calendar excludes a set of days of the month. You + may use it to exclude every 1. of each month for example. But you may define + any day of a month. + + + + Juergen Donnerstag + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Constructor + + The base calendar. + + + + Serialization constructor. + + + + + + + Initialize internal variables + + + + + Return true, if mday is defined to be exluded. + + + + + Redefine a certain day of the month to be excluded (true) or included + (false). + + + + + Check if all days are excluded. That is no day is included. + + boolean + + + + + Determine whether the given time (in milliseconds) is 'included' by the + Calendar. + + Note that this Calendar is only has full-day precision. + + + + + + Determine the next time (in milliseconds) that is 'included' by the + Calendar after the given time. Return the original value if timeStamp is + included. Return DateTime.MinValue if all days are excluded. + + Note that this Calendar is only has full-day precision. + + + + + + Creates a new object that is a copy of the current instance. + + A new object that is a copy of this instance. + + + + Get or set the array which defines the exclude-value of each day of month + Setting will redefine the array of days excluded. The array must of size greater or + equal 31. + + + + + This implementation of the Calendar excludes a set of days of the week. You + may use it to exclude weekends for example. But you may define any day of + the week. + + + + Juergen Donnerstag + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The base calendar. + + + + Serialization constructor. + + + + + + + Initialize internal variables + + + + + Return true, if wday is defined to be exluded. E. g. + saturday and sunday. + + + + + Redefine a certain day of the week to be excluded (true) or included + (false). Use enum to determine the weekday. + + + + + Check if all week ays are excluded. That is no day is included. + + + + + Determine whether the given time (in milliseconds) is 'included' by the + Calendar. + + Note that this Calendar is only has full-day precision. + + + + + + Determine the next time (in milliseconds) that is 'included' by the + Calendar after the given time. Return the original value if timeStamp is + included. Return DateTime.MinValue if all days are excluded. + + Note that this Calendar is only has full-day precision. + + + + + + Get the array with the week days. + Setting will redefine the array of days excluded. The array must of size greater or + equal 8. java.util.Calendar's constants like MONDAY should be used as + index. A value of true is regarded as: exclude it. + + + + + Matches using an AND operator on two Matcher operands. + + James House + Marko Lahma (.NET) + + + + Matchers can be used in various API methods to + select the entities that should be operated upon. + + James House + + + + + Create an AndMatcher that depends upon the result of both of the given matchers. + + + + + + + + + Matches on the complete key being equal (both name and group). + + + + jhouse + + + + Create an EverythingMatcher that matches all jobs. + + + + + + Create an EverythingMatcher that matches all triggers. + + + + + + Matches on group (ignores name) property of Keys. + + James House + Marko Lahma (.NET) + + + + An abstract base class for some types of matchers. + + James House + Marko Lahma (.NET) + + + + Create a GroupMatcher that matches groups equaling the given string. + + + + + + + Create a GroupMatcher that matches groups starting with the given string. + + + + + + + Create a GroupMatcher that matches groups ending with the given string. + + + + + + + Create a GroupMatcher that matches groups containing the given string. + + + + + + + Matches on the complete key being equal (both name and group). + + James House + Marko Lahma (.NET) + + + + Create a KeyMatcher that matches Keys that equal the given key. + + + + + + + + Matches on name (ignores group) property of Keys. + + James House + Marko Lahma (.NET) + + + + Create a NameMatcher that matches names equaling the given string. + + + + + + + Create a NameMatcher that matches names starting with the given string. + + + + + + + Create a NameMatcher that matches names ending with the given string. + + + + + + + Create a NameMatcher that matches names containing the given string. + + + + + + + Matches using an NOT operator on another Matcher. + + James House + Marko Lahma (.NET) + + + + Create a NotMatcher that reverses the result of the given matcher. + + + + + + + + Matches using an OR operator on two Matcher operands. + + James House + Marko Lahma (.NET) + + + + Create an OrMatcher that depends upon the result of at least one of the given matchers. + + + + + + + + + Operators available for comparing string values. + + + + + The base abstract class to be extended by all triggers. + + + + s have a name and group associated with them, which + should uniquely identify them within a single . + + + + s are the 'mechanism' by which s + are scheduled. Many s can point to the same , + but a single can only point to one . + + + + Triggers can 'send' parameters/data to s by placing contents + into the on the . + + + + + + + + James House + Sharada Jambula + Marko Lahma (.NET) + + + + Internal interface for managing triggers. This interface should not be used by the Quartz client. + + + + + Should not be used by end users. + + + + + The base interface with properties common to all s - + use to instantiate an actual Trigger. + + + + s have a associated with them, which + should uniquely identify them within a single . + + + + s are the 'mechanism' by which s + are scheduled. Many s can point to the same , + but a single can only point to one . + + + + Triggers can 'send' parameters/data to s by placing contents + into the on the . + + + + + + + + + + James House + Sharada Jambula + Marko Lahma (.NET) + + + + Get a that is configured to produce a + schedule identical to this trigger's schedule. + + + + + + Used by the to determine whether or not + it is possible for this to fire again. + + If the returned value is then the + may remove the from the . + + + + + + Returns the next time at which the is scheduled to fire. If + the trigger will not fire again, will be returned. Note that + the time returned can possibly be in the past, if the time that was computed + for the trigger to next fire has already arrived, but the scheduler has not yet + been able to fire the trigger (which would likely be due to lack of resources + e.g. threads). + + + The value returned is not guaranteed to be valid until after the + has been added to the scheduler. + + + + + + Returns the previous time at which the fired. + If the trigger has not yet fired, will be returned. + + + + + Returns the next time at which the will fire, + after the given time. If the trigger will not fire after the given time, + will be returned. + + + + + Get or set the description given to the instance by + its creator (if any). + + + + + Get or set the with the given name with + this Trigger. Use when setting to dis-associate a Calendar. + + + + + Get or set the that is associated with the + . + + Changes made to this map during job execution are not re-persisted, and + in fact typically result in an illegal state. + + + + + + Returns the last UTC time at which the will fire, if + the Trigger will repeat indefinitely, null will be returned. + + Note that the return time *may* be in the past. + + + + + + Get or set the instruction the should be given for + handling misfire situations for this - the + concrete type that you are using will have + defined a set of additional MISFIRE_INSTRUCTION_XXX + constants that may be set to this property. + + If not explicitly set, the default value is . + + + + + + + + + Gets and sets the date/time on which the trigger must stop firing. This + defines the final boundary for trigger firings 舒 the trigger will + not fire after to this date and time. If this value is null, no end time + boundary is assumed, and the trigger can continue indefinitely. + + + + + The time at which the trigger's scheduling should start. May or may not + be the first actual fire time of the trigger, depending upon the type of + trigger and the settings of the other properties of the trigger. However + the first actual first time will not be before this date. + + + Setting a value in the past may cause a new trigger to compute a first + fire time that is in the past, which may cause an immediate misfire + of the trigger. + + + + + The priority of a acts as a tie breaker such that if + two s have the same scheduled fire time, then Quartz + will do its best to give the one with the higher priority first access + to a worker thread. + + + If not explicitly set, the default value is 5. + + + + + + + Set a description for the instance - may be + useful for remembering/displaying the purpose of the trigger, though the + description has no meaning to Quartz. + + + + + Associate the with the given name with this Trigger. + + + + + Set the to be associated with the + . + + + + + The priority of a acts as a tie breaker such that if + two s have the same scheduled fire time, then Quartz + will do its best to give the one with the higher priority first access + to a worker thread. + + + If not explicitly set, the default value is 5. + + + + + + + The time at which the trigger's scheduling should start. May or may not + be the first actual fire time of the trigger, depending upon the type of + trigger and the settings of the other properties of the trigger. However + the first actual first time will not be before this date. + + + Setting a value in the past may cause a new trigger to compute a first + fire time that is in the past, which may cause an immediate misfire + of the trigger. + + ew DateTimeOffset StartTimeUtc { get; set; } + + + + + + Set the time at which the should quit repeating - + regardless of any remaining repeats (based on the trigger's particular + repeat settings). + + + + + + + + Set the instruction the should be given for + handling misfire situations for this - the + concrete type that you are using will have + defined a set of additional MisfireInstruction.XXX + constants that may be passed to this method. + + + If not explicitly set, the default value is . + + + + + + + + This method should not be used by the Quartz client. + + + Called when the has decided to 'fire' + the trigger (Execute the associated ), in order to + give the a chance to update itself for its next + triggering (if any). + + + + + + This method should not be used by the Quartz client. + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + + + After this method has been called, + should return a valid answer. + + + + The first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first firing of the ). + + + + + This method should not be used by the Quartz client. + + + Called after the has executed the + associated with the + in order to get the final instruction code from the trigger. + + + is the that was used by the + 's method. + is the thrown by the + , if any (may be null). + + + One of the members. + + + + + + + + + + This method should not be used by the Quartz client. + + To be implemented by the concrete classes that extend this class. + + + The implementation should update the 's state + based on the MISFIRE_INSTRUCTION_XXX that was selected when the + was created. + + + + + + This method should not be used by the Quartz client. + + The implementation should update the 's state + based on the given new version of the associated + (the state should be updated so that it's next fire time is appropriate + given the Calendar's new settings). + + + + + + + + Validates whether the properties of the are + valid for submission into a . + + + + + This method should not be used by the Quartz client. + + + Usable by + implementations, in order to facilitate 'recognizing' instances of fired + s as their jobs complete execution. + + + + + Returns the previous time at which the fired. + If the trigger has not yet fired, will be returned. + + + + + Create a with no specified name, group, or . + + + Note that the , and + the and properties + must be set before the can be placed into a + . + + + + + Create a with the given name, and default group. + + + Note that the and + properties must be set before the + can be placed into a . + + The name. + + + + Create a with the given name, and group. + + + Note that the and + properties must be set before the + can be placed into a . + + The name. + if , Scheduler.DefaultGroup will be used. + + + + Create a with the given name, and group. + + The name. + if , Scheduler.DefaultGroup will be used. + Name of the job. + The job group. + ArgumentException + if name is null or empty, or the group is an empty string. + + + + + This method should not be used by the Quartz client. + + + Called when the has decided to 'fire' + the trigger (Execute the associated ), in order to + give the a chance to update itself for its next + triggering (if any). + + + + + + This method should not be used by the Quartz client. + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + + + After this method has been called, + should return a valid answer. + + + + The first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first firing of the ). + + + + + This method should not be used by the Quartz client. + + + Called after the has executed the + associated with the + in order to get the final instruction code from the trigger. + + + is the that was used by the + 's method. + is the thrown by the + , if any (may be null). + + + One of the members. + + + + + + + Used by the to determine whether or not + it is possible for this to fire again. + + If the returned value is then the + may remove the from the . + + + + + + Returns the next time at which the is scheduled to fire. If + the trigger will not fire again, will be returned. Note that + the time returned can possibly be in the past, if the time that was computed + for the trigger to next fire has already arrived, but the scheduler has not yet + been able to fire the trigger (which would likely be due to lack of resources + e.g. threads). + + + The value returned is not guaranteed to be valid until after the + has been added to the scheduler. + + + + + + Returns the next time at which the will fire, + after the given time. If the trigger will not fire after the given time, + will be returned. + + + + + Validates the misfire instruction. + + The misfire instruction. + + + + + This method should not be used by the Quartz client. + + To be implemented by the concrete classes that extend this class. + + + The implementation should update the 's state + based on the MISFIRE_INSTRUCTION_XXX that was selected when the + was created. + + + + + + This method should not be used by the Quartz client. + + The implementation should update the 's state + based on the given new version of the associated + (the state should be updated so that it's next fire time is appropriate + given the Calendar's new settings). + + + + + + + + Validates whether the properties of the are + valid for submission into a . + + + + + Return a simple string representation of this object. + + + + + Compare the next fire time of this to that of + another by comparing their keys, or in other words, sorts them + according to the natural (i.e. alphabetical) order of their keys. + + + + + + + Determines whether the specified is equal to the current . + + The to compare with the current . + + true if the specified is equal to the current ; otherwise, false. + + + + + Trigger equality is based upon the equality of the TriggerKey. + + + true if the key of this Trigger equals that of the given Trigger + + + + Serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Creates a new object that is a copy of the current instance. + + + A new object that is a copy of this instance. + + + + + Get or sets the name of this . + + If name is null or empty. + + + + Get the group of this . If , Scheduler.DefaultGroup will be used. + + + if group is an empty string. + + + + + Get or set the name of the associated . + + + if jobName is null or empty. + + + + + Gets or sets the name of the associated 's + group. If set with , Scheduler.DefaultGroup will be used. + + ArgumentException + if group is an empty string. + + + + + Returns the 'full name' of the in the format + "group.name". + + + + + Gets the key. + + The key. + + + + Returns the 'full name' of the that the + points to, in the format "group.name". + + + + + Get or set the description given to the instance by + its creator (if any). + + + + + Get or set the with the given name with + this Trigger. Use when setting to dis-associate a Calendar. + + + + + Get or set the that is associated with the + . + + Changes made to this map during job execution are not re-persisted, and + in fact typically result in an illegal state. + + + + + + Returns the last UTC time at which the will fire, if + the Trigger will repeat indefinitely, null will be returned. + + Note that the return time *may* be in the past. + + + + + + Get or set the instruction the should be given for + handling misfire situations for this - the + concrete type that you are using will have + defined a set of additional MISFIRE_INSTRUCTION_XXX + constants that may be passed to this method. + + If not explicitly set, the default value is . + + + + + + + + + + This method should not be used by the Quartz client. + + + Usable by + implementations, in order to facilitate 'recognizing' instances of fired + s as their jobs complete execution. + + + + + Gets and sets the date/time on which the trigger must stop firing. This + defines the final boundary for trigger firings 舒 the trigger will + not fire after to this date and time. If this value is null, no end time + boundary is assumed, and the trigger can continue indefinitely. + + + + + The time at which the trigger's scheduling should start. May or may not + be the first actual fire time of the trigger, depending upon the type of + trigger and the settings of the other properties of the trigger. However + the first actual first time will not be before this date. + + + Setting a value in the past may cause a new trigger to compute a first + fire time that is in the past, which may cause an immediate misfire + of the trigger. + + + + + Tells whether this Trigger instance can handle events + in millisecond precision. + + + + + The priority of a acts as a tie breaker such that if + two s have the same scheduled fire time, then Quartz + will do its best to give the one with the higher priority first access + to a worker thread. + + + If not explicitly set, the default value is 5. + + + + + + + Gets a value indicating whether this instance has additional properties + that should be considered when for example saving to database. + + + If trigger implementation has additional properties that need to be saved + with base properties you need to make your class override this property with value true. + Returning true will effectively mean that ADOJobStore needs to serialize + this trigger instance to make sure additional properties are also saved. + + + true if this instance has additional properties; otherwise, false. + + + + + A concrete that is used to fire a + based upon repeating calendar time intervals. + + + The trigger will fire every N (see ) units of calendar time + (see ) as specified in the trigger's definition. + This trigger can achieve schedules that are not possible with (e.g + because months are not a fixed number of seconds) or (e.g. because + "every 5 months" is not an even divisor of 12). + + If you use an interval unit of then care should be taken when setting + a value that is on a day near the end of the month. For example, + if you choose a start time that occurs on January 31st, and have a trigger with unit + and interval 1, then the next fire time will be February 28th, + and the next time after that will be March 28th - and essentially each subsequent firing will + occur on the 28th of the month, even if a 31st day exists. If you want a trigger that always + fires on the last day of the month - regardless of the number of days in the month, + you should use . + + + + + + + 2.0 + James House + Marko Lahma (.NET) + + + + A that is used to fire a + based upon repeating calendar time intervals. + + + + + Get or set the interval unit - the time unit on with the interval applies. + + + + + Get the the time interval that will be added to the 's + fire time (in the set repeat interval unit) in order to calculate the time of the + next trigger repeat. + + + + + Get the number of times the has already fired. + + + + + Gets the time zone within which time calculations related to this trigger will be performed. + + + If null, the system default TimeZone will be used. + + + + + If intervals are a day or greater, this property (set to true) will + cause the firing of the trigger to always occur at the same time of day, + (the time of day of the startTime) regardless of daylight saving time + transitions. Default value is false. + + + + For example, without the property set, your trigger may have a start + time of 9:00 am on March 1st, and a repeat interval of 2 days. But + after the daylight saving transition occurs, the trigger may start + firing at 8:00 am every other day. + + + If however, the time of day does not exist on a given day to fire + (e.g. 2:00 am in the United States on the days of daylight saving + transition), the trigger will go ahead and fire one hour off on + that day, and then resume the normal hour on other days. If + you wish for the trigger to never fire at the "wrong" hour, then + you should set the property skipDayIfHourDoesNotExist. + + + + + + + + + If intervals are a day or greater, and + preserveHourOfDayAcrossDaylightSavings property is set to true, and the + hour of the day does not exist on a given day for which the trigger + would fire, the day will be skipped and the trigger advanced a second + interval if this property is set to true. Defaults to false. + + + CAUTION! If you enable this property, and your hour of day happens + to be that of daylight savings transition (e.g. 2:00 am in the United + States) and the trigger's interval would have had the trigger fire on + that day, then you may actually completely miss a firing on the day of + transition if that hour of day does not exist on that day! In such a + case the next fire time of the trigger will be computed as double (if + the interval is 2 days, then a span of 4 days between firings will + occur). + + + + + + Create a with no settings. + + + + + Create a that will occur immediately, and + repeat at the the given interval. + + Name for the trigger instance. + The repeat interval unit (minutes, days, months, etc). + The number of milliseconds to pause between the repeat firing. + + + + Create a that will occur immediately, and + repeat at the the given interval + + Name for the trigger instance. + Group for the trigger instance. + The repeat interval unit (minutes, days, months, etc). + The number of milliseconds to pause between the repeat firing. + + + + Create a that will occur at the given time, + and repeat at the the given interval until the given end time. + + Name for the trigger instance. + A set to the time for the to fire. + A set to the time for the to quit repeat firing. + The repeat interval unit (minutes, days, months, etc). + The number of milliseconds to pause between the repeat firing. + + + + Create a that will occur at the given time, + and repeat at the the given interval until the given end time. + + Name for the trigger instance. + Group for the trigger instance. + A set to the time for the to fire. + A set to the time for the to quit repeat firing. + The repeat interval unit (minutes, days, months, etc). + The number of milliseconds to pause between the repeat firing. + + + + Create a that will occur at the given time, + and repeat at the the given interval until the given end time. + + Name for the trigger instance. + Group for the trigger instance. + Name of the associated job. + Group of the associated job. + A set to the time for the to fire. + A set to the time for the to quit repeat firing. + The repeat interval unit (minutes, days, months, etc). + The number of milliseconds to pause between the repeat firing. + + + + Validates the misfire instruction. + + The misfire instruction. + + + + + Updates the 's state based on the + MisfireInstruction.XXX that was selected when the + was created. + + + If the misfire instruction is set to , + then the following scheme will be used: +
    +
  • The instruction will be interpreted as
    • +
+ + + + + This method should not be used by the Quartz client. + + Called when the has decided to 'fire' + the trigger (Execute the associated ), in order to + give the a chance to update itself for its next + triggering (if any). + + + + + + + This method should not be used by the Quartz client. + + The implementation should update the 's state + based on the given new version of the associated + (the state should be updated so that it's next fire time is appropriate + given the Calendar's new settings). + + + + + + + + This method should not be used by the Quartz client. + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + + + After this method has been called, + should return a valid answer. + + + + The first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first firing of the ). + + + + + Returns the next time at which the is scheduled to fire. If + the trigger will not fire again, will be returned. Note that + the time returned can possibly be in the past, if the time that was computed + for the trigger to next fire has already arrived, but the scheduler has not yet + been able to fire the trigger (which would likely be due to lack of resources + e.g. threads). + + + The value returned is not guaranteed to be valid until after the + has been added to the scheduler. + + + + + + Returns the previous time at which the fired. + If the trigger has not yet fired, will be returned. + + + + + Returns the next time at which the will fire, + after the given time. If the trigger will not fire after the given time, + will be returned. + + + + + Determines whether or not the will occur + again. + + + + + + Validates whether the properties of the are + valid for submission into a . + + + + + Get a that is configured to produce a + schedule identical to this trigger's schedule. + + + + + + + + Get the time at which the should occur. + + + + + Tells whether this Trigger instance can handle events + in millisecond precision. + + + + + Get the time at which the should quit + repeating. + + + + + Get or set the interval unit - the time unit on with the interval applies. + + + + + Get the the time interval that will be added to the 's + fire time (in the set repeat interval unit) in order to calculate the time of the + next trigger repeat. + + + + + If intervals are a day or greater, this property (set to true) will + cause the firing of the trigger to always occur at the same time of day, + (the time of day of the startTime) regardless of daylight saving time + transitions. Default value is false. + + + + For example, without the property set, your trigger may have a start + time of 9:00 am on March 1st, and a repeat interval of 2 days. But + after the daylight saving transition occurs, the trigger may start + firing at 8:00 am every other day. + + + If however, the time of day does not exist on a given day to fire + (e.g. 2:00 am in the United States on the days of daylight saving + transition), the trigger will go ahead and fire one hour off on + that day, and then resume the normal hour on other days. If + you wish for the trigger to never fire at the "wrong" hour, then + you should set the property skipDayIfHourDoesNotExist. + + + + + + + + + If intervals are a day or greater, and + preserveHourOfDayAcrossDaylightSavings property is set to true, and the + hour of the day does not exist on a given day for which the trigger + would fire, the day will be skipped and the trigger advanced a second + interval if this property is set to true. Defaults to false. + + + CAUTION! If you enable this property, and your hour of day happens + to be that of daylight savings transition (e.g. 2:00 am in the United + States) and the trigger's interval would have had the trigger fire on + that day, then you may actually completely miss a firing on the day of + transition if that hour of day does not exist on that day! In such a + case the next fire time of the trigger will be computed as double (if + the interval is 2 days, then a span of 4 days between firings will + occur). + + + + + + Get the number of times the has already fired. + + + + + Returns the final time at which the will + fire, if there is no end time set, null will be returned. + + + Note that the return time may be in the past. + + + + A concrete that is used to fire a + at given moments in time, defined with Unix 'cron-like' definitions. + + + + For those unfamiliar with "cron", this means being able to create a firing + schedule such as: "At 8:00am every Monday through Friday" or "At 1:30am + every last Friday of the month". + + + + The format of a "Cron-Expression" string is documented on the + class. + + + + Here are some full examples:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Expression Meaning
"0 0 12 * * ?"" /> Fire at 12pm (noon) every day" />
"0 15 10 ? * *"" /> Fire at 10:15am every day" />
"0 15 10 * * ?"" /> Fire at 10:15am every day" />
"0 15 10 * * ? *"" /> Fire at 10:15am every day" />
"0 15 10 * * ? 2005"" /> Fire at 10:15am every day during the year 2005" /> +
"0 * 14 * * ?"" /> Fire every minute starting at 2pm and ending at 2:59pm, every day" /> +
"0 0/5 14 * * ?"" /> Fire every 5 minutes starting at 2pm and ending at 2:55pm, every day" /> +
"0 0/5 14,18 * * ?"" /> Fire every 5 minutes starting at 2pm and ending at 2:55pm, AND fire every 5 minutes starting at 6pm and ending at 6:55pm, every day" /> +
"0 0-5 14 * * ?"" /> Fire every minute starting at 2pm and ending at 2:05pm, every day" /> +
"0 10,44 14 ? 3 WED"" /> Fire at 2:10pm and at 2:44pm every Wednesday in the month of March." /> +
"0 15 10 ? * MON-FRI"" /> Fire at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday" /> +
"0 15 10 15 * ?"" /> Fire at 10:15am on the 15th day of every month" /> +
"0 15 10 L * ?"" /> Fire at 10:15am on the last day of every month" /> +
"0 15 10 ? * 6L"" /> Fire at 10:15am on the last Friday of every month" /> +
"0 15 10 ? * 6L"" /> Fire at 10:15am on the last Friday of every month" /> +
"0 15 10 ? * 6L 2002-2005"" /> Fire at 10:15am on every last Friday of every month during the years 2002, 2003, 2004 and 2005" /> +
"0 15 10 ? * 6#3"" /> Fire at 10:15am on the third Friday of every month" /> +
+ + + + Pay attention to the effects of '?' and '*' in the day-of-week and + day-of-month fields! + + + + NOTES: +
    +
  • Support for specifying both a day-of-week and a day-of-month value is + not complete (you'll need to use the '?' character in on of these fields). +
    • +
  • Be careful when setting fire times between mid-night and 1:00 AM - + "daylight savings" can cause a skip or a repeat depending on whether the + time moves back or jumps forward.
    • +
+ + + + + Sharada Jambula + James House + Contributions from Mads Henderson + Marko Lahma (.NET) + + + + The public interface for inspecting settings specific to a CronTrigger, + which is used to fire a + at given moments in time, defined with Unix 'cron-like' schedule definitions. + + + + For those unfamiliar with "cron", this means being able to create a firing + schedule such as: "At 8:00am every Monday through Friday" or "At 1:30am + every last Friday of the month". + + + + The format of a "Cron-Expression" string is documented on the + class. + + + + Here are some full examples:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Expression Meaning
"0 0 12 * * ?"" /> Fire at 12pm (noon) every day" />
"0 15 10 ? * *"" /> Fire at 10:15am every day" />
"0 15 10 * * ?"" /> Fire at 10:15am every day" />
"0 15 10 * * ? *"" /> Fire at 10:15am every day" />
"0 15 10 * * ? 2005"" /> Fire at 10:15am every day during the year 2005" /> +
"0 * 14 * * ?"" /> Fire every minute starting at 2pm and ending at 2:59pm, every day" /> +
"0 0/5 14 * * ?"" /> Fire every 5 minutes starting at 2pm and ending at 2:55pm, every day" /> +
"0 0/5 14,18 * * ?"" /> Fire every 5 minutes starting at 2pm and ending at 2:55pm, AND fire every 5 minutes starting at 6pm and ending at 6:55pm, every day" /> +
"0 0-5 14 * * ?"" /> Fire every minute starting at 2pm and ending at 2:05pm, every day" /> +
"0 10,44 14 ? 3 WED"" /> Fire at 2:10pm and at 2:44pm every Wednesday in the month of March." /> +
"0 15 10 ? * MON-FRI"" /> Fire at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday" /> +
"0 15 10 15 * ?"" /> Fire at 10:15am on the 15th day of every month" /> +
"0 15 10 L * ?"" /> Fire at 10:15am on the last day of every month" /> +
"0 15 10 ? * 6L"" /> Fire at 10:15am on the last Friday of every month" /> +
"0 15 10 ? * 6L"" /> Fire at 10:15am on the last Friday of every month" /> +
"0 15 10 ? * 6L 2002-2005"" /> Fire at 10:15am on every last Friday of every month during the years 2002, 2003, 2004 and 2005" /> +
"0 15 10 ? * 6#3"" /> Fire at 10:15am on the third Friday of every month" /> +
+ + + + Pay attention to the effects of '?' and '*' in the day-of-week and + day-of-month fields! + + + + NOTES: +
    +
  • Support for specifying both a day-of-week and a day-of-month value is + not complete (you'll need to use the '?' character in on of these fields). +
    • +
  • Be careful when setting fire times between mid-night and 1:00 AM - + "daylight savings" can cause a skip or a repeat depending on whether the + time moves back or jumps forward.
    • +
+ + + + + Sharada Jambula + James House + Contributions from Mads Henderson + Marko Lahma (.NET) + + + + Gets the expression summary. + + + + + + Gets or sets the cron expression string. + + The cron expression string. + + + + Sets the time zone for which the of this + will be resolved. + + + If is set after this + property, the TimeZone setting on the CronExpression will "win". However + if is set after this property, the + time zone applied by this method will remain in effect, since the + string cron expression does not carry a time zone! + + The time zone. + + + + Create a with no settings. + + + The start-time will also be set to the current time, and the time zone + will be set the the system's default time zone. + + + + + Create a with the given name and default group. + + + The start-time will also be set to the current time, and the time zone + will be set the the system's default time zone. + + The name of the + + + + Create a with the given name and group. + + + The start-time will also be set to the current time, and the time zone + will be set the the system's default time zone. + + The name of the + The group of the + + + + Create a with the given name, group and + expression. + + + The start-time will also be set to the current time, and the time zone + will be set the the system's default time zone. + + The name of the + The group of the + A cron expression dictating the firing sequence of the + + + + Create a with the given name and group, and + associated with the identified . + + + The start-time will also be set to the current time, and the time zone + will be set the the system's default time zone. + + The name of the . + The group of the + name of the executed on firetime + Group of the executed on firetime + + + + Create a with the given name and group, + associated with the identified , + and with the given "cron" expression. + + + The start-time will also be set to the current time, and the time zone + will be set the the system's default time zone. + + The name of the + The group of the + name of the executed on firetime + Group of the executed on firetime + A cron expression dictating the firing sequence of the + + + + Create a with the given name and group, + associated with the identified , + and with the given "cron" expression resolved with respect to the . + + The name of the + The group of the + name of the executed on firetime + Group of the executed on firetime + A cron expression dictating the firing sequence of the + + Specifies for which time zone the cronExpression should be interpreted, + i.e. the expression 0 0 10 * * ?, is resolved to 10:00 am in this time zone. + + + + + Create a that will occur at the given time, + until the given end time. + + If null, the start-time will also be set to the current time, the time + zone will be set the the system's default. + + + The name of the + The group of the + name of the executed on firetime + Group of the executed on firetime + A set to the earliest time for the to start firing. + A set to the time for the to quit repeat firing. + A cron expression dictating the firing sequence of the + + + + Create a with fire time dictated by the + resolved with respect to the specified + occurring from the until + the given . + + The name of the + The group of the + name of the executed on firetime + Group of the executed on firetime + A set to the earliest time for the to start firing. + A set to the time for the to quit repeat firing. + + + + Clones this instance. + + + + + + Returns the next time at which the is scheduled to fire. If + the trigger will not fire again, will be returned. Note that + the time returned can possibly be in the past, if the time that was computed + for the trigger to next fire has already arrived, but the scheduler has not yet + been able to fire the trigger (which would likely be due to lack of resources + e.g. threads). + + + The value returned is not guaranteed to be valid until after the + has been added to the scheduler. + + + + + + Returns the previous time at which the fired. + If the trigger has not yet fired, will be returned. + + + + + + Sets the next fire time. + + This method should not be invoked by client code. + + + The fire time. + + + + Sets the previous fire time. + + This method should not be invoked by client code. + + + The fire time. + + + + Returns the next time at which the will fire, + after the given time. If the trigger will not fire after the given time, + will be returned. + + + + + + + Used by the to determine whether or not + it is possible for this to fire again. + + If the returned value is then the + may remove the from the . + + + + + + + Validates the misfire instruction. + + The misfire instruction. + + + + + This method should not be used by the Quartz client. + + To be implemented by the concrete classes that extend this class. + + + The implementation should update the 's state + based on the MISFIRE_INSTRUCTION_XXX that was selected when the + was created. + + + + + + + + Determines whether the date and (optionally) time of the given Calendar + instance falls on a scheduled fire-time of this trigger. + + + + Equivalent to calling . + + + The date to compare. + + + + + Determines whether the date and (optionally) time of the given Calendar + instance falls on a scheduled fire-time of this trigger. + + Note that the value returned is NOT validated against the related + ICalendar (if any). + + + The date to compare + If set to true, the method will only determine if the + trigger will fire during the day represented by the given Calendar + (hours, minutes and seconds will be ignored). + + + + + Called when the has decided to 'fire' + the trigger (Execute the associated ), in order to + give the a chance to update itself for its next + triggering (if any). + + + + + + + Updates the trigger with new calendar. + + The calendar to update with. + The misfire threshold. + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + After this method has been called, + should return a valid answer. + + + + + the first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first firing of the ). + + + + + Gets the expression summary. + + + + + + Gets the next time to fire after the given time. + + The time to compute from. + + + + + NOT YET IMPLEMENTED: Returns the time before the given time + that this will fire. + + The date. + + + + + Gets or sets the cron expression string. + + The cron expression string. + + + + Set the CronExpression to the given one. The TimeZone on the passed-in + CronExpression over-rides any that was already set on the Trigger. + + The cron expression. + + + + Returns the date/time on which the trigger may begin firing. This + defines the initial boundary for trigger firings the trigger + will not fire prior to this date and time. + + + + + + Get or sets the time at which the CronTrigger should quit + repeating - even if repeastCount isn't yet satisfied. + + + + + Sets the time zone for which the of this + will be resolved. + + + If is set after this + property, the TimeZone setting on the CronExpression will "win". However + if is set after this property, the + time zone applied by this method will remain in effect, since the + string cron expression does not carry a time zone! + + The time zone. + + + + Returns the last UTC time at which the will fire, if + the Trigger will repeat indefinitely, null will be returned. + + Note that the return time *may* be in the past. + + + + + + Tells whether this Trigger instance can handle events + in millisecond precision. + + + + + + A concrete implementation of DailyTimeIntervalTrigger that is used to fire a + based upon daily repeating time intervals. + + + + The trigger will fire every N ( ) seconds, minutes or hours + (see ) during a given time window on specified days of the week. + + + For example#1, a trigger can be set to fire every 72 minutes between 8:00 and 11:00 everyday. It's fire times would + be 8:00, 9:12, 10:24, then next day would repeat: 8:00, 9:12, 10:24 again. + + + For example#2, a trigger can be set to fire every 23 minutes between 9:20 and 16:47 Monday through Friday. + + + On each day, the starting fire time is reset to startTimeOfDay value, and then it will add repeatInterval value to it until + the endTimeOfDay is reached. If you set daysOfWeek values, then fire time will only occur during those week days period. Again, + remember this trigger will reset fire time each day with startTimeOfDay, regardless of your interval or endTimeOfDay! + + + The default values for fields if not set are: startTimeOfDay defaults to 00:00:00, the endTimeOfDay default to 23:59:59, + and daysOfWeek is default to every day. The startTime default to current time-stamp now, while endTime has not value. + + + If startTime is before startTimeOfDay, then startTimeOfDay will be used and startTime has no affect. Else if startTime is + after startTimeOfDay, then the first fire time for that day will be the next interval after the startTime. For example, if + you set startingTimeOfDay=9am, endingTimeOfDay=11am, interval=15 mins, and startTime=9:33am, then the next fire time will + be 9:45pm. Note also that if you do not set startTime value, the trigger builder will default to current time, and current time + maybe before or after the startTimeOfDay! So be aware how you set your startTime. + + + This trigger also supports "repeatCount" feature to end the trigger fire time after + a certain number of count is reached. Just as the SimpleTrigger, setting repeatCount=0 + means trigger will fire once only! Setting any positive count then the trigger will repeat + count + 1 times. Unlike SimpleTrigger, the default value of repeatCount of this trigger + is set to REPEAT_INDEFINITELY instead of 0 though. + + + + + 2.0 + James House + Zemian Deng saltnlight5@gmail.com + Nuno Maia (.NET) + + + + A that is used to fire a + based upon daily repeating time intervals. + + + The trigger will fire every N (see ) seconds, minutes or hours + (see during a given time window on specified days of the week. + + For example#1, a trigger can be set to fire every 72 minutes between 8:00 and 11:00 everyday. It's fire times + be 8:00, 9:12, 10:24, then next day would repeat: 8:00, 9:12, 10:24 again. + + For example#2, a trigger can be set to fire every 23 minutes between 9:20 and 16:47 Monday through Friday. + + On each day, the starting fire time is reset to startTimeOfDay value, and then it will add repeatInterval value to it until + the endTimeOfDay is reached. If you set daysOfWeek values, then fire time will only occur during those week days period. + + The default values for fields if not set are: startTimeOfDay defaults to 00:00:00, the endTimeOfDay default to 23:59:59, + and daysOfWeek is default to every day. The startTime default to current time-stamp now, while endTime has not value. + + If startTime is before startTimeOfDay, then it has no affect. Else if startTime after startTimeOfDay, then the first fire time + for that day will be normal startTimeOfDay incremental values after startTime value. Same reversal logic is applied to endTime + with endTimeOfDay. + + + + James House + Zemian Deng saltnlight5@gmail.com + Nuno Maia (.NET) + + + + + + + + + Get the the number of times for interval this trigger should repeat, + after which it will be automatically deleted. + + + + + Get the interval unit - the time unit on with the interval applies. + The only intervals that are valid for this type of trigger are , + , and + + + + + Get the the time interval that will be added to the 's + fire time (in the set repeat interval unit) in order to calculate the time of the + next trigger repeat. + + + + + The time of day to start firing at the given interval. + + + + + The time of day to complete firing at the given interval. + + + + + The days of the week upon which to fire. + + + A Set containing the integers representing the days of the week, per the values 0-6 as defined by + DayOfWees.Sunday - DayOfWeek.Saturday. + + + + + Get the number of times the has already fired. + + + + + Used to indicate the 'repeat count' of the trigger is indefinite. Or in + other words, the trigger should repeat continually until the trigger's + ending timestamp. + + + + + Create a with no settings. + + + + + Create a that will occur immediately, and + repeat at the the given interval. + + + The that the repeating should begin occurring. + The that the repeating should stop occurring. + The repeat interval unit. The only intervals that are valid for this type of trigger are + , , and . + + + + + Create a that will occur immediately, and + repeat at the the given interval. + + + + The that the repeating should begin occurring. + The that the repeating should stop occurring. + The repeat interval unit. The only intervals that are valid for this type of trigger are + , , and . + + + + + Create a that will occur at the given time, + and repeat at the the given interval until the given end time. + + + A set to the time for the to fire. + A set to the time for the to quit repeat firing. + The that the repeating should begin occurring. + The that the repeating should stop occurring. + The repeat interval unit. The only intervals that are valid for this type of trigger are + , , and . + The number of milliseconds to pause between the repeat firing. + + + + Create a that will occur at the given time, + and repeat at the the given interval until the given end time. + + + + A set to the time for the to fire. + A set to the time for the to quit repeat firing. + The that the repeating should begin occurring. + The that the repeating should stop occurring. + The repeat interval unit. The only intervals that are valid for this type of trigger are + , , and . + The number of milliseconds to pause between the repeat firing. + + + + Create a that will occur at the given time, + fire the identified job and repeat at the the given + interval until the given end time. + + + + + + A set to the time for the to fire. + A set to the time for the to quit repeat firing. + The that the repeating should begin occurring. + The that the repeating should stop occurring. + The repeat interval unit. The only intervals that are valid for this type of trigger are + , , and . + The number of milliseconds to pause between the repeat firing. + + + + Updates the 's state based on the + MisfireInstruction.XXX that was selected when the + was created. + + + If the misfire instruction is set to , + then the following scheme will be used: +
    +
  • The instruction will be interpreted as
    • +
+ + + + + Called when the scheduler has decided to 'fire' + the trigger (execute the associated job), in order to + give the trigger a chance to update itself for its next + triggering (if any). + + + + + + + + + + + + + + + This method should not be used by the Quartz client. + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + + + After this method has been called, + should return a valid answer. + + + + The first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first firing of the ). + + + + + Returns the next time at which the is scheduled to fire. If + the trigger will not fire again, will be returned. Note that + the time returned can possibly be in the past, if the time that was computed + for the trigger to next fire has already arrived, but the scheduler has not yet + been able to fire the trigger (which would likely be due to lack of resources + e.g. threads). + + + The value returned is not guaranteed to be valid until after the + has been added to the scheduler. + + + + + + Returns the previous time at which the fired. + If the trigger has not yet fired, will be returned. + + + + + Set the next time at which the should fire. + + + This method should not be invoked by client code. + + + + + + Set the previous time at which the fired. + + + This method should not be invoked by client code. + + + + + + Returns the next time at which the will + fire, after the given time. If the trigger will not fire after the given + time, will be returned. + + + + + + + Given fireTime time, we need to advance/calculate and return a time of next available week day. + + given next fireTime. + flag to whether to advance day without check existing week day. This scenario + can happen when a caller determine fireTime has passed the endTimeOfDay that fireTime should move to next day anyway. + + a next day fireTime. + + + + Determines whether or not the will occur + again. + + + + + + Validates whether the properties of the are + valid for submission into a . + + + + + Get a that is configured to produce a + schedule identical to this trigger's schedule. + + + + + + + The time at which the should occur. + + + + + the time at which the should quit repeating. + + + + + + Get the the number of times for interval this trigger should repeat, + after which it will be automatically deleted. + + + + + the interval unit - the time unit on with the interval applies. + + + The repeat interval unit. The only intervals that are valid for this type of trigger are + , , and . + + + + + the the time interval that will be added to the 's + fire time (in the set repeat interval unit) in order to calculate the time of the + next trigger repeat. + + + + + the number of times the has already + fired. + + + + + Returns the final time at which the will + fire, if there is no end time set, null will be returned. + + Note that the return time may be in the past. + + + + + The days of the week upon which to fire. + + + A Set containing the integers representing the days of the week, per the values 0-6 as defined by + DayOfWees.Sunday - DayOfWeek.Saturday. + + + + + The time of day to start firing at the given interval. + + + + + The time of day to complete firing at the given interval. + + + + + This trigger has no additional properties besides what's defined in this class. + + + + + + Tells whether this Trigger instance can handle events + in millisecond precision. + + + + + A concrete that is used to fire a + at a given moment in time, and optionally repeated at a specified interval. + + + + James House + Contributions by Lieven Govaerts of Ebitec Nv, Belgium. + Marko Lahma (.NET) + + + + A that is used to fire a + at a given moment in time, and optionally repeated at a specified interval. + + + + James House + Contributions by Lieven Govaerts of Ebitec Nv, Belgium. + Marko Lahma (.NET) + + + + Get or set thhe number of times the should + repeat, after which it will be automatically deleted. + + + + + + Get or set the the time interval at which the should repeat. + + + + + Get or set the number of times the has already + fired. + + + + + Used to indicate the 'repeat count' of the trigger is indefinite. Or in + other words, the trigger should repeat continually until the trigger's + ending timestamp. + + + + + Create a with no settings. + + + + + Create a that will occur immediately, and + not repeat. + + + + + Create a that will occur immediately, and + not repeat. + + + + + Create a that will occur immediately, and + repeat at the the given interval the given number of times. + + + + + Create a that will occur immediately, and + repeat at the the given interval the given number of times. + + + + + Create a that will occur at the given time, + and not repeat. + + + + + Create a that will occur at the given time, + and not repeat. + + + + + Create a that will occur at the given time, + and repeat at the the given interval the given number of times, or until + the given end time. + + The name. + A UTC set to the time for the to fire. + A UTC set to the time for the + to quit repeat firing. + The number of times for the to repeat + firing, use for unlimited times. + The time span to pause between the repeat firing. + + + + Create a that will occur at the given time, + and repeat at the the given interval the given number of times, or until + the given end time. + + The name. + The group. + A UTC set to the time for the to fire. + A UTC set to the time for the + to quit repeat firing. + The number of times for the to repeat + firing, use for unlimited times. + The time span to pause between the repeat firing. + + + + Create a that will occur at the given time, + fire the identified and repeat at the the given + interval the given number of times, or until the given end time. + + The name. + The group. + Name of the job. + The job group. + A set to the time for the + to fire. + A set to the time for the + to quit repeat firing. + The number of times for the to repeat + firing, use RepeatIndefinitely for unlimited times. + The time span to pause between the repeat firing. + + + + Validates the misfire instruction. + + The misfire instruction. + + + + + Updates the 's state based on the + MisfireInstruction value that was selected when the + was created. + + + If MisfireSmartPolicyEnabled is set to true, + then the following scheme will be used:
+
    +
  • If the Repeat Count is 0, then the instruction will + be interpreted as .
    • +
  • If the Repeat Count is , then + the instruction will be interpreted as . + WARNING: using MisfirePolicy.SimpleTrigger.RescheduleNowWithRemainingRepeatCount + with a trigger that has a non-null end-time may cause the trigger to + never fire again if the end-time arrived during the misfire time span. +
    • +
  • If the Repeat Count is > 0, then the instruction + will be interpreted as . +
    • +
+ + + + + Called when the has decided to 'fire' + the trigger (Execute the associated ), in order to + give the a chance to update itself for its next + triggering (if any). + + + + + + Updates the instance with new calendar. + + The calendar. + The misfire threshold. + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + After this method has been called, + should return a valid answer. + + + + The first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first firing of the ). + + + + + Returns the next time at which the will + fire. If the trigger will not fire again, will be + returned. The value returned is not guaranteed to be valid until after + the has been added to the scheduler. + + + + + Returns the previous time at which the fired. + If the trigger has not yet fired, will be + returned. + + + + + Returns the next UTC time at which the will + fire, after the given UTC time. If the trigger will not fire after the given + time, will be returned. + + + + + Returns the last UTC time at which the will + fire, before the given time. If the trigger will not fire before the + given time, will be returned. + + + + + Computes the number of times fired between the two UTC date times. + + The UTC start date and time. + The UTC end date and time. + + + + + Determines whether or not the will occur + again. + + + + + Validates whether the properties of the are + valid for submission into a . + + + + + Get or set thhe number of times the should + repeat, after which it will be automatically deleted. + + + + + + Get or set the the time interval at which the should repeat. + + + + + Get or set the number of times the has already + fired. + + + + + Returns the final UTC time at which the will + fire, if repeatCount is RepeatIndefinitely, null will be returned. + + Note that the return time may be in the past. + + + + + + Tells whether this Trigger instance can handle events + in millisecond precision. + + + + + + Schedules work on a newly spawned thread. This is the default Quartz behavior. + + matt.accola + + + + Allows different strategies for scheduling threads. The + method is required to be called before the first call to + . The Thread containing the work to be performed is + passed to execute and the work is scheduled by the underlying implementation. + + matt.accola + + + + Submit a task for execution. + + Thread to execute. + + + + Initialize any state prior to calling . + + + + + A singleton implementation of . + + + Here are some examples of using this class: + + To create a scheduler that does not write anything to the database (is not + persistent), you can call : + + + DirectSchedulerFactory.Instance.CreateVolatileScheduler(10); // 10 threads + // don't forget to start the scheduler: + DirectSchedulerFactory.Instance.GetScheduler().Start(); + + + Several create methods are provided for convenience. All create methods + eventually end up calling the create method with all the parameters: + + + public void CreateScheduler(string schedulerName, string schedulerInstanceId, IThreadPool threadPool, IJobStore jobStore) + + + Here is an example of using this method: + + + // create the thread pool + SimpleThreadPool threadPool = new SimpleThreadPool(maxThreads, ThreadPriority.Normal); + threadPool.Initialize(); + // create the job store + JobStore jobStore = new RAMJobStore(); + + DirectSchedulerFactory.Instance.CreateScheduler("My Quartz Scheduler", "My Instance", threadPool, jobStore); + // don't forget to start the scheduler: + DirectSchedulerFactory.Instance.GetScheduler("My Quartz Scheduler", "My Instance").Start(); + + > + Mohammad Rezaei + James House + Marko Lahma (.NET) + + + + + + Provides a mechanism for obtaining client-usable handles to + instances. + + + + James House + Marko Lahma (.NET) + + + + Returns a client-usable handle to a . + + + + + Returns a handle to the Scheduler with the given name, if it exists. + + + + + Returns handles to all known Schedulers (made by any SchedulerFactory + within this app domain.). + + + + + Initializes a new instance of the class. + + + + + Creates an in memory job store () + The thread priority is set to Thread.NORM_PRIORITY + + The number of threads in the thread pool + + + + Creates a proxy to a remote scheduler. This scheduler can be retrieved + via . + + SchedulerException + + + + Same as , + with the addition of specifying the scheduler name and instance ID. This + scheduler can only be retrieved via . + + The name for the scheduler. + The instance ID for the scheduler. + + SchedulerException + + + + Creates a scheduler using the specified thread pool and job store. This + scheduler can be retrieved via DirectSchedulerFactory#GetScheduler() + + + The thread pool for executing jobs + + + The type of job store + + SchedulerException + if initialization failed + + + + + Same as DirectSchedulerFactory#createScheduler(ThreadPool threadPool, JobStore jobStore), + with the addition of specifying the scheduler name and instance ID. This + scheduler can only be retrieved via DirectSchedulerFactory#getScheduler(String) + + The name for the scheduler. + The instance ID for the scheduler. + The thread pool for executing jobs + The type of job store + + + + Creates a scheduler using the specified thread pool and job store and + binds it for remote access. + + The name for the scheduler. + The instance ID for the scheduler. + The thread pool for executing jobs + The type of job store + The idle wait time. You can specify "-1" for + the default value, which is currently 30000 ms. + The db failure retry interval. + + + + Creates a scheduler using the specified thread pool and job store and + binds it for remote access. + + The name for the scheduler. + The instance ID for the scheduler. + The thread pool for executing jobs + The type of job store + + The idle wait time. You can specify TimeSpan.Zero for + the default value, which is currently 30000 ms. + The db failure retry interval. + + + + Creates a scheduler using the specified thread pool and job store and + binds it for remote access. + + The name for the scheduler. + The instance ID for the scheduler. + The thread pool for executing jobs + Thread executor. + The type of job store + + The idle wait time. You can specify TimeSpan.Zero for + the default value, which is currently 30000 ms. + The db failure retry interval. + + + + Creates a scheduler using the specified thread pool and job store and + binds it for remote access. + + The name for the scheduler. + The instance ID for the scheduler. + The thread pool for executing jobs + Thread executor. + The type of job store + + The idle wait time. You can specify TimeSpan.Zero for + the default value, which is currently 30000 ms. + The db failure retry interval. + The maximum batch size of triggers, when acquiring them + The time window for which it is allowed to "pre-acquire" triggers to fire + + + + Returns a handle to the Scheduler produced by this factory. + + you must call createRemoteScheduler or createScheduler methods before + calling getScheduler() + + + + SchedulerException + + + + Returns a handle to the Scheduler with the given name, if it exists. + + + + + Gets the log. + + The log. + + + + Gets the instance. + + The instance. + + + + Returns a handle to all known Schedulers (made by any + StdSchedulerFactory instance.). + + + + + + Conveys the detail properties of a given job instance. + + + Quartz does not store an actual instance of a type, but + instead allows you to define an instance of one, through the use of a . + + s have a name and group associated with them, which + should uniquely identify them within a single . + + + s are the 'mechanism' by which s + are scheduled. Many s can point to the same , + but a single can only point to one . + + + + + + + + James House + Marko Lahma (.NET) + + + + Conveys the detail properties of a given job instance. + JobDetails are to be created/defined with . + + + Quartz does not store an actual instance of a type, but + instead allows you to define an instance of one, through the use of a . + + s have a name and group associated with them, which + should uniquely identify them within a single . + + + s are the 'mechanism' by which s + are scheduled. Many s can point to the same , + but a single can only point to one . + + + + + + + + James House + Marko Lahma (.NET) + + + + Get a that is configured to produce a + identical to this one. + + + + + The key that identifies this jobs uniquely. + + + + + Get or set the description given to the instance by its + creator (if any). + + + + + Get or sets the instance of that will be executed. + + + + + Get or set the that is associated with the . + + + + + Whether or not the should remain stored after it is + orphaned (no s point to it). + + + If not explicitly set, the default value is . + + + if the Job should remain persisted after being orphaned. + + + + + Whether the associated Job class carries the . + + + + + + Whether the associated Job class carries the . + + + + + + Set whether or not the the should re-Execute + the if a 'recovery' or 'fail-over' situation is + encountered. + + + If not explicitly set, the default value is . + + + + + + Create a with no specified name or group, and + the default settings of all the other properties. + + Note that the , and + properties must be set before the job can be + placed into a . + + + + + + Create a with the given name, default group, and + the default settings of all the other properties. + If , Scheduler.DefaultGroup will be used. + + + If name is null or empty, or the group is an empty string. + + + + + Create a with the given name, and group, and + the default settings of all the other properties. + If , Scheduler.DefaultGroup will be used. + + + If name is null or empty, or the group is an empty string. + + + + + Create a with the given name, and group, and + the given settings of all the other properties. + + The name. + if , Scheduler.DefaultGroup will be used. + Type of the job. + if set to true, job will be durable. + if set to true, job will request recovery. + + ArgumentException if name is null or empty, or the group is an empty string. + + + + + Validates whether the properties of the are + valid for submission into a . + + + + + Return a simple string representation of this object. + + + + + Creates a new object that is a copy of the current instance. + + + A new object that is a copy of this instance. + + + + + Determines whether the specified detail is equal to this instance. + + The detail to examine. + + true if the specified detail is equal; otherwise, false. + + + + + Determines whether the specified is equal to the current . + + The to compare with the current . + + if the specified is equal to the + current ; otherwise, . + + + + + Checks equality between given job detail and this instance. + + The detail to compare this instance with. + + + + + Serves as a hash function for a particular type, suitable + for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Get or sets the name of this . + + + if name is null or empty. + + + + + Get or sets the group of this . + If , will be used. + + + If the group is an empty string. + + + + + Returns the 'full name' of the in the format + "group.name". + + + + + Gets the key. + + The key. + + + + Get or set the description given to the instance by its + creator (if any). + + + May be useful for remembering/displaying the purpose of the job, though the + description has no meaning to Quartz. + + + + + Get or sets the instance of that will be executed. + + + if jobType is null or the class is not a . + + + + + Get or set the that is associated with the . + + + + + Set whether or not the the should re-Execute + the if a 'recovery' or 'fail-over' situation is + encountered. + + If not explicitly set, the default value is . + + + + + + + Whether or not the should remain stored after it is + orphaned (no s point to it). + + If not explicitly set, the default value is . + + + + if the Job should remain persisted after + being orphaned. + + + + + Whether the associated Job class carries the attribute. + + + + + Whether the associated Job class carries the attribute. + + + + + A context bundle containing handles to various environment information, that + is given to a instance as it is + executed, and to a instance after the + execution completes. + + + + The found on this object (via the + method) serves as a convenience - + it is a merge of the found on the + and the one found on the , with + the value in the latter overriding any same-named values in the former. + It is thus considered a 'best practice' that the Execute code of a Job + retrieve data from the JobDataMap found on this object + + + NOTE: Do not + expect value 'set' into this JobDataMap to somehow be set back onto a + job's own JobDataMap. + + + + s are also returned from the + + method. These are the same instances as those past into the jobs that are + currently executing within the scheduler. The exception to this is when your + application is using Quartz remotely (i.e. via remoting or WCF) - in which case you get + a clone of the s, and their references to + the and instances have been lost (a + clone of the is still available - just not a handle + to the job instance that is running). + + + + + + + + James House + Marko Lahma (.NET) + + + + A context bundle containing handles to various environment information, that + is given to a instance as it is + executed, and to a instance after the + execution completes. + + + + + Put the specified value into the context's data map with the given key. + Possibly useful for sharing data between listeners and jobs. + + NOTE: this data is volatile - it is lost after the job execution + completes, and all TriggerListeners and JobListeners have been + notified. + + + + + + + + + + Get the value with the given key from the context's data map. + + + + + + + Get a handle to the instance that fired the + . + + + + + Get a handle to the instance that fired the + . + + + + + Get a handle to the referenced by the + instance that fired the . + + + + + If the is being re-executed because of a 'recovery' + situation, this method will return . + + + + + Gets the refire count. + + The refire count. + + + + Get the convenience of this execution context. + + + + The found on this object serves as a convenience - + it is a merge of the found on the + and the one found on the , with + the value in the latter overriding any same-named values in the former. + It is thus considered a 'best practice' that the Execute code of a Job + retrieve data from the JobDataMap found on this object. + + + NOTE: Do not expect value 'set' into this JobDataMap to somehow be + set back onto a job's own JobDataMap. + + + Attempts to change the contents of this map typically result in an + illegal state. + + + + + + Get the associated with the . + + + + + Get the instance of the that was created for this + execution. + + Note: The Job instance is not available through remote scheduler + interfaces. + + + + + + The actual time the trigger fired. For instance the scheduled time may + have been 10:00:00 but the actual fire time may have been 10:00:03 if + the scheduler was too busy. + + Returns the fireTimeUtc. + + + + + The scheduled time the trigger fired for. For instance the scheduled + time may have been 10:00:00 but the actual fire time may have been + 10:00:03 if the scheduler was too busy. + + Returns the scheduledFireTimeUtc. + + + + + Gets the previous fire time. + + The previous fire time. + + + + Gets the next fire time. + + The next fire time. + + + + Get the unique Id that identifies this particular firing instance of the + trigger that triggered this job execution. It is unique to this + JobExecutionContext instance as well. + + the unique fire instance id + + + + + Returns the result (if any) that the set before its + execution completed (the type of object set as the result is entirely up + to the particular job). + + + + The result itself is meaningless to Quartz, but may be informative + to s or + s that are watching the job's + execution. + + + Set the result (if any) of the 's execution (the type of + object set as the result is entirely up to the particular job). + + + The result itself is meaningless to Quartz, but may be informative + to s or + s that are watching the job's + execution. + + + + + + The amount of time the job ran for. The returned + value will be until the job has actually completed (or thrown an + exception), and is therefore generally only useful to + s and s. + + + + + Create a JobExcecutionContext with the given context data. + + + + + Increments the refire count. + + + + + Returns a that represents the current . + + + A that represents the current . + + + + + Put the specified value into the context's data map with the given key. + Possibly useful for sharing data between listeners and jobs. + + NOTE: this data is volatile - it is lost after the job execution + completes, and all TriggerListeners and JobListeners have been + notified. + + + + + + + + + + Get the value with the given key from the context's data map. + + + + + + + Get a handle to the instance that fired the + . + + + + + Get a handle to the instance that fired the + . + + + + + Get a handle to the referenced by the + instance that fired the . + + + + + If the is being re-executed because of a 'recovery' + situation, this method will return . + + + + + Gets the refire count. + + The refire count. + + + + Get the convenience of this execution context. + + + + The found on this object serves as a convenience - + it is a merge of the found on the + and the one found on the , with + the value in the latter overriding any same-named values in the former. + It is thus considered a 'best practice' that the Execute code of a Job + retrieve data from the JobDataMap found on this object. + + + NOTE: Do not expect value 'set' into this JobDataMap to somehow be + set back onto a job's own JobDataMap. + + + Attempts to change the contents of this map typically result in an + illegal state. + + + + + + Get the associated with the . + + + + + Get the instance of the that was created for this + execution. + + Note: The Job instance is not available through remote scheduler + interfaces. + + + + + + The actual time the trigger fired. For instance the scheduled time may + have been 10:00:00 but the actual fire time may have been 10:00:03 if + the scheduler was too busy. + + Returns the fireTimeUtc. + + + + + The scheduled time the trigger fired for. For instance the scheduled + time may have been 10:00:00 but the actual fire time may have been + 10:00:03 if the scheduler was too busy. + + Returns the scheduledFireTimeUtc. + + + + + Gets the previous fire time. + + The previous fire time. + + + + Gets the next fire time. + + The next fire time. + + + + Returns the result (if any) that the set before its + execution completed (the type of object set as the result is entirely up + to the particular job). + + + + The result itself is meaningless to Quartz, but may be informative + to s or + s that are watching the job's + execution. + + + Set the result (if any) of the 's execution (the type of + object set as the result is entirely up to the particular job). + + + The result itself is meaningless to Quartz, but may be informative + to s or + s that are watching the job's + execution. + + + + + + The amount of time the job ran for. The returned + value will be until the job has actually completed (or thrown an + exception), and is therefore generally only useful to + s and s. + + + + + Returns the fire instace id. + + + + + An implementation of the interface that remotely + proxies all method calls to the equivalent call on a given + instance, via remoting or similar technology. + + + + James House + Marko Lahma (.NET) + + + + This is the main interface of a Quartz Scheduler. + + + + A maintains a registry of + s and s. Once + registered, the is responsible for executing + s when their associated s + fire (when their scheduled time arrives). + + + instances are produced by a + . A scheduler that has already been + created/initialized can be found and used through the same factory that + produced it. After a has been created, it is in + "stand-by" mode, and must have its method + called before it will fire any s. + + + s are to be created by the 'client program', by + defining a class that implements the interface. + objects are then created (also by the client) to + define a individual instances of the . + instances can then be registered with the + via the %IScheduler.ScheduleJob(JobDetail, + Trigger)% or %IScheduler.AddJob(JobDetail, bool)% method. + + + s can then be defined to fire individual + instances based on given schedules. + s are most useful for one-time firings, or + firing at an exact moment in time, with N repeats with a given delay between + them. s allow scheduling based on time of day, + day of week, day of month, and month of year. + + + s and s have a name and + group associated with them, which should uniquely identify them within a single + . The 'group' feature may be useful for creating + logical groupings or categorizations of s and + s. If you don't have need for assigning a group to a + given s of s, then you can use + the constant defined on + this interface. + + + Stored s can also be 'manually' triggered through the + use of the %IScheduler.TriggerJob(string, string)% function. + + + Client programs may also be interested in the 'listener' interfaces that are + available from Quartz. The interface provides + notifications of executions. The + interface provides notifications of + firings. The + interface provides notifications of events and + errors. Listeners can be associated with local schedulers through the + interface. + + + The setup/configuration of a instance is very + customizable. Please consult the documentation distributed with Quartz. + + + + + + + + + Marko Lahma (.NET) + + + + returns true if the given JobGroup + is paused + + + + + + + returns true if the given TriggerGroup + is paused + + + + + + + Get a object describing the settings + and capabilities of the scheduler instance. + + + Note that the data returned is an 'instantaneous' snap-shot, and that as + soon as it's returned, the meta data values may be different. + + + + + Return a list of objects that + represent all currently executing Jobs in this Scheduler instance. + + + + This method is not cluster aware. That is, it will only return Jobs + currently executing in this Scheduler instance, not across the entire + cluster. + + + Note that the list returned is an 'instantaneous' snap-shot, and that as + soon as it's returned, the true list of executing jobs may be different. + Also please read the doc associated with - + especially if you're using remoting. + + + + + + + Get the names of all known groups. + + + + + Get the names of all known groups. + + + + + Get the names of all groups that are paused. + + + + + Starts the 's threads that fire s. + When a scheduler is first created it is in "stand-by" mode, and will not + fire triggers. The scheduler can also be put into stand-by mode by + calling the method. + + + The misfire/recovery process will be started, if it is the initial call + to this method on this scheduler instance. + + + + + + + + Calls after the indicated delay. + (This call does not block). This can be useful within applications that + have initializers that create the scheduler immediately, before the + resources needed by the executing jobs have been fully initialized. + + + + + + + + Temporarily halts the 's firing of s. + + + + When is called (to bring the scheduler out of + stand-by mode), trigger misfire instructions will NOT be applied + during the execution of the method - any misfires + will be detected immediately afterward (by the 's + normal process). + + + The scheduler is not destroyed, and can be re-started at any time. + + + + + + + + Halts the 's firing of s, + and cleans up all resources associated with the Scheduler. Equivalent to + . + + + The scheduler cannot be re-started. + + + + + + Halts the 's firing of s, + and cleans up all resources associated with the Scheduler. + + + The scheduler cannot be re-started. + + + if the scheduler will not allow this method + to return until all currently executing jobs have completed. + + + + + + Add the given to the + Scheduler, and associate the given with + it. + + + If the given Trigger does not reference any , then it + will be set to reference the Job passed with it into this method. + + + + + Schedule the given with the + identified by the 's settings. + + + + + Schedule all of the given jobs with the related set of triggers. + + + If any of the given jobs or triggers already exist (or more + specifically, if the keys are not unique) and the replace + parameter is not set to true then an exception will be thrown. + + + + + Remove the indicated from the scheduler. + If the related job does not have any other triggers, and the job is + not durable, then the job will also be deleted. + + + + + Remove all of the indicated s from the scheduler. + + + If the related job does not have any other triggers, and the job is + not durable, then the job will also be deleted. + Note that while this bulk operation is likely more efficient than + invoking several + times, it may have the adverse affect of holding data locks for a + single long duration of time (rather than lots of small durations + of time). + + + + + Remove (delete) the with the + given key, and store the new given one - which must be associated + with the same job (the new trigger must have the job name & group specified) + - however, the new trigger need not have the same name as the old trigger. + + The to be replaced. + + The new to be stored. + + + if a with the given + name and group was not found and removed from the store (and the + new trigger is therefore not stored), otherwise + the first fire time of the newly scheduled trigger. + + + + + Add the given to the Scheduler - with no associated + . The will be 'dormant' until + it is scheduled with a , or + is called for it. + + + The must by definition be 'durable', if it is not, + SchedulerException will be thrown. + + + + + Delete the identified from the Scheduler - and any + associated s. + + true if the Job was found and deleted. + + + + Delete the identified jobs from the Scheduler - and any + associated s. + + + Note that while this bulk operation is likely more efficient than + invoking several + times, it may have the adverse affect of holding data locks for a + single long duration of time (rather than lots of small durations + of time). + + + true if all of the Jobs were found and deleted, false if + one or more were not deleted. + + + + + Trigger the identified + (Execute it now). + + + + + Trigger the identified (Execute it now). + + + the (possibly ) JobDataMap to be + associated with the trigger that fires the job immediately. + + + The of the to be executed. + + + + + Pause the with the given + key - by pausing all of its current s. + + + + + Pause all of the s in the + matching groups - by pausing all of their s. + + + + The Scheduler will "remember" that the groups are paused, and impose the + pause on any new jobs that are added to any of those groups until it is resumed. + + NOTE: There is a limitation that only exactly matched groups + can be remembered as paused. For example, if there are pre-existing + job in groups "aaa" and "bbb" and a matcher is given to pause + groups that start with "a" then the group "aaa" will be remembered + as paused and any subsequently added jobs in group "aaa" will be paused, + however if a job is added to group "axx" it will not be paused, + as "axx" wasn't known at the time the "group starts with a" matcher + was applied. HOWEVER, if there are pre-existing groups "aaa" and + "bbb" and a matcher is given to pause the group "axx" (with a + group equals matcher) then no jobs will be paused, but it will be + remembered that group "axx" is paused and later when a job is added + in that group, it will become paused. + + + + + + Pause the with the given key. + + + + + Pause all of the s in the groups matching. + + + + The Scheduler will "remember" all the groups paused, and impose the + pause on any new triggers that are added to any of those groups until it is resumed. + + NOTE: There is a limitation that only exactly matched groups + can be remembered as paused. For example, if there are pre-existing + triggers in groups "aaa" and "bbb" and a matcher is given to pause + groups that start with "a" then the group "aaa" will be remembered as + paused and any subsequently added triggers in that group be paused, + however if a trigger is added to group "axx" it will not be paused, + as "axx" wasn't known at the time the "group starts with a" matcher + was applied. HOWEVER, if there are pre-existing groups "aaa" and + "bbb" and a matcher is given to pause the group "axx" (with a + group equals matcher) then no triggers will be paused, but it will be + remembered that group "axx" is paused and later when a trigger is added + in that group, it will become paused. + + + + + + Resume (un-pause) the with + the given key. + + + If any of the 's s missed one + or more fire-times, then the 's misfire + instruction will be applied. + + + + + Resume (un-pause) all of the s + in matching groups. + + + If any of the s had s that + missed one or more fire-times, then the 's + misfire instruction will be applied. + + + + + + Resume (un-pause) the with the given + key. + + + If the missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + Resume (un-pause) all of the s in matching groups. + + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Pause all triggers - similar to calling + on every group, however, after using this method + must be called to clear the scheduler's state of 'remembering' that all + new triggers will be paused as they are added. + + + When is called (to un-pause), trigger misfire + instructions WILL be applied. + + + + + + + + Resume (un-pause) all triggers - similar to calling + on every group. + + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Get the keys of all the s in the matching groups. + + + + + Get all s that are associated with the + identified . + + + The returned Trigger objects will be snap-shots of the actual stored + triggers. If you wish to modify a trigger, you must re-store the + trigger afterward (e.g. see ). + + + + + Get the names of all the s in the given + groups. + + + + + Get the for the + instance with the given key . + + + The returned JobDetail object will be a snap-shot of the actual stored + JobDetail. If you wish to modify the JobDetail, you must re-store the + JobDetail afterward (e.g. see ). + + + + + Get the instance with the given key. + + + The returned Trigger object will be a snap-shot of the actual stored + trigger. If you wish to modify the trigger, you must re-store the + trigger afterward (e.g. see ). + + + + + Get the current state of the identified . + + + + + + + + + + + Add (register) the given to the Scheduler. + + Name of the calendar. + The calendar. + if set to true [replace]. + whether or not to update existing triggers that + referenced the already existing calendar so that they are 'correct' + based on the new trigger. + + + + Delete the identified from the Scheduler. + + + If removal of the Calendar would result in + s pointing to non-existent calendars, then a + will be thrown. + + Name of the calendar. + true if the Calendar was found and deleted. + + + + Get the instance with the given name. + + + + + Get the names of all registered . + + + + + Request the interruption, within this Scheduler instance, of all + currently executing instances of the identified , which + must be an implementor of the interface. + + + + If more than one instance of the identified job is currently executing, + the method will be called on + each instance. However, there is a limitation that in the case that + on one instances throws an exception, all + remaining instances (that have not yet been interrupted) will not have + their method called. + + + + If you wish to interrupt a specific instance of a job (when more than + one is executing) you can do so by calling + to obtain a handle + to the job instance, and then invoke on it + yourself. + + + This method is not cluster aware. That is, it will only interrupt + instances of the identified InterruptableJob currently executing in this + Scheduler instance, not across the entire cluster. + + + + true is at least one instance of the identified job was found and interrupted. + + + + + + + Request the interruption, within this Scheduler instance, of the + identified executing job instance, which + must be an implementor of the interface. + + + This method is not cluster aware. That is, it will only interrupt + instances of the identified InterruptableJob currently executing in this + Scheduler instance, not across the entire cluster. + + + + + + + the unique identifier of the job instance to be interrupted (see + + + true if the identified job instance was found and interrupted. + + + + Determine whether a with the given identifier already + exists within the scheduler. + + the identifier to check for + true if a Job exists with the given identifier + + + + Determine whether a with the given identifier already + exists within the scheduler. + + the identifier to check for + true if a Trigger exists with the given identifier + + + + Clears (deletes!) all scheduling data - all s, s + s. + + + + + Returns the name of the . + + + + + Returns the instance Id of the . + + + + + Returns the of the . + + + + + Reports whether the is in stand-by mode. + + + + + + + Reports whether the has been Shutdown. + + + + + Set the that will be responsible for producing + instances of classes. + + + JobFactories may be of use to those wishing to have their application + produce instances via some special mechanism, such as to + give the opportunity for dependency injection. + + + + + + Get a reference to the scheduler's , + through which listeners may be registered. + + the scheduler's + + + + + + + + Whether the scheduler has been started. + + + Note: This only reflects whether has ever + been called on this Scheduler, so it will return even + if the is currently in standby mode or has been + since shutdown. + + + + + + + + Construct a instance to proxy the given + RemoteableQuartzScheduler instance. + + + + + returns true if the given JobGroup + is paused + + + + + + + returns true if the given TriggerGroup + is paused + + + + + + + Get a object describiing the settings + and capabilities of the scheduler instance. + + Note that the data returned is an 'instantaneous' snap-shot, and that as + soon as it's returned, the meta data values may be different. + + + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Get the names of all groups that are paused. + + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Get the names of all registered . + + + + + + Calls the equivalent method on the 'proxied' . + + + + + Returns the name of the . + + + + + Returns the instance Id of the . + + + + + Returns the of the . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Set the that will be responsible for producing + instances of classes. + + JobFactories may be of use to those wishing to have their application + produce instances via some special mechanism, such as to + give the opertunity for dependency injection. + + + + + SchedulerException + + + + Whether the scheduler has been started. + + + + Note: This only reflects whether has ever + been called on this Scheduler, so it will return even + if the is currently in standby mode or has been + since shutdown. + + + + + + + + This utility calls methods reflectively on the given objects even though the + methods are likely on a proper interface (ThreadPool, JobStore, etc). The + motivation is to be tolerant of older implementations that have not been + updated for the changes in the interfaces (eg. LocalTaskExecutorThreadPool in + spring quartz helpers) + + teck + Marko Lahma (.NET) + + + + Holds references to Scheduler instances - ensuring uniqueness, and + preventing garbage collection, and allowing 'global' lookups. + + James House + Marko Lahma (.NET) + + + + Binds the specified sched. + + The sched. + + + + Removes the specified sched name. + + Name of the sched. + + + + + Lookups the specified sched name. + + Name of the sched. + + + + + Lookups all. + + + + + + Gets the singleton instance. + + The instance. + + + + Responsible for creating the instances of + to be used within the instance. + + James House + Marko Lahma (.NET) + + + + Initialize the factory, providing a handle to the + that should be made available within the and + the s within it. + + + + + Called by the to obtain instances of + . + + + + + An implementation of the interface that directly + proxies all method calls to the equivalent call on a given + instance. + + + + James House + Marko Lahma (.NET) + + + + returns true if the given JobGroup + is paused + + + + + + + returns true if the given TriggerGroup + is paused + + + + + + + Get a object describiing the settings + and capabilities of the scheduler instance. + + Note that the data returned is an 'instantaneous' snap-shot, and that as + soon as it's returned, the meta data values may be different. + + + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Construct a instance to proxy the given + instance. + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Get the names of all registered . + + + + + + Request the interruption, within this Scheduler instance, of all + currently executing instances of the identified , which + must be an implementor of the interface. + + + + If more than one instance of the identified job is currently executing, + the method will be called on + each instance. However, there is a limitation that in the case that + on one instances throws an exception, all + remaining instances (that have not yet been interrupted) will not have + their method called. + + + If you wish to interrupt a specific instance of a job (when more than + one is executing) you can do so by calling + to obtain a handle + to the job instance, and then invoke on it + yourself. + + + This method is not cluster aware. That is, it will only interrupt + instances of the identified InterruptableJob currently executing in this + Scheduler instance, not across the entire cluster. + + + true is at least one instance of the identified job was found and interrupted. + UnableToInterruptJobException if the job does not implement + + + + + + Returns the name of the . + + + + + Returns the instance Id of the . + + + + + Returns the of the . + + + + + Whether the scheduler has been started. + + + + Note: This only reflects whether has ever + been called on this Scheduler, so it will return even + if the is currently in standby mode or has been + since shutdown. + + + + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + + + + + An implementation of that + does all of it's work of creating a instance + based on the contents of a properties file. + + + + By default a properties are loaded from App.config's quartz section. + If that fails, then the file is loaded "quartz.properties". If file does not exist, + default configration located (as a embedded resource) in Quartz.dll is loaded. If you + wish to use a file other than these defaults, you must define the system + property 'quartz.properties' to point to the file you want. + + + See the sample properties that are distributed with Quartz for + information about the various settings available within the file. + + + Alternativly, you can explicitly Initialize the factory by calling one of + the methods before calling . + + + Instances of the specified , + , classes will be created + by name, and then any additional properties specified for them in the config + file will be set on the instance by calling an equivalent 'set' method. For + example if the properties file contains the property 'quartz.jobStore. + myProp = 10' then after the JobStore class has been instantiated, the property + 'MyProp' will be set with the value. Type conversion to primitive CLR types + (int, long, float, double, boolean, enum and string) are performed before calling + the property's setter method. + + + James House + Anthony Eden + Mohammad Rezaei + Marko Lahma (.NET) + + + + Returns a handle to the default Scheduler, creating it if it does not + yet exist. + + + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The props. + + + + Initialize the . + + + By default a properties file named "quartz.properties" is loaded from + the 'current working directory'. If that fails, then the + "quartz.properties" file located (as an embedded resource) in the Quartz.NET + assembly is loaded. If you wish to use a file other than these defaults, + you must define the system property 'quartz.properties' to point to + the file you want. + + + + + Creates a new name value collection and overrides its values + with system values (environment variables). + + The base properties to override. + A new NameValueCollection instance. + + + + Initialize the with + the contents of the given key value collection object. + + + + + + + + Needed while loadhelper is not constructed. + + + + + + + Returns a handle to the Scheduler produced by this factory. + + + If one of the methods has not be previously + called, then the default (no-arg) method + will be called by this method. + + + + + Returns a handle to the Scheduler with the given name, if it exists (if + it has already been instantiated). + + + + + + Returns a handle to all known Schedulers (made by any + StdSchedulerFactory instance.). + + + + + + Inspects a directory and compares whether any files' "last modified dates" + have changed since the last time it was inspected. If one or more files + have been updated (or created), the job invokes a "call-back" method on an + identified that can be found in the + . + + pl47ypus + James House + Marko Lahma (.NET) + + + + + The interface to be implemented by classes which represent a 'job' to be + performed. + + + Instances of this interface must have a + no-argument constructor. provides a mechanism for 'instance member data' + that may be required by some implementations of this interface. + + + + + + + + James House + Marko Lahma (.NET) + + + + Called by the when a + fires that is associated with the . + + + The implementation may wish to set a result object on the + JobExecutionContext before this method exits. The result itself + is meaningless to Quartz, but may be informative to + s or + s that are watching the job's + execution. + + The execution context. + + + key with which to specify the directory to be + monitored - an absolute path is recommended. + + + key with which to specify the + to be + notified when the directory contents change. + + + key with which to specify a + value that represents the minimum number of milliseconds that must have + passed since the file's last modified time in order to consider the file + new/altered. This is necessary because another process may still be + in the middle of writing to the file when the scan occurs, and the + file may therefore not yet be ready for processing. + If this parameter is not specified, a default value of 5000 (five seconds) will be used. + + + + This is the main entry point for job execution. The scheduler will call this method on the + job once it is triggered. + + The that + the job will use during execution. + + + + Inspects a file and compares whether it's "last modified date" has changed + since the last time it was inspected. If the file has been updated, the + job invokes a "call-back" method on an identified + that can be found in the + . + + James House + Marko Lahma (.NET) + + + + + JobDataMap key with which to specify the name of the file to monitor. + + + + + JobDataMap key with which to specify the + to be notified when the file contents change. + + + + + key with which to specify a long + value that represents the minimum number of milliseconds that must have + past since the file's last modified time in order to consider the file + new/altered. This is necessary because another process may still be + in the middle of writing to the file when the scan occurs, and the + file may therefore not yet be ready for processing. + + If this parameter is not specified, a default value of + 5000 (five seconds) will be used. + + + + + Initializes a new instance of the class. + + + + + Called by the when a + fires that is associated with the . + + The implementation may wish to set a result object on the + JobExecutionContext before this method exits. The result itself + is meaningless to Quartz, but may be informative to + s or + s that are watching the job's + execution. + + + The execution context. + + + + + + Gets the last modified date. + + Name of the file. + + + + + Gets the log. + + The log. + + + Interface for objects wishing to receive a 'call-back' from a + Instances should be stored in the such that the + can find it. + James House + Marko Lahma (.NET) + + + An array of objects that were updated/added + since the last scan of the directory + + + + Interface for objects wishing to receive a 'call-back' from a + . + + James House + Marko Lahma (.NET) + + + + + Ãnforms that certain file has been updated. + + Name of the file. + + + + Built in job for executing native executables in a separate process. + + + + JobDetail job = new JobDetail("dumbJob", null, typeof(Quartz.Jobs.NativeJob)); + job.JobDataMap.Put(Quartz.Jobs.NativeJob.PropertyCommand, "echo \"hi\" >> foobar.txt"); + Trigger trigger = TriggerUtils.MakeSecondlyTrigger(5); + trigger.Name = "dumbTrigger"; + sched.ScheduleJob(job, trigger); + + If PropertyWaitForProcess is true, then the integer exit value of the process + will be saved as the job execution result in the JobExecutionContext. + + Matthew Payne + James House + Steinar Overbeck Cook + Marko Lahma (.NET) + + + + Required parameter that specifies the name of the command (executable) + to be ran. + + + + + Optional parameter that specifies the parameters to be passed to the + executed command. + + + + + Optional parameter (value should be 'true' or 'false') that specifies + whether the job should wait for the execution of the native process to + complete before it completes. + + Defaults to . + + + + + Optional parameter (value should be 'true' or 'false') that specifies + whether the spawned process's stdout and stderr streams should be + consumed. If the process creates output, it is possible that it might + 'hang' if the streams are not consumed. + + Defaults to . + + + + + Optional parameter that specifies the workling directory to be used by + the executed command. + + + + + Initializes a new instance of the class. + + + + + Called by the when a + fires that is associated with the . + + The implementation may wish to set a result object on the + JobExecutionContext before this method exits. The result itself + is meaningless to Quartz, but may be informative to + s or + s that are watching the job's + execution. + + + + + + + Gets the log. + + The log. + + + + Consumes data from the given input stream until EOF and prints the data to stdout + + cooste + James House + + + + Initializes a new instance of the class. + + The enclosing instance. + The input stream. + The type. + + + + Runs this object as a separate thread, printing the contents of the input stream + supplied during instantiation, to either Console. or stderr + + + + + An implementation of Job, that does absolutely nothing - useful for system + which only wish to use s + and s, rather than writing + Jobs that perform work. + + James House + Marko Lahma (.NET) + + + + Do nothing. + + + + + A Job which sends an e-mail with the configured content to the configured + recipient. + + James House + Marko Lahma (.NET) + + + The host name of the smtp server. REQUIRED. + + + The e-mail address to send the mail to. REQUIRED. + + + The e-mail address to cc the mail to. Optional. + + + The e-mail address to claim the mail is from. REQUIRED. + + + The e-mail address the message should say to reply to. Optional. + + + The subject to place on the e-mail. REQUIRED. + + + The e-mail message body. REQUIRED. + + + + Executes the job. + + The job execution context. + + + + Holds a List of references to JobListener instances and broadcasts all + events to them (in order). + + + The broadcasting behavior of this listener to delegate listeners may be + more convenient than registering all of the listeners directly with the + Scheduler, and provides the flexibility of easily changing which listeners + get notified. + + + + + James House (jhouse AT revolition DOT net) + + + + Construct an instance with the given name. + + + (Remember to add some delegate listeners!) + + the name of this instance + + + + Construct an instance with the given name, and List of listeners. + + + + the name of this instance + the initial List of JobListeners to broadcast to. + + + + Holds a List of references to SchedulerListener instances and broadcasts all + events to them (in order). + + + This may be more convenient than registering all of the listeners + directly with the Scheduler, and provides the flexibility of easily changing + which listeners get notified. + + + + James House + Marko Lahma (.NET) + + + + Construct an instance with the given List of listeners. + + The initial List of SchedulerListeners to broadcast to. + + + + Holds a List of references to TriggerListener instances and broadcasts all + events to them (in order). + + + The broadcasting behavior of this listener to delegate listeners may be + more convenient than registering all of the listeners directly with the + Scheduler, and provides the flexibility of easily changing which listeners + get notified. + + + + + James House (jhouse AT revolition DOT net) + + + + The interface to be implemented by classes that want to be informed when a + fires. In general, applications that use a + will not have use for this mechanism. + + + + + + + James House + Marko Lahma (.NET) + + + + Called by the when a + has fired, and it's associated + is about to be executed. + + It is called before the method of this + interface. + + + The that has fired. + + The that will be passed to the 's method. + + + + + Called by the when a + has fired, and it's associated + is about to be executed. + + It is called after the method of this + interface. If the implementation vetos the execution (via + returning ), the job's execute method will not be called. + + + The that has fired. + The that will be passed to + the 's method. + Returns true if job execution should be vetoed, false otherwise. + + + + Called by the when a + has misfired. + + Consideration should be given to how much time is spent in this method, + as it will affect all triggers that are misfiring. If you have lots + of triggers misfiring at once, it could be an issue it this method + does a lot. + + + The that has misfired. + + + + Called by the when a + has fired, it's associated + has been executed, and it's method has been + called. + + The that was fired. + + The that was passed to the + 's method. + + + The result of the call on the 's method. + + + + + Get the name of the . + + + + + Construct an instance with the given name. + + + (Remember to add some delegate listeners!) + + the name of this instance + + + + Construct an instance with the given name, and List of listeners. + + + + the name of this instance + the initial List of TriggerListeners to broadcast to. + + + + Keeps a collection of mappings of which Job to trigger after the completion + of a given job. If this listener is notified of a job completing that has a + mapping, then it will then attempt to trigger the follow-up job. This + achieves "job chaining", or a "poor man's workflow". + + + + Generally an instance of this listener would be registered as a global + job listener, rather than being registered directly to a given job. + + + If for some reason there is a failure creating the trigger for the + follow-up job (which would generally only be caused by a rare serious + failure in the system, or the non-existence of the follow-up job), an error + messsage is logged, but no other action is taken. If you need more rigorous + handling of the error, consider scheduling the triggering of the flow-up + job within your job itself. + + + James House + Marko Lahma (.NET) + + + + A helpful abstract base class for implementors of . + + + + The methods in this class are empty so you only need to override the + subset for the events you care about. + + + + You are required to implement + to return the unique name of your . + + + Marko Lahma (.NET) + + + + + Initializes a new instance of the class. + + + + + Called by the when a + is about to be executed (an associated + has occured). + + This method will not be invoked if the execution of the Job was vetoed + by a . + + + + + + + + Called by the when a + was about to be executed (an associated + has occured), but a vetoed it's + execution. + + + + + + + Called by the after a + has been executed, and be for the associated 's + method has been called. + + + + + + + Get the for this class's category. + This should be used by subclasses for logging. + + + + + Get the name of the . + + + + + + Construct an instance with the given name. + + The name of this instance. + + + + Add a chain mapping - when the Job identified by the first key completes + the job identified by the second key will be triggered. + + a JobKey with the name and group of the first job + a JobKey with the name and group of the follow-up job + + + + A helpful abstract base class for implementors of + . + + + + The methods in this class are empty so you only need to override the + subset for the events + you care about. + + + + You are required to implement + to return the unique name of your . + + + Marko Lahma (.NET) + + + + + Get the for this + class's category. This should be used by subclasses for logging. + + + + + Get the name of the . + + + + + + Logs a history of all job executions (and execution vetos) via common + logging. + + + + The logged message is customizable by setting one of the following message + properties to a string that conforms to the syntax of . + + + JobToBeFiredMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Job's Name.
1StringThe Job's Group.
2DateThe current time.
3StringThe Trigger's name.
4StringThe Triggers's group.
5DateThe scheduled fire time.
6DateThe next scheduled fire time.
7IntegerThe re-fire count from the JobExecutionContext.
+ The default message text is "Job {1}.{0} fired (by trigger {4}.{3}) at: + {2, date, HH:mm:ss MM/dd/yyyy" + + + JobSuccessMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Job's Name.
1StringThe Job's Group.
2DateThe current time.
3StringThe Trigger's name.
4StringThe Triggers's group.
5DateThe scheduled fire time.
6DateThe next scheduled fire time.
7IntegerThe re-fire count from the JobExecutionContext.
8ObjectThe string value (toString() having been called) of the result (if any) + that the Job set on the JobExecutionContext, with on it. "NULL" if no + result was set.
+ The default message text is "Job {1}.{0} execution complete at {2, date, + HH:mm:ss MM/dd/yyyy} and reports: {8" + + + JobFailedMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Job's Name.
1StringThe Job's Group.
2DateThe current time.
3StringThe Trigger's name.
4StringThe Triggers's group.
5DateThe scheduled fire time.
6DateThe next scheduled fire time.
7IntegerThe re-fire count from the JobExecutionContext.
8StringThe message from the thrown JobExecution Exception. +
+ The default message text is "Job {1}.{0} execution failed at {2, date, + HH:mm:ss MM/dd/yyyy} and reports: {8" + + + JobWasVetoedMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Job's Name.
1StringThe Job's Group.
2DateThe current time.
3StringThe Trigger's name.
4StringThe Triggers's group.
5DateThe scheduled fire time.
6DateThe next scheduled fire time.
7IntegerThe re-fire count from the JobExecutionContext.
+ The default message text is "Job {1}.{0} was vetoed. It was to be fired + (by trigger {4}.{3}) at: {2, date, HH:mm:ss MM/dd/yyyy" + + + Marko Lahma (.NET) + + + + Provides an interface for a class to become a "plugin" to Quartz. + + + Plugins can do virtually anything you wish, though the most interesting ones + will obviously interact with the scheduler in some way - either actively: by + invoking actions on the scheduler, or passively: by being a , + , and/or . + + If you use to + Initialize your Scheduler, it can also create and Initialize your plugins - + look at the configuration docs for details. + + + If you need direct access your plugin, you can have it explicitly put a + reference to itself in the 's + as part of its + method. + + + James House + Marko Lahma (.NET) + + + + Called during creation of the in order to give + the a chance to Initialize. + + + At this point, the Scheduler's is not yet + + If you need direct access your plugin, you can have it explicitly put a + reference to itself in the 's + as part of its + method. + + + + The name by which the plugin is identified. + + + The scheduler to which the plugin is registered. + + + + + Called when the associated is started, in order + to let the plug-in know it can now make calls into the scheduler if it + needs to. + + + + + Called in order to inform the that it + should free up all of it's resources because the scheduler is shutting + down. + + + + + Called during creation of the in order to give + the a chance to Initialize. + + + + + Called when the associated is started, in order + to let the plug-in know it can now make calls into the scheduler if it + needs to. + + + + + Called in order to inform the that it + should free up all of it's resources because the scheduler is shutting + down. + + + + + Called by the when a is + about to be executed (an associated has occurred). + + This method will not be invoked if the execution of the Job was vetoed by a + . + + + + + + + Called by the after a + has been executed, and be for the associated 's + method has been called. + + + + + + + Called by the when a + was about to be executed (an associated + has occured), but a vetoed it's + execution. + + + + + + + Logger instance to use. Defaults to common logging. + + + + + Get or sets the message that is logged when a Job successfully completes its + execution. + + + + + Get or sets the message that is logged when a Job fails its + execution. + + + + + Gets or sets the message that is logged when a Job is about to Execute. + + + + + Gets or sets the message that is logged when a Job execution is vetoed by a + trigger listener. + + + + + Get the name of the . + + + + + + Logs a history of all trigger firings via the Jakarta Commons-Logging + framework. + + + + The logged message is customizable by setting one of the following message + properties to a string that conforms to the syntax of . + + + + TriggerFiredMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Trigger's Name.
1StringThe Trigger's Group.
2DateThe scheduled fire time.
3DateThe next scheduled fire time.
4DateThe actual fire time.
5StringThe Job's name.
6StringThe Job's group.
7IntegerThe re-fire count from the JobExecutionContext.
+ + The default message text is "Trigger {1}.{0} fired job {6}.{5} at: {4, + date, HH:mm:ss MM/dd/yyyy" + + + + TriggerMisfiredMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Trigger's Name.
1StringThe Trigger's Group.
2DateThe scheduled fire time.
3DateThe next scheduled fire time.
4DateThe actual fire time. (the time the misfire was detected/handled)
5StringThe Job's name.
6StringThe Job's group.
+ + The default message text is "Trigger {1}.{0} misfired job {6}.{5} at: + {4, date, HH:mm:ss MM/dd/yyyy}. Should have fired at: {3, date, HH:mm:ss + MM/dd/yyyy" + + + + TriggerCompleteMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Trigger's Name.
1StringThe Trigger's Group.
2DateThe scheduled fire time.
3DateThe next scheduled fire time.
4DateThe job completion time.
5StringThe Job's name.
6StringThe Job's group.
7IntegerThe re-fire count from the JobExecutionContext.
8IntegerThe trigger's resulting instruction code.
9StringA human-readable translation of the trigger's resulting instruction + code.
+ + The default message text is "Trigger {1}.{0} completed firing job + {6}.{5} at {4, date, HH:mm:ss MM/dd/yyyy} with resulting trigger instruction + code: {9" + + + James House + Marko Lahma (.NET) + + + + Called during creation of the in order to give + the a chance to Initialize. + + + + + Called when the associated is started, in order + to let the plug-in know it can now make calls into the scheduler if it + needs to. + + + + + Called in order to inform the that it + should free up all of it's resources because the scheduler is shutting + down. + + + + + Called by the when a + has fired, and it's associated + is about to be executed. + + It is called before the method of this + interface. + + + The that has fired. + The that will be passed to the 's method. + + + + Called by the when a + has misfired. + + Consideration should be given to how much time is spent in this method, + as it will affect all triggers that are misfiring. If you have lots + of triggers misfiring at once, it could be an issue it this method + does a lot. + + + The that has misfired. + + + + Called by the when a + has fired, it's associated + has been executed, and it's method has been + called. + + The that was fired. + The that was passed to the + 's method. + The result of the call on the 's method. + + + + Called by the when a + has fired, and it's associated + is about to be executed. + + It is called after the method of this + interface. + + + The that has fired. + The that will be passed to + the 's method. + + + + + Logger instance to use. Defaults to common logging. + + + + + Get or set the message that is printed upon the completion of a trigger's + firing. + + + + + Get or set the message that is printed upon a trigger's firing. + + + + + Get or set the message that is printed upon a trigger's mis-firing. + + + + + Get the name of the . + + + + + + This plugin catches the event of the VM terminating (such as upon a CRTL-C) + and tells the scheuler to Shutdown. + + + James House + Marko Lahma (.NET) + + + + Called during creation of the in order to give + the a chance to Initialize. + + + + + Called when the associated is started, in order + to let the plug-in know it can now make calls into the scheduler if it + needs to. + + + + + Called in order to inform the that it + should free up all of it's resources because the scheduler is shutting + down. + + + + + Determine whether or not the plug-in is configured to cause a clean + Shutdown of the scheduler. + + The default value is . + + + + + + + This plugin loads XML file(s) to add jobs and schedule them with triggers + as the scheduler is initialized, and can optionally periodically scan the + file for changes. + + + The periodically scanning of files for changes is not currently supported in a + clustered environment. + + James House + Pierre Awaragi + + + + Initializes a new instance of the class. + + + + + + + + + + + Called during creation of the in order to give + the a chance to initialize. + + The name. + The scheduler. + SchedulerConfigException + + + + Called when the associated is started, in order + to let the plug-in know it can now make calls into the scheduler if it + needs to. + + + + + Helper method for generating unique job/trigger name for the + file scanning jobs (one per FileJob). The unique names are saved + in jobTriggerNameSet. + + + + + + + Called in order to inform the that it + should free up all of it's resources because the scheduler is shutting + down. + + + + + Gets the log. + + The log. + + + + Comma separated list of file names (with paths) to the XML files that should be read. + + + + + The interval at which to scan for changes to the file. + If the file has been changed, it is re-loaded and parsed. The default + value for the interval is 0, which disables scanning. + + + + + Whether or not initialization of the plugin should fail (throw an + exception) if the file cannot be found. Default is . + + + + + Information about a file that should be processed by . + + + + + Default object serialization strategy that uses + under the hood. + + Marko Lahma + + + + Interface for object serializers. + + Marko Lahma + + + + + Serializes given object as bytes + that can be stored to permanent stores. + + Object to serialize, always non-null. + + + + Deserializes object from byte array presentation. + + Data to deserialize object from, always non-null and non-empty. + + + + Serializes given object as bytes + that can be stored to permanent stores. + + Object to serialize. + + + + Deserializes object from byte array presentation. + + Data to deserialize object from. + + + + that names the scheduler instance using + just the machine hostname. + + + This class is useful when you know that your scheduler instance will be the + only one running on a particular machine. Each time the scheduler is + restarted, it will get the same instance id as long as the machine is not + renamed. + + Marko Lahma (.NET) + + + + + + An IInstanceIdGenerator is responsible for generating the clusterwide unique + instance id for a node. + + + This interface may be of use to those wishing to have specific control over + the mechanism by which the instances in their + application are named. + + + Marko Lahma (.NET) + + + + Generate the instance id for a + + The clusterwide unique instance id. + + + + + Generate the instance id for a + + The clusterwide unique instance id. + + + + A JobFactory that instantiates the Job instance (using the default no-arg + constructor, or more specifically: ), and + then attempts to set all values from the and + the 's merged onto + properties of the job. + + + Set the WarnIfPropertyNotFound property to true if you'd like noisy logging in + the case of values in the not mapping to properties on your job + class. This may be useful for troubleshooting typos of property names, etc. + but very noisy if you regularly (and purposely) have extra things in your + . + Also of possible interest is the ThrowIfPropertyNotFound property which + will throw exceptions on unmatched JobDataMap keys. + + + + + + + + James Houser + Marko Lahma (.NET) + + + + The default JobFactory used by Quartz - simply calls + on the job class. + + + + James House + Marko Lahma (.NET) + + + + A JobFactory is responsible for producing instances of + classes. + + + This interface may be of use to those wishing to have their application + produce instances via some special mechanism, such as to + give the opertunity for dependency injection. + + + + + James House + Marko Lahma (.NET) + + + + Called by the scheduler at the time of the trigger firing, in order to + produce a instance on which to call Execute. + + + It should be extremely rare for this method to throw an exception - + basically only the the case where there is no way at all to instantiate + and prepare the Job for execution. When the exception is thrown, the + Scheduler will move all triggers associated with the Job into the + state, which will require human + intervention (e.g. an application restart after fixing whatever + configuration problem led to the issue wih instantiating the Job. + + + The TriggerFiredBundle from which the + and other info relating to the trigger firing can be obtained. + + a handle to the scheduler that is about to execute the job + SchedulerException if there is a problem instantiating the Job. + the newly instantiated Job + + + + + Called by the scheduler at the time of the trigger firing, in order to + produce a instance on which to call Execute. + + + It should be extremely rare for this method to throw an exception - + basically only the the case where there is no way at all to instantiate + and prepare the Job for execution. When the exception is thrown, the + Scheduler will move all triggers associated with the Job into the + state, which will require human + intervention (e.g. an application restart after fixing whatever + configuration problem led to the issue wih instantiating the Job. + + The TriggerFiredBundle from which the + and other info relating to the trigger firing can be obtained. + + the newly instantiated Job + SchedulerException if there is a problem instantiating the Job. + + + + Called by the scheduler at the time of the trigger firing, in order to + produce a instance on which to call Execute. + + + + It should be extremely rare for this method to throw an exception - + basically only the the case where there is no way at all to instantiate + and prepare the Job for execution. When the exception is thrown, the + Scheduler will move all triggers associated with the Job into the + state, which will require human + intervention (e.g. an application restart after fixing whatever + configuration problem led to the issue wih instantiating the Job. + + + The TriggerFiredBundle from which the + and other info relating to the trigger firing can be obtained. + + the newly instantiated Job + SchedulerException if there is a problem instantiating the Job. + + + + Sets the object properties. + + The object to set properties to. + The data to set. + + + + Whether the JobInstantiation should fail and throw and exception if + a key (name) and value (type) found in the JobDataMap does not + correspond to a proptery setter on the Job class. + + + + + Get or set whether a warning should be logged if + a key (name) and value (type) found in the JobDataMap does not + correspond to a proptery setter on the Job class. + + + + + This class implements a that + utilizes RAM as its storage device. + + As you should know, the ramification of this is that access is extrememly + fast, but the data is completely volatile - therefore this + should not be used if true persistence between program shutdowns is + required. + + + James House + Sharada Jambula + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Gets the fired trigger record id. + + The fired trigger record id. + + + + Called by the QuartzScheduler before the is + used, in order to give the it a chance to Initialize. + + + + + Called by the QuartzScheduler to inform the that + the scheduler has started. + + + + + Called by the QuartzScheduler to inform the JobStore that + the scheduler has been paused. + + + + + Called by the QuartzScheduler to inform the JobStore that + the scheduler has resumed after being paused. + + + + + Called by the QuartzScheduler to inform the that + it should free up all of it's resources because the scheduler is + shutting down. + + + + + Clears (deletes!) all scheduling data - all s, s + s. + + + + + Store the given and . + + The to be stored. + The to be stored. + + + + Returns true if the given job group is paused. + + Job group name + + + + + returns true if the given TriggerGroup is paused. + + + + + + + Store the given . + + The to be stored. + If , any existing in the + with the same name and group should be + over-written. + + + + Remove (delete) the with the given + name, and any s that reference + it. + + + if a with the given name and + group was found and removed from the store. + + + + + Remove (delete) the with the + given name. + + + if a with the given + name and group was found and removed from the store. + + + + + Store the given . + + The to be stored. + If , any existing in + the with the same name and group should + be over-written. + + + + Remove (delete) the with the + given name. + + + + if a with the given + name and group was found and removed from the store. + + The to be removed. + Whether to delete orpahaned job details from scheduler if job becomes orphaned from removing the trigger. + + + + Replaces the trigger. + + The of the to be replaced. + The new trigger. + + + + + Retrieve the for the given + . + + + The desired , or null if there is no match. + + + + + Retrieve the given . + + + The desired , or null if there is no match. + + + + + Determine whether a with the given identifier already + exists within the scheduler. + + the identifier to check for + true if a Job exists with the given identifier + + + + Determine whether a with the given identifier already + exists within the scheduler. + + triggerKey the identifier to check for + true if a Trigger exists with the given identifier + + + + Get the current state of the identified . + + + + + + + + + + + Store the given . + + The name. + The to be stored. + If , any existing + in the with the same name and group + should be over-written. + If , any s existing + in the that reference an existing + Calendar with the same name with have their next fire time + re-computed with the new . + + + + Remove (delete) the with the + given name. + + If removal of the would result in + s pointing to non-existent calendars, then a + will be thrown. + + The name of the to be removed. + + if a with the given name + was found and removed from the store. + + + + + Retrieve the given . + + The name of the to be retrieved. + + The desired , or null if there is no match. + + + + + Get the number of s that are + stored in the . + + + + + Get the number of s that are + stored in the . + + + + + Get the number of s that are + stored in the . + + + + + Get the names of all of the s that + match the given group matcher. + + + + + Get the names of all of the s + in the . + + If there are no ICalendars in the given group name, the result should be + a zero-length array (not ). + + + + + + Get the names of all of the s + that have the given group name. + + + + + Get the names of all of the + groups. + + + + + Get the names of all of the groups. + + + + + Get all of the Triggers that are associated to the given Job. + + If there are no matches, a zero-length array should be returned. + + + + + + Gets the trigger wrappers for job. + + + + + + Gets the trigger wrappers for calendar. + + Name of the cal. + + + + + Pause the with the given name. + + + + + Pause all of the s in the given group. + + The JobStore should "remember" that the group is paused, and impose the + pause on any new triggers that are added to the group while the group is + paused. + + + + + + Pause the with the given + name - by pausing all of its current s. + + + + + Pause all of the s in the + given group - by pausing all of their s. + + The JobStore should "remember" that the group is paused, and impose the + pause on any new jobs that are added to the group while the group is + paused. + + + + + + Resume (un-pause) the with the given key. + + + If the missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + Resume (un-pause) all of the s in the + given group. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Resume (un-pause) the with + the given name. + + If any of the 's s missed one + or more fire-times, then the 's misfire + instruction will be applied. + + + + + + Resume (un-pause) all of the s + in the given group. + + If any of the s had s that + missed one or more fire-times, then the 's + misfire instruction will be applied. + + + + + + Pause all triggers - equivalent of calling + on every group. + + When is called (to un-pause), trigger misfire + instructions WILL be applied. + + + + + + + Resume (un-pause) all triggers - equivalent of calling + on every trigger group and setting all job groups unpaused />. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + + Applies the misfire. + + The trigger wrapper. + + + + + Get a handle to the next trigger to be fired, and mark it as 'reserved' + by the calling scheduler. + + + + + + Inform the that the scheduler no longer plans to + fire the given , that it had previously acquired + (reserved). + + + + + Inform the that the scheduler is now firing the + given (executing its associated ), + that it had previously acquired (reserved). + + + + + Inform the that the scheduler has completed the + firing of the given (and the execution its + associated ), and that the + in the given should be updated if the + is stateful. + + + + + Sets the state of all triggers of job to specified state. + + + + + Peeks the triggers. + + + + + + + + + The time span by which a trigger must have missed its + next-fire-time, in order for it to be considered "misfired" and thus + have its misfire instruction applied. + + + + + Returns whether this instance supports persistence. + + + + + + + Inform the of the Scheduler instance's Id, + prior to initialize being invoked. + + + + + Inform the of the Scheduler instance's name, + prior to initialize being invoked. + + + + + Comparer for trigger wrappers. + + + + + Indicates whether the current object is equal to another object of the same type. + + + true if the current object is equal to the parameter; otherwise, false. + + An object to compare with this object. + + + + Serves as a hash function for a particular type. + + + A hash code for the current . + + 2 + + + + Possible internal trigger states + in RAMJobStore + + + + + Waiting + + + + + Acquired + + + + + Executing + + + + + Complete + + + + + Paused + + + + + Blocked + + + + + Paused and Blocked + + + + + Error + + + + + Helper wrapper class + + + + + The key used + + + + + Job's key + + + + + The trigger + + + + + Current state + + + + + Determines whether the specified is equal to the current . + + The to compare with the current . + + true if the specified is equal to the current ; otherwise, false. + + + + + Serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Scheduler exporter that exports scheduler to remoting context. + + Marko Lahma + + + + Service interface for scheduler exporters. + + Marko Lahma + + + + Binds (exports) scheduler to external context. + + + + + + Unbinds scheduler from external context. + + + + + + Registers remoting channel if needed. This is determined + by checking whether there is a positive value for port. + + + + + Gets or sets the port used for remoting. + + + + + Gets or sets the name to use when exporting + scheduler to remoting context. + + + + + Gets or sets the name to use when binding to + tcp channel. + + + + + Sets the channel type when registering remoting. + + + + + + Sets the used when + exporting to remoting context. Defaults to + . + + + + + A implementation that creates + connection to remote scheduler using remoting. + + + + + Client Proxy to a IRemotableQuartzScheduler + + + + + Returns a client proxy to a remote . + + + + + Returns a client proxy to a remote . + + + + + Gets or sets the remote scheduler address. + + The remote scheduler address. + + + + The default InstanceIdGenerator used by Quartz when instance id is to be + automatically generated. Instance id is of the form HOSTNAME + CURRENT_TIME. + + Marko Lahma (.NET) + + + + + + Generate the instance id for a + + The clusterwide unique instance id. + + + + This is class is a simple implementation of a thread pool, based on the + interface. + + + objects are sent to the pool with the + method, which blocks until a becomes available. + + The pool has a fixed number of s, and does not grow or + shrink based on demand. + + James House + Juergen Donnerstag + Marko Lahma (.NET) + + + + The interface to be implemented by classes that want to provide a thread + pool for the 's use. + + + implementation instances should ideally be made + for the sole use of Quartz. Most importantly, when the method + returns a value of 1 or greater, + there must still be at least one available thread in the pool when the + method is called a few moments (or + many moments) later. If this assumption does not hold true, it may + result in extra JobStore queries and updates, and if clustering features + are being used, it may result in greater imballance of load. + + + James House + Marko Lahma (.NET) + + + + Execute the given in the next + available . + + + The implementation of this interface should not throw exceptions unless + there is a serious problem (i.e. a serious misconfiguration). If there + are no available threads, rather it should either queue the Runnable, or + block until a thread is available, depending on the desired strategy. + + + + + Determines the number of threads that are currently available in in + the pool. Useful for determining the number of times + can be called before returning + false. + + + The implementation of this method should block until there is at + least one available thread. + + the number of currently available threads + + + + Must be called before the is + used, in order to give the it a chance to Initialize. + + + Typically called by the . + + + + + Called by the QuartzScheduler to inform the + that it should free up all of it's resources because the scheduler is + shutting down. + + + + + Get the current number of threads in the . + + + + + Inform the of the Scheduler instance's Id, + prior to initialize being invoked. + + + + + Inform the of the Scheduler instance's name, + prior to initialize being invoked. + + + + + Create a new (unconfigured) . + + + + + Create a new with the specified number + of s that have the given priority. + + + the number of worker s in the pool, must + be > 0. + + + the thread priority for the worker threads. + + + + + + Called by the QuartzScheduler before the is + used, in order to give the it a chance to Initialize. + + + + + Terminate any worker threads in this thread group. + Jobs currently in progress will complete. + + + + + Run the given object in the next available + . If while waiting the thread pool is asked to + shut down, the Runnable is executed immediately within a new additional + thread. + + The to be added. + + + + Creates the worker threads. + + The thread count. + + + + + Terminate any worker threads in this thread group. + Jobs currently in progress will complete. + + + + + Gets or sets the number of worker threads in the pool. + Set has no effect after has been called. + + + + + Get or set the thread priority of worker threads in the pool. + Set operation has no effect after has been called. + + + + + Gets or sets the thread name prefix. + + The thread name prefix. + + + + Gets or sets the value of makeThreadsDaemons. + + + + + Gets the size of the pool. + + The size of the pool. + + + + Inform the of the Scheduler instance's Id, + prior to initialize being invoked. + + + + + Inform the of the Scheduler instance's name, + prior to initialize being invoked. + + + + + A Worker loops, waiting to Execute tasks. + + + + + Create a worker thread and start it. Waiting for the next Runnable, + executing it, and waiting for the next Runnable, until the Shutdown + flag is set. + + + + + Create a worker thread, start it, Execute the runnable and terminate + the thread (one time execution). + + + + + Signal the thread that it should terminate. + + + + + Loop, executing targets as they are received. + + + + + A that simply calls . + + + James House + Marko Lahma (.NET) + + + + Called to give the ClassLoadHelper a chance to Initialize itself, + including the oportunity to "steal" the class loader off of the calling + thread, which is the thread that is initializing Quartz. + + + + Return the class with the given name. + + + + Finds a resource with a given name. This method returns null if no + resource with this name is found. + + name of the desired resource + + a Uri object + + + + Finds a resource with a given name. This method returns null if no + resource with this name is found. + + name of the desired resource + + a Stream object + + + + + InstanceIdGenerator that will use a to configure the scheduler. + If no value set for the property, a is thrown. + Alex Snaps + + + + + System property to read the instanceId from. + + + + + Returns the cluster wide value for this scheduler instance's id, based on a system property. + + + + + A string of text to prepend (add to the beginning) to the instanceId found in the system property. + + + + + A string of text to postpend (add to the end) to the instanceId found in the system property. + + + + + The name of the system property from which to obtain the instanceId. + + + Defaults to . + + + + + This is class is a simple implementation of a zero size thread pool, based on the + interface. + + + The pool has zero s and does not grow or shrink based on demand. + Which means it is obviously not useful for most scenarios. When it may be useful + is to prevent creating any worker threads at all - which may be desirable for + the sole purpose of preserving system resources in the case where the scheduler + instance only exists in order to schedule jobs, but which will never execute + jobs (e.g. will never have Start() called on it). + + Wayne Fay + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Called by the QuartzScheduler before the is + used, in order to give the it a chance to Initialize. + + + + + Shutdowns this instance. + + + + + Called by the QuartzScheduler to inform the + that it should free up all of it's resources because the scheduler is + shutting down. + + + + + + Execute the given in the next + available . + + + + + The implementation of this interface should not throw exceptions unless + there is a serious problem (i.e. a serious misconfiguration). If there + are no available threads, rather it should either queue the Runnable, or + block until a thread is available, depending on the desired strategy. + + + + + Determines the number of threads that are currently available in in + the pool. Useful for determining the number of times + can be called before returning + false. + + + the number of currently available threads + + + The implementation of this method should block until there is at + least one available thread. + + + + + Gets the log. + + The log. + + + + Gets the size of the pool. + + The size of the pool. + + + + Inform the of the Scheduler instance's Id, + prior to initialize being invoked. + + + + + Inform the of the Scheduler instance's name, + prior to initialize being invoked. + + + + + A simple class (structure) used for returning execution-time data from the + JobStore to the . + + + James House + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + The job. + The trigger. + The calendar. + if set to true [job is recovering]. + The fire time. + The scheduled fire time. + The previous fire time. + The next fire time. + + + + Gets the job detail. + + The job detail. + + + + Gets the trigger. + + The trigger. + + + + Gets the calendar. + + The calendar. + + + + Gets a value indicating whether this is recovering. + + true if recovering; otherwise, false. + + + + Returns the UTC fire time. + + + + + Gets the next UTC fire time. + + The next fire time. + Returns the nextFireTimeUtc. + + + + Gets the previous UTC fire time. + + The previous fire time. + Returns the previous fire time. + + + + Returns the scheduled UTC fire time. + + + + + Result holder for trigger firing event. + + + + + Constructor. + + + + + + Constructor. + + + + + Bundle. + + + + + Possible exception. + + + + + Extension methods for . + + + + + Tries to read value and returns the value if successfully read. Otherwise return default value + for value's type. + + + + + + + + + + Extension methods for simplified access. + + + + + Returns string from given column name, or null if DbNull. + + + + + Returns int from given column name. + + + + + Returns long from given column name. + + + + + Returns long from given column name, or null if DbNull. + + + + + Returns decimal from given column name. + + + + + Manages a collection of IDbProviders, and provides transparent access + to their database. + + + James House + Sharada Jambula + Mohammad Rezaei + Marko Lahma (.NET) + + + + Private constructor + + + + + Adds the connection provider. + + Name of the data source. + The provider. + + + + Get a database connection from the DataSource with the given name. + + a database connection + + + + Shuts down database connections from the DataSource with the given name, + if applicable for the underlying provider. + + a database connection + + + + Gets the db provider. + + Name of the ds. + + + + + Get the class instance. + + an instance of this class + + + + + An implementation of that wraps another + and flags itself 'dirty' when it is modified. + + James House + Marko Lahma (.NET) + + + + Create a DirtyFlagMap that 'wraps' a . + + + + + Create a DirtyFlagMap that 'wraps' a that has the + given initial capacity. + + + + + Serialization constructor. + + + + + + + Creates a new object that is a copy of the current instance. + + + A new object that is a copy of this instance. + + + + + When implemented by a class, removes all elements from the . + + + The is read-only. + + + + + When implemented by a class, determines whether the contains an element with the specified key. + + The key to locate in the . + + if the contains an element with the key; otherwise, . + + + is . + + + + When implemented by a class, removes the element with the + specified key from the . + + The key of the element to remove. + + is . + + The is read-only. + -or- + The has a fixed size. + + + + + When implemented by a class, returns an + for the . + + + An for the . + + + + + When implemented by a class, adds an element with the provided key and value to the . + + The to use as the key of the element to add. + The to use as the value of the element to add. + is . + + An element with the same key already exists in the . + + + The is read-only. + -or- + The has a fixed size. + + + + + When implemented by a class, copies the elements of + the to an , starting at a particular index. + + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + The zero-based index in at which copying begins. + + is . + + is less than zero. + + + is multidimensional. + -or- + + is equal to or greater than the length of . + -or- + The number of elements in the source is greater than the available space from to the end of the destination . + + The type of the source cannot be cast automatically to the type of the destination . + + + + Clear the 'dirty' flag (set dirty flag to ). + + + + + Determines whether the specified obj contains value. + + The obj. + + true if the specified obj contains value; otherwise, false. + + + + + Gets the entries as a set. + + + + + + Determines whether the specified is equal to the current . + + The to compare with the current . + + if the specified is equal to the + current ; otherwise, . + + + + + Serves as a hash function for a particular type, suitable + for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Gets keyset for this map. + + + + + + Puts the value behind a specified key. + + The key. + The val. + + + + + Puts all. + + The t. + + + + Determine whether the is flagged dirty. + + + + + Get a direct handle to the underlying Map. + + + + + Gets a value indicating whether this instance is empty. + + true if this instance is empty; otherwise, false. + + + + Gets or sets the with the specified key. + + + + + + When implemented by a class, gets the number of + elements contained in the . + + + + + + When implemented by a class, gets an containing the values in the . + + + + + + When implemented by a class, gets an containing the keys of the . + + + + + + When implemented by a class, gets a value indicating whether the + is read-only. + + + + + + When implemented by a class, gets a value indicating whether the + has a fixed size. + + + + + + When implemented by a class, gets an object that + can be used to synchronize access to the . + + + + + + When implemented by a class, gets a value + indicating whether access to the is synchronized + (thread-safe). + + + + + + Utility class for file handling related things. + + Marko Lahma + + + + Resolves file to actual file if for example relative '~' used. + + File name to check + Expanded file name or actual no resolving was done. + + + + Object representing a job or trigger key. + + Jeffrey Wescott + Marko Lahma (.NET) + + + + The default group for scheduling entities, with the value "DEFAULT". + + + + + Construct a new key with the given name and group. + + the name + the group + + + + Return the string representation of the key. The format will be: + <group>.<name>. + + + + the string representation of the key + + + + + Get the name portion of the key. + + the name + + + + + Get the group portion of the key. + + + + the group + + + + + Wrapper class to access thread local data. + Data is either accessed from thread or HTTP Context's + data if HTTP Context is avaiable. + + Marko Lahma .NET + + + + Retrieves an object with the specified name. + + The name of the item. + The object in the call context associated with the specified name or null if no object has been stored previously + + + + Stores a given object and associates it with the specified name. + + The name with which to associate the new item. + The object to store in the call context. + + + + Empties a data slot with the specified name. + + The name of the data slot to empty. + + + + Generic extension methods for objects. + + + + + Creates a deep copy of object by serializing to memory stream. + + + + + + Utility methods that are used to convert objects from one type into another. + + Aleksandar Seovic + Marko Lahma + + + + Convert the value to the required (if necessary from a string). + + The proposed change value. + + The we must convert to. + + The new value, possibly the result of type conversion. + + + + Determines whether value is assignable to required type. + + The value to check. + Type of the required. + + true if value can be assigned as given type; otherwise, false. + + + + + Instantiates an instance of the type specified. + + + + + + Sets the object properties using reflection. + + + + + Sets the object properties using reflection. + + The object to set values to. + The properties to set to object. + + + + This is an utility class used to parse the properties. + + James House + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + The props. + + + + Gets the string property. + + The name. + + + + + Gets the string property. + + The name. + The default value. + + + + + Gets the string array property. + + The name. + + + + + Gets the string array property. + + The name. + The default value. + + + + + Gets the boolean property. + + The name. + + + + + Gets the boolean property. + + The name. + if set to true [defaultValue]. + + + + + Gets the byte property. + + The name. + + + + + Gets the byte property. + + The name. + The default value. + + + + + Gets the char property. + + The name. + + + + + Gets the char property. + + The name. + The default value. + + + + + Gets the double property. + + The name. + + + + + Gets the double property. + + The name. + The default value. + + + + + Gets the float property. + + The name. + + + + + Gets the float property. + + The name. + The default value. + + + + + Gets the int property. + + The name. + + + + + Gets the int property. + + The name. + The default value. + + + + + Gets the int array property. + + The name. + + + + + Gets the int array property. + + The name. + The default value. + + + + + Gets the long property. + + The name. + + + + + Gets the long property. + + The name. + The def. + + + + + Gets the TimeSpan property. + + The name. + The def. + + + + + Gets the short property. + + The name. + + + + + Gets the short property. + + The name. + The default value. + + + + + Gets the property groups. + + The prefix. + + + + + Gets the property group. + + The prefix. + + + + + Gets the property group. + + The prefix. + if set to true [strip prefix]. + + + + + Get all properties that start with the given prefix. + + The prefix for which to search. If it does not end in a "." then one will be added to it for search purposes. + Whether to strip off the given in the result's keys. + Optional array of fully qualified prefixes to exclude. For example if is "a.b.c", then might be "a.b.c.ignore". + Group of that start with the given prefix, optionally have that prefix removed, and do not include properties that start with one of the given excluded prefixes. + + + + Reads the properties from assembly (embedded resource). + + The file name to read resources from. + + + + + Reads the properties from file system. + + The file name to read resources from. + + + + + Gets the underlying properties. + + The underlying properties. + + + + Extension methods for . + + + + + Allows null-safe trimming of string. + + + + + + + Trims string and if resulting string is empty, null is returned. + + + + + + + An implementation of that wraps another + and flags itself 'dirty' when it is modified, enforces that all keys are + strings. + + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The initial capacity. + + + + Serialization constructor. + + + + + + + Determines whether the specified is equal to the current . + + The to compare with the current . + + if the specified is equal to the + current ; otherwise, . + + + + + Serves as a hash function for a particular type, suitable + for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Gets the keys. + + + + + + Adds the name-value pairs in the given to the . + + All keys must be s, and all values must be serializable. + + + + + + Adds the given value to the 's + data map. + + + + + Adds the given value to the 's + data map. + + + + + Adds the given value to the 's + data map. + + + + + Adds the given value to the 's + data map. + + + + + Adds the given value to the 's + data map. + + + + + Adds the given value to the 's + data map. + + + + + Adds the given value to the 's + data map. + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Reports JobSchedulingDataProcessor validation exceptions. + + Chris Bonham + Marko Lahma (.NET) + + + + Constructor for ValidationException. + + + + + Constructor for ValidationException. + + exception message. + + + + Constructor for ValidationException. + + collection of validation exceptions. + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + Gets the validation exceptions. + + The validation exceptions. + + + + Returns the detail message string. + + + + + Parses an XML file that declares Jobs and their schedules (Triggers). + + + + The xml document must conform to the format defined in "job_scheduling_data_2_0.xsd" + + + + After creating an instance of this class, you should call one of the + functions, after which you may call the ScheduledJobs() + function to get a handle to the defined Jobs and Triggers, which can then be + scheduled with the . Alternatively, you could call + the function to do all of this + in one step. + + + + The same instance can be used again and again, with the list of defined Jobs + being cleared each time you call a method, + however a single instance is not thread-safe. + + + Chris Bonham + James House + Marko Lahma (.NET) + + + + Constructor for XMLSchedulingDataProcessor. + + + + + Process the xml file in the default location (a file named + "quartz_jobs.xml" in the current working directory). + + + + + Process the xml file named . + + meta data file name. + + + + Process the xmlfile named with the given system + ID. + + Name of the file. + The system id. + + + + Process the xmlfile named with the given system + ID. + + The stream. + The system id. + + + + Process the xml file in the default location, and schedule all of the jobs defined within it. + + Note that we will set overWriteExistingJobs after the default xml is parsed. + + + + + + Process the xml file in the default location, and schedule all of the + jobs defined within it. + + + + + Process the xml file in the given location, and schedule all of the + jobs defined within it. + + meta data file name. + The scheduler. + + + + Process the xml file in the given location, and schedule all of the + jobs defined within it. + + Name of the file. + The system id. + The sched. + + + + Schedules the given sets of jobs and triggers. + + The sched. + + + + Adds a detected validation exception. + + The exception. + + + + Resets the the number of detected validation exceptions. + + + + + Throws a ValidationException if the number of validationExceptions + detected is greater than zero. + + + DTD validation exception. + + + + + Whether the existing scheduling data (with same identifiers) will be + overwritten. + + + If false, and is not false, and jobs or + triggers with the same names already exist as those in the file, an + error will occur. + + + + + + If true (and is false) then any + job/triggers encountered in this file that have names that already exist + in the scheduler will be ignored, and no error will be produced. + + + + + + Gets the log. + + The log. + + + + Helper class to map constant names to their values. + + + + + CalendarIntervalScheduleBuilder is a + that defines calendar time (day, week, month, year) interval-based + schedules for Triggers. + + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + Client code can then use the DSL to write code such as this: + + JobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + Trigger trigger = TriggerBuilder.Create() + .WithIdentity("myTrigger", "myTriggerGroup") + .WithSimpleSchedule(x => x + .WithIntervalInHours(1) + .RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + + + + Base class for implementors. + + + + + + Schedule builders offer fluent interface and are responsible for creating schedules. + + + + + + + + + Build the actual Trigger -- NOT intended to be invoked by end users, + but will rather be invoked by a TriggerBuilder which this + ScheduleBuilder is given to. + + + + + + Build the actual Trigger -- NOT intended to be invoked by end users, + but will rather be invoked by a TriggerBuilder which this + ScheduleBuilder is given to. + + + + + + Create a CalendarIntervalScheduleBuilder. + + + + + + Build the actual Trigger -- NOT intended to be invoked by end users, + but will rather be invoked by a TriggerBuilder which this + ScheduleBuilder is given to. + + + + + + Specify the time unit and interval for the Trigger to be produced. + + + + the interval at which the trigger should repeat. + the time unit (IntervalUnit) of the interval. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.SECOND that the produced + Trigger will repeat at. + + + + the number of seconds at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.MINUTE that the produced + Trigger will repeat at. + + + + the number of minutes at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.HOUR that the produced + Trigger will repeat at. + + + + the number of hours at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.DAY that the produced + Trigger will repeat at. + + + + the number of days at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.WEEK that the produced + Trigger will repeat at. + + + + the number of weeks at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.MONTH that the produced + Trigger will repeat at. + + + + the number of months at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.YEAR that the produced + Trigger will repeat at. + + + + the number of years at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CronScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CalendarIntervalScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CalendarIntervalScheduleBuilder + + + + + TimeZone in which to base the schedule. + + the time-zone for the schedule + the updated CalendarIntervalScheduleBuilder + + + + + If intervals are a day or greater, this property (set to true) will + cause the firing of the trigger to always occur at the same time of day, + (the time of day of the startTime) regardless of daylight saving time + transitions. Default value is false. + + + + For example, without the property set, your trigger may have a start + time of 9:00 am on March 1st, and a repeat interval of 2 days. But + after the daylight saving transition occurs, the trigger may start + firing at 8:00 am every other day. + + + If however, the time of day does not exist on a given day to fire + (e.g. 2:00 am in the United States on the days of daylight saving + transition), the trigger will go ahead and fire one hour off on + that day, and then resume the normal hour on other days. If + you wish for the trigger to never fire at the "wrong" hour, then + you should set the property skipDayIfHourDoesNotExist. + + + + + + + + + + If intervals are a day or greater, and + preserveHourOfDayAcrossDaylightSavings property is set to true, and the + hour of the day does not exist on a given day for which the trigger + would fire, the day will be skipped and the trigger advanced a second + interval if this property is set to true. Defaults to false. + + + CAUTION! If you enable this property, and your hour of day happens + to be that of daylight savings transition (e.g. 2:00 am in the United + States) and the trigger's interval would have had the trigger fire on + that day, then you may actually completely miss a firing on the day of + transition if that hour of day does not exist on that day! In such a + case the next fire time of the trigger will be computed as double (if + the interval is 2 days, then a span of 4 days between firings will + occur). + + + + + + Extension methods that attach to . + + + + + Provides a parser and evaluator for unix-like cron expressions. Cron + expressions provide the ability to specify complex time combinations such as + "At 8:00am every Monday through Friday" or "At 1:30am every + last Friday of the month". + + + + Cron expressions are comprised of 6 required fields and one optional field + separated by white space. The fields respectively are described as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field Name Allowed Values Allowed Special Characters
Seconds 0-59 , - /// /
Minutes 0-59 , - /// /
Hours 0-23 , - /// /
Day-of-month 1-31 , - /// ? / L W C
Month 1-12 or JAN-DEC , - /// /
Day-of-Week 1-7 or SUN-SAT , - /// ? / L #
Year (Optional) empty, 1970-2199 , - /// /
+ + The '*' character is used to specify all values. For example, "*" + in the minute field means "every minute". + + + The '?' character is allowed for the day-of-month and day-of-week fields. It + is used to specify 'no specific value'. This is useful when you need to + specify something in one of the two fields, but not the other. + + + The '-' character is used to specify ranges For example "10-12" in + the hour field means "the hours 10, 11 and 12". + + + The ',' character is used to specify additional values. For example + "MON,WED,FRI" in the day-of-week field means "the days Monday, + Wednesday, and Friday". + + + The '/' character is used to specify increments. For example "0/15" + in the seconds field means "the seconds 0, 15, 30, and 45". And + "5/15" in the seconds field means "the seconds 5, 20, 35, and + 50". Specifying '*' before the '/' is equivalent to specifying 0 is + the value to start with. Essentially, for each field in the expression, there + is a set of numbers that can be turned on or off. For seconds and minutes, + the numbers range from 0 to 59. For hours 0 to 23, for days of the month 0 to + 31, and for months 1 to 12. The "/" character simply helps you turn + on every "nth" value in the given set. Thus "7/6" in the + month field only turns on month "7", it does NOT mean every 6th + month, please note that subtlety. + + + The 'L' character is allowed for the day-of-month and day-of-week fields. + This character is short-hand for "last", but it has different + meaning in each of the two fields. For example, the value "L" in + the day-of-month field means "the last day of the month" - day 31 + for January, day 28 for February on non-leap years. If used in the + day-of-week field by itself, it simply means "7" or + "SAT". But if used in the day-of-week field after another value, it + means "the last xxx day of the month" - for example "6L" + means "the last friday of the month". You can also specify an offset + from the last day of the month, such as "L-3" which would mean the third-to-last + day of the calendar month. When using the 'L' option, it is important not to + specify lists, or ranges of values, as you'll get confusing/unexpected results. + + + The 'W' character is allowed for the day-of-month field. This character + is used to specify the weekday (Monday-Friday) nearest the given day. As an + example, if you were to specify "15W" as the value for the + day-of-month field, the meaning is: "the nearest weekday to the 15th of + the month". So if the 15th is a Saturday, the trigger will fire on + Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the + 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th. + However if you specify "1W" as the value for day-of-month, and the + 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not + 'jump' over the boundary of a month's days. The 'W' character can only be + specified when the day-of-month is a single day, not a range or list of days. + + + The 'L' and 'W' characters can also be combined for the day-of-month + expression to yield 'LW', which translates to "last weekday of the + month". + + + The '#' character is allowed for the day-of-week field. This character is + used to specify "the nth" XXX day of the month. For example, the + value of "6#3" in the day-of-week field means the third Friday of + the month (day 6 = Friday and "#3" = the 3rd one in the month). + Other examples: "2#1" = the first Monday of the month and + "4#5" = the fifth Wednesday of the month. Note that if you specify + "#5" and there is not 5 of the given day-of-week in the month, then + no firing will occur that month. If the '#' character is used, there can + only be one expression in the day-of-week field ("3#1,6#3" is + not valid, since there are two expressions). + + + + + + The legal characters and the names of months and days of the week are not + case sensitive. + + + NOTES: +
    +
  • Support for specifying both a day-of-week and a day-of-month value is + not complete (you'll need to use the '?' character in one of these fields). +
    • +
  • Overflowing ranges is supported - that is, having a larger number on + the left hand side than the right. You might do 22-2 to catch 10 o'clock + at night until 2 o'clock in the morning, or you might have NOV-FEB. It is + very important to note that overuse of overflowing ranges creates ranges + that don't make sense and no effort has been made to determine which + interpretation CronExpression chooses. An example would be + "0 0 14-6 ? * FRI-MON".
    • +
+ + + Sharada Jambula + James House + Contributions from Mads Henderson + Refactoring from CronTrigger to CronExpression by Aaron Craven + Marko Lahma (.NET) + + + + Field specification for second. + + + + + Field specification for minute. + + + + + Field specification for hour. + + + + + Field specification for day of month. + + + + + Field specification for month. + + + + + Field specification for day of week. + + + + + Field specification for year. + + + + + Field specification for all wildcard value '*'. + + + + + Field specification for not specified value '?'. + + + + + Field specification for wildcard '*'. + + + + + Field specification for no specification at all '?'. + + + + + Seconds. + + + + + minutes. + + + + + Hours. + + + + + Days of month. + + + + + Months. + + + + + Days of week. + + + + + Years. + + + + + Last day of week. + + + + + Nth day of week. + + + + + Last day of month. + + + + + Nearest weekday. + + + + + Calendar day of week. + + + + + Calendar day of month. + + + + + Expression parsed. + + + + + Constructs a new based on the specified + parameter. + + + String representation of the cron expression the new object should represent + + + + + + Indicates whether the given date satisfies the cron expression. + + + Note that milliseconds are ignored, so two Dates falling on different milliseconds + of the same second will always have the same result here. + + The date to evaluate. + a boolean indicating whether the given date satisfies the cron expression + + + + Returns the next date/time after the given date/time which + satisfies the cron expression. + + the date/time at which to begin the search for the next valid date/time + the next valid date/time + + + + Returns the next date/time after the given date/time which does + not satisfy the expression. + + the date/time at which to begin the search for the next invalid date/time + the next valid date/time + + + + Returns the string representation of the + + The string representation of the + + + + Indicates whether the specified cron expression can be parsed into a + valid cron expression + + the expression to evaluate + a boolean indicating whether the given expression is a valid cron + expression + + + + Builds the expression. + + The expression. + + + + Stores the expression values. + + The position. + The string to traverse. + The type of value. + + + + + Checks the next value. + + The position. + The string to check. + The value. + The type to search. + + + + + Gets the expression summary. + + + + + + Gets the expression set summary. + + The data. + + + + + Skips the white space. + + The i. + The s. + + + + + Finds the next white space. + + The i. + The s. + + + + + Adds to set. + + The val. + The end. + The incr. + The type. + + + + Gets the set of given type. + + The type of set to get. + + + + + Gets the value. + + The v. + The s. + The i. + + + + + Gets the numeric value from string. + + The string to parse from. + The i. + + + + + Gets the month number. + + The string to map with. + + + + + Gets the day of week number. + + The s. + + + + + Gets the time from given time parts. + + The seconds. + The minutes. + The hours. + The day of month. + The month. + + + + + Gets the next fire time after the given time. + + The UTC time to start searching from. + + + + + Creates the date time without milliseconds. + + The time. + + + + + Advance the calendar to the particular hour paying particular attention + to daylight saving problems. + + The date. + The hour. + + + + + Gets the time before. + + The end time. + + + + + NOT YET IMPLEMENTED: Returns the final time that the + will match. + + + + + + Determines whether given year is a leap year. + + The year. + + true if the specified year is a leap year; otherwise, false. + + + + + Gets the last day of month. + + The month num. + The year. + + + + + Creates a new object that is a copy of the current instance. + + + A new object that is a copy of this instance. + + + + + Determines whether the specified is equal to the current . + + + true if the specified is equal to the current ; otherwise, false. + + The to compare with the current . + + + + Determines whether the specified is equal to the current . + + + true if the specified is equal to the current ; otherwise, false. + + The to compare with the current . + + + + Serves as a hash function for a particular type. + + + A hash code for the current . + + 2 + + + + Sets or gets the time zone for which the of this + will be resolved. + + + + + Gets the cron expression string. + + The cron expression string. + + + + Helper class for cron expression handling. + + + + + The value. + + + + + The position. + + + + + CronScheduleBuilder is a that defines + -based schedules for s. + + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + + Client code can then use the DSL to write code such as this: + + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + ITrigger trigger = newTrigger() + .WithIdentity(triggerKey("myTrigger", "myTriggerGroup")) + .WithSimpleSchedule(x => x.WithIntervalInHours(1).RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + + + + + Build the actual Trigger -- NOT intended to be invoked by end users, + but will rather be invoked by a TriggerBuilder which this + ScheduleBuilder is given to. + + + + + + Create a CronScheduleBuilder with the given cron-expression - which + is presumed to b e valid cron expression (and hence only a RuntimeException + will be thrown if it is not). + + + + the cron expression to base the schedule on. + the new CronScheduleBuilder + + + + + Create a CronScheduleBuilder with the given cron-expression string - which + may not be a valid cron expression (and hence a ParseException will be thrown + f it is not). + + the cron expression string to base the schedule on + the new CronScheduleBuilder + + + + + Create a CronScheduleBuilder with the given cron-expression. + + the cron expression to base the schedule on. + the new CronScheduleBuilder + + + + + Create a CronScheduleBuilder with a cron-expression that sets the + schedule to fire every day at the given time (hour and minute). + + + + the hour of day to fire + the minute of the given hour to fire + the new CronScheduleBuilder + + + + + Create a CronScheduleBuilder with a cron-expression that sets the + schedule to fire at the given day at the given time (hour and minute) on the given days of the week. + + the hour of day to fire + the minute of the given hour to fire + the days of the week to fire + the new CronScheduleBuilder + + + + + Create a CronScheduleBuilder with a cron-expression that sets the + schedule to fire one per week on the given day at the given time + (hour and minute). + + + + the day of the week to fire + the hour of day to fire + the minute of the given hour to fire + the new CronScheduleBuilder + + + + + Create a CronScheduleBuilder with a cron-expression that sets the + schedule to fire one per month on the given day of month at the given + time (hour and minute). + + + + the day of the month to fire + the hour of day to fire + the minute of the given hour to fire + the new CronScheduleBuilder + + + + + The in which to base the schedule. + + + + the time-zone for the schedule. + the updated CronScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CronScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CronScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CronScheduleBuilder + + + + + Extension methods that attach to . + + + + + A implementation that build schedule for DailyTimeIntervalTrigger. + + + + This builder provide an extra convenient method for you to set the trigger's EndTimeOfDay. You may + use either endingDailyAt() or EndingDailyAfterCount() to set the value. The later will auto calculate + your EndTimeOfDay by using the interval, IntervalUnit and StartTimeOfDay to perform the calculation. + + + When using EndingDailyAfterCount(), you should note that it is used to calculating EndTimeOfDay. So + if your startTime on the first day is already pass by a time that would not add up to the count you + expected, until the next day comes. Remember that DailyTimeIntervalTrigger will use StartTimeOfDay + and endTimeOfDay as fresh per each day! + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + Client code can then use the DSL to write code such as this: + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + + ITrigger trigger = TriggerBuilder.Create() + .WithIdentity(triggerKey("myTrigger", "myTriggerGroup")) + .WithDailyTimeIntervalSchedule(x => + x.WithIntervalInMinutes(15) + .StartingDailyAt(TimeOfDay.HourAndMinuteOfDay(8, 0)) + .Build(); + + scheduler.scheduleJob(job, trigger); + + + James House + Zemian Deng saltnlight5@gmail.com + Nuno Maia (.NET) + + + + A set of all days of the week. + + + The set contains all values between and + + + + + A set of the business days of the week (for locales similar to the USA). + + + The set contains all values between and + + + + + A set of the weekend days of the week (for locales similar to the USA). + + + The set contains and + + + + + Create a DailyTimeIntervalScheduleBuilder + + The new DailyTimeIntervalScheduleBuilder + + + + Build the actual Trigger -- NOT intended to be invoked by end users, + but will rather be invoked by a TriggerBuilder which this + ScheduleBuilder is given to. + + + + + + Specify the time unit and interval for the Trigger to be produced. + + + + the interval at which the trigger should repeat. + the time unit (IntervalUnit) of the interval. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.Second that the produced + Trigger will repeat at. + + The number of seconds at which the trigger should repeat. + the updated DailyTimeIntervalScheduleBuilder> + + + + + + Specify an interval in the IntervalUnit.Minute that the produced + Trigger will repeat at. + + The number of minutes at which the trigger should repeat. + the updated DailyTimeIntervalScheduleBuilder> + + + + + + Specify an interval in the IntervalUnit.Hour that the produced + Trigger will repeat at. + + The number of hours at which the trigger should repeat. + the updated DailyTimeIntervalScheduleBuilder> + + + + + + Set the trigger to fire on the given days of the week. + + a Set containing the integers representing the days of the week, defined by - . + + the updated DailyTimeIntervalScheduleBuilder + + + + Set the trigger to fire on the given days of the week. + + a variable length list of week days representing the days of the week + the updated DailyTimeIntervalScheduleBuilder + + + + Set the trigger to fire on the days from Monday through Friday. + + the updated DailyTimeIntervalScheduleBuilder + + + + Set the trigger to fire on the days Saturday and Sunday. + + the updated DailyTimeIntervalScheduleBuilder + + + + Set the trigger to fire on all days of the week. + + the updated DailyTimeIntervalScheduleBuilder + + + + Set the trigger to begin firing each day at the given time. + + + the updated DailyTimeIntervalScheduleBuilder + + + + Set the startTimeOfDay for this trigger to end firing each day at the given time. + + + the updated DailyTimeIntervalScheduleBuilder + + + + Calculate and set the EndTimeOfDay using count, interval and StarTimeOfDay. This means + that these must be set before this method is call. + + + the updated DailyTimeIntervalScheduleBuilder + + + + If the Trigger misfires, use the + instruction. + + the updated DailyTimeIntervalScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + the updated DailyTimeIntervalScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + the updated DailyTimeIntervalScheduleBuilder + + + + + Set number of times for interval to repeat. + + + Note: if you want total count = 1 (at start time) + repeatCount + + + + + + + Extension methods that attach to . + + + + + DateBuilder is used to conveniently create + instances that meet particular criteria. + + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + Client code can then use the DSL to write code such as this: + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + ITrigger trigger = newTrigger() + .WithIdentity(triggerKey("myTrigger", "myTriggerGroup")) + .WithSimpleSchedule(x => x + .WithIntervalInHours(1) + .RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minutes)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + Create a DateBuilder, with initial settings for the current date + and time in the system default timezone. + + + + + Create a DateBuilder, with initial settings for the current date and time in the given timezone. + + + + + + Create a DateBuilder, with initial settings for the current date and time in the system default timezone. + + + + + + Create a DateBuilder, with initial settings for the current date and time in the given timezone. + + Time zone to use. + + + + + Build the defined by this builder instance. + + New date time based on builder parameters. + + + + Set the hour (0-23) for the Date that will be built by this builder. + + + + + + + Set the minute (0-59) for the Date that will be built by this builder. + + + + + + + Set the second (0-59) for the Date that will be built by this builder, and truncate the milliseconds to 000. + + + + + + + Set the day of month (1-31) for the Date that will be built by this builder. + + + + + + + Set the month (1-12) for the Date that will be built by this builder. + + + + + + + Set the year for the Date that will be built by this builder. + + + + + + + Set the TimeZoneInfo for the Date that will be built by this builder (if "null", system default will be used) + + + + + + + Get a object that represents the given time, on + tomorrow's date. + + + + + + + + + Get a object that represents the given time, on + today's date (equivalent to . + + + + + + + + + Get a object that represents the given time, on today's date. + + The value (0-59) to give the seconds field of the date + The value (0-59) to give the minutes field of the date + The value (0-23) to give the hours field of the date + the new date + + + + Get a object that represents the given time, on the + given date. + + The value (0-59) to give the seconds field of the date + The value (0-59) to give the minutes field of the date + The value (0-23) to give the hours field of the date + The value (1-31) to give the day of month field of the date + The value (1-12) to give the month field of the date + the new date + + + + Get a object that represents the given time, on the + given date. + + + + The value (0-59) to give the seconds field of the date + The value (0-59) to give the minutes field of the date + The value (0-23) to give the hours field of the date + The value (1-31) to give the day of month field of the date + The value (1-12) to give the month field of the date + The value (1970-2099) to give the year field of the date + the new date + + + + Returns a date that is rounded to the next even hour after the current time. + + + For example a current time of 08:13:54 would result in a date + with the time of 09:00:00. If the date's time is in the 23rd hour, the + date's 'day' will be promoted, and the time will be set to 00:00:00. + + the new rounded date + + + + Returns a date that is rounded to the next even hour above the given date. + + + For example an input date with a time of 08:13:54 would result in a date + with the time of 09:00:00. If the date's time is in the 23rd hour, the + date's 'day' will be promoted, and the time will be set to 00:00:00. + + the Date to round, if the current time will + be used + the new rounded date + + + + Returns a date that is rounded to the previous even hour below the given date. + + + For example an input date with a time of 08:13:54 would result in a date + with the time of 08:00:00. + + the Date to round, if the current time will + be used + the new rounded date + + + + + Returns a date that is rounded to the next even minute after the current time. + + + + For example a current time of 08:13:54 would result in a date + with the time of 08:14:00. If the date's time is in the 59th minute, + then the hour (and possibly the day) will be promoted. + + the new rounded date + + + + Returns a date that is rounded to the next even minute above the given date. + + + For example an input date with a time of 08:13:54 would result in a date + with the time of 08:14:00. If the date's time is in the 59th minute, + then the hour (and possibly the day) will be promoted. + + The Date to round, if the current time will be used + The new rounded date + + + + Returns a date that is rounded to the previous even minute below the given date. + + + For example an input date with a time of 08:13:54 would result in a date + with the time of 08:13:00. + + the Date to round, if the current time will + be used + the new rounded date + + + + Returns a date that is rounded to the next even second after the current time. + + the new rounded date + + + + Returns a date that is rounded to the next even second above the given date. + + + the Date to round, if the current time will + be used + the new rounded date + + + + Returns a date that is rounded to the previous even second below the + given date. + + + + For example an input date with a time of 08:13:54.341 would result in a + date with the time of 08:13:00.000. + + + + the Date to round, if the current time will + be used + the new rounded date + + + + Returns a date that is rounded to the next even multiple of the given + minute. + + + + For example an input date with a time of 08:13:54, and an input + minute-base of 5 would result in a date with the time of 08:15:00. The + same input date with an input minute-base of 10 would result in a date + with the time of 08:20:00. But a date with the time 08:53:31 and an + input minute-base of 45 would result in 09:00:00, because the even-hour + is the next 'base' for 45-minute intervals. + + + More examples: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Input TimeMinute-BaseResult Time
11:16:412011:20:00
11:36:412011:40:00
11:46:412012:00:00
11:26:413011:30:00
11:36:413012:00:00
11:16:411711:17:00
11:17:411711:34:00
11:52:411712:00:00
11:52:41511:55:00
11:57:41512:00:00
11:17:41012:00:00
11:17:41111:08:00
+ + + + the Date to round, if the current time will + be used + + the base-minute to set the time on + the new rounded date + + + + + Returns a date that is rounded to the next even multiple of the given + minute. + + + The rules for calculating the second are the same as those for + calculating the minute in the method . + + the Date to round, if the current time will + be used + the base-second to set the time on + the new rounded date + + + + + An attribute that marks a class as one that must not have multiple + instances executed concurrently (where instance is based-upon a + definition - or in other words based upon a . + + + This can be used in lieu of implementing the StatefulJob marker interface that + was used prior to Quartz 2.0 + + + James House + Marko Lahma (.NET) + + + + The interface to be implemented by s that provide a + mechanism for having their execution interrupted. It is NOT a requirement + for jobs to implement this interface - in fact, for most people, none of + their jobs will. + + + + The means of actually interrupting the Job must be implemented within the + itself (the method of this + interface is simply a means for the scheduler to inform the + that a request has been made for it to be interrupted). The mechanism that + your jobs use to interrupt themselves might vary between implementations. + However the principle idea in any implementation should be to have the + body of the job's periodically check some flag to + see if an interruption has been requested, and if the flag is set, somehow + abort the performance of the rest of the job's work. An example of + interrupting a job can be found in the java source for the class + . It is legal to use + some combination of and + synchronization within and + in order to have the method block until the + signals that it has noticed the set flag. + + + + If the Job performs some form of blocking I/O or similar functions, you may + want to consider having the method store a + reference to the calling as a member variable. Then the + implementation of this interfaces method can call + on that Thread. Before attempting this, make + sure that you fully understand what + does and doesn't do. Also make sure that you clear the Job's member + reference to the Thread when the Execute(..) method exits (preferably in a + block. + + + + + + James House + Marko Lahma (.NET) + + + + Called by the when a user + interrupts the . + + void (nothing) if job interrupt is successful. + + + + Supported interval units used by . + + + + + A marker interface for s that + wish to have their state maintained between executions. + + + instances follow slightly different rules from + regular instances. The key difference is that their + associated is re-persisted after every + execution of the job, thus preserving state for the next execution. The + other difference is that stateful jobs are not allowed to Execute + concurrently, which means new triggers that occur before the completion of + the method will be delayed. + + + + + + + + James House + Marko Lahma (.NET) + + + + JobBuilder is used to instantiate s. + + + + The builder will always try to keep itself in a valid state, with + reasonable defaults set for calling Build() at any point. For instance + if you do not invoke WithIdentity(..) a job name will be generated + for you. + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + + Client code can then use the DSL to write code such as this: + + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + + ITrigger trigger = TriggerBuilder.Create() + .WithIdentity("myTrigger", "myTriggerGroup") + .WithSimpleSchedule(x => x.WithIntervalInHours(1).RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + + scheduler.scheduleJob(job, trigger); + + + + + + + + + Create a JobBuilder with which to define a . + + a new JobBuilder + + + + Create a JobBuilder with which to define a , + and set the class name of the job to be executed. + + a new JobBuilder + + + + Create a JobBuilder with which to define a , + and set the class name of the job to be executed. + + a new JobBuilder + + + + Produce the instance defined by this JobBuilder. + + the defined JobDetail. + + + + Use a with the given name and default group to + identify the JobDetail. + + + If none of the 'withIdentity' methods are set on the JobBuilder, + then a random, unique JobKey will be generated. + + the name element for the Job's JobKey + the updated JobBuilder + + + + + + Use a with the given name and group to + identify the JobDetail. + + + If none of the 'withIdentity' methods are set on the JobBuilder, + then a random, unique JobKey will be generated. + + the name element for the Job's JobKey + the group element for the Job's JobKey + the updated JobBuilder + + + + + + Use a to identify the JobDetail. + + + If none of the 'withIdentity' methods are set on the JobBuilder, + then a random, unique JobKey will be generated. + + the Job's JobKey + the updated JobBuilder + + + + + + Set the given (human-meaningful) description of the Job. + + the description for the Job + the updated JobBuilder + + + + + Set the class which will be instantiated and executed when a + Trigger fires that is associated with this JobDetail. + + the updated JobBuilder + + + + + Set the class which will be instantiated and executed when a + Trigger fires that is associated with this JobDetail. + + the updated JobBuilder + + + + + Instructs the whether or not the job + should be re-executed if a 'recovery' or 'fail-over' situation is + encountered. + + + If not explicitly set, the default value is . + + the updated JobBuilder + + + + + Instructs the whether or not the job + should be re-executed if a 'recovery' or 'fail-over' situation is + encountered. + + + If not explicitly set, the default value is . + + + the updated JobBuilder + + + + Whether or not the job should remain stored after it is + orphaned (no s point to it). + + + If not explicitly set, the default value is . + + the updated JobBuilder + + + + + Whether or not the job should remain stored after it is + orphaned (no s point to it). + + + If not explicitly set, the default value is . + + the value to set for the durability property. + the updated JobBuilder + + + + + Add the given key-value pair to the JobDetail's . + + the updated JobBuilder + + + + + Add the given key-value pair to the JobDetail's . + + the updated JobBuilder + + + + + Add the given key-value pair to the JobDetail's . + + the updated JobBuilder + + + + + Add the given key-value pair to the JobDetail's . + + the updated JobBuilder + + + + + Add the given key-value pair to the JobDetail's . + + the updated JobBuilder + + + + + Add the given key-value pair to the JobDetail's . + + the updated JobBuilder + + + + + Set the JobDetail's , adding any values to it + that were already set on this JobBuilder using any of the + other 'usingJobData' methods. + + the updated JobBuilder + + + + + Holds state information for instances. + + + instances are stored once when the + is added to a scheduler. They are also re-persisted after every execution of + instances that have present. + + instances can also be stored with a + . This can be useful in the case where you have a Job + that is stored in the scheduler for regular/repeated use by multiple + Triggers, yet with each independent triggering, you want to supply the + Job with different data inputs. + + + The passed to a Job at execution time + also contains a convenience that is the result + of merging the contents of the trigger's JobDataMap (if any) over the + Job's JobDataMap (if any). + + + + + + + James House + Marko Lahma (.NET) + + + + Create an empty . + + + + + Create a with the given data. + + + + + Create a with the given data. + + + + + Serialization constructor. + + + + + + + Adds the given value as a string version to the + 's data map. + + + + + Adds the given value as a string version to the + 's data map. + + + + + Adds the given value as a string version to the + 's data map. + + + + + Adds the given value as a string version to the + 's data map. + + + + + Adds the given value as a string version to the + 's data map. + + + + + Adds the given value as a string version to the + 's data map. + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the + . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Gets the date time. + + The key. + + + + + Gets the value behind the specified key. + + The key. + + + + + An exception that can be thrown by a + to indicate to the Quartz that an error + occurred while executing, and whether or not the requests + to be re-fired immediately (using the same , + or whether it wants to be unscheduled. + + + Note that if the flag for 'refire immediately' is set, the flags for + unscheduling the Job are ignored. + + + + + James House + Marko Lahma (.NET) + + + + Create a JobExcecutionException, with the 're-fire immediately' flag set + to . + + + + + Create a JobExcecutionException, with the given cause. + + The cause. + + + + Create a JobExcecutionException, with the given message. + + + + + Initializes a new instance of the class. + + The message. + The original cause. + + + + Create a JobExcecutionException with the 're-fire immediately' flag set + to the given value. + + + + + Create a JobExcecutionException with the given underlying exception, and + the 're-fire immediately' flag set to the given value. + + + + + Create a JobExcecutionException with the given message, and underlying + exception, and the 're-fire immediately' flag set to the given value. + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + Creates and returns a string representation of the current exception. + + + A string representation of the current exception. + + + + + + Gets or sets a value indicating whether to unschedule firing trigger. + + + true if firing trigger should be unscheduled; otherwise, false. + + + + + Gets or sets a value indicating whether to unschedule all triggers. + + + true if all triggers should be unscheduled; otherwise, false. + + + + + Gets or sets a value indicating whether to refire immediately. + + true if to refire immediately; otherwise, false. + + + + Uniquely identifies a . + + + Keys are composed of both a name and group, and the name must be unique + within the group. If only a group is specified then the default group + name will be used. + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + Client code can then use the DSL to write code such as this: + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + ITrigger trigger = TriggerBuilder.Create() + .WithIdentity("myTrigger", "myTriggerGroup") + .WithSimpleSchedule(x => x + .WithIntervalInHours(1) + .RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + Misfire instructions. + + Marko Lahma (.NET) + + + + Instruction not set (yet). + + + + + Use smart policy. + + + + + Instructs the that the + will never be evaluated for a misfire situation, + and that the scheduler will simply try to fire it as soon as it can, + and then update the Trigger as if it had fired at the proper time. + + + NOTE: if a trigger uses this instruction, and it has missed + several of its scheduled firings, then several rapid firings may occur + as the trigger attempt to catch back up to where it would have been. + For example, a SimpleTrigger that fires every 15 seconds which has + misfired for 5 minutes will fire 20 times once it gets the chance to + fire. + + + + + Misfire policy settings for SimpleTrigger. + + + + + Instructs the that upon a mis-fire + situation, the wants to be fired + now by . + + NOTE: This instruction should typically only be used for + 'one-shot' (non-repeating) Triggers. If it is used on a trigger with a + repeat count > 0 then it is equivalent to the instruction + . + + + + + + Instructs the that upon a mis-fire + situation, the wants to be + re-scheduled to 'now' (even if the associated + excludes 'now') with the repeat count left as-is. This does obey the + end-time however, so if 'now' is after the + end-time the will not fire again. + + + + NOTE: Use of this instruction causes the trigger to 'forget' + the start-time and repeat-count that it was originally setup with (this + is only an issue if you for some reason wanted to be able to tell what + the original values were at some later time). + + + + + + Instructs the that upon a mis-fire + situation, the wants to be + re-scheduled to 'now' (even if the associated + excludes 'now') with the repeat count set to what it would be, if it had + not missed any firings. This does obey the end-time + however, so if 'now' is after the end-time the will + not fire again. + + + NOTE: Use of this instruction causes the trigger to 'forget' + the start-time and repeat-count that it was originally setup with. + Instead, the repeat count on the trigger will be changed to whatever + the remaining repeat count is (this is only an issue if you for some + reason wanted to be able to tell what the original values were at some + later time). + + + + NOTE: This instruction could cause the + to go to the 'COMPLETE' state after firing 'now', if all the + repeat-fire-times where missed. + + + + + + Instructs the that upon a mis-fire + situation, the wants to be + re-scheduled to the next scheduled time after 'now' - taking into + account any associated , and with the + repeat count set to what it would be, if it had not missed any firings. + + + NOTE/WARNING: This instruction could cause the + to go directly to the 'COMPLETE' state if all fire-times where missed. + + + + + Instructs the that upon a mis-fire + situation, the wants to be + re-scheduled to the next scheduled time after 'now' - taking into + account any associated , and with the + repeat count left unchanged. + + + + NOTE/WARNING: This instruction could cause the + to go directly to the 'COMPLETE' state if all the end-time of the trigger + has arrived. + + + + + + misfire instructions for CronTrigger + + + + + Instructs the that upon a mis-fire + situation, the wants to be fired now + by . + + + + + Instructs the that upon a mis-fire + situation, the wants to have it's + next-fire-time updated to the next time in the schedule after the + current time (taking into account any associated , + but it does not want to be fired now. + + + + + misfire instructions for NthIncludedDayTrigger + + + + + Instructs the that upon a mis-fire situation, the + wants to be fired now by the + + + + + + Instructs the that upon a mis-fire situation, the + wants to have + nextFireTime updated to the next time in the schedule after + the current time, but it does not want to be fired now. + + + + + Misfire instructions for DateIntervalTrigger + + + + + Instructs the that upon a mis-fire + situation, the wants to be + fired now by . + + + + + Instructs the that upon a mis-fire + situation, the wants to have it's + next-fire-time updated to the next time in the schedule after the + current time (taking into account any associated , + but it does not want to be fired now. + + + + + Misfire instructions for DailyTimeIntervalTrigger + + + + + Instructs the that upon a mis-fire + situation, the wants to be + fired now by . + + + + + Instructs the that upon a mis-fire + situation, the wants to have it's + next-fire-time updated to the next time in the schedule after the + current time (taking into account any associated , + but it does not want to be fired now. + + + + + A trigger which fires on the Nth day of every interval type + , or + that is not excluded by the associated + calendar. + + + When determining what the Nth day of the month or year + is, will skip excluded days on the + associated calendar. This would commonly be used in an Nth + business day situation, in which the user wishes to fire a particular job on + the Nth business day (i.e. the 5th business day of + every month). Each also has an associated + which indicates at what time of day the trigger is + to fire. + + All s default to a monthly interval type + (fires on the Nth day of every month) with N = 1 (first + non-excluded day) and set to 12:00 PM (noon). These + values can be changed using the , , and + methods. Users may also want to note the + and + methods. + + + Take, for example, the following calendar: + + + July August September + Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa + 1 W 1 2 3 4 5 W 1 2 W + W H 5 6 7 8 W W 8 9 10 11 12 W W H 6 7 8 9 W + W 11 12 13 14 15 W W 15 16 17 18 19 W W 12 13 14 15 16 W + W 18 19 20 21 22 W W 22 23 24 25 26 W W 19 20 21 22 23 W + W 25 26 27 28 29 W W 29 30 31 W 26 27 28 29 30 + W + + Where W's represent weekend days, and H's represent holidays, all of which + are excluded on a calendar associated with an + with n=5 and + intervalType=IntervalTypeMonthly. In this case, the trigger + would fire on the 8th of July (because of the July 4 holiday), + the 5th of August, and the 8th of September (because + of Labor Day). + + Aaron Craven + Marko Lahma (.NET) + + + + Indicates a monthly trigger type (fires on the Nth included + day of every month). + + + + indicates a yearly trigger type (fires on the Nth included + day of every year). + + + + + Indicates a weekly trigger type (fires on the Nth included + day of every week). When using this interval type, care must be taken + not to think of the value of as an analog to + . Such a comparison can only + be drawn when there are no calendars associated with the trigger. To + illustrate, consider an with + n = 3 which is associated with a Calendar excluding + non-weekdays. The trigger would fire on the 3rd + included day of the week, which would be 4th + actual day of the week. + + + + + Create an with no specified name, + group, or . This will result initially in a + default monthly trigger that fires on the first day of every month at + 12:00 PM (n = 1, + intervalType=, + fireAtTime="12:00"). + + + Note that and , must be + called before the can be placed into + a . + + + + + Create an with the given name and + default group but no specified . This will result + initially in a default monthly trigger that fires on the first day of + every month at 12:00 PM (=1, + intervalType=, + fireAtTime=12:00"). + + Note that must + be called before the can be placed + into a . + + + the name for the + + + + + Create an with the given name and + group but no specified . This will result + initially in a default monthly trigger that fires on the first day of + every month at 12:00 PM (=1, + intervalType=, + fireAtTime=12:00"). + + Note that must + be called before the can be placed + into a . + + + the name for the + + the group for the + + + + + Create an with the given name and + group and the specified . This will result + initially in a default monthly trigger that fires on the first day of + every month at 12:00 PM (=1, + intervalType=, + fireAtTime="12:00"). + + The name for the . + The group for the . + The name of the job to associate with the . + The group containing the job to associate with the . + + + + Returns the next UTC time at which the + will fire. If the trigger will not fire again, will be + returned. + + + + Because of the conceptual design of , + it is not always possible to decide with certainty that the trigger + will never fire again. Therefore, it will search for the next + fire time up to a given cutoff. These cutoffs can be changed by using the + property. The default cutoff is 12 + of the intervals specified by intervalType. + + + The returned value is not guaranteed to be valid until after + the trigger has been added to the scheduler. + + + the next fire time for the trigger + + + + + Returns the previous UTC time at which the + fired. If the trigger has not yet + fired, will be returned. + + the previous fire time for the trigger + + + + Returns the first time the will fire + after the specified date. + + + + Because of the conceptual design of , + it is not always possible to decide with certainty that the trigger + will never fire again. Therefore, it will search for the next + fire time up to a given cutoff. These cutoffs can be changed by using the + property. The default cutoff is 12 + of the intervals specified by intervalType. + + + Therefore, for triggers with intervalType = + , if the trigger + will not fire within 12 + weeks after the given date/time, will be returned. For + triggers with intervalType = + + , if the trigger will not fire within 12 + months after the given date/time, will be returned. + For triggers with intervalType = + + , if the trigger will not fire within 12 + years after the given date/time, will be returned. In + all cases, if the trigger will not fire before , + will be returned. + + + The time after which to find the nearest fire time. + This argument is treated as exclusive 舒 that is, + if afterTime is a valid fire time for the trigger, it + will not be returned as the next fire time. + + + the first time the trigger will fire following the specified date + + + + + Called when the has decided to 'fire' the trigger + (Execute the associated ), in order to give the + a chance to update itself for its next triggering + (if any). + + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + After this method has been called, + should return a valid answer. + + + + the first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first + firing of the ). + + + + + Called after the has executed the + associated with the in order + to get the final instruction code from the trigger. + + + The that was used by the + 's method. + + + The thrown by the + , if any (may be ) + + one of the Trigger.INSTRUCTION_XXX constants. + + + + + Used by the to determine whether or not it is + possible for this to fire again. + ' + + + If the returned value is then the + may remove the from the + + + + + A boolean indicator of whether the trigger could potentially fire + again. + + + + + Indicates whether is a valid misfire + instruction for this . + + Whether is valid. + + + Updates the 's state based on the + MisfireInstruction that was selected when the + was created +

+ If the misfire instruction is set to MISFIRE_INSTRUCTION_SMART_POLICY, + then the instruction will be interpreted as + . +

+ + a new or updated calendar to use for the trigger + + + + + Updates the 's state based on the + given new version of the associated . + + A new or updated calendar to use for the trigger + the amount of time that must + be between "now" and the time the next + firing of the trigger is supposed to occur. + + + + + Calculates the first time an with + intervalType = IntervalTypeWeekly will fire + after the specified date. See for more + information. + + The time after which to find the nearest fire time. + This argument is treated as exclusive 舒 that is, + if afterTime is a valid fire time for the trigger, it + will not be returned as the next fire time. + + the first time the trigger will fire following the specified + date + + + + + Calculates the first UTC time an with + intervalType = will fire + after the specified date. See for more + information. + + + The UTC time after which to find the nearest fire time. + This argument is treated as exclusive 舒 that is, + if afterTime is a valid fire time for the trigger, it + will not be returned as the next fire time. + + the first time the trigger will fire following the specified date + + + + Calculates the first time an with + intervalType = will fire + after the specified date. See for more + information. + + + The UTC time after which to find the nearest fire time. + This argument is treated as exclusive 舒 that is, + if afterTime is a valid fire time for the trigger, it + will not be returned as the next fire time. + + the first time the trigger will fire following the specified + date + + + + + Get a that is configured to produce a + schedule identical to this trigger's schedule. + + + + + + + Gets or sets the day of the interval on which the + should fire. If the Nth + day of the interval does not exist (i.e. the 32nd of a + month), the trigger simply will never fire. N may not be less than 1. + + + + + Returns the interval type for the . + + + Sets the interval type for the . If + , the trigger will fire on the + Nth included day of every month. If + , the trigger will fire on the + Nth included day of every year. If + , the trigger will fire on the + Nth included day of every week. + + + + + + + + Returns the fire time for the as a + string with the format "HH:MM[:SS]", with HH representing the + 24-hour clock hour of the fire time. Seconds are optional and their + inclusion depends on whether or not they were provided to + . + + + + + Returns the for the + . + + + + Because of the conceptual design of , + it is not always possible to decide with certainty that the trigger + will never fire again. Therefore, it will search for the next + fire time up to a given cutoff. These cutoffs can be changed by using the + property. The default cutoff is 12 + of the intervals specified by intervalType" />. + + + Because of the conceptual design of , + it is not always possible to decide with certainty that the trigger + will never fire again. Therefore, it will search for the next + fire time up to a given cutoff. These cutoffs can be changed by using the + method. The default cutoff is 12 + of the intervals specified by intervalType". + + + In most cases, the default value of this setting (12) is sufficient (it + is highly unlikely, for example, that you will need to look at more than + 12 months of dates to ensure that your trigger will never fire again). + However, this setting is included to allow for the rare exceptions where + this might not be true. + + + For example, if your trigger is associated with a calendar that excludes + a great many dates in the next 12 months, and hardly any following that, + it is possible (if is large enough) that you could run + into this situation. + + + + + + Returns the last UTC time the will fire. + If the trigger will not fire at any point between + and , will be returned. + + the last time the trigger will fire. + + + + Tells whether this Trigger instance can handle events + in millisecond precision. + + + + + + Sets or gets the time zone in which the will be resolved. + If no time zone is provided, then the default time zone will be used. + + + + + + + Gets or sets the trigger's calendar week rule. + + The trigger calendar week rule. + + + + Gets or sets the trigger's calendar first day of week rule. + + The trigger calendar first day of week. + + + + An exception that is thrown to indicate that an attempt to store a new + object (i.e. , + or ) in a + failed, because one with the same name and group already exists. + + James House + Marko Lahma (.NET) + + + + Create a with the given + message. + + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + Create a and auto-generate a + message using the name/group from the given . + + + + The message will read:
"Unable to store Job with name: '__' and + group: '__', because one already exists with this identification." + + + + + + Create a and auto-generate a + message using the name/group from the given . + + + + The message will read:
"Unable to store Trigger with name: '__' and + group: '__', because one already exists with this identification." + + + + + + An attribute that marks a class as one that makes updates to its + during execution, and wishes the scheduler to re-store the + when execution completes. + + + + Jobs that are marked with this annotation should also seriously consider + using the attribute, to avoid data + storage race conditions with concurrently executing job instances. + + + This can be used in lieu of implementing the StatefulJob marker interface that + was used prior to Quartz 2.0 + + + + James House + Marko Lahma (.NET) + + + + An exception that is thrown to indicate that there is a misconfiguration of + the - or one of the components it + configures. + + James House + Marko Lahma (.NET) + + + + Create a with the given message. + + + + + Create a with the given message + and cause. + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + Scheduler constants. + + Marko Lahma (.NET) + + + + A (possibly) useful constant that can be used for specifying the group + that and instances belong to. + + + + + A constant group name used internally by the + scheduler - clients should not use the value of this constant + ("RECOVERING_JOBS") for thename of a 's group. + + + + + A constant group name used internally by the + scheduler - clients should not use the value of this constant + ("FAILED_OVER_JOBS") for thename of a 's group. + + + + + A constant key that can be used to retrieve the + name of the original from a recovery trigger's + data map in the case of a job recovering after a failed scheduler + instance. + + + + + + A constant key that can be used to retrieve the + group of the original from a recovery trigger's + data map in the case of a job recovering after a failed scheduler + instance. + + + + + + A constant key that can be used to retrieve the + scheduled fire time of the original from a recovery + trigger's data map in the case of a job recovering after a failed scheduler + instance. + + + + + + Holds context/environment data that can be made available to Jobs as they + are executed. + + + Future versions of Quartz may make distinctions on how it propagates + data in between instances of proxies to a + single scheduler instance - i.e. if Quartz is being used via WCF of Remoting. + + + James House + Marko Lahma (.NET) + + + + Create an empty . + + + + + Create a with the given data. + + + + + Serialization constructor. + + + + + + + Instructs Scheduler what to do with a trigger and job. + + Marko Lahma (.NET) + + + + Instructs the that the + has no further instructions. + + + + + Instructs the that the + wants the to re-Execute + immediately. If not in a 'RECOVERING' or 'FAILED_OVER' situation, the + execution context will be re-used (giving the the + ability to 'see' anything placed in the context by its last execution). + + + + + Instructs the that the + should be put in the state. + + + + + Instructs the that the + wants itself deleted. + + + + + Instructs the that all + s referencing the same as + this one should be put in the state. + + + + + Instructs the that all + s referencing the same as + this one should be put in the state. + + + + + Instructs the that the + should be put in the state. + + + + + Describes the settings and capabilities of a given + instance. + + James House + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + Name of the scheduler. + The scheduler instance. + The scheduler type. + if set to true, scheduler is a remote scheduler. + if set to true, scheduler is started. + if set to true, scheduler is in standby mode. + if set to true, scheduler is shutdown. + The start time. + The number of jobs executed. + The job store type. + if set to true, job store is persistent. + if set to true, the job store is clustered + The thread pool type. + Size of the thread pool. + The version string. + + + + Returns a formatted (human readable) string describing all the 's + meta-data values. + + + + The format of the string looks something like this: + 
+            Quartz Scheduler 'SchedulerName' with instanceId 'SchedulerInstanceId' Scheduler class: 'Quartz.Impl.StdScheduler' - running locally. Running since: '11:33am on Jul 19, 2002' Not currently paused. Number of Triggers fired: '123' Using thread pool 'Quartz.Simpl.SimpleThreadPool' - with '8' threads Using job-store 'Quartz.Impl.JobStore' - which supports persistence.
+
+ + + + + + Return a simple string representation of this object. + + + + + Returns the name of the . + + + + + Returns the instance Id of the . + + + + + Returns the class-name of the instance. + + + + + Returns whether the is being used remotely (via remoting). + + + + + Returns whether the scheduler has been started. + + + Note: may return even if + returns . + + + + + Reports whether the is in standby mode. + + + Note: may return even if + returns . + + + + + Reports whether the has been Shutdown. + + + + + Returns the class-name of the instance that is + being used by the . + + + + + Returns the type name of the instance that is + being used by the . + + + + + Returns the number of threads currently in the 's + + + + + Returns the version of Quartz that is running. + + + + + Returns the at which the Scheduler started running. + + null if the scheduler has not been started. + + + + + Returns the number of jobs executed since the + started.. + + + + + Returns whether or not the 's + instance supports persistence. + + + + + Returns whether or not the 's + is clustered. + + + + + SimpleScheduleBuilder is a + that defines strict/literal interval-based schedules for + s. + + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + Client code can then use the DSL to write code such as this: + + JobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + Trigger trigger = TriggerBuilder.Create() + .WithIdentity(triggerKey("myTrigger", "myTriggerGroup")) + .WithSimpleSchedule(x => x + .WithIntervalInHours(1) + .RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + + + + Create a SimpleScheduleBuilder. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat forever with a 1 minute interval. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat forever with an interval + of the given number of minutes. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat forever with a 1 second interval. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat forever with an interval + of the given number of seconds. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat forever with a 1 hour interval. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat forever with an interval + of the given number of hours. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat the given number + of times - 1 with a 1 minute interval. + + + Note: Total count = 1 (at start time) + repeat count + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat the given number + of times - 1 with an interval of the given number of minutes. + + + Note: Total count = 1 (at start time) + repeat count + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat the given number + of times - 1 with a 1 second interval. + + + Note: Total count = 1 (at start time) + repeat count + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat the given number + of times - 1 with an interval of the given number of seconds. + + + Note: Total count = 1 (at start time) + repeat count + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat the given number + of times - 1 with a 1 hour interval. + + + Note: Total count = 1 (at start time) + repeat count + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat the given number + of times - 1 with an interval of the given number of hours. + + + Note: Total count = 1 (at start time) + repeat count + + the new SimpleScheduleBuilder + + + + Build the actual Trigger -- NOT intended to be invoked by end users, + but will rather be invoked by a TriggerBuilder which this + ScheduleBuilder is given to. + + + + + + + + Specify a repeat interval in milliseconds. + + + + the time span at which the trigger should repeat. + the updated SimpleScheduleBuilder + + + + + + Specify a repeat interval in seconds. + + + + the time span at which the trigger should repeat. + the updated SimpleScheduleBuilder + + + + + + Specify a the number of time the trigger will repeat - total number of + firings will be this number + 1. + + + + the number of seconds at which the trigger should repeat. + the updated SimpleScheduleBuilder + + + + + + Specify that the trigger will repeat indefinitely. + + + + the updated SimpleScheduleBuilder + + + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CronScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated SimpleScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated SimpleScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated SimpleScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated SimpleScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated SimpleScheduleBuilder + + + + + Extension methods that attach to . + + + + + A time source for Quartz.NET that returns the current time. + Original idea by Ayende Rahien: + http://ayende.com/Blog/archive/2008/07/07/Dealing-with-time-in-tests.aspx + + + + + Return current UTC time via . Allows easier unit testing. + + + + + Return current time in current time zone via . Allows easier unit testing. + + + + + Represents a time in hour, minute and second of any given day. + + + The hour is in 24-hour convention, meaning values are from 0 to 23. + + + + + James House + Zemian Deng saltnlight5@gmail.com + Nuno Maia (.NET) + + + + Create a TimeOfDay instance for the given hour, minute and second. + + The hour of day, between 0 and 23. + The minute of the hour, between 0 and 59. + The second of the minute, between 0 and 59. + + + + Create a TimeOfDay instance for the given hour, minute (at the zero second of the minute). + + The hour of day, between 0 and 23. + The minute of the hour, between 0 and 59. + + + + Create a TimeOfDay instance for the given hour, minute and second. + + The hour of day, between 0 and 23. + The minute of the hour, between 0 and 59. + The second of the minute, between 0 and 59. + + + + + Create a TimeOfDay instance for the given hour, minute (at the zero second of the minute).. + + The hour of day, between 0 and 23. + The minute of the hour, between 0 and 59. + The newly instantiated TimeOfDay + + + + Determine with this time of day is before the given time of day. + + + True this time of day is before the given time of day. + + + + Return a date with time of day reset to this object values. The millisecond value will be zero. + + + + + + The hour of the day (between 0 and 23). + + + + + The minute of the hour (between 0 and 59). + + + + + The second of the minute (between 0 and 59). + + + + + Attribute to use with public properties that + can be set with Quartz configuration. Attribute can be used to advice + parsing to use correct type of time span (milliseconds, seconds, minutes, hours) + as it may depend on property. + + Marko Lahma (.NET) + + + + + Initializes a new instance of the class. + + The rule. + + + + Gets the rule. + + The rule. + + + + Possible parse rules for s. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TriggerBuilder is used to instantiate s. + + + + The builder will always try to keep itself in a valid state, with + reasonable defaults set for calling build() at any point. For instance + if you do not invoke WithSchedule(..) method, a default schedule + of firing once immediately will be used. As another example, if you + do not invoked WithIdentity(..) a trigger name will be generated + for you. + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + + Client code can then use the DSL to write code such as this: + + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + ITrigger trigger = TriggerBuilder.Create() + .WithIdentity("myTrigger", "myTriggerGroup") + .WithSimpleSchedule(x => x + .WithIntervalInHours(1) + .RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + + + Create a new TriggerBuilder with which to define a + specification for a Trigger. + + + + the new TriggerBuilder + + + + Produce the . + + + + a Trigger that meets the specifications of the builder. + + + + Use a with the given name and default group to + identify the Trigger. + + + If none of the 'withIdentity' methods are set on the TriggerBuilder, + then a random, unique TriggerKey will be generated. + + the name element for the Trigger's TriggerKey + the updated TriggerBuilder + + + + + + Use a TriggerKey with the given name and group to + identify the Trigger. + + + If none of the 'withIdentity' methods are set on the TriggerBuilder, + then a random, unique TriggerKey will be generated. + + the name element for the Trigger's TriggerKey + the group element for the Trigger's TriggerKey + the updated TriggerBuilder + + + + + + Use the given TriggerKey to identify the Trigger. + + + If none of the 'withIdentity' methods are set on the TriggerBuilder, + then a random, unique TriggerKey will be generated. + + the TriggerKey for the Trigger to be built + the updated TriggerBuilder + + + + + + Set the given (human-meaningful) description of the Trigger. + + + + the description for the Trigger + the updated TriggerBuilder + + + + + Set the Trigger's priority. When more than one Trigger have the same + fire time, the scheduler will fire the one with the highest priority + first. + + + + the priority for the Trigger + the updated TriggerBuilder + + + + + + Set the name of the that should be applied to this + Trigger's schedule. + + + + the name of the Calendar to reference. + the updated TriggerBuilder + + + + + + Set the time the Trigger should start at - the trigger may or may + not fire at this time - depending upon the schedule configured for + the Trigger. However the Trigger will NOT fire before this time, + regardless of the Trigger's schedule. + + + + the start time for the Trigger. + the updated TriggerBuilder + + + + + + Set the time the Trigger should start at to the current moment - + the trigger may or may not fire at this time - depending upon the + schedule configured for the Trigger. + + + + the updated TriggerBuilder + + + + + Set the time at which the Trigger will no longer fire - even if it's + schedule has remaining repeats. + + + + the end time for the Trigger. If null, the end time is indefinite. + the updated TriggerBuilder + + + + + + Set the that will be used to define the + Trigger's schedule. + + + The particular used will dictate + the concrete type of Trigger that is produced by the TriggerBuilder. + + the SchedulerBuilder to use. + the updated TriggerBuilder + + + + + + + + Set the identity of the Job which should be fired by the produced + Trigger. + + + + the identity of the Job to fire. + the updated TriggerBuilder + + + + + Set the identity of the Job which should be fired by the produced + Trigger - a will be produced with the given + name and default group. + + + + the name of the job (in default group) to fire. + the updated TriggerBuilder + + + + + Set the identity of the Job which should be fired by the produced + Trigger - a will be produced with the given + name and group. + + + + the name of the job to fire. + the group of the job to fire. + the updated TriggerBuilder + + + + + Set the identity of the Job which should be fired by the produced + Trigger, by extracting the JobKey from the given job. + + + + the Job to fire. + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Common constants for triggers. + + + + + The default value for priority. + + + + + Uniquely identifies a . + + + Keys are composed of both a name and group, and the name must be unique + within the group. If only a name is specified then the default group + name will be used. + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + + Client code can then use the DSL to write code such as this: + + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + ITrigger trigger = TriggerBuilder.Create() + .WithIdentity("myTrigger", "myTriggerGroup") + .WithSimpleSchedule(x => x + .WithIntervalInHours(1) + .RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + All trigger states known to Scheduler. + + Marko Lahma (.NET) + + + + Indicates that the is in the "normal" state. + + + + + Indicates that the is in the "paused" state. + + + + + Indicates that the is in the "complete" state. + + + "Complete" indicates that the trigger has not remaining fire-times in + its schedule. + + + + + Indicates that the is in the "error" state. + + + + A arrives at the error state when the scheduler + attempts to fire it, but cannot due to an error creating and executing + its related job. Often this is due to the 's + class not existing in the classpath. + + + + When the trigger is in the error state, the scheduler will make no + attempts to fire it. + + + + + + Indicates that the is in the "blocked" state. + + + A arrives at the blocked state when the job that + it is associated with has a and it is + currently executing. + + + + + + Indicates that the does not exist. + + + + + A Comparator that compares trigger's next fire times, or in other words, + sorts them according to earliest next fire time. If the fire times are + the same, then the triggers are sorted according to priority (highest + value first), if the priorities are the same, then they are sorted + by key. + + + + + Convenience and utility methods for simplifying the construction and + configuration of s and DateTimeOffsetOffsets. + + + + James House + Marko Lahma (.NET) + + + + Returns a list of Dates that are the next fire times of a + . + The input trigger will be cloned before any work is done, so you need + not worry about its state being altered by this method. + + The trigger upon which to do the work + The calendar to apply to the trigger's schedule + The number of next fire times to produce + List of java.util.Date objects + + + + Compute the that is 1 second after the Nth firing of + the given , taking the triger's associated + into consideration. + + + The input trigger will be cloned before any work is done, so you need + not worry about its state being altered by this method. + + The trigger upon which to do the work + The calendar to apply to the trigger's schedule + The number of next fire times to produce + the computed Date, or null if the trigger (as configured) will not fire that many times + + + + Returns a list of Dates that are the next fire times of a + that fall within the given date range. The input trigger will be cloned + before any work is done, so you need not worry about its state being + altered by this method. + + NOTE: if this is a trigger that has previously fired within the given + date range, then firings which have already occurred will not be listed + in the output List. + + + The trigger upon which to do the work + The calendar to apply to the trigger's schedule + The starting date at which to find fire times + The ending date at which to stop finding fire times + List of java.util.Date objects + + + + An exception that is thrown to indicate that a call to + failed without interrupting the Job. + + + James House + Marko Lahma (.NET) + + + + Create a with the given message. + + + + + Create a with the given cause. + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + diff --git a/Resources/Libraries/Quartz/Common.Logging.dll b/Resources/Libraries/Quartz/Common.Logging.dll new file mode 100644 index 00000000..5c1feac9 Binary files /dev/null and b/Resources/Libraries/Quartz/Common.Logging.dll differ diff --git a/Resources/Libraries/Quartz/Quartz.dll b/Resources/Libraries/Quartz/Quartz.dll new file mode 100644 index 00000000..9b35e47c Binary files /dev/null and b/Resources/Libraries/Quartz/Quartz.dll differ diff --git a/Resources/Libraries/Quartz/Quartz.pdb b/Resources/Libraries/Quartz/Quartz.pdb new file mode 100644 index 00000000..5fee49e8 Binary files /dev/null and b/Resources/Libraries/Quartz/Quartz.pdb differ diff --git a/Resources/Libraries/Quartz/Quartz.xml b/Resources/Libraries/Quartz/Quartz.xml new file mode 100644 index 00000000..de320e2a --- /dev/null +++ b/Resources/Libraries/Quartz/Quartz.xml @@ -0,0 +1,20066 @@ + + + + Quartz + + + + + A wrapper for generic HashSet that brings a common interface. + + + + + + Represents a collection ob objects that contains no duplicate elements. + + Marko Lahma (.NET) + + + + A sorted set. + + Marko Lahma (.NET) + + + + Returns a portion of the list whose elements are greater than the limit object parameter. + + The start element of the portion to extract. + The portion of the collection whose elements are greater than the limit object parameter. + + + + Returns the first item in the set. + + First object. + + + + Returns the object in the specified index. + + + + + + + Simple C5 wrapper for common interface. + + + + + + Default constructor. + + + + + Constructor that accepts comparer. + + Comparer to use. + + + + Constructor that prepolutates. + + + + + + Returns the first element. + + + + + + Return items from given range. + + + + + + + Indexer. + + + + + + + Only for backwards compatibility with serialization! + + + + + Responsible for creating the instances of + to be used within the instance. + + James House + Marko Lahma (.NET) + + + + Initialize the factory, providing a handle to the + that should be made available within the and + the s within it. + + + + + Called by the + to obtain instances of . + + + + + JobRunShell instances are responsible for providing the 'safe' environment + for s to run in, and for performing all of the work of + executing the , catching ANY thrown exceptions, updating + the with the 's completion code, + etc. + + A instance is created by a + on behalf of the which then runs the + shell in a thread from the configured when the + scheduler determines that a has been triggered. + + + + + + + James House + Marko Lahma (.NET) + + + + A helpful abstract base class for implementors of + . + + + The methods in this class are empty so you only need to override the + subset for the events you care about. + + Marko Lahma (.NET) + + + + + The interface to be implemented by classes that want to be informed of major + events. + + + + + James House + Marko Lahma (.NET) + + + + Called by the when a + is scheduled. + + + + + Called by the when a + is unscheduled. + + + + + + Called by the when a + has reached the condition in which it will never fire again. + + + + + Called by the a s has been paused. + + + + + Called by the a group of + s has been paused. + + + If a all groups were paused, then the parameter + will be null. + + The trigger group. + + + + Called by the when a + has been un-paused. + + + + + Called by the when a + group of s has been un-paused. + + + If all groups were resumed, then the parameter + will be null. + + The trigger group. + + + + Called by the when a + has been added. + + + + + + Called by the when a + has been deleted. + + + + + Called by the when a + has been paused. + + + + + Called by the when a + group of s has been paused. + + If all groups were paused, then the parameter will be + null. If all jobs were paused, then both parameters will be null. + + + The job group. + + + + Called by the when a + has been un-paused. + + + + + Called by the when a + has been un-paused. + + The job group. + + + + Called by the when a serious error has + occurred within the scheduler - such as repeated failures in the , + or the inability to instantiate a instance when its + has fired. + + + + + Called by the to inform the listener + that it has move to standby mode. + + + + + Called by the to inform the listener + that it has started. + + + + + Called by the to inform the listener + that it has Shutdown. + + + + + Called by the to inform the listener + that it has begun the shutdown sequence. + + + + + Called by the to inform the listener + that all jobs, triggers and calendars were deleted. + + + + + Get the for this + type's category. This should be used by subclasses for logging. + + + + + This interface should be implemented by any class whose instances are intended + to be executed by a thread. + + Marko Lahma (.NET) + + + + This method has to be implemented in order that starting of the thread causes the object's + run method to be called in that separately executing thread. + + + + + Create a JobRunShell instance with the given settings. + + The instance that should be made + available within the . + + + + + Initializes the job execution context with given scheduler and bundle. + + The scheduler. + + + + Requests the Shutdown. + + + + + This method has to be implemented in order that starting of the thread causes the object's + run method to be called in that separately executing thread. + + + + + Runs begin procedures on this instance. + + + + + Completes the execution. + + if set to true [successful execution]. + + + + Passivates this instance. + + + + + Completes the trigger retry loop. + + The trigger. + The job detail. + The inst code. + + + + + Vetoeds the job retry loop. + + The trigger. + The job detail. + The inst code. + + + + + Default concrete implementation of . + + + + + Client programs may be interested in the 'listener' interfaces that are + available from Quartz. The interface + provides notifications of Job executions. The + interface provides notifications of + firings. The + interface provides notifications of scheduler events and + errors. Listeners can be associated with local schedulers through the + interface. + + + + jhouse + 2.0 - previously listeners were managed directly on the Scheduler interface. + + + + Add the given to the, + and register it to receive events for Jobs that are matched by ANY of the + given Matchers. + + + If no matchers are provided, the will be used. + + + + + + + Add the given to the, + and register it to receive events for Jobs that are matched by ANY of the + given Matchers. + + + If no matchers are provided, the will be used. + + + + + + + Add the given Matcher to the set of matchers for which the listener + will receive events if ANY of the matchers match. + + + + the name of the listener to add the matcher to + the additional matcher to apply for selecting events + true if the identified listener was found and updated + + + + Remove the given Matcher to the set of matchers for which the listener + will receive events if ANY of the matchers match. + + + + the name of the listener to add the matcher to + the additional matcher to apply for selecting events + true if the given matcher was found and removed from the listener's list of matchers + + + + Set the set of Matchers for which the listener + will receive events if ANY of the matchers match. + + + Removes any existing matchers for the identified listener! + + the name of the listener to add the matcher to + the matchers to apply for selecting events + true if the given matcher was found and removed from the listener's list of matchers + + + + Get the set of Matchers for which the listener + will receive events if ANY of the matchers match. + + + + the name of the listener to add the matcher to + the matchers registered for selecting events for the identified listener + + + + Remove the identified from the. + + + + true if the identified listener was found in the list, and removed. + + + + Get a List containing all of the s in + the. + + + + + Get the that has the given name. + + + + + Add the given to the, + and register it to receive events for Triggers that are matched by ANY of the + given Matchers. + + + If no matcher is provided, the will be used. + + + + + + + Add the given to the, + and register it to receive events for Triggers that are matched by ANY of the + given Matchers. + + + If no matcher is provided, the will be used. + + + + + + + Add the given Matcher to the set of matchers for which the listener + will receive events if ANY of the matchers match. + + + + the name of the listener to add the matcher to + the additional matcher to apply for selecting events + true if the identified listener was found and updated + + + + Remove the given Matcher to the set of matchers for which the listener + will receive events if ANY of the matchers match. + + + + the name of the listener to add the matcher to + the additional matcher to apply for selecting events + true if the given matcher was found and removed from the listener's list of matchers + + + + Set the set of Matchers for which the listener + will receive events if ANY of the matchers match. + + + Removes any existing matchers for the identified listener! + + the name of the listener to add the matcher to + the matchers to apply for selecting events + true if the given matcher was found and removed from the listener's list of matchers + + + + Get the set of Matchers for which the listener + will receive events if ANY of the matchers match. + + + + the name of the listener to add the matcher to + the matchers registered for selecting events for the identified listener + + + + Remove the identified from the. + + + + true if the identified listener was found in the list, and + removed. + + + + Get a List containing all of the s + in the. + + + + + Get the that has the given name. + + + + + Register the given with the + . + + + + + Remove the given from the + . + + + + true if the identified listener was found in the list, and removed. + + + + Get a List containing all of the s + registered with the. + + + + + This is the heart of Quartz, an indirect implementation of the + interface, containing methods to schedule s, + register instances, etc. + + + + + + James House + Marko Lahma (.NET) + + + + Remote scheduler service interface. + + Marko Lahma (.NET) + + + + Starts this instance. + + + + + Standbies this instance. + + + + + Shutdowns this instance. + + + + + returns true if the given JobGroup + is paused + + + + + + + returns true if the given TriggerGroup + is paused + + + + + + + Initializes the class. + + + + + Register the given with the + 's list of internal listeners. + + + + + + Remove the given from the + 's list of internal listeners. + + + true if the identified listener was found in the list, andremoved. + + + + Create a with the given configuration + properties. + + + + + + Bind the scheduler to remoting infrastructure. + + + + + Un-bind the scheduler from remoting infrastructure. + + + + + Adds an object that should be kept as reference to prevent + it from being garbage collected. + + The obj. + + + + Removes the object from garbae collection protected list. + + The obj. + + + + + Starts the 's threads that fire s. + + All s that have misfired will + be passed to the appropriate TriggerListener(s). + + + + + + Temporarily halts the 's firing of s. + + The scheduler is not destroyed, and can be re-started at any time. + + + + + + Halts the 's firing of s, + and cleans up all resources associated with the QuartzScheduler. + Equivalent to . + + The scheduler cannot be re-started. + + + + + + Halts the 's firing of s, + and cleans up all resources associated with the QuartzScheduler. + + The scheduler cannot be re-started. + + + + if the scheduler will not allow this method + to return until all currently executing jobs have completed. + + + + + Validates the state. + + + + + Add the identified by the given + to the Scheduler, and + associate the given with it. + + If the given Trigger does not reference any , then it + will be set to reference the Job passed with it into this method. + + + + + + Schedule the given with the + identified by the 's settings. + + + + + Add the given to the Scheduler - with no associated + . The will be 'dormant' until + it is scheduled with a , or + is called for it. + + The must by definition be 'durable', if it is not, + SchedulerException will be thrown. + + + + + + Delete the identified from the Scheduler - and any + associated s. + + true if the Job was found and deleted. + + + + Remove the indicated from the + scheduler. + + + + + Remove (delete) the with the + given name, and store the new given one - which must be associated + with the same job. + + the key of the trigger + The new to be stored. + + if a with the given + name and group was not found and removed from the store, otherwise + the first fire time of the newly scheduled trigger. + + + + + Creates a new positive random number + + The last random obtained + Returns a new positive random number + + + + Trigger the identified (Execute it now) - with a non-volatile trigger. + + + + + Store and schedule the identified + + + + + + Pause the with the given name. + + + + + Pause all of the s in the given group. + + + + + Pause the with the given + name - by pausing all of its current s. + + + + + Pause all of the s in the + given group - by pausing all of their s. + + + + + Resume (un-pause) the with the given + name. + + If the missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Resume (un-pause) all of the s in the + matching groups. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Gets the paused trigger groups. + + + + + + Resume (un-pause) the with + the given name. + + If any of the 's s missed one + or more fire-times, then the 's misfire + instruction will be applied. + + + + + + Resume (un-pause) all of the s + in the matching groups. + + If any of the s had s that + missed one or more fire-times, then the 's + misfire instruction will be applied. + + + + + + Pause all triggers - equivalent of calling + with a matcher matching all known groups. + + When is called (to un-pause), trigger misfire + instructions WILL be applied. + + + + + + + + Resume (un-pause) all triggers - equivalent of calling + on every group. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + + Get the names of all known groups. + + + + + Get the names of all the s in the + given group. + + + + + Get all s that are associated with the + identified . + + + + + Get the names of all known + groups. + + + + + Get the names of all the s in + the matching groups. + + + + + Get the for the + instance with the given name and group. + + + + + Get the instance with the given name and + group. + + + + + Determine whether a with the given identifier already + exists within the scheduler. + + + + the identifier to check for + true if a Job exists with the given identifier + + + + Determine whether a with the given identifier already + exists within the scheduler. + + + + the identifier to check for + true if a Trigger exists with the given identifier + + + + Clears (deletes!) all scheduling data - all s, s + s. + + + + + Get the current state of the identified . + + + + + + Add (register) the given to the Scheduler. + + + + + Delete the identified from the Scheduler. + + true if the Calendar was found and deleted. + + + + Get the instance with the given name. + + + + + Get the names of all registered s. + + + + + Add the given to the + 's internal list. + + + + + + Remove the identified from the 's + list of internal listeners. + + + true if the identified listener was found in the list, and removed. + + + + Get the internal + that has the given name. + + + + + + + Add the given to the + 's internal list. + + + + + + Remove the identified from the 's + list of internal listeners. + + + true if the identified listener was found in the list, and removed. + + + + Get the internal that + has the given name. + + + + + + + Notifies the job store job complete. + + The trigger. + The detail. + The instruction code. + + + + Notifies the scheduler thread. + + + + + Notifies the trigger listeners about fired trigger. + + The job execution context. + + + + + Notifies the trigger listeners about misfired trigger. + + The trigger. + + + + Notifies the trigger listeners of completion. + + The job executution context. + The instruction code to report to triggers. + + + + Notifies the job listeners about job to be executed. + + The jec. + + + + Notifies the job listeners that job exucution was vetoed. + + The job execution context. + + + + Notifies the job listeners that job was executed. + + The jec. + The je. + + + + Notifies the scheduler listeners about scheduler error. + + The MSG. + The se. + + + + Notifies the scheduler listeners about job that was scheduled. + + The trigger. + + + + Notifies the scheduler listeners about job that was unscheduled. + + + + + Notifies the scheduler listeners about finalized trigger. + + The trigger. + + + + Notifies the scheduler listeners about paused trigger. + + The group. + + + + Notifies the scheduler listeners about paused trigger. + + + + + Notifies the scheduler listeners resumed trigger. + + The group. + + + + Notifies the scheduler listeners resumed trigger. + + + + + Notifies the scheduler listeners about paused job. + + + + + Notifies the scheduler listeners about paused job. + + The group. + + + + Notifies the scheduler listeners about resumed job. + + + + + Notifies the scheduler listeners about resumed job. + + The group. + + + + Notifies the scheduler listeners about scheduler shutdown. + + + + + Interrupt all instances of the identified InterruptableJob. + + + + + Interrupt all instances of the identified InterruptableJob executing in this Scheduler instance. + + + This method is not cluster aware. That is, it will only interrupt + instances of the identified InterruptableJob currently executing in this + Scheduler instance, not across the entire cluster. + + + + + + + + Obtains a lifetime service object to control the lifetime policy for this instance. + + + + + Gets the version of the Quartz Scheduler. + + The version. + + + + Gets the version major. + + The version major. + + + + Gets the version minor. + + The version minor. + + + + Gets the version iteration. + + The version iteration. + + + + Gets the scheduler signaler. + + The scheduler signaler. + + + + Returns the name of the . + + + + + Returns the instance Id of the . + + + + + Returns the of the . + + + + + Gets or sets a value indicating whether to signal on scheduling change. + + + true if schduler should signal on scheduling change; otherwise, false. + + + + + Reports whether the is paused. + + + + + Gets the job store class. + + The job store class. + + + + Gets the thread pool class. + + The thread pool class. + + + + Gets the size of the thread pool. + + The size of the thread pool. + + + + Reports whether the has been Shutdown. + + + + + Return a list of objects that + represent all currently executing Jobs in this Scheduler instance. + + This method is not cluster aware. That is, it will only return Jobs + currently executing in this Scheduler instance, not across the entire + cluster. + + + Note that the list returned is an 'instantaneous' snap-shot, and that as + soon as it's returned, the true list of executing jobs may be different. + + + + + + Get a List containing all of the internal s + registered with the . + + + + + Gets or sets the job factory. + + The job factory. + + + + Gets the running since. + + The running since. + + + + Gets the number of jobs executed. + + The number of jobs executed. + + + + Gets a value indicating whether this scheduler supports persistence. + + true if supports persistence; otherwise, false. + + + + Get a List containing all of the s + in the 's internal list. + + + + + + Get a list containing all of the s + in the 's internal list. + + + + + Helper class to start scheduler in a delayed fashion. + + + + + ErrorLogger - Scheduler Listener Class + + + + + The interface to be implemented by classes that want to be informed when a + executes. In general, applications that use a + will not have use for this mechanism. + + + + + + + + James House + Marko Lahma (.NET) + + + + Called by the when a + is about to be executed (an associated + has occurred). + + This method will not be invoked if the execution of the Job was vetoed + by a . + + + + + + + Called by the when a + was about to be executed (an associated + has occurred), but a vetoed it's + execution. + + + + + + Called by the after a + has been executed, and be for the associated 's + method has been called. + + + + + Get the name of the . + + + + + Contains all of the resources (,, + etc.) necessary to create a instance. + + + James House + Marko Lahma (.NET) + + + + Gets the unique identifier. + + Name of the scheduler. + The scheduler instance id. + + + + + Gets the unique identifier. + + + + + + Add the given for the + to use. This method expects the plugin's + "initialize" method to be invoked externally (either before or after + this method is called). + + + + + + Get or set the name for the . + + + if name is null or empty. + + + + + Get or set the instance Id for the . + + + if name is null or empty. + + + + + Get or set the name for the . + + + if name is null or empty. + + + + + Get or set the for the + to use. + + + if threadPool is null. + + + + + Get or set the for the + to use. + + + if jobStore is null. + + + + + Get or set the for the + to use. + + + if jobRunShellFactory is null. + + + + + Get the of all s for the + to use. + + + + + + Gets or sets a value indicating whether to make scheduler thread daemon. + + + true if scheduler should be thread daemon; otherwise, false. + + + + + Gets or sets the scheduler exporter. + + The scheduler exporter. + + + + The ThreadExecutor which runs the QuartzSchedulerThread. + + + + + Gets or sets the batch time window. + + + + + The thread responsible for performing the work of firing + s that are registered with the . + + + + + James House + Marko Lahma (.NET) + + + + Support class used to handle threads + + Marko Lahma (.NET) + + + + The instance of System.Threading.Thread + + + + + Initializes a new instance of the QuartzThread class + + + + + Initializes a new instance of the Thread class. + + The name of the thread + + + + This method has no functionality unless the method is overridden + + + + + Causes the operating system to change the state of the current thread instance to ThreadState.Running + + + + + Interrupts a thread that is in the WaitSleepJoin thread state + + + + + Blocks the calling thread until a thread terminates + + + + + Obtain a string that represents the current object + + A string that represents the current object + + + + Gets or sets the name of the thread + + + + + Gets or sets a value indicating the scheduling priority of a thread + + + + + Gets or sets a value indicating whether or not a thread is a background thread. + + + + + Gets the randomized idle wait time. + + The randomized idle wait time. + + + + Construct a new for the given + as a non-daemon + with normal priority. + + + + + Construct a new for the given + as a with the given + attributes. + + + + + Signals the main processing loop to pause at the next possible point. + + + + + Signals the main processing loop to pause at the next possible point. + + + + + Signals the main processing loop that a change in scheduling has been + made - in order to interrupt any sleeping that may be occuring while + waiting for the fire time to arrive. + + + the time when the newly scheduled trigger + will fire. If this method is being called do to some other even (rather + than scheduling a trigger), the caller should pass null. + + + + + The main processing loop of the . + + + + + Trigger retry loop that is executed on error condition. + + The bndle. + + + + Releases the trigger retry loop. + + The trigger. + + + + Gets the log. + + The log. + + + + Sets the idle wait time. + + The idle wait time. + + + + Gets a value indicating whether this is paused. + + true if paused; otherwise, false. + + + + Gets or sets the db failure retry interval. + + The db failure retry interval. + + + + An interface to be used by instances in order to + communicate signals back to the . + + James House + Marko Lahma (.NET) + + + + An interface to be used by instances in order to + communicate signals back to the . + + James House + Marko Lahma (.NET) + + + + Notifies the scheduler about misfired trigger. + + The trigger that misfired. + + + + Notifies the scheduler about finalized trigger. + + The trigger that has finalized. + + + + Signals the scheduling change. + + + + + Notifies the scheduler about misfired trigger. + + The trigger that misfired. + + + + Notifies the scheduler about finalized trigger. + + The trigger that has finalized. + + + + Signals the scheduling change. + + + + + Metadata information about specific ADO.NET driver library. Metadata is used to + create correct types of object instances to interact with the underlying + database. + + Marko Lahma + + + + Initializes this instance. Parses information and initializes startup + values. + + + + + Gets the name of the parameter which includes the parameter prefix for this + database. + + Name of the parameter. + + + Gets or sets the name of the assembly that holds the connection library. + The name of the assembly. + + + + Gets or sets the name of the product. + + The name of the product. + + + + Gets or sets the type of the connection. + + The type of the connection. + + + + Gets or sets the type of the command. + + The type of the command. + + + + Gets or sets the type of the parameter. + + The type of the parameter. + + + + Gets the type of the command builder. + + The type of the command builder. + + + Gets the command builder's derive parameters method. + The command builder derive parameters method. + + + + Gets or sets the parameter name prefix. + + The parameter name prefix. + + + + Gets or sets the type of the exception that is thrown when using driver + library. + + The type of the exception. + + + + Gets or sets a value indicating whether parameters are bind by name when using + ADO.NET parameters. + + true if parameters are bind by name; otherwise, false. + + + Gets or sets the type of the database parameters. + The type of the parameter db. + + + + Gets the parameter db type property. + + The parameter db type property. + + + + Gets the parameter is nullable property. + + The parameter is nullable property. + + + + Gets or sets the type of the db binary column. This is a string representation of + Enum element because this information is database driver specific. + + The type of the db binary. + + + Gets the type of the db binary. + The type of the db binary. + + + + Sets the name of the parameter db type property. + + The name of the parameter db type property. + + + + Gets or sets a value indicating whether [use parameter name prefix in parameter collection]. + + + true if [use parameter name prefix in parameter collection]; otherwise, false. + + + + + Concrete implementation of . + + Marko Lahma + + + + Data access provider interface. + + Marko Lahma + + + + Returns a new command object for executing SQL statments/Stored Procedures + against the database. + + An new + + + + Returns a new instance of the providers CommandBuilder class. + + In .NET 1.1 there was no common base class or interface + for command builders, hence the return signature is object to + be portable (but more loosely typed) across .NET 1.1/2.0 + A new Command Builder + + + + Returns a new connection object to communicate with the database. + + A new + + + + Returns a new parameter object for binding values to parameter + placeholders in SQL statements or Stored Procedure variables. + + A new + + + + Shutdowns this instance. + + + + + Connection string used to create connections. + + + + + Registers DB metadata information for given provider name. + + + + + + + Initializes a new instance of the class. + + Name of the db provider. + The connection string. + + + + Returns a new command object for executing SQL statments/Stored Procedures + against the database. + + An new + + + + Returns a new instance of the providers CommandBuilder class. + + A new Command Builder + In .NET 1.1 there was no common base class or interface + for command builders, hence the return signature is object to + be portable (but more loosely typed) across .NET 1.1/2.0 + + + + Returns a new connection object to communicate with the database. + + A new + + + + Returns a new parameter object for binding values to parameter + placeholders in SQL statements or Stored Procedure variables. + + A new + + + + Shutdowns this instance. + + + + + Connection string used to create connections. + + + + + + Gets the metadata. + + The metadata. + + + + This interface can be implemented by any + class that needs to use the constants contained herein. + + Jeffrey Wescott + James House + Marko Lahma(.NET) + + + + Simple Trigger type. + + + + + Cron Trigger type. + + + + + Calendar Interval Trigger type. + + + + + Daily Time Interval Trigger type. + + + + + A general blob Trigger type. + + + + + This class contains utility functions for use in all delegate classes. + + Jeffrey Wescott + Marko Lahma (.NET) + + + + Replace the table prefix in a query by replacing any occurrences of + "{0}" with the table prefix. + + The unsubstitued query + The table prefix + the scheduler name + The query, with proper table prefix substituted + + + + Common helper methods for working with ADO.NET. + + Marko Lahma + + + + Persist a CalendarIntervalTriggerImpl by converting internal fields to and from + SimplePropertiesTriggerProperties. + + + + + + + A base implementation of that persists + trigger fields in the "QRTZ_SIMPROP_TRIGGERS" table. This allows extending + concrete classes to simply implement a couple methods that do the work of + getting/setting the trigger's fields, and creating the + for the particular type of trigger. + + + jhouse + Marko Lahma (.NET) + + + + An interface which provides an implementation for storing a particular + type of 's extended properties. + + jhouse + + + + Initializes the persistence delegate. + + + + + Returns whether the trigger type can be handled by delegate. + + + + + Returns database discriminator value for trigger type. + + + + + Inserts trigger's special properties. + + + + + Updates trigger's special properties. + + + + + Deletes trigger's special properties. + + + + + Loads trigger's special properties. + + + + + Returns whether the trigger type can be handled by delegate. + + + + + Returns database discriminator value for trigger type. + + + + + Utility class to keep track of both active transaction + and connection. + + Marko Lahma + + + + Initializes a new instance of the class. + + The connection. + The transaction. + + + + Gets or sets the connection. + + The connection. + + + + Gets or sets the transaction. + + The transaction. + + + + Persist a CronTriggerImpl. + + + + + + + Persist a DailyTimeIntervalTrigger by converting internal fields to and from + SimplePropertiesTriggerProperties. + + + + Zemian Deng saltnlight5@gmail.com + Nuno Maia (.NET) + + + + + + + + + + Base class for database based lock handlers for providing thread/resource locking + in order to protect resources from being altered by multiple threads at the + same time. + + Marko Lahma (.NET) + + + + This class extends + to include the query string constants in use by the + class. + + Jeffrey Wescott + Marko Lahma (.NET) + + + + An interface for providing thread/resource locking in order to protect + resources from being altered by multiple threads at the same time. + + James House + Marko Lahma (.NET) + + + + Grants a lock on the identified resource to the calling thread (blocking + until it is available). + + true if the lock was obtained. + + + + Release the lock on the identified resource if it is held by the calling + thread. + + + + + Determine whether the calling thread owns a lock on the identified + resource. + + + + + Whether this Semaphore implementation requires a database connection for + its lock management operations. + + + + + + + + Interface for Quartz objects that need to know what the table prefix of + the tables used by a ADO.NET JobStore is. + + Marko Lahma (.NET) + + + + Table prefix to use. + + + + + Initializes a new instance of the class. + + The table prefix. + the scheduler name + The SQL. + The default SQL. + The db provider. + + + + Execute the SQL that will lock the proper database row. + + + + + + + + + Grants a lock on the identified resource to the calling thread (blocking + until it is available). + + + + + true if the lock was obtained. + + + + Release the lock on the identified resource if it is held by the calling + thread. + + + + + + + Determine whether the calling thread owns a lock on the identified + resource. + + + + + + + + Gets or sets the lock owners. + + The lock owners. + + + + Gets the log. + + The log. + + + + This Semaphore implementation does use the database. + + + + + Gets or sets the table prefix. + + The table prefix. + + + + Initialization argumens holder for implementations. + + + + + Whether simple should be used (for serialization safety). + + + + + The logger to use during execution. + + + + + The prefix of all table names. + + + + + The instance's name. + + + + + The instance id. + + + + + The db provider. + + + + + The type loading strategy. + + + + + Object serializer and deserializer strategy to use. + + + + + Custom driver delegate initialization. + + + initStrings are of the format: + settingName=settingValue|otherSettingName=otherSettingValue|... + + + + + Conveys the state of a fired-trigger record. + + James House + Marko Lahma (.NET) + + + + Gets or sets the fire instance id. + + The fire instance id. + + + + Gets or sets the fire timestamp. + + The fire timestamp. + + + + Gets or sets a value indicating whether job disallows concurrent execution. + + + + + Gets or sets the job key. + + The job key. + + + + Gets or sets the scheduler instance id. + + The scheduler instance id. + + + + Gets or sets the trigger key. + + The trigger key. + + + + Gets or sets the state of the fire instance. + + The state of the fire instance. + + + + Gets or sets a value indicating whether [job requests recovery]. + + true if [job requests recovery]; otherwise, false. + + + + Gets or sets the priority. + + The priority. + + + + Service interface or modifying parameters + and resultset values. + + + + + Prepares a to be used to access database. + + Connection and tranasction pair + SQL to run + + + + + Adds a parameter to . + + Command to add parameter to + Parameter's name + Parameter's value + + + + Adds a parameter to . + + Command to add parameter to + Parameter's name + Parameter's value + Parameter's data type + + + + Gets the db presentation for boolean value. Subclasses can overwrite this behaviour. + + Value to map to database. + + + + + Gets the boolean value from db presentation. Subclasses can overwrite this behaviour. + + Value to map from database. + + + + + Gets the db presentation for date/time value. Subclasses can overwrite this behaviour. + + Value to map to database. + + + + + Gets the date/time value from db presentation. Subclasses can overwrite this behaviour. + + Value to map from database. + + + + + Gets the db presentation for time span value. Subclasses can overwrite this behaviour. + + Value to map to database. + + + + + Gets the time span value from db presentation. Subclasses can overwrite this behaviour. + + Value to map from database. + + + + + This is the base interface for all driver delegate classes. + + + + This interface is very similar to the + interface except each method has an additional + parameter. + + + Unless a database driver has some extremely-DB-specific + requirements, any IDriverDelegate implementation classes should extend the + class. + + + Jeffrey Wescott + James House + Marko Lahma (.NET) + + + + Initializes the driver delegate with configuration data. + + + + + + Update all triggers having one of the two given states, to the given new + state. + + The DB Connection + The new state for the triggers + The first old state to update + The second old state to update + Number of rows updated + + + + Get the names of all of the triggers that have misfired - according to + the given timestamp. + + The DB Connection + The timestamp. + An array of objects + + + + Get the names of all of the triggers in the given state that have + misfired - according to the given timestamp. + + The DB Connection + The state. + The time stamp. + An array of objects + + + + Get the names of all of the triggers in the given group and state that + have misfired - according to the given timestamp. + + The DB Connection + Name of the group. + The state. + The timestamp. + An array of objects + + + + Select all of the triggers for jobs that are requesting recovery. The + returned trigger objects will have unique "recoverXXX" trigger names and + will be in the trigger group. + + + In order to preserve the ordering of the triggers, the fire time will be + set from the ColumnFiredTime column in the TableFiredTriggers + table. The caller is responsible for calling + on each returned trigger. It is also up to the caller to insert the + returned triggers to ensure that they are fired. + + The DB Connection + An array of objects + + + + Delete all fired triggers. + + The DB Connection + The number of rows deleted + + + + Delete all fired triggers of the given instance. + + The DB Connection + The instance id. + The number of rows deleted + + + + Insert the job detail record. + + The DB Connection + The job to insert. + Number of rows inserted. + + + + Update the job detail record. + + The DB Connection. + The job to update. + Number of rows updated. + + + + Get the names of all of the triggers associated with the given job. + + + + The DB Connection + The key identifying the job. + + + + Delete the job detail record for the given job. + + The DB Connection + The key identifying the job. + the number of rows deleted + + + + Check whether or not the given job is stateful. + + The DB Connection + The key identifying the job. + true if the job exists and is stateful, false otherwise + + + + Check whether or not the given job exists. + + The DB Connection + The key identifying the job. + true if the job exists, false otherwise + + + + Update the job data map for the given job. + + The DB Connection + The job. + the number of rows updated + + + + Select the JobDetail object for a given job name / group name. + + The DB Connection + The key identifying the job. + The class load helper. + The populated JobDetail object + + + + Select the total number of jobs stored. + + The DB Connection + the total number of jobs stored + + + + Select all of the job group names that are stored. + + The DB Connection. + an array of group names + + + + Select all of the jobs contained in a given group. + + The DB Connection + + an array of job names + + + + Insert the base trigger data. + + The DB Connection + The trigger to insert. + The state that the trigger should be stored in. + The job detail. + The number of rows inserted + + + + Insert the blob trigger data. + + The DB Connection + The trigger to insert + The number of rows inserted + + + + Update the base trigger data. + + the DB Connection + The trigger. + The state. + The job detail. + the number of rows updated + + + + Update the blob trigger data. + + the DB Connection + The trigger. + the number of rows updated + + + + Check whether or not a trigger exists. + + the DB Connection + The key identifying the trigger. + the number of rows updated + + + + Update the state for a given trigger. + + The DB Connection + The key identifying the trigger. + The new state for the trigger. + the number of rows updated + + + + Update the given trigger to the given new state, if it is in the given + old state. + + The DB connection + The key identifying the trigger. + The new state for the trigger + The old state the trigger must be in + int the number of rows updated + + + + Update the given trigger to the given new state, if it is one of the + given old states. + + The DB connection + The key identifying the trigger. + The new state for the trigger + One of the old state the trigger must be in + One of the old state the trigger must be in + One of the old state the trigger must be in + + int the number of rows updated + + SQLException + + + + Update all triggers in the given group to the given new state, if they + are in one of the given old states. + + The DB connection + + The new state for the trigger + One of the old state the trigger must be in + One of the old state the trigger must be in + One of the old state the trigger must be in + The number of rows updated + + + + Update all of the triggers of the given group to the given new state, if + they are in the given old state. + + The DB connection + + The new state for the trigger group + The old state the triggers must be in. + int the number of rows updated + + + + Update the states of all triggers associated with the given job. + + The DB Connection + The key identifying the job. + The new state for the triggers. + The number of rows updated + + + + Update the states of any triggers associated with the given job, that + are the given current state. + + The DB Connection + The key identifying the job. + The new state for the triggers + The old state of the triggers + the number of rows updated + + + + Delete the BLOB trigger data for a trigger. + + The DB Connection + The key identifying the trigger. + The number of rows deleted + + + + Delete the base trigger data for a trigger. + + The DB Connection + The key identifying the trigger. + the number of rows deleted + + + + Select the number of triggers associated with a given job. + + The DB Connection + The key identifying the job. + the number of triggers for the given job + + + + Select the job to which the trigger is associated. + + The DB Connection + The key identifying the trigger. + The load helper. + + The object associated with the given trigger + + + + + Select the triggers for a job> + + The DB Connection + The key identifying the job. + an array of objects associated with a given job. + + + + Select the triggers for a calendar + + The DB Connection. + Name of the calendar. + + An array of objects associated with a given job. + + + + + Select a trigger. + + The DB Connection. + The key identifying the trigger. + The object. + + + + + Select a trigger's JobDataMap. + + The DB Connection. + The key identifying the trigger. + The of the Trigger, never null, but possibly empty. + + + + Select a trigger's state value. + + The DB Connection. + The key identifying the trigger. + The object. + + + + Select a triggers status (state and next fire time). + + The DB Connection. + The key identifying the trigger. + A object, or null + + + + Select the total number of triggers stored. + + The DB Connection. + The total number of triggers stored. + + + + Select all of the trigger group names that are stored. + + The DB Connection. + An array of group names. + + + + Select all of the triggers contained in a given group. + + The DB Connection. + + An array of trigger names. + + + + Select all of the triggers in a given state. + + The DB Connection. + The state the triggers must be in. + An array of trigger s. + + + + Inserts the paused trigger group. + + The conn. + Name of the group. + + + + + Deletes the paused trigger group. + + The conn. + Name of the group. + + + + + Deletes all paused trigger groups. + + The conn. + + + + + Determines whether the specified trigger group is paused. + + The conn. + Name of the group. + + true if trigger group is paused; otherwise, false. + + + + + Selects the paused trigger groups. + + The DB Connection. + + + + + Determines whether given trigger group already exists. + + The conn. + Name of the group. + + true if trigger group exists; otherwise, false. + + + + + Insert a new calendar. + + The DB Connection. + The name for the new calendar. + The calendar. + The number of rows inserted. + + + + Update a calendar. + + The DB Connection. + The name for the new calendar. + The calendar. + The number of rows updated. + + + + Check whether or not a calendar exists. + + The DB Connection. + The name of the calendar. + true if the trigger exists, false otherwise. + + + + Select a calendar. + + The DB Connection. + The name of the calendar. + The Calendar. + + + + Check whether or not a calendar is referenced by any triggers. + + The DB Connection. + The name of the calendar. + true if any triggers reference the calendar, false otherwise + + + + Delete a calendar. + + The DB Connection + The name of the trigger. + The number of rows deleted. + + + + Select the total number of calendars stored. + + The DB Connection + The total number of calendars stored. + + + + Select all of the stored calendars. + + The DB Connection + An array of calendar names. + + + + Select the trigger that will be fired at the given fire time. + + The DB Connection + The time that the trigger will be fired. + + A representing the + trigger that will be fired at the given fire time, or null if no + trigger will be fired at that time + + + + + Insert a fired trigger. + + The DB Connection + The trigger. + The state that the trigger should be stored in. + The job detail. + The number of rows inserted. + + + + Select the states of all fired-trigger records for a given trigger, or + trigger group if trigger name is . + + The DB Connection + Name of the trigger. + Name of the group. + A list of FiredTriggerRecord objects. + + + + Select the states of all fired-trigger records for a given job, or job + group if job name is . + + The DB Connection + Name of the job. + Name of the group. + A List of FiredTriggerRecord objects. + + + + Select the states of all fired-trigger records for a given scheduler + instance. + + The DB Connection + Name of the instance. + A list of FiredTriggerRecord objects. + + + + Delete a fired trigger. + + The DB Connection + The fired trigger entry to delete. + The number of rows deleted. + + + + Get the number instances of the identified job currently executing. + + The DB Connection + The key identifying the job. + + The number instances of the identified job currently executing. + + + + + Insert a scheduler-instance state record. + + The DB Connection + The instance id. + The check in time. + The interval. + The number of inserted rows. + + + + Delete a scheduler-instance state record. + + The DB Connection + The instance id. + The number of deleted rows. + + + + Update a scheduler-instance state record. + + The DB Connection + The instance id. + The check in time. + The number of updated rows. + + + + A List of all current s. + + If instanceId is not null, then only the record for the identified + instance will be returned. + + + The DB Connection + The instance id. + + + + + Select the next trigger which will fire to fire between the two given timestamps + in ascending order of fire time, and then descending by priority. + + The conn. + highest value of of the triggers (exclusive) + highest value of of the triggers (inclusive) + maximum number of trigger keys allow to acquired in the returning list. + A (never null, possibly empty) list of the identifiers (Key objects) of the next triggers to be fired. + + + + Select the distinct instance names of all fired-trigger records. + + + This is useful when trying to identify orphaned fired triggers (a + fired trigger without a scheduler state record.) + + The conn. + + + + + Counts the misfired triggers in states. + + The conn. + The state1. + The ts. + + + + + Selects the misfired triggers in states. + + The conn. + The state1. + The ts. + The count. + The result list. + + + + + Clear (delete!) all scheduling data - all s, s + s. + + + + + + Exception class for when a driver delegate cannot be found for a given + configuration, or lack thereof. + + Jeffrey Wescott + Marko Lahma (.NET) + + + + Base class for exceptions thrown by the Quartz . + + + SchedulerExceptions may contain a reference to another + , which was the underlying cause of the SchedulerException. + + James House + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The MSG. + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + Initializes a new instance of the class. + + The cause. + + + + Initializes a new instance of the class. + + The MSG. + The cause. + + + + Creates and returns a string representation of the current exception. + + + A string representation of the current exception. + + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + is meant to be used in an application-server + or other software framework environment that provides + container-managed-transactions. No commit / rollback will be handled by this class. + + + If you need commit / rollback, use + instead. + + Jeffrey Wescott + James House + Srinivas Venkatarangaiah + Marko Lahma (.NET) + + + + Contains base functionality for ADO.NET-based JobStore implementations. + + Jeffrey Wescott + James House + Marko Lahma (.NET) + + + + The interface to be implemented by classes that want to provide a + and storage mechanism for the + 's use. + + + Storage of s and s should be keyed + on the combination of their name and group for uniqueness. + + + + + + + + James House + Marko Lahma (.NET) + + + + Called by the QuartzScheduler before the is + used, in order to give the it a chance to Initialize. + + + + + Called by the QuartzScheduler to inform the that + the scheduler has started. + + + + + Called by the QuartzScheduler to inform the JobStore that + the scheduler has been paused. + + + + + Called by the QuartzScheduler to inform the JobStore that + the scheduler has resumed after being paused. + + + + + Called by the QuartzScheduler to inform the that + it should free up all of it's resources because the scheduler is + shutting down. + + + + + Store the given and . + + The to be stored. + The to be stored. + ObjectAlreadyExistsException + + + + returns true if the given JobGroup is paused + + + + + + + returns true if the given TriggerGroup + is paused + + + + + + + Store the given . + + The to be stored. + + If , any existing in the + with the same name and group should be + over-written. + + + + + Remove (delete) the with the given + key, and any s that reference + it. + + + If removal of the results in an empty group, the + group should be removed from the 's list of + known group names. + + + if a with the given name and + group was found and removed from the store. + + + + + Retrieve the for the given + . + + + The desired , or null if there is no match. + + + + + Store the given . + + The to be stored. + If , any existing in + the with the same name and group should + be over-written. + ObjectAlreadyExistsException + + + + Remove (delete) the with the given key. + + + + If removal of the results in an empty group, the + group should be removed from the 's list of + known group names. + + + If removal of the results in an 'orphaned' + that is not 'durable', then the should be deleted + also. + + + + if a with the given + name and group was found and removed from the store. + + + + + Remove (delete) the with the + given name, and store the new given one - which must be associated + with the same job. + + The to be replaced. + The new to be stored. + + if a with the given + name and group was found and removed from the store. + + + + + Retrieve the given . + + + The desired , or null if there is no + match. + + + + + Determine whether a with the given identifier already + exists within the scheduler. + + + + the identifier to check for + true if a job exists with the given identifier + + + + Determine whether a with the given identifier already + exists within the scheduler. + + + + the identifier to check for + true if a trigger exists with the given identifier + + + + Clear (delete!) all scheduling data - all s, s + s. + + + + + + + Store the given . + + The name. + The to be stored. + If , any existing + in the with the same name and group + should be over-written. + If , any s existing + in the that reference an existing + Calendar with the same name with have their next fire time + re-computed with the new . + ObjectAlreadyExistsException + + + + Remove (delete) the with the + given name. + + + If removal of the would result in + s pointing to non-existent calendars, then a + will be thrown. + + The name of the to be removed. + + if a with the given name + was found and removed from the store. + + + + + Retrieve the given . + + The name of the to be retrieved. + + The desired , or null if there is no + match. + + + + + Get the number of s that are + stored in the . + + + + + + Get the number of s that are + stored in the . + + + + + + Get the number of s that are + stored in the . + + + + + + Get the names of all of the s that + have the given group name. + + If there are no jobs in the given group name, the result should be a + zero-length array (not ). + + + + + + + + Get the names of all of the s + that have the given group name. + + If there are no triggers in the given group name, the result should be a + zero-length array (not ). + + + + + + Get the names of all of the + groups. + + If there are no known group names, the result should be a zero-length + array (not ). + + + + + + Get the names of all of the + groups. + + If there are no known group names, the result should be a zero-length + array (not ). + + + + + + Get the names of all of the s + in the . + + + If there are no Calendars in the given group name, the result should be + a zero-length array (not ). + + + + + + Get all of the Triggers that are associated to the given Job. + + + If there are no matches, a zero-length array should be returned. + + + + + Get the current state of the identified . + + + + + + Pause the with the given key. + + + + + Pause all of the s in the + given group. + + + The JobStore should "remember" that the group is paused, and impose the + pause on any new triggers that are added to the group while the group is + paused. + + + + + Pause the with the given key - by + pausing all of its current s. + + + + + Pause all of the s in the given + group - by pausing all of their s. + + The JobStore should "remember" that the group is paused, and impose the + pause on any new jobs that are added to the group while the group is + paused. + + + + + + + + Resume (un-pause) the with the + given key. + + + If the missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + + + Resume (un-pause) all of the s + in the given group. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Gets the paused trigger groups. + + + + + + Resume (un-pause) the with the + given key. + + If any of the 's s missed one + or more fire-times, then the 's misfire + instruction will be applied. + + + + + + Resume (un-pause) all of the s in + the given group. + + If any of the s had s that + missed one or more fire-times, then the 's + misfire instruction will be applied. + + + + + + Pause all triggers - equivalent of calling + on every group. + + When is called (to un-pause), trigger misfire + instructions WILL be applied. + + + + + + + Resume (un-pause) all triggers - equivalent of calling + on every group. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + + + Get a handle to the next trigger to be fired, and mark it as 'reserved' + by the calling scheduler. + + If > 0, the JobStore should only return a Trigger + that will fire no later than the time represented in this value as + milliseconds. + + + + + + + + + Inform the that the scheduler no longer plans to + fire the given , that it had previously acquired + (reserved). + + + + + Inform the that the scheduler is now firing the + given (executing its associated ), + that it had previously acquired (reserved). + + + May return null if all the triggers or their calendars no longer exist, or + if the trigger was not successfully put into the 'executing' + state. Preference is to return an empty list if none of the triggers + could be fired. + + + + + Inform the that the scheduler has completed the + firing of the given (and the execution its + associated ), and that the + in the given should be updated if the + is stateful. + + + + + Indicates whether job store supports persistence. + + + + + + How long (in milliseconds) the implementation + estimates that it will take to release a trigger and acquire a new one. + + + + + Whether or not the implementation is clustered. + + + + + + Inform the of the Scheduler instance's Id, + prior to initialize being invoked. + + + + + Inform the of the Scheduler instance's name, + prior to initialize being invoked. + + + + + Tells the JobStore the pool size used to execute jobs. + + + + + Initializes a new instance of the class. + + + + + Gets the connection and starts a new transaction. + + + + + + Called by the QuartzScheduler before the is + used, in order to give it a chance to Initialize. + + + + + + + + Called by the QuartzScheduler to inform the JobStore that + the scheduler has been paused. + + + + + Called by the QuartzScheduler to inform the JobStore that + the scheduler has resumed after being paused. + + + + + Called by the QuartzScheduler to inform the that + it should free up all of it's resources because the scheduler is + shutting down. + + + + + Will recover any failed or misfired jobs and clean up the data store as + appropriate. + + + + + Will recover any failed or misfired jobs and clean up the data store as + appropriate. + + + + + Store the given and . + + Job to be stored. + Trigger to be stored. + + + + returns true if the given JobGroup + is paused + + + + + + + returns true if the given TriggerGroup + is paused + + + + + + + Stores the given . + + The to be stored. + + If , any existing in the + with the same name & group should be over-written. + + + + + Insert or update a job. + + + + + + Check existence of a given job. + + + + + Store the given . + + The to be stored. + + If , any existing in + the with the same name & group should + be over-written. + + + if a with the same name/group already + exists, and replaceExisting is set to false. + + + + + Insert or update a trigger. + + + + + Check existence of a given trigger. + + + + + Remove (delete) the with the given + name, and any s that reference + it. + + + + If removal of the results in an empty group, the + group should be removed from the 's list of + known group names. + + + if a with the given name & + group was found and removed from the store. + + + + + Delete a job and its listeners. + + + + + + + Delete a trigger, its listeners, and its Simple/Cron/BLOB sub-table entry. + + + + + + + + Retrieve the for the given + . + + The key identifying the job. + The desired , or null if there is no match. + + + + Remove (delete) the with the + given name. + + + + + If removal of the results in an empty group, the + group should be removed from the 's list of + known group names. + + + + If removal of the results in an 'orphaned' + that is not 'durable', then the should be deleted + also. + + + The key identifying the trigger. + + if a with the given + name & group was found and removed from the store. + + + + + + + + Retrieve the given . + + The key identifying the trigger. + The desired , or null if there is no match. + + + + Get the current state of the identified . + + + + + + + + + + Gets the state of the trigger. + + The conn. + The key identifying the trigger. + + + + + Store the given . + + The name of the calendar. + The to be stored. + + If , any existing + in the with the same name & group + should be over-written. + + + + if a with the same name already + exists, and replaceExisting is set to false. + + + + + Remove (delete) the with the given name. + + + If removal of the would result in + s pointing to non-existent calendars, then a + will be thrown. + + The name of the to be removed. + + if a with the given name + was found and removed from the store. + + + + + Retrieve the given . + + The name of the to be retrieved. + The desired , or null if there is no match. + + + + Get the number of s that are + stored in the . + + + + + Get the number of s that are + stored in the . + + + + + Get the number of s that are + stored in the . + + + + + Get the names of all of the s that + have the given group name. + + + If there are no jobs in the given group name, the result should be a + zero-length array (not ). + + + + + Determine whether a with the given identifier already + exists within the scheduler. + + + + the identifier to check for + true if a Job exists with the given identifier + + + + Determine whether a with the given identifier already + exists within the scheduler. + + + + the identifier to check for + true if a Trigger exists with the given identifier + + + + Clear (delete!) all scheduling data - all s, s + s. + + + + + + + Get the names of all of the s + that have the given group name. + + + If there are no triggers in the given group name, the result should be a + zero-length array (not ). + + + + + Get the names of all of the + groups. + + + + If there are no known group names, the result should be a zero-length + array (not ). + + + + + Get the names of all of the + groups. + + + + If there are no known group names, the result should be a zero-length + array (not ). + + + + + Get the names of all of the s + in the . + + + If there are no Calendars in the given group name, the result should be + a zero-length array (not ). + + + + + Get all of the Triggers that are associated to the given Job. + + + If there are no matches, a zero-length array should be returned. + + + + + Pause the with the given name. + + + + + Pause the with the given name. + + + + + Pause the with the given name - by + pausing all of its current s. + + + + + + Pause all of the s in the given + group - by pausing all of their s. + + + + + + Determines if a Trigger for the given job should be blocked. + State can only transition to StatePausedBlocked/StateBlocked from + StatePaused/StateWaiting respectively. + + StatePausedBlocked, StateBlocked, or the currentState. + + + + Resume (un-pause) the with the + given name. + + + If the missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + Resume (un-pause) the with the + given name. + + + If any of the 's s missed one + or more fire-times, then the 's misfire + instruction will be applied. + + + + + + Resume (un-pause) all of the s in + the given group. + + + If any of the s had s that + missed one or more fire-times, then the 's + misfire instruction will be applied. + + + + + + Pause all of the s in the given group. + + + + + + Pause all of the s in the given group. + + + + + Pause all of the s in the + given group. + + + + + Resume (un-pause) all of the s + in the given group. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Pause all triggers - equivalent of calling + on every group. + + When is called (to un-pause), trigger misfire + instructions WILL be applied. + + + + + + + + Resume (un-pause) all triggers - equivalent of calling + on every group. + + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Resume (un-pause) all triggers - equivalent of calling + on every group. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + + Get a handle to the next N triggers to be fired, and mark them as 'reserved' + by the calling scheduler. + + + + + + Inform the that the scheduler no longer plans to + fire the given , that it had previously acquired + (reserved). + + + + + Inform the that the scheduler has completed the + firing of the given (and the execution its + associated ), and that the + in the given should be updated if the + is stateful. + + + + + Get a list of all scheduler instances in the cluster that may have failed. + This includes this scheduler if it is checking in for the first time. + + + + + Create dummy objects for fired triggers + that have no scheduler state record. Checkin timestamp and interval are + left as zero on these dummy objects. + + + List of all current s + + + + Cleanup the given database connection. This means restoring + any modified auto commit or transaction isolation connection + attributes, and then closing the underlying connection. + + + + This is separate from closeConnection() because the Spring + integration relies on being able to overload closeConnection() and + expects the same connection back that it originally returned + from the datasource. + + + + + + Closes the supplied connection. + + (Optional) + + + + Rollback the supplied connection. + + (Optional) + + JobPersistenceException thrown if a SQLException occurs when the + connection is rolled back + + + + + Commit the supplied connection. + + The CTH. + if set to true opens a new transaction. + JobPersistenceException thrown if a SQLException occurs when the + + + + Execute the given callback in a transaction. Depending on the JobStore, + the surrounding transaction may be assumed to be already present + (managed). + + + This method just forwards to ExecuteInLock() with a null lockName. + + + + + + Execute the given callback having acquired the given lock. + Depending on the JobStore, the surrounding transaction may be + assumed to be already present (managed). This version is just a + handy wrapper around executeInLock that doesn't require a return + value. + + + The name of the lock to acquire, for example + "TRIGGER_ACCESS". If null, then no lock is acquired, but the + lockCallback is still executed in a transaction. + + + The callback to excute after having acquired the given lock. + + + + + + Execute the given callback having acquired the given lock. + Depending on the JobStore, the surrounding transaction may be + assumed to be already present (managed). + + + The name of the lock to acquire, for example + "TRIGGER_ACCESS". If null, then no lock is acquired, but the + lockCallback is still executed in a transaction. + + + The callback to excute after having acquired the given lock. + + + + + Execute the given callback having optionally acquired the given lock. + This uses the non-managed transaction connection. This version is just a + handy wrapper around executeInNonManagedTXLock that doesn't require a return + value. + + + The name of the lock to acquire, for example + "TRIGGER_ACCESS". If null, then no lock is acquired, but the + lockCallback is still executed in a non-managed transaction. + + + + The callback to excute after having acquired the given lock. + + + + + Execute the given callback having optionally acquired the given lock. + This uses the non-managed transaction connection. + + + The name of the lock to acquire, for example + "TRIGGER_ACCESS". If null, then no lock is acquired, but the + lockCallback is still executed in a non-managed transaction. + + + The callback to excute after having acquired the given lock. + + + + + Get or set the datasource name. + + + + + Gets the log. + + The log. + + + + Get or sets the prefix that should be pre-pended to all table names. + + + + + Set whether string-only properties will be handled in JobDataMaps. + + + + + Get or set the instance Id of the Scheduler (must be unique within a cluster). + + + + + Get or set the instance Id of the Scheduler (must be unique within this server instance). + + + + + Get or set whether this instance is part of a cluster. + + + + + Get or set the frequency at which this instance "checks-in" + with the other instances of the cluster. -- Affects the rate of + detecting failed instances. + + + + + Get or set the maximum number of misfired triggers that the misfire handling + thread will try to recover at one time (within one transaction). The + default is 20. + + + + + Gets or sets the database retry interval. + + The db retry interval. + + + + Get or set whether this instance should use database-based thread + synchronization. + + + + + Whether or not to obtain locks when inserting new jobs/triggers. + Defaults to , which is safest - some db's (such as + MS SQLServer) seem to require this to avoid deadlocks under high load, + while others seem to do fine without. + + + Setting this property to will provide a + significant performance increase during the addition of new jobs + and triggers. + + + + + The time span by which a trigger must have missed its + next-fire-time, in order for it to be considered "misfired" and thus + have its misfire instruction applied. + + + + + Don't call set autocommit(false) on connections obtained from the + DataSource. This can be helpfull in a few situations, such as if you + have a driver that complains if it is called when it is already off. + + + + + Set the transaction isolation level of DB connections to sequential. + + + + + Whether or not the query and update to acquire a Trigger for firing + should be performed after obtaining an explicit DB lock (to avoid + possible race conditions on the trigger's db row). This is + is considered unnecessary for most databases (due to the nature of + the SQL update that is performed), and therefore a superfluous performance hit. + + + However, if batch acquisition is used, it is important for this behavior + to be used for all dbs. + + + + + Get or set the ADO.NET driver delegate class name. + + + + + The driver delegate's initialization string. + + + + + set the SQL statement to use to select and lock a row in the "locks" + table. + + + + + + Get whether the threads spawned by this JobStore should be + marked as daemon. Possible threads include the + and the . + + + + + + Get whether to check to see if there are Triggers that have misfired + before actually acquiring the lock to recover them. This should be + set to false if the majority of the time, there are are misfired + Triggers. + + + + + + Get the driver delegate for DB operations. + + + + + Get whether String-only properties will be handled in JobDataMaps. + + + + + Indicates whether this job store supports persistence. + + + + + + + An interface for classes wishing to provide the service of loading classes + and resources within the scheduler... + + James House + Marko Lahma (.NET) + + + + Called to give the ClassLoadHelper a chance to Initialize itself, + including the oportunity to "steal" the class loader off of the calling + thread, which is the thread that is initializing Quartz. + + + + + Return the class with the given name. + + + + + Finds a resource with a given name. This method returns null if no + resource with this name is found. + + name of the desired resource + + a java.net.URL object + + + + + Finds a resource with a given name. This method returns null if no + resource with this name is found. + + name of the desired resource + + a java.io.InputStream object + + + + + Helper class for returning the composite result of trying + to recover misfired jobs. + + + + + Initializes a new instance of the class. + + if set to true [has more misfired triggers]. + The processed misfired trigger count. + + + + + Gets a value indicating whether this instance has more misfired triggers. + + + true if this instance has more misfired triggers; otherwise, false. + + + + + Gets the processed misfired trigger count. + + The processed misfired trigger count. + + + + Called by the QuartzScheduler before the is + used, in order to give the it a chance to Initialize. + + + + + + + Called by the QuartzScheduler to inform the that + it should free up all of it's resources because the scheduler is + shutting down. + + + + + Gets the non managed TX connection. + + + + + + Execute the given callback having optionally acquired the given lock. + Because CMT assumes that the connection is already part of a managed + transaction, it does not attempt to commit or rollback the + enclosing transaction. + + + + + + + The name of the lock to acquire, for example + "TRIGGER_ACCESS". If null, then no lock is acquired, but the + txCallback is still executed in a transaction. + + Callback to execute. + + + + is meant to be used in a standalone environment. + Both commit and rollback will be handled by this class. + + Jeffrey Wescott + James House + Marko Lahma (.NET) + + + + Called by the QuartzScheduler before the is + used, in order to give the it a chance to Initialize. + + + + + + + For , the non-managed TX connection is just + the normal connection because it is not CMT. + + + + + + Execute the given callback having optionally aquired the given lock. + For , because it manages its own transactions + and only has the one datasource, this is the same behavior as + . + + + The name of the lock to aquire, for example "TRIGGER_ACCESS". + If null, then no lock is aquired, but the lockCallback is still + executed in a transaction. + + Callback to execute. + + + + + + + + + Exception class for when there is a failure obtaining or releasing a + resource lock. + + + James House + Marko Lahma (.NET) + + + + An exception that is thrown to indicate that there has been a failure in the + scheduler's underlying persistence mechanism. + + James House + Marko Lahma (.NET) + + + + Create a with the given message. + + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + Create a with the given message + and cause. + + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + This is a driver delegate for the MySQL ADO.NET driver. + + Marko Lahma + + + + This is meant to be an abstract base class for most, if not all, + implementations. Subclasses should override only those methods that need + special handling for the DBMS driver in question. + + Jeffrey Wescott + James House + Marko Lahma (.NET) + + + + Initializes the driver delegate. + + + + + Insert the job detail record. + + the DB Connection + the new state for the triggers + the first old state to update + the second old state to update + number of rows updated + + + + Get the names of all of the triggers that have misfired. + + the DB Connection + The ts. + an array of objects + + + + Select all of the triggers in a given state. + + The DB Connection + The state the triggers must be in + an array of trigger s + + + + Get the names of all of the triggers in the given state that have + misfired - according to the given timestamp. + + The DB Connection + The state. + The time stamp. + An array of objects + + + + Get the names of all of the triggers in the given state that have + misfired - according to the given timestamp. No more than count will + be returned. + + The conn. + The state1. + The ts. + The most misfired triggers to return, negative for all + + Output parameter. A List of objects. Must not be null + + Whether there are more misfired triggers left to find beyond the given count. + + + + Get the number of triggers in the given state that have + misfired - according to the given timestamp. + + + + + + + + + Get the names of all of the triggers in the given group and state that + have misfired. + + The DB Connection + Name of the group. + The state. + The timestamp. + an array of objects + + + + Select all of the triggers for jobs that are requesting recovery. The + returned trigger objects will have unique "recoverXXX" trigger names and + will be in the + trigger group. + + + In order to preserve the ordering of the triggers, the fire time will be + set from the ColumnFiredTime column in the TableFiredTriggers + table. The caller is responsible for calling + on each returned trigger. It is also up to the caller to insert the + returned triggers to ensure that they are fired. + + The DB Connection + an array of objects + + + + Delete all fired triggers. + + The DB Connection. + The number of rows deleted. + + + + Delete all fired triggers of the given instance. + + The DB Connection + The instance id. + The number of rows deleted + + + + Clear (delete!) all scheduling data - all s, s + s. + + + + + + + Insert the job detail record. + + The DB Connection. + The job to insert. + Number of rows inserted. + + + + Gets the db presentation for boolean value. Subclasses can overwrite this behaviour. + + Value to map to database. + + + + + Gets the boolean value from db presentation. Subclasses can overwrite this behaviour. + + Value to map from database. + + + + + Gets the db presentation for date/time value. Subclasses can overwrite this behaviour. + + Value to map to database. + + + + + Gets the date/time value from db presentation. Subclasses can overwrite this behaviour. + + Value to map from database. + + + + + Gets the db presentation for time span value. Subclasses can overwrite this behaviour. + + Value to map to database. + + + + + Gets the time span value from db presentation. Subclasses can overwrite this behaviour. + + Value to map from database. + + + + + Update the job detail record. + + The DB Connection. + The job to update. + Number of rows updated. + + + + Get the names of all of the triggers associated with the given job. + + The DB Connection. + The key identifying the job. + An array of objects + + + + Delete the job detail record for the given job. + + the DB Connection + The key identifying the job. + the number of rows deleted + + + + Check whether or not the given job is stateful. + + the DB Connection + The key identifying the job. + + true if the job exists and is stateful, false otherwise + + + + + Check whether or not the given job exists. + + the DB Connection + The key identifying the job. + true if the job exists, false otherwise + + + + Update the job data map for the given job. + + The conn. + the job to update + the number of rows updated + + + + Select the JobDetail object for a given job name / group name. + + The DB Connection. + The key identifying the job. + The load helper. + The populated JobDetail object. + + + build Map from java.util.Properties encoding. + + + + Select the total number of jobs stored. + + The DB Connection. + The total number of jobs stored. + + + + Select all of the job group names that are stored. + + The DB Connection. + An array of group names. + + + + Select all of the jobs contained in a given group. + + The DB Connection. + + An array of job names. + + + + Insert the base trigger data. + + the DB Connection + the trigger to insert + the state that the trigger should be stored in + The job detail. + the number of rows inserted + + + + Insert the blob trigger data. + + The DB Connection. + The trigger to insert. + The number of rows inserted. + + + + Update the base trigger data. + + The DB Connection. + The trigger to insert. + The state that the trigger should be stored in. + The job detail. + The number of rows updated. + + + + Update the blob trigger data. + + The DB Connection. + The trigger to insert. + The number of rows updated. + + + + Check whether or not a trigger exists. + + The DB Connection. + the key of the trigger + true if the trigger exists, false otherwise + + + + Update the state for a given trigger. + + The DB Connection. + the key of the trigger + The new state for the trigger. + The number of rows updated. + + + + Update the given trigger to the given new state, if it is one of the + given old states. + + The DB connection. + the key of the trigger + The new state for the trigger. + One of the old state the trigger must be in. + One of the old state the trigger must be in. + One of the old state the trigger must be in. + The number of rows updated. + + + + Update all triggers in the given group to the given new state, if they + are in one of the given old states. + + The DB connection. + + The new state for the trigger. + One of the old state the trigger must be in. + One of the old state the trigger must be in. + One of the old state the trigger must be in. + The number of rows updated. + + + + Update the given trigger to the given new state, if it is in the given + old state. + + the DB connection + the key of the trigger + the new state for the trigger + the old state the trigger must be in + int the number of rows updated + + + + Update all of the triggers of the given group to the given new state, if + they are in the given old state. + + the DB connection + + the new state for the trigger group + the old state the triggers must be in + int the number of rows updated + + + + Update the states of all triggers associated with the given job. + + the DB Connection + the key of the job + the new state for the triggers + the number of rows updated + + + + Updates the state of the trigger states for job from other. + + The conn. + Key of the job. + The state. + The old state. + + + + + Delete the cron trigger data for a trigger. + + the DB Connection + the key of the trigger + the number of rows deleted + + + + Delete the base trigger data for a trigger. + + the DB Connection + the key of the trigger + the number of rows deleted + + + + Select the number of triggers associated with a given job. + + the DB Connection + the key of the job + the number of triggers for the given job + + + + Select the job to which the trigger is associated. + + the DB Connection + the key of the trigger + The load helper. + The object associated with the given trigger + + + + Select the triggers for a job + + the DB Connection + the key of the job + + an array of objects + associated with a given job. + + + + + Select the triggers for a calendar + + The DB Connection. + Name of the calendar. + + An array of objects associated with a given job. + + + + + Select a trigger. + + the DB Connection + the key of the trigger + The object + + + + Select a trigger's JobDataMap. + + the DB Connection + the key of the trigger + The of the Trigger, never null, but possibly empty. + + + + Select a trigger's state value. + + the DB Connection + the key of the trigger + The object + + + + Select a trigger status (state and next fire time). + + the DB Connection + the key of the trigger + + a object, or null + + + + + Select the total number of triggers stored. + + the DB Connection + the total number of triggers stored + + + + Select all of the trigger group names that are stored. + + the DB Connection + + an array of group names + + + + + Select all of the triggers contained in a given group. + + the DB Connection + + + an array of trigger names + + + + + Inserts the paused trigger group. + + The conn. + Name of the group. + + + + + Deletes the paused trigger group. + + The conn. + Name of the group. + + + + + Deletes all paused trigger groups. + + The conn. + + + + + Determines whether the specified trigger group is paused. + + The conn. + Name of the group. + + true if trigger group is paused; otherwise, false. + + + + + Determines whether given trigger group already exists. + + The conn. + Name of the group. + + true if trigger group exists; otherwise, false. + + + + + Insert a new calendar. + + the DB Connection + The name for the new calendar. + The calendar. + the number of rows inserted + IOException + + + + Update a calendar. + + the DB Connection + The name for the new calendar. + The calendar. + the number of rows updated + IOException + + + + Check whether or not a calendar exists. + + the DB Connection + The name of the calendar. + + true if the trigger exists, false otherwise + + + + + Select a calendar. + + the DB Connection + The name of the calendar. + the Calendar + ClassNotFoundException + IOException + + + + Check whether or not a calendar is referenced by any triggers. + + the DB Connection + The name of the calendar. + + true if any triggers reference the calendar, false otherwise + + + + + Delete a calendar. + + the DB Connection + The name of the trigger. + the number of rows deleted + + + + Select the total number of calendars stored. + + the DB Connection + the total number of calendars stored + + + + Select all of the stored calendars. + + the DB Connection + + an array of calendar names + + + + + Select the trigger that will be fired at the given fire time. + + the DB Connection + the time that the trigger will be fired + + a representing the + trigger that will be fired at the given fire time, or null if no + trigger will be fired at that time + + + + + Select the next trigger which will fire to fire between the two given timestamps + in ascending order of fire time, and then descending by priority. + + The conn. + highest value of of the triggers (exclusive) + highest value of of the triggers (inclusive) + maximum number of trigger keys allow to acquired in the returning list. + A (never null, possibly empty) list of the identifiers (Key objects) of the next triggers to be fired. + + + + Insert a fired trigger. + + the DB Connection + the trigger + the state that the trigger should be stored in + The job. + the number of rows inserted + + + + + Update a fired trigger. + + + + + + the DB Connection + + the trigger + + + the state that the trigger should be stored in + the number of rows inserted + + + + Select the states of all fired-trigger records for a given trigger, or + trigger group if trigger name is . + + The DB connection. + Name of the trigger. + Name of the group. + a List of objects. + + + + Select the states of all fired-trigger records for a given job, or job + group if job name is . + + The DB connection. + Name of the job. + Name of the group. + a List of objects. + + + + Select the states of all fired-trigger records for a given scheduler + instance. + + The DB Connection + Name of the instance. + A list of FiredTriggerRecord objects. + + + + Select the distinct instance names of all fired-trigger records. + + The conn. + + + This is useful when trying to identify orphaned fired triggers (a + fired trigger without a scheduler state record.) + + + + + Delete a fired trigger. + + the DB Connection + the fired trigger entry to delete + the number of rows deleted + + + + Selects the job execution count. + + The DB connection. + The key of the job. + + + + + Inserts the state of the scheduler. + + The conn. + The instance id. + The check in time. + The interval. + + + + + Deletes the state of the scheduler. + + The database connection. + The instance id. + + + + + Updates the state of the scheduler. + + The database connection. + The instance id. + The check in time. + + + + + A List of all current s. + + If instanceId is not null, then only the record for the identified + instance will be returned. + + + The DB Connection + The instance id. + + + + + Replace the table prefix in a query by replacing any occurrences of + "{0}" with the table prefix. + + The unsubstitued query + The query, with proper table prefix substituted + + + + Create a serialized version of an Object. + + the object to serialize + Serialized object as byte array. + + + + Remove the transient data from and then create a serialized + version of a and returns the underlying bytes. + + The data. + the serialized data as byte array + + + + serialize + + The data. + + + + + Convert the JobDataMap into a list of properties. + + + + + Convert the JobDataMap into a list of properties. + + + + + This method should be overridden by any delegate subclasses that need + special handling for BLOBs. The default implementation uses standard + ADO.NET operations. + + The data reader, already queued to the correct row. + The column index for the BLOB. + The deserialized object from the DataReader BLOB. + + + + This method should be overridden by any delegate subclasses that need + special handling for BLOBs for job details. + + The result set, already queued to the correct row. + The column index for the BLOB. + The deserialized Object from the ResultSet BLOB. + + + + Selects the paused trigger groups. + + The DB Connection. + + + + + Gets the select next trigger to acquire SQL clause. + MySQL version with LIMIT support. + + + + + + Exception class for when a driver delegate cannot be found for a given + configuration, or lack thereof. + + Jeffrey Wescott + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + This is a driver delegate for the Oracle database. + + Marko Lahma + + + + Creates the SQL for select next trigger to acquire. + + + + + Gets the db presentation for boolean value. For Oracle we use true/false of "1"/"0". + + Value to map to database. + + + + + Conveys a scheduler-instance state record. + + James House + Marko Lahma (.NET) + + + + Gets or sets the checkin interval. + + The checkin interval. + + + + Gets or sets the checkin timestamp. + + The checkin timestamp. + + + + Gets or sets the scheduler instance id. + + The scheduler instance id. + + + + Internal in-memory lock handler for providing thread/resource locking in + order to protect resources from being altered by multiple threads at the + same time. + + James House + Marko Lahma (.NET) + + + + Grants a lock on the identified resource to the calling thread (blocking + until it is available). + + True if the lock was obtained. + + + Release the lock on the identified resource if it is held by the calling + thread. + + + + + Determine whether the calling thread owns a lock on the identified + resource. + + + + + Gets the thread locks. + + The thread locks. + + + + Whether this Semaphore implementation requires a database connection for + its lock management operations. + + + + + + + + + This is a driver delegate for the SQLiteDelegate ADO.NET driver. + + Marko Lahma + + + + Gets the select next trigger to acquire SQL clause. + SQLite version with LIMIT support. + + + + + + A SQL Server specific driver delegate. + + Marko Lahma + + + + Gets the select next trigger to acquire SQL clause. + SQL Server specific version with TOP functionality + + + + + + Internal database based lock handler for providing thread/resource locking + in order to protect resources from being altered by multiple threads at the + same time. + + James House + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + The table prefix. + the scheduler name + The select with lock SQL. + + + + + Execute the SQL select for update that will lock the proper database row. + + + + + Property name and value holder for trigger state data. + + + + + Object representing a job or trigger key. + + James House + Marko Lahma (.NET) + + + + Construct a new TriggerStatus with the status name and nextFireTime. + + The trigger's status + The next time trigger will fire + + + + Return the string representation of the TriggerStatus. + + + + + + Provide thread/resource locking in order to protect + resources from being altered by multiple threads at the same time using + a db row update. + + + + Note: This Semaphore implementation is useful for databases that do + not support row locking via "SELECT FOR UPDATE" or SQL Server's type syntax. + + + As of Quartz.NET 2.0 version there is no need to use this implementation for + SQL Server databases. + + + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Execute the SQL that will lock the proper database row. + + + + + + + + + This implementation of the Calendar excludes a set of days of the year. You + may use it to exclude bank holidays which are on the same date every year. + + + + Juergen Donnerstag + Marko Lahma (.NET) + + + + This implementation of the Calendar may be used (you don't have to) as a + base class for more sophisticated one's. It merely implements the base + functionality required by each Calendar. + + + Regarded as base functionality is the treatment of base calendars. Base + calendar allow you to chain (stack) as much calendars as you may need. For + example to exclude weekends you may use WeeklyCalendar. In order to exclude + holidays as well you may define a WeeklyCalendar instance to be the base + calendar for HolidayCalendar instance. + + + Juergen Donnerstag + James House + Marko Lahma (.NET) + + + + An interface to be implemented by objects that define spaces of time during + which an associated may (not) fire. Calendars + do not define actual fire times, but rather are used to limit a + from firing on its normal schedule if necessary. Most + Calendars include all times by default and allow the user to specify times + to exclude. + + + As such, it is often useful to think of Calendars as being used to exclude a block + of time - as opposed to include a block of time. (i.e. the + schedule "fire every five minutes except on Sundays" could be + implemented with a and a + which excludes Sundays) + + Implementations MUST take care of being properly cloneable and Serializable. + + + James House + Juergen Donnerstag + Marko Lahma (.NET) + + + + Determine whether the given UTC time is 'included' by the + Calendar. + + + + + Determine the next UTC time that is 'included' by the + Calendar after the given UTC time. + + + + + Gets or sets a description for the instance - may be + useful for remembering/displaying the purpose of the calendar, though + the description has no meaning to Quartz. + + + + + Set a new base calendar or remove the existing one. + Get the base calendar. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The base calendar. + + + + Initializes a new instance of the class. + + The time zone. + + + + Initializes a new instance of the class. + + The base calendar. + The time zone. + + + + Serialization constructor. + + + + + + + checks whether two arrays have + the same length and + for any given place there are equal elements + in both arrays + + + + + + Get the base calendar. Will be null, if not set. + + + + + Check if date/time represented by timeStamp is included. If included + return true. The implementation of BaseCalendar simply calls the base + calendars IsTimeIncluded() method if base calendar is set. + + + + + + Determine the next UTC time (in milliseconds) that is 'included' by the + Calendar after the given time. Return the original value if timeStamp is + included. Return 0 if all days are excluded. + + + + + + Creates a new object that is a copy of the current instance. + + A new object that is a copy of this instance. + + + + Gets or sets the time zone. + + The time zone. + + + + Gets or sets the description given to the instance by + its creator (if any). + + + + + Set a new base calendar or remove the existing one + + + + + + Constructor + + + + + Constructor + + The base calendar. + + + + Serialization constructor. + + + + + + + Return true, if day is defined to be exluded. + + + + + Redefine a certain day to be excluded (true) or included (false). + + + + + Determine whether the given UTC time (in milliseconds) is 'included' by the + Calendar. + + Note that this Calendar is only has full-day precision. + + + + + + Determine the next UTC time (in milliseconds) that is 'included' by the + Calendar after the given time. Return the original value if timeStampUtc is + included. Return 0 if all days are excluded. + + Note that this Calendar is only has full-day precision. + + + + + + Get or the array which defines the exclude-value of each day of month. + Setting will redefine the array of days excluded. The array must of size greater or + equal 31. + + + + + This implementation of the Calendar excludes the set of times expressed by a + given CronExpression. + + + For example, you could use this calendar to exclude all but business hours (8AM - 5PM) every + day using the expression "* * 0-7,18-23 ? * *". + + It is important to remember that the cron expression here describes a set of + times to be excluded from firing. Whereas the cron expression in + CronTrigger describes a set of times that can + be included for firing. Thus, if a has a + given cron expression and is associated with a with + the same expression, the calendar will exclude all the times the + trigger includes, and they will cancel each other out. + + + Aaron Craven + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + a string representation of the desired cron expression + + + + Create a with the given cron expression and + . + + + the base calendar for this calendar instance + see BaseCalendar for more information on base + calendar functionality + + a string representation of the desired cron expression + + + + Create a with the given cron expression and + . + + + the base calendar for this calendar instance + see BaseCalendar for more information on base + calendar functionality + + a string representation of the desired cron expression + + + + + Serialization constructor. + + + + + + + Determine whether the given time is 'included' by the + Calendar. + + the time to test + a boolean indicating whether the specified time is 'included' by the CronCalendar + + + + Determine the next time that is 'included' by the + Calendar after the given time. Return the original value if timeStamp is + included. Return 0 if all days are excluded. + + + + + + + Creates a new object that is a copy of the current instance. + + A new object that is a copy of this instance. + + + + Returns a that represents the current . + + + A that represents the current . + + + + + Sets the cron expression for the calendar to a new value. + + The expression. + + + + Returns the object representation of the cron expression that defines the + dates and times this calendar excludes. + + + + + This implementation of the Calendar excludes (or includes - see below) a + specified time range each day. + + + For example, you could use this calendar to + exclude business hours (8AM - 5PM) every day. Each + only allows a single time range to be specified, and that time range may not + * cross daily boundaries (i.e. you cannot specify a time range from 8PM - 5AM). + If the property is (default), + the time range defines a range of times in which triggers are not allowed to + * fire. If is , the time range + is inverted: that is, all times outside the defined time range + are excluded. + + Note when using , it behaves on the same principals + as, for example, WeeklyCalendar defines a set of days that are + excluded every week. Likewise, defines a + set of times that are excluded every day. + + + Mike Funk + Aaron Craven + Marko Lahma (.NET) + + + + Create a with a time range defined by the + specified strings and no baseCalendar. + and + must be in the format "HH:MM[:SS[:mmm]]" where: +
    +
  • + HH is the hour of the specified time. The hour should be + specified using military (24-hour) time and must be in the range + 0 to 23. +
    • +
  • + MM is the minute of the specified time and must be in the range + 0 to 59. +
    • +
  • + SS is the second of the specified time and must be in the range + 0 to 59. +
    • +
  • + mmm is the millisecond of the specified time and must be in the + range 0 to 999. +
    • +
  • items enclosed in brackets ('[', ']') are optional.
    • +
  • + The time range starting time must be before the time range ending + time. Note this means that a time range may not cross daily + boundaries (10PM - 2AM) +
    • +
+ + + + + Create a with a time range defined by the + specified strings and the specified baseCalendar. + and + must be in the format "HH:MM[:SS[:mmm]]" where: +
    +
  • + HH is the hour of the specified time. The hour should be + specified using military (24-hour) time and must be in the range + 0 to 23. +
    • +
  • + MM is the minute of the specified time and must be in the range + 0 to 59. +
    • +
  • + SS is the second of the specified time and must be in the range + 0 to 59. +
    • +
  • + mmm is the millisecond of the specified time and must be in the + range 0 to 999. +
    • +
  • + items enclosed in brackets ('[', ']') are optional. +
    • +
  • + The time range starting time must be before the time range ending + time. Note this means that a time range may not cross daily + boundaries (10PM - 2AM) +
    • +
+ + The base calendar for this calendar instance see BaseCalendar for more + information on base calendar functionality. + + + + Create a with a time range defined by the + specified values and no baseCalendar. Values are subject to + the following validations: +
    +
  • + Hours must be in the range 0-23 and are expressed using military + (24-hour) time. +
    • +
  • Minutes must be in the range 0-59
    • +
  • Seconds must be in the range 0-59
    • +
  • Milliseconds must be in the range 0-999
    • +
  • + The time range starting time must be before the time range ending + time. Note this means that a time range may not cross daily + boundaries (10PM - 2AM) +
    • +
+ + The range starting hour of day. + The range starting minute. + The range starting second. + The range starting millis. + The range ending hour of day. + The range ending minute. + The range ending second. + The range ending millis. + + + + Create a with a time range defined by the + specified values and the specified . Values are + subject to the following validations: +
    +
  • + Hours must be in the range 0-23 and are expressed using military + (24-hour) time. +
    • +
  • Minutes must be in the range 0-59
    • +
  • Seconds must be in the range 0-59
    • +
  • Milliseconds must be in the range 0-999
    • +
  • + The time range starting time must be before the time range ending + time. Note this means that a time range may not cross daily + boundaries (10PM - 2AM) +
    • +
+ + The range starting hour of day. + The range starting minute. + The range starting second. + The range starting millis. + The range ending hour of day. + The range ending minute. + The range ending second. + The range ending millis. + + + + Create a with a time range defined by the + specified s and no + baseCalendar. The Calendars are subject to the following + considerations: +
    +
  • + Only the time-of-day fields of the specified Calendars will be + used (the date fields will be ignored) +
    • +
  • + The starting time must be before the ending time of the defined + time range. Note this means that a time range may not cross + daily boundaries (10PM - 2AM). (because only time fields are + are used, it is possible for two Calendars to represent a valid + time range and + rangeStartingCalendar.after(rangeEndingCalendar) == true) + +
    • +
+ + The range starting calendar. + The range ending calendar. + + + + Create a with a time range defined by the + specified s and the specified + . The Calendars are subject to the following + considerations: +
    +
  • + Only the time-of-day fields of the specified Calendars will be + used (the date fields will be ignored) +
    • +
  • + The starting time must be before the ending time of the defined + time range. Note this means that a time range may not cross + daily boundaries (10PM - 2AM). (because only time fields are + are used, it is possible for two Calendars to represent a valid + time range and + rangeStartingCalendarUtc > rangeEndingCalendarUtc == true) +
    • +
+ + The range starting calendar. + The range ending calendar. + + + + Create a with a time range defined by the + specified values and no baseCalendar. The values are + subject to the following considerations: +
    +
  • + Only the time-of-day portion of the specified values will be + used +
    • +
  • + The starting time must be before the ending time of the defined + time range. Note this means that a time range may not cross + daily boundaries (10PM - 2AM). (because only time value are + are used, it is possible for the two values to represent a valid + time range and rangeStartingTime > rangeEndingTime) +
    • +
+ + The range starting time in millis. + The range ending time in millis. + + + + Create a with a time range defined by the + specified values and the specified . The values + are subject to the following considerations: +
    +
  • + Only the time-of-day portion of the specified values will be + used +
    • +
  • + The starting time must be before the ending time of the defined + time range. Note this means that a time range may not cross + daily boundaries (10PM - 2AM). (because only time value are + are used, it is possible for the two values to represent a valid + time range and rangeStartingTime > rangeEndingTime) +
    • +
+ + The range starting time in millis. + The range ending time in millis. + + + + Serialization constructor. + + + + + + + Determine whether the given time is 'included' by the + Calendar. + + + + + + + Determine the next time (in milliseconds) that is 'included' by the + Calendar after the given time. Return the original value if timeStamp is + included. Return 0 if all days are excluded. + + + + + + + + Returns the start time of the time range of the day + specified in . + + + a DateTime representing the start time of the + time range for the specified date. + + + + + Returns the end time of the time range of the day + specified in + + + A DateTime representing the end time of the + time range for the specified date. + + + + + Returns a that represents the current . + + + A that represents the current . + + + + + Sets the time range for the to the times + represented in the specified Strings. + + The range starting time string. + The range ending time string. + + + + Sets the time range for the to the times + represented in the specified values. + + The range starting hour of day. + The range starting minute. + The range starting second. + The range starting millis. + The range ending hour of day. + The range ending minute. + The range ending second. + The range ending millis. + + + + Sets the time range for the to the times + represented in the specified s. + + The range starting calendar. + The range ending calendar. + + + + Sets the time range for the to the times + represented in the specified values. + + The range starting time. + The range ending time. + + + + Gets the start of day, practically zeroes time part. + + The time. + + + + + Gets the end of day, pratically sets time parts to maximum allowed values. + + The time. + + + + + Checks the specified values for validity as a set of time values. + + The hour of day. + The minute. + The second. + The millis. + + + + Indicates whether the time range represents an inverted time range (see + class description). + + true if invert time range; otherwise, false. + + + + This implementation of the Calendar stores a list of holidays (full days + that are excluded from scheduling). + + + The implementation DOES take the year into consideration, so if you want to + exclude July 4th for the next 10 years, you need to add 10 entries to the + exclude list. + + Sharada Jambula + Juergen Donnerstag + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The base calendar. + + + + Serialization constructor. + + + + + + + Determine whether the given time (in milliseconds) is 'included' by the + Calendar. + + Note that this Calendar is only has full-day precision. + + + + + + Determine the next time (in milliseconds) that is 'included' by the + Calendar after the given time. + + Note that this Calendar is only has full-day precision. + + + + + + Creates a new object that is a copy of the current instance. + + A new object that is a copy of this instance. + + + + Add the given Date to the list of excluded days. Only the month, day and + year of the returned dates are significant. + + + + + Removes the excluded date. + + The date to remove. + + + + Returns a of Dates representing the excluded + days. Only the month, day and year of the returned dates are + significant. + + + + + This implementation of the Calendar excludes a set of days of the month. You + may use it to exclude every 1. of each month for example. But you may define + any day of a month. + + + + Juergen Donnerstag + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Constructor + + The base calendar. + + + + Serialization constructor. + + + + + + + Initialize internal variables + + + + + Return true, if mday is defined to be exluded. + + + + + Redefine a certain day of the month to be excluded (true) or included + (false). + + + + + Check if all days are excluded. That is no day is included. + + boolean + + + + + Determine whether the given time (in milliseconds) is 'included' by the + Calendar. + + Note that this Calendar is only has full-day precision. + + + + + + Determine the next time (in milliseconds) that is 'included' by the + Calendar after the given time. Return the original value if timeStamp is + included. Return DateTime.MinValue if all days are excluded. + + Note that this Calendar is only has full-day precision. + + + + + + Creates a new object that is a copy of the current instance. + + A new object that is a copy of this instance. + + + + Get or set the array which defines the exclude-value of each day of month + Setting will redefine the array of days excluded. The array must of size greater or + equal 31. + + + + + This implementation of the Calendar excludes a set of days of the week. You + may use it to exclude weekends for example. But you may define any day of + the week. + + + + Juergen Donnerstag + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The base calendar. + + + + Serialization constructor. + + + + + + + Initialize internal variables + + + + + Return true, if wday is defined to be exluded. E. g. + saturday and sunday. + + + + + Redefine a certain day of the week to be excluded (true) or included + (false). Use enum to determine the weekday. + + + + + Check if all week ays are excluded. That is no day is included. + + + + + Determine whether the given time (in milliseconds) is 'included' by the + Calendar. + + Note that this Calendar is only has full-day precision. + + + + + + Determine the next time (in milliseconds) that is 'included' by the + Calendar after the given time. Return the original value if timeStamp is + included. Return DateTime.MinValue if all days are excluded. + + Note that this Calendar is only has full-day precision. + + + + + + Get the array with the week days. + Setting will redefine the array of days excluded. The array must of size greater or + equal 8. java.util.Calendar's constants like MONDAY should be used as + index. A value of true is regarded as: exclude it. + + + + + Matches using an AND operator on two Matcher operands. + + James House + Marko Lahma (.NET) + + + + Matchers can be used in various API methods to + select the entities that should be operated upon. + + James House + + + + + Create an AndMatcher that depends upon the result of both of the given matchers. + + + + + + + + + Matches on the complete key being equal (both name and group). + + + + jhouse + + + + Create an EverythingMatcher that matches all jobs. + + + + + + Create an EverythingMatcher that matches all triggers. + + + + + + Matches on group (ignores name) property of Keys. + + James House + Marko Lahma (.NET) + + + + An abstract base class for some types of matchers. + + James House + Marko Lahma (.NET) + + + + Create a GroupMatcher that matches groups equaling the given string. + + + + + + + Create a GroupMatcher that matches groups starting with the given string. + + + + + + + Create a GroupMatcher that matches groups ending with the given string. + + + + + + + Create a GroupMatcher that matches groups containing the given string. + + + + + + + Matches on the complete key being equal (both name and group). + + James House + Marko Lahma (.NET) + + + + Create a KeyMatcher that matches Keys that equal the given key. + + + + + + + + Matches on name (ignores group) property of Keys. + + James House + Marko Lahma (.NET) + + + + Create a NameMatcher that matches names equaling the given string. + + + + + + + Create a NameMatcher that matches names starting with the given string. + + + + + + + Create a NameMatcher that matches names ending with the given string. + + + + + + + Create a NameMatcher that matches names containing the given string. + + + + + + + Matches using an NOT operator on another Matcher. + + James House + Marko Lahma (.NET) + + + + Create a NotMatcher that reverses the result of the given matcher. + + + + + + + + Matches using an OR operator on two Matcher operands. + + James House + Marko Lahma (.NET) + + + + Create an OrMatcher that depends upon the result of at least one of the given matchers. + + + + + + + + + Operators available for comparing string values. + + + + + The base abstract class to be extended by all triggers. + + + + s have a name and group associated with them, which + should uniquely identify them within a single . + + + + s are the 'mechanism' by which s + are scheduled. Many s can point to the same , + but a single can only point to one . + + + + Triggers can 'send' parameters/data to s by placing contents + into the on the . + + + + + + + + James House + Sharada Jambula + Marko Lahma (.NET) + + + + Internal interface for managing triggers. This interface should not be used by the Quartz client. + + + + + Should not be used by end users. + + + + + The base interface with properties common to all s - + use to instantiate an actual Trigger. + + + + s have a associated with them, which + should uniquely identify them within a single . + + + + s are the 'mechanism' by which s + are scheduled. Many s can point to the same , + but a single can only point to one . + + + + Triggers can 'send' parameters/data to s by placing contents + into the on the . + + + + + + + + + + James House + Sharada Jambula + Marko Lahma (.NET) + + + + Get a that is configured to produce a + schedule identical to this trigger's schedule. + + + + + + Used by the to determine whether or not + it is possible for this to fire again. + + If the returned value is then the + may remove the from the . + + + + + + Returns the next time at which the is scheduled to fire. If + the trigger will not fire again, will be returned. Note that + the time returned can possibly be in the past, if the time that was computed + for the trigger to next fire has already arrived, but the scheduler has not yet + been able to fire the trigger (which would likely be due to lack of resources + e.g. threads). + + + The value returned is not guaranteed to be valid until after the + has been added to the scheduler. + + + + + + Returns the previous time at which the fired. + If the trigger has not yet fired, will be returned. + + + + + Returns the next time at which the will fire, + after the given time. If the trigger will not fire after the given time, + will be returned. + + + + + Get or set the description given to the instance by + its creator (if any). + + + + + Get or set the with the given name with + this Trigger. Use when setting to dis-associate a Calendar. + + + + + Get or set the that is associated with the + . + + Changes made to this map during job execution are not re-persisted, and + in fact typically result in an illegal state. + + + + + + Returns the last UTC time at which the will fire, if + the Trigger will repeat indefinitely, null will be returned. + + Note that the return time *may* be in the past. + + + + + + Get or set the instruction the should be given for + handling misfire situations for this - the + concrete type that you are using will have + defined a set of additional MISFIRE_INSTRUCTION_XXX + constants that may be set to this property. + + If not explicitly set, the default value is . + + + + + + + + + Gets and sets the date/time on which the trigger must stop firing. This + defines the final boundary for trigger firings 舒 the trigger will + not fire after to this date and time. If this value is null, no end time + boundary is assumed, and the trigger can continue indefinitely. + + + + + The time at which the trigger's scheduling should start. May or may not + be the first actual fire time of the trigger, depending upon the type of + trigger and the settings of the other properties of the trigger. However + the first actual first time will not be before this date. + + + Setting a value in the past may cause a new trigger to compute a first + fire time that is in the past, which may cause an immediate misfire + of the trigger. + + + + + The priority of a acts as a tie breaker such that if + two s have the same scheduled fire time, then Quartz + will do its best to give the one with the higher priority first access + to a worker thread. + + + If not explicitly set, the default value is 5. + + + + + + + Set a description for the instance - may be + useful for remembering/displaying the purpose of the trigger, though the + description has no meaning to Quartz. + + + + + Associate the with the given name with this Trigger. + + + + + Set the to be associated with the + . + + + + + The priority of a acts as a tie breaker such that if + two s have the same scheduled fire time, then Quartz + will do its best to give the one with the higher priority first access + to a worker thread. + + + If not explicitly set, the default value is 5. + + + + + + + The time at which the trigger's scheduling should start. May or may not + be the first actual fire time of the trigger, depending upon the type of + trigger and the settings of the other properties of the trigger. However + the first actual first time will not be before this date. + + + Setting a value in the past may cause a new trigger to compute a first + fire time that is in the past, which may cause an immediate misfire + of the trigger. + + ew DateTimeOffset StartTimeUtc { get; set; } + + + + + + Set the time at which the should quit repeating - + regardless of any remaining repeats (based on the trigger's particular + repeat settings). + + + + + + + + Set the instruction the should be given for + handling misfire situations for this - the + concrete type that you are using will have + defined a set of additional MisfireInstruction.XXX + constants that may be passed to this method. + + + If not explicitly set, the default value is . + + + + + + + + This method should not be used by the Quartz client. + + + Called when the has decided to 'fire' + the trigger (Execute the associated ), in order to + give the a chance to update itself for its next + triggering (if any). + + + + + + This method should not be used by the Quartz client. + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + + + After this method has been called, + should return a valid answer. + + + + The first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first firing of the ). + + + + + This method should not be used by the Quartz client. + + + Called after the has executed the + associated with the + in order to get the final instruction code from the trigger. + + + is the that was used by the + 's method. + is the thrown by the + , if any (may be null). + + + One of the members. + + + + + + + + + + This method should not be used by the Quartz client. + + To be implemented by the concrete classes that extend this class. + + + The implementation should update the 's state + based on the MISFIRE_INSTRUCTION_XXX that was selected when the + was created. + + + + + + This method should not be used by the Quartz client. + + The implementation should update the 's state + based on the given new version of the associated + (the state should be updated so that it's next fire time is appropriate + given the Calendar's new settings). + + + + + + + + Validates whether the properties of the are + valid for submission into a . + + + + + This method should not be used by the Quartz client. + + + Usable by + implementations, in order to facilitate 'recognizing' instances of fired + s as their jobs complete execution. + + + + + Returns the previous time at which the fired. + If the trigger has not yet fired, will be returned. + + + + + Create a with no specified name, group, or . + + + Note that the , and + the and properties + must be set before the can be placed into a + . + + + + + Create a with the given name, and default group. + + + Note that the and + properties must be set before the + can be placed into a . + + The name. + + + + Create a with the given name, and group. + + + Note that the and + properties must be set before the + can be placed into a . + + The name. + if , Scheduler.DefaultGroup will be used. + + + + Create a with the given name, and group. + + The name. + if , Scheduler.DefaultGroup will be used. + Name of the job. + The job group. + ArgumentException + if name is null or empty, or the group is an empty string. + + + + + This method should not be used by the Quartz client. + + + Called when the has decided to 'fire' + the trigger (Execute the associated ), in order to + give the a chance to update itself for its next + triggering (if any). + + + + + + This method should not be used by the Quartz client. + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + + + After this method has been called, + should return a valid answer. + + + + The first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first firing of the ). + + + + + This method should not be used by the Quartz client. + + + Called after the has executed the + associated with the + in order to get the final instruction code from the trigger. + + + is the that was used by the + 's method. + is the thrown by the + , if any (may be null). + + + One of the members. + + + + + + + Used by the to determine whether or not + it is possible for this to fire again. + + If the returned value is then the + may remove the from the . + + + + + + Returns the next time at which the is scheduled to fire. If + the trigger will not fire again, will be returned. Note that + the time returned can possibly be in the past, if the time that was computed + for the trigger to next fire has already arrived, but the scheduler has not yet + been able to fire the trigger (which would likely be due to lack of resources + e.g. threads). + + + The value returned is not guaranteed to be valid until after the + has been added to the scheduler. + + + + + + Returns the next time at which the will fire, + after the given time. If the trigger will not fire after the given time, + will be returned. + + + + + Validates the misfire instruction. + + The misfire instruction. + + + + + This method should not be used by the Quartz client. + + To be implemented by the concrete classes that extend this class. + + + The implementation should update the 's state + based on the MISFIRE_INSTRUCTION_XXX that was selected when the + was created. + + + + + + This method should not be used by the Quartz client. + + The implementation should update the 's state + based on the given new version of the associated + (the state should be updated so that it's next fire time is appropriate + given the Calendar's new settings). + + + + + + + + Validates whether the properties of the are + valid for submission into a . + + + + + Return a simple string representation of this object. + + + + + Compare the next fire time of this to that of + another by comparing their keys, or in other words, sorts them + according to the natural (i.e. alphabetical) order of their keys. + + + + + + + Determines whether the specified is equal to the current . + + The to compare with the current . + + true if the specified is equal to the current ; otherwise, false. + + + + + Trigger equality is based upon the equality of the TriggerKey. + + + true if the key of this Trigger equals that of the given Trigger + + + + Serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Creates a new object that is a copy of the current instance. + + + A new object that is a copy of this instance. + + + + + Get or sets the name of this . + + If name is null or empty. + + + + Get the group of this . If , Scheduler.DefaultGroup will be used. + + + if group is an empty string. + + + + + Get or set the name of the associated . + + + if jobName is null or empty. + + + + + Gets or sets the name of the associated 's + group. If set with , Scheduler.DefaultGroup will be used. + + ArgumentException + if group is an empty string. + + + + + Returns the 'full name' of the in the format + "group.name". + + + + + Gets the key. + + The key. + + + + Returns the 'full name' of the that the + points to, in the format "group.name". + + + + + Get or set the description given to the instance by + its creator (if any). + + + + + Get or set the with the given name with + this Trigger. Use when setting to dis-associate a Calendar. + + + + + Get or set the that is associated with the + . + + Changes made to this map during job execution are not re-persisted, and + in fact typically result in an illegal state. + + + + + + Returns the last UTC time at which the will fire, if + the Trigger will repeat indefinitely, null will be returned. + + Note that the return time *may* be in the past. + + + + + + Get or set the instruction the should be given for + handling misfire situations for this - the + concrete type that you are using will have + defined a set of additional MISFIRE_INSTRUCTION_XXX + constants that may be passed to this method. + + If not explicitly set, the default value is . + + + + + + + + + + This method should not be used by the Quartz client. + + + Usable by + implementations, in order to facilitate 'recognizing' instances of fired + s as their jobs complete execution. + + + + + Gets and sets the date/time on which the trigger must stop firing. This + defines the final boundary for trigger firings 舒 the trigger will + not fire after to this date and time. If this value is null, no end time + boundary is assumed, and the trigger can continue indefinitely. + + + + + The time at which the trigger's scheduling should start. May or may not + be the first actual fire time of the trigger, depending upon the type of + trigger and the settings of the other properties of the trigger. However + the first actual first time will not be before this date. + + + Setting a value in the past may cause a new trigger to compute a first + fire time that is in the past, which may cause an immediate misfire + of the trigger. + + + + + Tells whether this Trigger instance can handle events + in millisecond precision. + + + + + The priority of a acts as a tie breaker such that if + two s have the same scheduled fire time, then Quartz + will do its best to give the one with the higher priority first access + to a worker thread. + + + If not explicitly set, the default value is 5. + + + + + + + Gets a value indicating whether this instance has additional properties + that should be considered when for example saving to database. + + + If trigger implementation has additional properties that need to be saved + with base properties you need to make your class override this property with value true. + Returning true will effectively mean that ADOJobStore needs to serialize + this trigger instance to make sure additional properties are also saved. + + + true if this instance has additional properties; otherwise, false. + + + + + A concrete that is used to fire a + based upon repeating calendar time intervals. + + + The trigger will fire every N (see ) units of calendar time + (see ) as specified in the trigger's definition. + This trigger can achieve schedules that are not possible with (e.g + because months are not a fixed number of seconds) or (e.g. because + "every 5 months" is not an even divisor of 12). + + If you use an interval unit of then care should be taken when setting + a value that is on a day near the end of the month. For example, + if you choose a start time that occurs on January 31st, and have a trigger with unit + and interval 1, then the next fire time will be February 28th, + and the next time after that will be March 28th - and essentially each subsequent firing will + occur on the 28th of the month, even if a 31st day exists. If you want a trigger that always + fires on the last day of the month - regardless of the number of days in the month, + you should use . + + + + + + + 2.0 + James House + Marko Lahma (.NET) + + + + A that is used to fire a + based upon repeating calendar time intervals. + + + + + Get or set the interval unit - the time unit on with the interval applies. + + + + + Get the the time interval that will be added to the 's + fire time (in the set repeat interval unit) in order to calculate the time of the + next trigger repeat. + + + + + Get the number of times the has already fired. + + + + + Gets the time zone within which time calculations related to this trigger will be performed. + + + If null, the system default TimeZone will be used. + + + + + If intervals are a day or greater, this property (set to true) will + cause the firing of the trigger to always occur at the same time of day, + (the time of day of the startTime) regardless of daylight saving time + transitions. Default value is false. + + + + For example, without the property set, your trigger may have a start + time of 9:00 am on March 1st, and a repeat interval of 2 days. But + after the daylight saving transition occurs, the trigger may start + firing at 8:00 am every other day. + + + If however, the time of day does not exist on a given day to fire + (e.g. 2:00 am in the United States on the days of daylight saving + transition), the trigger will go ahead and fire one hour off on + that day, and then resume the normal hour on other days. If + you wish for the trigger to never fire at the "wrong" hour, then + you should set the property skipDayIfHourDoesNotExist. + + + + + + + + + If intervals are a day or greater, and + preserveHourOfDayAcrossDaylightSavings property is set to true, and the + hour of the day does not exist on a given day for which the trigger + would fire, the day will be skipped and the trigger advanced a second + interval if this property is set to true. Defaults to false. + + + CAUTION! If you enable this property, and your hour of day happens + to be that of daylight savings transition (e.g. 2:00 am in the United + States) and the trigger's interval would have had the trigger fire on + that day, then you may actually completely miss a firing on the day of + transition if that hour of day does not exist on that day! In such a + case the next fire time of the trigger will be computed as double (if + the interval is 2 days, then a span of 4 days between firings will + occur). + + + + + + Create a with no settings. + + + + + Create a that will occur immediately, and + repeat at the the given interval. + + Name for the trigger instance. + The repeat interval unit (minutes, days, months, etc). + The number of milliseconds to pause between the repeat firing. + + + + Create a that will occur immediately, and + repeat at the the given interval + + Name for the trigger instance. + Group for the trigger instance. + The repeat interval unit (minutes, days, months, etc). + The number of milliseconds to pause between the repeat firing. + + + + Create a that will occur at the given time, + and repeat at the the given interval until the given end time. + + Name for the trigger instance. + A set to the time for the to fire. + A set to the time for the to quit repeat firing. + The repeat interval unit (minutes, days, months, etc). + The number of milliseconds to pause between the repeat firing. + + + + Create a that will occur at the given time, + and repeat at the the given interval until the given end time. + + Name for the trigger instance. + Group for the trigger instance. + A set to the time for the to fire. + A set to the time for the to quit repeat firing. + The repeat interval unit (minutes, days, months, etc). + The number of milliseconds to pause between the repeat firing. + + + + Create a that will occur at the given time, + and repeat at the the given interval until the given end time. + + Name for the trigger instance. + Group for the trigger instance. + Name of the associated job. + Group of the associated job. + A set to the time for the to fire. + A set to the time for the to quit repeat firing. + The repeat interval unit (minutes, days, months, etc). + The number of milliseconds to pause between the repeat firing. + + + + Validates the misfire instruction. + + The misfire instruction. + + + + + Updates the 's state based on the + MisfireInstruction.XXX that was selected when the + was created. + + + If the misfire instruction is set to , + then the following scheme will be used: +
    +
  • The instruction will be interpreted as
    • +
+ + + + + This method should not be used by the Quartz client. + + Called when the has decided to 'fire' + the trigger (Execute the associated ), in order to + give the a chance to update itself for its next + triggering (if any). + + + + + + + This method should not be used by the Quartz client. + + The implementation should update the 's state + based on the given new version of the associated + (the state should be updated so that it's next fire time is appropriate + given the Calendar's new settings). + + + + + + + + This method should not be used by the Quartz client. + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + + + After this method has been called, + should return a valid answer. + + + + The first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first firing of the ). + + + + + Returns the next time at which the is scheduled to fire. If + the trigger will not fire again, will be returned. Note that + the time returned can possibly be in the past, if the time that was computed + for the trigger to next fire has already arrived, but the scheduler has not yet + been able to fire the trigger (which would likely be due to lack of resources + e.g. threads). + + + The value returned is not guaranteed to be valid until after the + has been added to the scheduler. + + + + + + Returns the previous time at which the fired. + If the trigger has not yet fired, will be returned. + + + + + Returns the next time at which the will fire, + after the given time. If the trigger will not fire after the given time, + will be returned. + + + + + Determines whether or not the will occur + again. + + + + + + Validates whether the properties of the are + valid for submission into a . + + + + + Get a that is configured to produce a + schedule identical to this trigger's schedule. + + + + + + + + Get the time at which the should occur. + + + + + Tells whether this Trigger instance can handle events + in millisecond precision. + + + + + Get the time at which the should quit + repeating. + + + + + Get or set the interval unit - the time unit on with the interval applies. + + + + + Get the the time interval that will be added to the 's + fire time (in the set repeat interval unit) in order to calculate the time of the + next trigger repeat. + + + + + If intervals are a day or greater, this property (set to true) will + cause the firing of the trigger to always occur at the same time of day, + (the time of day of the startTime) regardless of daylight saving time + transitions. Default value is false. + + + + For example, without the property set, your trigger may have a start + time of 9:00 am on March 1st, and a repeat interval of 2 days. But + after the daylight saving transition occurs, the trigger may start + firing at 8:00 am every other day. + + + If however, the time of day does not exist on a given day to fire + (e.g. 2:00 am in the United States on the days of daylight saving + transition), the trigger will go ahead and fire one hour off on + that day, and then resume the normal hour on other days. If + you wish for the trigger to never fire at the "wrong" hour, then + you should set the property skipDayIfHourDoesNotExist. + + + + + + + + + If intervals are a day or greater, and + preserveHourOfDayAcrossDaylightSavings property is set to true, and the + hour of the day does not exist on a given day for which the trigger + would fire, the day will be skipped and the trigger advanced a second + interval if this property is set to true. Defaults to false. + + + CAUTION! If you enable this property, and your hour of day happens + to be that of daylight savings transition (e.g. 2:00 am in the United + States) and the trigger's interval would have had the trigger fire on + that day, then you may actually completely miss a firing on the day of + transition if that hour of day does not exist on that day! In such a + case the next fire time of the trigger will be computed as double (if + the interval is 2 days, then a span of 4 days between firings will + occur). + + + + + + Get the number of times the has already fired. + + + + + Returns the final time at which the will + fire, if there is no end time set, null will be returned. + + + Note that the return time may be in the past. + + + + A concrete that is used to fire a + at given moments in time, defined with Unix 'cron-like' definitions. + + + + For those unfamiliar with "cron", this means being able to create a firing + schedule such as: "At 8:00am every Monday through Friday" or "At 1:30am + every last Friday of the month". + + + + The format of a "Cron-Expression" string is documented on the + class. + + + + Here are some full examples:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Expression Meaning
"0 0 12 * * ?"" /> Fire at 12pm (noon) every day" />
"0 15 10 ? * *"" /> Fire at 10:15am every day" />
"0 15 10 * * ?"" /> Fire at 10:15am every day" />
"0 15 10 * * ? *"" /> Fire at 10:15am every day" />
"0 15 10 * * ? 2005"" /> Fire at 10:15am every day during the year 2005" /> +
"0 * 14 * * ?"" /> Fire every minute starting at 2pm and ending at 2:59pm, every day" /> +
"0 0/5 14 * * ?"" /> Fire every 5 minutes starting at 2pm and ending at 2:55pm, every day" /> +
"0 0/5 14,18 * * ?"" /> Fire every 5 minutes starting at 2pm and ending at 2:55pm, AND fire every 5 minutes starting at 6pm and ending at 6:55pm, every day" /> +
"0 0-5 14 * * ?"" /> Fire every minute starting at 2pm and ending at 2:05pm, every day" /> +
"0 10,44 14 ? 3 WED"" /> Fire at 2:10pm and at 2:44pm every Wednesday in the month of March." /> +
"0 15 10 ? * MON-FRI"" /> Fire at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday" /> +
"0 15 10 15 * ?"" /> Fire at 10:15am on the 15th day of every month" /> +
"0 15 10 L * ?"" /> Fire at 10:15am on the last day of every month" /> +
"0 15 10 ? * 6L"" /> Fire at 10:15am on the last Friday of every month" /> +
"0 15 10 ? * 6L"" /> Fire at 10:15am on the last Friday of every month" /> +
"0 15 10 ? * 6L 2002-2005"" /> Fire at 10:15am on every last Friday of every month during the years 2002, 2003, 2004 and 2005" /> +
"0 15 10 ? * 6#3"" /> Fire at 10:15am on the third Friday of every month" /> +
+ + + + Pay attention to the effects of '?' and '*' in the day-of-week and + day-of-month fields! + + + + NOTES: +
    +
  • Support for specifying both a day-of-week and a day-of-month value is + not complete (you'll need to use the '?' character in on of these fields). +
    • +
  • Be careful when setting fire times between mid-night and 1:00 AM - + "daylight savings" can cause a skip or a repeat depending on whether the + time moves back or jumps forward.
    • +
+ + + + + Sharada Jambula + James House + Contributions from Mads Henderson + Marko Lahma (.NET) + + + + The public interface for inspecting settings specific to a CronTrigger, + which is used to fire a + at given moments in time, defined with Unix 'cron-like' schedule definitions. + + + + For those unfamiliar with "cron", this means being able to create a firing + schedule such as: "At 8:00am every Monday through Friday" or "At 1:30am + every last Friday of the month". + + + + The format of a "Cron-Expression" string is documented on the + class. + + + + Here are some full examples:
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Expression Meaning
"0 0 12 * * ?"" /> Fire at 12pm (noon) every day" />
"0 15 10 ? * *"" /> Fire at 10:15am every day" />
"0 15 10 * * ?"" /> Fire at 10:15am every day" />
"0 15 10 * * ? *"" /> Fire at 10:15am every day" />
"0 15 10 * * ? 2005"" /> Fire at 10:15am every day during the year 2005" /> +
"0 * 14 * * ?"" /> Fire every minute starting at 2pm and ending at 2:59pm, every day" /> +
"0 0/5 14 * * ?"" /> Fire every 5 minutes starting at 2pm and ending at 2:55pm, every day" /> +
"0 0/5 14,18 * * ?"" /> Fire every 5 minutes starting at 2pm and ending at 2:55pm, AND fire every 5 minutes starting at 6pm and ending at 6:55pm, every day" /> +
"0 0-5 14 * * ?"" /> Fire every minute starting at 2pm and ending at 2:05pm, every day" /> +
"0 10,44 14 ? 3 WED"" /> Fire at 2:10pm and at 2:44pm every Wednesday in the month of March." /> +
"0 15 10 ? * MON-FRI"" /> Fire at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday" /> +
"0 15 10 15 * ?"" /> Fire at 10:15am on the 15th day of every month" /> +
"0 15 10 L * ?"" /> Fire at 10:15am on the last day of every month" /> +
"0 15 10 ? * 6L"" /> Fire at 10:15am on the last Friday of every month" /> +
"0 15 10 ? * 6L"" /> Fire at 10:15am on the last Friday of every month" /> +
"0 15 10 ? * 6L 2002-2005"" /> Fire at 10:15am on every last Friday of every month during the years 2002, 2003, 2004 and 2005" /> +
"0 15 10 ? * 6#3"" /> Fire at 10:15am on the third Friday of every month" /> +
+ + + + Pay attention to the effects of '?' and '*' in the day-of-week and + day-of-month fields! + + + + NOTES: +
    +
  • Support for specifying both a day-of-week and a day-of-month value is + not complete (you'll need to use the '?' character in on of these fields). +
    • +
  • Be careful when setting fire times between mid-night and 1:00 AM - + "daylight savings" can cause a skip or a repeat depending on whether the + time moves back or jumps forward.
    • +
+ + + + + Sharada Jambula + James House + Contributions from Mads Henderson + Marko Lahma (.NET) + + + + Gets the expression summary. + + + + + + Gets or sets the cron expression string. + + The cron expression string. + + + + Sets the time zone for which the of this + will be resolved. + + + If is set after this + property, the TimeZone setting on the CronExpression will "win". However + if is set after this property, the + time zone applied by this method will remain in effect, since the + string cron expression does not carry a time zone! + + The time zone. + + + + Create a with no settings. + + + The start-time will also be set to the current time, and the time zone + will be set the the system's default time zone. + + + + + Create a with the given name and default group. + + + The start-time will also be set to the current time, and the time zone + will be set the the system's default time zone. + + The name of the + + + + Create a with the given name and group. + + + The start-time will also be set to the current time, and the time zone + will be set the the system's default time zone. + + The name of the + The group of the + + + + Create a with the given name, group and + expression. + + + The start-time will also be set to the current time, and the time zone + will be set the the system's default time zone. + + The name of the + The group of the + A cron expression dictating the firing sequence of the + + + + Create a with the given name and group, and + associated with the identified . + + + The start-time will also be set to the current time, and the time zone + will be set the the system's default time zone. + + The name of the . + The group of the + name of the executed on firetime + Group of the executed on firetime + + + + Create a with the given name and group, + associated with the identified , + and with the given "cron" expression. + + + The start-time will also be set to the current time, and the time zone + will be set the the system's default time zone. + + The name of the + The group of the + name of the executed on firetime + Group of the executed on firetime + A cron expression dictating the firing sequence of the + + + + Create a with the given name and group, + associated with the identified , + and with the given "cron" expression resolved with respect to the . + + The name of the + The group of the + name of the executed on firetime + Group of the executed on firetime + A cron expression dictating the firing sequence of the + + Specifies for which time zone the cronExpression should be interpreted, + i.e. the expression 0 0 10 * * ?, is resolved to 10:00 am in this time zone. + + + + + Create a that will occur at the given time, + until the given end time. + + If null, the start-time will also be set to the current time, the time + zone will be set the the system's default. + + + The name of the + The group of the + name of the executed on firetime + Group of the executed on firetime + A set to the earliest time for the to start firing. + A set to the time for the to quit repeat firing. + A cron expression dictating the firing sequence of the + + + + Create a with fire time dictated by the + resolved with respect to the specified + occurring from the until + the given . + + The name of the + The group of the + name of the executed on firetime + Group of the executed on firetime + A set to the earliest time for the to start firing. + A set to the time for the to quit repeat firing. + + + + Clones this instance. + + + + + + Returns the next time at which the is scheduled to fire. If + the trigger will not fire again, will be returned. Note that + the time returned can possibly be in the past, if the time that was computed + for the trigger to next fire has already arrived, but the scheduler has not yet + been able to fire the trigger (which would likely be due to lack of resources + e.g. threads). + + + The value returned is not guaranteed to be valid until after the + has been added to the scheduler. + + + + + + Returns the previous time at which the fired. + If the trigger has not yet fired, will be returned. + + + + + + Sets the next fire time. + + This method should not be invoked by client code. + + + The fire time. + + + + Sets the previous fire time. + + This method should not be invoked by client code. + + + The fire time. + + + + Returns the next time at which the will fire, + after the given time. If the trigger will not fire after the given time, + will be returned. + + + + + + + Used by the to determine whether or not + it is possible for this to fire again. + + If the returned value is then the + may remove the from the . + + + + + + + Validates the misfire instruction. + + The misfire instruction. + + + + + This method should not be used by the Quartz client. + + To be implemented by the concrete classes that extend this class. + + + The implementation should update the 's state + based on the MISFIRE_INSTRUCTION_XXX that was selected when the + was created. + + + + + + + + Determines whether the date and (optionally) time of the given Calendar + instance falls on a scheduled fire-time of this trigger. + + + + Equivalent to calling . + + + The date to compare. + + + + + Determines whether the date and (optionally) time of the given Calendar + instance falls on a scheduled fire-time of this trigger. + + Note that the value returned is NOT validated against the related + ICalendar (if any). + + + The date to compare + If set to true, the method will only determine if the + trigger will fire during the day represented by the given Calendar + (hours, minutes and seconds will be ignored). + + + + + Called when the has decided to 'fire' + the trigger (Execute the associated ), in order to + give the a chance to update itself for its next + triggering (if any). + + + + + + + Updates the trigger with new calendar. + + The calendar to update with. + The misfire threshold. + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + After this method has been called, + should return a valid answer. + + + + + the first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first firing of the ). + + + + + Gets the expression summary. + + + + + + Gets the next time to fire after the given time. + + The time to compute from. + + + + + NOT YET IMPLEMENTED: Returns the time before the given time + that this will fire. + + The date. + + + + + Gets or sets the cron expression string. + + The cron expression string. + + + + Set the CronExpression to the given one. The TimeZone on the passed-in + CronExpression over-rides any that was already set on the Trigger. + + The cron expression. + + + + Returns the date/time on which the trigger may begin firing. This + defines the initial boundary for trigger firings the trigger + will not fire prior to this date and time. + + + + + + Get or sets the time at which the CronTrigger should quit + repeating - even if repeastCount isn't yet satisfied. + + + + + Sets the time zone for which the of this + will be resolved. + + + If is set after this + property, the TimeZone setting on the CronExpression will "win". However + if is set after this property, the + time zone applied by this method will remain in effect, since the + string cron expression does not carry a time zone! + + The time zone. + + + + Returns the last UTC time at which the will fire, if + the Trigger will repeat indefinitely, null will be returned. + + Note that the return time *may* be in the past. + + + + + + Tells whether this Trigger instance can handle events + in millisecond precision. + + + + + + A concrete implementation of DailyTimeIntervalTrigger that is used to fire a + based upon daily repeating time intervals. + + + + The trigger will fire every N ( ) seconds, minutes or hours + (see ) during a given time window on specified days of the week. + + + For example#1, a trigger can be set to fire every 72 minutes between 8:00 and 11:00 everyday. It's fire times would + be 8:00, 9:12, 10:24, then next day would repeat: 8:00, 9:12, 10:24 again. + + + For example#2, a trigger can be set to fire every 23 minutes between 9:20 and 16:47 Monday through Friday. + + + On each day, the starting fire time is reset to startTimeOfDay value, and then it will add repeatInterval value to it until + the endTimeOfDay is reached. If you set daysOfWeek values, then fire time will only occur during those week days period. Again, + remember this trigger will reset fire time each day with startTimeOfDay, regardless of your interval or endTimeOfDay! + + + The default values for fields if not set are: startTimeOfDay defaults to 00:00:00, the endTimeOfDay default to 23:59:59, + and daysOfWeek is default to every day. The startTime default to current time-stamp now, while endTime has not value. + + + If startTime is before startTimeOfDay, then startTimeOfDay will be used and startTime has no affect. Else if startTime is + after startTimeOfDay, then the first fire time for that day will be the next interval after the startTime. For example, if + you set startingTimeOfDay=9am, endingTimeOfDay=11am, interval=15 mins, and startTime=9:33am, then the next fire time will + be 9:45pm. Note also that if you do not set startTime value, the trigger builder will default to current time, and current time + maybe before or after the startTimeOfDay! So be aware how you set your startTime. + + + This trigger also supports "repeatCount" feature to end the trigger fire time after + a certain number of count is reached. Just as the SimpleTrigger, setting repeatCount=0 + means trigger will fire once only! Setting any positive count then the trigger will repeat + count + 1 times. Unlike SimpleTrigger, the default value of repeatCount of this trigger + is set to REPEAT_INDEFINITELY instead of 0 though. + + + + + 2.0 + James House + Zemian Deng saltnlight5@gmail.com + Nuno Maia (.NET) + + + + A that is used to fire a + based upon daily repeating time intervals. + + + The trigger will fire every N (see ) seconds, minutes or hours + (see during a given time window on specified days of the week. + + For example#1, a trigger can be set to fire every 72 minutes between 8:00 and 11:00 everyday. It's fire times + be 8:00, 9:12, 10:24, then next day would repeat: 8:00, 9:12, 10:24 again. + + For example#2, a trigger can be set to fire every 23 minutes between 9:20 and 16:47 Monday through Friday. + + On each day, the starting fire time is reset to startTimeOfDay value, and then it will add repeatInterval value to it until + the endTimeOfDay is reached. If you set daysOfWeek values, then fire time will only occur during those week days period. + + The default values for fields if not set are: startTimeOfDay defaults to 00:00:00, the endTimeOfDay default to 23:59:59, + and daysOfWeek is default to every day. The startTime default to current time-stamp now, while endTime has not value. + + If startTime is before startTimeOfDay, then it has no affect. Else if startTime after startTimeOfDay, then the first fire time + for that day will be normal startTimeOfDay incremental values after startTime value. Same reversal logic is applied to endTime + with endTimeOfDay. + + + + James House + Zemian Deng saltnlight5@gmail.com + Nuno Maia (.NET) + + + + + + + + + Get the the number of times for interval this trigger should repeat, + after which it will be automatically deleted. + + + + + Get the interval unit - the time unit on with the interval applies. + The only intervals that are valid for this type of trigger are , + , and + + + + + Get the the time interval that will be added to the 's + fire time (in the set repeat interval unit) in order to calculate the time of the + next trigger repeat. + + + + + The time of day to start firing at the given interval. + + + + + The time of day to complete firing at the given interval. + + + + + The days of the week upon which to fire. + + + A Set containing the integers representing the days of the week, per the values 0-6 as defined by + DayOfWees.Sunday - DayOfWeek.Saturday. + + + + + Get the number of times the has already fired. + + + + + Used to indicate the 'repeat count' of the trigger is indefinite. Or in + other words, the trigger should repeat continually until the trigger's + ending timestamp. + + + + + Create a with no settings. + + + + + Create a that will occur immediately, and + repeat at the the given interval. + + + The that the repeating should begin occurring. + The that the repeating should stop occurring. + The repeat interval unit. The only intervals that are valid for this type of trigger are + , , and . + + + + + Create a that will occur immediately, and + repeat at the the given interval. + + + + The that the repeating should begin occurring. + The that the repeating should stop occurring. + The repeat interval unit. The only intervals that are valid for this type of trigger are + , , and . + + + + + Create a that will occur at the given time, + and repeat at the the given interval until the given end time. + + + A set to the time for the to fire. + A set to the time for the to quit repeat firing. + The that the repeating should begin occurring. + The that the repeating should stop occurring. + The repeat interval unit. The only intervals that are valid for this type of trigger are + , , and . + The number of milliseconds to pause between the repeat firing. + + + + Create a that will occur at the given time, + and repeat at the the given interval until the given end time. + + + + A set to the time for the to fire. + A set to the time for the to quit repeat firing. + The that the repeating should begin occurring. + The that the repeating should stop occurring. + The repeat interval unit. The only intervals that are valid for this type of trigger are + , , and . + The number of milliseconds to pause between the repeat firing. + + + + Create a that will occur at the given time, + fire the identified job and repeat at the the given + interval until the given end time. + + + + + + A set to the time for the to fire. + A set to the time for the to quit repeat firing. + The that the repeating should begin occurring. + The that the repeating should stop occurring. + The repeat interval unit. The only intervals that are valid for this type of trigger are + , , and . + The number of milliseconds to pause between the repeat firing. + + + + Updates the 's state based on the + MisfireInstruction.XXX that was selected when the + was created. + + + If the misfire instruction is set to , + then the following scheme will be used: +
    +
  • The instruction will be interpreted as
    • +
+ + + + + Called when the scheduler has decided to 'fire' + the trigger (execute the associated job), in order to + give the trigger a chance to update itself for its next + triggering (if any). + + + + + + + + + + + + + + + This method should not be used by the Quartz client. + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + + + After this method has been called, + should return a valid answer. + + + + The first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first firing of the ). + + + + + Returns the next time at which the is scheduled to fire. If + the trigger will not fire again, will be returned. Note that + the time returned can possibly be in the past, if the time that was computed + for the trigger to next fire has already arrived, but the scheduler has not yet + been able to fire the trigger (which would likely be due to lack of resources + e.g. threads). + + + The value returned is not guaranteed to be valid until after the + has been added to the scheduler. + + + + + + Returns the previous time at which the fired. + If the trigger has not yet fired, will be returned. + + + + + Set the next time at which the should fire. + + + This method should not be invoked by client code. + + + + + + Set the previous time at which the fired. + + + This method should not be invoked by client code. + + + + + + Returns the next time at which the will + fire, after the given time. If the trigger will not fire after the given + time, will be returned. + + + + + + + Given fireTime time, we need to advance/calculate and return a time of next available week day. + + given next fireTime. + flag to whether to advance day without check existing week day. This scenario + can happen when a caller determine fireTime has passed the endTimeOfDay that fireTime should move to next day anyway. + + a next day fireTime. + + + + Determines whether or not the will occur + again. + + + + + + Validates whether the properties of the are + valid for submission into a . + + + + + Get a that is configured to produce a + schedule identical to this trigger's schedule. + + + + + + + The time at which the should occur. + + + + + the time at which the should quit repeating. + + + + + + Get the the number of times for interval this trigger should repeat, + after which it will be automatically deleted. + + + + + the interval unit - the time unit on with the interval applies. + + + The repeat interval unit. The only intervals that are valid for this type of trigger are + , , and . + + + + + the the time interval that will be added to the 's + fire time (in the set repeat interval unit) in order to calculate the time of the + next trigger repeat. + + + + + the number of times the has already + fired. + + + + + Returns the final time at which the will + fire, if there is no end time set, null will be returned. + + Note that the return time may be in the past. + + + + + The days of the week upon which to fire. + + + A Set containing the integers representing the days of the week, per the values 0-6 as defined by + DayOfWees.Sunday - DayOfWeek.Saturday. + + + + + The time of day to start firing at the given interval. + + + + + The time of day to complete firing at the given interval. + + + + + This trigger has no additional properties besides what's defined in this class. + + + + + + Tells whether this Trigger instance can handle events + in millisecond precision. + + + + + A concrete that is used to fire a + at a given moment in time, and optionally repeated at a specified interval. + + + + James House + Contributions by Lieven Govaerts of Ebitec Nv, Belgium. + Marko Lahma (.NET) + + + + A that is used to fire a + at a given moment in time, and optionally repeated at a specified interval. + + + + James House + Contributions by Lieven Govaerts of Ebitec Nv, Belgium. + Marko Lahma (.NET) + + + + Get or set thhe number of times the should + repeat, after which it will be automatically deleted. + + + + + + Get or set the the time interval at which the should repeat. + + + + + Get or set the number of times the has already + fired. + + + + + Used to indicate the 'repeat count' of the trigger is indefinite. Or in + other words, the trigger should repeat continually until the trigger's + ending timestamp. + + + + + Create a with no settings. + + + + + Create a that will occur immediately, and + not repeat. + + + + + Create a that will occur immediately, and + not repeat. + + + + + Create a that will occur immediately, and + repeat at the the given interval the given number of times. + + + + + Create a that will occur immediately, and + repeat at the the given interval the given number of times. + + + + + Create a that will occur at the given time, + and not repeat. + + + + + Create a that will occur at the given time, + and not repeat. + + + + + Create a that will occur at the given time, + and repeat at the the given interval the given number of times, or until + the given end time. + + The name. + A UTC set to the time for the to fire. + A UTC set to the time for the + to quit repeat firing. + The number of times for the to repeat + firing, use for unlimited times. + The time span to pause between the repeat firing. + + + + Create a that will occur at the given time, + and repeat at the the given interval the given number of times, or until + the given end time. + + The name. + The group. + A UTC set to the time for the to fire. + A UTC set to the time for the + to quit repeat firing. + The number of times for the to repeat + firing, use for unlimited times. + The time span to pause between the repeat firing. + + + + Create a that will occur at the given time, + fire the identified and repeat at the the given + interval the given number of times, or until the given end time. + + The name. + The group. + Name of the job. + The job group. + A set to the time for the + to fire. + A set to the time for the + to quit repeat firing. + The number of times for the to repeat + firing, use RepeatIndefinitely for unlimited times. + The time span to pause between the repeat firing. + + + + Validates the misfire instruction. + + The misfire instruction. + + + + + Updates the 's state based on the + MisfireInstruction value that was selected when the + was created. + + + If MisfireSmartPolicyEnabled is set to true, + then the following scheme will be used:
+
    +
  • If the Repeat Count is 0, then the instruction will + be interpreted as .
    • +
  • If the Repeat Count is , then + the instruction will be interpreted as . + WARNING: using MisfirePolicy.SimpleTrigger.RescheduleNowWithRemainingRepeatCount + with a trigger that has a non-null end-time may cause the trigger to + never fire again if the end-time arrived during the misfire time span. +
    • +
  • If the Repeat Count is > 0, then the instruction + will be interpreted as . +
    • +
+ + + + + Called when the has decided to 'fire' + the trigger (Execute the associated ), in order to + give the a chance to update itself for its next + triggering (if any). + + + + + + Updates the instance with new calendar. + + The calendar. + The misfire threshold. + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + After this method has been called, + should return a valid answer. + + + + The first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first firing of the ). + + + + + Returns the next time at which the will + fire. If the trigger will not fire again, will be + returned. The value returned is not guaranteed to be valid until after + the has been added to the scheduler. + + + + + Returns the previous time at which the fired. + If the trigger has not yet fired, will be + returned. + + + + + Returns the next UTC time at which the will + fire, after the given UTC time. If the trigger will not fire after the given + time, will be returned. + + + + + Returns the last UTC time at which the will + fire, before the given time. If the trigger will not fire before the + given time, will be returned. + + + + + Computes the number of times fired between the two UTC date times. + + The UTC start date and time. + The UTC end date and time. + + + + + Determines whether or not the will occur + again. + + + + + Validates whether the properties of the are + valid for submission into a . + + + + + Get or set thhe number of times the should + repeat, after which it will be automatically deleted. + + + + + + Get or set the the time interval at which the should repeat. + + + + + Get or set the number of times the has already + fired. + + + + + Returns the final UTC time at which the will + fire, if repeatCount is RepeatIndefinitely, null will be returned. + + Note that the return time may be in the past. + + + + + + Tells whether this Trigger instance can handle events + in millisecond precision. + + + + + + Schedules work on a newly spawned thread. This is the default Quartz behavior. + + matt.accola + + + + Allows different strategies for scheduling threads. The + method is required to be called before the first call to + . The Thread containing the work to be performed is + passed to execute and the work is scheduled by the underlying implementation. + + matt.accola + + + + Submit a task for execution. + + Thread to execute. + + + + Initialize any state prior to calling . + + + + + A singleton implementation of . + + + Here are some examples of using this class: + + To create a scheduler that does not write anything to the database (is not + persistent), you can call : + + + DirectSchedulerFactory.Instance.CreateVolatileScheduler(10); // 10 threads + // don't forget to start the scheduler: + DirectSchedulerFactory.Instance.GetScheduler().Start(); + + + Several create methods are provided for convenience. All create methods + eventually end up calling the create method with all the parameters: + + + public void CreateScheduler(string schedulerName, string schedulerInstanceId, IThreadPool threadPool, IJobStore jobStore) + + + Here is an example of using this method: + + + // create the thread pool + SimpleThreadPool threadPool = new SimpleThreadPool(maxThreads, ThreadPriority.Normal); + threadPool.Initialize(); + // create the job store + JobStore jobStore = new RAMJobStore(); + + DirectSchedulerFactory.Instance.CreateScheduler("My Quartz Scheduler", "My Instance", threadPool, jobStore); + // don't forget to start the scheduler: + DirectSchedulerFactory.Instance.GetScheduler("My Quartz Scheduler", "My Instance").Start(); + + > + Mohammad Rezaei + James House + Marko Lahma (.NET) + + + + + + Provides a mechanism for obtaining client-usable handles to + instances. + + + + James House + Marko Lahma (.NET) + + + + Returns a client-usable handle to a . + + + + + Returns a handle to the Scheduler with the given name, if it exists. + + + + + Returns handles to all known Schedulers (made by any SchedulerFactory + within this app domain.). + + + + + Initializes a new instance of the class. + + + + + Creates an in memory job store () + The thread priority is set to Thread.NORM_PRIORITY + + The number of threads in the thread pool + + + + Creates a proxy to a remote scheduler. This scheduler can be retrieved + via . + + SchedulerException + + + + Same as , + with the addition of specifying the scheduler name and instance ID. This + scheduler can only be retrieved via . + + The name for the scheduler. + The instance ID for the scheduler. + + SchedulerException + + + + Creates a scheduler using the specified thread pool and job store. This + scheduler can be retrieved via DirectSchedulerFactory#GetScheduler() + + + The thread pool for executing jobs + + + The type of job store + + SchedulerException + if initialization failed + + + + + Same as DirectSchedulerFactory#createScheduler(ThreadPool threadPool, JobStore jobStore), + with the addition of specifying the scheduler name and instance ID. This + scheduler can only be retrieved via DirectSchedulerFactory#getScheduler(String) + + The name for the scheduler. + The instance ID for the scheduler. + The thread pool for executing jobs + The type of job store + + + + Creates a scheduler using the specified thread pool and job store and + binds it for remote access. + + The name for the scheduler. + The instance ID for the scheduler. + The thread pool for executing jobs + The type of job store + The idle wait time. You can specify "-1" for + the default value, which is currently 30000 ms. + The db failure retry interval. + + + + Creates a scheduler using the specified thread pool and job store and + binds it for remote access. + + The name for the scheduler. + The instance ID for the scheduler. + The thread pool for executing jobs + The type of job store + + The idle wait time. You can specify TimeSpan.Zero for + the default value, which is currently 30000 ms. + The db failure retry interval. + + + + Creates a scheduler using the specified thread pool and job store and + binds it for remote access. + + The name for the scheduler. + The instance ID for the scheduler. + The thread pool for executing jobs + Thread executor. + The type of job store + + The idle wait time. You can specify TimeSpan.Zero for + the default value, which is currently 30000 ms. + The db failure retry interval. + + + + Creates a scheduler using the specified thread pool and job store and + binds it for remote access. + + The name for the scheduler. + The instance ID for the scheduler. + The thread pool for executing jobs + Thread executor. + The type of job store + + The idle wait time. You can specify TimeSpan.Zero for + the default value, which is currently 30000 ms. + The db failure retry interval. + The maximum batch size of triggers, when acquiring them + The time window for which it is allowed to "pre-acquire" triggers to fire + + + + Returns a handle to the Scheduler produced by this factory. + + you must call createRemoteScheduler or createScheduler methods before + calling getScheduler() + + + + SchedulerException + + + + Returns a handle to the Scheduler with the given name, if it exists. + + + + + Gets the log. + + The log. + + + + Gets the instance. + + The instance. + + + + Returns a handle to all known Schedulers (made by any + StdSchedulerFactory instance.). + + + + + + Conveys the detail properties of a given job instance. + + + Quartz does not store an actual instance of a type, but + instead allows you to define an instance of one, through the use of a . + + s have a name and group associated with them, which + should uniquely identify them within a single . + + + s are the 'mechanism' by which s + are scheduled. Many s can point to the same , + but a single can only point to one . + + + + + + + + James House + Marko Lahma (.NET) + + + + Conveys the detail properties of a given job instance. + JobDetails are to be created/defined with . + + + Quartz does not store an actual instance of a type, but + instead allows you to define an instance of one, through the use of a . + + s have a name and group associated with them, which + should uniquely identify them within a single . + + + s are the 'mechanism' by which s + are scheduled. Many s can point to the same , + but a single can only point to one . + + + + + + + + James House + Marko Lahma (.NET) + + + + Get a that is configured to produce a + identical to this one. + + + + + The key that identifies this jobs uniquely. + + + + + Get or set the description given to the instance by its + creator (if any). + + + + + Get or sets the instance of that will be executed. + + + + + Get or set the that is associated with the . + + + + + Whether or not the should remain stored after it is + orphaned (no s point to it). + + + If not explicitly set, the default value is . + + + if the Job should remain persisted after being orphaned. + + + + + Whether the associated Job class carries the . + + + + + + Whether the associated Job class carries the . + + + + + + Set whether or not the the should re-Execute + the if a 'recovery' or 'fail-over' situation is + encountered. + + + If not explicitly set, the default value is . + + + + + + Create a with no specified name or group, and + the default settings of all the other properties. + + Note that the , and + properties must be set before the job can be + placed into a . + + + + + + Create a with the given name, default group, and + the default settings of all the other properties. + If , Scheduler.DefaultGroup will be used. + + + If name is null or empty, or the group is an empty string. + + + + + Create a with the given name, and group, and + the default settings of all the other properties. + If , Scheduler.DefaultGroup will be used. + + + If name is null or empty, or the group is an empty string. + + + + + Create a with the given name, and group, and + the given settings of all the other properties. + + The name. + if , Scheduler.DefaultGroup will be used. + Type of the job. + if set to true, job will be durable. + if set to true, job will request recovery. + + ArgumentException if name is null or empty, or the group is an empty string. + + + + + Validates whether the properties of the are + valid for submission into a . + + + + + Return a simple string representation of this object. + + + + + Creates a new object that is a copy of the current instance. + + + A new object that is a copy of this instance. + + + + + Determines whether the specified detail is equal to this instance. + + The detail to examine. + + true if the specified detail is equal; otherwise, false. + + + + + Determines whether the specified is equal to the current . + + The to compare with the current . + + if the specified is equal to the + current ; otherwise, . + + + + + Checks equality between given job detail and this instance. + + The detail to compare this instance with. + + + + + Serves as a hash function for a particular type, suitable + for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Get or sets the name of this . + + + if name is null or empty. + + + + + Get or sets the group of this . + If , will be used. + + + If the group is an empty string. + + + + + Returns the 'full name' of the in the format + "group.name". + + + + + Gets the key. + + The key. + + + + Get or set the description given to the instance by its + creator (if any). + + + May be useful for remembering/displaying the purpose of the job, though the + description has no meaning to Quartz. + + + + + Get or sets the instance of that will be executed. + + + if jobType is null or the class is not a . + + + + + Get or set the that is associated with the . + + + + + Set whether or not the the should re-Execute + the if a 'recovery' or 'fail-over' situation is + encountered. + + If not explicitly set, the default value is . + + + + + + + Whether or not the should remain stored after it is + orphaned (no s point to it). + + If not explicitly set, the default value is . + + + + if the Job should remain persisted after + being orphaned. + + + + + Whether the associated Job class carries the attribute. + + + + + Whether the associated Job class carries the attribute. + + + + + A context bundle containing handles to various environment information, that + is given to a instance as it is + executed, and to a instance after the + execution completes. + + + + The found on this object (via the + method) serves as a convenience - + it is a merge of the found on the + and the one found on the , with + the value in the latter overriding any same-named values in the former. + It is thus considered a 'best practice' that the Execute code of a Job + retrieve data from the JobDataMap found on this object + + + NOTE: Do not + expect value 'set' into this JobDataMap to somehow be set back onto a + job's own JobDataMap. + + + + s are also returned from the + + method. These are the same instances as those past into the jobs that are + currently executing within the scheduler. The exception to this is when your + application is using Quartz remotely (i.e. via remoting or WCF) - in which case you get + a clone of the s, and their references to + the and instances have been lost (a + clone of the is still available - just not a handle + to the job instance that is running). + + + + + + + + James House + Marko Lahma (.NET) + + + + A context bundle containing handles to various environment information, that + is given to a instance as it is + executed, and to a instance after the + execution completes. + + + + + Put the specified value into the context's data map with the given key. + Possibly useful for sharing data between listeners and jobs. + + NOTE: this data is volatile - it is lost after the job execution + completes, and all TriggerListeners and JobListeners have been + notified. + + + + + + + + + + Get the value with the given key from the context's data map. + + + + + + + Get a handle to the instance that fired the + . + + + + + Get a handle to the instance that fired the + . + + + + + Get a handle to the referenced by the + instance that fired the . + + + + + If the is being re-executed because of a 'recovery' + situation, this method will return . + + + + + Gets the refire count. + + The refire count. + + + + Get the convenience of this execution context. + + + + The found on this object serves as a convenience - + it is a merge of the found on the + and the one found on the , with + the value in the latter overriding any same-named values in the former. + It is thus considered a 'best practice' that the Execute code of a Job + retrieve data from the JobDataMap found on this object. + + + NOTE: Do not expect value 'set' into this JobDataMap to somehow be + set back onto a job's own JobDataMap. + + + Attempts to change the contents of this map typically result in an + illegal state. + + + + + + Get the associated with the . + + + + + Get the instance of the that was created for this + execution. + + Note: The Job instance is not available through remote scheduler + interfaces. + + + + + + The actual time the trigger fired. For instance the scheduled time may + have been 10:00:00 but the actual fire time may have been 10:00:03 if + the scheduler was too busy. + + Returns the fireTimeUtc. + + + + + The scheduled time the trigger fired for. For instance the scheduled + time may have been 10:00:00 but the actual fire time may have been + 10:00:03 if the scheduler was too busy. + + Returns the scheduledFireTimeUtc. + + + + + Gets the previous fire time. + + The previous fire time. + + + + Gets the next fire time. + + The next fire time. + + + + Get the unique Id that identifies this particular firing instance of the + trigger that triggered this job execution. It is unique to this + JobExecutionContext instance as well. + + the unique fire instance id + + + + + Returns the result (if any) that the set before its + execution completed (the type of object set as the result is entirely up + to the particular job). + + + + The result itself is meaningless to Quartz, but may be informative + to s or + s that are watching the job's + execution. + + + Set the result (if any) of the 's execution (the type of + object set as the result is entirely up to the particular job). + + + The result itself is meaningless to Quartz, but may be informative + to s or + s that are watching the job's + execution. + + + + + + The amount of time the job ran for. The returned + value will be until the job has actually completed (or thrown an + exception), and is therefore generally only useful to + s and s. + + + + + Create a JobExcecutionContext with the given context data. + + + + + Increments the refire count. + + + + + Returns a that represents the current . + + + A that represents the current . + + + + + Put the specified value into the context's data map with the given key. + Possibly useful for sharing data between listeners and jobs. + + NOTE: this data is volatile - it is lost after the job execution + completes, and all TriggerListeners and JobListeners have been + notified. + + + + + + + + + + Get the value with the given key from the context's data map. + + + + + + + Get a handle to the instance that fired the + . + + + + + Get a handle to the instance that fired the + . + + + + + Get a handle to the referenced by the + instance that fired the . + + + + + If the is being re-executed because of a 'recovery' + situation, this method will return . + + + + + Gets the refire count. + + The refire count. + + + + Get the convenience of this execution context. + + + + The found on this object serves as a convenience - + it is a merge of the found on the + and the one found on the , with + the value in the latter overriding any same-named values in the former. + It is thus considered a 'best practice' that the Execute code of a Job + retrieve data from the JobDataMap found on this object. + + + NOTE: Do not expect value 'set' into this JobDataMap to somehow be + set back onto a job's own JobDataMap. + + + Attempts to change the contents of this map typically result in an + illegal state. + + + + + + Get the associated with the . + + + + + Get the instance of the that was created for this + execution. + + Note: The Job instance is not available through remote scheduler + interfaces. + + + + + + The actual time the trigger fired. For instance the scheduled time may + have been 10:00:00 but the actual fire time may have been 10:00:03 if + the scheduler was too busy. + + Returns the fireTimeUtc. + + + + + The scheduled time the trigger fired for. For instance the scheduled + time may have been 10:00:00 but the actual fire time may have been + 10:00:03 if the scheduler was too busy. + + Returns the scheduledFireTimeUtc. + + + + + Gets the previous fire time. + + The previous fire time. + + + + Gets the next fire time. + + The next fire time. + + + + Returns the result (if any) that the set before its + execution completed (the type of object set as the result is entirely up + to the particular job). + + + + The result itself is meaningless to Quartz, but may be informative + to s or + s that are watching the job's + execution. + + + Set the result (if any) of the 's execution (the type of + object set as the result is entirely up to the particular job). + + + The result itself is meaningless to Quartz, but may be informative + to s or + s that are watching the job's + execution. + + + + + + The amount of time the job ran for. The returned + value will be until the job has actually completed (or thrown an + exception), and is therefore generally only useful to + s and s. + + + + + Returns the fire instace id. + + + + + An implementation of the interface that remotely + proxies all method calls to the equivalent call on a given + instance, via remoting or similar technology. + + + + James House + Marko Lahma (.NET) + + + + This is the main interface of a Quartz Scheduler. + + + + A maintains a registry of + s and s. Once + registered, the is responsible for executing + s when their associated s + fire (when their scheduled time arrives). + + + instances are produced by a + . A scheduler that has already been + created/initialized can be found and used through the same factory that + produced it. After a has been created, it is in + "stand-by" mode, and must have its method + called before it will fire any s. + + + s are to be created by the 'client program', by + defining a class that implements the interface. + objects are then created (also by the client) to + define a individual instances of the . + instances can then be registered with the + via the %IScheduler.ScheduleJob(JobDetail, + Trigger)% or %IScheduler.AddJob(JobDetail, bool)% method. + + + s can then be defined to fire individual + instances based on given schedules. + s are most useful for one-time firings, or + firing at an exact moment in time, with N repeats with a given delay between + them. s allow scheduling based on time of day, + day of week, day of month, and month of year. + + + s and s have a name and + group associated with them, which should uniquely identify them within a single + . The 'group' feature may be useful for creating + logical groupings or categorizations of s and + s. If you don't have need for assigning a group to a + given s of s, then you can use + the constant defined on + this interface. + + + Stored s can also be 'manually' triggered through the + use of the %IScheduler.TriggerJob(string, string)% function. + + + Client programs may also be interested in the 'listener' interfaces that are + available from Quartz. The interface provides + notifications of executions. The + interface provides notifications of + firings. The + interface provides notifications of events and + errors. Listeners can be associated with local schedulers through the + interface. + + + The setup/configuration of a instance is very + customizable. Please consult the documentation distributed with Quartz. + + + + + + + + + Marko Lahma (.NET) + + + + returns true if the given JobGroup + is paused + + + + + + + returns true if the given TriggerGroup + is paused + + + + + + + Get a object describing the settings + and capabilities of the scheduler instance. + + + Note that the data returned is an 'instantaneous' snap-shot, and that as + soon as it's returned, the meta data values may be different. + + + + + Return a list of objects that + represent all currently executing Jobs in this Scheduler instance. + + + + This method is not cluster aware. That is, it will only return Jobs + currently executing in this Scheduler instance, not across the entire + cluster. + + + Note that the list returned is an 'instantaneous' snap-shot, and that as + soon as it's returned, the true list of executing jobs may be different. + Also please read the doc associated with - + especially if you're using remoting. + + + + + + + Get the names of all known groups. + + + + + Get the names of all known groups. + + + + + Get the names of all groups that are paused. + + + + + Starts the 's threads that fire s. + When a scheduler is first created it is in "stand-by" mode, and will not + fire triggers. The scheduler can also be put into stand-by mode by + calling the method. + + + The misfire/recovery process will be started, if it is the initial call + to this method on this scheduler instance. + + + + + + + + Calls after the indicated delay. + (This call does not block). This can be useful within applications that + have initializers that create the scheduler immediately, before the + resources needed by the executing jobs have been fully initialized. + + + + + + + + Temporarily halts the 's firing of s. + + + + When is called (to bring the scheduler out of + stand-by mode), trigger misfire instructions will NOT be applied + during the execution of the method - any misfires + will be detected immediately afterward (by the 's + normal process). + + + The scheduler is not destroyed, and can be re-started at any time. + + + + + + + + Halts the 's firing of s, + and cleans up all resources associated with the Scheduler. Equivalent to + . + + + The scheduler cannot be re-started. + + + + + + Halts the 's firing of s, + and cleans up all resources associated with the Scheduler. + + + The scheduler cannot be re-started. + + + if the scheduler will not allow this method + to return until all currently executing jobs have completed. + + + + + + Add the given to the + Scheduler, and associate the given with + it. + + + If the given Trigger does not reference any , then it + will be set to reference the Job passed with it into this method. + + + + + Schedule the given with the + identified by the 's settings. + + + + + Schedule all of the given jobs with the related set of triggers. + + + If any of the given jobs or triggers already exist (or more + specifically, if the keys are not unique) and the replace + parameter is not set to true then an exception will be thrown. + + + + + Remove the indicated from the scheduler. + If the related job does not have any other triggers, and the job is + not durable, then the job will also be deleted. + + + + + Remove all of the indicated s from the scheduler. + + + If the related job does not have any other triggers, and the job is + not durable, then the job will also be deleted. + Note that while this bulk operation is likely more efficient than + invoking several + times, it may have the adverse affect of holding data locks for a + single long duration of time (rather than lots of small durations + of time). + + + + + Remove (delete) the with the + given key, and store the new given one - which must be associated + with the same job (the new trigger must have the job name & group specified) + - however, the new trigger need not have the same name as the old trigger. + + The to be replaced. + + The new to be stored. + + + if a with the given + name and group was not found and removed from the store (and the + new trigger is therefore not stored), otherwise + the first fire time of the newly scheduled trigger. + + + + + Add the given to the Scheduler - with no associated + . The will be 'dormant' until + it is scheduled with a , or + is called for it. + + + The must by definition be 'durable', if it is not, + SchedulerException will be thrown. + + + + + Delete the identified from the Scheduler - and any + associated s. + + true if the Job was found and deleted. + + + + Delete the identified jobs from the Scheduler - and any + associated s. + + + Note that while this bulk operation is likely more efficient than + invoking several + times, it may have the adverse affect of holding data locks for a + single long duration of time (rather than lots of small durations + of time). + + + true if all of the Jobs were found and deleted, false if + one or more were not deleted. + + + + + Trigger the identified + (Execute it now). + + + + + Trigger the identified (Execute it now). + + + the (possibly ) JobDataMap to be + associated with the trigger that fires the job immediately. + + + The of the to be executed. + + + + + Pause the with the given + key - by pausing all of its current s. + + + + + Pause all of the s in the + matching groups - by pausing all of their s. + + + + The Scheduler will "remember" that the groups are paused, and impose the + pause on any new jobs that are added to any of those groups until it is resumed. + + NOTE: There is a limitation that only exactly matched groups + can be remembered as paused. For example, if there are pre-existing + job in groups "aaa" and "bbb" and a matcher is given to pause + groups that start with "a" then the group "aaa" will be remembered + as paused and any subsequently added jobs in group "aaa" will be paused, + however if a job is added to group "axx" it will not be paused, + as "axx" wasn't known at the time the "group starts with a" matcher + was applied. HOWEVER, if there are pre-existing groups "aaa" and + "bbb" and a matcher is given to pause the group "axx" (with a + group equals matcher) then no jobs will be paused, but it will be + remembered that group "axx" is paused and later when a job is added + in that group, it will become paused. + + + + + + Pause the with the given key. + + + + + Pause all of the s in the groups matching. + + + + The Scheduler will "remember" all the groups paused, and impose the + pause on any new triggers that are added to any of those groups until it is resumed. + + NOTE: There is a limitation that only exactly matched groups + can be remembered as paused. For example, if there are pre-existing + triggers in groups "aaa" and "bbb" and a matcher is given to pause + groups that start with "a" then the group "aaa" will be remembered as + paused and any subsequently added triggers in that group be paused, + however if a trigger is added to group "axx" it will not be paused, + as "axx" wasn't known at the time the "group starts with a" matcher + was applied. HOWEVER, if there are pre-existing groups "aaa" and + "bbb" and a matcher is given to pause the group "axx" (with a + group equals matcher) then no triggers will be paused, but it will be + remembered that group "axx" is paused and later when a trigger is added + in that group, it will become paused. + + + + + + Resume (un-pause) the with + the given key. + + + If any of the 's s missed one + or more fire-times, then the 's misfire + instruction will be applied. + + + + + Resume (un-pause) all of the s + in matching groups. + + + If any of the s had s that + missed one or more fire-times, then the 's + misfire instruction will be applied. + + + + + + Resume (un-pause) the with the given + key. + + + If the missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + Resume (un-pause) all of the s in matching groups. + + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Pause all triggers - similar to calling + on every group, however, after using this method + must be called to clear the scheduler's state of 'remembering' that all + new triggers will be paused as they are added. + + + When is called (to un-pause), trigger misfire + instructions WILL be applied. + + + + + + + + Resume (un-pause) all triggers - similar to calling + on every group. + + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Get the keys of all the s in the matching groups. + + + + + Get all s that are associated with the + identified . + + + The returned Trigger objects will be snap-shots of the actual stored + triggers. If you wish to modify a trigger, you must re-store the + trigger afterward (e.g. see ). + + + + + Get the names of all the s in the given + groups. + + + + + Get the for the + instance with the given key . + + + The returned JobDetail object will be a snap-shot of the actual stored + JobDetail. If you wish to modify the JobDetail, you must re-store the + JobDetail afterward (e.g. see ). + + + + + Get the instance with the given key. + + + The returned Trigger object will be a snap-shot of the actual stored + trigger. If you wish to modify the trigger, you must re-store the + trigger afterward (e.g. see ). + + + + + Get the current state of the identified . + + + + + + + + + + + Add (register) the given to the Scheduler. + + Name of the calendar. + The calendar. + if set to true [replace]. + whether or not to update existing triggers that + referenced the already existing calendar so that they are 'correct' + based on the new trigger. + + + + Delete the identified from the Scheduler. + + + If removal of the Calendar would result in + s pointing to non-existent calendars, then a + will be thrown. + + Name of the calendar. + true if the Calendar was found and deleted. + + + + Get the instance with the given name. + + + + + Get the names of all registered . + + + + + Request the interruption, within this Scheduler instance, of all + currently executing instances of the identified , which + must be an implementor of the interface. + + + + If more than one instance of the identified job is currently executing, + the method will be called on + each instance. However, there is a limitation that in the case that + on one instances throws an exception, all + remaining instances (that have not yet been interrupted) will not have + their method called. + + + + If you wish to interrupt a specific instance of a job (when more than + one is executing) you can do so by calling + to obtain a handle + to the job instance, and then invoke on it + yourself. + + + This method is not cluster aware. That is, it will only interrupt + instances of the identified InterruptableJob currently executing in this + Scheduler instance, not across the entire cluster. + + + + true is at least one instance of the identified job was found and interrupted. + + + + + + + Request the interruption, within this Scheduler instance, of the + identified executing job instance, which + must be an implementor of the interface. + + + This method is not cluster aware. That is, it will only interrupt + instances of the identified InterruptableJob currently executing in this + Scheduler instance, not across the entire cluster. + + + + + + + the unique identifier of the job instance to be interrupted (see + + + true if the identified job instance was found and interrupted. + + + + Determine whether a with the given identifier already + exists within the scheduler. + + the identifier to check for + true if a Job exists with the given identifier + + + + Determine whether a with the given identifier already + exists within the scheduler. + + the identifier to check for + true if a Trigger exists with the given identifier + + + + Clears (deletes!) all scheduling data - all s, s + s. + + + + + Returns the name of the . + + + + + Returns the instance Id of the . + + + + + Returns the of the . + + + + + Reports whether the is in stand-by mode. + + + + + + + Reports whether the has been Shutdown. + + + + + Set the that will be responsible for producing + instances of classes. + + + JobFactories may be of use to those wishing to have their application + produce instances via some special mechanism, such as to + give the opportunity for dependency injection. + + + + + + Get a reference to the scheduler's , + through which listeners may be registered. + + the scheduler's + + + + + + + + Whether the scheduler has been started. + + + Note: This only reflects whether has ever + been called on this Scheduler, so it will return even + if the is currently in standby mode or has been + since shutdown. + + + + + + + + Construct a instance to proxy the given + RemoteableQuartzScheduler instance. + + + + + returns true if the given JobGroup + is paused + + + + + + + returns true if the given TriggerGroup + is paused + + + + + + + Get a object describiing the settings + and capabilities of the scheduler instance. + + Note that the data returned is an 'instantaneous' snap-shot, and that as + soon as it's returned, the meta data values may be different. + + + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Get the names of all groups that are paused. + + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Get the names of all registered . + + + + + + Calls the equivalent method on the 'proxied' . + + + + + Returns the name of the . + + + + + Returns the instance Id of the . + + + + + Returns the of the . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Set the that will be responsible for producing + instances of classes. + + JobFactories may be of use to those wishing to have their application + produce instances via some special mechanism, such as to + give the opertunity for dependency injection. + + + + + SchedulerException + + + + Whether the scheduler has been started. + + + + Note: This only reflects whether has ever + been called on this Scheduler, so it will return even + if the is currently in standby mode or has been + since shutdown. + + + + + + + + This utility calls methods reflectively on the given objects even though the + methods are likely on a proper interface (ThreadPool, JobStore, etc). The + motivation is to be tolerant of older implementations that have not been + updated for the changes in the interfaces (eg. LocalTaskExecutorThreadPool in + spring quartz helpers) + + teck + Marko Lahma (.NET) + + + + Holds references to Scheduler instances - ensuring uniqueness, and + preventing garbage collection, and allowing 'global' lookups. + + James House + Marko Lahma (.NET) + + + + Binds the specified sched. + + The sched. + + + + Removes the specified sched name. + + Name of the sched. + + + + + Lookups the specified sched name. + + Name of the sched. + + + + + Lookups all. + + + + + + Gets the singleton instance. + + The instance. + + + + Responsible for creating the instances of + to be used within the instance. + + James House + Marko Lahma (.NET) + + + + Initialize the factory, providing a handle to the + that should be made available within the and + the s within it. + + + + + Called by the to obtain instances of + . + + + + + An implementation of the interface that directly + proxies all method calls to the equivalent call on a given + instance. + + + + James House + Marko Lahma (.NET) + + + + returns true if the given JobGroup + is paused + + + + + + + returns true if the given TriggerGroup + is paused + + + + + + + Get a object describiing the settings + and capabilities of the scheduler instance. + + Note that the data returned is an 'instantaneous' snap-shot, and that as + soon as it's returned, the meta data values may be different. + + + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Construct a instance to proxy the given + instance. + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Get the names of all registered . + + + + + + Request the interruption, within this Scheduler instance, of all + currently executing instances of the identified , which + must be an implementor of the interface. + + + + If more than one instance of the identified job is currently executing, + the method will be called on + each instance. However, there is a limitation that in the case that + on one instances throws an exception, all + remaining instances (that have not yet been interrupted) will not have + their method called. + + + If you wish to interrupt a specific instance of a job (when more than + one is executing) you can do so by calling + to obtain a handle + to the job instance, and then invoke on it + yourself. + + + This method is not cluster aware. That is, it will only interrupt + instances of the identified InterruptableJob currently executing in this + Scheduler instance, not across the entire cluster. + + + true is at least one instance of the identified job was found and interrupted. + UnableToInterruptJobException if the job does not implement + + + + + + Returns the name of the . + + + + + Returns the instance Id of the . + + + + + Returns the of the . + + + + + Whether the scheduler has been started. + + + + Note: This only reflects whether has ever + been called on this Scheduler, so it will return even + if the is currently in standby mode or has been + since shutdown. + + + + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + Calls the equivalent method on the 'proxied' . + + + + + + + + + An implementation of that + does all of it's work of creating a instance + based on the contents of a properties file. + + + + By default a properties are loaded from App.config's quartz section. + If that fails, then the file is loaded "quartz.properties". If file does not exist, + default configration located (as a embedded resource) in Quartz.dll is loaded. If you + wish to use a file other than these defaults, you must define the system + property 'quartz.properties' to point to the file you want. + + + See the sample properties that are distributed with Quartz for + information about the various settings available within the file. + + + Alternativly, you can explicitly Initialize the factory by calling one of + the methods before calling . + + + Instances of the specified , + , classes will be created + by name, and then any additional properties specified for them in the config + file will be set on the instance by calling an equivalent 'set' method. For + example if the properties file contains the property 'quartz.jobStore. + myProp = 10' then after the JobStore class has been instantiated, the property + 'MyProp' will be set with the value. Type conversion to primitive CLR types + (int, long, float, double, boolean, enum and string) are performed before calling + the property's setter method. + + + James House + Anthony Eden + Mohammad Rezaei + Marko Lahma (.NET) + + + + Returns a handle to the default Scheduler, creating it if it does not + yet exist. + + + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The props. + + + + Initialize the . + + + By default a properties file named "quartz.properties" is loaded from + the 'current working directory'. If that fails, then the + "quartz.properties" file located (as an embedded resource) in the Quartz.NET + assembly is loaded. If you wish to use a file other than these defaults, + you must define the system property 'quartz.properties' to point to + the file you want. + + + + + Creates a new name value collection and overrides its values + with system values (environment variables). + + The base properties to override. + A new NameValueCollection instance. + + + + Initialize the with + the contents of the given key value collection object. + + + + + + + + Needed while loadhelper is not constructed. + + + + + + + Returns a handle to the Scheduler produced by this factory. + + + If one of the methods has not be previously + called, then the default (no-arg) method + will be called by this method. + + + + + Returns a handle to the Scheduler with the given name, if it exists (if + it has already been instantiated). + + + + + + Returns a handle to all known Schedulers (made by any + StdSchedulerFactory instance.). + + + + + + Inspects a directory and compares whether any files' "last modified dates" + have changed since the last time it was inspected. If one or more files + have been updated (or created), the job invokes a "call-back" method on an + identified that can be found in the + . + + pl47ypus + James House + Marko Lahma (.NET) + + + + + The interface to be implemented by classes which represent a 'job' to be + performed. + + + Instances of this interface must have a + no-argument constructor. provides a mechanism for 'instance member data' + that may be required by some implementations of this interface. + + + + + + + + James House + Marko Lahma (.NET) + + + + Called by the when a + fires that is associated with the . + + + The implementation may wish to set a result object on the + JobExecutionContext before this method exits. The result itself + is meaningless to Quartz, but may be informative to + s or + s that are watching the job's + execution. + + The execution context. + + + key with which to specify the directory to be + monitored - an absolute path is recommended. + + + key with which to specify the + to be + notified when the directory contents change. + + + key with which to specify a + value that represents the minimum number of milliseconds that must have + passed since the file's last modified time in order to consider the file + new/altered. This is necessary because another process may still be + in the middle of writing to the file when the scan occurs, and the + file may therefore not yet be ready for processing. + If this parameter is not specified, a default value of 5000 (five seconds) will be used. + + + + This is the main entry point for job execution. The scheduler will call this method on the + job once it is triggered. + + The that + the job will use during execution. + + + + Inspects a file and compares whether it's "last modified date" has changed + since the last time it was inspected. If the file has been updated, the + job invokes a "call-back" method on an identified + that can be found in the + . + + James House + Marko Lahma (.NET) + + + + + JobDataMap key with which to specify the name of the file to monitor. + + + + + JobDataMap key with which to specify the + to be notified when the file contents change. + + + + + key with which to specify a long + value that represents the minimum number of milliseconds that must have + past since the file's last modified time in order to consider the file + new/altered. This is necessary because another process may still be + in the middle of writing to the file when the scan occurs, and the + file may therefore not yet be ready for processing. + + If this parameter is not specified, a default value of + 5000 (five seconds) will be used. + + + + + Initializes a new instance of the class. + + + + + Called by the when a + fires that is associated with the . + + The implementation may wish to set a result object on the + JobExecutionContext before this method exits. The result itself + is meaningless to Quartz, but may be informative to + s or + s that are watching the job's + execution. + + + The execution context. + + + + + + Gets the last modified date. + + Name of the file. + + + + + Gets the log. + + The log. + + + Interface for objects wishing to receive a 'call-back' from a + Instances should be stored in the such that the + can find it. + James House + Marko Lahma (.NET) + + + An array of objects that were updated/added + since the last scan of the directory + + + + Interface for objects wishing to receive a 'call-back' from a + . + + James House + Marko Lahma (.NET) + + + + + Ãnforms that certain file has been updated. + + Name of the file. + + + + Built in job for executing native executables in a separate process. + + + + JobDetail job = new JobDetail("dumbJob", null, typeof(Quartz.Jobs.NativeJob)); + job.JobDataMap.Put(Quartz.Jobs.NativeJob.PropertyCommand, "echo \"hi\" >> foobar.txt"); + Trigger trigger = TriggerUtils.MakeSecondlyTrigger(5); + trigger.Name = "dumbTrigger"; + sched.ScheduleJob(job, trigger); + + If PropertyWaitForProcess is true, then the integer exit value of the process + will be saved as the job execution result in the JobExecutionContext. + + Matthew Payne + James House + Steinar Overbeck Cook + Marko Lahma (.NET) + + + + Required parameter that specifies the name of the command (executable) + to be ran. + + + + + Optional parameter that specifies the parameters to be passed to the + executed command. + + + + + Optional parameter (value should be 'true' or 'false') that specifies + whether the job should wait for the execution of the native process to + complete before it completes. + + Defaults to . + + + + + Optional parameter (value should be 'true' or 'false') that specifies + whether the spawned process's stdout and stderr streams should be + consumed. If the process creates output, it is possible that it might + 'hang' if the streams are not consumed. + + Defaults to . + + + + + Optional parameter that specifies the workling directory to be used by + the executed command. + + + + + Initializes a new instance of the class. + + + + + Called by the when a + fires that is associated with the . + + The implementation may wish to set a result object on the + JobExecutionContext before this method exits. The result itself + is meaningless to Quartz, but may be informative to + s or + s that are watching the job's + execution. + + + + + + + Gets the log. + + The log. + + + + Consumes data from the given input stream until EOF and prints the data to stdout + + cooste + James House + + + + Initializes a new instance of the class. + + The enclosing instance. + The input stream. + The type. + + + + Runs this object as a separate thread, printing the contents of the input stream + supplied during instantiation, to either Console. or stderr + + + + + An implementation of Job, that does absolutely nothing - useful for system + which only wish to use s + and s, rather than writing + Jobs that perform work. + + James House + Marko Lahma (.NET) + + + + Do nothing. + + + + + A Job which sends an e-mail with the configured content to the configured + recipient. + + James House + Marko Lahma (.NET) + + + The host name of the smtp server. REQUIRED. + + + The e-mail address to send the mail to. REQUIRED. + + + The e-mail address to cc the mail to. Optional. + + + The e-mail address to claim the mail is from. REQUIRED. + + + The e-mail address the message should say to reply to. Optional. + + + The subject to place on the e-mail. REQUIRED. + + + The e-mail message body. REQUIRED. + + + + Executes the job. + + The job execution context. + + + + Holds a List of references to JobListener instances and broadcasts all + events to them (in order). + + + The broadcasting behavior of this listener to delegate listeners may be + more convenient than registering all of the listeners directly with the + Scheduler, and provides the flexibility of easily changing which listeners + get notified. + + + + + James House (jhouse AT revolition DOT net) + + + + Construct an instance with the given name. + + + (Remember to add some delegate listeners!) + + the name of this instance + + + + Construct an instance with the given name, and List of listeners. + + + + the name of this instance + the initial List of JobListeners to broadcast to. + + + + Holds a List of references to SchedulerListener instances and broadcasts all + events to them (in order). + + + This may be more convenient than registering all of the listeners + directly with the Scheduler, and provides the flexibility of easily changing + which listeners get notified. + + + + James House + Marko Lahma (.NET) + + + + Construct an instance with the given List of listeners. + + The initial List of SchedulerListeners to broadcast to. + + + + Holds a List of references to TriggerListener instances and broadcasts all + events to them (in order). + + + The broadcasting behavior of this listener to delegate listeners may be + more convenient than registering all of the listeners directly with the + Scheduler, and provides the flexibility of easily changing which listeners + get notified. + + + + + James House (jhouse AT revolition DOT net) + + + + The interface to be implemented by classes that want to be informed when a + fires. In general, applications that use a + will not have use for this mechanism. + + + + + + + James House + Marko Lahma (.NET) + + + + Called by the when a + has fired, and it's associated + is about to be executed. + + It is called before the method of this + interface. + + + The that has fired. + + The that will be passed to the 's method. + + + + + Called by the when a + has fired, and it's associated + is about to be executed. + + It is called after the method of this + interface. If the implementation vetos the execution (via + returning ), the job's execute method will not be called. + + + The that has fired. + The that will be passed to + the 's method. + Returns true if job execution should be vetoed, false otherwise. + + + + Called by the when a + has misfired. + + Consideration should be given to how much time is spent in this method, + as it will affect all triggers that are misfiring. If you have lots + of triggers misfiring at once, it could be an issue it this method + does a lot. + + + The that has misfired. + + + + Called by the when a + has fired, it's associated + has been executed, and it's method has been + called. + + The that was fired. + + The that was passed to the + 's method. + + + The result of the call on the 's method. + + + + + Get the name of the . + + + + + Construct an instance with the given name. + + + (Remember to add some delegate listeners!) + + the name of this instance + + + + Construct an instance with the given name, and List of listeners. + + + + the name of this instance + the initial List of TriggerListeners to broadcast to. + + + + Keeps a collection of mappings of which Job to trigger after the completion + of a given job. If this listener is notified of a job completing that has a + mapping, then it will then attempt to trigger the follow-up job. This + achieves "job chaining", or a "poor man's workflow". + + + + Generally an instance of this listener would be registered as a global + job listener, rather than being registered directly to a given job. + + + If for some reason there is a failure creating the trigger for the + follow-up job (which would generally only be caused by a rare serious + failure in the system, or the non-existence of the follow-up job), an error + messsage is logged, but no other action is taken. If you need more rigorous + handling of the error, consider scheduling the triggering of the flow-up + job within your job itself. + + + James House + Marko Lahma (.NET) + + + + A helpful abstract base class for implementors of . + + + + The methods in this class are empty so you only need to override the + subset for the events you care about. + + + + You are required to implement + to return the unique name of your . + + + Marko Lahma (.NET) + + + + + Initializes a new instance of the class. + + + + + Called by the when a + is about to be executed (an associated + has occured). + + This method will not be invoked if the execution of the Job was vetoed + by a . + + + + + + + + Called by the when a + was about to be executed (an associated + has occured), but a vetoed it's + execution. + + + + + + + Called by the after a + has been executed, and be for the associated 's + method has been called. + + + + + + + Get the for this class's category. + This should be used by subclasses for logging. + + + + + Get the name of the . + + + + + + Construct an instance with the given name. + + The name of this instance. + + + + Add a chain mapping - when the Job identified by the first key completes + the job identified by the second key will be triggered. + + a JobKey with the name and group of the first job + a JobKey with the name and group of the follow-up job + + + + A helpful abstract base class for implementors of + . + + + + The methods in this class are empty so you only need to override the + subset for the events + you care about. + + + + You are required to implement + to return the unique name of your . + + + Marko Lahma (.NET) + + + + + Get the for this + class's category. This should be used by subclasses for logging. + + + + + Get the name of the . + + + + + + Logs a history of all job executions (and execution vetos) via common + logging. + + + + The logged message is customizable by setting one of the following message + properties to a string that conforms to the syntax of . + + + JobToBeFiredMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Job's Name.
1StringThe Job's Group.
2DateThe current time.
3StringThe Trigger's name.
4StringThe Triggers's group.
5DateThe scheduled fire time.
6DateThe next scheduled fire time.
7IntegerThe re-fire count from the JobExecutionContext.
+ The default message text is "Job {1}.{0} fired (by trigger {4}.{3}) at: + {2, date, HH:mm:ss MM/dd/yyyy" + + + JobSuccessMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Job's Name.
1StringThe Job's Group.
2DateThe current time.
3StringThe Trigger's name.
4StringThe Triggers's group.
5DateThe scheduled fire time.
6DateThe next scheduled fire time.
7IntegerThe re-fire count from the JobExecutionContext.
8ObjectThe string value (toString() having been called) of the result (if any) + that the Job set on the JobExecutionContext, with on it. "NULL" if no + result was set.
+ The default message text is "Job {1}.{0} execution complete at {2, date, + HH:mm:ss MM/dd/yyyy} and reports: {8" + + + JobFailedMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Job's Name.
1StringThe Job's Group.
2DateThe current time.
3StringThe Trigger's name.
4StringThe Triggers's group.
5DateThe scheduled fire time.
6DateThe next scheduled fire time.
7IntegerThe re-fire count from the JobExecutionContext.
8StringThe message from the thrown JobExecution Exception. +
+ The default message text is "Job {1}.{0} execution failed at {2, date, + HH:mm:ss MM/dd/yyyy} and reports: {8" + + + JobWasVetoedMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Job's Name.
1StringThe Job's Group.
2DateThe current time.
3StringThe Trigger's name.
4StringThe Triggers's group.
5DateThe scheduled fire time.
6DateThe next scheduled fire time.
7IntegerThe re-fire count from the JobExecutionContext.
+ The default message text is "Job {1}.{0} was vetoed. It was to be fired + (by trigger {4}.{3}) at: {2, date, HH:mm:ss MM/dd/yyyy" + + + Marko Lahma (.NET) + + + + Provides an interface for a class to become a "plugin" to Quartz. + + + Plugins can do virtually anything you wish, though the most interesting ones + will obviously interact with the scheduler in some way - either actively: by + invoking actions on the scheduler, or passively: by being a , + , and/or . + + If you use to + Initialize your Scheduler, it can also create and Initialize your plugins - + look at the configuration docs for details. + + + If you need direct access your plugin, you can have it explicitly put a + reference to itself in the 's + as part of its + method. + + + James House + Marko Lahma (.NET) + + + + Called during creation of the in order to give + the a chance to Initialize. + + + At this point, the Scheduler's is not yet + + If you need direct access your plugin, you can have it explicitly put a + reference to itself in the 's + as part of its + method. + + + + The name by which the plugin is identified. + + + The scheduler to which the plugin is registered. + + + + + Called when the associated is started, in order + to let the plug-in know it can now make calls into the scheduler if it + needs to. + + + + + Called in order to inform the that it + should free up all of it's resources because the scheduler is shutting + down. + + + + + Called during creation of the in order to give + the a chance to Initialize. + + + + + Called when the associated is started, in order + to let the plug-in know it can now make calls into the scheduler if it + needs to. + + + + + Called in order to inform the that it + should free up all of it's resources because the scheduler is shutting + down. + + + + + Called by the when a is + about to be executed (an associated has occurred). + + This method will not be invoked if the execution of the Job was vetoed by a + . + + + + + + + Called by the after a + has been executed, and be for the associated 's + method has been called. + + + + + + + Called by the when a + was about to be executed (an associated + has occured), but a vetoed it's + execution. + + + + + + + Logger instance to use. Defaults to common logging. + + + + + Get or sets the message that is logged when a Job successfully completes its + execution. + + + + + Get or sets the message that is logged when a Job fails its + execution. + + + + + Gets or sets the message that is logged when a Job is about to Execute. + + + + + Gets or sets the message that is logged when a Job execution is vetoed by a + trigger listener. + + + + + Get the name of the . + + + + + + Logs a history of all trigger firings via the Jakarta Commons-Logging + framework. + + + + The logged message is customizable by setting one of the following message + properties to a string that conforms to the syntax of . + + + + TriggerFiredMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Trigger's Name.
1StringThe Trigger's Group.
2DateThe scheduled fire time.
3DateThe next scheduled fire time.
4DateThe actual fire time.
5StringThe Job's name.
6StringThe Job's group.
7IntegerThe re-fire count from the JobExecutionContext.
+ + The default message text is "Trigger {1}.{0} fired job {6}.{5} at: {4, + date, HH:mm:ss MM/dd/yyyy" + + + + TriggerMisfiredMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Trigger's Name.
1StringThe Trigger's Group.
2DateThe scheduled fire time.
3DateThe next scheduled fire time.
4DateThe actual fire time. (the time the misfire was detected/handled)
5StringThe Job's name.
6StringThe Job's group.
+ + The default message text is "Trigger {1}.{0} misfired job {6}.{5} at: + {4, date, HH:mm:ss MM/dd/yyyy}. Should have fired at: {3, date, HH:mm:ss + MM/dd/yyyy" + + + + TriggerCompleteMessage - available message data are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementData TypeDescription
0StringThe Trigger's Name.
1StringThe Trigger's Group.
2DateThe scheduled fire time.
3DateThe next scheduled fire time.
4DateThe job completion time.
5StringThe Job's name.
6StringThe Job's group.
7IntegerThe re-fire count from the JobExecutionContext.
8IntegerThe trigger's resulting instruction code.
9StringA human-readable translation of the trigger's resulting instruction + code.
+ + The default message text is "Trigger {1}.{0} completed firing job + {6}.{5} at {4, date, HH:mm:ss MM/dd/yyyy} with resulting trigger instruction + code: {9" + + + James House + Marko Lahma (.NET) + + + + Called during creation of the in order to give + the a chance to Initialize. + + + + + Called when the associated is started, in order + to let the plug-in know it can now make calls into the scheduler if it + needs to. + + + + + Called in order to inform the that it + should free up all of it's resources because the scheduler is shutting + down. + + + + + Called by the when a + has fired, and it's associated + is about to be executed. + + It is called before the method of this + interface. + + + The that has fired. + The that will be passed to the 's method. + + + + Called by the when a + has misfired. + + Consideration should be given to how much time is spent in this method, + as it will affect all triggers that are misfiring. If you have lots + of triggers misfiring at once, it could be an issue it this method + does a lot. + + + The that has misfired. + + + + Called by the when a + has fired, it's associated + has been executed, and it's method has been + called. + + The that was fired. + The that was passed to the + 's method. + The result of the call on the 's method. + + + + Called by the when a + has fired, and it's associated + is about to be executed. + + It is called after the method of this + interface. + + + The that has fired. + The that will be passed to + the 's method. + + + + + Logger instance to use. Defaults to common logging. + + + + + Get or set the message that is printed upon the completion of a trigger's + firing. + + + + + Get or set the message that is printed upon a trigger's firing. + + + + + Get or set the message that is printed upon a trigger's mis-firing. + + + + + Get the name of the . + + + + + + This plugin catches the event of the VM terminating (such as upon a CRTL-C) + and tells the scheuler to Shutdown. + + + James House + Marko Lahma (.NET) + + + + Called during creation of the in order to give + the a chance to Initialize. + + + + + Called when the associated is started, in order + to let the plug-in know it can now make calls into the scheduler if it + needs to. + + + + + Called in order to inform the that it + should free up all of it's resources because the scheduler is shutting + down. + + + + + Determine whether or not the plug-in is configured to cause a clean + Shutdown of the scheduler. + + The default value is . + + + + + + + This plugin loads XML file(s) to add jobs and schedule them with triggers + as the scheduler is initialized, and can optionally periodically scan the + file for changes. + + + The periodically scanning of files for changes is not currently supported in a + clustered environment. + + James House + Pierre Awaragi + + + + Initializes a new instance of the class. + + + + + + + + + + + Called during creation of the in order to give + the a chance to initialize. + + The name. + The scheduler. + SchedulerConfigException + + + + Called when the associated is started, in order + to let the plug-in know it can now make calls into the scheduler if it + needs to. + + + + + Helper method for generating unique job/trigger name for the + file scanning jobs (one per FileJob). The unique names are saved + in jobTriggerNameSet. + + + + + + + Called in order to inform the that it + should free up all of it's resources because the scheduler is shutting + down. + + + + + Gets the log. + + The log. + + + + Comma separated list of file names (with paths) to the XML files that should be read. + + + + + The interval at which to scan for changes to the file. + If the file has been changed, it is re-loaded and parsed. The default + value for the interval is 0, which disables scanning. + + + + + Whether or not initialization of the plugin should fail (throw an + exception) if the file cannot be found. Default is . + + + + + Information about a file that should be processed by . + + + + + Default object serialization strategy that uses + under the hood. + + Marko Lahma + + + + Interface for object serializers. + + Marko Lahma + + + + + Serializes given object as bytes + that can be stored to permanent stores. + + Object to serialize, always non-null. + + + + Deserializes object from byte array presentation. + + Data to deserialize object from, always non-null and non-empty. + + + + Serializes given object as bytes + that can be stored to permanent stores. + + Object to serialize. + + + + Deserializes object from byte array presentation. + + Data to deserialize object from. + + + + that names the scheduler instance using + just the machine hostname. + + + This class is useful when you know that your scheduler instance will be the + only one running on a particular machine. Each time the scheduler is + restarted, it will get the same instance id as long as the machine is not + renamed. + + Marko Lahma (.NET) + + + + + + An IInstanceIdGenerator is responsible for generating the clusterwide unique + instance id for a node. + + + This interface may be of use to those wishing to have specific control over + the mechanism by which the instances in their + application are named. + + + Marko Lahma (.NET) + + + + Generate the instance id for a + + The clusterwide unique instance id. + + + + + Generate the instance id for a + + The clusterwide unique instance id. + + + + A JobFactory that instantiates the Job instance (using the default no-arg + constructor, or more specifically: ), and + then attempts to set all values from the and + the 's merged onto + properties of the job. + + + Set the WarnIfPropertyNotFound property to true if you'd like noisy logging in + the case of values in the not mapping to properties on your job + class. This may be useful for troubleshooting typos of property names, etc. + but very noisy if you regularly (and purposely) have extra things in your + . + Also of possible interest is the ThrowIfPropertyNotFound property which + will throw exceptions on unmatched JobDataMap keys. + + + + + + + + James Houser + Marko Lahma (.NET) + + + + The default JobFactory used by Quartz - simply calls + on the job class. + + + + James House + Marko Lahma (.NET) + + + + A JobFactory is responsible for producing instances of + classes. + + + This interface may be of use to those wishing to have their application + produce instances via some special mechanism, such as to + give the opertunity for dependency injection. + + + + + James House + Marko Lahma (.NET) + + + + Called by the scheduler at the time of the trigger firing, in order to + produce a instance on which to call Execute. + + + It should be extremely rare for this method to throw an exception - + basically only the the case where there is no way at all to instantiate + and prepare the Job for execution. When the exception is thrown, the + Scheduler will move all triggers associated with the Job into the + state, which will require human + intervention (e.g. an application restart after fixing whatever + configuration problem led to the issue wih instantiating the Job. + + + The TriggerFiredBundle from which the + and other info relating to the trigger firing can be obtained. + + a handle to the scheduler that is about to execute the job + SchedulerException if there is a problem instantiating the Job. + the newly instantiated Job + + + + + Called by the scheduler at the time of the trigger firing, in order to + produce a instance on which to call Execute. + + + It should be extremely rare for this method to throw an exception - + basically only the the case where there is no way at all to instantiate + and prepare the Job for execution. When the exception is thrown, the + Scheduler will move all triggers associated with the Job into the + state, which will require human + intervention (e.g. an application restart after fixing whatever + configuration problem led to the issue wih instantiating the Job. + + The TriggerFiredBundle from which the + and other info relating to the trigger firing can be obtained. + + the newly instantiated Job + SchedulerException if there is a problem instantiating the Job. + + + + Called by the scheduler at the time of the trigger firing, in order to + produce a instance on which to call Execute. + + + + It should be extremely rare for this method to throw an exception - + basically only the the case where there is no way at all to instantiate + and prepare the Job for execution. When the exception is thrown, the + Scheduler will move all triggers associated with the Job into the + state, which will require human + intervention (e.g. an application restart after fixing whatever + configuration problem led to the issue wih instantiating the Job. + + + The TriggerFiredBundle from which the + and other info relating to the trigger firing can be obtained. + + the newly instantiated Job + SchedulerException if there is a problem instantiating the Job. + + + + Sets the object properties. + + The object to set properties to. + The data to set. + + + + Whether the JobInstantiation should fail and throw and exception if + a key (name) and value (type) found in the JobDataMap does not + correspond to a proptery setter on the Job class. + + + + + Get or set whether a warning should be logged if + a key (name) and value (type) found in the JobDataMap does not + correspond to a proptery setter on the Job class. + + + + + This class implements a that + utilizes RAM as its storage device. + + As you should know, the ramification of this is that access is extrememly + fast, but the data is completely volatile - therefore this + should not be used if true persistence between program shutdowns is + required. + + + James House + Sharada Jambula + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Gets the fired trigger record id. + + The fired trigger record id. + + + + Called by the QuartzScheduler before the is + used, in order to give the it a chance to Initialize. + + + + + Called by the QuartzScheduler to inform the that + the scheduler has started. + + + + + Called by the QuartzScheduler to inform the JobStore that + the scheduler has been paused. + + + + + Called by the QuartzScheduler to inform the JobStore that + the scheduler has resumed after being paused. + + + + + Called by the QuartzScheduler to inform the that + it should free up all of it's resources because the scheduler is + shutting down. + + + + + Clears (deletes!) all scheduling data - all s, s + s. + + + + + Store the given and . + + The to be stored. + The to be stored. + + + + Returns true if the given job group is paused. + + Job group name + + + + + returns true if the given TriggerGroup is paused. + + + + + + + Store the given . + + The to be stored. + If , any existing in the + with the same name and group should be + over-written. + + + + Remove (delete) the with the given + name, and any s that reference + it. + + + if a with the given name and + group was found and removed from the store. + + + + + Remove (delete) the with the + given name. + + + if a with the given + name and group was found and removed from the store. + + + + + Store the given . + + The to be stored. + If , any existing in + the with the same name and group should + be over-written. + + + + Remove (delete) the with the + given name. + + + + if a with the given + name and group was found and removed from the store. + + The to be removed. + Whether to delete orpahaned job details from scheduler if job becomes orphaned from removing the trigger. + + + + Replaces the trigger. + + The of the to be replaced. + The new trigger. + + + + + Retrieve the for the given + . + + + The desired , or null if there is no match. + + + + + Retrieve the given . + + + The desired , or null if there is no match. + + + + + Determine whether a with the given identifier already + exists within the scheduler. + + the identifier to check for + true if a Job exists with the given identifier + + + + Determine whether a with the given identifier already + exists within the scheduler. + + triggerKey the identifier to check for + true if a Trigger exists with the given identifier + + + + Get the current state of the identified . + + + + + + + + + + + Store the given . + + The name. + The to be stored. + If , any existing + in the with the same name and group + should be over-written. + If , any s existing + in the that reference an existing + Calendar with the same name with have their next fire time + re-computed with the new . + + + + Remove (delete) the with the + given name. + + If removal of the would result in + s pointing to non-existent calendars, then a + will be thrown. + + The name of the to be removed. + + if a with the given name + was found and removed from the store. + + + + + Retrieve the given . + + The name of the to be retrieved. + + The desired , or null if there is no match. + + + + + Get the number of s that are + stored in the . + + + + + Get the number of s that are + stored in the . + + + + + Get the number of s that are + stored in the . + + + + + Get the names of all of the s that + match the given group matcher. + + + + + Get the names of all of the s + in the . + + If there are no ICalendars in the given group name, the result should be + a zero-length array (not ). + + + + + + Get the names of all of the s + that have the given group name. + + + + + Get the names of all of the + groups. + + + + + Get the names of all of the groups. + + + + + Get all of the Triggers that are associated to the given Job. + + If there are no matches, a zero-length array should be returned. + + + + + + Gets the trigger wrappers for job. + + + + + + Gets the trigger wrappers for calendar. + + Name of the cal. + + + + + Pause the with the given name. + + + + + Pause all of the s in the given group. + + The JobStore should "remember" that the group is paused, and impose the + pause on any new triggers that are added to the group while the group is + paused. + + + + + + Pause the with the given + name - by pausing all of its current s. + + + + + Pause all of the s in the + given group - by pausing all of their s. + + The JobStore should "remember" that the group is paused, and impose the + pause on any new jobs that are added to the group while the group is + paused. + + + + + + Resume (un-pause) the with the given key. + + + If the missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + Resume (un-pause) all of the s in the + given group. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + Resume (un-pause) the with + the given name. + + If any of the 's s missed one + or more fire-times, then the 's misfire + instruction will be applied. + + + + + + Resume (un-pause) all of the s + in the given group. + + If any of the s had s that + missed one or more fire-times, then the 's + misfire instruction will be applied. + + + + + + Pause all triggers - equivalent of calling + on every group. + + When is called (to un-pause), trigger misfire + instructions WILL be applied. + + + + + + + Resume (un-pause) all triggers - equivalent of calling + on every trigger group and setting all job groups unpaused />. + + If any missed one or more fire-times, then the + 's misfire instruction will be applied. + + + + + + + Applies the misfire. + + The trigger wrapper. + + + + + Get a handle to the next trigger to be fired, and mark it as 'reserved' + by the calling scheduler. + + + + + + Inform the that the scheduler no longer plans to + fire the given , that it had previously acquired + (reserved). + + + + + Inform the that the scheduler is now firing the + given (executing its associated ), + that it had previously acquired (reserved). + + + + + Inform the that the scheduler has completed the + firing of the given (and the execution its + associated ), and that the + in the given should be updated if the + is stateful. + + + + + Sets the state of all triggers of job to specified state. + + + + + Peeks the triggers. + + + + + + + + + The time span by which a trigger must have missed its + next-fire-time, in order for it to be considered "misfired" and thus + have its misfire instruction applied. + + + + + Returns whether this instance supports persistence. + + + + + + + Inform the of the Scheduler instance's Id, + prior to initialize being invoked. + + + + + Inform the of the Scheduler instance's name, + prior to initialize being invoked. + + + + + Comparer for trigger wrappers. + + + + + Indicates whether the current object is equal to another object of the same type. + + + true if the current object is equal to the parameter; otherwise, false. + + An object to compare with this object. + + + + Serves as a hash function for a particular type. + + + A hash code for the current . + + 2 + + + + Possible internal trigger states + in RAMJobStore + + + + + Waiting + + + + + Acquired + + + + + Executing + + + + + Complete + + + + + Paused + + + + + Blocked + + + + + Paused and Blocked + + + + + Error + + + + + Helper wrapper class + + + + + The key used + + + + + Job's key + + + + + The trigger + + + + + Current state + + + + + Determines whether the specified is equal to the current . + + The to compare with the current . + + true if the specified is equal to the current ; otherwise, false. + + + + + Serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Scheduler exporter that exports scheduler to remoting context. + + Marko Lahma + + + + Service interface for scheduler exporters. + + Marko Lahma + + + + Binds (exports) scheduler to external context. + + + + + + Unbinds scheduler from external context. + + + + + + Registers remoting channel if needed. This is determined + by checking whether there is a positive value for port. + + + + + Gets or sets the port used for remoting. + + + + + Gets or sets the name to use when exporting + scheduler to remoting context. + + + + + Gets or sets the name to use when binding to + tcp channel. + + + + + Sets the channel type when registering remoting. + + + + + + Sets the used when + exporting to remoting context. Defaults to + . + + + + + A implementation that creates + connection to remote scheduler using remoting. + + + + + Client Proxy to a IRemotableQuartzScheduler + + + + + Returns a client proxy to a remote . + + + + + Returns a client proxy to a remote . + + + + + Gets or sets the remote scheduler address. + + The remote scheduler address. + + + + The default InstanceIdGenerator used by Quartz when instance id is to be + automatically generated. Instance id is of the form HOSTNAME + CURRENT_TIME. + + Marko Lahma (.NET) + + + + + + Generate the instance id for a + + The clusterwide unique instance id. + + + + This is class is a simple implementation of a thread pool, based on the + interface. + + + objects are sent to the pool with the + method, which blocks until a becomes available. + + The pool has a fixed number of s, and does not grow or + shrink based on demand. + + James House + Juergen Donnerstag + Marko Lahma (.NET) + + + + The interface to be implemented by classes that want to provide a thread + pool for the 's use. + + + implementation instances should ideally be made + for the sole use of Quartz. Most importantly, when the method + returns a value of 1 or greater, + there must still be at least one available thread in the pool when the + method is called a few moments (or + many moments) later. If this assumption does not hold true, it may + result in extra JobStore queries and updates, and if clustering features + are being used, it may result in greater imballance of load. + + + James House + Marko Lahma (.NET) + + + + Execute the given in the next + available . + + + The implementation of this interface should not throw exceptions unless + there is a serious problem (i.e. a serious misconfiguration). If there + are no available threads, rather it should either queue the Runnable, or + block until a thread is available, depending on the desired strategy. + + + + + Determines the number of threads that are currently available in in + the pool. Useful for determining the number of times + can be called before returning + false. + + + The implementation of this method should block until there is at + least one available thread. + + the number of currently available threads + + + + Must be called before the is + used, in order to give the it a chance to Initialize. + + + Typically called by the . + + + + + Called by the QuartzScheduler to inform the + that it should free up all of it's resources because the scheduler is + shutting down. + + + + + Get the current number of threads in the . + + + + + Inform the of the Scheduler instance's Id, + prior to initialize being invoked. + + + + + Inform the of the Scheduler instance's name, + prior to initialize being invoked. + + + + + Create a new (unconfigured) . + + + + + Create a new with the specified number + of s that have the given priority. + + + the number of worker s in the pool, must + be > 0. + + + the thread priority for the worker threads. + + + + + + Called by the QuartzScheduler before the is + used, in order to give the it a chance to Initialize. + + + + + Terminate any worker threads in this thread group. + Jobs currently in progress will complete. + + + + + Run the given object in the next available + . If while waiting the thread pool is asked to + shut down, the Runnable is executed immediately within a new additional + thread. + + The to be added. + + + + Creates the worker threads. + + The thread count. + + + + + Terminate any worker threads in this thread group. + Jobs currently in progress will complete. + + + + + Gets or sets the number of worker threads in the pool. + Set has no effect after has been called. + + + + + Get or set the thread priority of worker threads in the pool. + Set operation has no effect after has been called. + + + + + Gets or sets the thread name prefix. + + The thread name prefix. + + + + Gets or sets the value of makeThreadsDaemons. + + + + + Gets the size of the pool. + + The size of the pool. + + + + Inform the of the Scheduler instance's Id, + prior to initialize being invoked. + + + + + Inform the of the Scheduler instance's name, + prior to initialize being invoked. + + + + + A Worker loops, waiting to Execute tasks. + + + + + Create a worker thread and start it. Waiting for the next Runnable, + executing it, and waiting for the next Runnable, until the Shutdown + flag is set. + + + + + Create a worker thread, start it, Execute the runnable and terminate + the thread (one time execution). + + + + + Signal the thread that it should terminate. + + + + + Loop, executing targets as they are received. + + + + + A that simply calls . + + + James House + Marko Lahma (.NET) + + + + Called to give the ClassLoadHelper a chance to Initialize itself, + including the oportunity to "steal" the class loader off of the calling + thread, which is the thread that is initializing Quartz. + + + + Return the class with the given name. + + + + Finds a resource with a given name. This method returns null if no + resource with this name is found. + + name of the desired resource + + a Uri object + + + + Finds a resource with a given name. This method returns null if no + resource with this name is found. + + name of the desired resource + + a Stream object + + + + + InstanceIdGenerator that will use a to configure the scheduler. + If no value set for the property, a is thrown. + Alex Snaps + + + + + System property to read the instanceId from. + + + + + Returns the cluster wide value for this scheduler instance's id, based on a system property. + + + + + A string of text to prepend (add to the beginning) to the instanceId found in the system property. + + + + + A string of text to postpend (add to the end) to the instanceId found in the system property. + + + + + The name of the system property from which to obtain the instanceId. + + + Defaults to . + + + + + This is class is a simple implementation of a zero size thread pool, based on the + interface. + + + The pool has zero s and does not grow or shrink based on demand. + Which means it is obviously not useful for most scenarios. When it may be useful + is to prevent creating any worker threads at all - which may be desirable for + the sole purpose of preserving system resources in the case where the scheduler + instance only exists in order to schedule jobs, but which will never execute + jobs (e.g. will never have Start() called on it). + + Wayne Fay + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Called by the QuartzScheduler before the is + used, in order to give the it a chance to Initialize. + + + + + Shutdowns this instance. + + + + + Called by the QuartzScheduler to inform the + that it should free up all of it's resources because the scheduler is + shutting down. + + + + + + Execute the given in the next + available . + + + + + The implementation of this interface should not throw exceptions unless + there is a serious problem (i.e. a serious misconfiguration). If there + are no available threads, rather it should either queue the Runnable, or + block until a thread is available, depending on the desired strategy. + + + + + Determines the number of threads that are currently available in in + the pool. Useful for determining the number of times + can be called before returning + false. + + + the number of currently available threads + + + The implementation of this method should block until there is at + least one available thread. + + + + + Gets the log. + + The log. + + + + Gets the size of the pool. + + The size of the pool. + + + + Inform the of the Scheduler instance's Id, + prior to initialize being invoked. + + + + + Inform the of the Scheduler instance's name, + prior to initialize being invoked. + + + + + A simple class (structure) used for returning execution-time data from the + JobStore to the . + + + James House + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + The job. + The trigger. + The calendar. + if set to true [job is recovering]. + The fire time. + The scheduled fire time. + The previous fire time. + The next fire time. + + + + Gets the job detail. + + The job detail. + + + + Gets the trigger. + + The trigger. + + + + Gets the calendar. + + The calendar. + + + + Gets a value indicating whether this is recovering. + + true if recovering; otherwise, false. + + + + Returns the UTC fire time. + + + + + Gets the next UTC fire time. + + The next fire time. + Returns the nextFireTimeUtc. + + + + Gets the previous UTC fire time. + + The previous fire time. + Returns the previous fire time. + + + + Returns the scheduled UTC fire time. + + + + + Result holder for trigger firing event. + + + + + Constructor. + + + + + + Constructor. + + + + + Bundle. + + + + + Possible exception. + + + + + Extension methods for . + + + + + Tries to read value and returns the value if successfully read. Otherwise return default value + for value's type. + + + + + + + + + + Extension methods for simplified access. + + + + + Returns string from given column name, or null if DbNull. + + + + + Returns int from given column name. + + + + + Returns long from given column name. + + + + + Returns long from given column name, or null if DbNull. + + + + + Returns decimal from given column name. + + + + + Manages a collection of IDbProviders, and provides transparent access + to their database. + + + James House + Sharada Jambula + Mohammad Rezaei + Marko Lahma (.NET) + + + + Private constructor + + + + + Adds the connection provider. + + Name of the data source. + The provider. + + + + Get a database connection from the DataSource with the given name. + + a database connection + + + + Shuts down database connections from the DataSource with the given name, + if applicable for the underlying provider. + + a database connection + + + + Gets the db provider. + + Name of the ds. + + + + + Get the class instance. + + an instance of this class + + + + + An implementation of that wraps another + and flags itself 'dirty' when it is modified. + + James House + Marko Lahma (.NET) + + + + Create a DirtyFlagMap that 'wraps' a . + + + + + Create a DirtyFlagMap that 'wraps' a that has the + given initial capacity. + + + + + Serialization constructor. + + + + + + + Creates a new object that is a copy of the current instance. + + + A new object that is a copy of this instance. + + + + + When implemented by a class, removes all elements from the . + + + The is read-only. + + + + + When implemented by a class, determines whether the contains an element with the specified key. + + The key to locate in the . + + if the contains an element with the key; otherwise, . + + + is . + + + + When implemented by a class, removes the element with the + specified key from the . + + The key of the element to remove. + + is . + + The is read-only. + -or- + The has a fixed size. + + + + + When implemented by a class, returns an + for the . + + + An for the . + + + + + When implemented by a class, adds an element with the provided key and value to the . + + The to use as the key of the element to add. + The to use as the value of the element to add. + is . + + An element with the same key already exists in the . + + + The is read-only. + -or- + The has a fixed size. + + + + + When implemented by a class, copies the elements of + the to an , starting at a particular index. + + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + The zero-based index in at which copying begins. + + is . + + is less than zero. + + + is multidimensional. + -or- + + is equal to or greater than the length of . + -or- + The number of elements in the source is greater than the available space from to the end of the destination . + + The type of the source cannot be cast automatically to the type of the destination . + + + + Clear the 'dirty' flag (set dirty flag to ). + + + + + Determines whether the specified obj contains value. + + The obj. + + true if the specified obj contains value; otherwise, false. + + + + + Gets the entries as a set. + + + + + + Determines whether the specified is equal to the current . + + The to compare with the current . + + if the specified is equal to the + current ; otherwise, . + + + + + Serves as a hash function for a particular type, suitable + for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Gets keyset for this map. + + + + + + Puts the value behind a specified key. + + The key. + The val. + + + + + Puts all. + + The t. + + + + Determine whether the is flagged dirty. + + + + + Get a direct handle to the underlying Map. + + + + + Gets a value indicating whether this instance is empty. + + true if this instance is empty; otherwise, false. + + + + Gets or sets the with the specified key. + + + + + + When implemented by a class, gets the number of + elements contained in the . + + + + + + When implemented by a class, gets an containing the values in the . + + + + + + When implemented by a class, gets an containing the keys of the . + + + + + + When implemented by a class, gets a value indicating whether the + is read-only. + + + + + + When implemented by a class, gets a value indicating whether the + has a fixed size. + + + + + + When implemented by a class, gets an object that + can be used to synchronize access to the . + + + + + + When implemented by a class, gets a value + indicating whether access to the is synchronized + (thread-safe). + + + + + + Utility class for file handling related things. + + Marko Lahma + + + + Resolves file to actual file if for example relative '~' used. + + File name to check + Expanded file name or actual no resolving was done. + + + + Object representing a job or trigger key. + + Jeffrey Wescott + Marko Lahma (.NET) + + + + The default group for scheduling entities, with the value "DEFAULT". + + + + + Construct a new key with the given name and group. + + the name + the group + + + + Return the string representation of the key. The format will be: + <group>.<name>. + + + + the string representation of the key + + + + + Get the name portion of the key. + + the name + + + + + Get the group portion of the key. + + + + the group + + + + + Wrapper class to access thread local data. + Data is either accessed from thread or HTTP Context's + data if HTTP Context is avaiable. + + Marko Lahma .NET + + + + Retrieves an object with the specified name. + + The name of the item. + The object in the call context associated with the specified name or null if no object has been stored previously + + + + Stores a given object and associates it with the specified name. + + The name with which to associate the new item. + The object to store in the call context. + + + + Empties a data slot with the specified name. + + The name of the data slot to empty. + + + + Generic extension methods for objects. + + + + + Creates a deep copy of object by serializing to memory stream. + + + + + + Utility methods that are used to convert objects from one type into another. + + Aleksandar Seovic + Marko Lahma + + + + Convert the value to the required (if necessary from a string). + + The proposed change value. + + The we must convert to. + + The new value, possibly the result of type conversion. + + + + Determines whether value is assignable to required type. + + The value to check. + Type of the required. + + true if value can be assigned as given type; otherwise, false. + + + + + Instantiates an instance of the type specified. + + + + + + Sets the object properties using reflection. + + + + + Sets the object properties using reflection. + + The object to set values to. + The properties to set to object. + + + + This is an utility class used to parse the properties. + + James House + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + The props. + + + + Gets the string property. + + The name. + + + + + Gets the string property. + + The name. + The default value. + + + + + Gets the string array property. + + The name. + + + + + Gets the string array property. + + The name. + The default value. + + + + + Gets the boolean property. + + The name. + + + + + Gets the boolean property. + + The name. + if set to true [defaultValue]. + + + + + Gets the byte property. + + The name. + + + + + Gets the byte property. + + The name. + The default value. + + + + + Gets the char property. + + The name. + + + + + Gets the char property. + + The name. + The default value. + + + + + Gets the double property. + + The name. + + + + + Gets the double property. + + The name. + The default value. + + + + + Gets the float property. + + The name. + + + + + Gets the float property. + + The name. + The default value. + + + + + Gets the int property. + + The name. + + + + + Gets the int property. + + The name. + The default value. + + + + + Gets the int array property. + + The name. + + + + + Gets the int array property. + + The name. + The default value. + + + + + Gets the long property. + + The name. + + + + + Gets the long property. + + The name. + The def. + + + + + Gets the TimeSpan property. + + The name. + The def. + + + + + Gets the short property. + + The name. + + + + + Gets the short property. + + The name. + The default value. + + + + + Gets the property groups. + + The prefix. + + + + + Gets the property group. + + The prefix. + + + + + Gets the property group. + + The prefix. + if set to true [strip prefix]. + + + + + Get all properties that start with the given prefix. + + The prefix for which to search. If it does not end in a "." then one will be added to it for search purposes. + Whether to strip off the given in the result's keys. + Optional array of fully qualified prefixes to exclude. For example if is "a.b.c", then might be "a.b.c.ignore". + Group of that start with the given prefix, optionally have that prefix removed, and do not include properties that start with one of the given excluded prefixes. + + + + Reads the properties from assembly (embedded resource). + + The file name to read resources from. + + + + + Reads the properties from file system. + + The file name to read resources from. + + + + + Gets the underlying properties. + + The underlying properties. + + + + Extension methods for . + + + + + Allows null-safe trimming of string. + + + + + + + Trims string and if resulting string is empty, null is returned. + + + + + + + An implementation of that wraps another + and flags itself 'dirty' when it is modified, enforces that all keys are + strings. + + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The initial capacity. + + + + Serialization constructor. + + + + + + + Determines whether the specified is equal to the current . + + The to compare with the current . + + if the specified is equal to the + current ; otherwise, . + + + + + Serves as a hash function for a particular type, suitable + for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Gets the keys. + + + + + + Adds the name-value pairs in the given to the . + + All keys must be s, and all values must be serializable. + + + + + + Adds the given value to the 's + data map. + + + + + Adds the given value to the 's + data map. + + + + + Adds the given value to the 's + data map. + + + + + Adds the given value to the 's + data map. + + + + + Adds the given value to the 's + data map. + + + + + Adds the given value to the 's + data map. + + + + + Adds the given value to the 's + data map. + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Reports JobSchedulingDataProcessor validation exceptions. + + Chris Bonham + Marko Lahma (.NET) + + + + Constructor for ValidationException. + + + + + Constructor for ValidationException. + + exception message. + + + + Constructor for ValidationException. + + collection of validation exceptions. + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + Gets the validation exceptions. + + The validation exceptions. + + + + Returns the detail message string. + + + + + Parses an XML file that declares Jobs and their schedules (Triggers). + + + + The xml document must conform to the format defined in "job_scheduling_data_2_0.xsd" + + + + After creating an instance of this class, you should call one of the + functions, after which you may call the ScheduledJobs() + function to get a handle to the defined Jobs and Triggers, which can then be + scheduled with the . Alternatively, you could call + the function to do all of this + in one step. + + + + The same instance can be used again and again, with the list of defined Jobs + being cleared each time you call a method, + however a single instance is not thread-safe. + + + Chris Bonham + James House + Marko Lahma (.NET) + + + + Constructor for XMLSchedulingDataProcessor. + + + + + Process the xml file in the default location (a file named + "quartz_jobs.xml" in the current working directory). + + + + + Process the xml file named . + + meta data file name. + + + + Process the xmlfile named with the given system + ID. + + Name of the file. + The system id. + + + + Process the xmlfile named with the given system + ID. + + The stream. + The system id. + + + + Process the xml file in the default location, and schedule all of the jobs defined within it. + + Note that we will set overWriteExistingJobs after the default xml is parsed. + + + + + + Process the xml file in the default location, and schedule all of the + jobs defined within it. + + + + + Process the xml file in the given location, and schedule all of the + jobs defined within it. + + meta data file name. + The scheduler. + + + + Process the xml file in the given location, and schedule all of the + jobs defined within it. + + Name of the file. + The system id. + The sched. + + + + Schedules the given sets of jobs and triggers. + + The sched. + + + + Adds a detected validation exception. + + The exception. + + + + Resets the the number of detected validation exceptions. + + + + + Throws a ValidationException if the number of validationExceptions + detected is greater than zero. + + + DTD validation exception. + + + + + Whether the existing scheduling data (with same identifiers) will be + overwritten. + + + If false, and is not false, and jobs or + triggers with the same names already exist as those in the file, an + error will occur. + + + + + + If true (and is false) then any + job/triggers encountered in this file that have names that already exist + in the scheduler will be ignored, and no error will be produced. + + + + + + Gets the log. + + The log. + + + + Helper class to map constant names to their values. + + + + + CalendarIntervalScheduleBuilder is a + that defines calendar time (day, week, month, year) interval-based + schedules for Triggers. + + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + Client code can then use the DSL to write code such as this: + + JobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + Trigger trigger = TriggerBuilder.Create() + .WithIdentity("myTrigger", "myTriggerGroup") + .WithSimpleSchedule(x => x + .WithIntervalInHours(1) + .RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + + + + Base class for implementors. + + + + + + Schedule builders offer fluent interface and are responsible for creating schedules. + + + + + + + + + Build the actual Trigger -- NOT intended to be invoked by end users, + but will rather be invoked by a TriggerBuilder which this + ScheduleBuilder is given to. + + + + + + Build the actual Trigger -- NOT intended to be invoked by end users, + but will rather be invoked by a TriggerBuilder which this + ScheduleBuilder is given to. + + + + + + Create a CalendarIntervalScheduleBuilder. + + + + + + Build the actual Trigger -- NOT intended to be invoked by end users, + but will rather be invoked by a TriggerBuilder which this + ScheduleBuilder is given to. + + + + + + Specify the time unit and interval for the Trigger to be produced. + + + + the interval at which the trigger should repeat. + the time unit (IntervalUnit) of the interval. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.SECOND that the produced + Trigger will repeat at. + + + + the number of seconds at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.MINUTE that the produced + Trigger will repeat at. + + + + the number of minutes at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.HOUR that the produced + Trigger will repeat at. + + + + the number of hours at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.DAY that the produced + Trigger will repeat at. + + + + the number of days at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.WEEK that the produced + Trigger will repeat at. + + + + the number of weeks at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.MONTH that the produced + Trigger will repeat at. + + + + the number of months at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.YEAR that the produced + Trigger will repeat at. + + + + the number of years at which the trigger should repeat. + the updated CalendarIntervalScheduleBuilder + + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CronScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CalendarIntervalScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CalendarIntervalScheduleBuilder + + + + + TimeZone in which to base the schedule. + + the time-zone for the schedule + the updated CalendarIntervalScheduleBuilder + + + + + If intervals are a day or greater, this property (set to true) will + cause the firing of the trigger to always occur at the same time of day, + (the time of day of the startTime) regardless of daylight saving time + transitions. Default value is false. + + + + For example, without the property set, your trigger may have a start + time of 9:00 am on March 1st, and a repeat interval of 2 days. But + after the daylight saving transition occurs, the trigger may start + firing at 8:00 am every other day. + + + If however, the time of day does not exist on a given day to fire + (e.g. 2:00 am in the United States on the days of daylight saving + transition), the trigger will go ahead and fire one hour off on + that day, and then resume the normal hour on other days. If + you wish for the trigger to never fire at the "wrong" hour, then + you should set the property skipDayIfHourDoesNotExist. + + + + + + + + + + If intervals are a day or greater, and + preserveHourOfDayAcrossDaylightSavings property is set to true, and the + hour of the day does not exist on a given day for which the trigger + would fire, the day will be skipped and the trigger advanced a second + interval if this property is set to true. Defaults to false. + + + CAUTION! If you enable this property, and your hour of day happens + to be that of daylight savings transition (e.g. 2:00 am in the United + States) and the trigger's interval would have had the trigger fire on + that day, then you may actually completely miss a firing on the day of + transition if that hour of day does not exist on that day! In such a + case the next fire time of the trigger will be computed as double (if + the interval is 2 days, then a span of 4 days between firings will + occur). + + + + + + Extension methods that attach to . + + + + + Provides a parser and evaluator for unix-like cron expressions. Cron + expressions provide the ability to specify complex time combinations such as + "At 8:00am every Monday through Friday" or "At 1:30am every + last Friday of the month". + + + + Cron expressions are comprised of 6 required fields and one optional field + separated by white space. The fields respectively are described as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field Name Allowed Values Allowed Special Characters
Seconds 0-59 , - /// /
Minutes 0-59 , - /// /
Hours 0-23 , - /// /
Day-of-month 1-31 , - /// ? / L W C
Month 1-12 or JAN-DEC , - /// /
Day-of-Week 1-7 or SUN-SAT , - /// ? / L #
Year (Optional) empty, 1970-2199 , - /// /
+ + The '*' character is used to specify all values. For example, "*" + in the minute field means "every minute". + + + The '?' character is allowed for the day-of-month and day-of-week fields. It + is used to specify 'no specific value'. This is useful when you need to + specify something in one of the two fields, but not the other. + + + The '-' character is used to specify ranges For example "10-12" in + the hour field means "the hours 10, 11 and 12". + + + The ',' character is used to specify additional values. For example + "MON,WED,FRI" in the day-of-week field means "the days Monday, + Wednesday, and Friday". + + + The '/' character is used to specify increments. For example "0/15" + in the seconds field means "the seconds 0, 15, 30, and 45". And + "5/15" in the seconds field means "the seconds 5, 20, 35, and + 50". Specifying '*' before the '/' is equivalent to specifying 0 is + the value to start with. Essentially, for each field in the expression, there + is a set of numbers that can be turned on or off. For seconds and minutes, + the numbers range from 0 to 59. For hours 0 to 23, for days of the month 0 to + 31, and for months 1 to 12. The "/" character simply helps you turn + on every "nth" value in the given set. Thus "7/6" in the + month field only turns on month "7", it does NOT mean every 6th + month, please note that subtlety. + + + The 'L' character is allowed for the day-of-month and day-of-week fields. + This character is short-hand for "last", but it has different + meaning in each of the two fields. For example, the value "L" in + the day-of-month field means "the last day of the month" - day 31 + for January, day 28 for February on non-leap years. If used in the + day-of-week field by itself, it simply means "7" or + "SAT". But if used in the day-of-week field after another value, it + means "the last xxx day of the month" - for example "6L" + means "the last friday of the month". You can also specify an offset + from the last day of the month, such as "L-3" which would mean the third-to-last + day of the calendar month. When using the 'L' option, it is important not to + specify lists, or ranges of values, as you'll get confusing/unexpected results. + + + The 'W' character is allowed for the day-of-month field. This character + is used to specify the weekday (Monday-Friday) nearest the given day. As an + example, if you were to specify "15W" as the value for the + day-of-month field, the meaning is: "the nearest weekday to the 15th of + the month". So if the 15th is a Saturday, the trigger will fire on + Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the + 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th. + However if you specify "1W" as the value for day-of-month, and the + 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not + 'jump' over the boundary of a month's days. The 'W' character can only be + specified when the day-of-month is a single day, not a range or list of days. + + + The 'L' and 'W' characters can also be combined for the day-of-month + expression to yield 'LW', which translates to "last weekday of the + month". + + + The '#' character is allowed for the day-of-week field. This character is + used to specify "the nth" XXX day of the month. For example, the + value of "6#3" in the day-of-week field means the third Friday of + the month (day 6 = Friday and "#3" = the 3rd one in the month). + Other examples: "2#1" = the first Monday of the month and + "4#5" = the fifth Wednesday of the month. Note that if you specify + "#5" and there is not 5 of the given day-of-week in the month, then + no firing will occur that month. If the '#' character is used, there can + only be one expression in the day-of-week field ("3#1,6#3" is + not valid, since there are two expressions). + + + + + + The legal characters and the names of months and days of the week are not + case sensitive. + + + NOTES: +
    +
  • Support for specifying both a day-of-week and a day-of-month value is + not complete (you'll need to use the '?' character in one of these fields). +
    • +
  • Overflowing ranges is supported - that is, having a larger number on + the left hand side than the right. You might do 22-2 to catch 10 o'clock + at night until 2 o'clock in the morning, or you might have NOV-FEB. It is + very important to note that overuse of overflowing ranges creates ranges + that don't make sense and no effort has been made to determine which + interpretation CronExpression chooses. An example would be + "0 0 14-6 ? * FRI-MON".
    • +
+ + + Sharada Jambula + James House + Contributions from Mads Henderson + Refactoring from CronTrigger to CronExpression by Aaron Craven + Marko Lahma (.NET) + + + + Field specification for second. + + + + + Field specification for minute. + + + + + Field specification for hour. + + + + + Field specification for day of month. + + + + + Field specification for month. + + + + + Field specification for day of week. + + + + + Field specification for year. + + + + + Field specification for all wildcard value '*'. + + + + + Field specification for not specified value '?'. + + + + + Field specification for wildcard '*'. + + + + + Field specification for no specification at all '?'. + + + + + Seconds. + + + + + minutes. + + + + + Hours. + + + + + Days of month. + + + + + Months. + + + + + Days of week. + + + + + Years. + + + + + Last day of week. + + + + + Nth day of week. + + + + + Last day of month. + + + + + Nearest weekday. + + + + + Calendar day of week. + + + + + Calendar day of month. + + + + + Expression parsed. + + + + + Constructs a new based on the specified + parameter. + + + String representation of the cron expression the new object should represent + + + + + + Indicates whether the given date satisfies the cron expression. + + + Note that milliseconds are ignored, so two Dates falling on different milliseconds + of the same second will always have the same result here. + + The date to evaluate. + a boolean indicating whether the given date satisfies the cron expression + + + + Returns the next date/time after the given date/time which + satisfies the cron expression. + + the date/time at which to begin the search for the next valid date/time + the next valid date/time + + + + Returns the next date/time after the given date/time which does + not satisfy the expression. + + the date/time at which to begin the search for the next invalid date/time + the next valid date/time + + + + Returns the string representation of the + + The string representation of the + + + + Indicates whether the specified cron expression can be parsed into a + valid cron expression + + the expression to evaluate + a boolean indicating whether the given expression is a valid cron + expression + + + + Builds the expression. + + The expression. + + + + Stores the expression values. + + The position. + The string to traverse. + The type of value. + + + + + Checks the next value. + + The position. + The string to check. + The value. + The type to search. + + + + + Gets the expression summary. + + + + + + Gets the expression set summary. + + The data. + + + + + Skips the white space. + + The i. + The s. + + + + + Finds the next white space. + + The i. + The s. + + + + + Adds to set. + + The val. + The end. + The incr. + The type. + + + + Gets the set of given type. + + The type of set to get. + + + + + Gets the value. + + The v. + The s. + The i. + + + + + Gets the numeric value from string. + + The string to parse from. + The i. + + + + + Gets the month number. + + The string to map with. + + + + + Gets the day of week number. + + The s. + + + + + Gets the time from given time parts. + + The seconds. + The minutes. + The hours. + The day of month. + The month. + + + + + Gets the next fire time after the given time. + + The UTC time to start searching from. + + + + + Creates the date time without milliseconds. + + The time. + + + + + Advance the calendar to the particular hour paying particular attention + to daylight saving problems. + + The date. + The hour. + + + + + Gets the time before. + + The end time. + + + + + NOT YET IMPLEMENTED: Returns the final time that the + will match. + + + + + + Determines whether given year is a leap year. + + The year. + + true if the specified year is a leap year; otherwise, false. + + + + + Gets the last day of month. + + The month num. + The year. + + + + + Creates a new object that is a copy of the current instance. + + + A new object that is a copy of this instance. + + + + + Determines whether the specified is equal to the current . + + + true if the specified is equal to the current ; otherwise, false. + + The to compare with the current . + + + + Determines whether the specified is equal to the current . + + + true if the specified is equal to the current ; otherwise, false. + + The to compare with the current . + + + + Serves as a hash function for a particular type. + + + A hash code for the current . + + 2 + + + + Sets or gets the time zone for which the of this + will be resolved. + + + + + Gets the cron expression string. + + The cron expression string. + + + + Helper class for cron expression handling. + + + + + The value. + + + + + The position. + + + + + CronScheduleBuilder is a that defines + -based schedules for s. + + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + + Client code can then use the DSL to write code such as this: + + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + ITrigger trigger = newTrigger() + .WithIdentity(triggerKey("myTrigger", "myTriggerGroup")) + .WithSimpleSchedule(x => x.WithIntervalInHours(1).RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + + + + + Build the actual Trigger -- NOT intended to be invoked by end users, + but will rather be invoked by a TriggerBuilder which this + ScheduleBuilder is given to. + + + + + + Create a CronScheduleBuilder with the given cron-expression - which + is presumed to b e valid cron expression (and hence only a RuntimeException + will be thrown if it is not). + + + + the cron expression to base the schedule on. + the new CronScheduleBuilder + + + + + Create a CronScheduleBuilder with the given cron-expression string - which + may not be a valid cron expression (and hence a ParseException will be thrown + f it is not). + + the cron expression string to base the schedule on + the new CronScheduleBuilder + + + + + Create a CronScheduleBuilder with the given cron-expression. + + the cron expression to base the schedule on. + the new CronScheduleBuilder + + + + + Create a CronScheduleBuilder with a cron-expression that sets the + schedule to fire every day at the given time (hour and minute). + + + + the hour of day to fire + the minute of the given hour to fire + the new CronScheduleBuilder + + + + + Create a CronScheduleBuilder with a cron-expression that sets the + schedule to fire at the given day at the given time (hour and minute) on the given days of the week. + + the hour of day to fire + the minute of the given hour to fire + the days of the week to fire + the new CronScheduleBuilder + + + + + Create a CronScheduleBuilder with a cron-expression that sets the + schedule to fire one per week on the given day at the given time + (hour and minute). + + + + the day of the week to fire + the hour of day to fire + the minute of the given hour to fire + the new CronScheduleBuilder + + + + + Create a CronScheduleBuilder with a cron-expression that sets the + schedule to fire one per month on the given day of month at the given + time (hour and minute). + + + + the day of the month to fire + the hour of day to fire + the minute of the given hour to fire + the new CronScheduleBuilder + + + + + The in which to base the schedule. + + + + the time-zone for the schedule. + the updated CronScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CronScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CronScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CronScheduleBuilder + + + + + Extension methods that attach to . + + + + + A implementation that build schedule for DailyTimeIntervalTrigger. + + + + This builder provide an extra convenient method for you to set the trigger's EndTimeOfDay. You may + use either endingDailyAt() or EndingDailyAfterCount() to set the value. The later will auto calculate + your EndTimeOfDay by using the interval, IntervalUnit and StartTimeOfDay to perform the calculation. + + + When using EndingDailyAfterCount(), you should note that it is used to calculating EndTimeOfDay. So + if your startTime on the first day is already pass by a time that would not add up to the count you + expected, until the next day comes. Remember that DailyTimeIntervalTrigger will use StartTimeOfDay + and endTimeOfDay as fresh per each day! + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + Client code can then use the DSL to write code such as this: + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + + ITrigger trigger = TriggerBuilder.Create() + .WithIdentity(triggerKey("myTrigger", "myTriggerGroup")) + .WithDailyTimeIntervalSchedule(x => + x.WithIntervalInMinutes(15) + .StartingDailyAt(TimeOfDay.HourAndMinuteOfDay(8, 0)) + .Build(); + + scheduler.scheduleJob(job, trigger); + + + James House + Zemian Deng saltnlight5@gmail.com + Nuno Maia (.NET) + + + + A set of all days of the week. + + + The set contains all values between and + + + + + A set of the business days of the week (for locales similar to the USA). + + + The set contains all values between and + + + + + A set of the weekend days of the week (for locales similar to the USA). + + + The set contains and + + + + + Create a DailyTimeIntervalScheduleBuilder + + The new DailyTimeIntervalScheduleBuilder + + + + Build the actual Trigger -- NOT intended to be invoked by end users, + but will rather be invoked by a TriggerBuilder which this + ScheduleBuilder is given to. + + + + + + Specify the time unit and interval for the Trigger to be produced. + + + + the interval at which the trigger should repeat. + the time unit (IntervalUnit) of the interval. + the updated CalendarIntervalScheduleBuilder + + + + + + Specify an interval in the IntervalUnit.Second that the produced + Trigger will repeat at. + + The number of seconds at which the trigger should repeat. + the updated DailyTimeIntervalScheduleBuilder> + + + + + + Specify an interval in the IntervalUnit.Minute that the produced + Trigger will repeat at. + + The number of minutes at which the trigger should repeat. + the updated DailyTimeIntervalScheduleBuilder> + + + + + + Specify an interval in the IntervalUnit.Hour that the produced + Trigger will repeat at. + + The number of hours at which the trigger should repeat. + the updated DailyTimeIntervalScheduleBuilder> + + + + + + Set the trigger to fire on the given days of the week. + + a Set containing the integers representing the days of the week, defined by - . + + the updated DailyTimeIntervalScheduleBuilder + + + + Set the trigger to fire on the given days of the week. + + a variable length list of week days representing the days of the week + the updated DailyTimeIntervalScheduleBuilder + + + + Set the trigger to fire on the days from Monday through Friday. + + the updated DailyTimeIntervalScheduleBuilder + + + + Set the trigger to fire on the days Saturday and Sunday. + + the updated DailyTimeIntervalScheduleBuilder + + + + Set the trigger to fire on all days of the week. + + the updated DailyTimeIntervalScheduleBuilder + + + + Set the trigger to begin firing each day at the given time. + + + the updated DailyTimeIntervalScheduleBuilder + + + + Set the startTimeOfDay for this trigger to end firing each day at the given time. + + + the updated DailyTimeIntervalScheduleBuilder + + + + Calculate and set the EndTimeOfDay using count, interval and StarTimeOfDay. This means + that these must be set before this method is call. + + + the updated DailyTimeIntervalScheduleBuilder + + + + If the Trigger misfires, use the + instruction. + + the updated DailyTimeIntervalScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + the updated DailyTimeIntervalScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + the updated DailyTimeIntervalScheduleBuilder + + + + + Set number of times for interval to repeat. + + + Note: if you want total count = 1 (at start time) + repeatCount + + + + + + + Extension methods that attach to . + + + + + DateBuilder is used to conveniently create + instances that meet particular criteria. + + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + Client code can then use the DSL to write code such as this: + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + ITrigger trigger = newTrigger() + .WithIdentity(triggerKey("myTrigger", "myTriggerGroup")) + .WithSimpleSchedule(x => x + .WithIntervalInHours(1) + .RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minutes)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + Create a DateBuilder, with initial settings for the current date + and time in the system default timezone. + + + + + Create a DateBuilder, with initial settings for the current date and time in the given timezone. + + + + + + Create a DateBuilder, with initial settings for the current date and time in the system default timezone. + + + + + + Create a DateBuilder, with initial settings for the current date and time in the given timezone. + + Time zone to use. + + + + + Build the defined by this builder instance. + + New date time based on builder parameters. + + + + Set the hour (0-23) for the Date that will be built by this builder. + + + + + + + Set the minute (0-59) for the Date that will be built by this builder. + + + + + + + Set the second (0-59) for the Date that will be built by this builder, and truncate the milliseconds to 000. + + + + + + + Set the day of month (1-31) for the Date that will be built by this builder. + + + + + + + Set the month (1-12) for the Date that will be built by this builder. + + + + + + + Set the year for the Date that will be built by this builder. + + + + + + + Set the TimeZoneInfo for the Date that will be built by this builder (if "null", system default will be used) + + + + + + + Get a object that represents the given time, on + tomorrow's date. + + + + + + + + + Get a object that represents the given time, on + today's date (equivalent to . + + + + + + + + + Get a object that represents the given time, on today's date. + + The value (0-59) to give the seconds field of the date + The value (0-59) to give the minutes field of the date + The value (0-23) to give the hours field of the date + the new date + + + + Get a object that represents the given time, on the + given date. + + The value (0-59) to give the seconds field of the date + The value (0-59) to give the minutes field of the date + The value (0-23) to give the hours field of the date + The value (1-31) to give the day of month field of the date + The value (1-12) to give the month field of the date + the new date + + + + Get a object that represents the given time, on the + given date. + + + + The value (0-59) to give the seconds field of the date + The value (0-59) to give the minutes field of the date + The value (0-23) to give the hours field of the date + The value (1-31) to give the day of month field of the date + The value (1-12) to give the month field of the date + The value (1970-2099) to give the year field of the date + the new date + + + + Returns a date that is rounded to the next even hour after the current time. + + + For example a current time of 08:13:54 would result in a date + with the time of 09:00:00. If the date's time is in the 23rd hour, the + date's 'day' will be promoted, and the time will be set to 00:00:00. + + the new rounded date + + + + Returns a date that is rounded to the next even hour above the given date. + + + For example an input date with a time of 08:13:54 would result in a date + with the time of 09:00:00. If the date's time is in the 23rd hour, the + date's 'day' will be promoted, and the time will be set to 00:00:00. + + the Date to round, if the current time will + be used + the new rounded date + + + + Returns a date that is rounded to the previous even hour below the given date. + + + For example an input date with a time of 08:13:54 would result in a date + with the time of 08:00:00. + + the Date to round, if the current time will + be used + the new rounded date + + + + + Returns a date that is rounded to the next even minute after the current time. + + + + For example a current time of 08:13:54 would result in a date + with the time of 08:14:00. If the date's time is in the 59th minute, + then the hour (and possibly the day) will be promoted. + + the new rounded date + + + + Returns a date that is rounded to the next even minute above the given date. + + + For example an input date with a time of 08:13:54 would result in a date + with the time of 08:14:00. If the date's time is in the 59th minute, + then the hour (and possibly the day) will be promoted. + + The Date to round, if the current time will be used + The new rounded date + + + + Returns a date that is rounded to the previous even minute below the given date. + + + For example an input date with a time of 08:13:54 would result in a date + with the time of 08:13:00. + + the Date to round, if the current time will + be used + the new rounded date + + + + Returns a date that is rounded to the next even second after the current time. + + the new rounded date + + + + Returns a date that is rounded to the next even second above the given date. + + + the Date to round, if the current time will + be used + the new rounded date + + + + Returns a date that is rounded to the previous even second below the + given date. + + + + For example an input date with a time of 08:13:54.341 would result in a + date with the time of 08:13:00.000. + + + + the Date to round, if the current time will + be used + the new rounded date + + + + Returns a date that is rounded to the next even multiple of the given + minute. + + + + For example an input date with a time of 08:13:54, and an input + minute-base of 5 would result in a date with the time of 08:15:00. The + same input date with an input minute-base of 10 would result in a date + with the time of 08:20:00. But a date with the time 08:53:31 and an + input minute-base of 45 would result in 09:00:00, because the even-hour + is the next 'base' for 45-minute intervals. + + + More examples: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Input TimeMinute-BaseResult Time
11:16:412011:20:00
11:36:412011:40:00
11:46:412012:00:00
11:26:413011:30:00
11:36:413012:00:00
11:16:411711:17:00
11:17:411711:34:00
11:52:411712:00:00
11:52:41511:55:00
11:57:41512:00:00
11:17:41012:00:00
11:17:41111:08:00
+ + + + the Date to round, if the current time will + be used + + the base-minute to set the time on + the new rounded date + + + + + Returns a date that is rounded to the next even multiple of the given + minute. + + + The rules for calculating the second are the same as those for + calculating the minute in the method . + + the Date to round, if the current time will + be used + the base-second to set the time on + the new rounded date + + + + + An attribute that marks a class as one that must not have multiple + instances executed concurrently (where instance is based-upon a + definition - or in other words based upon a . + + + This can be used in lieu of implementing the StatefulJob marker interface that + was used prior to Quartz 2.0 + + + James House + Marko Lahma (.NET) + + + + The interface to be implemented by s that provide a + mechanism for having their execution interrupted. It is NOT a requirement + for jobs to implement this interface - in fact, for most people, none of + their jobs will. + + + + The means of actually interrupting the Job must be implemented within the + itself (the method of this + interface is simply a means for the scheduler to inform the + that a request has been made for it to be interrupted). The mechanism that + your jobs use to interrupt themselves might vary between implementations. + However the principle idea in any implementation should be to have the + body of the job's periodically check some flag to + see if an interruption has been requested, and if the flag is set, somehow + abort the performance of the rest of the job's work. An example of + interrupting a job can be found in the java source for the class + . It is legal to use + some combination of and + synchronization within and + in order to have the method block until the + signals that it has noticed the set flag. + + + + If the Job performs some form of blocking I/O or similar functions, you may + want to consider having the method store a + reference to the calling as a member variable. Then the + implementation of this interfaces method can call + on that Thread. Before attempting this, make + sure that you fully understand what + does and doesn't do. Also make sure that you clear the Job's member + reference to the Thread when the Execute(..) method exits (preferably in a + block. + + + + + + James House + Marko Lahma (.NET) + + + + Called by the when a user + interrupts the . + + void (nothing) if job interrupt is successful. + + + + Supported interval units used by . + + + + + A marker interface for s that + wish to have their state maintained between executions. + + + instances follow slightly different rules from + regular instances. The key difference is that their + associated is re-persisted after every + execution of the job, thus preserving state for the next execution. The + other difference is that stateful jobs are not allowed to Execute + concurrently, which means new triggers that occur before the completion of + the method will be delayed. + + + + + + + + James House + Marko Lahma (.NET) + + + + JobBuilder is used to instantiate s. + + + + The builder will always try to keep itself in a valid state, with + reasonable defaults set for calling Build() at any point. For instance + if you do not invoke WithIdentity(..) a job name will be generated + for you. + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + + Client code can then use the DSL to write code such as this: + + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + + ITrigger trigger = TriggerBuilder.Create() + .WithIdentity("myTrigger", "myTriggerGroup") + .WithSimpleSchedule(x => x.WithIntervalInHours(1).RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + + scheduler.scheduleJob(job, trigger); + + + + + + + + + Create a JobBuilder with which to define a . + + a new JobBuilder + + + + Create a JobBuilder with which to define a , + and set the class name of the job to be executed. + + a new JobBuilder + + + + Create a JobBuilder with which to define a , + and set the class name of the job to be executed. + + a new JobBuilder + + + + Produce the instance defined by this JobBuilder. + + the defined JobDetail. + + + + Use a with the given name and default group to + identify the JobDetail. + + + If none of the 'withIdentity' methods are set on the JobBuilder, + then a random, unique JobKey will be generated. + + the name element for the Job's JobKey + the updated JobBuilder + + + + + + Use a with the given name and group to + identify the JobDetail. + + + If none of the 'withIdentity' methods are set on the JobBuilder, + then a random, unique JobKey will be generated. + + the name element for the Job's JobKey + the group element for the Job's JobKey + the updated JobBuilder + + + + + + Use a to identify the JobDetail. + + + If none of the 'withIdentity' methods are set on the JobBuilder, + then a random, unique JobKey will be generated. + + the Job's JobKey + the updated JobBuilder + + + + + + Set the given (human-meaningful) description of the Job. + + the description for the Job + the updated JobBuilder + + + + + Set the class which will be instantiated and executed when a + Trigger fires that is associated with this JobDetail. + + the updated JobBuilder + + + + + Set the class which will be instantiated and executed when a + Trigger fires that is associated with this JobDetail. + + the updated JobBuilder + + + + + Instructs the whether or not the job + should be re-executed if a 'recovery' or 'fail-over' situation is + encountered. + + + If not explicitly set, the default value is . + + the updated JobBuilder + + + + + Instructs the whether or not the job + should be re-executed if a 'recovery' or 'fail-over' situation is + encountered. + + + If not explicitly set, the default value is . + + + the updated JobBuilder + + + + Whether or not the job should remain stored after it is + orphaned (no s point to it). + + + If not explicitly set, the default value is . + + the updated JobBuilder + + + + + Whether or not the job should remain stored after it is + orphaned (no s point to it). + + + If not explicitly set, the default value is . + + the value to set for the durability property. + the updated JobBuilder + + + + + Add the given key-value pair to the JobDetail's . + + the updated JobBuilder + + + + + Add the given key-value pair to the JobDetail's . + + the updated JobBuilder + + + + + Add the given key-value pair to the JobDetail's . + + the updated JobBuilder + + + + + Add the given key-value pair to the JobDetail's . + + the updated JobBuilder + + + + + Add the given key-value pair to the JobDetail's . + + the updated JobBuilder + + + + + Add the given key-value pair to the JobDetail's . + + the updated JobBuilder + + + + + Set the JobDetail's , adding any values to it + that were already set on this JobBuilder using any of the + other 'usingJobData' methods. + + the updated JobBuilder + + + + + Holds state information for instances. + + + instances are stored once when the + is added to a scheduler. They are also re-persisted after every execution of + instances that have present. + + instances can also be stored with a + . This can be useful in the case where you have a Job + that is stored in the scheduler for regular/repeated use by multiple + Triggers, yet with each independent triggering, you want to supply the + Job with different data inputs. + + + The passed to a Job at execution time + also contains a convenience that is the result + of merging the contents of the trigger's JobDataMap (if any) over the + Job's JobDataMap (if any). + + + + + + + James House + Marko Lahma (.NET) + + + + Create an empty . + + + + + Create a with the given data. + + + + + Create a with the given data. + + + + + Serialization constructor. + + + + + + + Adds the given value as a string version to the + 's data map. + + + + + Adds the given value as a string version to the + 's data map. + + + + + Adds the given value as a string version to the + 's data map. + + + + + Adds the given value as a string version to the + 's data map. + + + + + Adds the given value as a string version to the + 's data map. + + + + + Adds the given value as a string version to the + 's data map. + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the + . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Retrieve the identified value from the . + + + + + Gets the date time. + + The key. + + + + + Gets the value behind the specified key. + + The key. + + + + + An exception that can be thrown by a + to indicate to the Quartz that an error + occurred while executing, and whether or not the requests + to be re-fired immediately (using the same , + or whether it wants to be unscheduled. + + + Note that if the flag for 'refire immediately' is set, the flags for + unscheduling the Job are ignored. + + + + + James House + Marko Lahma (.NET) + + + + Create a JobExcecutionException, with the 're-fire immediately' flag set + to . + + + + + Create a JobExcecutionException, with the given cause. + + The cause. + + + + Create a JobExcecutionException, with the given message. + + + + + Initializes a new instance of the class. + + The message. + The original cause. + + + + Create a JobExcecutionException with the 're-fire immediately' flag set + to the given value. + + + + + Create a JobExcecutionException with the given underlying exception, and + the 're-fire immediately' flag set to the given value. + + + + + Create a JobExcecutionException with the given message, and underlying + exception, and the 're-fire immediately' flag set to the given value. + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + Creates and returns a string representation of the current exception. + + + A string representation of the current exception. + + + + + + Gets or sets a value indicating whether to unschedule firing trigger. + + + true if firing trigger should be unscheduled; otherwise, false. + + + + + Gets or sets a value indicating whether to unschedule all triggers. + + + true if all triggers should be unscheduled; otherwise, false. + + + + + Gets or sets a value indicating whether to refire immediately. + + true if to refire immediately; otherwise, false. + + + + Uniquely identifies a . + + + Keys are composed of both a name and group, and the name must be unique + within the group. If only a group is specified then the default group + name will be used. + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + Client code can then use the DSL to write code such as this: + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + ITrigger trigger = TriggerBuilder.Create() + .WithIdentity("myTrigger", "myTriggerGroup") + .WithSimpleSchedule(x => x + .WithIntervalInHours(1) + .RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + Misfire instructions. + + Marko Lahma (.NET) + + + + Instruction not set (yet). + + + + + Use smart policy. + + + + + Instructs the that the + will never be evaluated for a misfire situation, + and that the scheduler will simply try to fire it as soon as it can, + and then update the Trigger as if it had fired at the proper time. + + + NOTE: if a trigger uses this instruction, and it has missed + several of its scheduled firings, then several rapid firings may occur + as the trigger attempt to catch back up to where it would have been. + For example, a SimpleTrigger that fires every 15 seconds which has + misfired for 5 minutes will fire 20 times once it gets the chance to + fire. + + + + + Misfire policy settings for SimpleTrigger. + + + + + Instructs the that upon a mis-fire + situation, the wants to be fired + now by . + + NOTE: This instruction should typically only be used for + 'one-shot' (non-repeating) Triggers. If it is used on a trigger with a + repeat count > 0 then it is equivalent to the instruction + . + + + + + + Instructs the that upon a mis-fire + situation, the wants to be + re-scheduled to 'now' (even if the associated + excludes 'now') with the repeat count left as-is. This does obey the + end-time however, so if 'now' is after the + end-time the will not fire again. + + + + NOTE: Use of this instruction causes the trigger to 'forget' + the start-time and repeat-count that it was originally setup with (this + is only an issue if you for some reason wanted to be able to tell what + the original values were at some later time). + + + + + + Instructs the that upon a mis-fire + situation, the wants to be + re-scheduled to 'now' (even if the associated + excludes 'now') with the repeat count set to what it would be, if it had + not missed any firings. This does obey the end-time + however, so if 'now' is after the end-time the will + not fire again. + + + NOTE: Use of this instruction causes the trigger to 'forget' + the start-time and repeat-count that it was originally setup with. + Instead, the repeat count on the trigger will be changed to whatever + the remaining repeat count is (this is only an issue if you for some + reason wanted to be able to tell what the original values were at some + later time). + + + + NOTE: This instruction could cause the + to go to the 'COMPLETE' state after firing 'now', if all the + repeat-fire-times where missed. + + + + + + Instructs the that upon a mis-fire + situation, the wants to be + re-scheduled to the next scheduled time after 'now' - taking into + account any associated , and with the + repeat count set to what it would be, if it had not missed any firings. + + + NOTE/WARNING: This instruction could cause the + to go directly to the 'COMPLETE' state if all fire-times where missed. + + + + + Instructs the that upon a mis-fire + situation, the wants to be + re-scheduled to the next scheduled time after 'now' - taking into + account any associated , and with the + repeat count left unchanged. + + + + NOTE/WARNING: This instruction could cause the + to go directly to the 'COMPLETE' state if all the end-time of the trigger + has arrived. + + + + + + misfire instructions for CronTrigger + + + + + Instructs the that upon a mis-fire + situation, the wants to be fired now + by . + + + + + Instructs the that upon a mis-fire + situation, the wants to have it's + next-fire-time updated to the next time in the schedule after the + current time (taking into account any associated , + but it does not want to be fired now. + + + + + misfire instructions for NthIncludedDayTrigger + + + + + Instructs the that upon a mis-fire situation, the + wants to be fired now by the + + + + + + Instructs the that upon a mis-fire situation, the + wants to have + nextFireTime updated to the next time in the schedule after + the current time, but it does not want to be fired now. + + + + + Misfire instructions for DateIntervalTrigger + + + + + Instructs the that upon a mis-fire + situation, the wants to be + fired now by . + + + + + Instructs the that upon a mis-fire + situation, the wants to have it's + next-fire-time updated to the next time in the schedule after the + current time (taking into account any associated , + but it does not want to be fired now. + + + + + Misfire instructions for DailyTimeIntervalTrigger + + + + + Instructs the that upon a mis-fire + situation, the wants to be + fired now by . + + + + + Instructs the that upon a mis-fire + situation, the wants to have it's + next-fire-time updated to the next time in the schedule after the + current time (taking into account any associated , + but it does not want to be fired now. + + + + + A trigger which fires on the Nth day of every interval type + , or + that is not excluded by the associated + calendar. + + + When determining what the Nth day of the month or year + is, will skip excluded days on the + associated calendar. This would commonly be used in an Nth + business day situation, in which the user wishes to fire a particular job on + the Nth business day (i.e. the 5th business day of + every month). Each also has an associated + which indicates at what time of day the trigger is + to fire. + + All s default to a monthly interval type + (fires on the Nth day of every month) with N = 1 (first + non-excluded day) and set to 12:00 PM (noon). These + values can be changed using the , , and + methods. Users may also want to note the + and + methods. + + + Take, for example, the following calendar: + + + July August September + Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa + 1 W 1 2 3 4 5 W 1 2 W + W H 5 6 7 8 W W 8 9 10 11 12 W W H 6 7 8 9 W + W 11 12 13 14 15 W W 15 16 17 18 19 W W 12 13 14 15 16 W + W 18 19 20 21 22 W W 22 23 24 25 26 W W 19 20 21 22 23 W + W 25 26 27 28 29 W W 29 30 31 W 26 27 28 29 30 + W + + Where W's represent weekend days, and H's represent holidays, all of which + are excluded on a calendar associated with an + with n=5 and + intervalType=IntervalTypeMonthly. In this case, the trigger + would fire on the 8th of July (because of the July 4 holiday), + the 5th of August, and the 8th of September (because + of Labor Day). + + Aaron Craven + Marko Lahma (.NET) + + + + Indicates a monthly trigger type (fires on the Nth included + day of every month). + + + + indicates a yearly trigger type (fires on the Nth included + day of every year). + + + + + Indicates a weekly trigger type (fires on the Nth included + day of every week). When using this interval type, care must be taken + not to think of the value of as an analog to + . Such a comparison can only + be drawn when there are no calendars associated with the trigger. To + illustrate, consider an with + n = 3 which is associated with a Calendar excluding + non-weekdays. The trigger would fire on the 3rd + included day of the week, which would be 4th + actual day of the week. + + + + + Create an with no specified name, + group, or . This will result initially in a + default monthly trigger that fires on the first day of every month at + 12:00 PM (n = 1, + intervalType=, + fireAtTime="12:00"). + + + Note that and , must be + called before the can be placed into + a . + + + + + Create an with the given name and + default group but no specified . This will result + initially in a default monthly trigger that fires on the first day of + every month at 12:00 PM (=1, + intervalType=, + fireAtTime=12:00"). + + Note that must + be called before the can be placed + into a . + + + the name for the + + + + + Create an with the given name and + group but no specified . This will result + initially in a default monthly trigger that fires on the first day of + every month at 12:00 PM (=1, + intervalType=, + fireAtTime=12:00"). + + Note that must + be called before the can be placed + into a . + + + the name for the + + the group for the + + + + + Create an with the given name and + group and the specified . This will result + initially in a default monthly trigger that fires on the first day of + every month at 12:00 PM (=1, + intervalType=, + fireAtTime="12:00"). + + The name for the . + The group for the . + The name of the job to associate with the . + The group containing the job to associate with the . + + + + Returns the next UTC time at which the + will fire. If the trigger will not fire again, will be + returned. + + + + Because of the conceptual design of , + it is not always possible to decide with certainty that the trigger + will never fire again. Therefore, it will search for the next + fire time up to a given cutoff. These cutoffs can be changed by using the + property. The default cutoff is 12 + of the intervals specified by intervalType. + + + The returned value is not guaranteed to be valid until after + the trigger has been added to the scheduler. + + + the next fire time for the trigger + + + + + Returns the previous UTC time at which the + fired. If the trigger has not yet + fired, will be returned. + + the previous fire time for the trigger + + + + Returns the first time the will fire + after the specified date. + + + + Because of the conceptual design of , + it is not always possible to decide with certainty that the trigger + will never fire again. Therefore, it will search for the next + fire time up to a given cutoff. These cutoffs can be changed by using the + property. The default cutoff is 12 + of the intervals specified by intervalType. + + + Therefore, for triggers with intervalType = + , if the trigger + will not fire within 12 + weeks after the given date/time, will be returned. For + triggers with intervalType = + + , if the trigger will not fire within 12 + months after the given date/time, will be returned. + For triggers with intervalType = + + , if the trigger will not fire within 12 + years after the given date/time, will be returned. In + all cases, if the trigger will not fire before , + will be returned. + + + The time after which to find the nearest fire time. + This argument is treated as exclusive 舒 that is, + if afterTime is a valid fire time for the trigger, it + will not be returned as the next fire time. + + + the first time the trigger will fire following the specified date + + + + + Called when the has decided to 'fire' the trigger + (Execute the associated ), in order to give the + a chance to update itself for its next triggering + (if any). + + + + + Called by the scheduler at the time a is first + added to the scheduler, in order to have the + compute its first fire time, based on any associated calendar. + + After this method has been called, + should return a valid answer. + + + + the first time at which the will be fired + by the scheduler, which is also the same value + will return (until after the first + firing of the ). + + + + + Called after the has executed the + associated with the in order + to get the final instruction code from the trigger. + + + The that was used by the + 's method. + + + The thrown by the + , if any (may be ) + + one of the Trigger.INSTRUCTION_XXX constants. + + + + + Used by the to determine whether or not it is + possible for this to fire again. + ' + + + If the returned value is then the + may remove the from the + + + + + A boolean indicator of whether the trigger could potentially fire + again. + + + + + Indicates whether is a valid misfire + instruction for this . + + Whether is valid. + + + Updates the 's state based on the + MisfireInstruction that was selected when the + was created +

+ If the misfire instruction is set to MISFIRE_INSTRUCTION_SMART_POLICY, + then the instruction will be interpreted as + . +

+ + a new or updated calendar to use for the trigger + + + + + Updates the 's state based on the + given new version of the associated . + + A new or updated calendar to use for the trigger + the amount of time that must + be between "now" and the time the next + firing of the trigger is supposed to occur. + + + + + Calculates the first time an with + intervalType = IntervalTypeWeekly will fire + after the specified date. See for more + information. + + The time after which to find the nearest fire time. + This argument is treated as exclusive 舒 that is, + if afterTime is a valid fire time for the trigger, it + will not be returned as the next fire time. + + the first time the trigger will fire following the specified + date + + + + + Calculates the first UTC time an with + intervalType = will fire + after the specified date. See for more + information. + + + The UTC time after which to find the nearest fire time. + This argument is treated as exclusive 舒 that is, + if afterTime is a valid fire time for the trigger, it + will not be returned as the next fire time. + + the first time the trigger will fire following the specified date + + + + Calculates the first time an with + intervalType = will fire + after the specified date. See for more + information. + + + The UTC time after which to find the nearest fire time. + This argument is treated as exclusive 舒 that is, + if afterTime is a valid fire time for the trigger, it + will not be returned as the next fire time. + + the first time the trigger will fire following the specified + date + + + + + Get a that is configured to produce a + schedule identical to this trigger's schedule. + + + + + + + Gets or sets the day of the interval on which the + should fire. If the Nth + day of the interval does not exist (i.e. the 32nd of a + month), the trigger simply will never fire. N may not be less than 1. + + + + + Returns the interval type for the . + + + Sets the interval type for the . If + , the trigger will fire on the + Nth included day of every month. If + , the trigger will fire on the + Nth included day of every year. If + , the trigger will fire on the + Nth included day of every week. + + + + + + + + Returns the fire time for the as a + string with the format "HH:MM[:SS]", with HH representing the + 24-hour clock hour of the fire time. Seconds are optional and their + inclusion depends on whether or not they were provided to + . + + + + + Returns the for the + . + + + + Because of the conceptual design of , + it is not always possible to decide with certainty that the trigger + will never fire again. Therefore, it will search for the next + fire time up to a given cutoff. These cutoffs can be changed by using the + property. The default cutoff is 12 + of the intervals specified by intervalType" />. + + + Because of the conceptual design of , + it is not always possible to decide with certainty that the trigger + will never fire again. Therefore, it will search for the next + fire time up to a given cutoff. These cutoffs can be changed by using the + method. The default cutoff is 12 + of the intervals specified by intervalType". + + + In most cases, the default value of this setting (12) is sufficient (it + is highly unlikely, for example, that you will need to look at more than + 12 months of dates to ensure that your trigger will never fire again). + However, this setting is included to allow for the rare exceptions where + this might not be true. + + + For example, if your trigger is associated with a calendar that excludes + a great many dates in the next 12 months, and hardly any following that, + it is possible (if is large enough) that you could run + into this situation. + + + + + + Returns the last UTC time the will fire. + If the trigger will not fire at any point between + and , will be returned. + + the last time the trigger will fire. + + + + Tells whether this Trigger instance can handle events + in millisecond precision. + + + + + + Sets or gets the time zone in which the will be resolved. + If no time zone is provided, then the default time zone will be used. + + + + + + + Gets or sets the trigger's calendar week rule. + + The trigger calendar week rule. + + + + Gets or sets the trigger's calendar first day of week rule. + + The trigger calendar first day of week. + + + + An exception that is thrown to indicate that an attempt to store a new + object (i.e. , + or ) in a + failed, because one with the same name and group already exists. + + James House + Marko Lahma (.NET) + + + + Create a with the given + message. + + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + Create a and auto-generate a + message using the name/group from the given . + + + + The message will read:
"Unable to store Job with name: '__' and + group: '__', because one already exists with this identification." + + + + + + Create a and auto-generate a + message using the name/group from the given . + + + + The message will read:
"Unable to store Trigger with name: '__' and + group: '__', because one already exists with this identification." + + + + + + An attribute that marks a class as one that makes updates to its + during execution, and wishes the scheduler to re-store the + when execution completes. + + + + Jobs that are marked with this annotation should also seriously consider + using the attribute, to avoid data + storage race conditions with concurrently executing job instances. + + + This can be used in lieu of implementing the StatefulJob marker interface that + was used prior to Quartz 2.0 + + + + James House + Marko Lahma (.NET) + + + + An exception that is thrown to indicate that there is a misconfiguration of + the - or one of the components it + configures. + + James House + Marko Lahma (.NET) + + + + Create a with the given message. + + + + + Create a with the given message + and cause. + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + + Scheduler constants. + + Marko Lahma (.NET) + + + + A (possibly) useful constant that can be used for specifying the group + that and instances belong to. + + + + + A constant group name used internally by the + scheduler - clients should not use the value of this constant + ("RECOVERING_JOBS") for thename of a 's group. + + + + + A constant group name used internally by the + scheduler - clients should not use the value of this constant + ("FAILED_OVER_JOBS") for thename of a 's group. + + + + + A constant key that can be used to retrieve the + name of the original from a recovery trigger's + data map in the case of a job recovering after a failed scheduler + instance. + + + + + + A constant key that can be used to retrieve the + group of the original from a recovery trigger's + data map in the case of a job recovering after a failed scheduler + instance. + + + + + + A constant key that can be used to retrieve the + scheduled fire time of the original from a recovery + trigger's data map in the case of a job recovering after a failed scheduler + instance. + + + + + + Holds context/environment data that can be made available to Jobs as they + are executed. + + + Future versions of Quartz may make distinctions on how it propagates + data in between instances of proxies to a + single scheduler instance - i.e. if Quartz is being used via WCF of Remoting. + + + James House + Marko Lahma (.NET) + + + + Create an empty . + + + + + Create a with the given data. + + + + + Serialization constructor. + + + + + + + Instructs Scheduler what to do with a trigger and job. + + Marko Lahma (.NET) + + + + Instructs the that the + has no further instructions. + + + + + Instructs the that the + wants the to re-Execute + immediately. If not in a 'RECOVERING' or 'FAILED_OVER' situation, the + execution context will be re-used (giving the the + ability to 'see' anything placed in the context by its last execution). + + + + + Instructs the that the + should be put in the state. + + + + + Instructs the that the + wants itself deleted. + + + + + Instructs the that all + s referencing the same as + this one should be put in the state. + + + + + Instructs the that all + s referencing the same as + this one should be put in the state. + + + + + Instructs the that the + should be put in the state. + + + + + Describes the settings and capabilities of a given + instance. + + James House + Marko Lahma (.NET) + + + + Initializes a new instance of the class. + + Name of the scheduler. + The scheduler instance. + The scheduler type. + if set to true, scheduler is a remote scheduler. + if set to true, scheduler is started. + if set to true, scheduler is in standby mode. + if set to true, scheduler is shutdown. + The start time. + The number of jobs executed. + The job store type. + if set to true, job store is persistent. + if set to true, the job store is clustered + The thread pool type. + Size of the thread pool. + The version string. + + + + Returns a formatted (human readable) string describing all the 's + meta-data values. + + + + The format of the string looks something like this: + 
+            Quartz Scheduler 'SchedulerName' with instanceId 'SchedulerInstanceId' Scheduler class: 'Quartz.Impl.StdScheduler' - running locally. Running since: '11:33am on Jul 19, 2002' Not currently paused. Number of Triggers fired: '123' Using thread pool 'Quartz.Simpl.SimpleThreadPool' - with '8' threads Using job-store 'Quartz.Impl.JobStore' - which supports persistence.
+
+ + + + + + Return a simple string representation of this object. + + + + + Returns the name of the . + + + + + Returns the instance Id of the . + + + + + Returns the class-name of the instance. + + + + + Returns whether the is being used remotely (via remoting). + + + + + Returns whether the scheduler has been started. + + + Note: may return even if + returns . + + + + + Reports whether the is in standby mode. + + + Note: may return even if + returns . + + + + + Reports whether the has been Shutdown. + + + + + Returns the class-name of the instance that is + being used by the . + + + + + Returns the type name of the instance that is + being used by the . + + + + + Returns the number of threads currently in the 's + + + + + Returns the version of Quartz that is running. + + + + + Returns the at which the Scheduler started running. + + null if the scheduler has not been started. + + + + + Returns the number of jobs executed since the + started.. + + + + + Returns whether or not the 's + instance supports persistence. + + + + + Returns whether or not the 's + is clustered. + + + + + SimpleScheduleBuilder is a + that defines strict/literal interval-based schedules for + s. + + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + Client code can then use the DSL to write code such as this: + + JobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + Trigger trigger = TriggerBuilder.Create() + .WithIdentity(triggerKey("myTrigger", "myTriggerGroup")) + .WithSimpleSchedule(x => x + .WithIntervalInHours(1) + .RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + + + + Create a SimpleScheduleBuilder. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat forever with a 1 minute interval. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat forever with an interval + of the given number of minutes. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat forever with a 1 second interval. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat forever with an interval + of the given number of seconds. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat forever with a 1 hour interval. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat forever with an interval + of the given number of hours. + + + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat the given number + of times - 1 with a 1 minute interval. + + + Note: Total count = 1 (at start time) + repeat count + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat the given number + of times - 1 with an interval of the given number of minutes. + + + Note: Total count = 1 (at start time) + repeat count + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat the given number + of times - 1 with a 1 second interval. + + + Note: Total count = 1 (at start time) + repeat count + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat the given number + of times - 1 with an interval of the given number of seconds. + + + Note: Total count = 1 (at start time) + repeat count + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat the given number + of times - 1 with a 1 hour interval. + + + Note: Total count = 1 (at start time) + repeat count + + the new SimpleScheduleBuilder + + + + Create a SimpleScheduleBuilder set to repeat the given number + of times - 1 with an interval of the given number of hours. + + + Note: Total count = 1 (at start time) + repeat count + + the new SimpleScheduleBuilder + + + + Build the actual Trigger -- NOT intended to be invoked by end users, + but will rather be invoked by a TriggerBuilder which this + ScheduleBuilder is given to. + + + + + + + + Specify a repeat interval in milliseconds. + + + + the time span at which the trigger should repeat. + the updated SimpleScheduleBuilder + + + + + + Specify a repeat interval in seconds. + + + + the time span at which the trigger should repeat. + the updated SimpleScheduleBuilder + + + + + + Specify a the number of time the trigger will repeat - total number of + firings will be this number + 1. + + + + the number of seconds at which the trigger should repeat. + the updated SimpleScheduleBuilder + + + + + + Specify that the trigger will repeat indefinitely. + + + + the updated SimpleScheduleBuilder + + + + + + + If the Trigger misfires, use the + instruction. + + + + the updated CronScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated SimpleScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated SimpleScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated SimpleScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated SimpleScheduleBuilder + + + + + If the Trigger misfires, use the + instruction. + + + + the updated SimpleScheduleBuilder + + + + + Extension methods that attach to . + + + + + A time source for Quartz.NET that returns the current time. + Original idea by Ayende Rahien: + http://ayende.com/Blog/archive/2008/07/07/Dealing-with-time-in-tests.aspx + + + + + Return current UTC time via . Allows easier unit testing. + + + + + Return current time in current time zone via . Allows easier unit testing. + + + + + Represents a time in hour, minute and second of any given day. + + + The hour is in 24-hour convention, meaning values are from 0 to 23. + + + + + James House + Zemian Deng saltnlight5@gmail.com + Nuno Maia (.NET) + + + + Create a TimeOfDay instance for the given hour, minute and second. + + The hour of day, between 0 and 23. + The minute of the hour, between 0 and 59. + The second of the minute, between 0 and 59. + + + + Create a TimeOfDay instance for the given hour, minute (at the zero second of the minute). + + The hour of day, between 0 and 23. + The minute of the hour, between 0 and 59. + + + + Create a TimeOfDay instance for the given hour, minute and second. + + The hour of day, between 0 and 23. + The minute of the hour, between 0 and 59. + The second of the minute, between 0 and 59. + + + + + Create a TimeOfDay instance for the given hour, minute (at the zero second of the minute).. + + The hour of day, between 0 and 23. + The minute of the hour, between 0 and 59. + The newly instantiated TimeOfDay + + + + Determine with this time of day is before the given time of day. + + + True this time of day is before the given time of day. + + + + Return a date with time of day reset to this object values. The millisecond value will be zero. + + + + + + The hour of the day (between 0 and 23). + + + + + The minute of the hour (between 0 and 59). + + + + + The second of the minute (between 0 and 59). + + + + + Attribute to use with public properties that + can be set with Quartz configuration. Attribute can be used to advice + parsing to use correct type of time span (milliseconds, seconds, minutes, hours) + as it may depend on property. + + Marko Lahma (.NET) + + + + + Initializes a new instance of the class. + + The rule. + + + + Gets the rule. + + The rule. + + + + Possible parse rules for s. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TriggerBuilder is used to instantiate s. + + + + The builder will always try to keep itself in a valid state, with + reasonable defaults set for calling build() at any point. For instance + if you do not invoke WithSchedule(..) method, a default schedule + of firing once immediately will be used. As another example, if you + do not invoked WithIdentity(..) a trigger name will be generated + for you. + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + + Client code can then use the DSL to write code such as this: + + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + ITrigger trigger = TriggerBuilder.Create() + .WithIdentity("myTrigger", "myTriggerGroup") + .WithSimpleSchedule(x => x + .WithIntervalInHours(1) + .RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + + + Create a new TriggerBuilder with which to define a + specification for a Trigger. + + + + the new TriggerBuilder + + + + Produce the . + + + + a Trigger that meets the specifications of the builder. + + + + Use a with the given name and default group to + identify the Trigger. + + + If none of the 'withIdentity' methods are set on the TriggerBuilder, + then a random, unique TriggerKey will be generated. + + the name element for the Trigger's TriggerKey + the updated TriggerBuilder + + + + + + Use a TriggerKey with the given name and group to + identify the Trigger. + + + If none of the 'withIdentity' methods are set on the TriggerBuilder, + then a random, unique TriggerKey will be generated. + + the name element for the Trigger's TriggerKey + the group element for the Trigger's TriggerKey + the updated TriggerBuilder + + + + + + Use the given TriggerKey to identify the Trigger. + + + If none of the 'withIdentity' methods are set on the TriggerBuilder, + then a random, unique TriggerKey will be generated. + + the TriggerKey for the Trigger to be built + the updated TriggerBuilder + + + + + + Set the given (human-meaningful) description of the Trigger. + + + + the description for the Trigger + the updated TriggerBuilder + + + + + Set the Trigger's priority. When more than one Trigger have the same + fire time, the scheduler will fire the one with the highest priority + first. + + + + the priority for the Trigger + the updated TriggerBuilder + + + + + + Set the name of the that should be applied to this + Trigger's schedule. + + + + the name of the Calendar to reference. + the updated TriggerBuilder + + + + + + Set the time the Trigger should start at - the trigger may or may + not fire at this time - depending upon the schedule configured for + the Trigger. However the Trigger will NOT fire before this time, + regardless of the Trigger's schedule. + + + + the start time for the Trigger. + the updated TriggerBuilder + + + + + + Set the time the Trigger should start at to the current moment - + the trigger may or may not fire at this time - depending upon the + schedule configured for the Trigger. + + + + the updated TriggerBuilder + + + + + Set the time at which the Trigger will no longer fire - even if it's + schedule has remaining repeats. + + + + the end time for the Trigger. If null, the end time is indefinite. + the updated TriggerBuilder + + + + + + Set the that will be used to define the + Trigger's schedule. + + + The particular used will dictate + the concrete type of Trigger that is produced by the TriggerBuilder. + + the SchedulerBuilder to use. + the updated TriggerBuilder + + + + + + + + Set the identity of the Job which should be fired by the produced + Trigger. + + + + the identity of the Job to fire. + the updated TriggerBuilder + + + + + Set the identity of the Job which should be fired by the produced + Trigger - a will be produced with the given + name and default group. + + + + the name of the job (in default group) to fire. + the updated TriggerBuilder + + + + + Set the identity of the Job which should be fired by the produced + Trigger - a will be produced with the given + name and group. + + + + the name of the job to fire. + the group of the job to fire. + the updated TriggerBuilder + + + + + Set the identity of the Job which should be fired by the produced + Trigger, by extracting the JobKey from the given job. + + + + the Job to fire. + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Add the given key-value pair to the Trigger's . + + + + the updated TriggerBuilder + + + + + Common constants for triggers. + + + + + The default value for priority. + + + + + Uniquely identifies a . + + + Keys are composed of both a name and group, and the name must be unique + within the group. If only a name is specified then the default group + name will be used. + + + Quartz provides a builder-style API for constructing scheduling-related + entities via a Domain-Specific Language (DSL). The DSL can best be + utilized through the usage of static imports of the methods on the classes + , , + , , + and the various implementations. + + + Client code can then use the DSL to write code such as this: + + + IJobDetail job = JobBuilder.Create<MyJob>() + .WithIdentity("myJob") + .Build(); + ITrigger trigger = TriggerBuilder.Create() + .WithIdentity("myTrigger", "myTriggerGroup") + .WithSimpleSchedule(x => x + .WithIntervalInHours(1) + .RepeatForever()) + .StartAt(DateBuilder.FutureDate(10, IntervalUnit.Minute)) + .Build(); + scheduler.scheduleJob(job, trigger); + + + + + + + + All trigger states known to Scheduler. + + Marko Lahma (.NET) + + + + Indicates that the is in the "normal" state. + + + + + Indicates that the is in the "paused" state. + + + + + Indicates that the is in the "complete" state. + + + "Complete" indicates that the trigger has not remaining fire-times in + its schedule. + + + + + Indicates that the is in the "error" state. + + + + A arrives at the error state when the scheduler + attempts to fire it, but cannot due to an error creating and executing + its related job. Often this is due to the 's + class not existing in the classpath. + + + + When the trigger is in the error state, the scheduler will make no + attempts to fire it. + + + + + + Indicates that the is in the "blocked" state. + + + A arrives at the blocked state when the job that + it is associated with has a and it is + currently executing. + + + + + + Indicates that the does not exist. + + + + + A Comparator that compares trigger's next fire times, or in other words, + sorts them according to earliest next fire time. If the fire times are + the same, then the triggers are sorted according to priority (highest + value first), if the priorities are the same, then they are sorted + by key. + + + + + Convenience and utility methods for simplifying the construction and + configuration of s and DateTimeOffsetOffsets. + + + + James House + Marko Lahma (.NET) + + + + Returns a list of Dates that are the next fire times of a + . + The input trigger will be cloned before any work is done, so you need + not worry about its state being altered by this method. + + The trigger upon which to do the work + The calendar to apply to the trigger's schedule + The number of next fire times to produce + List of java.util.Date objects + + + + Compute the that is 1 second after the Nth firing of + the given , taking the triger's associated + into consideration. + + + The input trigger will be cloned before any work is done, so you need + not worry about its state being altered by this method. + + The trigger upon which to do the work + The calendar to apply to the trigger's schedule + The number of next fire times to produce + the computed Date, or null if the trigger (as configured) will not fire that many times + + + + Returns a list of Dates that are the next fire times of a + that fall within the given date range. The input trigger will be cloned + before any work is done, so you need not worry about its state being + altered by this method. + + NOTE: if this is a trigger that has previously fired within the given + date range, then firings which have already occurred will not be listed + in the output List. + + + The trigger upon which to do the work + The calendar to apply to the trigger's schedule + The starting date at which to find fire times + The ending date at which to stop finding fire times + List of java.util.Date objects + + + + An exception that is thrown to indicate that a call to + failed without interrupting the Job. + + + James House + Marko Lahma (.NET) + + + + Create a with the given message. + + + + + Create a with the given cause. + + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The class name is null or is zero (0). + The info parameter is null. + + + diff --git a/Resources/Libraries/SharpSSH/DiffieHellman.dll b/Resources/Libraries/SharpSSH/DiffieHellman.dll new file mode 100644 index 00000000..aa310511 Binary files /dev/null and b/Resources/Libraries/SharpSSH/DiffieHellman.dll differ diff --git a/Resources/Libraries/SharpSSH/Org.Mentalis.Security.dll b/Resources/Libraries/SharpSSH/Org.Mentalis.Security.dll new file mode 100644 index 00000000..bac39dd9 Binary files /dev/null and b/Resources/Libraries/SharpSSH/Org.Mentalis.Security.dll differ diff --git a/Resources/Libraries/SharpSSH/Tamir.SharpSSH.dll b/Resources/Libraries/SharpSSH/Tamir.SharpSSH.dll new file mode 100644 index 00000000..c2f67a82 Binary files /dev/null and b/Resources/Libraries/SharpSSH/Tamir.SharpSSH.dll differ diff --git a/Resources/Libraries/Spring.NET/Common.Logging.dll b/Resources/Libraries/Spring.NET/Common.Logging.dll new file mode 100644 index 00000000..d7a8f158 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Common.Logging.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Aop.dll b/Resources/Libraries/Spring.NET/Spring.Aop.dll new file mode 100644 index 00000000..1383c08b Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Aop.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Aop.pdb b/Resources/Libraries/Spring.NET/Spring.Aop.pdb new file mode 100644 index 00000000..47cbe661 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Aop.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Aop.xml b/Resources/Libraries/Spring.NET/Spring.Aop.xml new file mode 100644 index 00000000..e2d4986c --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Aop.xml @@ -0,0 +1,11751 @@ + + + + Spring.Aop + + + + + Namespace parser for the aop namespace. + + + Using the advisor tag you can configure an and have it + applied to all the relevant objects in your application context automatically. The + advisor tag supports only referenced s. + + Rob harrop + Adrian Colyer + Rod Johnson + Mark Pollack (.NET) + + + + Register the for the 'config' tag. + + + + + Utility class for handling registration of auto-proxy creators used internally by the + aop and tx namespace tags. + + Rob Harrop + Juergen Hoeller + Mark Pollack (.NET) + Erich Eichinger (.NET) + + + + The object name of the internally managed auto-proxy creator. + + + + + The type of the APC that handles advisors with object role . + + + + + Registers the internal auto proxy creator if necessary. + + The parser context. + The source element. + + + + Registers the internal auto proxy creator if necessary. + + + + + Forces the auto proxy creator to use decorator proxy. + + The registry. + + + + The for the <aop:config> tag. + + Mark Pollack (.NET) + + + + The 'proxy-target-type' attribute + + + + + Parse the specified XmlElement and register the resulting + ObjectDefinitions with the IObjectDefinitionRegistry + embedded in the supplied + + The element to be parsed. + The object encapsulating the current state of the parsing process. + Provides access to a IObjectDefinitionRegistry + The primary object definition. + +

+ This method is never invoked if the parser is namespace aware + and was called to process the root node. +

+ + + + + Parses the supplied advisor element and registers the resulting + + The advisor element. + The parser context. + + + + implementation + that registers instances of any non-default + instances with the + + singleton. + + +

+ The only requirement for it to work is that it needs to be defined + in an application context along with any arbitrary "non-native" Spring.NET + instances that need + to be recognized by Spring.NET's AOP framework. +

+ + Dmitriy Kopylenko + Aleksandar Seovic (.NET) + + + + Apply this + to the given new object instance before any object initialization callbacks. + + +

+ Does nothing, simply returns the supplied as is. +

+ + + The new object instance. + + + The name of the object. + + + The object instance to use, either the original or a wrapped one. + + + In case of errors. + + + + + Apply this to the + given new object instance after any object initialization callbacks. + + +

+ Registers the supplied with the + + singleton if it is an + instance. +

+ + + The new object instance. + + + The name of the object. + + + The object instance to use, either the original or a wrapped one. + + + In case of errors. + + + + + implementation + to enable to be used in the + Spring.NET AOP framework. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Permits the handling of new advisors and advice types as extensions to + the Spring AOP framework. + + +

+ Implementors can create AOP Alliance + s from custom advice + types, enabling these advice types to be used in the Spring.NET AOP + framework, which uses interception under the covers. +

+

+ There is no need for most Spring.NET users to implement this interface; + do so only if you need to introduce more + or + types to Spring.NET. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Does this adapter understand the supplied ? + + +

+ Is it valid to invoke the + + method with the given advice as an argument? +

+ + + such as + . + + if this adapter understands the + supplied . + + + + + Return an AOP Alliance + exposing the + behaviour of the given advice to an interception-based AOP + framework. + + +

+ Don't worry about any + contained in the supplied ; + the AOP framework will take care of checking the pointcut. +

+ + + The advice. The + + method must have previously returned on the + supplied . + + + An AOP Alliance + exposing the + behaviour of the given advice to an interception-based AOP + framework. + + + + + Returns if the supplied + is an instance of the + interface. + + The advice to check. + + if the supplied is + an instance of the interface; + if not or if the supplied + is . + + + + + Wraps the supplied 's + within a + + instance. + + + The advisor exposing the that + is to be wrapped. + + + The supplied 's + wrapped within a + + instance. + + + + + Interceptor to wrap an + instance. + + +

+ A more efficient alternative solution in cases where there is no + interception advice and therefore no need to create an + object may be + offered in future. +

+

+ Used internally by the AOP framework: application developers should not need + to use this class directly. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Intercepts calls on an interface on its way to the target. + + +

+ Such interceptions are nested "on top" of the target. +

+ + + + + Represents a generic interceptor. + + +

+ A generic interceptor can intercept runtime events that occur within a + base program. Those events are materialized by (reified in) joinpoints. + Runtime joinpoints can be invocations, field access, exceptions, etc. +

+

+ This interface is not used directly. Use the various derived interfaces + to intercept specific events. +

+ + + + + + Tag interface for advice. + + +

+ Implementations can be any type of advice, such as interceptors. +

+ + + + + Implement this method to perform extra treatments before and after + the call to the supplied . + + +

+ Polite implementations would certainly like to invoke + . +

+ + + The method invocation that is being intercepted. + + + The result of the call to the + method of + the supplied ; this return value may + well have been intercepted by the interceptor. + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + Creates a new instance of the + + class. + + + The advice to be applied after a target method successfully + returns. + + + If the supplied is . + + + + + Executes interceptor after the target method successfully returns. + + + The method invocation that is being intercepted. + + + The result of the call to the + method of + the supplied ; this return value may + well have been intercepted by the interceptor. + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + implementation + to enable to be used in the + Spring.NET AOP framework. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Returns if the supplied + is an instance of the + interface. + + The advice to check. + + if the supplied is + an instance of the interface; + if not or if the supplied + is . + + + + + Wraps the supplied 's + within a + + instance. + + + The advisor exposing the that + is to be wrapped. + + + The supplied 's + wrapped within a + + instance. + + + + + Default implementation of the + + interface. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + A registry of + instances. + + +

+ Implementations must also automatically register adapters for + types. +

+ + This is an SPI interface, that should not need to be implemented by any + Spring.NET user. + + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Returns an wrapping the supplied + . + + + The object that should be an advice, such as + or + . + + + An wrapping the supplied + . Never returns . If + the parameter is an + , it will simply be returned. + + + If no registered + can wrap + the supplied . + + + + + Returns an to + allow the use of the supplied in an + interception-based framework. + + +

+ Don't worry about the pointcut associated with the + ; if it's an + , just return an + interceptor. +

+ + + The advisor to find an interceptor for. + + + An interceptor to expose this advisor's behaviour. + + + If the advisor type is not understood by any registered + . + + + + + Register the given . + + +

+ Note that it is not necessary to register adapters for + instances: these + must be automatically recognized by an + + implementation. +

+ + + An that + understands the particular advisor and advice types. + + + + + Creates a new instance of the + class. + + +

+ This constructor will also register the well-known + types. +

+ + + + + + Returns an wrapping the supplied + . + + + The object that should be an advice, such as + or + . + + + An wrapping the supplied + . Never returns . If + the parameter is an + , it will simply be returned. + + + If no registered + can wrap + the supplied . + + + + + Returns an to + allow the use of the supplied in an + interception-based framework. + + The advisor to find an interceptor for. + + An interceptor to expose this advisor's behaviour. + + + If the advisor type is not understood by any registered + . + + + + + Register the given . + + + An that + understands the particular advisor and advice types. + + + + + Provides Singleton-style access to the default + instance. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + class. + + +

+ This contructor is marked as to enforce the + Singleton pattern +

+ + + + + The default instance. + + + + + implementation that + wraps instances. + + +

+ In the future Spring.NET may also offer a more efficient alternative + solution in cases where there is no interception advice and therefore + no need to create an + object. +

+

+ Used internally by the Spring.NET AOP framework: application developers + should not need to use this class directly. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + + class. + + + The that is to be wrapped. + + + If the supplied is . + + + + + Executes interceptor before the target method successfully returns. + + + The method invocation that is being intercepted. + + + The result of the call to the + method of + the supplied . + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + implementation + to enable to be used in the + Spring.NET AOP framework. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Returns if the supplied + is an instance of the + interface. + + The advice to check. + + if the supplied is + an instance of the interface; + if not or if the supplied + is . + + + + + Wraps the supplied 's + within a + + instance. + + + The advisor exposing the that + is to be wrapped. + + + The supplied 's + wrapped within a + + instance. + + + + Interceptor to wrap an after throwing advice. + +

+ Implementations of the interface + must define methods of the form... + + AfterThrowing([MethodInfo method, Object[] args, Object target], Exception subclass); + + The method name is fixed (i.e. your methods must be named + AfterThrowing. The first three arguments (as a whole) are + optional, and only useful if futher information about the joinpoint is + required. The return type can be anything, but is almost always + by convention. +

+

+ Please note that the object encapsulating the throws advice does not + need to implement the interface. + Throws advice methods are discovered via reflection... the + interface serves merely to + discover objects that are to be considered as throws advice. + Other mechanisms for discovering throws advice such as attributes are + also equally valid... all that this class cares about is that a throws + advice object implement one or more methods with a valid throws advice + signature (see above, and the examples below). +

+

+ This is a framework class that should not normally need to be used + directly by Spring.NET users. +

+ + +

+ Find below some examples of valid + method signatures... +

+ + public class GlobalExceptionHandlingAdvice : IThrowsAdvice + { + public void AfterThrowing(Exception ex) { + // handles absolutely any and every Exception... + } + } + + + public class RemotingExceptionHandlingAdvice : IThrowsAdvice + { + public void AfterThrowing(RemotingException ex) { + // handles any and every RemotingException (and subclasses of RemotingException)... + } + } + + + using System.Data; + + public class DataExceptionHandlingAdvice + { + public void AfterThrowing(ConstraintException ex) { + // specialised handling of ConstraintExceptions + } + + public void AfterThrowing(NoNullAllowedException ex) { + // specialised handling of NoNullAllowedExceptions + } + + public void AfterThrowing(DataException ex) { + // handles all other DataExceptions... + } + } + + + Rod Johnson + Aleksandar Seovic (.NET) + + + + + The mapping of exception Types to MethodInfo handlers. + + + + + Creates a new instance of the + class. + + + + + The throws advice to check for exception handler methods. + + + If the supplied is . + + + If no (0) handler methods were discovered on the supplied ; + or if more than one handler method suitable for a particular + type was discovered on the supplied + . + + + + + Executes interceptor if (and only if) the supplied + throws an exception that is mapped to + an appropriate exception handler. + + + The method invocation that is being intercepted. + + + The result of the call to the + method of + the supplied (this assumes no + exception was thrown by the call to the supplied . + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + + Gets the exception handler (if any) that has been mapped to the + supplied . + + +

+ Will return if not found. +

+ + + The exception handler for the of the + supplied given exception. + + exception that was thrown + + + + Invokes handler method with appropriate number of parameters + + + The original method invocation that was intercepted. + + + The exception that triggered this interceptor. + + + The exception handler method to invoke. + + + + + Convenience property that returns the number of exception handler + methods managed by this interceptor. + + + The number of exception handler methods managed by this interceptor. + + + + + Exception thrown when an attempt is made to use an unsupported + or + type. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + class. + + The advice that caused the exception. + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class with + the specified message. + + + A message about the exception. + + + + + Creates a new instance of the + class with + the specified message and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Summary description for AbstractPrototypeBasedTargetSourceCreator. + + + + + Implementations can create special target sources, such as pooling target + sources, for particular objects. For example, they may base their choice + on attributes, such as a pooling attribute, on the target type. + +

AbstractAutoProxyCreator can support a number of TargetSourceCreators, + which will be applied in order.

+ + Rod Johnson + Adhari C Mahendra (.NET) + + + + Create a special TargetSource for the given object, if any. + + The type of the object to create a TargetSource for + the name of the object + the containing factory + a special TargetSource or null if this TargetSourceCreator isn't + interested in the particular object + + + + The logger + + + + + Create a special TargetSource for the given object, if any. + + the type of the object to create a TargetSource for + the name of the object + the containing factory + + a special TargetSource or null if this TargetSourceCreator isn't + interested in the particular object + + + + + Creates the prototype target source. + + The type of the object to create a target source for. + The name. + The factory. + + + + + Abstract IObjectPostProcessor implementation that creates AOP proxies. + This class is completely generic; it contains no special code to handle + any particular aspects, such as pooling aspects. + + +

Subclasses must implement the abstract FindCandidateAdvisors() method + to return a list of Advisors applying to any object. Subclasses can also + override the inherited ShouldSkip() method to exclude certain objects + from autoproxying, but they must be careful to invoke the ShouldSkip() + method of this class, which tries to avoid circular reference problems + and infinite loops.

+

Advisors or advices requiring ordering should implement the Ordered interface. + This class sorts advisors by Ordered order value. Advisors that don't implement + the Ordered interface will be considered to be unordered, and will appear + at the end of the advisor chain in undefined order.

+ + + Rod Johnson + Adhari C Mahendra (.NET) + Erich Eichinger + + + + ObjectPostProcessor implementation that wraps a group of objects with AOP proxies + that delegate to the given interceptors before invoking the object itself. + + +

This class distinguishes between "common" interceptors: shared for all proxies it + creates, and "specific" interceptors: unique per object instance. There need not + be any common interceptors. If there are, they are set using the interceptorNames + property. As with ProxyFactoryObject, interceptors names in the current factory + are used rather than object references to allow correct handling of prototype + advisors and interceptors: for example, to support stateful mixins. + Any advice type is supported for "interceptorNames" entries.

+

Such autoproxying is particularly useful if there's a large number of objects that need + to be wrapped with similar proxies, i.e. delegating to the same interceptors. + Instead of x repetitive proxy definitions for x target objects, you can register + one single such post processor with the object factory to achieve the same effect.

+

Subclasses can apply any strategy to decide if a object is to be proxied, + e.g. by type, by name, by definition details, etc. They can also return + additional interceptors that should just be applied to the specific object + instance. The default concrete implementation is ObjectNameAutoProxyCreator, + identifying the objects to be proxied via a list of object names.

+

Any number of TargetSourceCreator implementations can be used with any subclass, + to create a custom target source - for example, to pool prototype objects. + Autoproxying will occur even if there is no advice if a TargetSourceCreator specifies + a custom TargetSource. If there are no TargetSourceCreators set, or if none matches, + a SingletonTargetSource will be used by default to wrap the object to be autoproxied.

+ + Juergen Hoeller + Rod Johnson + Adhari C Mahendra (.NET) + + + + + + Convenience superclass for configuration used in creating proxies, + to ensure that all proxy creators have consistent properties. + + +

+ Note that it is no longer possible to configure subclasses to + expose the . + Interceptors should normally manage their own thread locals if they + need to make resources available to advised objects. If it is + absolutely necessary to expose the + , use an + interceptor to do so. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Copies the configuration from the supplied + into this instance. + + + The configuration to be copied. + + + If the supplied is + . + + + + + A that represents the current + configuration. + + + A that represents the current + configuration. + + + + + Use to synchronize access to this ProxyConfig instance + + + + + Is the target to be proxied in addition + to any interfaces declared on the proxied ? + + + + + Is target type attributes, method attributes, method's return type attributes + and method's parameter attributes to be proxied in addition + to any interfaces declared on the proxied ? + + + + + Are any agressive optimizations to be performed? + + +

+ The exact meaning of agressive optimizations will differ + between proxies, but there is usually some tradeoff. +

+

+ For example, optimization will usually mean that advice changes + won't take effect after a proxy has been created. For this reason, + optimization is disabled by default. An optimize value of + may be ignored if other settings preclude + optimization: for example, if the + property + is set to and such a value is not compatible + with the optimization. +

+

+ The default is . +

+ + + + + Should proxies obtained from this configuration expose + the AOP proxy to the + class? + + +

+ The default is , as enabling this property + may impair performance. +

+ + + + + Gets and set the factory to be used to create AOP proxies. + + +

+ This obviously allows one to customise the + implementation, + allowing different strategies to be dropped in without changing the + core framework. For example, an + implementation + could return an + using remoting proxies, Reflection.Emit or a code generation + strategy. +

+ + + + + Is this configuration frozen? + + +

+ The default is not frozen. +

+ + + + + The logger for this class hierarchy. + + + + + Convenience constant for subclasses: Return value for "do not proxy". + + + + + Convenience constant for subclasses: Return value for + "proxy without additional interceptors, just the common ones". + + + + + Default value is same as non-ordered + + + + + Default is global AdvisorAdapterRegistry + + + + + Indicates whether to mark the create proxy as immutable. + + + Setting this to true effectively disables modifying the generated + proxy's advisor configuration + + + + + Names of common interceptors. + We must use object name rather than object references + to handle prototype advisors/interceptors. + Default is the empty array: no common interceptors. + + + + + Set of object type + name strings, referring to all objects that this auto-proxy + creator created a custom TargetSource for. Used to detect own pre-built proxies + (from "PostProcessBeforeInstantiation") in the "PostProcessAfterInitialization" method. + + + + + Create a new instance of this AutoProxyCreator + + + + + Create a proxy with the configured interceptors if the object is + identified as one to proxy by the subclass. + + + + + No-op for before initialization. + + The obj. + The name. + + + + + Subclasses should override this method to return true if this + object should not be considered for autoproxying by this post processor. + Sometimes we need to be able to avoid this happening if it will lead to + a circular reference. This implementation returns false. + + the type of the object + the name of the object + if remarkable to skip + + + + Subclasses may choose to implement this: for example, + to change the interfaces exposed + + + ProxyFactory that will be used to create the proxy immediably after this method returns. + + + + + Determines whether the object is an infrastructure type, + IAdvisor, IAdvice, IAdvisors or AbstractAutoProxyCreator + + The object type to compare + The name of the object + + true if [is infrastructure type] [the specified obj]; otherwise, false. + + + + + Create a target source for object instances. Uses any + TargetSourceCreators if set. Returns null if no Custom TargetSource + should be used. + This implementation uses the customTargetSourceCreators property. + Subclasses can override this method to use a different mechanism. + + the type of the object to create a TargetSource for + the name of the object + a TargetSource for this object + + + + Return whether the given object is to be proxied, what additional + advices (e.g. AOP Alliance interceptors) and advisors to apply. + + +

The previous targetName of this method was "GetInterceptorAndAdvisorForObject". + It has been renamed in the course of general terminology clarification + in Spring 1.1. An AOP Alliance Interceptor is just a special form of + Advice, so the generic Advice term is preferred now.

+

The third parameter, customTargetSource, is new in Spring 1.1; + add it to existing implementations of this method.

+ + the new object instance + the name of the object + targetSource returned by TargetSource property: + may be ignored. Will be null unless a custom target source is in use. + an array of additional interceptors for the particular object; + or an empty array if no additional interceptors but just the common ones; + or null if no proxy at all, not even with the common interceptors. + + + + Create an AOP proxy for the given object. + + Type of the object. + The name of the object. + The set of interceptors that is specific to this + object (may be empty but not null) + The target source for the proxy, already pre-configured to access the object. + The AOP Proxy for the object. + + + + Obtain a new proxy factory instance to be used for proxying a particular object + + A proxy factory instance for proxying a particular object + + + + Determines the advisors for the given object, including the specific interceptors + as well as the common interceptor, all adapted to the Advisor interface. + + The name of the object. + The set of interceptors that is specific to this + object (may be empty, but not null) + The list of Advisors for the given object + + + + Build a cache key for the given object type and object name + + The object type. + The object name. + The cache key for the given type and name + + + + Create the proxy if have a custom TargetSource + + The object type + The object name + null if not creating a proxy, otherwise return the proxy. + + + + Default behavior, return true and continue processing. + + The object instance + The object name. + true + + + + Default behavior, return passed in PropertyValues + + The property values that the factory is about to apply (never null). + he relevant property infos for the target object (with ignored + dependency types - which the factory handles specifically - already filtered out) + The object instance created, but whose properties have not yet + been set. + Name of the object. + The passed in PropertyValues + + + + Sets the AdvisorAdapterRegistry to use. + + + Default is the global AdvisorAdapterRegistry. + + + + + Sets custom TargetSourceCreators to be applied in this order. + + + + If the list is empty, or they all return null, a SingletonTargetSource + will be created. + + + TargetSourceCreators can only be invoked if this post processor is used + in a IObjectFactory, and its ObjectFactoryAware callback is used. + + + + + + Sets the common interceptors, a list of , + and introduction object names. + + + + If this property isn't set, there will be zero common interceptors. + This is perfectly valid, if "specific" interceptors such as + matching Advisors are all we want. + + + + The list of , + and introduction object names. + + + + + + + Sets whether the common interceptors should be applied before + object-specific ones. + + + Default is true; else, object-specific interceptors will get applied first. + + + + + Set whether or not the proxy should be frozen, preventing advice + from being added to it once it is created. + + +

Overridden from the super class to prevent the proxy configuration + from being frozen before the proxy is created. The default is not frozen. +

+ + + + + Callback that supplies the owning factory to an object instance. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + In case of initialization errors. + + + + + Propery Order + + + Ordering which will apply to this class's implementation + of Ordered, used when applying multiple ObjectPostProcessors. + Default value is int.MaxValue, meaning that it's non-ordered. + + + + + Initialize + + + + + An new was set. Initialize this creator instance + according to the specified object factory. + + + + + + Create the for retrieving the list of + applicable advisor objects. The default implementation calls back into + thus it usually is sufficient to just + override . Override + only if you know what you are doing! + + + + + + + Return whether the given object is to be proxied, what additional + advices (e.g. AOP Alliance interceptors) and advisors to apply. + + +

The previous targetName of this method was "GetInterceptorAndAdvisorForObject". + It has been renamed in the course of general terminology clarification + in Spring 1.1. An AOP Alliance Interceptor is just a special form of + Advice, so the generic Advice term is preferred now.

+

The third parameter, customTargetSource, is new in Spring 1.1; + add it to existing implementations of this method.

+ + the type of the target object + the name of the target object + targetSource returned by TargetSource property: + may be ignored. Will be null unless a custom target source is in use. + + an array of additional interceptors for the particular object; + or an empty array if no additional interceptors but just the common ones; + or null if no proxy at all, not even with the common interceptors. + + + + + Find all eligible advices and for autoproxying this class. + + the type of the object to be advised + the name of the object to be advised + + the empty list, not null, if there are no pointcuts or interceptors. + The by-order sorted list of advisors otherwise + + + + + Find all possible advisor candidates to use in auto-proxying + + the type of the object to be advised + the name of the object to be advised + the list of candidate advisors + + + + From the given list of candidate advisors, select the ones that are applicable + to the given target specified by targetType and name. + + the list of candidate advisors to date + the target object's type + the target object's name + the list of applicable advisors + + + + Sorts the advisors. + + The advisors. + + + + + Extension hook that subclasses can override to add additional advisors for the given object, + given the sorted advisors obtained to date.
+ The default implementation does nothing.
+ Typically used to add advisors that expose contextual information required by some of the later advisors. + + + The advisor list passed into this method is already reduced to advisors applying to this particular object. + If you want to register additional common advisor candidates, override . + + Advisors that have already been identified as applying to a given object + the type of the object to be advised + the name of the object to be advised + + + + Whether the given advisor is eligible for the specified target. The default implementation + always returns true. + + the advisor name + the target object's type + the target object's name + + + + We override this method to ensure that all candidate advisors are materialized + under a stack trace including this object. Otherwise, the dependencies won't + be apparent to the circular-reference prevention strategy in AbstractObjectFactory. + + + + + Helper for retrieving standard Spring advisors from an for + use with auto-proxying. + + Erich Eichinger + + + + Interface encapsulating the advisor retrieval strategy used by + an to retrieve the + applicable list of advisor objects. + + + + + Get the list of advisor objects to apply on the target. + + + + + Create a new helper for the specified . + + + + + Find all all eligible advisor objects in the current object factory. + + the type of the object to be advised + the name of the object to be advised + A list of eligible instances + + + + Add the named advisor instance to the list of advisors. + + the advisor list + the object name of the advisor to add + + + + Gets the names of advisor candidates + + the type of the object to be advised + the name of the object to be advised + a non-null string array of advisor candidate names + + + + Determine, whether the specified aspect object is eligible. + The default implementation accepts all except for advisors that are + part of the internal infrastructure. + + the name of the candidate advisor + the type of the object to be advised + the name of the object to be advised + + + + The object factory to lookup advisors from + + + + + The base class for AutoProxyCreator implementations that mark objects + eligible for proxying based on arbitrary criteria. + + Erich Eichinger + + + + Overridden to call . + + the type of the object + the name of the object + if remarkable to skip + + + + Override to always return . + + + Whether an object shall be proxied or not is determined by the result of . + + ingored + ignored + ignored + + Always to indicate, that the object shall be proxied. + + + + + + Decide, whether the given object is eligible for proxying. + + + Override this method to allow or reject proxying for the given object. + + the object's type + the name of the object + + whether the given object shall be proxied. + + + + An AutoProxyCreator, that identifies objects to be proxied by checking s defined on their type. + + Erich Eichinger + + + + Determines, whether the given object shall be proxied by matching against . + + the object's type + the name of the object + + + + Checks if is annotated with any of the attributes within the given list of . + + the object's type + the list of types to match agains. + whether to check base classes and intefaces for any of the given attributes. + if any of the attributes is found + + + + Checks if is annotated with the specified . + + the object's type + the type to match agains. + whether to check base classes and intefaces for the specified attribute. + if the attributes is found + + + + Indicates, whether to consider base types for filtering when checking declared attributes. Defaults to false. + + + + + The list of attribute types marking object types as eligible for auto-proxying by this AutoProxyCreator. Must not be null. + + + + + ObjectPostProcessor implementation that creates AOP proxies based on all candidate + Advisors in the current IObjectFactory. This class is completely generic; it contains + no special code to handle any particular aspects, such as pooling aspects. + + Rod Johnson + Adhari C Mahendra (.NET) + Erich Eichinger (.NET) + + + + Separator between prefix and remainder of object name + + + + + Find all possible advisor candidates to use in auto-proxying + + the type of the object to be advised + the name of the object to be advised + the list of candidate advisors + + + + Whether the given advisor is eligible for the specified target. + + the advisor name + the target object's type + the target object's name + + + + Validate configuration + + + + + Gets or sets a value indicating whether to exclude + advisors with a certain prefix. + + true if [use prefix]; otherwise, false. + + + + Set the prefix for object names that will cause them to be included for + auto-proxying by this object. This prefix should be set to avoid circular + references. Default value is the object name of this object + a dot. + + The advisor object name prefix. + + + + Set the name of the object in the object factory that created this object. + + The name of the object in the factory. + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + + + A special version of an APC that explicitely cares for infrastructure (=internal) + advisors only + + Erich Eichinger + + + + Overridden to create a special version of an + that accepts only infrastructure advisor definitions + + + + + + + implementation that replaces a group of objects + with a 'true' inheritance based AOP mechanism that delegates + to the given interceptors before invoking the object itself. + + Bruno Baia + + + + Allows for custom modification of an application context's object definitions. + + +

+ If the object name matches, replaces the type by a AOP proxied type based on inheritance. +

+ + + + + Determines whether the object is an infrastructure type, + IAdvisor, IAdvice, IAdvisors, AbstractAutoProxyCreator or InheritanceBasedAopConfigurer. + + The object type to compare + The name of the object + + true if [is infrastructure type] [the specified obj]; otherwise, false. + + + + + Create an AOP proxy for the given object. + + Type of the object. + The name of the object. + The AOP Proxy for the object. + + + + Return if the given object name matches one of the object names specified. + + +

+ The default implementation checks for "xxx*", "*xxx" and "*xxx*" matches, + as well as direct equality. Can be overridden in subclasses. +

+ + the object name to check + if the names match + + + + Set the names of the objects in IList fashioned way + that should automatically get intercepted. + + + A name can specify a prefix to match by ending with "*", e.g. "myObject,tx*" + will match the object named "myObject" and all objects whose name start with "tx". + + + + + Sets the common interceptors, a list of , + and introduction object names. + + + + If this property isn't set, there will be zero common interceptors. + This is perfectly valid, if "specific" interceptors such as + matching Advisors are all we want. + + + + The list of , + and introduction object names. + + + + + + + Is target type attributes, method attributes, method's return type attributes + and method's parameter attributes to be proxied in addition + to any interfaces declared on the proxied ? + + + + + Gets or sets a value indicating whether inherited members should be proxied. + + + if inherited members should be proxied; + otherwise, . + + + + + Gets or sets a value indicating whether interfaces members should be proxied. + + + if interfaces members should be proxied; + otherwise, . + + + + + Callback that supplies the owning factory to an object instance. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + In case of initialization errors. + + + + + Return the order value of this object, where a higher value means greater in + terms of sorting. + + + Ordering which will apply to this class's implementation + of Ordered, used when applying multiple ObjectPostProcessors. + Default value is int.MaxValue, meaning that it's non-ordered. + + The order value. + + + + Used to obtain the current "target" of an AOP invocation + + +

+ This target will be invoked via reflection if no around advice chooses + to end the interceptor chain itself. +

+

+ If an is "static", it + will always return the same target, allowing optimizations in the AOP + framework. Dynamic target sources can support pooling, hot swapping etc. +

+

+ Application developers don't usually need to work with target sources + directly: this is an AOP framework interface. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Returns the target object. + + The target object. + + If unable to obtain the target object. + + + + + Releases the target object. + + The target object to release. + + + + The of the target object. + + + + + Is the target source static? + + + if the target source is static. + + + + + AutoProxyCreator that identifies objects to proxy via a list of names. + + + + Auto proxy creator that identifies objects to proxy via a list of names. + Checks for direct, "xxx*", "*xxx" and "*xxx*" matches. + + In case of a IFactoryObject, only the objects created by the + FactoryBean will get proxied. If you intend to proxy a IFactoryObject instance itself + specify the object name of the IFactoryObject including + the factory-object prefix "&" e.g. "&MyFactoryObject". + + + + Juergen Hoeller + Adhari C Mahendra (.NET) + Erich Eichinger + + + + Initializes a new instance of . + + + + + Identify as object to proxy if the object name is in the configured list of names. + + + + + Return if the given object name matches the mapped name. + + +

+ The default implementation checks for "xxx*", "*xxx" and "*xxx*" matches, + as well as direct equality. Can be overridden in subclasses. +

+ + the object name to check + the name in the configured list of names + if the names match + + + + Convenience method that may be used by derived classes. Iterates over the list of to match against. + + the object's type. Must not be null. + the name of the object Must not be null. + the list of patterns, that shall be matched against. Must not be null. + + If is null, will always return true, otherwise + if matches any of the patterns specified in . + + + + + Set the names of the objects in IList fashioned way that should automatically + get wrapped with proxies. + A name can specify a prefix to match by ending with "*", e.g. "myObject,tx*" + will match the object named "myObject" and all objects whose name start with "tx". + + + + + This AutoProxyCreator only proxies objects matching the specified . + + Erich Eichinger + + + + Determines, whether the given object shall be proxied. + + + + + Set the pointcut used to filter objects that should automatically get wrapped with proxies. + + + + + AutoProxyCreator, that identifies objects to proxy by matching their against a list of patterns. + + Erich Eichinger + + + + Decide, whether the given object is eligible for proxying. + + + Override this method to allow or reject proxying for the given object. + + the object's type + the name of the object + + whether the given object shall be proxied. + + + + The list of patterns to match against. For pattern syntax, see + + + + + A reusable base implementation of , providing + some useful default implementations + + Erich Eichinger + + + + Factory interface for the creation of AOP proxies based on + configuration + objects. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates an for the + supplied configuration. + + The AOP configuration. + An . + + If the supplied configuration is + invalid. + + + + + Creates an for the + supplied configuration. + + The AOP configuration. + An . + + If the supplied configuration is + invalid. + + + + + + Actually creates the proxy instance based on the supplied . + + the proxy instance described by . Must not be null + + + + If possible, checks for advisor duplicates on the supplied and + eliminates them. + + + + + Checks, if the given holds a proxy generated by this factory. + + + + + + Base class for AOP method builders that contains common functionalities. + + Aleksandar Seovic + Bruno Baia + + + + The implementation to use. + + + + + The dictionary to cache the list of target + s. + + + + + The dictionary to cache the list of target + s defined on the proxy. + + + + + The local variable to store the list of method interceptors. + + + + + The local variable to store the target type being proxied. + + + + + The local variable to store method arguments. + + + + + The local variable to store the return value. + + + + + The local variable to store the closed generic method + when the target method is generic. + + + + + The local variable to store the closed generic method + when the target method defined on the proxy is generic. + + + + + The field to cache the target . + + + + + The field to cache the target + defined on the proxy. + + + + + Indicates if the method returns a value. + + + + + Creates a new instance of the method builder. + + The type builder to use. + + The implementation to use. + + + if the interface is to be + implemented explicitly; otherwise . + + + The dictionary to cache the list of target + s. + + + + + Creates a new instance of the method builder. + + The type builder to use. + + The implementation to use. + + + if the interface is to be + implemented explicitly; otherwise . + + + The dictionary to cache the list of target + s. + + + The dictionary to cache the list of target + s defined on the proxy. + + + + + Generates the proxy method. + + The IL generator to use. + The method to proxy. + + The interface definition of the method, if applicable. + + + + + Generates unique method id for the cache field. + + The target method. + An unique method name. + + + + Create static field that will cache target method. + + The IL generator to use. + The target method. + + + + Create static field that will cache target method when defined on the proxy. + + The IL generator to use. + The target method. + + + + Create a closed generic method for the current call + if target method is a generic definition. + + The IL generator to use. + The target method. + + The field that contains the method generic definition + + + The local variable to store the closed generic method. + + + + + Generates the IL instructions that pushes + the target type on stack. + + The IL generator to use. + + + + Generates the IL instructions that pushes + the current + instance on stack. + + The IL generator to use. + + + + Pushes the target to stack. + + The IL generator to use. + The method to proxy. + + + + Pushes the target defined on the proxy to stack. + + The IL generator to use. + The method to proxy. + + + + Creates local variable declarations. + + The IL generator to use. + The method to proxy. + + + + Initializes local variables + + The IL generator to use. + The method to proxy. + + + + Generates method logic. + + The IL generator to use. + The method to proxy. + + The interface definition of the method, if applicable. + + + + + Calls method using Invoke + + The IL generator to use. + The method to proxy. + + + + Setup proxied method arguments. + + The IL generator to use. + The method to proxy. + The method's parameters. + + + + Calls proxied method directly. + + The IL generator to use. + The method to proxy. + + The interface definition of the method, if applicable. + + + + + Ends method by returning return value if appropriate. + + The IL generator to use. + The method to proxy. + + + + Emits MSIL instructions to load a value of the specified + onto the evaluation stack indirectly. + + The IL generator to use. + The type of the value. + + + + Emit MSIL instructions to store a value of the specified + at a supplied address. + + The IL generator to use. + The type of the value. + + + + Emits MSIL instructions to convert the boxed representation + of the supplied to its unboxed form. + + The IL generator to use. + The type specified in the instruction. + + + + Base class for proxy builders that can be used + to create an AOP proxy for any object. + + Bruno Baia + + + + Describes the operations that generates IL instructions + used to build the Aop proxy type. + + Bruno Baia + + + + Generates the IL instructions that pushes + the current + instance on stack. + + The IL generator to use. + + + + Generates the IL instructions that pushes + the target instance on which calls should be delegated to. + + The IL generator to use. + + + + Generates the IL instructions that pushes + the current + instance on stack. + + The IL generator to use. + + + + Calculates and returns the list of attributes that apply to the + specified type. + + + Removes from the list. + + The type to find attributes for. + + A list of custom attributes that should be applied to type. + + + + + Represents the AOP configuration data built-in with the proxy. + + Bruno Baia + + + + Configuration data for an AOP proxy factory. + + +

+ This configuration includes the + s, + s, and (any) proxied interfaces. +

+

+ Any AOP proxy obtained from Spring.NET can be cast to this interface to + allow the manipulation of said proxy's AOP advice. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + + Adds the supplied to the end (or tail) + of the advice (interceptor) chain. + + +

+ Please be aware that Spring.NET's AOP implementation only supports + method advice (as encapsulated by the + interface). +

+ + + The to be added. + + + + + + + Adds the supplied to the supplied + in the advice (interceptor) chain. + + +

+ Please be aware that Spring.NET's AOP implementation only supports + method advice (as encapsulated by the + interface). +

+ + + The zero (0) indexed position (from the head) at which the + supplied is to be inserted into the + advice (interceptor) chain. + + + The to be added. + + + + + + + Is the supplied (interface) + proxied? + + + The interface to test. + + + if the supplied + (interface) is proxied; + if not or the supplied + is . + + + + + Adds the advisors from the supplied + to the list of . + + + The to add advisors from. + + + If this proxy configuration is frozen and the + cannot be added. + + + + + Adds the supplied to the list + of . + + + The to add. + + + If this proxy configuration is frozen and the + cannot be added. + + + + + Adds the supplied to the list + of . + + + The index in the + list at which the supplied + is to be inserted. + + + The to add. + + + If this proxy configuration is frozen and the + cannot be added. + + + + + Adds the supplied to the list + of . + + + The to add. + + + If this proxy configuration is frozen and the + cannot be added. + + + + + Adds the supplied to the list + of . + + + The index in the + list at which the supplied + is to be inserted. + + + The to add. + + + If this proxy configuration is frozen and the + cannot be added. + + + + + Return the index (0 based) of the supplied + in the interceptor + (advice) chain for this proxy. + + +

+ The return value of this method can be used to index into + the + list. +

+ + + The to search for. + + + The zero (0) based index of this advisor, or -1 if the + supplied is not an advisor for this + proxy. + + + + + Return the index (0 based) of the supplied + in the introductions + for this proxy. + + +

+ The return value of this method can be used to index into + the + list. +

+ + + The to search for. + + + The zero (0) based index of this advisor, or -1 if the + supplied is not an introduction advisor + for this proxy. + + + + + Removes the supplied the list of advisors + for this proxy. + + The advisor to remove. + + if advisor was found in the list of + for this + proxy and was successfully removed; if not + or if the supplied is . + + + If this proxy configuration is frozen and the + cannot be removed. + + + + + Removes the at the supplied + in the + list + from the list of + for this proxy. + + + The index of the to remove. + + + If this proxy configuration is frozen and the + at the supplied + cannot be removed; or if the supplied is out of + range. + + + + + Removes the supplied from the list + of . + + + The to remove. + + + if the supplied was + found in the list of + and successfully removed. + + + If this proxy configuration is frozen and the + cannot be removed. + + + + + Removes the supplied from the list + of . + + + The to remove. + + + if the supplied was + found in the list of + and successfully removed. + + + If this proxy configuration is frozen and the + cannot be removed. + + + + + Removes the at the supplied + in the list of + for this proxy. + + The index of the advisor to remove. + + + If this proxy configuration is frozen and the + at the supplied + cannot be removed; or if the supplied + is out of range. + + + + + Replaces the that + exists at the supplied in the list of + + with the supplied . + + + The index of the + in the list of + + that is to be replaced. + + + The new (replacement) . + + + If the supplied is out of range. + + + + + Replaces the with the + . + + + The original (old) advisor to be replaced. + + + The new advisor to replace the with. + + + if the was + replaced; if the was not found in the + advisors collection, this method returns + and (effectively) does nothing. + + + If this proxy configuration is frozen and the + cannot be replaced. + + + + + + As will normally be passed + straight through to the advised target, this method returns the + equivalent for the AOP + proxy itself. + + + A description of the proxy configuration. + + + + + Should proxies obtained from this configuration expose + the AOP proxy to the + class? + + +

+ This is useful if an advised object needs to call another advised + method on itself. (If it uses the this reference (Me + in Visual Basic.NET), the invocation will not be advised). +

+ + + + + Gets the + + implementation that will be used to get the interceptor + chains for the advised + . + + + The + implementation that will be used to get the interceptor + chains for the advised + . + + + + + Is the target to be proxied in addition + to any interfaces declared on the proxied ? + + + + + Is target type attributes, method attributes, method's return type attributes + and method's parameter attributes to be proxied in addition + to any interfaces declared on the proxied ? + + + + + Returns the collection of + instances that have been applied to this proxy. + + +

+ Will never return , but may return an + empty array (in the case where no + instances have been applied to + this proxy). +

+ + + The collection of + instances that have been applied to this proxy. + + + + + Returns the collection of + instances that have been applied to this proxy. + + +

+ Will never return , but may return an + empty array (in the case where no + instances have been + applied to this proxy). +

+ + + The collection of + instances that have been applied to this proxy. + + + + + Returns the collection of interface s + to be (or that are being) proxied by this proxy. + + + The collection of interface s + to be (or that are being) proxied by this proxy. + + + + + Returns the mapping of the proxied interface + s to their delegates. + + + The mapping of the proxied interface + s to their delegates. + + + + + Is this configuration frozen? + + +

+ When a config is frozen, no advice changes can be made. This is + useful for optimization, and useful when we don't want callers + to be able to manipulate configuration after casting to + . +

+ + + + + Returns the used by this + object. + + + The used by this + object. + + + + + Returns a boolean specifying if this + instance can be serialized. + + + true if this instance can be serialized, false otherwise. + + + + + Should we use dynamic reflection for method invocation ? + + + + + Optimization fields + + + + + IAdvised delegate + + + + + Array of introduction delegates + + + + + Target source + + + + + Type of target object. + + + + + Creates a new instance of the class. + + + + + Creates a new instance of the class. + + + + + Creates a new instance of the class. + + The proxy configuration. + + + + Creates a new instance of the + class. + + The proxy configuration. + The proxy. + + + + Deserialization constructor. + + Serialization data. + Serialization context. + + + + Serializes this instance. + + Serialization data. + Serialization context. + + + + Initialization method. + + The proxy configuration. + + The current implementation. + + + + + Invokes intercepted methods using reflection + + proxy object + target object to invoke method on + target type + taget method to invoke + The method to invoke on proxy. + method arguments + interceptor chain + value returned by invocation chain + + + + Returns a list of method interceptors + + target type + target method + list of inteceptors for the specified method + + + + Adds the supplied to the end (or tail) + of the advice (interceptor) chain. + + + The to be added. + + + + + + + Adds the supplied to the supplied + in the advice (interceptor) chain. + + + The zero (0) indexed position (from the head) at which the + supplied is to be inserted into the + advice (interceptor) chain. + + + The to be added. + + + + + + + Gets the target type behind the implementing object. + Ttypically a proxy configuration or an actual proxy. + + The type of the target or null if not known. + + + + implementation + that delegates method calls to the base method. + + Bruno Baia + + + + Creates a new instance of the method builder. + + The type builder to use. + + The implementation to use. + + + The dictionary to cache the list of target + s. + + + The dictionary to cache the list of target + s defined on the proxy. + + + + + Create static field that will cache target method when defined on the proxy. + + The IL generator to use. + The target method. + + + + Calls target method directly. + + The IL generator to use. + The method to proxy. + + The interface definition of the method, if applicable. + + + + + Base class that each dynamic composition proxy has to extend. + + Aleksandar Seovic + Bruno Baia + + + + The central interface for Spring.NET based AOP proxies. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new proxy object. + + + + + Default constructor. + + + + + Creates a new instance of the + class. + + The proxy configuration. + + + + Deserialization constructor. + + Serialization data. + Serialization context. + + + + Populates a with the data needed to serialize the target object. + + + + + Returns this proxy instance + + + + + + Delegate to target object handling of equals method. + + The object to compare with the current target object + true if the specified Object is equal to the current target object; otherwise, false + + + + Delgate to the target object generation of the hash code. + + A hash code for the target object. + + + + Returns a String the represents the target object. + + A String that represents the target object + + + + Implementation of the + interface that caches the AOP proxy instance. + + +

+ Caches against a key based on : + - the base type + - the target type + - the interfaces to proxy +

+ + Bruno Baia + Erich Eichinger + + + + + + Default implementation of the + interface, + either creating a decorator-based dynamic proxy or + a composition-based dynamic proxy. + + +

+ Creates a decorator-base proxy if one the following is true : + - the "ProxyTargetType" property is set + - no interfaces have been specified +

+

+ In general, specify "ProxyTargetType" to enforce a decorator-based proxy, + or specify one or more interfaces to use a composition-based proxy. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + Bruno Baia (.NET) + Erich Eichinger (.NET) + + + + + Force transient assemblies to be resolvable by . + + + + + Creates an actual proxy instance based on the supplied + + + + + + + Generates the proxy type. + + + The to use + + The generated proxy class. + + + + The shared instance for this class. + + + + + Clears the type cache + + + + + Creates a new instance + + + + + Generates the proxy type and caches the + instance against the base type and the interfaces to proxy. + + + The to use + + The generated or cached proxy class. + + + + Returns the number of proxy types in the cache + + + + + Uniquely identifies a proxytype in the cache + + + + + Builds an AOP proxy type using composition. + + Aleksandar Seovic + Bruno Baia + + + + Creates a new instance of the + class. + + The proxy configuration. + + + + Creates the proxy type. + + The generated proxy type. + + + + Generates the IL instructions that pushes + the current + instance on stack. + + The IL generator to use. + + + + Implements serialization constructor. + + Type builder to use. + + + + Implements constructors for the proxy class. + + +

+ This implementation calls the base constructor. +

+ + + The builder to use. + + + + + Determines if the specified + is one of those generated by this builder. + + The type to check. + + if the type is a composition-based proxy; + otherwise . + + + + + Builds an AOP proxy type using the decorator pattern. + + Bruno Baia + + + + AdvisedProxy instance calls should be delegated to. + + + + + Creates a new instance of the + class. + + The proxy configuration. + + + + Creates the proxy type. + + The generated proxy class. + + + + Generates the IL instructions that pushes + the current + instance on stack. + + The IL generator to use. + + + + Declares field that holds the + instance used by the proxy. + + + The builder to use for code generation. + + + + + Implements serialization method. + + + + + + Implements serialization constructor. + + Type builder to use. + + + + Implements constructors for the proxy class. + + +

+ This implementation creates a new instance + of the class. +

+ + + The builder to use. + + + + + Implements interface. + + The type builder to use. + + + + Determines if the specified + is one of those generated by this builder. + + The type to check. + + if the type is a decorator-based proxy; + otherwise . + + + + + implementation that delegates + method calls to an instance. + + Bruno Baia + + + + The implementation to use. + + + + + Creates a new instance of the method builder. + + The type builder to use. + + The implementation to use. + + + + + Generates the IL instructions that pushes + the target instance on which calls should be delegated to. + + The IL generator to use. + + + + Builds an AOP proxy type using inheritance. + + Bruno Baia + + + + AdvisedProxy instance calls should be delegated to. + + + + + Creates a new instance of the + class. + + The proxy configuration. + + + + Creates the proxy type. + + The generated proxy class. + + + + Generates the IL instructions that pushes + the target instance on which calls should be delegated to. + + The IL generator to use. + + + + Generates the IL instructions that pushes + the current + instance on stack. + + The IL generator to use. + + + + Declares field that holds the + instance used by the proxy. + + + The builder to use for code generation. + + + + + Implements serialization method. + + + + + + Implements serialization constructor. + + Type builder to use. + + + + Defines the types of the parameters for the specified constructor. + + The constructor to use. + The types for constructor's parameters. + + + + Generates the proxy constructor. + + +

+ This implementation creates instance of the AdvisedProxy object. +

+ + The constructor builder to use. + The IL generator to use. + The constructor to delegate the creation to. + + + + Implements interface. + + The type builder to use. + + + + Determines if the specified + is one of those generated by this builder. + + The type to check. + + if the type is a inheritance-based proxy; + otherwise . + + + + + Gets or sets a value indicating whether inherited members should be proxied. + + + if inherited members should be proxied; + otherwise, . + + + + + implementation + that delegates method calls to introduction object. + + Aleksandar Seovic + Bruno Baia + + + + The index of the introduction to delegate call to. + + + + + Creates a new instance of the method builder. + + The type builder to use. + + The implementation to use. + + + + + index of the introduction to delegate call to + + + + Generates the IL instructions that pushes + the introduction type on stack. + + The IL generator to use. + + + + Generates the IL instructions that pushes + the introduction instance on stack. + + The IL generator to use. + + + + Calls proxied method directly. + + The IL generator to use. + The method to proxy. + + The interface definition of the method, if applicable. + + + + + implementation + that delegates method calls to target object. + + Aleksandar Seovic + Bruno Baia + + + + The local variable to store the target instance. + + + + + Creates a new instance of the method builder. + + The type builder to use. + + The implementation to use. + + + if the interface is to be + implemented explicitly; otherwise . + + + The dictionary to cache the list of target + s. + + + + + Creates local variable declarations. + + The IL generator to use. + The method to proxy. + + + + Generates the IL instructions that pushes + the target instance on which calls should be delegated to. + + The IL generator to use. + + + + Generates method logic. + + The IL generator to use. + The method to proxy. + + The interface definition of the method, if applicable. + + + + + Calls proxied method directly. + + The IL generator to use. + The method to proxy. + + The interface definition of the method, if applicable. + + + + + Convenience base class for + implementations. + + +

+ Subclasses can override the + + method to change this behavior, so this is a useful/ base class for + implementations. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + Rick Evans (.NET) + Bruno Baia (.NET) + + + + Description of an invocation to a method, given to an interceptor + upon method-call. + + +

+ A method invocation is a joinpoint and can be intercepted by a method + interceptor. +

+ + + + + + Represents an invocation in the program. + + +

+ An invocation is a joinpoint and can be intercepted by an interceptor. + Typical examples would be a constructor invocation and a method call. +

+ + + + + Represents a generic runtime joinpoint (in the AOP terminology). + + +

+ A runtime joinpoint is an event that occurs on a static + joinpoint (i.e. a location in a program). For instance, an + invocation is the runtime joinpoint on a method (static joinpoint). + The static part of a given joinpoint can be generically retrieved + using the + property. +

+

+ In the context of an interception framework, a runtime joinpoint + is then the reification of an access to an accessible object (a + method, a constructor, a field), i.e. the static part of the + joinpoint. It is passed to the interceptors that are installed on + the static joinpoint. +

+ + + + + + Proceeds to the next interceptor in the chain. + + +

+ The implementation and semantics of this method depend on the + actual joinpoint type. Consult the derived interfaces of this + interface for specifics. +

+ + + Consult the derived interfaces of this interface for specifics. + + + If any of the interceptors at the joinpoint throws an exception. + + + + + Gets the static part of this joinpoint. + + +

+ The static part is an accessible object on which a chain of + interceptors are installed. +

+ + + The static part of this joinpoint. + + + + + Gets the object that holds the current joinpoint's static part. + + +

+ For instance, the target object for a method invocation. +

+ + + The object that holds the current joinpoint's static part. + + + + + Gets the arguments to an invocation. + + +

+ It is of course possible to change element values within this array + to change the arguments to an intercepted invocation. +

+ + + The arguments to an invocation. + + + + + Gets the method invocation that is to be invoked. + + +

+ This property is a friendly implementation of the + property. + It should be used in preference to the + property + because it provides immediate access to the underlying method + without the need to resort to a cast. +

+ + + The method invocation that is to be invoked. + + + + + Gets the proxy object for the invocation. + + + The proxy object for this method invocation. + + + + + Gets the target object for the invocation. + + + The target object for this method invocation. + + + + + Gets the type of the target object. + + + The type of the target object. + + + + + The arguments (if any = may be ) to the method + that is to be invoked. + + + + + The target object that the method is to be invoked on. + + + + + The AOP proxy for the target object. + + + + + The method invocation that is to be invoked. + + + + + The list of and + + that need dynamic checks. + + + + + The declaring type of the method that is to be invoked. + + + + + The index from 0 of the current interceptor we're invoking. + + + + + Creates a new instance of the + class. + + +

+ This is an abstract class, and as such exposes no publicly visible + constructors. +

+

+ + The list can also contain any + s + that need evaluation at runtime. + s included in an + + must already have been found to have matched as far as was possible + statically. Passing an array might be about 10% faster, but + would complicate the code, and it would work only for static + pointcuts. + +

+ + The AOP proxy. + The target object. + the target method. + The target method's arguments. + + The of the target object. + + The list of interceptors that are to be applied. May be + . + + + If the is . + + + + + Proceeds to the next interceptor in the chain. + + + The return value of the method invocation. + + + If any of the interceptors at the joinpoint throws an exception. + + + + + + Retrieves a new instance + for the next Proceed method call. + + + The current instance. + + + The new instance to use. + + + + + + Performs sanity checks, whether the actual joinpoint may be invoked + + + By default checks that the underlying target is not null and the called method is implemented + by the target's type. + + if is null. + if the 's type does not implement . + + + + Invokes the joinpoint. + + +

+ Subclasses can override this to use custom invocation. +

+ + + The return value of the invocation of the joinpoint. + + + If invoking the joinpoint resulted in an exception. + + + + + + A that represents the current + invocation. + + +

+ + Does not invoke on the + target + object, as that too may be proxied. + +

+ + + A that represents the current invocation. + + + + + Gets the method invocation that is to be invoked. + + +

+ May or may not correspond with a method invoked on an underlying + implementation of that interface. +

+ + + + + + Gets the static part of this joinpoint. + + + The proxied member's information. + + + + + + Gets the proxy that this interception was made through. + + + The proxy that this interception was made through. + + + + + Gets the target object for the invocation. + + + The target object for this method invocation. + + + + + Gets the type of the target object. + + + The type of the target object. + + + + + Gets and sets the arguments (if any - may be ) + to the method that is to be invoked. + + + The arguments (if any - may be ) to the + method that is to be invoked. + + + + + + The list of method interceptors. + + +

+ May be . +

+ + + + + Gets the target object. + + + + + Superclass for AOP proxy configuration managers. + + +

+ Instances of this class are not themselves AOP proxies, but + subclasses of this class are normally factories from which AOP proxy + instances are obtained directly. +

+

+ This class frees subclasses of the housekeeping of + and + instances, but doesn't actually + implement proxy creation methods, the functionality for which + is provided by subclasses. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + The list of advice. + +

+ If an is added, it + will be wrapped in an advice before being added to this list. +

+ + + + + Array updated on changes to the advisors list, which is easier to + manipulate internally + + + + + List of introductions. + + + + + Interface map specifying which object should interface methods be + delegated to. + + +

+ If entry value is methods should be delegated + to the target object. +

+ + + + + The for this instance. + + + + + Set to when the first AOP proxy has been + created, meaning that we must track advice changes via the + OnAdviceChange() callback. + + + + + The list of event listeners. + + + + + The advisor chain factory. + + + + + If no explicit interfaces are specified, interfaces will be automatically determined + from the target type + + + + + Creates a new instance of the + class using the + default advisor chain factory. + + + + + Creates a new instance of the + class. + + The interfaces that are to be proxied. + + If this + + + + + Creates a new instance of the + class that proxys all of the interfaces exposed by the supplied + . + + The object to proxy. + + If the is . + + + + + Creates a new instance of the + class that proxys all of the interfaces exposed by the supplied + 's target. + + The providing access to the object to proxy. + + If the is . + + + + + Set interfaces to be proxied, bypassing locking and + + + + + Is the supplied (interface) + proxied? + + + The interface to test. + + + if the supplied + (interface) is proxied; + if not or the supplied + is . + + + + + + Adds the supplied to the end (or tail) + of the advice (interceptor) chain. + + + The to be added. + + + + + + + Adds the supplied to the supplied + in the advice (interceptor) chain. + + + The zero (0) indexed position (from the head) at which the + supplied is to be inserted into the + advice (interceptor) chain. + + + The to be added. + + + If the supplied is ; + or is not an + reference; or if the supplied is a + . + + + + + + + Return the index (0 based) of the supplied + in the interceptor + (advice) chain for this proxy. + + + The to search for. + + + The zero (0) based index of this advisor, or -1 if the + supplied is not an advisor for this + proxy. + + + + + Return the index (0 based) of the supplied + in the introductions + for this proxy. + + + The to search for. + + + The zero (0) based index of this advisor, or -1 if the + supplied is not an introduction advisor + for this proxy. + + + + + Removes the supplied the list of advisors + for this proxy. + + The advisor to remove. + + if advisor was found in the list of + for this + proxy and was successfully removed; if not + or if the supplied is . + + + If this proxy configuration is frozen and the + cannot be removed. + + + + + Removes the at the supplied + in the + list + from the list of + for this proxy. + + + The index of the to remove. + + + If this proxy configuration is frozen and the + at the supplied + cannot be removed; or if the supplied is out of + range. + + + + + Removes the supplied from the list + of . + + + The to remove. + + + if the supplied was + found in the list of + and successfully removed. + + + If this proxy configuration is frozen and the + cannot be removed. + + + + + Removes the supplied from the list + of . + + + The to remove. + + + if the supplied was + found in the list of + and successfully removed. + + + If this proxy configuration is frozen and the + cannot be removed. + + + + + Removes the at the supplied + in the list of + for this proxy. + + The index of the advisor to remove. + + + If this proxy configuration is frozen and the + at the supplied + cannot be removed; or if the supplied + is out of range. + + + + + Adds the supplied to the list + of . + + + The index in the + list at which the supplied + is to be inserted. If -1, appends to the end of the list. + + + The to add. + + + If this proxy configuration is frozen and the + cannot be added. + + + + + Adds the supplied to the list + of . + + + The to add. + + + If this proxy configuration is frozen and the + cannot be added. + + + + + Adds the advisors from the supplied + to the list of . + + + The to add advisors from. + + + If this proxy configuration is frozen and the + cannot be added. + + + + + Adds the supplied to the list + of . + + + The index in the + list at which the supplied + is to be inserted. + + + The to add. + + + If this proxy configuration is frozen and the + cannot be added. + + + + + Adds the supplied to the list + of . + + + The to add. + + + If this proxy configuration is frozen and the + cannot be added. + + + + + Replaces the that + exists at the supplied in the list of + + with the supplied . + + + The index of the + in the list of + + that is to be replaced. + + + The new (replacement) . + + + If the supplied is out of range. + + + + + Replaces the with the + . + + + The original (old) advisor to be replaced. + + + The new advisor to replace the with. + + + if the was + replaced; if the was not found in the + advisors collection (or the is + , this method returns + and (effectively) does nothing. + + + If this proxy configuration is frozen and the + cannot be replaced. + + + + + + As will normally be passed straight through + to the advised target, this method returns the + equivalent for the AOP proxy itself. + + To override this format, override + + A description of the proxy configuration. + + + + + Returns textual information about this configuration object + + + + + + Registers the supplied as a listener for + notifications. + + + The to + register. + + + + + Removes the supplied . + + + The to + be removed. + + + + + Adds a new interface to the list of interfaces that are proxied by this proxy. + + + The interface to be proxied by this proxy. + + + If this proxy configuration is frozen + (); + + + If the supplied is . + + + + + Adds a new interface to the list of interfaces that are proxied by this proxy. + + + The interface to be proxied by this proxy. + + + Access is not synchronized. + + + + + Removes the supplied (proxied) . + + +

+ Does nothing if the supplied (proxied) + isn't proxied. +

+ + The interface to remove. + + if the interface was removed. + + + + Return the index (0 based) of the supplied + in the interceptor + (advice) chain for this proxy. + + +

+ The return value of this method can be used to index into + the + list. +

+ + + The to search for. + + + The zero (0) based index of this interceptor, or -1 if the + supplied is not an advice for this + proxy. + + + + + Return the index (0 based) of the supplied + in the interceptor + (advice) chain for this proxy. + + +

Acces is not synchronized

+

+ The return value of this method can be used to index into + the + list. +

+ + + The to search for. + + + The zero (0) based index of this interceptor, or -1 if the + supplied is not an advice for this + proxy. + + + + + Return the index (0 based) of the supplied + in the interceptor + (advice) chain for this proxy. + + + The to search for. + + + The zero (0) based index of this advisor, or -1 if the + supplied is not an advisor for this + proxy. + + + Access is not synchronized. + + + + + Return the index (0 based) of the supplied + in the introductions + for this proxy. + + + The to search for. + + + The zero (0) based index of this advisor, or -1 if the + supplied is not an introduction advisor + for this proxy. + + + Access is not synchronized + + + + + Removes the at the supplied + in the + list + from the list of + for this proxy. + + + The index of the to remove. + + + If this proxy configuration is frozen and the + at the supplied + cannot be removed; or if the supplied is out of + range. + + + Does not synchronize access. + + + + + Is the supplied included in any + advisor? + + + The to check for the + inclusion of. + + + if the supplied + could be run in an invocation (this does not imply that said + will be run). + + + + + Returns a count of all of the + type-compatible with the supplied . + + + The of the + to check. + + + A count of all of the + type-compatible with the supplied . + + + + + Throws an if + this instances proxy configuration data is frozen. + + + The message that will be passed through to the constructor of any + thrown . + + + If the configuration for this proxy is frozen. + + + + + + Bring the advisors array up to date with the list. + + + + + Callback method that is invoked when the list of proxied interfaces + has changed. + + +

+ An example of such a change would be when a new introduction is + added. Resetting + to + will cause a new proxy + to be generated on the next call to get a proxy. +

+ + + + + Callback method that is invoked when the interceptor list has changed. + + + + + Activates this instance. + + + + + Creates an AOP proxy using this instance's configuration data. + + +

+ Subclasses must not create a proxy by any other means (at least + without having a well thought out and cogent reason for doing so). + This is because the implementation of this method performs some + required housekeeping logic prior to creating an AOP proxy. +

+ + + + + + Calculates the number of not delegating to one of the . + + + + + Copies the configuration from the supplied other + into this instance. + + +

+ Useful when this instance has been created using the no-argument + constructor, and needs to get all of its confiuration data from + another (most + usually to have an independant copy of said configuration data). +

+ + + The instance + containing the configiration data that is to be copied into this + instance. + + + + + Copies the configuration from the supplied other + into this instance. + + +

+ Useful when this instance has been created using the no-argument + constructor, and needs to get all of its confiuration data from + another (most + usually to have an independant copy of said configuration data). +

+ + + The instance + containing the configiration data that is to be copied into this + instance. + + the new target source + the advisors for the chain + the introductions for the chain + + + + A that represents the current + configuration. + + + A that represents the current + configuration. + + + + + Helper method that adds the names of all of the proxied interfaces + to the buffer of the supplied . + + + The to append the proxied interface + names to. + + + + + Helper method that adds advisor's + to the buffer of the supplied . + + + The to append the advisor details to. + + + + + Gets all of the interfaces implemented by the + of the supplied + . + + + The object to get the interfaces of. + + + All of the interfaces implemented by the + of the supplied + . + + + If the supplied is . + + + + + Gets and sets the + + implementation that will be used to get the interceptor + chains for the advised + . + + + The + implementation that will be used to get the interceptor + chains for the advised + . + + + + + Returns the current used + by this object. + + + The used by this + object. + + + + + + Returns a boolean specifying if this + instance can be serialized. + + + true if this instance can be serialized, false otherwise. + + + + + Returns the collection of interface s + to be (or that are being) proxied by this proxy. + + + The collection of interface s + to be (or that are being) proxied by this proxy. + + + + + + Returns the mapping of the proxied interface + s to their delegates. + + + The mapping of the proxied interface + s to their delegates. + + + + + + Returns the collection of + instances that have been applied to this proxy. + + + The collection of + instances that have been applied to this proxy. + + + + + + Returns the collection of + instances that have been applied to this proxy. + + +

+ Will never return , but may return an + empty array (in the case where no + instances have been + applied to this proxy). +

+ + + The collection of + instances that have been applied to this proxy. + + + + + + Gets the target type behind the implementing object. + Ttypically a proxy configuration or an actual proxy. + + The type of the target or null if not known. + + + + If no explicit interfaces are specified, interfaces will be automatically determined + from the target type on proxy creation. Defaults to true + + + + + Sets the target object that is to be advised. + + +

+ This is a convenience write-only property that allows client code + to set the target object... the target object will be implicitly + wrapped within a new + instance. +

+ + + + + Called by subclasses to get a value indicating whether any AOP proxies have been created yet. + + true if this AOp proxies have been created; otherwise, false. + + + + Specifies the of proxies that are to be + created for this instance of proxy config. + + +

+ If this property value is it simply means that + no proxies have been created yet. Only when the first proxy is + created will this property value be set by the AOP framework. +

+

+ Users will be able to add interceptors dynamically without proxy + regeneration, but if they add introductions the proxy + will have to be regenerated. +

+ + + The of proxies that are to be + created for this instance of proxy config; if + no proxies have been created yet. + + + + + Caches proxy constructor for performance reasons. + + + + + Utility methods for use by + implementations. + + +

+ Not intended to be used directly by applications. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Gets the list of + interceptors and dynamic interception + advice that may apply to the supplied + invocation. + + The proxy configuration. + The object proxy. + + The method to evaluate interceptors for. + + + The of the target object. + + + A of + (if there's + a dynamic method matcher that needs evaluation at runtime). + + + + + Creates a new instance of the + + class. + + +

+ This is a utility class, and as such has no publicly visible + constructors. +

+ + + + + Thrown in response to the misconfiguration of an AOP proxy. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class with + the specified message. + + + A message about the exception. + + + + + Creates a new instance of the + class with + the specified message and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + This class contains various methods used to + obtain information about the current AOP invocation. + + +

+ The + property is + usable if the AOP framework is configured to expose the current proxy + (not the default)... it returns the AOP proxy in use. Target objects or + advice can use this to make advised calls. They can also use it to find + advice configuration. +

+

+ To expose the current proxy, set the + property on the controlling proxy to . + The default value for the property + is , for performance reasons. +

+ + The AOP framework does not expose proxies by default, as there is a + performance cost in doing so. + +

+ The functionality in this class might be used by a target object that + needed access to resources on the invocation. However, this approach + should not be used when there is a reasonable alternative, as it makes + application code dependent on usage under AOP and the Spring.NET AOP + framework. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Sets the current proxy by pushing it to the proxy stack. + + +

+ This method is for internal use only, and should never be called by + client code. +

+ + + The proxy to put on top of the proxy stack. + + + + + Removes the current proxy from the proxy stack, making the previous + proxy (if any) the current proxy. + + +

+ This method is for internal use only, and should never be called by + client code. +

+ + + If the proxy stack is empty. + + + + + Creates a new instance of the + class. + + +

+ This is a utility class, and as such exposes no public constructors. +

+ + + + + The AOP proxy stack associated with this thread. + + + + + Indicates if the current call is executed under control of an AOP proxy. + + +

+ Will be unless the + property + on the controlling proxy has been set to . +

+

+ The default value for the + property + is , for performance reasons. +

+ + + + + Gets the current AOP proxy. + + + If the proxy stack is empty. + + + + + Utility methods used by the AOP framework. + + +

+ Not intended to be used directly by applications. +

+ + Rod Johnson + Juergen Hoeller + Aleksandar Seovic (.NET) + + + + Is the supplied an AOP proxy? + + + Return whether the given type is either a composition-based or a decorator-based proxy type. + + The type to be checked. + if the supplied is an AOP proxy type. + + + + Is the supplied an AOP proxy? + + + Return whether the given object is either + a composition-based proxy or a decorator-based proxy. + + The instance to be checked. + + if the supplied is + an AOP proxy. + + + + + Is the supplied a composition-based AOP proxy? + + The instance to be checked. + + if the supplied is + an composition-based AOP proxy. + + + + + Is the supplied a composition based AOP proxy type? + + + Return whether the given type is a composition-based proxy type. + + The type to be checked. + if the supplied is a composition based AOP proxy type. + + + + Is the supplied a decorator-based AOP proxy? + + The instance to be checked. + + if the supplied is + an decorator-based AOP proxy. + + + + + Is the supplied a composition based AOP proxy type? + + + Return whether the given type is a composition-based proxy type. + + The type to be checked. + if the supplied is a composition based AOP proxy type. + + + + Gets all of the interfaces that the of the + supplied implements. + + +

+ This includes interfaces implemented by any superclasses. +

+ + + The object to analyse for interfaces. + + + All of the interfaces that the of the + supplied implements; or an empty + array if the supplied is + . + + + + + Gets all of the interfaces that the + supplied implements. + + + This includes interfaces implemented by any superclasses. + + + The type to analyse for interfaces. + + + All of the interfaces that the supplied implements. + + + + + Can the supplied apply at all on the + supplied ? + + +

+ This is an important test as it can be used to optimize out a + pointcut for a class. +

+

+ Invoking this method with a that is + an interface type will always yield a + return value. +

+ + The pointcut being tested. + The class being tested. + + The interfaces being proxied. If , all + methods on a class may be proxied. + + + if the pointcut can apply on any method. + + + + + Can the supplied apply at all on the + supplied ? + + +

+ This is an important test as it can be used to optimize out a + pointcut for a class. +

+

+ Invoking this method with a that is + an interface type will always yield a + return value. +

+ + The pointcut being tested. + The class being tested. + + The interfaces being proxied. If , all + methods on a class may be proxied. + + whether or not the advisor chain for the target object includes any introductions. + + if the pointcut can apply on any method. + + + + + Can the supplied apply at all on the + supplied ? + + +

+ This is an important test as it can be used to optimize out an + advisor for a class. +

+ + The advisor to check. + The class being tested. + + The interfaces being proxied. If , all + methods on a class may be proxied. + + + if the advisor can apply on any method. + + + + + Can the supplied apply at all on the + supplied ? + + +

+ This is an important test as it can be used to optimize out an + advisor for a class. +

+ + The advisor to check. + The class being tested. + + The interfaces being proxied. If , all + methods on a class may be proxied. + + whether or not the advisor chain for the target object includes any introductions. + + if the advisor can apply on any method. + + + + + Creates a new instance of the + class. + + +

+ This is a utility class, and as such has no publicly + visible constructors. +

+ + + + + Gets the type of the target. + + The candidate. + + + + + Invokes a target method using dynamic reflection. + + + Aleksandar Seovic + Bruno Baia + + + + The method invocation that is to be invoked on the proxy. + + + + + Creates a new instance of the + class. + + The AOP proxy. + The target object. + The target method proxied. + The method to invoke on proxy. + The target method's arguments. + + The of the target object. + + The list of interceptors that are to be applied. May be + . + + + If any of the or + parameters is . + + + + + Invokes the joinpoint using dynamic reflection. + + +

+ Subclasses can override this to use custom invocation. +

+ + + The return value of the invocation of the joinpoint. + + + If invoking the joinpoint resulted in an exception. + + + + + + Creates a new instance + from the specified and + increments the interceptor index. + + + The current instance. + + + The new instance to use. + + + + + implementation + that caches advisor chains on a per-advised-method basis. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Factory interface for advisor chains. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Callback interface for + listeners. + + +

+ Allows + implementations to be notified of notable lifecycle events relating + to the creation of a proxy, and changes to the configuration data of a + proxy. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Invoked when the first proxy is created. + + + The relevant source. + + + + + Invoked when advice is changed after a proxy is created. + + + The relevant source. + + + + + Invoked when interfaces are changed after a proxy is created. + + + The relevant source. + + + + + Gets the list of and + + instances for the supplied . + + The proxy configuration object. + The object proxy. + + The method for which the interceptors are to be evaluated. + + + The of the target object. + + + The list of and + + instances for the supplied . + + + + + Gets the list of and + + instances for the supplied . + + The proxy configuration object. + The object proxy. + + The method for which the interceptors are to be evaluated. + + + The of the target object. + + + The list of and + + instances for the supplied . + + + + + Invoked when the first proxy is created. + + + The relevant source. + + + + + Invoked when advice is changed after a proxy is created. + + + The relevant source. + + + + + Invoked when interfaces are changed after a proxy is created. + + + The relevant source. + + + + Internal framework class. + This class is required because if we put an interceptor that implements IInterceptionAdvice + in the interceptor list passed to MethodInvocation, it may be mistaken for an + advice that requires dynamic method matching. + + Rod Johnson + Aleksandar Seovic (.Net) + + + + Provides access to the target object of an AOP proxy. + + +

+ To be implemented by introduction aspects in order to obtain access to + the target object. +

+ + Aleksandar Seovic + + + + Sets the target object. + + + + + Factory for AOP proxies for programmatic use, rather than via a + Spring.NET IoC container. + + +

+ This class provides a simple way of obtaining and configuring AOP + proxies in code. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class that proxys all of the interfaces exposed by the supplied + . + + The object to proxy. + + If the is . + + + + + Creates a new instance of the + class that has no target object, only interfaces. + + +

+ Interceptors must be added if this factory is to do anything useful. +

+ + The interfaces to implement. + + + + Creates a new instance of the class for the + given interface and interceptor. + + Convenience method for creating a proxy for a single interceptor + , assuming that the interceptor handles all calls itself rather than delegating + to a target, like in the case of remoting proxies. + The interface that the proxy should implement. + The interceptor that the proxy should invoke. + + + + Create a new instance of the class for the specified + making the proxy implement the specified interface. + + + The interface that the proxy should implement. + The target source that the proxy should invoek. + + + + Creates a new proxy according to the settings in this factory. + + +

+ Can be called repeatedly; the effect of repeated invocations will + (of course) vary if interfaces have been added or removed. +

+ + An AOP proxy for target object. + + + + Creates a new proxy for the supplied + and . + + +

+ This is a convenience method for creating a proxy for a single + interceptor. +

+ + + The interface that the proxy must implement. + + + The interceptor that the proxy must invoke. + + + A new AOP proxy for the supplied + and . + + + + + implementation to + source AOP proxies from a Spring.NET IoC container (an + ). + + +

+ s and + s are identified by a list of object + names in the current container.

+

+ Global interceptors and advisors can be added at the factory level + (that is, outside the context of a + definition). The + specified interceptors and advisors are expanded in an interceptor list + (see + ) + where an 'xxx*' wildcard-style entry is included in the list, + matching the given prefix with the object names. For example, + 'global*' would match both 'globalObject1' and + 'globalObjectBar', and '*' would match all defined + interceptors. The matching interceptors get applied according to their + returned order value, if they implement the + interface. An interceptor name list + may not conclude with a global 'xxx*' pattern, as global + interceptors cannot invoke targets. +

+

+ It is possible to cast a proxy obtained from this factory to an + reference, or to obtain the + reference and + programmatically manipulate it. This won't work for existing prototype + references, which are independent... however, it will work for prototypes + subsequently obtained from the factory. Changes to interception will + work immediately on singletons (including existing references). + However, to change interfaces or the target it is necessary to obtain a + new instance from the surrounding container. This means that singleton + instances obtained from the factory do not have the same object + identity... however, they do have the same interceptors and target, and + changing any reference will change all objects. +

+ + Rod Johnson + Juergen Hoeller + Federico Spinazzi (.NET) + Choy Rim (.NET) + Mark Pollack (.NET) + Aleksandar Seovic (.NET) + + + + + + + + + The instance for this class. + + + + + Is the object managed by this factory a singleton or a prototype? + + + + + This suffix in a value in an interceptor list indicates to expand globals. + + + + + The cached instance if this proxy factory object is a singleton. + + + + + The owning object factory (which cannot be changed after this object is initialized). + + + + + The advisor adapter registry for wrapping pure advices and pointcuts according to needs + + + + + Names of interceptors and pointcut objects in the factory. + + +

+ Default is for globals expansion only. +

+ + + + + Names of introductions and pointcut objects in the factory. + + +

+ Default is for globals expansion only. +

+ + + + + The name of the target object(in the enclosing + ). + + + + + Indicates if the advisor chain has already been initialized + + + + + Indicate whether this config shall be frozen upon creation + of the first proxy instance + + + + + Creates a new instance of ProxyFactoryObject + + + + + Creates an instance of the AOP proxy to be returned by this factory + + +

+ Invoked when clients obtain objects from this factory object. The + (proxy) instance will be cached for a singleton, and created on each + call to + for a prototype. +

+ + + A fresh AOP proxy reflecting the current state of this factory. + + + + + + Initialize this proxy factory - usually called after all properties are set + + + + Create the advisor (interceptor) chain. + + The advisors that are sourced from an ObjectFactory will be refreshed each time + a new prototype instance is added. Interceptors added programmatically through + the factory API are unaffected by such changes. + + + + Add all global interceptors and pointcuts. + + + + Configures introductions for this proxy. + + + + Add all global introductions. + + + Add the introduction to the introduction list. + + If specified parameter is IIntroducionAdvisor it is added directly, otherwise it is wrapped + with DefaultIntroductionAdvisor first. + + introducion to add + object name from which we obtained this object in our owning object factory + + + + Refreshes target object for prototype instances. + + + + Refresh named objects from the interceptor chain. + We need to do this every time a new prototype instance is returned, + to return distinct instances of prototype interfaces and pointcuts. + + + + Refresh named objects from the interceptor chain. + We need to do this every time a new prototype instance is returned, + to return distinct instances of prototype interfaces and pointcuts. + + + + Wraps target with SingletonTargetSource if necessary + target or target source object + target source passed or target wrapped with SingletonTargetSource + + + Wraps introduction with IIntroductionAdvisor if necessary + Wraps pointcut or interceptor with appropriate advisor + pointcut or interceptor that needs to be wrapped with advisor + Advisor + + + object to wrap + Introduction advisor + + + + Callback method that is invoked when the list of proxied interfaces + has changed. + + +

+ An example of such a change would be when a new introduction is + added. Resetting + to + will cause a new proxy + to be generated on the next call to get a proxy. +

+ + + + + Returns textual information about this configuration object + + + + + Check the interceptorNames list whether it contains a target name as final element. + If found, remove the final name from the list and set it as targetName. + + + + + Indicate whether this config shall be frozen upon creation + of the first proxy instance + + + + + If set true, any attempt to modify this proxy configuration will raise an exception + + + + + Specify the AdvisorAdapterRegistry to use. Default is the + + + + + Sets the names of the interfaces that are to be implemented by the proxy. + + + The names of the interfaces that are to be implemented by the proxy. + + + If the supplied value (or any of its elements) is ; + or if any of the element values is not the (assembly qualified) name of + an interface type. + + + + + Sets the name of the target object being proxied. + + +

+ Only works when the + + property is set; it is a logic error on the part of the programmer + if this value is set and the accompanying + is not also set. +

+ + + The name of the target object being proxied. + + + + + Sets the list of and + object names. + + +

+ This property must always be set (configured) when using a + in an + context. +

+ + + The list of and + object names. + + + + + + + + + Sets the list of introduction object names. + + +

+ Only works when the + + property is set; it is a logic error on the part of the programmer + if this value is set and the accompanying + is not supplied. +

+ + + The list of introduction object names. . + + + + + Callback that supplies the owning factory to an object instance. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + + In case of initialization errors. + + + + + + + Return the of the proxy. + + + Will check the singleton instance if already created, + else fall back to the proxy interface (if a single one), + the target bean type, or the TargetSource's target class. + + Return the of object that this + creates, or + if not known in advance. + + + + Is the object managed by this factory a singleton or a prototype? + + + + + Superinterface for advisors that perform one or more AOP + introductions. + + +

+ This interface cannot be implemented directly; subinterfaces must + provide the advice type implementing the introduction. +

+

+ Introduction is the implementation of additional interfaces (not + implemented by a target) via AOP advice. +

+ + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Base interface holding AOP advice and a filter determining the + applicability of the advice (such as a pointcut). + + + + This interface is not for use by Spring.NET users, but exists rather to + allow for commonality in the support for different types of advice + within the framework. + +

+ Spring.NET AOP is centered on around advice delivered via method + interception, compliant with the AOP Alliance interception API. + The interface allows support for + different types of advice, such as before and after + advice, which need not be implemented using interception. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + + + + + Is this advice associated with a particular instance? + + +

+ An advisor that was creating a mixin would be a per instance + operation and would thus return . If the + advisor is not per instance, it is shared with all instances of the + advised class obtained from the same Spring.NET IoC container. +

+

+ Use singleton and prototype object definitions or + appropriate programmatic proxy creation to ensure that + s have the correct lifecycle model. +

+ + This method is not currently used by the framework. + + + + if this advice is associated with a + particular instance. + + + + + Return the advice part of this aspect. + + +

+ An advice may be an interceptor, a throws advice, before advice, + introduction etc. +

+ + + The advice that should apply if the pointcut matches. + + + + + Can the advised interfaces be implemented by the introduction + advice? + + +

+ Invoked before adding an + . +

+ + + If the advised interfaces cannot be implemented by the introduction + advice. + + + + + + Returns the filter determining which target classes this + introduction should apply to. + + +

+ This is the part of a pointcut. + Be advised that method matching doesn't make sense in the context + of introductions. +

+ + + The filter determining which target classes this introduction + should apply to. + + + + + Gets the interfaces introduced by this + . + + + The interfaces introduced by this + . + + + + + Invokes a target method using standard reflection. + + Rod Johnson + Aleksandar Seovic (.NET) + Rick Evans (.NET) + Bruno Baia (.NET) + + + + The method invocation that is to be invoked on the proxy. + + + + + Creates a new instance of the + class. + + The AOP proxy. + The target object. + The target method proxied. + The method to invoke on proxy. + The target method's arguments. + + The of the target object. + + The list of interceptors that are to be applied. May be + . + + + If any of the or + parameters is . + + + + + Invokes the joinpoint using standard reflection. + + +

+ Subclasses can override this to use custom invocation. +

+ + + The return value of the invocation of the joinpoint. + + + If invoking the joinpoint resulted in an exception. + + + + + + Creates a new instance + from the specified and + increments the interceptor index. + + + The current instance. + + + The new instance to use. + + + + + Abstract PointcutAdvisor that allows for any Advice to be configured. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Abstract base class for implementations. + + + Can be subclassed for returning a specific pointcut/advice or a freely configurable pointcut/advice. + + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + + + + Superinterface for all s that are + driven by a pointcut. + + +

+ This covers nearly all advisors except introduction advisors, for which + method-level matching does not apply. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + + The that drives this advisor. + + + + + Determines whether the specified + is equal to the current . + + The advisor to compare with. + + if this instance is equal to the + specified . + + + + + Serves as a hash function for a particular type, suitable for use + in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Returns this s order in the + interception chain. + + + This s order in the + interception chain. + + + + + Return the advice part of this aspect. + + +

+ An advice may be an interceptor, a throws advice, before advice, + introduction etc. +

+ + + The advice that should apply if the pointcut matches. + + + + + Is this advice associated with a particular instance? + + +

+ Not supported for dynamic advisors. +

+ + + if this advice is associated with a + particular instance. + + Always. + + + + + The that drives this advisor. + + + + + 2 s are considered equals, if + a) their pointcuts are equal + b) their advices are equal + + + + + Calculates a unique hashcode based on advice + pointcut + + + + + Returns a that represents the current + . + + + A representation of this advisor. + + + + + Return the advice part of this advisor. + + + The advice that should apply if the pointcut matches. + + + + + + Abstract ObjectFactory-based IPointcutAdvisor that allows for any Advice to be + configured as reference to an Advice object in an ObjectFactory. + + + specifying the name of an advice object instead of the advice object itself + (if running within an ObjectFactory/ApplicationContext increses loose coupling + at initialization time, in order not to initialize the advice object until the + pointcut actually matches. + + Juergen Hoeller + Mark Pollack + + + + Describe this Advisor, showing name of advice object. + + + Type name and advice object name. + + + + + Gets or sets the name of the advice object that this advisor should refer to. + + An instance of the specified object will be obtained on first access of + this advisor's advice. This advisor will only ever obtain at most one + single instance of the advice object, caching the instance for the lifetime of + the advisor. + The name of the advice object. + + + + Callback that supplies the owning factory to an object instance. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + In case of initialization errors. + + + + + Return the advice part of this aspect. + + +

+ An advice may be an interceptor, a throws advice, before advice, + introduction etc. +

+ + + The advice that should apply if the pointcut matches. + + + + + Abstract base regular expression pointcut object. + + +

+ The regular expressions must be a match. For example, the + .*Get.* pattern will match Com.Mycom.Foo.GetBar(), and + Get.* will not. +

+

+ This base class is serializable. Subclasses should decorate all + fields with the - the + + method in this class will be invoked again on the client side on deserialization. +

+ + Rod Johnson + Juergen Hoeller + Simon White (.NET) + + + + Convenient superclass when one wants to force subclasses to + implement the interface + but subclasses will still want to be pointcuts. + + +

+ The + property can be overriden to customize filter + behavior as well. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + Mark Pollack (.NET) + + + + Convenient abstract superclass for static method matchers that don't care + about arguments at runtime. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + That part of an that checks whether a + target method is eligible for advice. + + +

+ An may be evaluated + statically or at runtime (dynamically). Static + matching involves only the method signature and (possibly) any + s that have been applied to a method. + Dynamic matching additionally takes into account the actual argument + values passed to a method invocation. +

+

+ If the value of the + property of an implementation instance returns , + evaluation can be performed statically, and the result will be the same + for all invocations of this method, whatever their arguments. This + means that if the value of the + is + , the three argument + + method will never be invoked for the lifetime of the + . +

+

+ If an implementation returns in its two argument + + method, and the value of it's + property is + , the three argument + + method will be invoked immediately before each and every potential + execution of the related advice, to decide whether the advice + should run. All previous advice, such as earlier interceptors in an + interceptor chain, will have run, so any state changes they have + produced in parameters or thread local storage, will be available at + the time of evaluation. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + + Does the supplied satisfy this matcher? + + +

+ This is a static check. If this method invocation returns + ,or if the + property is + , then no runtime check will be made. +

+ + The candidate method. + + The target (may be , + in which case the candidate must be taken + to be the 's declaring class). + + + if this this method matches statically. + + + + + Is there a runtime (dynamic) match for the supplied + ? + + +

+ In order for this method to have even been invoked, the supplied + must have matched + statically. This method is invoked only if the two argument + + method returns for the supplied + and , and + if the property + is . +

+

+ Invoked immediately before any potential running of the + advice, and after any advice earlier in the advice chain has + run. +

+ + The candidate method. + + The target . + + The arguments to the method + + if there is a runtime match. + + + + Is this dynamic? + + +

+ If , the three argument + + method will be invoked if the two argument + + method returns . +

+

+ Note that this property can be checked when an AOP proxy is created, + and implementations need not check the value of this property again + before each method invocation. +

+ + + if this + is dynamic. + + + + + Is there a runtime (dynamic) match for the supplied + ? + + +

+ Always throws a . This + method should never be called on a static matcher. +

+ + The candidate method. + + The target . + + The arguments to the method + + Always throws a . + + + Always. + + + + + Does the supplied satisfy this matcher? + + +

+ Must be implemented by a derived class in order to specify matching + rules. +

+ + The candidate method. + + The target (may be , + in which case the candidate must be taken + to be the 's declaring class). + + + if this this method matches statically. + + + + + Override in case you need to initialized non-serialized fields on deserialization. + + + + + Is this dynamic? + + +

+ Always returns . +

+ + + Always returns . + + + + + Spring.NET's core pointcut abstraction. + + +

+ A pointcut is composed of s and + s. Both these basic terms and an + itself can be combined to build up + sophisticated combinations. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + The for this pointcut. + + + The current . + + + + + The for this pointcut. + + + The current . + + + + + Creates a new instance of the + + class. + + +

+ This is an abstract class, and as such has no publicly + visible constructors. +

+ + + + + The for this pointcut. + + + The current . + + + + + The for this pointcut. + + + The current . + + + + + A filter that restricts the matching of a pointcut or introduction to + a given set of target types. + + +

+ Can be used as part of a pointcut, or for the entire targeting of an + introduction. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + + + Should the pointcut apply to the supplied + ? + + + The candidate . + + + if the advice should apply to the supplied + + + + + + Creates a new instance of the + + class. + + +

+ This is an abstract class, and as such has no publicly + visible constructors. +

+ + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + If an error was encountered during the deserialization process. + + + + + Overridden to ensure proper initialization + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + Subclasses must implement this to initialize regular expression pointcuts. + + +

+ Can be invoked multiple times. +

+

+ This method will be invoked from the property, + and also on deserialization. +

+ + + The patterns to initialize. + + + In the case of an invalid pattern. + + + + + Does the pattern at the supplied + match this ? + + The pattern to match + The index of pattern. + + if there is a match. + + + + + Does the supplied satisfy this matcher? + + +

+ Try to match the regular expression against the fully qualified name + of the method's declaring , plus the name of + the supplied . +

+

+ Note that the declaring is that + that originally declared + the method, not necessarily the that is + currently exposing it. For example, + matches any subclass of 's + method. +

+ + The candidate method. + + The target (may be , + in which case the candidate must be taken + to be the 's declaring class). + + + if this this method matches statically. + + + + + Should the pointcut apply to the supplied + ? + + +

+ In this instance, simply returns . +

+ + + The candidate . + + + if the advice should apply to the supplied + + + + + + The for this pointcut. + + + The current . + + + + + Convenience property for setting a single pattern. + + + Use this property or Patterns, not both. + + + + + The regular expressions defining methods to match. + + + Matching will be the union of all these; if any match, + the pointcut matches. + + + + + Pointcut that looks for a specific attribute being present on a class or + method. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class for the + given attribute type. + + Type of the attribute to look for at the class level. + + + + Initializes a new instance of the class for the + given attribute type + + Type of the attribute. + if set to true [check inherited]. + + + + Initializes a new instance of the class for the given + attribute type + + The attribute type to look for at the class level. + The attribute type to look for at the method attribute. + + + + The for this pointcut. + + The current . + + + + The for this pointcut. + + The current . + + + + implementation that matches methods + that have been decorated with a specified . + + Aleksandar Seovic + Ronald Wildenberg + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The to match. + + + + + Creates a new instance of the + + class. + + + The to match. + + + Flag that controls whether or not the inheritance tree of the + method to be included in the search for the ? + + + + + Creates a new instance of the + + class. + + + The to match. + + + Flag that controls whether or not the inheritance tree of the + method to be included in the search for the ? + + + Flag that controls whether or not interfaces attributes of the + method to be included in the search for the ? + + + + + Does the supplied satisfy this matcher? + + The candidate method. + + The target (may be , + in which case the candidate must be taken + to be the 's declaring class). + + + if this this method matches statically. + + + + + The to match. + + + If the supplied value is not a that + derives from the class. + + + + + Is the inheritance tree of the method to be included in the search for the + ? + + +

+ The default is . +

+ + + + + Is the interfaces attributes of the method to be included in the search for theg + ? + + +

+ The default is . +

+ + + + + Convenient class for attribute-match method pointcuts that hold an Interceptor, + making them an Advisor. + + Bruno Baia + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class + for the supplied . + + the advice to apply if the pointcut matches + + + + Creates a new instance of the + class + for the supplied . + + + The to match. + + + Flag that controls whether or not the inheritance tree of the + method to be included in the search for the ? + + the advice to apply if the pointcut matches + + + + Is this advice associated with a particular instance? + + + if this advice is associated with a + particular instance. + + + Always; this property is not yet supported. + + + + + Returns this s order in the + interception chain. + + + This s order in the + interception chain. + + + + + Return the advice part of this advisor. + + + The advice that should apply if the pointcut matches. + + + + + + The that drives this advisor. + + + + + MethodMatcher that looks for a specific attribute being present on the + method (checking both the method on the onviked interface, if any and the corresponding + method on the target class + + Juergen hoeller + Mark Pollack + + + + + Initializes a new instance of the class for the + given atribute type. + + Type of the attribute to look for. + + + + Does the supplied satisfy this matcher? + + The candidate method. + The target (may be , + in which case the candidate must be taken + to be the 's declaring class). + + if this this method matches statically. + + +

+ Must be implemented by a derived class in order to specify matching + rules. +

+ + + + + ITypeFilter that looks for a specific attribute being present on a class + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class for the + given attribute type. + + Type of the attribute to look for. + + + + Initializes a new instance of the class for the + given attribute type. + + Type of the attribute. + if set to true [check inherited]. + + + + Should the pointcut apply to the supplied ? + + The candidate . + + if the advice should apply to the supplied + + + + + + The attribute for this filter. + + + + + Indicates, whether this filter considers base types for filtering. + + + + + Convenient class for building up pointcuts. + + +

+ All methods return a + instance, which facilitates the following concise usage pattern... +

+ + IPointcut pointcut = new ComposablePointcut() + .Union(typeFilter) + .Intersection(methodMatcher) + .Intersection(pointcut); + +

+ There is no Union() method on this class. Use the + method for such functionality. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + class + that matches all the methods on all s. + + + + + Creates a new instance of the + class + that uses the supplied and + . + + + The type filter to use. + + + The method matcher to use. + + + + + Changes the current type filter to be the union of the existing filter and the + supplied . + + The filter to union with. + + The union of the existing filter and the supplied . + + + + + Changes the current type filter to be the intersection of the existing filter + and the supplied . + + The filter to diff against. + + The intersection of the existing filter and the supplied . + + + + + Changes the current method matcher to be the union of the existing matcher and the + supplied . + + The matcher to union with. + + The union of the existing matcher and the supplied . + + + + + Changes the current method matcher to be the intersection of the existing matcher + and the supplied . + + The matcher to diff against. + + The intersection of the existing matcher and the supplied . + + + + + Changes current pointcut to intersection of the current and supplied pointcut + + pointcut to diff against + updated pointcut + + + + The for this pointcut. + + + The current . + + + + + The for this pointcut. + + + The current . + + + + + Pointcut and method matcher for use in simple cflow-style + pointcuts. + + +

+ Evaluating such pointcuts is slower than evaluating normal pointcuts, + but can nevertheless be useful in some cases. Of course, your mileage + may vary as to what 'slower' actually means. +

+ + Rod Johnson + Simon White (.NET) + + + + Creates a new instance of the + class. + + + The class under which all control flows are to be matched. + + + + + Construct a new pointcut that matches all calls below the + given method in the given class. + + +

+ If the supplied is + , all control flows below the given + class will be successfully matched. +

+ + + The class under which all control flows are to be matched. + + + The method name under which all control flows are to be matched. + + + + + Should the pointcut apply to the supplied ? + + +

+ Subclasses are encouraged to override this method for greater + filtering (and performance). +

+

+ This, the default, implementation always matches (returns + ). +

+ + The candidate target class. + + if the advice should apply to the supplied + + + + + + Does the supplied satisfy this matcher? + Perform static checking. If this returns false, or if the isRuntime() method + returns false, no runtime check will be made. + + +

+ Subclasses are encouraged to override this method if it is possible + to filter out some candidate classes. +

+

+ This, the default, implementation always matches (returns + ). This means that the three argument + + method will always be invoked. +

+ + The candidate method. + + The target class (may be , in which case the + candidate class must be taken to be the 's + declaring class). + + + if this this method matches statically. + + + + + + Is there a runtime (dynamic) match for the supplied + ? + + +

+ Subclasses are encouraged to override this method if it is possible + to filter out some candidate classes. +

+ + The candidate method. + The target class. + The arguments to the method + + if there is a runtime match. + + + + + The for this pointcut. + + + The current . + + + + + Gets the number of times this pointcut has been evaluated. + + +

+ Useful as a debugging aid. +

+

+ Note that this value is distinct from the number of times that this + pointcut sucessfully matches a target method, in that a + may be evaluated many times but + never actually match even once. +

+ + + The number of times this pointcut has been evaluated. + + + + + The for this pointcut. + + + The current . + + + + + Is this a runtime pointcut? + + +

+ This implementation is a runtime pointcut, and so always returns + . +

+ + + if this is a runtime pointcut. + + + + + + Simple implementation that + by default applies to any class. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + class using + the supplied + + +

+ This constructor adds all interfaces implemented by the supplied + (except the + interface) to the list of + interfaces to introduce. +

+ + The introduction to use. + + + + Creates a new instance of the + class using + the supplied + + The introduction to use. + + The interface to introduce. + + + + + Creates a new instance of the + class using + the supplied + + The introduction to use. + + The interfaces to introduce. + + + If the supplied is . + + + + + Adds the supplied to the list of + introduced interfaces. + + The interface to add. + + If any of the are not interface . + + + + + Should the pointcut apply to the supplied + ? + + +

+ This, the default, implementation always returns . +

+ + + The candidate . + + + if the advice should apply to the supplied + + + + + + Can the advised interfaces be implemented by the introduction + advice? + + +

+ Invoked before adding an + . +

+ + + If the advised interfaces cannot be implemented by the introduction + advice. + + + + If any of the are not interface . + + + + + 2 IntroductionAdvisors are considered equal if + a) they are of the same type + b) their introduction advices are equal + c) they introduce the same interfaces + + + + + 2 IntroductionAdvisors are considered equal if + a) they are of the same type + b) their introduction advices are equal + c) they introduce the same interfaces + + + + + 2 IntroductionAdvisors are considered equal if + a) they are of the same type + b) their introduction advices are equal + c) they introduce the same interfaces + + + + + Returns the filter determining which target classes this + introduction should apply to. + + + The filter determining which target classes this introduction + should apply to. + + + + + Gets the interfaces introduced by this + . + + + The interfaces introduced by this + . + + + + + Is this advice associated with a particular instance? + + +

+ Default for an introduction is per-instance interception. +

+ + + if this advice is associated with a + particular instance. + + + + + Return the advice part of this aspect. + + + The advice that should apply if the pointcut matches. + + + + + Concrete ObjectFactory-based IPointcutAdvisor thta allows for any Advice to be + configured as reference to an Advice object in the ObjectFatory, as well as + the Pointcut to be configured through an object property. + + + Specifying the name of an advice object instead of the advice object itself + (if running within a ObjectFactory/ApplicationContext) increases loose coupling + at initialization time, in order to not intialize the advice object until the pointcut + actually matches. + + Juerge Hoeller + Mark Pollack + + + + Describe this Advisor, showing pointcut and name of advice object. + + Type name , pointcut, and advice object name. + + + + The that drives this advisor. + + + + + Convenient pointcut-driven advisor implementation. + + +

+ This is the most commonly used implementation. + It can be used with any pointcut and advice type, except for introductions. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + + class for the supplied , + + + The advice to use. + + + + + Creates a new instance of the + + class for the supplied and + . + + + The advice to use. + + + The pointcut to use. + + + + + 2 s are considered equal, if + a) their pointcuts are equal + b) their advices are equal + + + + + Calculates a unique hashcode based on advice + pointcut + + + + + Returns a that represents the current + . + + + A representation of this advisor. + + + + + The that drives this advisor. + + + + + Convenient abstract superclass for dynamic method matchers that do + care about arguments at runtime. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + + class. + + +

+ This is an class, and as such exposes no + public constructors. +

+ + + + + Does the supplied satisfy this matcher? + + +

+ Derived classes can override this method to add preconditions for + dynamic matching. +

+

+ This implementation always returns . +

+ + The candidate method. + + The target (may be , + in which case the candidate must be taken + to be the 's declaring class). + + + if this this method matches statically. + + + + + Is there a runtime (dynamic) match for the supplied + ? + + +

+ Must be overriden by derived classes to provide criteria for dynamic matching. +

+ + The candidate method. + + The target . + + The arguments to the method + + if there is a runtime match. + + + + Is this dynamic? + + + Always returns , to specify that this is a + dynamic matcher. + + + + + Convenient superclass for s + that are also dynamic pointcuts. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + + class. + + +

+ This is an abstract class, and as such has no publicly + visible constructors. +

+ + + + + Creates a new instance of the + + class for the supplied . + + +

+ This is an abstract class, and as such has no publicly + visible constructors. +

+ + + The advice portion of this advisor. + + + + + Is this advice associated with a particular instance? + + +

+ Not supported for dynamic advisors. +

+ + + if this advice is associated with a + particular instance. + + Always. + + + + + The for this pointcut. + + +

+ This implementation always returns a filter that evaluates to + for any . +

+ + + The current . + + + + + The for this pointcut. + + +

+ This implementation always returns itself (this object). +

+ + + The current . + + + + + Returns this s order in the + interception chain. + + + This s order in the + interception chain. + + + + + Return the advice part of this aspect. + + + The advice that should apply if the pointcut matches. + + + + + + The that drives this advisor. + + +

+ This implementation always returns itself (this object). +

+ + + + + Various utility methods relating to the composition of + s. + + +

+ A method matcher may be evaluated statically (based on method and target + class) or need further evaluation dynamically (based on arguments at + the time of method invocation). +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new that is the + union of the two supplied s. + + +

+ The newly created matcher will match all the methods that either of the two + supplied matchers would match. +

+ + The first method matcher. + The second method matcher. + + A new that is the + union of the two supplied s + + + + + Creates a new that is the + intersection of the two supplied s. + + +

+ The newly created matcher will match only those methods that both + of the supplied matchers would match. +

+ + The first method matcher. + The second method matcher. + + A new that is the + intersection of the two supplied s + + + + + Creates a new instance of the + class. + + +

+ This is a utility class, and as such has no publicly + visible constructors. +

+ + + + + Pointcut object for simple method name matches, useful as an alternative to pure + regular expression based patterns. + + Juergen Hoeller + Aleksandar Seovic (.NET) + + + + Does the of the supplied + matches any of the mapped names? + + + The to check. + + + The of the target class. + + + if the name of the supplied + matches one of the mapped names. + + + + + Does the supplied match the supplied ? + + +

+ The default implementation checks for "xxx*", "*xxx" and "*xxx*" matches, + as well as direct equality. Can be overridden in subclasses. +

+ + + The method name of the class. + + + The name in the descriptor. + + + True if the names match. + + + + + Convenience property when we have only a single method name + to match. + + + + Use either this property or the + property, + not both. + + + + + + Set the method names defining methods to match. + + +

+ Matching will be the union of all these; if any match, the pointcut matches. +

+ + + + + Convenient class for name-match method pointcuts that hold an Interceptor, + making them an Advisor. + + Juergen Hoeller + Aleksandar Seovic (.NET) + Mark Pollack (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class + for the supplied . + + + + + + The for this pointcut. + + Default is + + The current . + + + + + Convenience property when we have only a single method name + to match. + + + + Use either this property or the + property, + not both. + + + + + + Set the method names defining methods to match. + + +

+ Matching will be the union of all these; if any match, the pointcut matches. +

+ + + + + The that drives this advisor. + + + + + Various related utility methods. + + +

+ These methods are particularly useful for composing pointcuts + using the union and intersection methods. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a union of the two supplied pointcuts. + + The first pointcut. + The second pointcut. + + The union of the two supplied pointcuts. + + + + + + Creates an that is the + intersection of the two supplied pointcuts. + + The first pointcut. + The second pointcut. + + An that is the + intersection of the two supplied pointcuts. + + + + + Performs the least expensive check for a match. + + + The to be evaluated. + + The candidate method. + + The target . + + The arguments to the method + if there is a runtime match. + + + + + Are the supplied s equal? + + The first pointcut. + The second pointcut. + + if the supplied s + are equal. + + + + + Creates a new instance of the + class. + + +

+ This is a utility class, and as such has no publicly + visible constructors. +

+ + + + + Convenient class for regular expression method pointcuts that hold an + , making them an + . + + +

+ Configure this class using the and + pass-through properties. These are analogous + to the and + s properties of the + class. +

+

+ Can delegate to any type of regular expression pointcut. Currently only + pointcuts based on the regular expression classes from the .NET Base + Class Library are supported. The + + property must be a subclass of the + class. +

+

+ This should not normally be set directly. +

+ + Dmitriy Kopylenko + Rod Johnson + Simon White (.NET) + Mark Pollack (.NET) + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class for the supplied . + + The target advice. + + + + + Initialises the pointcut. + + + + + A single pattern to be used during method evaluation. + + + + + Multiple patterns to be used during method evaluation. + + + + + The that drives this advisor. + + + + + Simple implementation that matches + all classes classes (and any derived subclasses) of a give root + . + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + for the supplied + . + + The root . + + If the supplied is . + + + + + Should the pointcut apply to the supplied + ? + + +

+ Returns if the supplied + can be assigned to the root . +

+ + + The candidate . + + + if the advice should apply to the supplied + + + + + + Regular expression based pointcut object. + + +

+ Uses the regular expression classes from the .NET Base Class Library. +

+

+ The regular expressions must be a match. For example, the + .*Get* pattern will match Com.Mycom.Foo.GetBar(), and + Get.* will not. +

+ + Rod Johnson + Simon White (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class, + using the supplied pattern or . + + + The intial pattern value(s) to be matched against. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + If an error was encountered during the deserialization process. + + + + + Initializes the regular expression pointcuts. + + +

+ Can be invoked multiple times. +

+

+ This method will be invoked from the + property, + and also on deserialization. +

+ + + The patterns to initialize. + + + In the case of an invalid pattern. + + + If the supplied is . + + + + + Does the pattern at the supplied + match this ? + + The pattern to match + The index of pattern. + + if there is a match. + + + + + Gets or sets default options that should be used by + regular expressions that don't have options explicitly set. + + + Default options that should be used by regular expressions + that don't have options explicitly set. + + + + + Convenient superclass for s that + are also static pointcuts. + + Rod Johnson + Aleksandar Seovic (.Net) + + + + Creates a new instance of the + + class. + + +

+ This is an abstract class, and as such has no publicly + visible constructors. +

+ + + + + Creates a new instance of the + + class for the supplied + + +

+ This is an abstract class, and as such has no publicly + visible constructors. +

+ + + The advice to use. + + + + + Is this advice associated with a particular instance? + + + if this advice is associated with a + particular instance. + + + Always; this property is not yet supported. + + + + + Returns this s order in the + interception chain. + + + This s order in the + interception chain. + + + + + Return the advice part of this advisor. + + + The advice that should apply if the pointcut matches. + + + + + + The that drives this advisor. + + + + + Defines miscellaneous filter operations. + + Rod Johnson + Aleksandar Seovic (.Net) + + + + Creates a union of two filters. + + +

+ The filter arising from the union will match all of the + that either of the two supplied filters + would match. +

+ + + The first filter. + + + The second filter. + + + The union of the supplied filters. + + + + + Creates the intersection of two filters. + + +

+ The filter arising from the intersection will match all of the + that both of the two supplied filters + would match. +

+ + + The first filter. + + + The second filter. + + + The intersection of the supplied filters. + + + + + Creates a new instance of the + class. + + +

+ This is a utility class, and as such has no publicly visible constructors. +

+ + + + + Union class filter implementation. + + + + + Intersection implementation. + + + + + Simple implementation that matches + a given 's against . + For a list of supported pattern syntax see . + + Erich Eichinger + + + + + Creates a new instance of using a list of given . + + the list patterns to match typenames against. Must not be null. + + + + + Does the supplied type's match any of the ? + + + The candidate . + + + if the matches any of the . + + + + + Returns the list of type name patterns for this filter. + + + + + + A union. + + +

+ Such pointcut unions are tricky, because one cannot simply OR + the respective s: one has to + ascertain that each 's + is also satisfied. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + class. + + The first pointcut. + The second pointcut. + + + + The for this pointcut. + + + The current . + + + + + The for this pointcut. + + + The current . + + + + + Internal method matcher class for union pointcut. + + + + + Abstract superclass for pooling s. + + +

+ Maintains a pool of target instances, acquiring and releasing a target + object from the pool for each method invocation. +

+

+ This class is independent of pooling technology. +

+

+ Subclasses must implement the + and + + methods to work with their chosen pool. The + + method inherited from the + base class + can be used to create objects to put in the pool. Subclasses must also + implement some of the monitoring methods from the + interface. This class + provides the + + method to return an + making these statistics available on proxied objects. +

+

+ This class implements the interface in + order to force subclasses to implement the + method to cleanup and close + down their pool. +

+ + Rod Johnson + Federico Spinazzi (.NET) + + + + Base class for dynamic + implementations that can create new prototype object instances to + support a pooling or new-instance-per-invocation strategy. + + +

+ All such s must run in an + , as they need to + call the + method to create a new prototype instance. +

+ + Rod Johnson + Federico Spinazzi (.NET) + + + + Creates a new instance of the + + class. + + +

+ This is an class, and as such exposes no + public constructors. +

+ + + + + Subclasses should use this method to create a new prototype instance. + + + + + Returns the target object. + + The target object. + + If unable to obtain the target object. + + + + + Releases the target object. + + The target object to release. + + + + Invoked by an + after it has set all object properties supplied + (and satisfied the + + and + interfaces). + + +

+ Ensures that the property has been + set to a valid value (i.e. is not or a string + that consists solely of whitespace). +

+ + + In the event of misconfiguration (such as failure to set an essential + property) or if initialization fails. + + + + + + Returns a textual representation of this target source instance. + This implementation returns + + + + + Returns a textual representation of this target source instance + + + + + The shared instance for this class (and derived classes). + + + + + The name of the target object to be created on each invocation. + + +

+ This object should be a prototype, or the same instance will always + be obtained from the owning . +

+ + + + + The of the target object. + + + + + Is the target source static? + + + if the target source is static. + + + + + The target factory that will be used to perform the lookup + of the object referred to by the + property. + + +

+ Needed so that prototype instances can be created as necessary. +

+ + + The owning + (will never be ). + + + In case of initialization errors. + + + + + + Configuration interface for a pooling invoker. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + The number of active object instances in a pool. + + + + + The number of free object instances in a pool. + + + + + The maximum number of object instances in a pool. + + + + + Creates a new instance of the + + class. + + +

+ This is an class, and as such exposes no + public constructors. +

+ + + + + Returns the target object (acquired from the pool). + + The target object (acquired from the pool). + + If unable to obtain the target object. + + + + + Gets the mixin. + + + An exposing statistics + about the pool maintained by this object. + + + + + Create the pool. + + + The owning , in + case one needs collaborators from it (normally one's own properties + are sufficient). + + + In the case of errors encountered during the creation of the pool. + + + + + Releases the target object (returns it to the pool). + + + The target object to release (return to the pool). + + + In the case that the could not be released. + + + + + Performs application-defined tasks associated with freeing, releasing, or + resetting unmanaged resources. + + +

+ Disposes of the pool. +

+ + + + + The maximum number of object instances in this pool. + + + + + The number of active object instances in this pool. + + + + + The number of free object instances in this pool. + + + + + The target factory that will be used to perform the lookup + of the object referred to by the + + property. + + + The owning + (will never be ). + + + In case of initialization errors. + + + + + + The to be used + when there is no target object, and behavior is supplied by the + advisors. + + +

+ This class is exposed as a singleton. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + The to be used + when there is no target object, and behavior is supplied by the + advisors. + + + + + Creates a new instance of the + class. + + +

+ This is a utility class, and as such has no publicly visible constructors. +

+ + + + + Returns the target object. + + The target object. + + If unable to obtain the target object. + + + + + Releases the target object. + + + + This is a no-op operation in this implementation. + + + The target object to release. + + + + A that represents the current + . + + + A that represents the current + . + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + The of the target object. + + + + + Is the target source static? + + +

+ The + instance is static, and this always returns . +

+ + + if the target source is static. + + + + + implementation that caches a + local target object, but allows the target to be swapped while the + application is running + + +

+ If configuring an object of this class in a Spring IoC container, + use constructor injection to supply the intial target. +

+ + Rod Johnson + Aleksandar Seovic (.Net) + + + + Creates a new instance of the + with the initial target. + + + The initial target. May be . + + + + + Returns the target object. + + The target object. + + If unable to obtain the target object. + + + + + Releases the target object. + + +

+ No-op implementation. +

+ + The target object to release. + + + + Swap the target, returning the old target. + + The new target. + The old target. + + If the new target is . + + + + + Determines whether the specified + is equal to the current . + + +

+ Two invoker interceptors are equal if they have the same target or + if the targets are equal. +

+ + The target source to compare with. + + if this instance is equal to the + specified . + + + + + Serves as a hash function for a particular type, suitable for use + in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + The of the target object. + + +

+ Can return . +

+ + + + + Is the target source static? + + + if the target source is static. + + + + + Statistics for a thread local . + + Rod Johnson + Federico Spinazzi (.NET) + + + + Gets the number of invocations of the + and + methods. + + + The number of invocations of the + and + methods. + + + + + Gets the number of hits that were satisfied by a thread bound object. + + + The number of hits that were satisfied by a thread bound object. + + + + + Gets the number of thread bound objects created. + + The number of thread bound objects created. + + + + implementation that creates a + new instance of the target object for each request. + + +

+ Can only be used in an object factory. +

+ + Rod Johnson + Spinazzi Federico (.NET) + + + + Returns the target object. + + The target object. + + If unable to obtain the target object. + + + + + Releases the target object. + + +

+ No-op implementation. +

+ + The target object to release. + + + + Is the target source static? + + + because this target source is never static. + + + + + Pooling target source implementation based on the + + + Rod Johnson + Federico Spinazzi + + + + Returns the target object (acquired from the pool). + + + The target object (acquired from the pool). + + + If unable to obtain the target object. + + + + + Creates the pool. + + + The owning , in + case one needs collaborators from it (normally one's own properties + are sufficient). + + + + + + Creates a new instance of an appropriate + implementation. + + +

+ Subclasses can, of course, override this method if they want to + return a different implementation. +

+ + + An empty . + + + + + Releases the target object (returns it to the pool). + + The target object to release (return to the pool). + + In the case that the could not be released. + + + + + Performs application-defined tasks associated with freeing, releasing, or + resetting unmanaged resources. + + +

+ Disposes of the pool. +

+ + + + + Creates an instance that can be returned by the pool. + + + An instance that can be returned by the pool. + + + + + + Destroys an instance no longer needed by the pool. + + The instance to be destroyed. + + + + + Ensures that the instance is safe to be returned by the pool. + Returns false if this object should be destroyed. + + The instance to validate. + + if this object is not valid and + should be dropped from the pool, otherwise . + + + + + + Reinitialize an instance to be returned by the pool. + + The instance to be activated. + + + + + Passivates the object. + + The instance returned to the pool. + + + + + The number of active object instances in this pool. + + + + + The number of free object instances in this pool. + + + + + implementation that holds a local + object. + + +

+ This is the default implementation of the + interface used by the AOP + framework. There should be no need to create objects of this class in + application code. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + + for the specified target object. + + The target object to expose. + + If the supplied is + . + + + + + Creates a new instance of the + + for the specified target object. + + The target object to expose. + The type of to expose. + + If the supplied is + . + + + + + Returns the target object. + + The target object. + + If unable to obtain the target object. + + + + + Releases the target object. + + +

+ No-op implementation. +

+ + The target object to release. + + + + Returns a stringified representation of this target source. + + + A stringified representation of this target source. + + + + + Determines whether the specified + is equal to the current . + + The target source to compare with. + + if this instance is equal to the + specified . + + + + + Serves as a hash function for a particular type, suitable for use + in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + The of the target object. + + + + + Is the target source static? + + + because this target source is always static. + + + + + implementation that uses a + threading model in which every thread has its own copy of the target. + + +

+ Alternative to an object pool. +

+

+ Application code is written as to a normal pool; callers can't assume + they will be dealing with the same instance in invocations in different + threads. However, state can be relied on during the operations of a + single thread: for example, if one caller makes repeated calls on the + AOP proxy. +

+

+ This class act both as an introduction and as an interceptor, so it + should be added twice, once as an introduction and once as an + interceptor. +

+ + Rod Johnson + Federico Spinazzi (.NET) + + + + ThreadLocal holding the target associated with the current thread. + + +

+ Unlike most thread local storage which is static, this variable is + meant to be per thread per instance of this class. +

+ + + + + The set of managed targets, enabling us to keep track of the + targets we've created. + + + + + Returns the target object. + + +

+ Tries to locate the target from thread local storage. If no target + is found, a target will be obtained and bound to the thread. +

+ + The target object. + + If unable to obtain the target object. + + + + + + Return an introduction advisor mixin that allows the AOP proxy to be + cast to an reference. + + + + + Cleans up this instance's thread storage, and disposes of any + targets as necessary. + + + + + + Increments Invocations and Hits statistics + + The method invocation joinpoint + The result of the call to IJoinpoint.Proceed(), might be intercepted by the interceptor. + if the interceptors or the target-object throws an exception. + + + + Gets the number of invocations of the and + methods. + + + The number of invocations of the and + methods. + + + + + Gets the number of hits that were satisfied by a thread bound object. + + + The number of hits that were satisfied by a thread bound object. + + + + + Gets the number of thread bound objects created. + + The number of thread bound objects created. + + + + AOP Aspect abstraction, holding a list of s + + + Aleksandar Seovic (.NET) + + + + Gets or sets a list of advisors. + + + A list of advisors. + + + + + Advice that executes after a method returns successfully. + + +

+ After returning advice is invoked only on a normal method + return, but not if an exception is thrown. Such advice can see + the return value of the advised method invocation, but cannot change it. +

+

+ Possible uses for this type of advice would include performing access + control checks on the return value of an advised method invocation, the + ubiquitous logging of method invocation return values (useful during + development), etc. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + + + + Executes after + returns successfully. + + +

+ Note that the supplied cannot + be changed by this type of advice... use the around advice type + () if you + need to change the return value of an advised method invocation. + The data encapsulated by the supplied + can of course be modified though. +

+ + + The value returned by the . + + The intecepted method. + The intercepted method's arguments. + The target object. + + + + + Superinterface for all before advice. + + +

+ Before advice is advice that executes before a joinpoint, but + which does not have the ability to prevent execution flow proceeding to + the joinpoint (unless it throws an ). +

+

+ Spring.NET only supports method before advice. Although this + is unlikely to change, this API is designed to allow field + before advice in future if desired. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + + + + + Subinterface of the AOP Alliance + interface that + allows additional interfaces to be implemented by the interceptor, and + available via a proxy using that interceptor. + + +

+ This is a fundamental AOP concept called introduction. +

+

+ Introductions are often mixins, enabling the building of composite + objects that can achieve many of the goals of multiple inheritance. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Does this + implement the given interface? + + The interface to check. + + if this + + implements the given interface. + + + + + Advice executed before a method is invoked. + + +

+ Such advice cannot prevent the method call proceeding, short of + throwing an . +

+

+ The main advantage of before advice is that there is no + possibility of inadvertently failing to proceed down the interceptor + chain, since there is no need (and indeed means) to invoke the next + interceptor in the call chain. +

+

+ Possible uses for this type of advice would include performing class + invariant checks prior to the actual method invocation, the ubiquitous + logging of method invocations (useful during development), etc. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + + + + + The callback before a given method is invoked. + + The method being invoked. + The arguments to the method. + + The target of the method invocation. May be . + + + Thrown when and if this object wishes to abort the call. Any + exception so thrown will be propagated to the caller. + + + + + Simple marker interface for throws advice. + + +

+ There are no methods on this interface, as methods are discovered and + invoked via reflection. Please do see read the API documentation for the + class; + said documention describes in detail the signature of the methods that + implementations of the interface + must adhere to in the specific case of Spring.NET's implementation of + throws advice. +

+

+ There are any number of possible uses for this type of advice. Some + examples would include the ubiquitous logging of any such exceptions, + monitoring the number and type of exceptions and sending emails to + a support desk once certain criteria have been met, wrapping generic + exceptions such as in + exceptions that are more meaningful to your business logic, etc. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + + + + Canonical that matches + all methods. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Canonical instance that matches all methods. + + +

+ It is not dynamic. +

+ + + + + Creates a new instance of the + class. + + +

+ This is a utility class, and as such has no publicly visible + constructors. +

+ + + + + Does the supplied satisfy this matcher? + Perform static checking. If this returns false, or if the isRuntime() method + returns false, no runtime check will be made. + + The candidate method. + + The target class (may be , in which case the + candidate class must be taken to be the 's + declaring class). + + + if this this method matches statically. + + + + + + Is there a runtime (dynamic) match for the supplied + ? + + The candidate method. + The target class. + The arguments to the method + + if there is a runtime match. + + + + + A that represents the current + . + + + A that represents the current + . + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + Is this dynamic? + + + if this + is dynamic. + + + + + + Canonical instance that matches + everything. + + Rod Johnson + Aleksandar Seovic (.NET) + + + + Canonical instance that matches everything. + + + + + Creates a new instance of the + class. + + +

+ This is a utility class, and as such has no publicly + visible constructors. +

+ + + + + A that represents the current + . + + + A that represents the current + . + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + The for this pointcut. + + + The current . + + + + + The for this pointcut. + + + The current . + + + + + Canonical instances. + + +

+ Only one canonical instance is + provided out of the box. The + matches all classes. +

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Canonical instance that + matches all classes. + + + + + Creates a new instance of the + class. + + +

+ This is a utility class, and as such has no publicly visible + constructors. +

+ + + + + Should the pointcut apply to the supplied + ? + + + The candidate . + + + if the advice should apply to the supplied + + + + + + + A that represents the current + . + + + A that represents the current + . + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + Superclass for all AOP infrastructure exceptions. + + Aleksandar Seovic + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Intercepts the construction of a new object. + + +

+ Such interceptions are nested "on top" of the target. +

+ + + + + Implement this method to perform extra treatments before and after + the consruction of a new object. + + +

+ Polite implementations would certainly like to invoke + . +

+ + + The constructor invocation that is being intercepted. + + + The newly created object, which is also the result of the call to + , and might be + replaced by the interceptor. + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + A description of an invocation to a constuctor, given to an interceptor + upon constructor-call. + + +

+ A constructor invocation is a joinpoint and can be intercepted by a + constructor interceptor. +

+ + + + + + Gets the constructor invocation that is to be invoked. + + +

+ This property is a friendly implementation of the + property. + It should be used in preference to the + property + because it provides immediate access to the underlying constructor + without the need to resort to a cast. +

+ + + The constructor invocation that is to be invoked. + + + + + Base class for different cache advice implementations that provide + access to common functionality, such as obtaining a cache instance. + + Aleksandar Seovic + + + + Shared logger instance + + + + + Create a new default instance. + + + + + Returns an instance based on the cache name. + + The name of the cache. + + Cache instance for the specified if one + is registered in the application context, or null if it isn't. + + + If there's no cache instance registered for the specified . + + + If the cache instance could not be created. + + + If the cache instance registered does not implement the interface. + + + + + Prepares variables for expression evaluation by packaging all + method arguments into a dictionary, keyed by argument name. + + + Method to get parameters info from. + + + Argument values to package. + + + A dictionary containing all method arguments, keyed by method name. + + + + + Evaluates a SpEL expression as a boolean value. + + + The expression string that should be evaluated. + + + The SpEL expression instance that should be evaluated. + + + The object to evaluate expression against. + + + The expression variables dictionary. + + + The evaluated boolean. + + + If the SpEL expression could not be successfuly resolved to a boolean. + + + + + Retrieves custom attribute for the specified attribute type. + + + Method/Parameter to get attribute from. + + + Attribute type. + + + Attribute instance if one is found, null otherwise. + + + + + Retrieves custom attribute for the specified attribute type. + + + Method/Parameter to get attribute from. + + + Attribute type. + + + Attribute instance if one is found, null otherwise. + + + + + Sets the that this + object runs in. + + + + + Caching aspect implementation. + + + This class encapsulates all the advisors that need to be configured to support + Spring's full caching functionality. + + + + + Aleksandar Seovic + + + + Creates a new instance. + + + + + Gets or sets a list of advisors for this aspect. + + + A list of advisors for this aspect. + + + + + Sets the that this + object runs in. + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Implementation of a parameter caching advice. + + +

+ This advice can be used to cache the parameter of the method. +

+

+ Information that determines where, how and for how long the return value + will be cached are retrieved from the s + that are defined on the pointcut. +

+

+ Parameter values are cached *after* the target method is invoked in order to + capture any parameter state changes it might make (for example, it is common + to set an object identifier within the save method for the persistent entity). +

+ + + Aleksandar Seovic + + + + Executes after target + returns successfully. + + +

+ Note that the supplied cannot + be changed by this type of advice... use the around advice type + () if you + need to change the return value of an advised method invocation. + The data encapsulated by the supplied + can of course be modified though. +

+ + + The value returned by the . + + The intecepted method. + The intercepted method's arguments. + The target object. + + + + + Convinience advisor implementation that applies + to all the methods that have defined on one or + more of their parameters. + + Aleksandar Seovic + + + + Creates new advisor instance. + + + + + Returns true if any of the parameters of the specified + has applied. + + + Method to check. + + + Type of target object. + + + true if any of the parameters of the specified + has applied; false otherwise. + + + + + Sets the that this + object runs in. + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Implementation of a result caching advice. + + +

+ This advice can be used to cache the return value of the method. +

+

+ Parameters that determine where, how and for how long the return value + will be cached are retrieved from the and/or + that are defined on the pointcut. +

+ + + + Aleksandar Seovic + + + + Applies caching around a method invocation. + + +

+ This method tries to retrieve an object from the cache, using the supplied + to generate a cache key. If an object is found + in the cache, the cached value is returned and the method call does not + proceed any further down the invocation chain. +

+

+ If object does not exist in the cache, the advised method is called (using + ) + and any return value is cached for the next method invocation. +

+ + + The method invocation that is being intercepted. + + + A cached object or the result of the + call. + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + Obtains return value either from cache or by invoking target method + and caches it if necessary. + + + The method invocation that is being intercepted. + + + Attribute specifying where and how to cache return value. Can be null, + in which case no caching of the result as a whole will be performed + (if the result is collection, individual items could still be cached separately). + + + Variables for expression evaluation. + + + Returns true if the return value was found in cache, false otherwise. + + + Return value for the specified . + + + + + Caches each item from the collection returned by target method. + + + A collection of items to cache. + + + Attributes specifying where and how to cache each item from the collection. + + + Variables for expression evaluation. + + + + + Inner class to help cache null values. + + + + true when other object is of same type. + + + 13 + + + + Convinience advisor implementation that applies + to all the methods that have defined. + + Aleksandar Seovic + + + + Creates new advisor instance. + + + + + Returns true if either or + is applied to the + . + + + Method to check. + + + Type of target object. + + + true if either or + is applied to the + ; false otherwise. + + + + + Sets the that this + object runs in. + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Implementation of a cache invalidation advice. + + +

+ This advice can be used to evict items from the cache. +

+

+ Information that determines which items should be evicted and from which cache + are retrieved from the s that are defined + on the pointcut. +

+

+ Items are evicted *after* target method is invoked. Return value of the method, + as well as method arguments, can be used to determine a list of keys for the items + that should be evicted (return value will be passed as a context for + expression evaluation, and method + arguments will be passed as variables, keyed by argument name). +

+ + + Aleksandar Seovic + + + + Executes after + returns successfully. + + +

+ Note that the supplied cannot + be changed by this type of advice... use the around advice type + () if you + need to change the return value of an advised method invocation. + The data encapsulated by the supplied + can of course be modified though. +

+ + + The value returned by the . + + The intecepted method. + The intercepted method's arguments. + The target object. + + + + + Convinience advisor implementation that applies + to all the methods that have defined. + + Aleksandar Seovic + + + + Creates new advisor instance. + + + + + Sets the that this + object runs in. + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Exception advice to perform exception translation, conversion of exceptions to default return values, and + exception swallowing. Configuration is via a DSL like string for ease of use in common cases as well as + allowing for custom translation logic by leveraging the Spring expression language. + + + + The exception handler collection can be filled with either instances of objects that implement the interface + or a string that follows a simple syntax for most common exception management + needs. The source exceptions to perform processing on are listed immediately after the keyword 'on' and can + be comma delmited. Following that is the action to perform, either log, translate, wrap, replace, return, or + swallow. Following the action is a Spring expression language (SpEL) fragment that is used to either create the + translated/wrapped/replaced exception or specify an alternative return value. The variables available to be + used in the expression language fragment are, #method, #args, #target, and #e which are 1) the method that + threw the exception, the arguments to the method, the target object itself, and the exception that was thrown. + Using SpEL gives you great flexibility in creating a translation of an exception that has access to the calling context. + + Common translation cases, wrap and rethrow, are supported with a shorter syntax where you can specify only + the exception text for the new translated exception. If you ommit the exception text a default value will be + used. + The exceptionsHandlers are compared to the thrown exception in the order they are listed. logging + an exception will continue the evaluation process, in all other cases exceution stops at that point and the + appropriate exceptions handler is executed. + + + + on FooException1 log 'My Message, Method Name ' + #method.Name + on FooException1 translate new BarException('My Message, Method Called = ' + #method.Name", #e) + on FooException2,Foo3Exception wrap BarException 'My Bar Message' + on FooException4 replace BarException 'My Bar Message' + on FooException5 return 32 + on FooException6 swallow + + + + + + + Mark Pollack + + + + This is + + + + + Mark Pollack + + + + Implement this method to perform extra treatments before and after + the call to the supplied . + + +

+ Polite implementations would certainly like to invoke + . +

+ + + The method invocation that is being intercepted. + + + The result of the call to the + method of + the supplied ; this return value may + well have been intercepted by the interceptor. + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Parses the advice expression. + + The advice expression. + An instance of ParsedAdviceExpression + + + + Gets the match using exception constraint expression. + + The advice expression string. + The regex string. + The Match object resulting from the regular expression match. + + + + Override in case you need to initialized non-serialized fields on deserialization. + + + + + Gets or sets the Regex string used to parse advice expressions starting with 'on exception name' and subclass specific actions. + + The regex string to parse advice expressions starting with 'on exception name' and subclass specific actions. + + + + Gets or sets the Regex string used to parse advice expressions starting with 'on exception (constraint)' and subclass specific actions. + + The regex string to parse advice expressions starting with 'on exception (constraint)' and subclass specific actions. + + + + Log instance available to subclasses + + + + + Holds shared handler definition templates + + + + + Implement this method to perform extra treatments before and after + the call to the supplied . + + +

+ Polite implementations would certainly like to invoke + . +

+ + + The method invocation that is being intercepted. + + + The result of the call to the + method of + the supplied ; this return value may + well have been intercepted by the interceptor. + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Invokes handlers registered for the passed exception and + + The exception to be handled + The that raised this exception. + The output of + + + + Parses the specified handler string, creating an instance of IExceptionHander. + + The handler string. + an instance of an exception handler or null if was not able to correctly parse + handler string. + + + + Creates the exception handler. + + The parsed advice expression. + The exception handler instance + + + + Creates the execute spel exception handler. + + The parsed advice expression. + + + + + Creates the return value exception handler. + + The parsed advice expression. + + + + + Creates the swallow exception hander. + + The parsed advice expression. + + + + + Creates the translation exception handler. + + The exception names. + + + + + Creates the log exception handler. + + The exception names. + Log exception + + + + Parses the wrapped exception expression. + + The action. + The handler string. + + + + + Gets or sets the Regex string used to parse advice expressions starting with 'on exception name' and exception handling actions. + + The regex string to parse advice expressions starting with 'on exception name' and exception handling actions. + + + + Gets or sets the Regex string used to parse advice expressions starting with 'on exception (constraint)' and exception handling actions. + + The regex string to parse advice expressions starting with 'on exception (constraint)' and exception handling actions. + + + + Gets or sets the exception handler. + + The exception handler. + + + + Gets the exception handler dictionary. Allows for registration of a specific handler where the key + is the action type. This makes configuration of a custom exception handler easier, for example + LogExceptionHandler, in that only 'user friendly' properties such as LogName, etc., need to be configured + and not 'user unfriendly' properties such as ConstraintExpressionText and ActionExpressionText. + + The exception handler dictionary. + + + + A specialized dictionary for key value pairs of (string, IExceptionHandler) + + + + + Adds the specified key. + + The key. + The value. + + + + Adds an element with the specified key and value into the . + + The key of the element to add. + The value of the element to add. The value can be null. + + is null. + An element with the same key already exists in the . + or key is not a string or value is not an IExceptionHandler. + The is read-only.-or- The has a fixed size. + + + + Gets the with the specified key. + + + + + + Gets the with the specified key. + + + + + + Executes an abribtrary Spring Expression Language (SpEL) expression as an action when handling an exception. + + + + + An abstract base class providing all necessary functionality for typical IExceptionHandler implementations. + + Mark Pollack + + + + Handles a thrown exception providing calling context. + + Mark Pollack + + + + Determines whether this instance can handle the exception the specified exception. + + The exception. + The call context dictionary. + + true if this instance can handle the specified exception; otherwise, false. + + + + + Handles the exception. + + The call context dictionary. + + The return value from handling the exception, if not rethrown or a new exception is thrown. + + + + + Gets the source exception names. + + The source exception names. + + + + Gets the source exception types. + + The source exception types. + + + + Gets the translation expression text + + The translation expression text + + + + Gets or sets the constraint expression text. + + The constraint expression text. + + + + Gets a value indicating whether to continue processing. + + true if continue processing; otherwise, false. + + + + The logging instance + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The exception names. + + + + Determines whether this instance can handle the exception the specified exception. + + The exception. + The call context dictionary. + + true if this instance can handle the specified exception; otherwise, false. + + + + + Handles the exception. + + The return value from handling the exception, if not rethrown or a new exception is thrown. + + + + Gets the source exception names. + + The source exception names. + + + + Gets the source exception types. + + The source exception types. + + + + Gets the action translation expression text + + The action translation expression. + + + + Gets or sets the constraint expression text. + + The constraint expression text. + + + + Gets a value indicating whether to continue processing. + + true if continue processing; otherwise, false. + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The exception names. + + + + Handles the exception. + + The return value from handling the exception, if not rethrown or a new exception is thrown. + + + + Log the exceptions. Default log nameis "LogExceptionHandler" and log level is Debug + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The exception names. + + + + Handles the exception. + + the calling context dictionary + + The return value from handling the exception, if not rethrown or a new exception is thrown. + + + + + Gets or sets the name of the log. + + The name of the log. + + + + Gets or sets the log level. + + The log level. + + + + Gets or sets a value indicating whether to log message only, and not pass in the + exception to the logging API + + true if log message only; otherwise, false. + + + + Gets the action translation expression text. Overridden to add approprate settings to + the SpEL expression that does the logging so that it depends on the values of LogLevel and + LogMessageOnly. Those properties must be set to the desired values before calling this method. + + + The action translation expression. + + + + Evaluates the expression for the return value of the method. + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The exception names. + + + + Returns the result of evaluating the translation expression. + + The return value from handling the exception, if not rethrown or a new exception is thrown. + + + + Returns a token to indicate that this exception should be swallowed. + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The exception names. + + + + Handles the exception. + + The return value from handling the exception, if not rethrown or a new exception is thrown. + + + + Translates from one exception to another based. My wrap or replace exception depending on the expression. + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The exception names. + + + + Handles the exception. + + The return value from handling the exception, if not rethrown or a new exception is thrown. + + + + Abstract base class for logging advice + + + + + Mark Pollack + + + + The default ILog instance used to write logging messages. + + + + + The name of the logger instance to use for obtaining from . + + + + + Indicates whether or not proxy type names should be hidden when using dynamic loggers. + + + + + Creates a new advice instance using this advice type's name for logging by default. + + + + + Creates a new advice instance using the given logger by default. + + + + + Adds logging to the method invocation. + + + The method IsInterceptorEnabled is called + as an optimization to determine if logging should be applied. If logging should be + applied, the method invocation is passed to the InvokeUnderLog method for handling. + If not, the method proceeds as normal. + + + The method invocation that is being intercepted. + + + The result of the call to the + method of + the supplied ; this return value may + well have been intercepted by the interceptor. + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + Determines whether the interceptor is enabled for the specified invocation, that + is, whether the method InvokeUnderLog is called. + + The default behavior is to check whether the given ILog instance + is enabled by calling IsLogEnabled, whose default behavior is to check if + the TRACE level of logging is enabled. Subclasses + The invocation. + The log to write messages to + + true if [is interceptor enabled] [the specified invocation]; otherwise, false. + + + + + Determines whether the given log is enabled. + + + Default is true when the trace level is enabled. Subclasses may override this + to change the level at which logging occurs, or return true to ignore level + checks. + The log instance to check. + + true if log is for a given log level; otherwise, false. + + + + + Subclasses must override this method to perform any tracing around the supplied + IMethodInvocation. + + + Subclasses are resonsible for ensuring that the IMethodInvocation actually executes + by calling IMethodInvocation.Proceed(). + + By default, the passed-in ILog instance will have log level + "trace" enabled. Subclasses do not have to check for this again, unless + they overwrite the IsInterceptorEnabled method to modify + the default behavior. + + + The method invocation to log + The log to write messages to + The result of the call to IMethodInvocation.Proceed() + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + Gets the appropriate log instance to use for the given IMethodInvocation. + + + If the UseDynamicLogger property is set to true, the ILog instance will be + for the target class of the IMethodInvocation, otherwise the log will be the + default static logger. + + The method invocation being logged. + The ILog instance to use. + + + + Sets the default logger to the given name. + + if null, the default logger is removed. + + + + Override in case you need to initialized non-serialized fields on deserialization. + + + + + Sets a value indicating whether to use a dynamic logger or static logger + + Default is to use a static logger. + + Used to determine which ILog instance should be used to write log messages for + a particular method invocation: a dynamic one for the Type getting called, + or a static one for the Type of the trace interceptor. + + + Specify either this property or LoggerName, not both. + + + true if use dynamic logger; otherwise, false. + + + + Sets the name of the logger to use. + + + The name will be passed to the underlying logging implementation through Common.Logging, + getting interpreted as the log category according to the loggers configuration. + + This can be specified to not log into the category of a Type (whether this + interceptor's class or the class getting called) but rather to a specific named category. + + + Specify either this property or UseDynamicLogger, but not both. + + + The name of the logger. + + + + Sets a value indicating whether hide proxy type names (whenever possible) + when using dynamic loggers, i.e. property UseDynamicLogger is set to true. + + true if [hide proxy type names]; otherwise, false. + + + + Configurable advice for logging. + + + + + Mark Pollack + + + + Flag to indicate if unique identifier should be in the log message. + + + + + Flag to indicate if the execution time should be in the log message. + + + + + Flag to indicate if the method arguments should be in the log message. + + + + + Flag to indicate if the return value should be in the log message. + + + + + The separator string to use for delmiting log message fields. + + + + + The log level to use for logging the entry, exit, exception messages. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + if set to true to use dynamic logger, if + false use static logger. + + + + Initializes a new instance of the class. + + the default logger to use + + + + Subclasses must override this method to perform any tracing around the supplied + IMethodInvocation. + + The method invocation to log + The log to write messages to + + The result of the call to IMethodInvocation.Proceed() + + + Subclasses are resonsible for ensuring that the IMethodInvocation actually executes + by calling IMethodInvocation.Proceed(). + + By default, the passed-in ILog instance will have log level + "trace" enabled. Subclasses do not have to check for this again, unless + they overwrite the IsInterceptorEnabled method to modify + the default behavior. + + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + Determines whether the given log is enabled. + + The log instance to check. + + true if log is for a given log level; otherwise, false. + + + Default is true when the trace level is enabled. Subclasses may override this + to change the level at which logging occurs, or return true to ignore level + checks. + + + + Creates a unique identifier. + + + Default implementation uses Guid.NewGuid(). Subclasses may override to provide an alternative + ID generation implementation. + + A unique identifier + + + + Gets the entry message to log + + The invocation. + The id string. + The entry log message + + + + Gets the exception message. + + The method invocation. + The thown exception. + The execution time span. + The id string. + The exception log message. + + + + Gets the exit log message. + + The method invocation. + The return value. + The execution time span. + The id string. + the exit log message + + + + Appends common information across entry,exit, exception logging + + Add method name and unique identifier if required. + The string buffer building logging message. + The method invocation. + The unique identifier string. + + + + Gets the method argument as argumen name/value pairs. + + The method invocation. + string for logging method argument name and values. + + + + Gets or sets a value indicating whether to log a unique identifier with the log message. + + true if [log unique identifier]; otherwise, false. + + + + Gets or sets a value indicating whether to log execution time. + + true if log execution time; otherwise, false. + + + + Gets or sets a value indicating whether log method arguments. + + true if log method arguments]; otherwise, false. + + + + Gets or sets a value indicating whether log return value. + + true if log return value; otherwise, false. + + + + Gets or sets the seperator string to use for delmiting log message fields. + + The seperator. + + + + Gets or sets the entry log level. + + The entry log level. + + + + This advice is typically applied to service-layer methods in order to validate + method arguments. + + + Each argument that should be validated has to be marked with one or more + s. + If the validation fails, this advice will throw , + thus preventing target method invocation. + + + Damjan Tomic + Aleksandar Seovic + + + + Intercepts method invocation and validates arguments. + + + Method invocation. + + + Method arguments. + + + Target object. + + + If one or more method arguments fail validation. + + + + + Sets the application context to search for validators in. + + + The application context to search for validators in. + + + + + Convinience advisor implementation that applies + to all the methods that have defined on one or + more of their parameters. + + Bruno Baia + + + + Creates new advisor instance. + + + + + Returns true if any of the parameters of the specified + has applied. + + + Method to check. + + + Type of target object. + + + true if any of the parameters of the specified + has applied; false otherwise. + + + + + Sets the that this + object runs in. + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + This class contains the results of parsing an advice expresion of the form + on exception name [ExceptionName1,ExceptionName2,...] [action] [action expression] + or + on exception [constraint expression] [action] [action expression] + + + + + Mark Pollack + + + + Initializes a new instance of the class. + + The advice expression. + + + + Gets or sets the advice expression. + + The advice expression. + + + + Gets or sets the exception names. + + The exception names. + + + + Gets or sets the constraint expression. + + The constraint expression. + + + + Gets or sets the action expression text. + + The action expression text. + + + + Gets or sets the action text. + + The action text. + + + + Gets or sets a value indicating whether this is success. + + true if success; otherwise, false. + + + + AOP Advice to retry a method invocation on an exception. The retry semantics are defined by a DSL of the + form on exception name [ExceptionName1,ExceptionName2,...] retry [number of times] [delay|rate] [delay time|rate expression]. + For example, on exception name ArithmeticException retry 3x delay 1s + + + + + Mark Pollack + + + + Creates a new RetryAdvice instance, using for delaying retries + + + + + Creates a new RetryAdvice instance, using any arbitrary callback for delaying retries + + + + + Implement this method to perform extra treatments before and after + the call to the supplied . + + The method invocation that is being intercepted. + + The result of the call to the + method of + the supplied ; this return value may + well have been intercepted by the interceptor. + + +

+ Polite implementations would certainly like to invoke + . +

+ + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Parses the specified handler string. + + The handler string. + + + + + Gets the match for action expression. + + The action expression string. + The regex string. + The Match object resulting from the regular expression match. + + + + Override in case you need to initialized non-serialized fields on deserialization. + + + + + Gets or sets the retry expression. + + The retry expression. + + + + Gets or sets the Regex string used to parse advice expressions starting with 'on exception name' and exception handling actions. + + The regex string to parse advice expressions starting with 'on exception name' and exception handling actions. + + + + Gets or sets the Regex string used to parse advice expressions starting with 'on exception (constraint)' and exception handling actions. + + The regex string to parse advice expressions starting with 'on exception (constraint)' and exception handling actions. + + + + The type of the callback that is called for delaying retries. + + + + + Sleeps for the appropriate amount of time for an exception. + + + + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The exception names. + + + + Handles the exception. + + + + The return value from handling the exception, if not rethrown or a new exception is thrown. + + + + + Gets the maximum retry count. + + The maximum retry count. + + + + Gets a value indicating whether this instance is delay based. + + + true if this instance is delay based; otherwise, false. + + + + + Gets or sets the delay time span to sleep after an exception is thrown and a rety is + attempted. + + The delay time span. + + + + Gets or sets the delay rate expression. + + The delay rate expression. + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Core.dll b/Resources/Libraries/Spring.NET/Spring.Core.dll new file mode 100644 index 00000000..b2170a4c Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Core.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Core.pdb b/Resources/Libraries/Spring.NET/Spring.Core.pdb new file mode 100644 index 00000000..a2fd7e99 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Core.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Core.xml b/Resources/Libraries/Spring.NET/Spring.Core.xml new file mode 100644 index 00000000..a7bd6512 --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Core.xml @@ -0,0 +1,49291 @@ + + + + Spring.Core + + + + + An abstract implementation that can + be used as base class for concrete implementations. + + Aleksandar Seovic + Erich Eichinger + + + + Defines a contract that all cache implementations have to fulfill. + + Aleksandar Seovic + Erich Eichinger + + + + Retrieves an item from the cache. + + + Item key. + + + Item for the specified , or null. + + + + + Removes an item from the cache. + + + Item key. + + + + + Removes collection of items from the cache. + + + Collection of keys to remove. + + + + + Removes all items from the cache. + + + + + Inserts an item into the cache. + + + Items inserted using this method have no expiration time + and default cache priority. + + + Item key. + + + Item value. + + + + + Inserts an item into the cache. + + + Items inserted using this method have default cache priority. + + + Item key. + + + Item value. + + + Item's time-to-live. + + + + + Gets the number of items in the cache. + + + + + Gets a collection of all cache item keys. + + + + + Retrieves an item from the cache. + + + Item key. + + + Item for the specified , or null. + + + + + Removes an item from the cache. + + + Item key. + + + + + Removes collection of items from the cache. + + + Collection of keys to remove. + + + + + Removes all items from the cache. + + + + + Inserts an item into the cache. + + + Items inserted using this method use the default + + + Item key. + + + Item value. + + + + + Inserts an item into the cache. + + + If equals , + or is true, this cache + instance's value will be applied. + + + Item key. + + + Item value. + + + Item's time-to-live (TTL). + + + + + Actually does the cache implementation specific insert operation into the cache. + + + Items inserted using this method have default cache priority. + + + Item key. + + + Item value. + + + Item's time-to-live (TTL). + + + + + Gets/Set the Default time-to-live (TTL) for items inserted into this cache. + Used by + + + + + Gets/Sets a value, whether the this cache instance's + shall be applied to all items, regardless of their individual TTL + when is called. + + + + + Gets the number of items in the cache. + + + May be overridden by subclasses for cache-specific efficient implementation. + + + + + Gets a collection of all cache item keys. + + + + + Abstract base class containing shared properties for all cache attributes. + + Aleksandar Seovic + + + + The instance used to parse values. + + + + + + + Creates an attribute instance. + + + + + Creates an attribute instance. + + + The name of the cache to use. + + + An expression string that should be evaluated in order to determine + the cache key for the item. + + The cache key cannot evaluate be null or an empty string. + + + + Gets or sets the name of the cache to use. + + + The name of the cache to use. + + + + + Gets or sets a SpEL expression that should be evaluated in order + to determine the cache key for the item. + + + An expression string that should be evaluated in order to determine + the cache key for the item. + + + + + Gets an expression instance that should be evaluated in order + to determine the cache key for the item. + + + An expression instance that should be evaluated in order to determine + the cache key for the item. + + + + + Gets or sets a SpEL expression that should be evaluated in order + to determine whether the item should be cached. + + + An expression string that should be evaluated in order to determine + whether the item should be cached. + + + + + Gets an expression instance that should be evaluated in order + to determine whether the item should be cached. + + + An expression instance that should be evaluated in order to determine + whether the item should be cached. + + + + + The amount of time an object should remain in the cache. + + + If no TTL is specified, the default TTL defined by the + cache's policy will be applied. + + + The amount of time object should remain in the cache + formatted to be recognizable by . + + + + + The amount of time an object should remain in the cache (in seconds). + + + If no TTL is specified, the default TTL defined by the + cache's policy will be applied. + + + The amount of time object should remain in the cache (in seconds). + + + + + This attribute should be used to mark methods whose argument(s) + need to be cached. + + +

+ This attribute allows application developers to specify that an argument + of the method should be cached, but it will not do any caching by itself. +

+

+ In order to actually cache the result, an application developer + must apply a Spring.Aspects.Cache.CacheParameterAdvice to + all of the members that have this attribute defined. +

+

+ You can specify this attribute multiple times on the same method in order to + cache several method parameters. +

+ + Aleksandar Seovic + + + + Creates an attribute instance. + + + + + Creates an attribute instance. + + + The name of the cache to use. + + + An expression string that should be evaluated in order to determine + the cache key for the item. + + + + + This attribute should be used to mark methods whose result + needs to be cached. + + +

+ This attribute allows application developers to mark that a result + of the method invocation should be cached, but it will not do any + caching by itself. +

+

+ In order to actually cache the result, an application developer + must apply a Spring.Aspects.Cache.CacheResultAdvice to + all of the members that have this attribute defined. +

+ + Aleksandar Seovic + + + + Creates an attribute instance. + + + + + Creates an attribute instance. + + + The name of the cache to use. + + + An expression string that should be evaluated in order to determine + the cache key for the item. + + + + + This attribute should be used with methods that return an + in order to cache each item separately. + + +

+ This attribute allows application developers to specify that each item + from the collection returned by the method should be cached, + but it will not do any caching by itself. +

+

+ In order to actually cache the result, an application developer + must apply a Spring.Aspects.Cache.CacheResultAdvice to + all of the members that have this attribute defined. +

+ + Aleksandar Seovic + + + + Creates an attribute instance. + + + + + Creates an attribute instance. + + + The name of the cache to use. + + + An expression string that should be evaluated in order to determine + the cache key for the item. + + + + + This attribute should be used to mark method that should + invalidate one or more cache items when invoked. + + +

+ This attribute allows application developers to specify that some + cache items should be evicted from cache when the method is invoked, + but it will not do any eviction by itself. +

+

+ In order to actually evict cache items, an application developer + must apply a Spring.Aspects.Cache.InvalidateCacheAdvice to + all of the members that have this attribute defined. +

+ + Aleksandar Seovic + + + + Creates an attribute instance. + + + + + Creates an attribute instance. + + + The name of the cache to use. + + + + + Gets or sets the name of the cache to use. + + + The name of the cache to use. + + + + + Gets or sets a SpEL expression that should be evaluated in order + to determine the keys for the items that should be evicted. + + + An expression string that should be evaluated in order + to determine the keys for the items that should be evicted. + + + + + Gets an expression instance that should be evaluated in order + to determine the keys for the items that should be evicted. + + + An expression instance that should be evaluated in order + to determine the keys for the items that should be evicted. + + + + + Gets or sets a SpEL expression that should be evaluated in order + to determine whether items should be evicted. + + + An expression string that should be evaluated in order to determine + whether items should be evicted. + + + + + Gets an expression instance that should be evaluated in order + to determine whether items should be evicted. + + + An expression instance that should be evaluated in order to determine + whether items should be evicted. + + + + + A simple implementation backed by a dictionary that + never expires cache items. + + Aleksandar Seovic + + + + Retrieves an item from the cache. + + + Item key. + + + Item for the specified , or null. + + + + + Removes an item from the cache. + + + Item key. + + + + + Removes collection of items from the cache. + + + Collection of keys to remove. + + + + + Removes all items from the cache. + + + + + Inserts an item into the cache. + + + Item key. + + + Item value. + + + Item's time-to-live (TTL) in milliseconds. + + + + + Gets the number of items in the cache. + + + + + Gets a collection of all cache item keys. + + + + +

DictionarySet is an abstract class that supports the creation of new Set + types where the underlying data store is an IDictionary instance.

+ +

You can use any object that implements the IDictionary interface to hold set data. + You can define your own, or you can use one of the objects provided in the Framework. + The type of IDictionary you choose will affect both the performance and the behavior + of the Set using it.

+ +

To make a Set typed based on your own IDictionary, simply derive a + new class with a constructor that takes no parameters. Some Set implmentations + cannot be defined with a default constructor. If this is the case for your class, + you will need to override Clone() as well.

+ +

It is also standard practice that at least one of your constructors takes an ICollection or + an ISet as an argument.

+ + + +

A collection that contains no duplicate elements. This class models the mathematical + Set abstraction, and is the base class for all other Set implementations. + The order of elements in a set is dependant on (a)the data-structure implementation, and + (b)the implementation of the various Set methods, and thus is not guaranteed.

+ +

None of the Set implementations in this library are guranteed to be thread-safe + in any way unless wrapped in a SynchronizedSet.

+ +

The following table summarizes the binary operators that are supported by the Set class.

+ + + Operation + Description + Method + Operator + + + Union (OR) + Element included in result if it exists in either A OR B. + Union() + | + + + Intersection (AND) + Element included in result if it exists in both A AND B. + InterSect() + & + + + Exclusive Or (XOR) + Element included in result if it exists in one, but not both, of A and B. + ExclusiveOr() + ^ + + + Minus (n/a) + Take all the elements in A. Now, if any of them exist in B, remove + them. Note that unlike the other operators, A - B is not the same as B - A. + Minus() + - + + + + + + +

A collection that contains no duplicate elements. This interface models the mathematical + Set abstraction. + The order of elements in a set is dependant on (a)the data-structure implementation, and + (b)the implementation of the various Set methods, and thus is not guaranteed.

+ +

None of the Set implementations in this library are guranteed to be thread-safe + in any way unless wrapped in a SynchronizedSet.

+ +

The following table summarizes the binary operators that are supported by the Set class.

+ + + Operation + Description + Method + + + Union (OR) + Element included in result if it exists in either A OR B. + Union() + + + Intersection (AND) + Element included in result if it exists in both A AND B. + InterSect() + + + Exclusive Or (XOR) + Element included in result if it exists in one, but not both, of A and B. + ExclusiveOr() + + + Minus (n/a) + Take all the elements in A. Now, if any of them exist in B, remove + them. Note that unlike the other operators, A - B is not the same as B - A. + Minus() + + + + + + + Performs a "union" of the two sets, where all the elements + in both sets are present. That is, the element is included if it is in either a or b. + Neither this set nor the input set are modified during the operation. The return value + is a Clone() of this set with the extra elements added in. + + A collection of elements. + A new Set containing the union of this Set with the specified collection. + Neither of the input objects is modified by the union. + + + + Performs an "intersection" of the two sets, where only the elements + that are present in both sets remain. That is, the element is included if it exists in + both sets. The Intersect() operation does not modify the input sets. It returns + a Clone() of this set with the appropriate elements removed. + + A set of elements. + The intersection of this set with a. + + + + Performs a "minus" of set b from set a. This returns a set of all + the elements in set a, removing the elements that are also in set b. + The original sets are not modified during this operation. The result set is a Clone() + of this Set containing the elements from the operation. + + A set of elements. + A set containing the elements from this set with the elements in a removed. + + + + Performs an "exclusive-or" of the two sets, keeping only the elements that + are in one of the sets, but not in both. The original sets are not modified + during this operation. The result set is a Clone() of this set containing + the elements from the exclusive-or operation. + + A set of elements. + A set containing the result of a ^ b. + + + + Returns if the set contains all the elements in the specified collection. + + A collection of objects. + if the set contains all the elements in the specified collection, otherwise. + + + + Adds the specified element to this set if it is not already present. + + The object to add to the set. + is the object was added, if it was already present. + + + + Adds all the elements in the specified collection to the set if they are not already present. + + A collection of objects to add to the set. + is the set changed as a result of this operation, if not. + + + + Remove all the specified elements from this set, if they exist in this set. + + A collection of elements to remove. + if the set was modified as a result of this operation. + + + + Retains only the elements in this set that are contained in the specified collection. + + Collection that defines the set of elements to be retained. + if this set changed as a result of this operation. + + + + Returns if this set contains no elements. + + + + + A collection that contains no duplicate elements. + + +

+ This interface models the mathematical + abstraction. The order of + elements in a set is dependant on (a)the data-structure implementation, and + (b)the implementation of the various + methods, and thus is not + guaranteed. +

+

+ overrides the + method to test for "equivalency": + whether the two sets contain the same elements. The "==" and "!=" + operators are not overridden by design, since it is often desirable to + compare object references for equality. +

+

+ Also, the method is not + implemented on any of the set implementations, since none of them are + truly immutable. This is by design, and it is the way almost all + collections in the .NET framework function. So as a general rule, don't + store collection objects inside + instances. You would typically want to use a keyed + instead. +

+

+ None of the implementations in + this library are guaranteed to be thread-safe in any way unless wrapped + in a . +

+

+ The following table summarizes the binary operators that are supported + by the class. +

+ + + Operation + Description + Method + + + Union (OR) + + Element included in result if it exists in either A OR + B. + + Union() + + + Intersection (AND) + + Element included in result if it exists in both A AND + B. + + InterSect() + + + Exclusive Or (XOR) + + Element included in result if it exists in one, but not both, + of A and B. + + ExclusiveOr() + + + Minus (n/a) + + Take all the elements in A. Now, if any of them exist in + B, remove them. Note that unlike the other operators, + A - B is not the same as B - A. + + Minus() + + + + + + + Performs a "union" of the two sets, where all the elements + in both sets are present. + + +

+ That is, the element is included if it is in either + or this set. Neither this set nor the input + set are modified during the operation. The return value is a + clone of this set with the extra elements added in. +

+ + A collection of elements. + + A new containing the union of + this with the specified + collection. Neither of the input objects is modified by the union. + + + + + Performs an "intersection" of the two sets, where only the elements + that are present in both sets remain. + + +

+ That is, the element is included if it exists in both sets. The + Intersect() operation does not modify the input sets. It + returns a clone of this set with the appropriate elements + removed. +

+ + A set of elements. + + The intersection of this set with . + + + + + Performs a "minus" of this set from the + set. + + +

+ This returns a set of all the elements in set + , removing the elements that are also in + this set. The original sets are not modified during this operation. + The result set is a clone of this + containing the elements from + the operation. +

+ + A set of elements. + + A set containing the elements from this set with the elements in + removed. + + + + + Performs an "exclusive-or" of the two sets, keeping only those + elements that are in one of the sets, but not in both. + + +

+ The original sets are not modified during this operation. The + result set is a clone of this set containing the elements + from the exclusive-or operation. +

+ + A set of elements. + + A set containing the result of + ^ this. + + + + + Returns if this set contains the specified + element. + + The element to look for. + + if this set contains the specified element. + + + + + Returns if the set contains all the + elements in the specified collection. + + A collection of objects. + + if the set contains all the elements in the + specified collection. + + + + + Adds the specified element to this set if it is not already present. + + The object to add to the set. + + is the object was added, + if the object was already present. + + + + + Adds all the elements in the specified collection to the set if + they are not already present. + + A collection of objects to add to the set. + + is the set changed as a result of this + operation. + + + + + Removes the specified element from the set. + + The element to be removed. + + if the set contained the specified element. + + + + + Remove all the specified elements from this set, if they exist in + this set. + + A collection of elements to remove. + + if the set was modified as a result of this + operation. + + + + + Retains only the elements in this set that are contained in the + specified collection. + + + The collection that defines the set of elements to be retained. + + + if this set changed as a result of this + operation. + + + + + Removes all objects from this set. + + + + + Returns if this set contains no elements. + + + + + Performs a "union" of the two sets, where all the elements + in both sets are present. That is, the element is included if it is in either a or b. + Neither this set nor the input set are modified during the operation. The return value + is a Clone() of this set with the extra elements added in. + + A collection of elements. + A new Set containing the union of this Set with the specified collection. + Neither of the input objects is modified by the union. + + + + Performs a "union" of two sets, where all the elements + in both are present. That is, the element is included if it is in either a or b. + The return value is a Clone() of one of the sets (a if it is not ) with elements of the other set + added in. Neither of the input sets is modified by the operation. + + A set of elements. + A set of elements. + A set containing the union of the input sets. if both sets are . + + + + Performs a "union" of two sets, where all the elements + in both are present. That is, the element is included if it is in either a or b. + The return value is a Clone() of one of the sets (a if it is not ) with elements of the other set + added in. Neither of the input sets is modified by the operation. + + A set of elements. + A set of elements. + A set containing the union of the input sets. if both sets are . + + + + Performs an "intersection" of the two sets, where only the elements + that are present in both sets remain. That is, the element is included if it exists in + both sets. The Intersect() operation does not modify the input sets. It returns + a Clone() of this set with the appropriate elements removed. + + A set of elements. + The intersection of this set with a. + + + + Performs an "intersection" of the two sets, where only the elements + that are present in both sets remain. That is, the element is included only if it exists in + both a and b. Neither input object is modified by the operation. + The result object is a Clone() of one of the input objects (a if it is not ) containing the + elements from the intersect operation. + + A set of elements. + A set of elements. + The intersection of the two input sets. if both sets are . + + + + Performs an "intersection" of the two sets, where only the elements + that are present in both sets remain. That is, the element is included only if it exists in + both a and b. Neither input object is modified by the operation. + The result object is a Clone() of one of the input objects (a if it is not ) containing the + elements from the intersect operation. + + A set of elements. + A set of elements. + The intersection of the two input sets. if both sets are . + + + + Performs a "minus" of set b from set a. This returns a set of all + the elements in set a, removing the elements that are also in set b. + The original sets are not modified during this operation. The result set is a Clone() + of this Set containing the elements from the operation. + + A set of elements. + A set containing the elements from this set with the elements in a removed. + + + + Performs a "minus" of set b from set a. This returns a set of all + the elements in set a, removing the elements that are also in set b. + The original sets are not modified during this operation. The result set is a Clone() + of set a containing the elements from the operation. + + A set of elements. + A set of elements. + A set containing A - B elements. if a is . + + + + Performs a "minus" of set b from set a. This returns a set of all + the elements in set a, removing the elements that are also in set b. + The original sets are not modified during this operation. The result set is a Clone() + of set a containing the elements from the operation. + + A set of elements. + A set of elements. + A set containing A - B elements. if a is . + + + + Performs an "exclusive-or" of the two sets, keeping only the elements that + are in one of the sets, but not in both. The original sets are not modified + during this operation. The result set is a Clone() of this set containing + the elements from the exclusive-or operation. + + A set of elements. + A set containing the result of a ^ b. + + + + Performs an "exclusive-or" of the two sets, keeping only the elements that + are in one of the sets, but not in both. The original sets are not modified + during this operation. The result set is a Clone() of one of the sets + (a if it is not ) containing + the elements from the exclusive-or operation. + + A set of elements. + A set of elements. + A set containing the result of a ^ b. if both sets are . + + + + Performs an "exclusive-or" of the two sets, keeping only the elements that + are in one of the sets, but not in both. The original sets are not modified + during this operation. The result set is a Clone() of one of the sets + (a if it is not ) containing + the elements from the exclusive-or operation. + + A set of elements. + A set of elements. + A set containing the result of a ^ b. if both sets are . + + + + Adds the specified element to this set if it is not already present. + + The object to add to the set. + is the object was added, if it was already present. + + + + Adds all the elements in the specified collection to the set if they are not already present. + + A collection of objects to add to the set. + is the set changed as a result of this operation, if not. + + + + Removes all objects from the set. + + + + + Returns if this set contains the specified element. + + The element to look for. + if this set contains the specified element, otherwise. + + + + Returns if the set contains all the elements in the specified collection. + + A collection of objects. + if the set contains all the elements in the specified collection, otherwise. + + + + Removes the specified element from the set. + + The element to be removed. + if the set contained the specified element, otherwise. + + + + Remove all the specified elements from this set, if they exist in this set. + + A collection of elements to remove. + if the set was modified as a result of this operation. + + + + Retains only the elements in this set that are contained in the specified collection. + + Collection that defines the set of elements to be retained. + if this set changed as a result of this operation. + + + + Returns a clone of the Set instance. This will work for derived Set + classes if the derived class implements a constructor that takes no arguments. + + A clone of this object. + + + + Copies the elements in the Set to an array. The type of array needs + to be compatible with the objects in the Set, obviously. + + An array that will be the target of the copy operation. + The zero-based index where copying will start. + + + + Gets an enumerator for the elements in the Set. + + An IEnumerator over the elements in the Set. + + + + Performs CopyTo when called trhough non-generic ISet (ICollection) interface + + + + + + + Performs Union when called trhough non-generic ISet interface + + + + + + + Performs Minus when called trhough non-generic ISet interface + + + + + + + Performs Intersect when called trhough non-generic ISet interface + + + + + + + Performs ExclusiveOr when called trhough non-generic ISet interface + + + + + + + Returns if this set contains no elements. + + + + + The number of elements currently contained in this collection. + + + + + Returns if the Set is synchronized across threads. Note that + enumeration is inherently not thread-safe. Use the SyncRoot to lock the + object during enumeration. + + + + + An object that can be used to synchronize this collection to make it thread-safe. + When implementing this, if your object uses a base object, like an IDictionary, + or anything that has a SyncRoot, return that object instead of "this". + + + + + Indicates whether the given instance is read-only or not + + + if the ISet is read-only; otherwise, . + In the default implementation of Set, this property always returns false. + + + + + Provides the storage for elements in the Set, stored as the key-set + of the IDictionary object. Set this object in the constructor + if you create your own Set class. + + + + + Adds the specified element to this set if it is not already present. + + The to add to the set. + is the object was added, if it was already present. + + + + Adds all the elements in the specified collection to the set if they are not already present. + + A collection of objects to add to the set. + is the set changed as a result of this operation, if not. + + + + Removes all objects from the set. + + + + + Returns if this set contains the specified element. + + The element to look for. + if this set contains the specified element, otherwise. + + + + Returns if the set contains all the elements in the specified collection. + + A collection of objects. + if the set contains all the elements in the specified collection, otherwise. + + + + Removes the specified element from the set. + + The element to be removed. + if the set contained the specified element, otherwise. + + + + Remove all the specified elements from this set, if they exist in this set. + + A collection of elements to remove. + if the set was modified as a result of this operation. + + + + Retains only the elements in this set that are contained in the specified collection. + + Collection that defines the set of elements to be retained. + if this set changed as a result of this operation. + + + + Copies the elements in the Set to an array of T. The type of array needs + to be compatible with the objects in the Set, obviously. + + An array that will be the target of the copy operation. + The zero-based index where copying will start. + + + + Gets an enumerator for the elements in the Set. + + An IEnumerator over the elements in the Set. + + + + Copies the elements in the Set to an array. The type of array needs + to be compatible with the objects in the Set, obviously. Needed for + non-generic ISet methods implementation + + An array that will be the target of the copy operation. + The zero-based index where copying will start. + + + + The placeholder object used as the value for the IDictionary instance. + + + There is a single instance of this object globally, used for all Sets. + + + + + Returns if this set contains no elements. + + + + + The number of elements contained in this collection. + + + + + None of the objects based on DictionarySet are synchronized. Use the + SyncRoot property instead. + + + + + Returns an object that can be used to synchronize the Set between threads. + + + + + Indicates wether the Set is read-only or not + + + + + Implements a Set based on a Dictionary (which is equivalent of + non-genric HashTable) This will give the best lookup, add, and remove + performance for very large data-sets, but iteration will occur in no particular order. + + + + + Creates a new set instance based on a Dictinary. + + + + + Creates a new set instance based on a Dictinary and + initializes it based on a collection of elements. + + A collection of elements that defines the initial set contents. + + + +

Implements an immutable (read-only) Set wrapper.

+

Although this is advertised as immutable, it really isn't. Anyone with access to the + basisSet can still change the data-set. So GetHashCode() is not implemented + for this Set, as is the case for all Set implementations in this library. + This design decision was based on the efficiency of not having to Clone() the + basisSet every time you wrap a mutable Set.

+ + + + + Constructs an immutable (read-only) Set wrapper. + + The Set that is wrapped. + + + + Adds the specified element to this set if it is not already present. + + The object to add to the set. + nothing + is always thrown + + + + Adds all the elements in the specified collection to the set if they are not already present. + + A collection of objects to add to the set. + nothing + is always thrown + + + + Removes all objects from the set. + + is always thrown + + + + Returns if this set contains the specified element. + + The element to look for. + if this set contains the specified element, otherwise. + + + + Returns if the set contains all the elements in the specified collection. + + A collection of objects. + if the set contains all the elements in the specified collection, otherwise. + + + + Removes the specified element from the set. + + The element to be removed. + nothing + is always thrown + + + + Remove all the specified elements from this set, if they exist in this set. + + A collection of elements to remove. + nothing + is always thrown + + + + Retains only the elements in this set that are contained in the specified collection. + + Collection that defines the set of elements to be retained. + nothing + is always thrown + + + + Copies the elements in the Set to an array of T. The type of array needs + to be compatible with the objects in the Set, obviously. + + An array that will be the target of the copy operation. + The zero-based index where copying will start. + + + + Gets an enumerator for the elements in the Set. + + An IEnumerator over the elements in the Set. + + + + Returns a clone of the Set instance. + + A clone of this object. + + + + Performs a "union" of the two sets, where all the elements + in both sets are present. That is, the element is included if it is in either a or b. + Neither this set nor the input set are modified during the operation. The return value + is a Clone() of this set with the extra elements added in. + + A collection of elements. + A new Set containing the union of this Set with the specified collection. + Neither of the input objects is modified by the union. + + + + Performs an "intersection" of the two sets, where only the elements + that are present in both sets remain. That is, the element is included if it exists in + both sets. The Intersect() operation does not modify the input sets. It returns + a Clone() of this set with the appropriate elements removed. + + A set of elements. + The intersection of this set with a. + + + + Performs a "minus" of set b from set a. This returns a set of all + the elements in set a, removing the elements that are also in set b. + The original sets are not modified during this operation. The result set is a Clone() + of this Set containing the elements from the operation. + + A set of elements. + A set containing the elements from this set with the elements in a removed. + + + + Performs an "exclusive-or" of the two sets, keeping only the elements that + are in one of the sets, but not in both. The original sets are not modified + during this operation. The result set is a Clone() of this set containing + the elements from the exclusive-or operation. + + A set of elements. + A set containing the result of a ^ b. + + + + Performs CopyTo when called trhough non-generic ISet (ICollection) interface + + + + + + + Performs Union when called trhough non-generic ISet interface + + + + + + + Performs Minus when called trhough non-generic ISet interface + + + + + + + Performs Intersect when called trhough non-generic ISet interface + + + + + + + Performs ExclusiveOr when called trhough non-generic ISet interface + + + + + + + Returns if this set contains no elements. + + + + + The number of elements contained in this collection. + + + + + Returns an object that can be used to synchronize use of the Set across threads. + + + + + Returns an object that can be used to synchronize the Set between threads. + + + + + Indicates that the given instance is read-only + + + + + Implements an ordered Set based on a dictionary. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + A collection of elements that defines the initial set contents. + + + + Represents a read only wrapper around a generic IDictionary. The design pattern + mirrors ReadOnlyCollection, and follows the apparent pattern that write operations + do not throw an exception, but simply make no change to the underlying collection. + + Originally put into the public domain. + http://www.simple-talk.com/community/forums/thread/2263.aspx + + + + Original from Public Domain + Mark Pollack (.NET) + + + + Inner storage for ReadOnlyDictionary + + + + + Easy access to non-generic dictionary API + + + + + Initializes a new instance of the class. + + The dictionary to wrap. + + + + Add does not change a read only Dictionary + + The object to use as the key of the element to add. + The object to use as the value of the element to add. + The is read-only. + + + + Determines whether the contains an element with the specified key. + + The key to locate in the . + + true if the contains an element with the key; otherwise, false. + + key is null. + + + + Remove does not change a read only Dictionary, will throw an exception. + + The is read-only. + + + + Tries the get value. + + The key. + The value. + + + + + Add does not change a read only Dictionary + + The object to add to the . + The is read-only. + + + + Clear does not change a read only Dictionary. + + The is read-only. + + + + Determines whether the contains a specific value. + + The object to locate in the . + + true if item is found in the ; otherwise, false. + + + + + Copies the elements of the to an , starting at a particular index. + + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + The zero-based index in array at which copying begins. + arrayIndex is less than 0. + array is null. + array is multidimensional.-or-arrayIndex is equal to or greater than the length of array.-or-The number of elements in the source is greater than the available space from arrayIndex to the end of the destination array.-or-Type T cannot be cast automatically to the type of the destination array. + + + + Remove does not change a read only Dictionary. Throws an exception + + The object to remove from the . + + true if item was successfully removed from the ; otherwise, false. This method also returns false if item is not found in the original . + + The is read-only. + + + + Returns an enumerator that iterates through the collection. + + + A that can be used to iterate through the collection. + + + + + Returns an enumerator that iterates through a collection. + + + An object that can be used to iterate through the collection. + + + + + Add does not change a read only Dictionary. Throws an exception. + + The to use as the key of the element to add. + The to use as the value of the element to add. + The is read-only.-or- The has a fixed size. + + + + Determines whether the object contains an element with the specified key. + + The key to locate in the object. + + true if the contains an element with the key; otherwise, false. + + key is null. + + + + Returns an object for the object. + + + An object for the object. + + + + + Remove does not change a read only Dictionary. Throws an exception. + + The key of the element to remove. + The object is read-only.-or- The has a fixed size. + + + + Copies the elements of the to an , starting at a particular index. + + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + The zero-based index in array at which copying begins. + array is null. + index is less than zero. + array is multidimensional.-or- index is equal to or greater than the length of array.-or- The number of elements in the source is greater than the available space from index to the end of the destination array. + The type of the source cannot be cast automatically to the type of the destination array. + + + + Runs when the entire object graph has been deserialized. + + The object that initiated the callback. The functionality for this parameter is not currently implemented. + + + + Populates a with the data needed to serialize the target object. + + The to populate with data. + The destination (see ) for this serialization. + The caller does not have the required permission. + + + + Gets a read only containing the keys of the . + + + An containing the keys of the object that implements . + + + + Gets an containing the values in the . + + + An containing the values in the object that implements . + + + + Gets the value with the specified key. + Set will throw an exception + + + + + Gets the number of elements contained in the . + + + The number of elements contained in the . + + + + Gets a value indicating whether the is read-only. + + + true if the is read-only; otherwise, false. + + + + Gets a value indicating whether the object has a fixed size. + + + true if the object has a fixed size; otherwise, false. + + + + Gets an containing the keys of the . + + + An containing the keys of the object that implements . + + + + Gets an containing the values in the . + + + An containing the values in the object that implements . + + + + Gets the with the specified key. Set throws an exception. + + + The is read-only. + if try to set value + + + + Gets a value indicating whether access to the is synchronized (thread safe). + + + true if access to the is synchronized (thread safe); otherwise, false. + + + + Gets an object that can be used to synchronize access to the . + + + An object that can be used to synchronize access to the . + + + + Implements a Set based on a sorted tree. This gives good performance for operations on very + large data-sets, though not as good - asymptotically - as a HashedSet. However, iteration + occurs in order. Elements that you put into this type of collection must implement IComparable, + and they must actually be comparable. You can't mix string and int values, for example. + + + + + Creates a new set instance based on a sorted tree. + + + + + Creates a new set instance based on a sorted tree. + + The to use for sorting. + + + + Creates a new set instance based on a sorted tree and + initializes it based on a collection of elements. + + A collection of elements that defines the initial set contents. + + + + Creates a new set instance based on a sorted tree and + initializes it based on a collection of elements. + + A collection of elements that defines the initial set contents. + + + + Creates a new set instance based on a sorted tree and + initializes it based on a collection of elements. + + A collection of elements that defines the initial set contents. + The to use for sorting. + + + +

Implements a thread-safe Set wrapper. The implementation is extremely conservative, + serializing critical sections to prevent possible deadlocks, and locking on everything. + The one exception is for enumeration, which is inherently not thread-safe. For this, you + have to lock the SyncRoot object for the duration of the enumeration.

+ + + + + Constructs a thread-safe Set wrapper. + + The Set object that this object will wrap. + + + + Adds the specified element to this set if it is not already present. + + The object to add to the set. + is the object was added, if it was already present. + + + + Adds all the elements in the specified collection to the set if they are not already present. + + A collection of objects to add to the set. + is the set changed as a result of this operation, if not. + + + + Removes all objects from the set. + + + + + Returns if this set contains the specified element. + + The element to look for. + if this set contains the specified element, otherwise. + + + + Returns if the set contains all the elements in the specified collection. + + A collection of objects. + if the set contains all the elements in the specified collection, otherwise. + + + + Removes the specified element from the set. + + The element to be removed. + if the set contained the specified element, otherwise. + + + + Remove all the specified elements from this set, if they exist in this set. + + A collection of elements to remove. + if the set was modified as a result of this operation. + + + + Retains only the elements in this set that are contained in the specified collection. + + Collection that defines the set of elements to be retained. + if this set changed as a result of this operation. + + + + Copies the elements in the Set to an array. The type of array needs + to be compatible with the objects in the Set, obviously. + + An array that will be the target of the copy operation. + The zero-based index where copying will start. + + + + Enumeration is, by definition, not thread-safe. Use a lock on the SyncRoot + to synchronize the entire enumeration process. + + + + + + Returns a clone of the Set instance. + + A clone of this object. + + + + Performs CopyTo when called trhough non-generic ISet (ICollection) interface + + + + + + + Returns if this set contains no elements. + + + + + The number of elements contained in this collection. + + + + + Returns , indicating that this object is thread-safe. The exception to this + is enumeration, which is inherently not thread-safe. Use the SyncRoot object to + lock this object for the entire duration of the enumeration. + + + + + Returns an object that can be used to synchronize the Set between threads. + + + + + Indicates whether given instace is read-only or not + + + + + This class provides skeletal implementations of some + operations. + + +

+ The implementations in this class are appropriate when the base + implementation does not allow elements. The methods + , + , and + are based on + the , + , and + methods + respectively but throw exceptions instead of indicating failure via + or returns. +

+ An implementation that extends this class must + minimally define a method + which does + not permit the insertion of elements, along with methods + , and + . Typically, + additional methods will be overridden as well. If these requirements + cannot be met, consider instead subclassing + }. +

+ + Doug Lea + Griffin Caprio (.NET) + + + + A collection designed for holding elements prior to processing. + + +

+ Besides basic operations, + queues provide additional insertion, extraction, and inspection + operations. +

+

+ Each of these methods exists in two forms: one throws + an exception if the operation fails, the other returns a special + value (either or , depending on the + operation). The latter form of the insert operation is designed + specifically for use with capacity-restricted + implementations; in most implementations, insert operations cannot + fail. +

+

+ Queues typically, but do not necessarily, order elements in a + FIFO (first-in-first-out) manner. Among the exceptions are + priority queues, which order elements according to a supplied + comparator, or the elements' natural ordering, and LIFO queues (or + stacks) which order the elements LIFO (last-in-first-out). + Whatever the ordering used, the head of the queue is that + element which would be removed by a call to + or + . In a FIFO queue, all new + elements are inserted at the tail of the queue. Other kinds of queues may + use different placement rules. Every implementation + must specify its ordering properties. +

+

+ The method inserts an + element if possible, otherwise returning . This differs from the + method, which can fail to + add an element only by throwing an exception. The + method is designed for + use when failure is a normal, rather than exceptional occurrence, for example, + in fixed-capacity (or "bounded" queues. +

+

+ The + methods remove and + return the head of the queue. Exactly which element is removed from the + queue is a function of the queue's ordering policy, which differs from + implementation to implementation. The + and + methods differ only in their + behavior when the queue is empty: the + method throws an exception, + while the method returns + . +

+

+ The and + methods return, but do + not remove, the head of the queue. +

+

+ The interface does not define the blocking queue + methods, which are common in concurrent programming. +

+

+ implementations generally do not allow insertion + of elements, although some implementations, such as + a linked list, do not prohibit the insertion of . + Even in the implementations that permit it, should + not be inserted into a , as is also + used as a special return value by the + method to + indicate that the queue contains no elements. +

+

+ implementations generally do not define + element-based versions of methods + and , but instead inherit the + identity based versions from the class object, because element-based equality + is not always well-defined for queues with the same elements but different + ordering properties. +

+

+ Based on the back port of JCP JSR-166. +

+ + Doug Lea + Griffin Caprio (.NET) + + + + Inserts the specified element into this queue if it is possible to do so + immediately without violating capacity restrictions, returning + upon success and throwing an + if no space is + currently available. + + + The element to add. + + + if successful. + + + If the element cannot be added at this time due to capacity restrictions. + + + If the class of the supplied prevents it + from being added to this queue. + + + If the specified element is and this queue does not + permit elements. + + + If some property of the supplied prevents + it from being added to this queue. + + + + + Inserts the specified element into this queue if it is possible to do + so immediately without violating capacity restrictions. + + +

+ When using a capacity-restricted queue, this method is generally + preferable to , + which can fail to insert an element only by throwing an exception. +

+ + + The element to add. + + + if the element was added to this queue. + + + If the element cannot be added at this time due to capacity restrictions. + + + If the supplied is + . + + + If some property of the supplied prevents + it from being added to this queue. + + + + + Retrieves and removes the head of this queue. + + +

+ This method differs from + only in that it throws an exception if this queue is empty. +

+ + + The head of this queue + + if this queue is empty + + + + Retrieves and removes the head of this queue, + or returns if this queue is empty. + + + The head of this queue, or if this queue is empty. + + + + + Retrieves, but does not remove, the head of this queue. + + +

+ This method differs from + only in that it throws an exception if this queue is empty. +

+ + + The head of this queue. + + If this queue is empty. + + + + Retrieves, but does not remove, the head of this queue, + or returns if this queue is empty. + + + The head of this queue, or if this queue is empty. + + + + + Returns if there are no elements in the , otherwise. + + + + + Creates a new instance of the class. + + +

+ This is an abstract class, and as such has no publicly + visible constructors. +

+ + + + + Inserts the specified element into this queue if it is possible + to do so immediately without violating capacity restrictions. + + + The element to add. + + + if successful. + + + If the element cannot be added at this time due to capacity restrictions. + + + + + Retrieves and removes the head of this queue. + + +

+ This method differs from + only in that + it throws an exception if this queue is empty. +

+ + + The head of this queue + + + If this queue is empty. + + + + + Retrieves, but does not remove, the head of this queue. + + +

+ This method differs from + only in that it throws an exception if this queue is empty. +

+

+ ALso note that this implementation returns the result of + unless the queue + is empty. +

+ + The head of this queue. + + If this queue is empty. + + + + + Removes all of the elements from this queue. + + +

+ The queue will be empty after this call returns. +

+

+ This implementation repeatedly invokes + until it + returns . +

+ + + + + Adds all of the elements in the supplied + to this queue. + + +

+ Attempts to + + of a queue to itself result in . + Further, the behavior of this operation is undefined if the specified + collection is modified while the operation is in progress. +

+

+ This implementation iterates over the specified collection, + and adds each element returned by the iterator to this queue, in turn. + An exception encountered while trying to add an element (including, + in particular, a element) may result in only some + of the elements having been successfully added when the associated + exception is thrown. +

+ + + The collection containing the elements to be added to this queue. + + + if this queue changed as a result of the call. + + + If the supplied or any one of its elements are . + + + If the collection is the current or + the collection size is greater than the queue capacity. + + + + + Inserts the specified element into this queue if it is possible to do + so immediately without violating capacity restrictions. + + +

+ When using a capacity-restricted queue, this method is generally + preferable to , + which can fail to insert an element only by throwing an exception. +

+ + + The element to add. + + + if the element was added to this queue. + + + If the element cannot be added at this time due to capacity restrictions. + + + If the supplied is + . + + + If some property of the supplied prevents + it from being added to this queue. + + + + + Retrieves, but does not remove, the head of this queue, + or returns if this queue is empty. + + + The head of this queue, or if this queue is empty. + + + + + Retrieves and removes the head of this queue, + or returns if this queue is empty. + + + The head of this queue, or if this queue is empty. + + + + + Copies the elements of the to an , starting at a particular index. + + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + The zero-based index in array at which copying begins. + array is null. + index is less than zero. + array is multidimensional.-or- index is equal to or greater than the length of array.-or- The number of elements in the source is greater than the available space from index to the end of the destination array. + The type of the source cannot be cast automatically to the type of the destination array. 2 + + + + Returns an enumerator that iterates through a collection. + + + An object that can be used to iterate through the collection. + + + + + Returns if there are no elements in the , otherwise. + + + + + Returns the current capacity of this queue. + + + + + Gets the number of elements contained in the . + + + The number of elements contained in the . + + + + + Gets an object that can be used to synchronize access to the . + + + An object that can be used to synchronize access to the . + + + + + Gets a value indicating whether access to the is synchronized (thread safe). + + + true if access to the is synchronized (thread safe); otherwise, false. + + + + + Provides a performance improved hashtable with case-insensitive (string-only! based) key handling. + + Erich Eichinger + + + + Creates a case-insensitive hashtable using . + + + + + Creates a case-insensitive hashtable using the given . + + the to calculate the hashcode + + + + Creates a case-insensitive hashtable using the given , initially + populated with entries from another dictionary. + + the dictionary to copy entries from + the to calculate the hashcode + + + + Initializes a new, empty instance of the class that is serializable using the specified and objects. + + A object containing the source and destination of the serialized stream associated with the . + A object containing the information required to serialize the object. + info is null. + + + + Implements the interface and returns the data needed to serialize the . + + + A object containing the source and destination of the serialized stream associated with the . + A object containing the information required to serialize the . + info is null. + + + + Calculate the hashcode of the given string key, using the configured culture. + + + + + + + Compares two keys + + + + + Creates a shallow copy of the current instance. + + + + + is an + class that supports the creation of new + types where the underlying data + store is an instance. + + +

+ You can use any object that implements the + interface to hold set + data. You can define your own, or you can use one of the objects + provided in the framework. The type of + you + choose will affect both the performance and the behavior of the + using it. +

+

+ This object overrides the method, + but not the method, because + the class is mutable. + Therefore, it is not safe to use as a key value in a dictionary. +

+

+ To make a typed based on your + own , simply derive a new + class with a constructor that takes no parameters. Some + implmentations cannot be defined + with a default constructor. If this is the case for your class, you + will need to override clone as well. +

+

+ It is also standard practice that at least one of your constructors + takes an or an + as an argument. +

+ + + + + + A collection that contains no duplicate elements. + + + + + + Performs a "union" of the two sets, where all the elements + in both sets are present. + + A collection of elements. + + A new containing the union of + this with the specified + collection. Neither of the input objects is modified by the union. + + + + + + Performs a "union" of two sets, where all the elements in both are + present. + + +

+ That is, the element is included if it is in either + or . The return + value is a clone of one of the sets ( + if it is not ) with elements of the other set + added in. Neither of the input sets is modified by the operation. +

+ + A set of elements. + A set of elements. + + A set containing the union of the input sets; + if both sets are . + + + + + Performs a "union" of two sets, where all the elements in both are + present. + + A set of elements. + A set of elements. + + A set containing the union of the input sets; + if both sets are . + + + + + + Performs an "intersection" of the two sets, where only the elements + that are present in both sets remain. + + A set of elements. + + The intersection of this set with . + + + + + + Performs an "intersection" of the two sets, where only the elements + that are present in both sets remain. + + +

+ That is, the element is included only if it exists in both + and . Neither input + object is modified by the operation. The result object is a + clone of one of the input objects ( + if it is not ) containing the elements from + the intersect operation. +

+ + A set of elements. + A set of elements. + + The intersection of the two input sets; if + both sets are . + + + + + Performs an "intersection" of the two sets, where only the elements + that are present in both sets remain. + + A set of elements. + A set of elements. + + The intersection of the two input sets; if + both sets are . + + + + + + Performs a "minus" of this set from the + set. + + A set of elements. + + A set containing the elements from this set with the elements in + removed. + + + + + + Performs a "minus" of set from set + . + + +

+ This returns a set of all the elements in set + , removing the elements that are also in + set . The original sets are not modified + during this operation. The result set is a clone of set + containing the elements from the operation. +

+ + A set of elements. + A set of elements. + + A set containing + - elements. + if is + . + + + + + Performs a "minus" of set from set + . + + A set of elements. + A set of elements. + + A set containing + - elements. + if is + . + + + + + + Performs an "exclusive-or" of the two sets, keeping only those + elements that are in one of the sets, but not in both. + + A set of elements. + + A set containing the result of + ^ this. + + + + + + Performs an "exclusive-or" of the two sets, keeping only those + elements that are in one of the sets, but not in both. + + +

+ The original sets are not modified during this operation. The + result set is a clone of one of the sets ( + if it is not ) + containing the elements from the exclusive-or operation. +

+ + A set of elements. + A set of elements. + + A set containing the result of + ^ . + if both sets are . + + + + + Performs an "exclusive-or" of the two sets, keeping only those + elements that are in one of the sets, but not in both. + + A set of elements. + A set of elements. + + A set containing the result of + ^ . + if both sets are . + + + + + + Adds the specified element to this set if it is not already present. + + The object to add to the set. + + is the object was added, + if the object was already present. + + + + + Adds all the elements in the specified collection to the set if + they are not already present. + + A collection of objects to add to the set. + + is the set changed as a result of this + operation. + + + + + Removes all objects from this set. + + + + + Returns if this set contains the specified + element. + + The element to look for. + + if this set contains the specified element. + + + + + Returns if the set contains all the + elements in the specified collection. + + A collection of objects. + + if the set contains all the elements in the + specified collection. + + + + + Removes the specified element from the set. + + The element to be removed. + + if the set contained the specified element. + + + + + Remove all the specified elements from this set, if they exist in + this set. + + A collection of elements to remove. + + if the set was modified as a result of this + operation. + + + + + Retains only the elements in this set that are contained in the + specified collection. + + + The collection that defines the set of elements to be retained. + + + if this set changed as a result of this + operation. + + + + + Returns a clone of the + instance. + + +

+ This will work for derived + classes if the derived class implements a constructor that takes no + arguments. +

+ + A clone of this object. + + + + Copies the elements in the to + an array. + + +

+ The type of array needs to be compatible with the objects in the + , obviously. +

+ + + An array that will be the target of the copy operation. + + + The zero-based index where copying will start. + + + + + Gets an enumerator for the elements in the + . + + + An over the elements + in the . + + + + + This method will test the + against another for + "equality". + + +

+ In this case, "equality" means that the two sets contain the same + elements. The "==" and "!=" operators are not overridden by design. + If you wish to check for "equivalent" + instances, use + Equals(). If you wish to check to see if two references are + actually the same object, use "==" and "!=". +

+ + + A object to compare to. + + + if the two sets contain the same elements. + + + + + Gets the hashcode for the object. + + + + + Returns if this set contains no elements. + + + + + The number of elements currently contained in this collection. + + + + + Returns if the + is synchronized across + threads. + + +

+ Note that enumeration is inherently not thread-safe. Use the + to lock the object during enumeration. +

+ + + + + An object that can be used to synchronize this collection to make + it thread-safe. + + +

+ When implementing this, if your object uses a base object, like an + , or anything that has + a SyncRoot, return that object instead of "this". +

+ + + An object that can be used to synchronize this collection to make + it thread-safe. + + + + + Adds the specified element to this set if it is not already present. + + The object to add to the set. + + is the object was added, + if the object was already present. + + + + + Adds all the elements in the specified collection to the set if + they are not already present. + + A collection of objects to add to the set. + + is the set changed as a result of this + operation. + + + + + Removes all objects from this set. + + + + + Returns if this set contains the specified + element. + + The element to look for. + + if this set contains the specified element. + + + + + Returns if the set contains all the + elements in the specified collection. + + A collection of objects. + + if the set contains all the elements in the + specified collection; also if the + supplied is . + + + + + Removes the specified element from the set. + + The element to be removed. + + if the set contained the specified element. + + + + + Remove all the specified elements from this set, if they exist in + this set. + + A collection of elements to remove. + + if the set was modified as a result of this + operation. + + + + + Retains only the elements in this set that are contained in the + specified collection. + + + The collection that defines the set of elements to be retained. + + + if this set changed as a result of this + operation. + + + + + Copies the elements in the to + an array. + + +

+ The type of array needs to be compatible with the objects in the + , obviously. +

+ + + An array that will be the target of the copy operation. + + + The zero-based index where copying will start. + + + + + Gets an enumerator for the elements in the + . + + + An over the elements + in the . + + + + + Provides the storage for elements in the + , stored as the key-set + of the object. + + +

+ Set this object in the constructor if you create your own + class. +

+ + + + + The placeholder object used as the value for the + instance. + + + There is a single instance of this object globally, used for all + s. + + + + + Returns if this set contains no elements. + + + + + The number of elements currently contained in this collection. + + + + + Returns if the + is synchronized across + threads. + + + + + + An object that can be used to synchronize this collection to make + it thread-safe. + + + An object that can be used to synchronize this collection to make + it thread-safe. + + + + + + Implements an based on a + hash table. + + +

+ This will give the best lookup, add, and remove performance for very + large data-sets, but iteration will occur in no particular order. +

+ + + + + + Creates a new instance of the class. + + + + + Creates a new instance of the class, and + initializes it based on a collection of elements. + + + A collection of elements that defines the initial set contents. + + + + + Implements an that automatically + changes from a list based implementation to a hashtable based + implementation when the size reaches a certain threshold. + + +

+ This is good if you are unsure about whether you data-set will be tiny + or huge. +

+ + Because this uses a dual implementation, iteration order is not + guaranteed! + + + + + + + Creates a new set instance based on either a list or a hash table, + depending on which will be more efficient based on the data-set + size. + + + + + Initializes a new instance of the class with a given capacity + + The size. + + + + Creates a new set instance based on either a list or a hash table, + depending on which will be more efficient based on the data-set + size, and initializes it based on a collection of elements. + + + A collection of elements that defines the initial set contents. + + + + + Implements an immutable (read-only) + wrapper. + + +

+ Although this class is advertised as immutable, it really isn't. + Anyone with access to the wrapped + can still change the data. So + is not implemented for this , as + is the case for all + implementations in this library. This design decision was based on the + efficiency of not having to clone the wrapped + every time you wrap a mutable + . +

+ + + + + Constructs an immutable (read-only) + wrapper. + + + The that is to be wrapped. + + + + + Adds the specified element to this set if it is not already present. + + The object to add to the set. + + is the object was added, + if the object was already present. + + + + + + Adds all the elements in the specified collection to the set if + they are not already present. + + A collection of objects to add to the set. + + is the set changed as a result of this + operation. + + + + + + Removes all objects from this set. + + + + + + Returns if this set contains the specified + element. + + The element to look for. + + if this set contains the specified element. + + + + + Returns if the set contains all the + elements in the specified collection. + + A collection of objects. + + if the set contains all the elements in the + specified collection. + + + + + Removes the specified element from the set. + + The element to be removed. + + if the set contained the specified element. + + + + + + Remove all the specified elements from this set, if they exist in + this set. + + A collection of elements to remove. + + if the set was modified as a result of this + operation. + + + + + + Retains only the elements in this set that are contained in the + specified collection. + + + The collection that defines the set of elements to be retained. + + + if this set changed as a result of this + operation. + + + + + + Copies the elements in the to + an array. + + +

+ The type of array needs to be compatible with the objects in the + , obviously. +

+ + + An array that will be the target of the copy operation. + + + The zero-based index where copying will start. + + + + + Gets an enumerator for the elements in the + . + + + An over the elements + in the . + + + + + Returns a clone of the + instance. + + A clone of this object. + + + + Performs a "union" of the two sets, where all the elements + in both sets are present. + + A collection of elements. + + A new containing the union of + this with the specified + collection. Neither of the input objects is modified by the union. + + + + + + Performs an "intersection" of the two sets, where only the elements + that are present in both sets remain. + + A set of elements. + + The intersection of this set with . + + + + + + Performs a "minus" of this set from the + set. + + A set of elements. + + A set containing the elements from this set with the elements in + removed. + + + + + + Performs an "exclusive-or" of the two sets, keeping only those + elements that are in one of the sets, but not in both. + + A set of elements. + + A set containing the result of + ^ this. + + + + + + Returns if this set contains no elements. + + + + + The number of elements currently contained in this collection. + + + + + Returns if the + is synchronized across + threads. + + +

+ Note that enumeration is inherently not thread-safe. Use the + to lock the object during enumeration. +

+ + + + + An object that can be used to synchronize this collection to make + it thread-safe. + + + An object that can be used to synchronize this collection to make + it thread-safe. + + + + + Simple linked list implementation. + + Simon White + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class that contains all + elements of the specified list. + + + A list of elements that defines the initial contents. + + + + + Removes the object at the specified index. + + The lookup index. + + If the specified is greater than the + number of objects within the list. + + + + + Inserts an object at the specified index. + + The lookup index. + The object to be inserted. + + If the specified is greater than the + number of objects within the list. + + + + + Removes the first instance of the specified object found. + + The object to remove + + + + Returns if this list contains the specified + element. + + The element to look for. + + if this list contains the specified element. + + + + + Removes all objects from the list. + + + + + Returns the index of the first instance of the specified + found. + + The object to search for + + The index of the first instance found, or -1 if the element was not + found. + + + + + Adds the specified object to the end of the list. + + The object to add + The index that the object was added at. + + + + Adds all of the elements of the supplied + list to the end of this list. + + The list of objects to add. + + + + Checks whether the list can be modified. + + + If the list cannot be modified. + + + + + Validates the specified index. + + The lookup index. + + If the index is invalid. + + + + + Returns the node at the specified index. + + The lookup index. + The node at the specified index. + + If the specified is greater than the + number of objects within the list. + + + + + Returns the node (and index) of the first node that contains + the specified value. + + The value to search for. + + The node, or if not found. + + + + + Removes the specified node. + + The node to be removed. + + + + Copies the elements in this list to an array. + + +

+ The type of array needs to be compatible with the objects in this + list, obviously. +

+ + + An array that will be the target of the copy operation. + + + The zero-based index where copying will start. + + + If the supplied is . + + + If the supplied is less than zero + or is greater than the length of . + + + If the supplied is of insufficient size. + + + + + Gets an enumerator for the elements in the + . + + +

+ Enumerators are fail fast. +

+ + + An over the elements + in the . + + + + + Is list read only? + + + if the list is read only. + + + + + Returns the node at the specified index. + + +

+ This is the indexer for the + class. +

+ + + + + + Is the list a fixed size? + + + if the list is a fixed size list. + + + + + Returns if the list is synchronized across + threads. + + + + This implementation always returns . + +

+ Note that enumeration is inherently not thread-safe. Use the + to lock the object during enumeration. +

+ + + + + The number of objects within the list. + + + + + An object that can be used to synchronize this + to make it thread-safe. + + + An object that can be used to synchronize this + to make it thread-safe. + + + + + Implements a based on a list. + + +

+ Performance is much better for very small lists than either + or . + However, performance degrades rapidly as the data-set gets bigger. Use a + instead if you are not sure your data-set + will always remain very small. Iteration produces elements in the order they were added. + However, element order is not guaranteed to be maintained by the various + mathematical operators. +

+ + + + + Creates a new set instance based on a list. + + + + + Creates a new set instance based on a list and initializes it based on a + collection of elements. + + + A collection of elements that defines the initial set contents. + + + + + Thrown when an element is requested from an empty . + + Griffin Caprio + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the + class with the + specified message. + + + A message about the exception. + + + + + Creates a new instance of the + class with the + specified message. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + An unbounded priority based on a priority + heap. This queue orders elements according to an order specified + at construction time, which is specified either according to their + natural order (see , or according to a + , depending on which constructor is + used. A priority queue does not permit elements. + A priority queue relying on natural ordering also does not + permit insertion of non-comparable objects (doing so will result + . + +

+ The head of this queue is the lowest element + with respect to the specified ordering. If multiple elements are + tied for lowest value, the head is one of those elements -- ties are + broken arbitrarily. + +

+ A priority queue is unbounded, but has an internal + capacity governing the size of an array used to store the + elements on the queue. It is always at least as large as the queue + size. As elements are added to a priority queue, its capacity + grows automatically. The details of the growth policy are not + specified. + +

+ This class and its enumerator implement all of the + optional methods of the and + interfaces. + The enumerator provided in method + is not guaranteed to traverse the elements of the PriorityQueue in any + particular order. + +

+ Note that this implementation is NOT synchronized. + Multiple threads should not access a + instance concurrently if any of the threads modifies the list + structurally. Instead, use the thread-safe PriorityBlockingQueue. +

+ Josh Bloch + Griffin Caprio (.NET) + + + + Priority queue represented as a balanced binary heap: the two children + of queue[n] are queue[2*n] and queue[2*n + 1]. The priority queue is + ordered by comparator, or by the elements' natural ordering, if + comparator is null: For each node n in the heap and each descendant d + of n, n <= d. + + The element with the lowest value is in queue[1], assuming the queue is + nonempty. (A one-based array is used in preference to the traditional + zero-based array to simplify parent and child calculations.) + + queue.length must be >= 2, even if size == 0. + + + + The number of elements in the priority queue. + + + + The comparator, or null if priority queue uses elements' + natural ordering. + + + + + The number of times this priority queue has been + structurally modified. + + + + + Creates a with the default initial capacity + (11) that orders its elements according to their natural + ordering (using ). + + + + + Creates a with the specified initial capacity + that orders its elements according to their natural ordering + (using ). + + the initial capacity for this priority queue. + + if is less than 1. + + + + Creates a with the specified initial capacity + that orders its elements according to the specified comparator. + + the initial capacity for this priority queue. + the comparator used to order this priority queue. + If then the order depends on the elements' natural ordering. + + if is less than 1. + + + + Creates a containing the elements in the + specified collection. The priority queue has an initial + capacity of 110% of the size of the specified collection or 1 + if the collection is empty. If the specified collection is an + instance of a , the priority queue will be sorted + according to the same comparator, or according to its elements' + natural order if the collection is sorted according to its + elements' natural order. Otherwise, the priority queue is + ordered according to its elements' natural order. + + the collection whose elements are to be placed into this priority queue. + if elements of cannot be + compared to one another according to the priority queue's ordering + if or any element with it is + + + + + + Common code to initialize underlying queue array across + constructors below. + + + + + Performs an unsigned bitwise right shift with the specified number + + Number to operate on + Ammount of bits to shift + The resulting number from the shift operation + + + + Establishes the heap invariant assuming the heap + satisfies the invariant except possibly for the leaf-node indexed by k + (which may have a nextExecutionTime less than its parent's). + + + This method functions by "promoting" queue[k] up the hierarchy + (by swapping it with its parent) repeatedly until queue[k] + is greater than or equal to its parent. + + + + + Establishes the heap invariant (described above) in the subtree + rooted at k, which is assumed to satisfy the heap invariant except + possibly for node k itself (which may be greater than its children). + + + This method functions by "demoting" queue[k] down the hierarchy + (by swapping it with its smaller child) repeatedly until queue[k] + is less than or equal to its children. + + + + + Establishes the heap invariant in the entire tree, + assuming nothing about the order of the elements prior to the call. + + + + + Returns the of or - 1, + whichever is smaller. + + base size + percentage to return + of + + + + Initially fill elements of the queue array under the + knowledge that it is sorted or is another , in which + case we can just place the elements in the order presented. + + + + + Initially fill elements of the queue array that is not to our knowledge + sorted, so we must rearrange the elements to guarantee the heap + invariant. + + + + + Removes and returns element located at from queue. (Recall that the queue + is one-based, so 1 <= i <= size.) + + + Normally this method leaves the elements at positions from 1 up to i-1, + inclusive, untouched. Under these circumstances, it returns . + Occasionally, in order to maintain the heap invariant, it must move + the last element of the list to some index in the range [2, i-1], + and move the element previously at position (i/2) to position i. + Under these circumstances, this method returns the element that was + previously at the end of the list and is now at some position between + 2 and i-1 inclusive. + + + + Resize array, if necessary, to be able to hold given index + + + + Inserts the specified element into this queue if it is possible to do + so immediately without violating capacity restrictions. + + +

+ When using a capacity-restricted queue, this method is generally + preferable to , + which can fail to insert an element only by throwing an exception. +

+ + + The element to add. + + + if the element was added to this queue. + + + if the specified element cannot be compared + with elements currently in the priority queue according + to the priority queue's ordering. + + + If the element cannot be added at this time due to capacity restrictions. + + + If the supplied is + and this queue does not permit + elements. + + + If some property of the supplied prevents + it from being added to this queue. + + + + + Retrieves, but does not remove, the head of this queue, + or returns if this queue is empty. + + + The head of this queue, or if this queue is empty. + + + + + Inserts the specified element into this queue if it is possible to do so + immediately without violating capacity restrictions, returning + upon success and throwing an + if no space is + currently available. + + + The element to add. + + + if successful. + + + If the element cannot be added at this time due to capacity restrictions. + + + If the specified element is and this queue does not + permit elements. + + + If some property of the supplied prevents + it from being added to this queue. + + + if the specified element cannot be compared + with elements currently in the priority queue according + to the priority queue's ordering. + + + + + Removes a single instance of the specified element from this + queue, if it is present. + + + + + Returns an over the elements in this queue. + The enumeratoar does not return the elements in any particular order. + + an enumerator over the elements in this queue. + + + + Removes all elements from the priority queue. + The queue will be empty after this call returns. + + + + + Retrieves and removes the head of this queue, + or returns if this queue is empty. + + + The head of this queue, or if this queue is empty. + + + + + Queries the queue to see if it contains the specified + + element to look for. + if the queue contains the , + otherwise. + + + Returns the comparator used to order this collection, or + if this collection is sorted according to its elements natural ordering + (using ). + + + the comparator used to order this collection, or + if this collection is sorted according to its elements natural ordering. + + + + + Save the state of the instance to a stream (that + is, serialize it). + + The length of the array backing the instance is + emitted (int), followed by all of its elements (each an + ) in the proper order. + + the stream + the context + + + + Reconstitute the instance from a stream (that is, + deserialize it). + + the stream + the context + + + + Copies the elements of the to an , starting at a particular index. + + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + The zero-based index in array at which copying begins. + array is null. + index is less than zero. + array is multidimensional.-or- index is equal to or greater than the length of array.-or- The number of elements in the source is greater than the available space from index to the end of the destination array. + The type of the source cannot be cast automatically to the type of the destination array. 2 + + + + Copies the elements of the to an , starting at index 0. + + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + array is null. + index is less than zero. + array is multidimensional.-or- index is equal to or greater than the length of array.-or- The number of elements in the source is greater than the available space from index to the end of the destination array. + The type of the source cannot be cast automatically to the type of the destination array. 2 + + + + Gets the Capacity of this queue. Will equal + + + + + Returns the queue count. + + + + + Gets an object that can be used to synchronize access to the . + + + An object that can be used to synchronize access to the . + + + + + Gets a value indicating whether access to the is synchronized (thread safe). + + + true if access to the is synchronized (thread safe); otherwise, false. + + + + + Returns if there are no elements in the , otherwise. + + + + + Index (into queue array) of element to be returned by subsequent call to next. + + + + + Implements an based on a sorted + tree. + + +

+ This gives good performance for operations on very large data-sets, + though not as good - asymptotically - as a + . However, iteration occurs + in order. +

+

+ Elements that you put into this type of collection must implement + , and they must actually be comparable. + You can't mix and + values, for example. +

+

+ This implementation does + not support elements that are . +

+ + + + + + Creates a new set instance based on a sorted tree. + + + + + Creates a new set instance based on a sorted tree using for ordering. + + + + + Creates a new set instance based on a sorted tree and initializes + it based on a collection of elements. + + + A collection of elements that defines the initial set contents. + + + + + Synchronized that should be returned by synchronized + dictionary implementations in order to ensure that the enumeration is thread safe. + + Aleksandar Seovic + + + + Synchronized that should be returned by synchronized + collections in order to ensure that the enumeration is thread safe. + + Aleksandar Seovic + + + + Synchronized that, unlike hashtable created + using method, synchronizes + reads from the underlying hashtable in addition to writes. + + +

+ In addition to synchronizing reads, this implementation also fixes + IEnumerator/ICollection issue described at + http://msdn.microsoft.com/en-us/netframework/aa570326.aspx + (search for SynchronizedHashtable for issue description), by implementing + interface explicitly, and returns thread safe enumerator + implementations as well. +

+

+ This class should be used whenever a truly synchronized + is needed. +

+ + Aleksandar Seovic + + + + Initializes a new instance of + + + + + Initializes a new instance of + + + + + Initializes a new instance of , copying inital entries from + handling keys depending on . + + + + + Creates a instance that + synchronizes access to the underlying . + + the hashtable to be synchronized + + + + Creates a wrapper that synchronizes + access to the passed . + + the hashtable to be synchronized + + + + Adds an element with the provided key and value to the object. + + The to use as the value of the element to add. + The to use as the key of the element to add. + An element with the same key already exists in the object. + key is null. + The is read-only.-or- The has a fixed size. 2 + + + + Removes all elements from the object. + + The object is read-only. 2 + + + + Creates a new object that is a copy of the current instance. + + + A new object that is a copy of this instance. + + + + + Determines whether the object contains an element with the specified key. + + + true if the contains an element with the key; otherwise, false. + + The key to locate in the object. + key is null. 2 + + + + Returns, whether this contains an entry with the specified . + + The key to look for + , if this contains an entry with this + + + + Returns, whether this contains an entry with the specified . + + The valúe to look for + , if this contains an entry with this + + + + Copies the elements of the to an , starting at a particular index. + + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + The zero-based index in array at which copying begins. + array is null. + The type of the source cannot be cast automatically to the type of the destination array. + index is less than zero. + array is multidimensional.-or- index is equal to or greater than the length of array.-or- The number of elements in the source is greater than the available space from index to the end of the destination array. 2 + + + + Returns an object for the object. + + + An object for the object. + + + + + Removes the element with the specified key from the object. + + The key of the element to remove. + The object is read-only.-or- The has a fixed size. + key is null. 2 + + + + Returns an enumerator that iterates through a collection. + + + An object that can be used to iterate through the collection. + + + + + Gets a value indicating whether the object is read-only. + + + true if the object is read-only; otherwise, false. + + + + + Gets a value indicating whether the object has a fixed size. + + + true if the object has a fixed size; otherwise, false. + + + + + Gets a value indicating whether access to the is synchronized (thread safe). + + + true if access to the is synchronized (thread safe); otherwise, false. + + + + + Gets an object containing the keys of the object. + + + An object containing the keys of the object. + + + + + Gets an object containing the values in the object. + + + An object containing the values in the object. + + + + + Gets an object that can be used to synchronize access to the . + + + An object that can be used to synchronize access to the . + + + + + Gets the number of elements contained in the . + + + The number of elements contained in the . + + + + + Gets or sets the element with the specified key. + + + The element with the specified key. + + The key of the element to get or set. + The property is set and the object is read-only.-or- The property is set, key does not exist in the collection, and the has a fixed size. + key is null. 2 + + + + Implements a thread-safe wrapper. + + +

+ The implementation is extremely conservative, serializing critical + sections to prevent possible deadlocks, and locking on everything. The + one exception is for enumeration, which is inherently not thread-safe. + For this, you have to lock the SyncRoot object for the + duration of the enumeration. +

+ + + + + + Constructs a thread-safe + wrapper. + + + The object that this object + will wrap. + + + If the supplied ecposes a + SyncRoot value. + + + + + Adds the specified element to this set if it is not already present. + + The object to add to the set. + + is the object was added, + if the object was already present. + + + + + Adds all the elements in the specified collection to the set if + they are not already present. + + A collection of objects to add to the set. + + is the set changed as a result of this + operation. + + + + + Removes all objects from this set. + + + + + Returns if this set contains the specified + element. + + The element to look for. + + if this set contains the specified element. + + + + + Returns if the set contains all the + elements in the specified collection. + + A collection of objects. + + if the set contains all the elements in the + specified collection; also if the + supplied is . + + + + + Removes the specified element from the set. + + The element to be removed. + + if the set contained the specified element. + + + + + Remove all the specified elements from this set, if they exist in + this set. + + A collection of elements to remove. + + if the set was modified as a result of this + operation. + + + + + Retains only the elements in this set that are contained in the + specified collection. + + + The collection that defines the set of elements to be retained. + + + if this set changed as a result of this + operation. + + + + + Copies the elements in the to + an array. + + +

+ The type of array needs to be compatible with the objects in the + , obviously. +

+ + + An array that will be the target of the copy operation. + + + The zero-based index where copying will start. + + + + + Gets an enumerator for the elements in the + . + + + An over the elements + in the . + + + + + Returns a clone of the instance. + + A clone of this object. + + + + Returns if this set contains no elements. + + + + + The number of elements currently contained in this collection. + + + + + Returns if the + is synchronized across + threads. + + + + + + An object that can be used to synchronize this collection to make + it thread-safe. + + + An object that can be used to synchronize this collection to make + it thread-safe. + + + + + + Simple listener that logs application events to the console. + + +

+ Intended for use during debugging only. +

+ + Rod Johnson + Griffin Caprio (.NET) + + + + + A listener for application events. + + Rod Johnson + Griffin Caprio (.NET) + + + + Handle an application event. + + + The source of the event. + + + The event that is to be handled. + + + + + Creates a new instance of the + class. + + + + + Handle an application event. + + + The source of the event. + + + The event that is to be handled. + + + + + Event object sent to listeners registered with an + to inform them of + context lifecycle events. + + Griffin Caprio (.NET) + + + + + + + Encapsulates the data associated with an event raised by an + . + + Rod Johnson + Mark Pollack (.NET) + Griffin Caprio (.NET) + + + + + Creates a new instance of the + class. + + + + + The date and time when the event occured. + + + The date and time when the event occured. + + + + + The system time in milliseconds when the event happened. + + + The system time in milliseconds when the event happened. + + + + + Creates a new instance of the ContextEventArgs class to represent the + supplied context event. + + The type of context event. + + + + Returns a string representation of this object. + + A string representation of this object. + + + + The event type. + + + + + The various context event types. + + + + + The event type when the context is refreshed or created. + + + + + The event type when the context is closed. + + + + + Event object sent to listeners registered with an + to inform them of + context lifecycle event. + + + + + Event object sent to listeners registered with an + to inform them of + context lifecycle event. + + + + + Partial implementation of the + interface. + + +

+ Does not mandate the type of storage used for configuration, but does + implement common functionality. Uses the Template Method design + pattern, requiring concrete subclasses to implement + methods. +

+

+ In contrast to a plain vanilla + , an + is supposed + to detect special objects defined in its object factory: therefore, + this class automatically registers + s, + s + and s that are + defined as objects in the context. +

+

+ An may be also supplied as + an object in the context, with the special, well-known-name of + "messageSource". Else, message resolution is delegated to the + parent context. +

+ + Rod Johnson + Juergan Hoeller + Griffin Caprio (.NET) + + + + + + Configurable implementation of the + interface. + + +

+ This implementation + supports the configuration of resource access protocols and the + corresponding .NET types that know how to handle those protocols. +

+

+ Basic protocol-to-resource type mappings are also defined by this class, + while others can be added either internally, by application contexts + extending this class, or externally, by the end user configuring the + context. +

+

+ Only one resource type can be defined for each protocol, but multiple + protocols can map to the same resource type (for example, the + "http" and "ftp" protocols both map to the + type. The protocols that are + mapped by default can be found in the following list. +

+

+ + + assembly + + + config + + + file + + + http + + + https + + +

+ + Aleksandar Seovic + + + + + + + Describes an object that can load + s. + + +

+ An implementation is + generally required to support the functionality described by this + interface. +

+

+ The class is a + standalone implementation that is usable outside an + ; the aforementioned + class is also used by the + class. +

+ + Juergen Hoeller + Mark Pollack (.NET) + + + + + + + Return an handle for the + specified resource. + + +

+ The handle should always be a reusable resource descriptor; this + allows one to make repeated calls to the underlying + . +

+

+

    +
  • + Must support fully qualified URLs, e.g. "file:C:/test.dat". +
    • +
  • + Should support relative file paths, e.g. "test.dat" (this will be + implementation-specific, typically provided by an + implementation). +
    • +
+

+ + An handle does not imply an + existing resource; you need to check the value of an + 's + property to determine + conclusively whether or not the resource actually exists. + + + The resource location. + + An appropriate handle. + + + + + + + + The separator between the protocol name and the resource name. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class using the specified default protocol for unqualified resources. + + + + + Returns a that has been + mapped to the protocol of the supplied . + + The name of the resource. + + A new instance for the + supplied . + + + If a + mapping does not exist for the supplied . + + + In the case of any errors arising from the instantiation of the + returned instance. + + + + + + Checks that the supplied starts + with one of the protocol names currently mapped by this + instance. + + The name of the resource. + + if the supplied + starts with one of the known + protocols; if not, or if the supplied + is itself . + + + + + Extracts the protocol name from the supplied + . + + The name of the resource. + + The extracted protocol name or if the + supplied is unqualified (or + is itself ). + + + + + The default protocol to use for unqualified resources. + + +

+ The initial value is "file". +

+ + + + + Provides the means to configure an application context in addition to + the methods exposed on the + interface. + + +

+ This interface is to be implemented by most (if not all) + implementations. +

+

+ Configuration and lifecycle methods are encapsulated here to avoid + making them obvious to + client code. +

+

+ Calling will close this + application context, releasing all resources and locks that the + implementation might hold. This includes disposing all cached + singleton objects. +

+ + does not invoke the + attendant on any parent + context. + + + Juergen Hoeller + Mark Pollack (.NET) + + + + + + The central interface to Spring.NET's IoC container. + + +

+ implementations + provide: + + + + Object factory functionality inherited from the + + and + interfaces. + + + + + The ability to resolve messages, supporting internationalization. + Inherited from the + interface. + + + + + The ability to load file resources in a generic fashion. + Inherited from the + interface. + + + + + Acts an an event registry for supporting loosely coupled eventing + between objecs. Inherited from the + interface. + + + + + The ability to raise events related to the context lifecycle. Inherited + from the + interface. + + + + + Inheritance from a parent context. Definitions in a descendant context + will always take priority. + + + +

+

+ In addition to standard object factory lifecycle capabilities, + implementations need + to detect + , + , and + objects and supply + their attendant dependencies accordingly. +

+

+ This interface is the central client interface in Spring.NET's IoC + container implementation. As such it does inherit a quite sizeable + number of interfaces; implementations are strongly encouraged to use + composition to satisfy each of the inherited interfaces (where + appropriate of course). +

+ + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + + + + + + + + Extension of the interface + to be implemented by object factories that can enumerate all their object instances, + rather than attempting object lookup by name one by one as requested by clients. + + +

+ implementations that preload + all their objects (for example, DOM-based XML factories) may implement this + interface. This interface is discussed in + "Expert One-on-One J2EE Design and Development", by Rod Johnson. +

+

+ If this is an , + the return values will not take any + hierarchy into account, but + will relate only to the objects defined in the current factory. + Use the helper class to + get all objects. +

+

+ With the exception of + , + the methods and properties in this interface are not designed for frequent + invocation. Implementations may be slow. +

+ + Rod Johnson + Rick Evans (.NET) + + + + The root interface for accessing a Spring.NET IoC container. + + + + This is the basic client view of a Spring.NET IoC container; further interfaces + such as and + + are available for specific purposes such as enumeration and configuration. + + + This is the root interface to be implemented by objects that can hold a number + of object definitions, each uniquely identified by a + name. An independent instance of any of these objects can be obtained + (the Prototype design pattern), or a single shared instance can be obtained + (a superior alternative to the Singleton design pattern, in which the instance is a + singleton in the scope of the factory). Which type of instance + will be returned depends on the object factory configuration - the API is the same. + The Singleton approach is more useful and hence more common in practice. + + + The point of this approach is that the IObjectFactory is a central registry of + application components, and centralizes the configuring of application components + (no more do individual objects need to read properties files, for example). + See chapters 4 and 11 of "Expert One-on-One J2EE Design and Development" for a + discussion of the benefits of this approach. + + + Normally an IObjectFactory will load object definitions stored in a configuration + source (such as an XML document), and use the + namespace to configure the objects. However, an implementation could simply return + .NET objects it creates as necessary directly in .NET code. There are no + constraints on how the definitions could be stored: LDAP, RDBMS, XML, properties + file etc. Implementations are encouraged to support references amongst objects, + to either Singletons or Prototypes. + + + In contrast to the methods in + , all of the methods + in this interface will also check parent factories if this is an + . If an object is + not found in this factory instance, the immediate parent is asked. Objects in + this factory instance are supposed to override objects of the same name in any + parent factory. + + + Object factories are supposed to support the standard object lifecycle interfaces + as far as possible. The maximum set of initialization methods and their standard + order is: + + + + + + 's + property. + + + + + 's + property. + + + + + + (only applicable if running within an ). + + + + + The + + method of + s. + + + + + 's + method. + + + + + A custom init-method definition. + + + + + The + + method of + s. + + + + +

+ + On shutdown of an object factory, the following lifecycle methods apply: + + + + + + 's + method. + + + + + A custom destroy-method definition. + + + + + + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + +

+ Is this object a singleton? + + + + That is, will + always return the same object? + + + Will ask the parent factory if the object cannot be found in this factory + instance. + + + The name of the object to query. + True if the named object is a singleton. + + If there's no such object definition. + + + + + Determines whether the specified object name is prototype. That is, will GetObject + always return independent instances? + + This method returning false does not clearly indicate a singleton object. + It indicated non-independent instances, which may correspond to a scoped object as + well. use the IsSingleton property to explicitly check for a shared + singleton instance. + Translates aliases back to the corresponding canonical object name. Will ask the + parent factory if the object can not be found in this factory instance. + + + + The name of the object to query + + true if the specified object name will always deliver independent instances; otherwise, false. + + if there is no object with the given name. + + + + Does this object factory contain an object with the given name? + + + + The concrete lookup strategy depends on the implementation. E.g. s + will also search their parent factory if a name isn't found . + + + The name of the object to query. + True if an object with the given name is defined. + + + + Return the aliases for the given object name, if defined. + + + + Will ask the parent factory if the object cannot be found in this factory + instance. + + + The object name to check for aliases. + The aliases, or an empty array if none. + + If there's no such object definition. + + + + + Return an instance (possibly shared or independent) of the given object name. + + + + This method allows an object factory to be used as a replacement for the + Singleton or Prototype design pattern. + + + Note that callers should retain references to returned objects. There is no + guarantee that this method will be implemented to be efficient. For example, + it may be synchronized, or may need to run an RDBMS query. + + + Will ask the parent factory if the object cannot be found in this factory + instance. + + + The name of the object to return. + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + + + Return an instance (possibly shared or independent) of the given object name. + + + + This method allows an object factory to be used as a replacement for the + Singleton or Prototype design pattern. + + + Note that callers should retain references to returned objects. There is no + guarantee that this method will be implemented to be efficient. For example, + it may be synchronized, or may need to run an RDBMS query. + + + Will ask the parent factory if the object cannot be found in this factory + instance. + + + The name of the object to return. + + The arguments to use if creating a prototype using explicit arguments to + a static factory method. If there is no factory method and the + arguments are not null, then match the argument values by type and + call the object's constructor. + + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + If the supplied is . + + + + + Return an instance (possibly shared or independent) of the given object name. + + The name of the object to return. + + The the object may match. Can be an interface or + superclass of the actual class. For example, if the value is the + class, this method will succeed whatever the + class of the returned instance. + + + The arguments to use if creating a prototype using explicit arguments to + a factory method. If there is no factory method and the + supplied array is not , then + match the argument values by type and call the object's constructor. + + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + If the object is not of the required type. + + + If the supplied is . + + + + + + Return an instance (possibly shared or independent) of the given object name. + + + + Provides a measure of type safety by throwing an exception if the object is + not of the required . + + + This method allows an object factory to be used as a replacement for the + Singleton or Prototype design pattern. + + + Note that callers should retain references to returned objects. There is no + guarantee that this method will be implemented to be efficient. For example, + it may be synchronized, or may need to run an RDBMS query. + + + Will ask the parent factory if the object cannot be found in this factory + instance. + + + The name of the object to return. + + the object may match. Can be an interface or + superclass of the actual class. For example, if the value is the + class, this method will succeed whatever the + class of the returned instance. + + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + If the object is not of the required type. + + + + + Determine the type of the object with the given name. + + + + More specifically, checks the type of object that + would return. + For an , returns the type + of object that the creates. + + + The name of the object to query. + + The type of the object or if not determinable. + + + + + Determines whether the object with the given name matches the specified type. + + More specifically, check whether a GetObject call for the given name + would return an object that is assignable to the specified target type. + Translates aliases back to the corresponding canonical bean name. + Will ask the parent factory if the bean cannot be found in this factory instance. + + The name of the object to query. + Type of the target to match against. + + true if the object type matches; otherwise, false + if it doesn't match or cannot be determined yet. + + Ff there is no object with the given name + + + + + Return an unconfigured(!) instance (possibly shared or independent) of the given object name. + + The name of the object to return. + + The the object may match. Can be an interface or + superclass of the actual class. For example, if the value is the + class, this method will succeed whatever the + class of the returned instance. + + + The arguments to use if creating a prototype using explicit arguments to + a factory method. If there is no factory method and the + supplied array is not , then + match the argument values by type and call the object's constructor. + + The unconfigured(!) instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + If the object is not of the required type. + + + If the supplied is . + + + + This method will only instantiate the requested object. It does NOT inject any dependencies! + + + + + Injects dependencies into the supplied instance + using the named object definition. + + + + In addition to being generally useful, typically this method is used to provide + dependency injection functionality for objects that are instantiated outwith the + control of a developer. A case in point is the way that the current (1.1) + ASP.NET classes instantiate web controls... the instantiation takes place within + a private method of a compiled page, and thus cannot be hooked into the + typical Spring.NET IOC container lifecycle for dependency injection. + + + + The following code snippet assumes that the instantiated factory instance + has been configured with an object definition named + 'ExampleNamespace.BusinessObject' that has been configured to set the + Dao property of any ExampleNamespace.BusinessObject instance + to an instance of an appropriate implementation... + + namespace ExampleNamespace + { + public class BusinessObject + { + private IDao _dao; + + public BusinessObject() {} + + public IDao Dao + { + get { return _dao; } + set { _dao = value; } + } + } + } + + with the corresponding driver code looking like so... + + IObjectFactory factory = GetAnIObjectFactoryImplementation(); + BusinessObject instance = new BusinessObject(); + factory.ConfigureObject(instance, "object_definition_name"); + // at this point the dependencies for the 'instance' object will have been resolved... + + + + The object instance that is to be so configured. + + + The name of the object definition expressing the dependencies that are to + be injected into the supplied instance. + + + If there is no object definition for the supplied . + + + If any of the target object's dependencies could not be created. + + + + + Determine whether this object factory treats object names case-sensitive or not. + + + + + Return an instance (possibly shared or independent) of the given object name. + + + + This method allows an object factory to be used as a replacement for the + Singleton or Prototype design pattern. + + + Note that callers should retain references to returned objects. There is no + guarantee that this method will be implemented to be efficient. For example, + it may be synchronized, or may need to run an RDBMS query. + + + Will ask the parent factory if the object cannot be found in this factory + instance. + + + This is the indexer for the + interface. + + + The name of the object to return. + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + + + Check if this object factory contains an object definition with the given name. + + +

+ Does not consider any hierarchy this factory may participate in. +

+ + Ignores any singleton objects that have been registered by other means + than object definitions. + + + The name of the object to look for. + + if this object factory contains an object + definition with the given name. + + + + + Return the names of all objects defined in this factory. + + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + Return the names of objects matching the given + (including subclasses), judging from the object definitions. + + +

+ Does consider objects created by s, + or rather it considers the type of objects created by + (which means that + s will be instantiated). +

+

+ Does not consider any hierarchy this factory may participate in. +

+ + + The (class or interface) to match, or + for all object names. + + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + Return the names of objects matching the given + (including subclasses), judging from the object definitions. + + +

+ Does consider objects created by s, + or rather it considers the type of objects created by + (which means that + s will be instantiated). +

+

+ Does not consider any hierarchy this factory may participate in. + Use + to include beans in ancestor factories too. + <p>Note: Does <i>not</i> ignore singleton objects that have been registered + by other means than bean definitions. +

+ + + The (class or interface) to match, or + for all object names. + + + Whether to include prototype objects too or just singletons (also applies to + s). + + + Whether to include s too + or just normal objects. + + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + Return the object instances that match the given object + (including subclasses), judging from either object + definitions or the value of + in the case of + s. + + +

+ This version of the + method matches all kinds of object definitions, be they singletons, prototypes, or + s. Typically, the results + of this method call will be the same as a call to + IListableObjectFactory.GetObjectsOfType(type,true,true) . +

+ + + The (class or interface) to match. + + + A of the matching objects, + containing the object names as keys and the corresponding object instances + as values. + + + If the objects could not be created. + + + + + Return the object instances that match the given object + (including subclasses), judging from either object + definitions or the value of + in the case of + s. + + + The (class or interface) to match. + + + Whether to include prototype objects too or just singletons (also applies to + s). + + + Whether to include s too + or just normal objects. + + + A of the matching objects, + containing the object names as keys and the corresponding object instances + as values. + + + If the objects could not be created. + + + + + Return the number of objects defined in the factory. + + + The number of objects defined in the factory. + + + + + Sub-interface implemented by object factories that can be part + of a hierarchy. + + Rod Johnson + Rick Evans (.NET) + + + + Determines whether the local object factory contains a bean of the given name, + ignoring object defined in ancestor contexts, also resolving a given alias if necessary. + This is an alternative to ContainsObject, ignoring an object + of the given name from an ancestor object factory. + + The name of the object to query. + + true if objects with the specified name is defined in the local factory; otherwise, false. + + + + + Return the parent object factory, or + if this factory does not have a parent. + + + The parent object factory, or + if this factory does not have a parent. + + + + + Describes an object that can resolve messages. + + +

+ This enables the parameterization and internationalization of messages. +

+

+ Spring.NET provides one out-of-the-box implementation for production + use: +

    +
  • .
    • +
+

+ + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + Aleksandar Seovic (.NET) + + + + + Resolve the message identified by the supplied + . + + +

+ If the lookup is not successful, implementations are permitted to + take one of two actions. +

+ + + Throw an exception. + + + + Return the supplied as is. + + + + + The name of the message to resolve. + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + + + Resolve the message identified by the supplied + . + + +

+ If the lookup is not successful, implementations are permitted to + take one of two actions. +

+ + + Throw an exception. + + + + Return the supplied as is. + + + + + The name of the message to resolve. + + The array of arguments that will be filled in for parameters within + the message, or if there are no parameters + within the message. Parameters within a message should be + referenced using the same syntax as the format string for the + method. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + + + Resolve the message identified by the supplied + . + + + Note that the fallback behavior based on CultureInfo seem to + have a bug that is fixed by installed .NET 1.1 Service Pack 1. +

+ If the lookup is not successful, implementations are permitted to + take one of two actions. +

+ + + Throw an exception. + + + + Return the supplied as is. + + + + + The name of the message to resolve. + + The that represents + the culture for which the resource is localized. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + + + Resolve the message identified by the supplied + . + + + Note that the fallback behavior based on CultureInfo seem to + have a bug that is fixed by installed .NET 1.1 Service Pack 1. +

+ If the lookup is not successful, implementations are permitted to + take one of two actions. +

+ + + Throw an exception. + + + + Return the supplied as is. + + + + + The name of the message to resolve. + + The that represents + the culture for which the resource is localized. + + + The array of arguments that will be filled in for parameters within + the message, or if there are no parameters + within the message. Parameters within a message should be + referenced using the same syntax as the format string for the + method. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + + + Resolve the message identified by the supplied + . + + + Note that the fallback behavior based on CultureInfo seem to + have a bug that is fixed by installed .NET 1.1 Service Pack 1. +

+ If the lookup is not successful, implementations are permitted to + take one of two actions. +

+ + + Throw an exception. + + + + Return the supplied as is. + + + + + The name of the message to resolve. + The default message if name is not found. + + The that represents + the culture for which the resource is localized. + + + The array of arguments that will be filled in for parameters within + the message, or if there are no parameters + within the message. Parameters within a message should be + referenced using the same syntax as the format string for the + method. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + + + Resolve the message using all of the attributes contained within + the supplied + argument. + + + The value object storing those attributes that are required to + properly resolve a message. + + + The that represents + the culture for which the resource is localized. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + If the message could not be resolved. + + + + + Gets a localized resource object identified by the supplied + . + + +

+ This method must use the + + value to obtain a resource. +

+

+ Examples of resources that may be resolved by this method include + (but are not limited to) objects such as icons and bitmaps. +

+ + + The name of the resource object to resolve. + + + The resolved object, or if not found. + + + + + Gets a localized resource object identified by the supplied + . + + +

+ Examples of resources that may be resolved by this method include + (but are not limited to) objects such as icons and bitmaps. +

+ + + The name of the resource object to resolve. + + + The with which the + resource is associated. + + + The resolved object, or if not found. + + + + + Applies resources to object properties. + + +

+ Resource key names are of the form objectName.propertyName. +

+ + + An object that contains the property values to be applied. + + + The base name of the object to use for key lookup. + + + The with which the + resource is associated. + + + + + Encapsulates event publication functionality. + + +

+ Serves as a super-interface for the + interface. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + Publishes an application context event. + + + The source of the event. May be . + + + The event that is to be raised. + + + + + A registry that manages subscriptions to and the + publishing of events. + + Griffin Caprio + + + + Publishes all events of the source object. + + + The source object containing events to publish. + + + + + Subscribes to all events published, if the subscriber + implements compatible handler methods. + + The subscriber to use. + + + + Subscribes to the published events of all objects of a given + , if the subscriber implements + compatible handler methods. + + The subscriber to use. + + The target to subscribe to. + + + + + Unsubscribes to all events published, if the subscriber + implmenets compatible handler methods. + + The subscriber to use + + + + Unsubscribes to the published events of all objects of a given + , if the subscriber implements + compatible handler methods. + + The subscriber to use. + + The target to unsubscribe from + + + + + Raised in response to an application context event. + + + + + Returns the date and time this context was loaded. + + +

+ This is to be set immediately after an + has been + instantiated and its configuration has been loaded. Implementations + are permitted to update this value if the context is reset or + refreshed in some way. +

+ + + The representing when this context + was loaded. + + + + + + Gets the parent context, or if there is no + parent context. + + +

+ If the parent context is , then this context + is the root of any context hierarchy. +

+ + + The parent context, or if there is no + parent. + + + + + Gets and sets a name for this context. + + + A name for this context. + + + + + Interface defining methods for start/stop lifecycle control. + The typical use case for this is to control asynchronous processing. + + + + Can be implemented by both components (typically a Spring object defined in + a spring and containers + (typically a spring . Containers will + propagate start/stop signals to all components that apply. + + + Juergen Hoeller + Mark Pollack (.NET) + + + + Starts this component. + + Should not throw an exception if the component is already running. + In the case of a container, this will propagate the start signal + to all components that apply. + + + + + Stops this component. + + + Should not throw an exception if the component isn't started yet. + In the case of a container, this will propagate the stop signal + to all components that apply. + + + + + Gets a value indicating whether this component is currently running. + + + In the case of a container, this will return true + only if all components that apply are currently running. + + + true if this component is running; otherwise, false. + + + + + Add an + + that will get applied to the internal object factory of this + application context on refresh, before any of the object + definitions are evaluated. + + +

+ To be invoked during context configuration. +

+ + + The factory processor to register. + + + + + + Load or refresh the persistent representation of the configuration, + which might an XML file, properties file, or relational database schema. + + + If the configuration cannot be loaded. + + + If the object factory could not be initialized. + + + + + Return the internal object factory of this application context. + + +

+ Can be used to access specific functionality of the factory. +

+ + This is just guaranteed to return an instance that is not + after the context has been refreshed + at least once. + + + Do not use this to post-process the object factory; singletons + will already have been instantiated. Use an + + to intercept the object factory setup process before objects even + get touched. + + + + + + + Sets the parent of this application context. + + + + The parent should not be changed: it should only be set + outside a constructor if it isn't available when an instance of + this class is created. + + + + The parent context. + + + + + Interface for registries that hold object definitions, i.e. + + and + + instances. + + +

+ Typically implemented by object factories that work with the + + hierarchy internally. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + Determine whether the given object name is already in use within this registry, + i.e. whether there is a local object or alias registered under this name. + + + + + Return the names of all objects defined in this registry. + + + The names of all objects defined in this registry, or an empty array + if none defined + + + + + Check if this registry contains a object definition with the given name. + + + The name of the object to look for. + + + True if this object factory contains an object definition with the + given name. + + + + + Returns the + + for the given object name. + + + The name of the object to find a definition for. + + + The for + the given name (never null). + + + If the object definition cannot be resolved. + + + In case of errors. + + + + + Register a new object definition with this registry. + Must support + + and . + + + The name of the object instance to register. + + + The definition of the object instance to register. + + +

+ Must support + and + . +

+ + + If the object definition is invalid. + + + + + Return the aliases for the given object name, if defined. + + the object name to check for aliases + + +

+ Will ask the parent factory if the object cannot be found in this + factory instance. +

+ + + The aliases, or an empty array if none. + + + If there's no such object definition. + + + + + Given a object name, create an alias. We typically use this method to + support names that are illegal within XML ids (used for object names). + + + The name of the object. + + + The alias that will behave the same as the object name. + + + If there is no object with the given name. + + + If the alias is already in use. + + + + + Return the number of objects defined in the registry. + + + The number of objects defined in the registry. + + + + + Name of the .Net config section that contains Spring.Net context definition. + + + + + Default name of the root context. + + + + + The special, well-known-name of the default + in the context. + + +

+ If no can be found + in the context using this lookup key, then message resolution + will be delegated to the parent context (if any). +

+ + + + + The special, well-known-name of the default + in the context. + + +

+ If no can be found + in the context using this lookup key, then a default + will be used. +

+ + + + + The instance for this class. + + + + + The instance we delegate + our implementation of said interface to. + + + + + The instance we + delegate our implementation of said interface to. + + + + + Creates a new instance of the + with no parent context. + + +

+ This is an class, and as such exposes + no public constructors. +

+ + + + + Creates a new instance of the + with no parent context. + + +

+ This is an class, and as such exposes + no public constructors. +

+ + Flag specifying whether to make this context case sensitive or not. + + + + Creates a new instance of the + with the supplied parent context. + + +

+ This is an class, and as such exposes + no public constructors. +

+ + The application context name. + Flag specifying whether to make this context case sensitive or not. + The parent application context. + + + + Adds the given to the list of standard + processors being added to the underlying + + + Each time is called on this context, the context ensures, that + all default s are registered with the underlying . + + The instance. + + + + Closes this context and disposes of any resources (such as + singleton objects in the wrapped + ). + + + + + Subclasses must implement this method to perform the actual + configuration loading. + + +

+ This method is invoked by + , + before any other initialization occurs. +

+ + + In the case of errors encountered while refreshing the object factory. + + + + + Returns the internal object factory of the parent context if it implements + ; else, + returns the parent context itself. + + + The parent context's object factory, or the parent itself. + + + + + Raises an application context event. + + + Any arguments to the event. May be . + + + + + Raises an application context event. + + + The source of the event. + + + Any arguments to the event. May be . + + + + + Create the strategy to be used + + + + + Modify the application context's internal object factory after its standard + initialization. + + +

+ All object definitions will have been loaded, but no objects + will have been instantiated yet. This allows for the registration + of special + s + in certain + implementations. +

+ + + The object factory used by the application context. + + + In the case of errors. + . + + + + Template method which can be overridden to add context-specific + work before the underlying object factory gets refreshed. + + + + + Template method which can be overridden to add context-specific + refresh work. + + +

+ Called on initialization of special objects, before instantiation + of singletons. +

+ + + + + Template method which can be overridden to add context-specific + work after the context was refreshed but before the + event gets raised. + + + + + Instantiate and invoke all registered + + objects, respecting any explicit ordering. + + + + Must be called before singleton instantiation. + + + In the case of errors. + + + + Resets the well-known ObjectPostProcessorChecker that logs an info + message when an object is created during IObjectPostProcessor + instantiation, i.e. when an object is not eligible for being + processed by all IObjectPostProcessors. + + + + + Initializes the default event registry for this context. + + + + + Returns the internal message source of the parent context if said + parent context is an , else + simply the parent context itself. + + + The internal message source of the parent context if said + parent context is an , else + simply the parent context itself. + + + + + Initializes the default message source for this context. + + +

+ Uses any parent context's message source if one is not available + in this context. +

+ + + + + Add a new + that will get applied to the internal object factory of this application context + on refresh, before any of the object definitions are evaluated. + + + The factory processor to register. + + + + + Load or refresh the persistent representation of the configuration, + which might an XML file, properties file, or relational database schema. + + + If the configuration cannot be loaded. + + + If the object factory could not be initialized. + + + + + Registers well-known s and + preregisters well-known dependencies using + + the raw object factory as returned from + + + + Ensures, that predefined ObjectPostProcessors are registered with this ObjectFactory + + + + + + Starts this component. + + Should not throw an exception if the component is already running. + In the case of a container, this will propagate the start signal + to all components that apply. + + + + + Stops this component. + + + Should not throw an exception if the component isn't started yet. + In the case of a container, this will propagate the stop signal + to all components that apply. + + + + + Return the names of objects matching the given + (including subclasses), judging from the object definitions. + + + The (class or interface) to match, or + for all object names. + + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + + Return the names of objects matching the given + (including subclasses), judging from the object definitions. + + + The (class or interface) to match, or + for all object names. + + + Whether to include prototype objects too or just singletons (also applies to + s). + + + Whether to include s too + or just normal objects. + + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + + Return the names of all objects defined in this factory. + + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + + Return the registered + for the + given object, allowing access to its property values and constructor + argument values. + + The name of the object. + + The registered + . + + + If there is no object with the given name. + + + In the case of errors. + + + + + Return the registered + for the + given object, allowing access to its property values and constructor + argument values. + + The name of the object. + Whether to search parent object factories. + + The registered + . + + + If there is no object with the given name. + + + In the case of errors. + + + + + Return the object instances that match the given object + (including subclasses), judging from either object + definitions or the value of + in the case of + s. + + + The (class or interface) to match. + + + A of the matching objects, + containing the object names as keys and the corresponding object instances + as values. + + + If the objects could not be created. + + + + + + Return the object instances that match the given object + (including subclasses), judging from either object + definitions or the value of + in the case of + s. + + + The (class or interface) to match. + + + Whether to include prototype objects too or just singletons (also applies to + s). + + + Whether to include s too + or just normal objects. + + + A of the matching objects, + containing the object names as keys and the corresponding object instances + as values. + + + If the objects could not be created. + + + + + + Check if this object factory contains an object definition with the given name. + + The name of the object to look for. + + True if this object factory contains an object definition with the given name. + + + + + + Does this object factory contain an object with the given name? + + The name of the object to query. + + if an object with the given name is defined. + + + + + + Return the aliases for the given object name, if defined. + + The object name to check for aliases. + The aliases, or an empty array if none. + + If there's no such object definition. + + + + + + Return an unconfigured(!) instance (possibly shared or independent) of the given object name. + + The name of the object to return. + + The the object may match. Can be an interface or + superclass of the actual class. For example, if the value is the + class, this method will succeed whatever the + class of the returned instance. + + + The arguments to use if creating a prototype using explicit arguments to + a factory method. If there is no factory method and the + supplied array is not , then + match the argument values by type and call the object's constructor. + + The unconfigured(!) instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + If the object is not of the required type. + + + If the supplied is . + + + + This method will only instantiate the requested object. It does NOT inject any dependencies! + + + + + Return an instance (possibly shared or independent) of the given object name. + + The name of the object to return. + + the object may match. Can be an interface or + superclass of the actual class. For example, if the value is the + class, this method will succeed whatever the + class of the returned instance. + + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + If the object is not of the required type. + + + + + + Return an instance (possibly shared or independent) of the given object name. + + The name of the object to return. + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + + + + Return an instance (possibly shared or independent) of the given object name. + + +

+ This method allows an object factory to be used as a replacement for the + Singleton or Prototype design pattern. +

+

+ Note that callers should retain references to returned objects. There is no + guarantee that this method will be implemented to be efficient. For example, + it may be synchronized, or may need to run an RDBMS query. +

+

+ Will ask the parent factory if the object cannot be found in this factory + instance. +

+ + The name of the object to return. + + The arguments to use if creating a prototype using explicit arguments to + a static factory method. If there is no factory method and the + arguments are not null, then match the argument values by type and + call the object's constructor. + + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + If the supplied is . + + + + + Return an instance (possibly shared or independent) of the given object name. + + The name of the object to return. + + The the object may match. Can be an interface or + superclass of the actual class. For example, if the value is the + class, this method will succeed whatever the + class of the returned instance. + + + The arguments to use if creating a prototype using explicit arguments to + a factory method. If there is no factory method and the + supplied array is not , then + match the argument values by type and call the object's constructor. + + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + If the object is not of the required type. + + + If the supplied is . + + + + + + Is this object a singleton? + + The name of the object to query. + True if the named object is a singleton. + + If there's no such object definition. + + + + + + Determines whether the specified object name is prototype. That is, will GetObject + always return independent instances? + + The name of the object to query + + true if the specified object name will always deliver independent instances; otherwise, false. + + This method returning false does not clearly indicate a singleton object. + It indicated non-independent instances, which may correspond to a scoped object as + well. use the IsSingleton property to explicitly check for a shared + singleton instance. + Translates aliases back to the corresponding canonical object name. Will ask the + parent factory if the object can not be found in this factory instance. + + + if there is no object with the given name. + + + + Determines whether the object with the given name matches the specified type. + + More specifically, check whether a GetObject call for the given name + would return an object that is assignable to the specified target type. + Translates aliases back to the corresponding canonical bean name. + Will ask the parent factory if the bean cannot be found in this factory instance. + + The name of the object to query. + Type of the target to match against. + + true if the object type matches; otherwise, false + if it doesn't match or cannot be determined yet. + + Ff there is no object with the given name + + + + + Determine the of the object with the + given name. + + The name of the object to query. + + The of the object, or + if not determinable. + + + + + + Injects dependencies into the supplied instance + using the named object definition. + + + The object instance that is to be so configured. + + + The name of the object definition expressing the dependencies that are to + be injected into the supplied instance. + + + + + + Injects dependencies into the supplied instance + using the supplied . + + + The object instance that is to be so configured. + + + The name of the object definition expressing the dependencies that are to + be injected into the supplied instance. + + + An object definition that should be used to configure object. + + + + + + Determines whether the local object factory contains a bean of the given name, + ignoring object defined in ancestor contexts. + This is an alternative to ContainsObject, ignoring an object + of the given name from an ancestor object factory. + + + + + The name of the object to query. + + true if objects with the specified name is defined in the local factory; otherwise, false. + + + + + Determine whether the given object name is already in use within this context, + i.e. whether there is a local object. May be override by subclasses, the default + implementation simply returns + + + + + Register a new object definition with this registry. + Must support + + and . + + The name of the object instance to register. + The definition of the object instance to register. + +

+ Must support + and + . +

+ + + If the object definition is invalid. + + + + + Given a object name, create an alias. We typically use this method to + support names that are illegal within XML ids (used for object names). + + The name of the object. + The alias that will behave the same as the object name. + + If there is no object with the given name. + + + If the alias is already in use. + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + + The that represents + the culture for which the resource is localized. + + + The array of arguments that will be filled in for parameters within + the message, or if there are no parameters + within the message. Parameters within a message should be + referenced using the same syntax as the format string for the + method. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + If no message could be resolved. + + + If the supplied is . + + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + The default message. + + The that represents + the culture for which the resource is localized. + + + The array of arguments that will be filled in for parameters within + the message, or if there are no parameters + within the message. Parameters within a message should be + referenced using the same syntax as the format string for the + method. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + If no message could be resolved. + + + If the supplied is . + + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + + The resolved message if the lookup was successful. + + + If no message could be resolved. + + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + + The array of arguments that will be filled in for parameters within + the message, or if there are no parameters + within the message. Parameters within a message should be + referenced using the same syntax as the format string for the + method. + + + The resolved message if the lookup was successful. + + + If no message could be resolved. + + + If the supplied is . + + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + + The that represents + the culture for which the resource is localized. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + If no message could be resolved. + + + If the supplied is . + + + + + + Resolve the message using all of the attributes contained within + the supplied + argument. + + + The value object storing those attributes that are required to + properly resolve a message. + + + The that represents + the culture for which the resource is localized. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + If the message could not be resolved. + + + + + + Gets a localized resource object identified by the supplied + . + + + The name of the resource object to resolve. + + + The with which the + resource is associated. + + + The resolved object, or if not found. + + + + + + Gets a localized resource object identified by the supplied + . + + + The name of the resource object to resolve. + + + The resolved object, or if not found. + + + + + + Gets a localized resource object identified by the supplied + . + + + The name of the resource object to resolve. + + + The with which the + resource is associated. + + + The resolved object, or if not found. + + + + + + Gets a localized resource object identified by the supplied + . + + + The name of the resource object to resolve. + + + The resolved object, or if not found. + + + + + + Applies resources to object properties. + + + An object that contains the property values to be applied. + + + The base name of the object to use for key lookup. + + + The with which the + resource is associated. + + + + + + Publishes all events of the source object. + + + The source object containing events to publish. + + + + + + Subscribes to all events published, if the subscriber + implements compatible handler methods. + + The subscriber to use. + + + + + Subscribes to published events of a all objects of a given + , if the subscriber implements + compatible handler methods. + + The subscriber to use. + + The target to subscribe to. + + + + + + Unsubscribes to all events published, if the subscriber + implmenets compatible handler methods. + + The subscriber to use + + + + Unsubscribes to the published events of all objects of a given + , if the subscriber implements + compatible handler methods. + + The subscriber to use. + + The target to unsubscribe from + + + + + Publishes an application context event. + + +

+ +

+ + + The source of the event. May be . + + + The event that is to be raised. + + + + + + An object that can be used to synchronize access to the + + + + + Set the to be used by this context. + + + + + The timestamp when this context was first loaded. + + + The timestamp (milliseconds) when this context was first loaded. + + + + + Gets a flag indicating whether context should be case sensitive. + + true if object lookups are case sensitive; otherwise, false. + + + + The for this context. + + + If the context has not been initialized yet. + + + + + The for this context. + + + If the context has not been initialized yet. + + + + + Returns the list of the + s + that will be applied to the objects created with this factory. + + +

+ The elements of this list are instances of implementations of the + + interface. +

+ + + The list of the + s + that will be applied to the objects created with this factory. + + + + + Return the internal object factory of this application context. + + + + + Gets the parent context, or if there is no + parent context. + + + The parent context, or if there is no + parent. + + + + + + Gets a value indicating whether this component is currently running. + + + true if this component is running; otherwise, false. + + + In the case of a container, this will return true + only if all components that apply are currently running. + + + + + Gets a dictionary of all singleton beans that implement the + ILifecycle interface in this context. + + A dictionary of ILifecycle objects with object name as key. + + + + Raised in response to an implementation-dependant application + context event. + + + + + The date and time this context was first loaded. + + + The representing when this context + was first loaded. + + + + + A name for this context. + + + A name for this context. + + + + + Return the number of objects defined in the factory. + + + The number of objects defined in the factory. + + + + + + Return an instance (possibly shared or independent) of the given object name. + + The name of the object to return. + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + + + + Return the parent object factory, or if there is none. + + + The parent object factory, or if there is none. + + + + + + Allows for custom modification of new object instances, e.g. + checking for marker interfaces or wrapping them with proxies. + + +

+ Application contexts can auto-detect + + objects in their object definitions and apply them before any other + objects get created. Plain object factories allow for programmatic + registration of post-processors. +

+

+ Typically, post-processors that populate objects via marker interfaces + or the like will implement + , + and post-processors that wrap objects with proxies will normally implement + . +

+ + Juergen Hoeller + Aleksandar Seovic (.NET) + + + + + Apply this + to the given new object instance before any object initialization callbacks. + + +

+ The object will already be populated with property values. + The returned object instance may be a wrapper around the original. +

+ + + The new object instance. + + + The name of the object. + + + The object instance to use, either the original or a wrapped one. + + + In case of errors. + + + + + Apply this to the + given new object instance after any object initialization callbacks. + + +

+ The object will already be populated with property values. The returned object + instance may be a wrapper around the original. +

+ + + The new object instance. + + + The name of the object. + + + The object instance to use, either the original or a wrapped one. + + + In case of errors. + + + + + Interface that can be implemented by objects that should be orderable, e.g. in an + . + + +

+ The actual order can be interpreted as prioritization, the first object (with the + lowest order value) having the highest priority. +

+ + Juergen Hoeller + Aleksandar Seovic (.Net) + + + + Return the order value of this object, where a higher value means greater in + terms of sorting. + + +

+ Normally starting with 0 or 1, with indicating + greatest. Same order values will result in arbitrary positions for the affected + objects. +

+

+ Higher value can be interpreted as lower priority, consequently the first object + has highest priority. +

+ + The order value. + + + + Abstract implementation of the interface, + implementing common handling of message variants, making it easy + to implement a specific strategy for a concrete . + + +

Subclasses must implement the abstract ResolveObject + method.

+

Note: By default, message texts are only parsed through + String.Format if arguments have been passed in for the message. In case + of no arguments, message texts will be returned as-is. As a consequence, + you should only use String.Format escaping for messages with actual + arguments, and keep all other messages unescaped. +

+

Supports not only IMessageSourceResolvables as primary messages + but also resolution of message arguments that are in turn + IMessageSourceResolvables themselves. +

+

This class does not implement caching of messages per code, thus + subclasses can dynamically change messages over time. Subclasses are + encouraged to cache their messages in a modification-aware fashion, + allowing for hot deployment of updated messages. +

+ + Rod Johnson + Juergen Hoeller + Griffin Caprio (.NET) + Harald Radi (.NET) + + + + + + + Sub-interface of to be + implemented by objects that can resolve messages hierarchically. + + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + + + + + The parent message source used to try and resolve messages that + this object can't resolve. + + +

+ If the value of this property is then no + further resolution is possible. +

+ + + + + holds the logger instance shared with subclasses. + + + + + Initializes this instance. + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + If the lookup is not successful throw NoSuchMessageException + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + The that represents + the culture for which the resource is localized. + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + Note that the fallback behavior based on CultureInfo seem to + have a bug that is fixed by installed .NET 1.1 Service Pack 1. +

+ If the lookup is not successful, implementations are permitted to + take one of two actions. +

+ If the lookup is not successful throw NoSuchMessageException + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + The array of arguments that will be filled in for parameters within + the message, or if there are no parameters + within the message. Parameters within a message should be + referenced using the same syntax as the format string for the + method. + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + If the lookup is not successful throw NoSuchMessageException + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + The that represents + the culture for which the resource is localized. + The array of arguments that will be filled in for parameters within + the message, or if there are no parameters + within the message. Parameters within a message should be + referenced using the same syntax as the format string for the + method. + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + Note that the fallback behavior based on CultureInfo seem to + have a bug that is fixed by installed .NET 1.1 Service Pack 1. +

+ If the lookup is not successful throw NoSuchMessageException. +

+ + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + The default message if name is not found. + The that represents + the culture for which the resource is localized. + The array of arguments that will be filled in for parameters within + the message, or if there are no parameters + within the message. Parameters within a message should be + referenced using the same syntax as the format string for the + method. + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + Note that the fallback behavior based on CultureInfo seem to + have a bug that is fixed by installed .NET 1.1 Service Pack 1. +

+ If the lookup is not successful throw NoSuchMessageException +

+ + + + + Resolve the message using all of the attributes contained within + the supplied + argument. + + The value object storing those attributes that are required to + properly resolve a message. + The that represents + the culture for which the resource is localized. + + The resolved message if the lookup was successful. + + + If the message could not be resolved. + + + + + Gets a localized resource object identified by the supplied + . + + + The name of the resource object to resolve. + + + The resolved object, or if not found. + + + + + + Gets a localized resource object identified by the supplied + . + + + Note that the fallback behavior based on CultureInfo seem to + have a bug that is fixed by installed .NET 1.1 Service Pack 1. + + + The name of the resource object to resolve. + + + The with which the + resource is associated. + + + The resolved object, or if not found. If + the resource name resolves to null, then in .NET 1.1 the return + value will be String.Empty whereas in .NET 2.0 it will return + null. + + + + + + Applies resources to object properties. + + + An object that contains the property values to be applied. + + + The base name of the object to use for key lookup. + + + The with which the + resource is associated. + + + + + Resolve the given code and arguments as message in the given culture, + returning null if not found. Does not fall back to the code + as default message. Invoked by GetMessage methods. + + The code to lookup up, such as 'calculator.noRateSet'. + array of arguments that will be filled in for params + within the message. + The with which the + resource is associated. + + The resolved message if the lookup was successful. + + + + + Try to retrieve the given message from the parent MessageSource, if any. + + The code to lookup up, such as 'calculator.noRateSet'. + array of arguments that will be filled in for params + within the message. + The with which the + resource is associated. + + The resolved message if the lookup was successful. + + + + + Return a fallback default message for the given code, if any. + + + Default is to return the code itself if "UseCodeAsDefaultMessage" + is activated, or return no fallback else. In case of no fallback, + the caller will usually receive a NoSuchMessageException from GetMessage + + The code to lookup up, such as 'calculator.noRateSet'. + The default message to use, or null if none. + + + + Renders the default message string. The default message is passed in as specified by the + caller and can be rendered into a fully formatted default message shown to the user. + + Default implementation passed he String for String.Format resolving any + argument placeholders found in them. Subclasses may override this method to plug + in custom processing of default messages. + + The default message. + The array of agruments that will be filled in for parameter + placeholders within the message, or null if none. + The with which the + resource is associated. + The rendered default message (with resolved arguments) + + + + Format the given default message String resolving any + agrument placeholders found in them. + + The message to format. + The array of agruments that will be filled in for parameter + placeholders within the message, or null if none. + The with which the + resource is associated. + The formatted message (with resolved arguments) + + + + Search through the given array of objects, find any + MessageSourceResolvable objects and resolve them. + + + Allows for messages to have MessageSourceResolvables as arguments. + + + The array of arguments for a message. + The with which the + resource is associated. + An array of arguments with any IMessageSourceResolvables resolved + + + + Gets the specified resource (e.g. Icon or Bitmap). + + The name of the resource to resolve. + + The to resolve the + code for. + + The resource if found. otherwise. + + + + Applies resources from the given name on the specified object. + + + An object that contains the property values to be applied. + + + The base name of the object to use for key lookup. + + + The with which the + resource is associated. + + + + + Subclasses must implement this method to resolve a message. + + The code to lookup up, such as 'calculator.noRateSet'. + The with which the + resource is associated. + The resolved message from the backing store of message data. + + + + Resolves an object (typically an icon or bitmap). + + +

+ Subclasses must implement this method to resolve an object. +

+ + The code of the object to resolve. + + The to resolve the + code for. + + + The resolved object or if not found. + + + + + Applies resources to object properties. + + +

+ Subclasses must implement this method to apply resources + to an arbitrary object. +

+ + + An object that contains the property values to be applied. + + + The base name of the object to use for key lookup. + + + The with which the + resource is associated. + + + + Gets or Sets a value indicating whether to use the message code as + default message instead of throwing a NoSuchMessageException. + Useful for development and debugging. Default is "false". + + +

Note: In case of a IMessageSourceResolvable with multiple codes + (like a FieldError) and a MessageSource that has a parent MessageSource, + do not activate "UseCodeAsDefaultMessage" in the parent: + Else, you'll get the first code returned as message by the parent, + without attempts to check further codes.

+

To be able to work with "UseCodeAsDefaultMessage" turned on in the parent, + AbstractMessageSource contains special checks + to delegate to the internal GetMessageInternal method if available. + In general, it is recommended to just use "UseCodeAsDefaultMessage" during + development and not rely on it in production in the first place, though.

+

Alternatively, consider overriding the GetDefaultMessage + method to return a custom fallback message for an unresolvable code.

+ + + true if use the message code as default message instead of + throwing a NoSuchMessageException; otherwise, false. + + + + + The parent message source used to try and resolve messages that + this object can't resolve. + + + +

+ If the value of this property is then no + further resolution is possible. +

+ + + + + Convenient abstract superclass for + implementations that + draw their configuration from XML documents containing object + definitions as understood by an + . + + Rod Johnson + Juergen Hoeller + Griffin Caprio (.NET) + + + + Creates a new instance of the + + class. + + +

+ This is an class, and as such exposes + no public constructors. +

+ + + + + Creates a new instance of the + class + with the given parent context. + + +

+ This is an class, and as such exposes + no public constructors. +

+ + The application context name. + Flag specifying whether to make this context case sensitive or not. + The parent context. + + + + Instantiates and populates the underlying + with the object + definitions yielded up by the + method. + + + In the case of errors encountered while refreshing the object factory. + + + In the case of errors encountered reading any of the resources + yielded by the method. + + + + + + Initialize the object definition reader used for loading the object + definitions of this context. + + +

+ The default implementation of this method is a no-op; i.e. it does + nothing. Can be overridden in subclasses to provide custom + initialization of the supplied + ; for example, a derived + class may want to turn off XML validation. +

+ + + The object definition reader used by this context. + + + + + Load the object definitions with the given + . + + +

+ The lifecycle of the object factory is handled by + ; + therefore this method is just supposed to load and / or register + object definitions. +

+ + + The reader containing object definitions. + + In case of object registration errors. + + + In the case of errors encountered reading any of the resources + yielded by either the or + the methods. + + + + + Loads the object definitions into the given object factory, typically through + delegating to one or more object definition readers. + + The object factory to lead object definitions into + + + + + + Create a new reader instance for importing object definitions into the specified . + + the to be associated with the reader + a new instance. + + + + Customizes the internal object factory used by this context. + + Called for each attempt. +

+ The default implementation is empty. Can be overriden in subclassses to customize + DefaultListableBeanFatory's standard settings. +

+ The newly created object factory for this context + + + + Create an internal object factory for this context. + + +

+ Called for each attempt. + This default implementation creates a + + with the internal object factory of this context's parent serving + as the parent object factory. Can be overridden in subclasse,s + for example to customize DefaultListableBeanFactory's settings. +

+ + The object factory for this context. + + + + Determine whether the given object name is already in use within this context's object factory, + i.e. whether there is a local object or alias registered under this name. + + + + + An array of resource locations, referring to the XML object + definition files that this context is to be built with. + + +

+ Examples of the format of the various strings that would be + returned by accessing this property can be found in the overview + documentation of with the + class. +

+ + + An array of resource locations, or if none. + + + + + An array of resources that this context is to be built with. + + +

+ Examples of the format of the various strings that would be + returned by accessing this property can be found in the overview + documentation of with the + class. +

+ + + An array of s, or if none. + + + + + Subclasses must return their internal object factory here. + + + The internal object factory for the application context. + + + + + + + implementation that passes the application context to object that + implement the + , + , and + interfaces. + + +

+ If an object's class implements more than one of the + , + , and + interfaces, then the + order in which the interfaces are satisfied is as follows... + + + + + + + + + + + +

+

+ Application contexts will automatically register this with their + underlying object factory. Applications should thus never need to use + this class directly. +

+ + Juergen Hoeller + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + The that this + instance will work with. + + + + + Apply this + to the given new object instance before any object + initialization callbacks. + + + The new object instance. + + + The name of the object. + + + The the object instance to use, either the original or a wrapped one. + + + In case of errors. + + + + + + Apply this to the + given new object instance after any object initialization + callbacks. + + + The new object instance. + + + The name of the object. + + + The object instance to use, either the original or a wrapped one. + + + In case of errors. + + + + + + Convenient superclass for application objects that want to be aware of + the application context, e.g. for custom lookup of collaborating object + or for context-specific resource access. + + +

+ It saves the application context reference and provides an + initialization callback method. Furthermore, it offers numerous + convenience methods for message lookup. +

+

+ There is no requirement to subclass this class: it just makes things + a little easier if you need access to the context, e.g. for access to + file resources or to the message source. Note that many application + objects do not need to be aware of the application context at all, + as they can receive collaborating objects via object references. +

+ + Rod Johnson + Juergen Hoeller + Griffin Caprio (.NET) + + + + To be implemented by any object that wishes to be notified + of the that it runs in. + + +

+ Implementing this interface makes sense when an object requires access + to a set of collaborating objects. Note that configuration via object + references is preferable to implementing this interface just for object + lookup purposes. +

+

+ This interface can also be implemented if an object needs access to + file resources, i.e. wants to call + , or access to + the . However, it is + preferable to implement the more specific + + interface to receive a reference to the + object in that scenario. +

+

+ Note that dependencies can also + be exposed as object properties of the + type, populated via strings with + automatic type conversion performed by an object factory. This obviates + the need for implementing any callback interface just for the purpose + of accessing a specific file resource. +

+

+ + is a convenience implementation of this interface for your + application objects. +

+

+ For a list of all object lifecycle methods, see the overview for the + interface. +

+ + Rod Johnson + Mark Pollack (.NET) + + + + + + + Sets the that this + object runs in. + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Creates a new instance of the + class. + + +

+ This is an class, and as such exposes no + public constructors. +

+ + + + + Creates a new instance of the + class. + + +

+ This is an class, and as such exposes no + public constructors. +

+ + + The that this + object runs in. + + + + + Intializes the wrapped + . + + +

+ This is a template method that subclasses can override for custom + initialization behavior. +

+

+ Gets called by the + + instance directly after setting the context instance. +

+ + Does not get called on reinitialization of the context. + + + + In the case of any initialization errors. + + + If thrown by application context methods. + + + + + The context class that any context passed to the + + must be an instance of. + + + The + . + + + + + Return a for the + application context used by this object, for easy message access. + + + + + Gets or sets the that this + object runs in. + + + When passed an unexpected + implementation + instance that is not compatible with the + defined by the value of the + . + property. Also, thrown when trying to re-initialize with a + different than was + originally used. + + + If thrown by any application context methods. + + + + + + + Creates an instance + using context definitions supplied in a custom configuration and + configures the with that instance. + + + Implementations of the + interface must provide the following two constructors: + + + + A constructor that takes a string array of resource locations. + + + + + A constructor that takes a reference to a parent application context + and a string array of resource locations (and in that order). + + + +

+ Note that if the type attribute is not present in the declaration + of a particular context, then a default + + is assumed. This default + + is currently the + ; please note the exact + of this default is an + implementation detail, that, while unlikely, may do so in the future. + to +

+ + +

+ This is an example of specifying a context that reads its resources from + an embedded Spring.NET XML object configuration file... +

+ + + + +
+ + + + + + + + + +

+ This is an example of specifying a context that reads its resources from + a custom configuration section within the same application / web + configuration file and uses case insensitive object lookups. +

+

+ Please note that you must adhere to the naming + of the various sections (i.e. '<sectionGroup name="spring">' and + '<section name="context">'. +

+ + + + +
+
+ + + + + + + + + + + + +

+ And this is an example of specifying a hierarchy of contexts. The + hierarchy in this case is only a simple parent->child hierarchy, but + hopefully it illustrates the nesting of context configurations. This + nesting of contexts can be arbitrarily deep, and is one way... child + contexts know about their parent contexts, but parent contexts do not + know how many child contexts they have (if any), or have references + to any such child contexts. +

+ + + + +
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Mark Pollack + Aleksandar Seovic + Rick Evans + + + + + Creates an instance + using the context definitions supplied in a custom + configuration section. + + +

+ This instance is + also used to configure the . +

+ + + The configuration settings in a corresponding parent + configuration section. + + + The configuration context when called from the ASP.NET + configuration system. Otherwise, this parameter is reserved and + is . + + + The for the section. + + + An instance + populated with the object definitions supplied in the configuration + section. + + + + + Create all child-contexts in the given for the given context. + + The parent context to use + The current configContext + The list of child context elements + + + + Instantiates a new context. + + + + + Gets the context's name specified in the name attribute of the context element. + + The current configContext + The context element + + + + Extracts the context-type from the context element. + If none is specified, returns the parent's type. + + + + + Extracts the case-sensitivity attribute from the context element + + + + + Gets the context specified in the type + attribute of the context element. + + +

+ If this attribute is not defined it defaults to the + type. +

+ + + If the context type does not implement the + interface. + + + + + Returns the array of resources containing object definitions for + this context. + + + + + Returns the array of child contexts for this context. + + + + + The of + created if no type attribute is specified on a context element. + + + + + + Get the context's case-sensitivity to use if none is specified + + +

+ Derived handlers may override this property to change their default case-sensitivity. +

+

+ Defaults to 'true'. +

+ + + + + Specifies, whether the instantiated context will be automatically registered in the + global . + + + + + Returns if the context should be lazily + initialized. + + + + + Constants defining the structure and values associated with the + schema for laying out Spring.NET contexts in XML. + + + + + Defines a single + . + + + + + Specifies a context name. + + + + + Specifies if context should be case sensitive or not. Default is true. + + + + + Specifies a . + + +

+ Does not have to be fully assembly qualified, but its generally regarded + as better form if the names of one's objects + are specified explicitly. +

+ + + + + Specifies whether context should be lazy initialized. + + + + + Defines an + + + + + Specifies the URI for an + . + + + + + Provides access to a central registry of + s. + + +

+ A singleton implementation to access one or more application contexts. Application + context instances are cached. +

+

Note that the use of this class or similar is unnecessary except (sometimes) for + a small amount of glue code. Excessive usage will lead to code that is more tightly + coupled, and harder to modify or test. Consider refactoring your code to use standard + Dependency Injection techniques or implement the interface IApplicationContextAware to + obtain a reference to an application context.

+ + Mark Pollack + Aleksandar Seovic + + + + + The shared instance for this class (and derived classes). + + + + + Creates a new instance of the ContextRegistry class. + + +

+ Explicit static constructor to tell C# compiler + not to mark type as beforefieldinit. +

+ + + + + Registers an instance of an + . + + +

+ This is usually called via a + inside a .NET + application configuration file. +

+ + The application context to be registered. + + If a context has previously been registered using the same name + + + + + Handles events raised by an application context. + + + + + + + Removes the context from the registry + + + Has no effect if the context wasn't registered + + ´the context to remove from the registry + + + + Returns the root application context. + + +

+ The first call to GetContext will create the context + as specified in the .NET application configuration file + under the location spring/context. +

+ + The root application context. + + + + Returns context based on specified name. + + +

+ The first call to GetContext will create the context + as specified in the .NET application configuration file + under the location spring/context. +

+ + The context name. + The specified context, or null, if context with that name doesn't exists. + + If the context name is null or empty + + + + + Removes all registered + s from this + registry. + + + Raises the event while still holding a lock on + + + + + Allows to check, if a context is already registered + + The context name. + true, if the context is already registered. false otherwise + + + + This event is fired, if ContextRegistry.Clear() is called.
+ Clients may register to get informed + + + This event is fired while still holding a lock on the Registry.
+ 'sender' parameter is sent as typeof(ContextRegistry), EventArgs are not used + + + + + Gets an object that should be used to synchronize access to ContextRegistry + from the calling code. + + + + + Default implementation of the + interface. + + +

+ Provides easy ways to store all the necessary values needed to resolve + messages from an . +

+ + Juergen Hoeller + Griffin Caprio (.NET) + + + + + Describes objects that are suitable for message resolution in a + . + + +

+ Spring.NET's own validation error classes implement this interface. +

+ + Juergen Hoeller + Mark Pollack (.NET) + + + + + + Return the codes to be used to resolve this message, in the order + that they are to be tried. + + +

+ The last code will therefore be the default one. +

+ + + A array of codes which are associated + with this message. + + + + + Return the array of arguments to be used to resolve this message. + + + An array of objects to be used as parameters to replace + placeholders within the message text. + + + + + Return the default message to be used to resolve this message. + + + The default message, or if there is no + default. + + + + + Creates a new instance of the + class + using a single code. + + The message code to be resolved. + + + + Initializes a new instance of the class. + + The codes to be used to resolve this message + + + + Creates a new instance of the + class + using multiple codes. + + The message codes to be resolved. + + The arguments used to resolve the supplied . + + + + + Creates a new instance of the + class + using multiple codes and a default message. + + The message codes to be resolved. + + The arguments used to resolve the supplied . + + + The default message used if no code could be resolved. + + + + + Creates a new instance of the + class + from another resolvable. + + +

+ This is the copy constructor for the + class. +

+ + + The to be copied. + + + If the supplied is . + + + + + Returns a representation of this + . + + + A representation of this + . + + + + + Calls the visit method on the supplied + to output a version of this class. + + The visitor to use. + + A representation of this + . + + + + + Return the codes to be used to resolve this message, in the order + that they are to be tried. + + + A array of codes which are associated + with this message. + + + + + + Return the array of arguments to be used to resolve this message. + + + An array of objects to be used as parameters to replace + placeholders within the message text. + + + + + + Return the default code for this resolvable. + + + The default code of this resolvable; this will be the last code in + the codes array, or if this instance has no + codes. + + + + + + Return the default message to be used to resolve this message. + + + The default message, or if there is no + default. + + + + + + Default section handler that can handle any configuration section. + + +

+ Simply returns the configuration section as an . +

+ + Aleksandar Seovic + + + + Returns the configuration section as an + + + The configuration settings in a corresponding parent + configuration section. + + + The configuration context when called from the ASP.NET + configuration system. Otherwise, this parameter is reserved and + is a null reference. + + + The for the section. + + Config section as XmlElement. + + + + Empty implementation that + simply delegates all method calls to it's parent + . + + +

+ If no parent is available, + no messages will be resolved (and a + will be thrown). +

+

+ Used as placeholder by the + class, + if the context definition doesn't define its own + . Not intended for direct use + in applications. +

+ + Juergan Hoeller + Rick Evans (.NET) + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The parent message source used to try and resolve messages that + this object can't resolve. + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + If the message could not be resolved. + + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + + The array of arguments that will be filled in for parameters within + the message, or if there are no parameters + within the message. Parameters within a message should be + referenced using the same syntax as the format string for the + method. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + If the message could not be resolved. + + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + + The that represents + the culture for which the resource is localized. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + If the message could not be resolved. + + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + + The that represents + the culture for which the resource is localized. + + + The array of arguments that will be filled in for parameters within + the message, or if there are no parameters + within the message. Parameters within a message should be + referenced using the same syntax as the format string for the + method. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + If the message could not be resolved. + + + + + + Resolve the message identified by the supplied + . + + The name of the message to resolve. + The default message. + + The that represents + the culture for which the resource is localized. + + + The array of arguments that will be filled in for parameters within + the message, or if there are no parameters + within the message. Parameters within a message should be + referenced using the same syntax as the format string for the + method. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + If the message could not be resolved. + + + + + + Resolve the message using all of the attributes contained within + the supplied + argument. + + + The value object storing those attributes that are required to + properly resolve a message. + + + The that represents + the culture for which the resource is localized. + + + The resolved message if the lookup was successful (see above for + the return value in the case of an unsuccessful lookup). + + + If the message could not be resolved. + + + If the message could not be resolved. + + + + + + Gets a localized resource object identified by the supplied + . + + + The name of the resource object to resolve. + + + The resolved object, or if not found. + + + + + + Gets a localized resource object identified by the supplied + . + + + The name of the resource object to resolve. + + + The with which the + resource is associated. + + + The resolved object, or if not found. + + + + + + Applies resources to object properties. + + + An object that contains the property values to be applied. + + + The base name of the object to use for key lookup. + + + The with which the + resource is associated. + + + + + + The parent message source used to try and resolve messages that + this object can't resolve. + + + + + + Generic ApplicationContext implementation that holds a single internal + instance and does not + assume a specific object definition format. + + + Implements the interface in order + to allow for aplying any object definition readers to it. + Typical usage is to register a variety of object definitions via the + interface and then call + to initialize those + objects with application context semantics (handling + , auto-detecting + ObjectFactoryPostProcessors, etc). + + In contrast to other IApplicationContext implementations that create a new internal + IObjectFactory instance for each refresh, the internal IObjectFactory of this context + is available right from the start, to be able to register object definitions on it. + may only be called once + Usage examples + + GenericApplicationContext ctx = new GenericApplicationContext(); + // register your objects and object definitions + ctx.RegisterObjectDefinition(...) + ctx.Refresh(); + + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + if set to true names in the context are case sensitive. + + + + Initializes a new instance of the class. + + The object factory instance to use for this context. + + + + Initializes a new instance of the class. + + The parent application context. + + + + Initializes a new instance of the class. + + The name of the application context. + if set to true names in the context are case sensitive. + The parent application context. + + + + Initializes a new instance of the class. + + The object factory to use for this context + The parent applicaiton context. + + + + Initializes a new instance of the class. + + The name of the application context. + if set to true names in the context are case sensitive. + The parent application context. + The object factory to use for this context + + + + Do nothing operation. We hold a single internal ObjectFactory and rely on callers + to register objects throug our public methods (or the ObjectFactory's). + + + In the case of errors encountered while refreshing the object factory. + + + + + Determines whether the given object name is already in use within this factory, + i.e. whether there is a local object or alias registered under this name or + an inner object created with this name. + + + + + Return the internal object factory of this application context. + + + + + + Gets the underlying object factory of this context, available for + registering object definitions. + + You need to call Refresh to initialize the + objects factory and its contained objects with application context + semantics (autodecting IObjectFactoryPostProcessors, etc). + The internal object factory (as DefaultListableObjectFactory). + + + + Helper class for easy access to messages from an + , providing various + overloaded GetMessage methods. + + +

+ Available from + , but also + reusable as a standalone helper to delegate to in application objects. +

+ + Juergen Hoeller + Griffin Caprio (.NET) + + + + + + Creates a new instance of the + class + that uses the current + for all locale specific lookups. + + + The to use to locate messages. + + + + + Creates a new instance of the + class + + + The to use to locate + messages. + + + The to use for + locale specific messages. + + + + + Retrieve the message for the given code and the default + . + + The code of the message. + The message. + + + + Retrieve the message for the given code and the given + . + + The code of the message. + + The to use for + lookups. + + The message. + + + + Retrieve the message for the given code and the default + . + + The code of the message. + + The arguments for the message, or if none. + + The message. + + If the message could not be found. + + + + + Retrieve the message for the given code and the given + . + + The code of the message. + + The to use for + lookups. + + + The arguments for the message, or if none. + + The message. + + If the message could not be found. + + + + + Retrieve a mesage using the given + . + + + The . + + The message. + + If the message could not be found. + + + + + Retrieve a mesage using the given + in the given + . + + + The . + + + The to use for + lookups. + + The message + + If the message could not be found. + + + + + Visitor class to represent + instances. + + +

+ Used in the first instance to supply stringified versions of + instances. +

+

+ Other methods can be added here to return different representations, + including XML, CSV, etc.. +

+ + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Outputs the supplied + as a nicely formatted . + + + The to output. + + + + + Configuration section handler for the (recommended, Spring.NET standard) parsers + config section. + + +

+ Spring.NET allows the registration of custom configuration parsers that + can be used to create simplified configuration schemas that better + describe object definitions. +

+

+ For example, Spring.NET uses this facility internally in order to + define simplified schemas for various AOP, Data and Services definitions. +

+ + +

+ The following example shows how to configure both this section handler + and how to define custom configuration parsers within a Spring.NET + config section. +

+ + + + +
+ + + + + + + ... + + ... + + + + + Aleksandar Seovic + + + + + Registers parsers specified in the (recommended, Spring.NET standard) + parsers config section with the . + + + The configuration settings in a corresponding parent + configuration section. + + + The configuration context when called from the ASP.NET + configuration system. Otherwise, this parameter is reserved and + is . + + + The for the section. + + + This method always returns , because parsers + are registered as a side-effect of this object's execution and there + is thus no need to return anything. + + + + + An that doesn't do a whole lot. + + +

+ is an implementation of + the NullObject pattern. It should be used in those situations where a + needs to be passed (say to a + method) but where the resolution of messages is not required. +

+

+ There should not (typically) be a need to instantiate instances of this class; + does not maintan any state + and the instance is + thus safe to pass around. +

+ + Aleksandar Seovic + + + + The canonical instance of the + class. + + + + + Creates a new instance of the class. + + +

+ Consider using + instead. +

+ + + + + Simply returns the supplied message as-is. + + The code of the message to resolve. + + The to resolve the + code for. + + + The supplied message as-is. + + + + + Always returns . + + The code of the object to resolve. + + The to resolve the + code for. + + + (always). + + + + + Does nothing. + + + An object that contains the property values to be applied. + + + The base name of the object to use for key lookup. + + + The with which the + resource is associated. + + + + + Handler for Spring.NET resourceHandlers config section. + + +

+ Spring allows registration of custom resource handlers that can be used to load + object definitions from. +

+

+ For example, if you wanted to store your object definitions in a database instead + of in the config file, you could write a custom implementation + and register it with Spring using 'db' as a protocol name. +

+

+ Afterwards, you would simply specify resource URI within the context config element + using your custom resource handler. +

+ + +

+ The following example shows how to configure both this section handler, + how to define custom resource within Spring config section, and how to load + object definitions using custom resource handler: +

+ + + + +
+ + + + + + + + + + + + + + Aleksandar Seovic + + + + + Registers resource handlers that are specified in + the resources config section with the . + + + The configuration settings in a corresponding parent + configuration section. Ignored. + + + The configuration context when called from the ASP.NET + configuration system. Otherwise, this parameter is reserved and + is . + + + The for the section. + + + This method always returns null, because resource handlers are registered + as a sideffect of its execution and there is no need to return anything. + + + + + An implementation that + accesses resources from .resx / .resource files. + + Note that for the method + GetResourceObject if the resource name resolves to null, then in + .NET 1.1 the return value will be String.Empty whereas + in .NET 2.0 it will return null. + Griffin Caprio (.NET) + Mark Pollack (.NET) + Aleksandar Seovic (.NET) + + + + Defines a simple initialization callback for objects that need to to some + post-initialization logic after all of their dependencies have been injected. + + +

+ An implementation of the + + method might perform some additional custom initialization (over and above that + performed by the constructor), or merely check that all mandatory properties + have been set (this last example is a very typical use case of this interface). +

+ + The use of the + interface + by non-Spring.NET framework code can be avoided (and is generally + discouraged). The Spring.NET container provides support for a generic + initialization method given to the object definition in the object + configuration store (be it XML, or a database, etc). This requires + slightly more configuration (one attribute-value pair in the case of + XML configuration), but removes any dependency on Spring.NET from the + class definition. + + + Rod Johnson + Rick Evans (.NET) + + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Creates a new instance of the + class. + + + + + Resolves a given code by searching through each assembly name in + the base names array. + + The code to resolve. + + The to use for lookups. + + The message from the resource set. + + + + Resolves a given code by searching through each assembly name in the array. + + The code to resolve. + + The to use for lookups. + + The object from the resource set. + + + + Uses a System.ComponentModel.ComponentResourceManager + to apply resources to object properties. + Resource key names are of the form objectName.propertyName + + + This feature is not currently supported on version 1.0 of the .NET platform. + + + An object that contains the property values to be applied. + + + The base name of the object to use for the key lookup. + + + The to use for lookups. + If , uses the + value. + + + This feature is not currently supported on version 1.0 of the .NET platform. + + + + + Resolves a code into an object given a base name. + + The to search. + The code to resolve. + + The to use for lookups. + + The object from the resource file. + + + + Returns a representation of the + . + + A representation of the + . + + + + Invoked by an + after it has set all object properties supplied. + + +

+ The list may contain objects of type or + . types + are converted to instances using the notation + resourcename, assembly partial name. +

+ + + If the conversion from a to a + can't be performed. + + + + + The collection of s + in this . + + + + + that allows concrete registration of + objects and messages in code, rather than from external configuration sources. + + +

+ Mainly useful for testing. +

+ + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the StaticApplicationContext class. + + + + + Creates a new instance of the StaticApplicationContext class. + + The parent application context. + + + + Creates a new, named instance of the StaticApplicationContext class. + + the context name + The parent application context. + + + + Do nothing: we rely on callers to update our public methods. + + + + + Register a singleton object with the default object factory. + + The name of the object. + The of the object. + The property values for the singleton instance. + + + + Registers a prototype object with the default object factory. + + The name of the prototype object. + The of the prototype object. + The property values for the prototype instance. + + + + Associate the given message with the given code. + + The lookup code. + + The that the message should be found within. + + The message associated with the lookup code. + + + + Simple implementation of + that allows messages to be held in an object and added programmatically. + + +

+ Mainly useful for testing. +

+

+ This supports internationalization. +

+ + Rod Johnson + Juergen Hoeller + Griffin Caprio (.NET) + + + + + Creates a new instance of the + class. + + + + + Returns a format string. + + The code of the message to resolve. + + The to resolve the + code for. + + + A format string or if not found. + + + + + + Resolves an object (typically an icon or bitmap). + + The code of the object to resolve. + + The to resolve the + code for. + + + The resolved object or if not found. + + + + + + Applies resources to object properties. + + +

+ Uses a System.ComponentModel.ComponentResourceManager + internally to apply resources to object properties. Resource key + names are of the form objectName.propertyName. +

+

+ This feature is not currently supported on version 1.0 of the .NET platform. +

+ + + An object that contains the property values to be applied. + + + The base name of the object to use for key lookup. + + + The with which the + resource is associated. + + + This feature is not currently supported on version 1.0 of the .NET platform. + + + + + + Associate the supplied with the + supplied . + + The lookup code. + + The to resolve the + code for. + + + The message format associated with this lookup code. + + + + + Associate the supplied with the + supplied . + + The lookup code. + + The to resolve the + code for. + + + The object associated with this lookup code. + + + + + Returns a representation of this + message source. + + + A containing all of this message + source's messages. + + + + + Configuration section handler for the Spring.NET typeAliases + config section. + + +

+ Type aliases can be used instead of fully qualified type names anywhere + a type name is expected in a Spring.NET configuration file. +

+

+ This includes type names specified within an object definition, as well + as values of the properties or constructor arguments that expect + instances. +

+ + +

+ The following example shows how to configure both this section handler and + how to define type aliases within a Spring.NET config section: +

+ + + + +
+ + + + + + + ... + + ... + + + + + Aleksandar Seovic + + + + + Populates using values specified in + the typeAliases config section. + + + The configuration settings in a corresponding parent + configuration section. + + + The configuration context when called from the ASP.NET + configuration system. Otherwise, this parameter is reserved and + is . + + + The for the section. + + + This method always returns , because the + is populated as a side-effect of this + object's execution and thus there is no need to return anything. + + + + + Configuration section handler for the Spring.NET typeConverters + config section. + + +

+ Type converters are used to convert objects from one type into another + when injecting property values, evaluating expressions, performing data + binding, etc. +

+

+ They are a very powerful mechanism as they allow Spring.NET to automatically + convert string-based property values from the configuration file into the appropriate + type based on the target property's type or to convert string values submitted + via a web form into a type that is used by your data model when Spring.NET data + binding is used. Because they offer such tremendous help, you should always provide + a type converter implementation for your custom types that you want to be able to use + for injected properties or for data binding. +

+

+ The standard .NET mechanism for specifying type converter for a particular type is + to decorate the type with a , passing the type + of the -derived class as a parameter. +

+

+ This mechanism will still work and is a preferred way of defining type converters if + you control the source code for the type that you want to define a converter for. However, + this configuration section allows you to specify converters for the types that you don't + control and it also allows you to override some of the standard type converters, such as + the ones that are defined for some of the types in the .NET Base Class Library. +

+ + +

+ The following example shows how to configure both this section handler and + how to define type converters within a Spring.NET config section: +

+ + + + +
+ + + + + + + ... + + ... + + + + + Aleksandar Seovic + + + + + Populates using values specified in + the typeConverters config section. + + + The configuration settings in a corresponding parent + configuration section. + + + The configuration context when called from the ASP.NET + configuration system. Otherwise, this parameter is reserved and + is . + + + The for the section. + + + This method always returns , because the + is populated as a side-effect of + its execution and thus there is no need to return anything. + + + + + An implementation that + reads context definitions from XML based resources. + + +

+ Currently, the resources that are supported are the file, + http, ftp, config and assembly resource + types. +

+

+ You can provide custom implementations of the + interface and and register them + with any that inherits + from the + + interface. +

+ + In case of multiple config locations, later object definitions will + override ones defined in previously loaded resources. This can be + leveraged to deliberately override certain object definitions via an + extra XML file. + + + +

+ Find below some examples of instantiating an + using a + variety of different XML resources. +

+ + // an XmlApplicationContext that reads its object definitions from an + // XML file that has been embedded in an assembly... + IApplicationContext context = new XmlApplicationContext + ( + "assembly://AssemblyName/NameSpace/ResourceName" + ); + + // an XmlApplicationContext that reads its object definitions from a + // number of disparate XML resources... + IApplicationContext context = new XmlApplicationContext + ( + // from an XML file that has been embedded in an assembly... + "assembly://AssemblyName/NameSpace/ResourceName", + // and from a (relative) filesystem-based resource... + "file://Objects/services.xml", + // and from an App.config / Web.config resource... + "config://spring/objects" + ); + + + Rod Johnson + Juergen Hoeller + Griffin Caprio (.NET) + + + + + + + Initializes a new instance of the XmlApplicationContext class. + + + + + Creates a new instance of the + class, + loading the definitions from the supplied XML resource locations. + + The created context will be case sensitive. + + Any number of XML based object definition resource locations. + + + + + Creates a new instance of the + class, + loading the definitions from the supplied XML resource locations. + + Flag specifying whether to make this context case sensitive or not. + + Any number of XML based object definition resource locations. + + + + + Creates a new instance of the + class, + loading the definitions from the supplied XML resource locations. + + The application context name. + Flag specifying whether to make this context case sensitive or not. + + Any number of XML based object definition resource locations. + + + + + Creates a new instance of the + class, + loading the definitions from the supplied XML resource locations, + with the given . + + + The parent context (may be ). + + + Any number of XML based object definition resource locations. + + + + + Creates a new instance of the + class, + loading the definitions from the supplied XML resource locations, + with the given . + + Flag specifying whether to make this context case sensitive or not. + + The parent context (may be ). + + + Any number of XML based object definition resource locations. + + + + + Creates a new instance of the + class, + loading the definitions from the supplied XML resource locations, + with the given . + + The application context name. + Flag specifying whether to make this context case sensitive or not. + + The parent context (may be ). + + + Any number of XML based object definition resource locations. + + + + + Creates a new instance of the + class, + loading the definitions from the supplied XML resource locations, + with the given . + + + This constructor is meant to be used by derived classes. By passing =false, it is + the responsibility of the deriving class to call to initialize the context instance. + + if true, is called automatically. + The application context name. + Flag specifying whether to make this context case sensitive or not. + + The parent context (may be ). + + + Any number of XML based object definition resource locations. + + + + + An array of resource locations, referring to the XML object + definition files with which this context is to be built. + + + An array of resource locations, or if none. + + + + + + An array of resources instances with which this context is to be built. + + + An array of s, or if none. + + + + + + Encapsulates arguments to the class. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The name. + The parent context. + The configuration locations. + The configuration resources. + + + + Initializes a new instance of the XmlApplicationContextArgs class. + + The name. + The parent context. + The configuration locations. + The configuration resources. + if set to true [case sensitive]. + if set to true [refresh]. + + + Exception thrown during application context initialization. + Rod Johnson + Mark Pollack (.NET) + + + + Thrown on an unrecoverable problem encountered in the + objects namespace or sub-namespaces, e.g. bad class or field. + + Rod Johnson + Mark Pollack (.NET) + + + + Superclass for all exceptions thrown in the Objects namespace and sub-namespaces. + + Rod Johnson + Mark Pollack (.NET) + + + Creates a new instance of the ObjectsException class. + + + + Creates a new instance of the ObjectsException class. with the specified message. + + + A message about the exception. + + + + + Creates a new instance of the ObjectsException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the ObjectsException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the FatalObjectException class. + + + + + Creates a new instance of the FatalObjectException class with the + specified message. + + + A message about the exception. + + + + + Creates a new instance of the FatalObjectException class with the + specified message. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the FatalObjectException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the + class with the + specified message. + + + A message about the exception. + + + + + Creates a new instance of the + class with the + specified message. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Marks an interface as being an application event listener. + + Griffin Caprio + + + + + Creates a new instance of the + class. + + + + + The callback for application events. + + + + + To be implemented by any object that wishes to be notified + of the associated with it. + + +

+ In the current implementation, the + will typically be the + associated that + spawned the implementing object. +

+

+ The can usually also be + passed on as an object reference to arbitrary object properties or + constructor arguments, because a + is typically defined as an + object with the well known name "messageSource" in the + associated application context. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + + Sets the associated + with this object. + + +

+ Invoked after population of normal object properties but + before an initializing callback such as the + + method of the + interface + or a custom init-method. +

+

+ It is also invoked before the + + property of any + + implementation. +

+ + + The associated + with this object. + + + + + Interface to be implemented by any object that wishes to be notified + of the (typically the + ) that it runs in. + + +

+ Note that dependencies can also + be exposed as object properties of type + , populated via strings with + automatic type conversion by the object factory. This obviates the + need for implementing any callback interface just for the purpose of + accessing a specific resource. +

+

+ You typically need an + when your application object has to access a variety of file resources + whose names are calculated. A good strategy is to make the object use + a default resource loader but still implement the + interface to allow + for overriding when running in an + . +

+ + Juergen Hoeller + Mark Pollack (.NET) + + + + + + + Sets the + that this object runs in. + + +

+ Invoked after population of normal objects properties but + before an init callback such as + 's + + or a custom init-method. Invoked before setting + 's + + property. +

+ + + + + Thrown when a message cannot be resolved. + + Rod Johnson + Mark Pollack (.NET) + + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class with the + specified message. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being + thrown. + + + The + that contains contextual information about the source or + destination. + + + + + Creates a new instance of the + class. + + + The code that could not be resolved for given culture. + + + The that was used + to search for the code. + + + + + Creates a new instance of the + class. + + + The code that could not be resolved for the current UI culture. + + + + + Convenience base class for + implementations, pre-implementing typical behavior. + + +

+ The method will + check whether a or + can be opened; + will always return + ; + and + throw an exception; + and will + return the value of the + property. +

+ + Juergen Hoeller + Rick Evans (.NET) + Aleksandar Seovic (.NET) + + + + + The central abstraction for Spring.NET's access to resources such as + s. + + +

+ This interface encapsulates a resource descriptor that abstracts away + from the underlying type of resource; possible resource types include + files, memory streams, and databases (this list is not exhaustive). +

+

+ A can definitely be opened and accessed + for every such resource; if the resource exists in a physical form (for + example, the resource is not an in-memory stream or one that has been + extracted from an assembly or ZIP file), a or + can also be accessed. The actual + behavior is implementation-specific. +

+

+ This interface, when used in tandem with the + interface, forms the backbone of + Spring.NET's resource handling. Third party extensions or libraries + that want to integrate external resources with Spring.NET's IoC + container are encouraged expose such resources via this abstraction. +

+

+ Interfaces cannot obviously mandate implementation, but derived classes + are strongly encouraged to expose a constructor that takes a + single as it's sole argument (see example). + Exposing such a constructor will make your custom + implementation integrate nicely + with the class. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + + + Simple interface for objects that are sources for + s. + + +

+ This is the base interface for the abstraction encapsulated by + Spring.NET's interface. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + + Return an for this resource. + + + + Clients of this interface must be aware that every access of this + property will create a fresh ; + it is the responsibility of the calling code to close any such + . + + + + An . + + + If the stream could not be opened. + + + + + Creates a resource relative to this resource. + + + The path (always resolved as relative to this resource). + + + The relative resource. + + + If the relative resource could not be created from the supplied + path. + + + If the resource does not support the notion of a relative path. + + + + + Does this resource represent a handle with an open stream? + + +

+ If , the + cannot be read multiple times, and must be read and then closed to + avoid resource leaks. +

+

+ Will be for all usual resource descriptors. +

+ + + if this resource represents a handle with an + open stream. + + + + + + Returns the handle for this resource. + + +

+ For safety, always check the value of the + property prior to + accessing this property; resources that cannot be exposed as + a will typically return + from a call to the + property. +

+ + + The handle for this resource. + + + If the resource is not available or cannot be exposed as a + . + + + + + + + Returns a handle for this resource. + + +

+ For safety, always check the value of the + property prior to + accessing this property; resources that cannot be exposed as + a will typically return + from a call to the + property. +

+ + + The handle for this resource. + + + If the resource is not available on a filesystem, or cannot be + exposed as a handle. + + + + + + + Returns a description for this resource. + + +

+ The description is typically used for diagnostics and other such + logging when working with the resource. +

+

+ Implementations are also encouraged to return this value from their + method. +

+ + + A description for this resource. + + + + + Does this resource actually exist in physical form? + + +

+ An example of a resource that physically exists would be a + file on a local filesystem. An example of a resource that does not + physically exist would be an in-memory stream. +

+ + + if this resource actually exists in physical + form (for example on a filesystem). + + + + + + + The default special character that denotes the base (home, or root) + path. + + +

+ Will be resolved (by those + implementations that support it) to the home (or root) path for + the specific implementation. +

+

+ For example, in the case of a web application this will (probably) + resolve to the virtual directory of said web application. +

+ + + + + Creates a new instance of the + class. + + +

+ This is an class, and as such exposes no + public constructors. +

+ + + + + Creates a new instance of the + class. + + +

+ This is an class, and as such exposes no + public constructors. +

+ + + A string representation of the resource. + + + If the supplied is + or contains only whitespace character(s). + + + + + Strips any protocol name from the supplied + . + + +

+ If the supplied does not + have any protocol associated with it, then the supplied + will be returned as-is. +

+ + + + GetResourceNameWithoutProtocol("http://www.mycompany.com/resource.txt"); + // returns www.mycompany.com/resource.txt + + + + The name of the resource. + + + The name of the resource without the protocol name. + + + + + Resolves the supplied to its value + sans any leading protocol. + + + The name of the resource. + + + The name of the resource without the protocol name. + + + + + + Resolves the presence of the + value + in the supplied into a path. + + +

+ The default implementation simply returns the supplied + as is. +

+ + + The name of the resource. + + + The string that is a placeholder for a base path. + + + The name of the resource with any + value having been resolved into an actual path. + + + + + This implementation returns the + of this resource. + + + + + + Determines whether the specified is + equal to the current . + + +

+ This implementation compares values. +

+ + + + + + Serves as a hash function for a particular type, suitable for use + in hashing algorithms and data structures like a hash table. + + +

+ This implementation returns the hashcode of the + property. +

+ + + + + + Factory Method. Create a new instance of the current resource type using the given resourceName + + + + + The ResourceLoader to be used for resolving relative resources + + + + + Does the supplied relative ? + + + The name of the resource to test. + + + if resource name is relative; + otherwise . + + + + + Creates a new resource that is relative to this resource based on the + supplied . + + +

+ This method can accept either a fully qualified resource name or a + relative resource name as it's parameter. +

+

+ A fully qualified resource is one that has a protocol prefix and + all elements of the resource name. All other resources are treated + as relative to this resource, and the following rules are used to + locate a relative resource: +

+ + + If the starts with '..', + the current resource path is navigated backwards before the + is concatenated to the current + of + this resource. + + + If the starts with '/', the + current resource path is ignored and a new resource name is + appended to the + of + this resource. + + + If the starts with '.' or a + letter, a new path is appended to the current + of + this resource. + + + + + The name of the resource to create. + + The relative resource. + + If the process of resolving the relative resource yielded an + invalid URI. + + + If this resource does not support the resolution of relative + resources (as determined by the value of the + + property). + + + + + + Calculates a new resource path based on the supplied + . + + + The relative path to evaluate. + + The newly calculated resource path. + + + + The special character that denotes the base (home, or root) + path. + + +

+ Will be resolved (by those + implementations that support it) to the home (or root) path for + the specific implementation. +

+

+ For example, in the case of a web application this will (probably) + resolve to the virtual directory of said web application. +

+ + + + + + Return an for this resource. + + + An . + + + If the stream could not be opened. + + + + + + Returns a description for this resource. + + + A description for this resource. + + + + + + Returns the protocol associated with this resource (if any). + + +

+ The value of this property may be if no + protocol is associated with the resource type (for example if the + resource is a memory stream). +

+ + + The protocol associated with this resource (if any). + + + + + Does this resource represent a handle with an open stream? + + +

+ This, the default implementation, always returns + . +

+ + + if this resource represents a handle with an + open stream. + + + + + + Returns the handle for this resource. + + + + + + Returns a handle for this resource. + + +

+ This, the default implementation, always throws a + , assuming that the + resource cannot be resolved to an absolute file path. +

+ + + The handle for this resource. + + + This implementation always throws a + . + + + + + + + Does this resource actually exist in physical form? + + +

+ This implementation checks whether a + can be opened, falling back to whether a + can be opened. +

+

+ This will cover both directories and content resources. +

+

+ This implementation will also return if + permission to the (file's) path is denied. +

+ + + if this resource actually exists in physical + form (for example on a filesystem). + + + + + + + Does this support relative + resource retrieval? + + +

+ This property is generally to be consulted prior to attempting + to attempting to access a resource that is relative to this + resource (via a call to + ). +

+

+ This, the default implementation, always returns + . +

+ + + if this + supports relative resource + retrieval. + + + + + Gets the root location of the resource. + + +

+ Where root resource can be taken to mean that part of the resource + descriptor that doesn't change when a relative resource is looked + up. Examples of such a root location would include a drive letter, + a web server name, an assembly name, etc. +

+ + + The root location of the resource. + + + This, the default implementation, always throws a + . + + + + + Gets the current path of the resource. + + +

+ An example value of this property would be the name of the + directory containing a filesystem based resource. +

+ + + The current path of the resource. + + + This, the default implementation, always throws a + . + + + + + Gets those characters that are valid path separators for the + resource type. + + +

+ An example value of this property would be the + and + values for a + filesystem based resource. +

+

+ Any derived classes that override this method are expected to + return a new array for each access of this property. +

+ + + Those characters that are valid path separators for the resource + type. + + + This, the default implementation, always throws a + . + + + + + An implementation for + resources stored within assemblies. + + +

+ This implementation expects any resource name passed to the + constructor to adhere to the following format: +

+

+ assembly://assemblyName/namespace/resourceName +

+ + Aleksandar Seovic (.NET) + Federico Spinazzi (.NET) + + + + Creates a new instance of the + class. + + + The name of the assembly resource. + + + If the supplied did not conform + to the expected format. + + + If the assembly specified in the supplied + was loaded twice with two + different evidences. + + + If the assembly specified in the supplied + could not be found. + + + If the caller does not have the required permission to load + the assembly specified in the supplied + . + + + + + + Does the supplied relative ? + + + The name of the resource to test. + + + if resource name is relative; + otherwise . + + + + + Return an for this resource. + + + An . + + + If the stream could not be opened. + + + If the caller does not have the required permission to load + the underlying assembly's manifest. + + + + + + + Does the embedded resource specified in the value passed to the + constructor exist? + + + if this resource actually exists in physical + form (for example on a filesystem). + + + + + + + + Does this support relative + resource retrieval? + + +

+ This implementation does support relative resource retrieval, and + so will always return . +

+ + + if this + supports relative resource + retrieval. + + + + + + Gets the root location of the resource (the assembly name in this + case). + + + The root location of the resource. + + + + + + Gets the current path of the resource (the namespace in which the + target resource was embedded in this case). + + + The current path of the resource. + + + + + + Gets those characters that are valid path separators for the + resource type. + + + Those characters that are valid path separators for the resource + type. + + + + + + Returns a description for this resource. + + + A description for this resource. + + + + + + Returns the handle for this resource. + + + + + + Used when retrieving information from the standard .NET configuration + files (App.config / Web.config). + + +

+ If created with the name of a configuration section, then all methods + aside from the description return , + , or throw an exception. If created with an + , then the + property + will return a corresponding to parse. +

+ + Mark Pollack + Rick Evans + + + + Creates new instance of the + class. + + + The actual XML configuration section. + + + If the supplied is . + + + + + Creates new instance of the + class. + + + The name of the configuration section. + + + If the supplied is + or contains only whitespace character(s). + + + + + Returns the handle for this resource. + + +

+ This implementation always returns . +

+ + + . + + + + + + Returns a handle for this resource. + + +

+ This implementation always returns . +

+ + + . + + + + + + Returns a description for this resource (the name of the + configuration section in this case). + + + A description for this resource. + + + + + + Does this resource actually exist in physical form? + + +

+ This implementation always returns . +

+ + + + + + + + + + Return an for this resource. + + + An . + + + If the stream could not be opened. + + + + + + Exposes the actual for the + configuration section. + + +

+ Introduced to accomodate line info tracking during parsing. +

+ + + + + Holder that combines with a specific encoding to be used for reading + from the resource + + Juergen Hoeller + Erich Eichinger (.NET) + + + + Create an encoded resource, autodetecting the encoding from the resource stream. + + + + + + Create an encoded resource, autodetecting the encoding from the resource stream. + + the resource to read from. Must not be null + whether to autoDetect encoding from byte-order marks () + + + + Create an encoded resource using the specified encoding. + + the resource to read from. Must not be null + the encoding to use. If null, encoding will be autodetected. + whether to autoDetect encoding from byte-order marks () + + + + + + + + + + Determine whether equals this instance. + + + true if obj is an and both + , and are equal. + + + + + Calculate the unique hash code for this instance. + + + + + + Get a textual description of the resource. + + + + + Get the underlying resource + + + + + Get the encoding to use for reading, if any. May be null + + + + + whether to autoDetect encoding from byte-order marks () + + + + + A backed resource. + + +

+ Supports resolution as both a and a + . +

+

+ Also supports the use of the ~ character. If the ~ character + is the first character in a resource path (sans protocol), the ~ + character will be replaced with the value of the + System.AppDomain.CurrentDomain.BaseDirectory property (an example of + this can be seen in the examples below). +

+ + +

+ Consider the example of an application that is running (has been launched + from) the C:\App\ directory. The following resource paths will map + to the following resources on the filesystem... +

+ + strings.txt C:\App\strings.txt + ~/strings.txt C:\App\strings.txt + file://~/strings.txt C:\App\strings.txt + file://~/../strings.txt C:\strings.txt + ../strings.txt C:\strings.txt + ~/../strings.txt C:\strings.txt + + // note that only a leading ~ character is resolved to the executing directory... + stri~ngs.txt C:\App\stri~ngs.txt + + + Juergen Hoeller + Leonardo Susatyo (.NET) + Aleksandar Seovic (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The name of the file system resource. + + + If the supplied is + or contains only whitespace character(s). + + + + + Creates a new instance of the + class. + + + The name of the file system resource. + + + Supresses initialization of this instance. Used from derived classes. + + + If the supplied is + or contains only whitespace character(s). + + + + + Initializes this instance. + + + + + + Resolves the handle + for the supplied . + + + The name of the file system resource. + + + The handle for this resource. + + + + + Resolves the root location for the supplied . + + + The name of the file system resource. + + + The root location of the resource. + + + + + Resolves the path for the supplied . + + + The name of the file system resource. + + + The current path of the resource. + + + + + Resolves the presence of the + value + in the supplied into a path. + + + The name of the resource. + + + The string that is a placeholder for a base path. + + + The name of the resource with any + value having been resolved into an actual path. + + + + + Does the supplied relative ? + + + The name of the resource to test. + + + if resource name is relative; + otherwise . + + + + + Returns the underlying handle for + this resource. + + + The handle for this resource. + + + + + + Does this support relative + resource retrieval? + + +

+ This implementation does support relative resource retrieval, and + so will always return . +

+ + + if this + supports relative resource + retrieval. + + + + + + Gets the root location of the resource (a drive or UNC file share + name in this case). + + + The root location of the resource. + + + + + + Gets the current path of the resource. + + + The current path of the resource. + + + + + + Gets those characters that are valid path separators for the + resource type. + + + Those characters that are valid path separators for the resource + type. + + + + + + + Return an for this resource. + + + An . + + + If the stream could not be opened. + + + If the underlying file could not be found. + + + + + + Returns a description for this resource. + + + A description for this resource. + + + + + + Returns the handle for this resource. + + + The handle for this resource. + + + If the resource is not available or cannot be exposed as a + . + + + + + + adapter implementation for a + . + + +

+ Should only be used if no other + implementation is applicable. +

+

+ In contrast to other + implementations, this is an adapter for an already opened + resource - the + therefore always returns . Do not use this class + if you need to keep the resource descriptor somewhere, or if you need + to read a stream multiple times. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + Creates a new instance of the + class. + + + The input to use. + + + Where the input comes from. + + + If the supplied is + . + + + + + The input to use. + + + If the underlying has already + been read. + + + + + Returns a description for this resource. + + + A description for this resource. + + + + + + This implementation always returns true + + + + + This implemementation always returns true + + + + + Custom type converter for instances. + + +

+ A resource path may contain placeholder variables of the form ${...} + that will be expended to environment variables. +

+

+ Currently only supports conversion from a + instance. +

+ + +

+ On Win9x boxes, this resource path, ${userprofile}\objects.xml will + be expanded at runtime with the value of the 'userprofile' environment + variable substituted for the '${userprofile}' portion of the path. +

+ + // assuming a user called Rick, running on a plain vanilla Windows XP setup... + // this resource path... + + ${userprofile}\objects.xml + + // will become (after expansion)... + + C:\Documents and Settings\Rick\objects.xml + + + Mark Pollack + + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class using the specified resourceLoader. + + the underlying IResourceLoader to be used to resolve resources + + + + Returns whether this converter can convert an object of one + to a + + + A + that provides a format context. + + + A that represents the + you want to convert from. + + + if the conversion is possible. + + + + + Convert from a string value to a + instance. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + An if successful. + + + If the resource name objectained form the supplied + is malformed. + + + In the case of any errors arising from the instantiation of the + returned instance. + + + + + Resolve the given path, replacing placeholder values with + corresponding property values if necessary. + + +

+ This implementation resolves environment variables only. +

+ + The original resource path. + The resolved resource path. + + + + Return the used to + resolve the string. + + + The used to resolve + the string. + + + + + Registry class that allows users to register and retrieve protocol handlers. + + + + Resource handler is an implementation of interface + that should be used to process resources with the specified protocol. + + + They are used throughout the framework to access resources from various + sources. For example, application context loads object definitions from the resources + that are processed using one of the registered resource handlers. + + Following resource handlers are registered by default: + + + Protocol + Handler Type + Description + + + config + + Resolves the resources by loading specified configuration section from the standard .NET config file. + + + file + + Resolves filesystem resources. + + + http + + Resolves remote web resources. + + + https + + Resolves remote web resources via HTTPS. + + + ftp + + Resolves ftp resources. + + + assembly + + Resolves resources that are embedded into an assembly. + + + web + Spring.Core.IO.WebResource, Spring.Web* + Resolves resources relative to the web application's virtual directory. + + + * only available in web applications. + + Users can create and register their own protocol handlers by implementing interface + and mapping custom protocol name to that implementation. See for details + on how to register custom protocol handler. + + + Aleksandar Seovic + + + + Name of the .Net config section that contains definitions + for custom resource handlers. + + + + + Registers standard and user-configured resource handlers. + + + + + Returns resource handler for the specified protocol name. + + + + This method returns object that should be used + to create an instance of the -derived type by passing + resource location as a parameter. + + + Name of the protocol to get the handler for. + Resource handler constructor for the specified protocol name. + If is null. + + + + Returns true if a handler is registered for the specified protocol, + false otherwise. + + Name of the protocol. + + true if a handler is registered for the specified protocol, false otherwise. + + If is null. + + + + Registers resource handler and maps it to the specified protocol name. + + +

+ If the mapping already exists, the existing mapping will be + silently overwritten with the new mapping. +

+ + + The protocol to add (or override). + + + The type name of the concrete implementation of the + interface that will handle + the specified protocol. + + + If the supplied is + or contains only whitespace character(s); or + if the supplied is + . + + + If the supplied is not a + that derives from the + interface; or (having passed + this first check), the supplied + does not expose a constructor that takes a single + parameter. + + + + + Registers resource handler and maps it to the specified protocol name. + + +

+ If the mapping already exists, the existing mapping will be + silently overwritten with the new mapping. +

+ + + The protocol to add (or override). + + + The concrete implementation of the + interface that will handle + the specified protocol. + + + If the supplied is + or contains only whitespace character(s); or + if the supplied is + . + + + If the supplied is not a + that derives from the + interface; or (having passed + this first check), the supplied + does not expose a constructor that takes a single + parameter. + + + + + Allows to create any arbitrary Url format + + + + + A adapter implementation encapsulating a simple string. + + Erich Eichinger + + + + Creates a new instance of the class. + + + + + Creates a new instance of the class. + + + + + Creates a new instance of the class. + + + + + Get the to + for accessing this resource. + + + + + Returns a description for this resource. + + + A description for this resource. + + + + + + This implementation always returns true + + + + + This implemementation always returns true + + + + + Gets the encoding used to create a byte stream of the string. + + + + + Gets the content encapsulated by this . + + + + + A backed resource + on top of + + +

+ Obviously supports resolution as a , and also + as a in the case of the "file:" + protocol. +

+ + +

+ Some examples of the strings that can be used to initialize a new + instance of the class + include... + + + file:///Config/objects.xml + + + http://www.mycompany.com/services.txt + + +

+ + Juergen Hoeller + Leonardo Susatyo (.NET) + Aleksandar Seovic (.NET) + + + + + + + Creates a new instance of the + class. + + +

+ Some examples of the values that the + can typically be expected to hold include... + + + file:///Config/objects.xml + + + http://www.mycompany.com/services.txt + + +

+ + + A string representation of the resource. + + + + + Does the supplied relative ? + + + The name of the resource to test. + + + if resource name is relative; + otherwise . + + + + + Returns the instance + used for the resource resolution. + + + A instance. + + + + + + + Return an for this resource. + + + An . + + + If the stream could not be opened. + + + + + + Returns the handle for this resource. + + + The handle for this resource. + + + If the resource is not available or cannot be exposed as a + . + + + + + + Returns a handle for this resource. + + + The handle for this resource. + + + If the resource is not available on a filesystem. + + + + + + Does this support relative + resource retrieval? + + +

+ This implementation does support relative resource retrieval, and + so will always return . +

+ + + if this + supports relative resource + retrieval. + + + + + + Gets the root location of the resource. + + + The root location of the resource. + + + + + + Gets the current path of the resource. + + + The current path of the resource. + + + + + + Gets those characters that are valid path separators for the + resource type. + + + Those characters that are valid path separators for the resource + type. + + + + + + Returns a description for this resource. + + + A description for this resource. + + + + + + Converts string representation of a credential for Web client authentication + into an instance of . + + +

+ Find below some examples of the XML formatted strings that this + converter will sucessfully convert. +

+ + + + + + + + Bruno Baia + + + + Can we convert from the sourcetype + to a instance ? + + +

+ Currently only supports conversion from a instance. +

+ + + A + that provides a format context. + + + A that represents the + you want to convert from. + + if the conversion is possible. + + + + Convert from a value to an + instance. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + A instance if successful. + + + + + A custom for any + primitive numeric type such as , + , , etc. + + +

+ Can use a given for + (locale-specific) parsing and rendering. +

+

+ This is not meant to be used as a system + but rather as a + locale-specific number converter within custom controller code, to + parse user-entered number strings into number properties of objects, + and render them in a UI form. +

+ + Juergen Hoeller + Simon White (.NET) + + + + Creates a new instance of the + class. + + + The primitive numeric to convert to. + + + The to use for + (locale-specific) parsing and rendering + + + Is an empty string allowed to be converted? If + , an empty string value will be converted to + numeric 0. + + Id the supplied is not a primitive + . + + + + + + Returns whether this converter can convert an object of one + to a + + +

+ Currently only supports conversion from a + instance. +

+ + + A + that provides a format context. + + + A that represents the + you want to convert from. + + + if the conversion is possible. + + + + + Converts the specified object (a string) to the required primitive + type. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + A primitive representation of the string value. + + + + Converter for instances. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Creates a new instance of the + class. + + + + + Returns whether this converter can convert an object of one + to a + + +

+ Currently only supports conversion from a + instance. +

+ + + A + that provides a format context. + + + A that represents the + you want to convert from. + + True if the conversion is possible. + + + + Convert from a string value to a instance. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + A if successful. + + + + + Custom implementation for + objects. + + +

+ Handles conversion from an XML formatted string to a + object + (see below for an example of the expected XML format). +

+

+ This converter must be registered before it will be available. Standard + converters in this namespace are automatically registered by the + class. +

+ + +

+ Find below some examples of the XML formatted strings that this + converter will sucessfully convert. Note that the name of the top level + (document) element is quite arbitrary... it is only the content that + matters (and which must be in the format + <add key="..." value="..."/>. For your continued sanity + though, you may wish to standardize on the top level name of + 'dictionary' (although you are of course free to not do so). +

+ + + + + + +

+ The following example uses a different top level (document) element + name, but is equivalent to the first example. +

+ + + + + + + + Rod Johnson + Juergen Hoeller + Simon White (.NET) + + + + Creates a new instance of the + class. + + + + + Returns whether this converter can convert an object of one + to a + + + +

+ Currently only supports conversion from an + XML formatted instance. +

+ + + A + that provides a format context. + + + A that represents the + you want to convert from. + + True if the conversion is possible. + + + + Convert from a string value to a + instance. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + A + if successful. + + + + + Converts string representation of a regular expression into an instance of . + + Aleksandar Seovic + + + + Can we convert from the sourcetype to a ? + + +

+ Currently only supports conversion from a instance. +

+ + + A + that provides a format context. + + + A that represents the + you want to convert from. + + if the conversion is possible. + + + + Convert from a value to an + instance. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + A if successful. + + + + + Converts string representation of the registry key + into instance. + + Aleksandar Seovic + + + + Can we convert from a the sourcetype to a ? + + +

+ Currently only supports conversion from a instance. +

+ + + A + that provides a format context. + + + A that represents the + you want to convert from. + + if the conversion is possible. + + + + Convert from a value to an + instance. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + A array if successful. + + + + + Generates partial registry key name. + + + Key elements. + + + Index of the last element to use. + + + Friendly key name containing key element from + 0 to , inclusive. + + + + + Returns for the specified + root hive name. + + + Root hive name. + + + Registry key for the specified name. + + + + + Converts a two part string, (resource name, assembly name) + to a ResourceManager instance. + + + + + This constant represents the name of the folder/assembly containing global resources. + + + + + Creates a new instance of the + class. + + + + + Returns whether this converter can convert an object of one + to a + + + +

+ Currently only supports conversion from a + instance. +

+ + + A + that provides a format context. + + + A that represents the + you want to convert from. + + True if the conversion is possible. + + + + Convert from a string value to a + instance. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + A + if successful. + + If the specified does not denote a valid resource + + + + Converter for from a comma separated + list of RBG values. + + +

+ Please note that this class does not implement converting + to a comma separated list of RBG values from a + . +

+ + Federico Spinazzi + + + + Returns whether this converter can convert an object of one + to a + . + + +

+ Currently only supports conversion from a + instance. +

+ + + A + that provides a format context. + + + A that represents the + you want to convert from. + + if the conversion is possible. + + + + Converts the specified object (a string) a + instance. + + + A + that provides a format context. + + + The to use + as the current culture: currently ignored. + + + The value that is to be converted, in "R,G,B", "A,R,G,B", or + symbolic color name (). + + + A representation of the string value. + + + If the input string is not in a supported format, or is not one of the + predefined system colors (). + + + + + A custom for + runtime type references. + + +

+ Currently only supports conversion to and from a + . +

+ + Rick Evans (.NET) + + + + Creates a new instance of the + class. + + + + + Returns whether this converter can convert an object of one + to the + of this converter. + + +

+ Currently only supports conversion from a + instance. +

+ + + A + that provides a format context. + + + A that represents the + you want to convert from. + + True if the conversion is possible. + + + + Returns whether this converter can convert the object to the specified + . + + + A + that provides a format context. + + + A that represents the + you want to convert to. + + True if the conversion is possible. + + + + Converts the given value to the type of this converter. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + An that represents the converted value. + + + + + Converts the given value object to the specified type, + using the specified context and culture information. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + The to convert the + parameter to. + + + An that represents the converted value. + + + + + Converter for to directly set a + property. + + Jurgen Hoeller + Mark Pollack (.NET) + + + + Create a new StreamConverter using the default + . + + + + + Create a new StreamConverter using the given + . + + + The to use. + + + + Returns whether this converter can convert an object of one + to a + + +

+ Currently only supports conversion from a + instance. +

+ + + A + that provides a format context. + + + A that represents the + you want to convert from. + + True if the conversion is possible. + + + + Convert from a string value to a instance. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + A if successful. + + + + + Converts a separated to a + array. + + +

+ Defaults to using the , (comma) as the list separator. Note that the value + of the current is + not used. +

+

+ If you want to provide your own list separator, you can set the value of the + + property to the value that you want. Please note that this value will be used + for all future conversions in preference to the default list separator. +

+

+ Please note that the individual elements of a string will be passed + through as is (i.e. no conversion or trimming of surrounding + whitespace will be performed). +

+

+ This should be + automatically registered with any + implementations. +

+ + + + public class StringArrayConverterExample + { + public static void Main() + { + StringArrayConverter converter = new StringArrayConverter(); + + string csvWords = "This,Is,It"; + string[] frankBoothWords = converter.ConvertFrom(csvWords); + + // the 'frankBoothWords' array will have 3 elements, namely + // "This", "Is", "It". + + // please note that extraneous whitespace is NOT trimmed off + // in the current implementation... + string csv = " Cogito ,ergo ,sum "; + string[] descartesWords = converter.ConvertFrom(csv); + + // the 'descartesWords' array will have 3 elements, namely + // " Cogito ", "ergo ", "sum ". + // notice how the whitespace has NOT been trimmed. + } + } + + + + + + + Can we convert from a the sourcetype to a array? + + +

+ Currently only supports conversion from a instance. +

+ + + A + that provides a format context. + + + A that represents the + you want to convert from. + + if the conversion is possible. + + + + Convert from a value to a + array. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + A array if successful. + + + + + The value that will be used as the list separator when performing + conversions. + + + A 'single' string character that will be used as the list separator + when performing conversions. + + + If the supplied value is not and is an empty + string, or has more than one character. + + + + + Base parser for custom specifiers. + + + + + Convert int value to a Timespan based on the specifier + + + + + + + Check if the string contains the specifier and + + + + + + + Specifier + + + + + Recognize 10d as ten days + + + + + Parse value as days + + Timespan in days + + + + + Day specifier: d + + + + + Recognize 10h as ten hours + + + + + Parse value as hours + + Timespan in hours + + + + + Hour specifier: h + + + + + Recognize 10m as ten minutes + + + + + Parse value as minutes + + Timespan in minutes + + + + + Minute specifier: m + + + + + Recognize 10s as ten seconds + + + + + Parse value as seconds + + Timespan in seconds + + + + + Second specifier: s + + + + + Recognize 10ms as ten milliseconds + + + + + Parse value as milliseconds + + Timespan in milliseconds + + + + + Millisecond specifier: ms + + + + + Converter for instances. + + Bruno Baia + Roberto Paterlini + + + + Creates a new instance of the + class. + + + + + Convert from a string value to a instance. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + A if successful. + + + + + Utility methods that are used to convert objects from one type into another. + + Aleksandar Seovic + + + + Convert the value to the required (if necessary from a string). + + The proposed change value. + + The we must convert to. + + Property name, used for error reporting purposes... + + If there is an internal error. + + The new value, possibly the result of type conversion. + + + + Utility method to create a property change event. + + + The full name of the property that has changed. + + The property old value + The property new value + + A new . + + + + + Determines if a Type implements a specific generic interface. + + Candidate to evaluate. + The to test for in the Candidate . + if a match, else + + + + Registry class that allows users to register and retrieve type converters. + + Aleksandar Seovic + + + + Name of the .Net config section that contains Spring.Net type aliases. + + + + + Registers standard and configured type converters. + + + + + Returns for the specified type. + + Type to get the converter for. + a type converter for the specified type. + If is null. + + + + Registers for the specified type. + + Type to register the converter for. + Type converter to register. + If either of arguments is null. + + + + Registers for the specified type. + + + This is a convinience method that accepts the names of both + type to register converter for and the converter itself, + resolves them using , creates an + instance of type converter and calls overloaded + method. + + Type name of the type to register the converter for (can be a type alias). + Type name of the type converter to register (can be a type alias). + If either of arguments is null or empty string. + + If either of arguments fails to resolve to a valid . + + + If type converter does not derive from or if it cannot be instantiated. + + + + + Converts between instances of and their string representations. + + Erich Eichinger + + + + Can we convert from the sourcetype to a ? + + +

+ Currently only supports conversion from a instance. +

+ + + A that provides a format context. + + + A that represents the you want to convert from. + + if the conversion is possible. + + + + Convert from a value to an instance. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + A if successful, otherwise. + + The conversion cannot be performed. + + + + Returns whether this converter can convert the object to the specified type, using the specified context. + + An that provides a format context. + A that represents the type you want to convert to. + + true if this converter can perform the conversion; otherwise, false. + + + At the moment only conversion to string is supported. + + + + + Converts the given value object to the specified type, using the specified context and culture information. + + + + An that represents the converted value. + + + A . If null is passed, the current culture is assumed. + An that provides a format context. + The to convert the value parameter to. + The to convert. + The conversion cannot be performed. + The destinationType parameter is null. + + + + Converter for instances. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Creates a new instance of the + class. + + + + + Returns whether this converter can convert an object of one + to a + + +

+ Currently only supports conversion from a + instance. +

+ + + A + that provides a format context. + + + A that represents the + you want to convert from. + + True if the conversion is possible. + + + + Convert from a string value to a instance. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + A if successful. + + + + + Resolves (instantiates) a by it's (possibly + assembly qualified) name, and caches the + instance against the type name. + + Rick Evans + Bruno Baia + Erich Eichinger + + + + Resolves a by name. + + +

+ The rationale behind the creation of this interface is to centralise + the resolution of type names to instances + beyond that offered by the plain vanilla + method call. +

+ + Rick Evans + + + + Resolves the supplied to a + + instance. + + + The (possibly partially assembly qualified) name of a + . + + + A resolved instance. + + + If the supplied could not be resolved + to a . + + + + + The cache, mapping type names ( instances) against + instances. + + + + + Creates a new instance of the class. + + + The that this instance will delegate + actual resolution to if a + cannot be found in this instance's cache. + + + If the supplied is . + + + + + Resolves the supplied to a + + instance. + + + The (possibly partially assembly qualified) name of a + . + + + A resolved instance. + + + If the supplied could not be resolved + to a . + + + + + Holder for the generic arguments when using type parameters. + + +

+ Type parameters can be applied to classes, interfaces, + structures, methods, delegates, etc... +

+ + + + + The generic arguments prefix. + + + + + The generic arguments suffix. + + + + + The generic arguments prefix. + + + + + The generic arguments suffix. + + + + + The character that separates a list of generic arguments. + + + + + Creates a new instance of the GenericArgumentsHolder class. + + + The string value to parse looking for a generic definition + and retrieving its generic arguments. + + + + + Returns the array declaration portion of the definition, e.g. "[,]" + + + + + + Returns an array of unresolved generic arguments types. + + +

+ A empty string represents a type parameter that + did not have been substituted by a specific type. +

+ + + An array of strings that represents the unresolved generic + arguments types or an empty array if not generic. + + + + + The (unresolved) generic type name portion + of the original value when parsing a generic type. + + + + + The (unresolved) generic method name portion + of the original value when parsing a generic method. + + + + + Is the string value contains generic arguments ? + + +

+ A generic argument can be a type parameter or a type argument. +

+ + + + + Is generic arguments only contains type parameters ? + + + + + Is this an array type definition? + + + + + Resolves a generic by name. + + Bruno Baia + + + + Resolves a by name. + + Rick Evans + Aleksandar Seovic + Bruno Baia + + + + Resolves the supplied to a + instance. + + + The unresolved (possibly partially assembly qualified) name + of a . + + + A resolved instance. + + + If the supplied could not be resolved + to a . + + + + + Uses + to load an and then the attendant + referred to by the + parameter. + + +

+ is + deprecated in .NET 2.0, but is still used here (even when this class is + compiled for .NET 2.0); + will + still resolve (non-.NET Framework) local assemblies when given only the + display name of an assembly (the behaviour for .NET Framework assemblies + and strongly named assemblies is documented in the docs for the + method). +

+ + + The assembly and type to be loaded. + + + A , or . + + + + + + + + Uses + to load the attendant referred to by + the parameter. + + + The type to be loaded. + + + A , or . + + + + + Creates a new instance + from the given + + + + + Creates a new instance + from the given with the given inner + + + + + Resolves the supplied generic to a + instance. + + + The unresolved (possibly generic) name of a . + + + A resolved instance. + + + If the supplied could not be resolved + to a . + + + + + Holds data about a and it's + attendant . + + + + + The string that separates a name + from the name of it's attendant + in an assembly qualified type name. + + + + + Creates a new instance of the TypeAssemblyHolder class. + + + The unresolved name of a . + + + + + The (unresolved) type name portion of the original type name. + + + + + The (unresolved, possibly partial) name of the attandant assembly. + + + + + Is the type name being resolved assembly qualified? + + + + + Provides access to a central registry of aliased s. + + +

+ Simplifies configuration by allowing aliases to be used instead of + fully qualified type names. +

+

+ Comes 'pre-loaded' with a number of convenience alias' for the more + common types; an example would be the 'int' (or 'Integer' + for Visual Basic.NET developers) alias for the + type. +

+ + Aleksandar Seovic + + + + + Name of the .Net config section that contains Spring.Net type aliases. + + + + + The alias around the 'int' type. + + + + + The alias around the 'Integer' type (Visual Basic.NET style). + + + + + The alias around the 'int[]' array type. + + + + + The alias around the 'Integer()' array type (Visual Basic.NET style). + + + + + The alias around the 'decimal' type. + + + + + The alias around the 'Decimal' type (Visual Basic.NET style). + + + + + The alias around the 'decimal[]' array type. + + + + + The alias around the 'Decimal()' array type (Visual Basic.NET style). + + + + + The alias around the 'char' type. + + + + + The alias around the 'Char' type (Visual Basic.NET style). + + + + + The alias around the 'char[]' array type. + + + + + The alias around the 'Char()' array type (Visual Basic.NET style). + + + + + The alias around the 'long' type. + + + + + The alias around the 'Long' type (Visual Basic.NET style). + + + + + The alias around the 'long[]' array type. + + + + + The alias around the 'Long()' array type (Visual Basic.NET style). + + + + + The alias around the 'short' type. + + + + + The alias around the 'Short' type (Visual Basic.NET style). + + + + + The alias around the 'short[]' array type. + + + + + The alias around the 'Short()' array type (Visual Basic.NET style). + + + + + The alias around the 'unsigned int' type. + + + + + The alias around the 'unsigned long' type. + + + + + The alias around the 'ulong[]' array type. + + + + + The alias around the 'uint[]' array type. + + + + + The alias around the 'unsigned short' type. + + + + + The alias around the 'ushort[]' array type. + + + + + The alias around the 'double' type. + + + + + The alias around the 'Double' type (Visual Basic.NET style). + + + + + The alias around the 'double[]' array type. + + + + + The alias around the 'Double()' array type (Visual Basic.NET style). + + + + + The alias around the 'float' type. + + + + + The alias around the 'Single' type (Visual Basic.NET style). + + + + + The alias around the 'float[]' array type. + + + + + The alias around the 'Single()' array type (Visual Basic.NET style). + + + + + The alias around the 'DateTime' type. + + + + + The alias around the 'DateTime' type (C# style). + + + + + The alias around the 'DateTime' type (Visual Basic.NET style). + + + + + The alias around the 'DateTime[]' array type. + + + + + The alias around the 'DateTime[]' array type. + + + + + The alias around the 'DateTime()' array type (Visual Basic.NET style). + + + + + The alias around the 'bool' type. + + + + + The alias around the 'Boolean' type (Visual Basic.NET style). + + + + + The alias around the 'bool[]' array type. + + + + + The alias around the 'Boolean()' array type (Visual Basic.NET style). + + + + + The alias around the 'string' type. + + + + + The alias around the 'string' type (Visual Basic.NET style). + + + + + The alias around the 'string[]' array type. + + + + + The alias around the 'string[]' array type (Visual Basic.NET style). + + + + + The alias around the 'object' type. + + + + + The alias around the 'object' type (Visual Basic.NET style). + + + + + The alias around the 'object[]' array type. + + + + + The alias around the 'object[]' array type (Visual Basic.NET style). + + + + + The alias around the 'int?' type. + + + + + The alias around the 'int?[]' array type. + + + + + The alias around the 'decimal?' type. + + + + + The alias around the 'decimal?[]' array type. + + + + + The alias around the 'char?' type. + + + + + The alias around the 'char?[]' array type. + + + + + The alias around the 'long?' type. + + + + + The alias around the 'long?[]' array type. + + + + + The alias around the 'short?' type. + + + + + The alias around the 'short?[]' array type. + + + + + The alias around the 'unsigned int?' type. + + + + + The alias around the 'unsigned long?' type. + + + + + The alias around the 'ulong?[]' array type. + + + + + The alias around the 'uint?[]' array type. + + + + + The alias around the 'unsigned short?' type. + + + + + The alias around the 'ushort?[]' array type. + + + + + The alias around the 'double?' type. + + + + + The alias around the 'double?[]' array type. + + + + + The alias around the 'float?' type. + + + + + The alias around the 'float?[]' array type. + + + + + The alias around the 'bool?' type. + + + + + The alias around the 'bool?[]' array type. + + + + + Registers standard and user-configured type aliases. + + + + + Registers an alias for the specified . + + +

+ This overload does eager resolution of the + referred to by the parameter. It will throw a + if the referred + to by the parameter cannot be resolved. +

+ + + A string that will be used as an alias for the specified + . + + + The (possibly partially assembly qualified) name of the + to register the alias for. + + + If either of the supplied parameters is or + contains only whitespace character(s). + + + If the referred to by the supplied + cannot be loaded. + + + + + Registers short type name as an alias for + the supplied . + + + The to register. + + + If the supplied is . + + + + + Registers an alias for the supplied . + + + The alias for the supplied . + + + The to register the supplied under. + + + If the supplied is ; or if + the supplied is or + contains only whitespace character(s). + + + + + Resolves the supplied to a . + + + The alias to resolve. + + + The the supplied was + associated with, or if no + was previously registered for the supplied . + + + If the supplied is or + contains only whitespace character(s). + + + + + Returns a flag specifying whether TypeRegistry contains + specified alias or not. + + + Alias to check. + + + true if the specified type alias is registered, + false otherwise. + + + + + Helper methods with regard to type resolution. + + +

+ Not intended to be used directly by applications. +

+ + Bruno Baia + + + + Creates a new instance of the class. + + +

+ This is a utility class, and as such exposes no public constructors. +

+ + + + + Resolves the supplied type name into a + instance. + + +

+ If you require special resolution, do + not use this method, but rather instantiate + your own . +

+ + + The (possibly partially assembly qualified) name of a + . + + + A resolved instance. + + + If the type cannot be resolved. + + + + + Resolves a string array of interface names to + a array. + + + An array of valid interface names. Each name must include the full + interface and assembly name. + + An array of interface s. + + If any of the interfaces can't be loaded. + + + If any of the s specified is not an interface. + + + If (or any of its elements ) is + . + + + + + Match a method against the given pattern. + + the pattern to match against. + the method to match. + + if the method matches the given pattern; otherwise . + + + If the supplied is invalid. + + + + + Exception thrown when the ObjectFactory cannot load the specified type of a given object. + + Mark Pollack + + + + Thrown on an unrecoverable problem encountered in the + objects namespace or sub-namespaces, e.g. bad class or field. + + Rod Johnson + Mark Pollack (.NET) + + + + Superclass for all exceptions thrown in the Objects namespace and sub-namespaces. + + Rod Johnson + Mark Pollack (.NET) + + + Creates a new instance of the ObjectsException class. + + + + Creates a new instance of the ObjectsException class. with the specified message. + + + A message about the exception. + + + + + Creates a new instance of the ObjectsException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the ObjectsException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the FatalObjectException class. + + + + + Creates a new instance of the FatalObjectException class with the + specified message. + + + A message about the exception. + + + + + Creates a new instance of the FatalObjectException class with the + specified message. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the FatalObjectException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Initializes a new instance of the class. + + The resource description that the object definition came from. + Name of the object requested + Name of the object type. + The root cause. + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + Gets he name of the object we are trying to load. + + The name of the object. + + + + Gets the name of the object type we are trying to load. + + The name of the object type. + + + + Gets the resource description that the object definition came from + + The resource description. + + + + A implementation that represents + a composed collection of instances. + + + + + The criteria for an arbitrary filter. + + Rick Evans + + + + Does the supplied satisfy the criteria + encapsulated by this instance? + + + The datum to be checked by this criteria instance. + + + if the supplied + satisfies the criteria encapsulated by this instance; + if not, or the supplied + is . + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A user-defined (child) criteria that will be composed into this instance. + + + + + Does the supplied satisfy the criteria encapsulated by + this instance? + + The data to be checked by this criteria instance. + + True if the supplied satisfies the criteria encapsulated + by this instance; false if not or the supplied is null. + + + + + Adds the supplied into the criteria + composed within this instance. + + + The to be added. + + + + + The list of composing this + instance. + + + + + Factory class to conceal any default implementation. + + Rod Johnson + Simon White (.NET) + + + + Creates a new instance of the + implementation provided by this factory. + + + A new instance of the + implementation provided by this factory. + + + + + Interface to be implemented by objects that can return information about + the current call stack. + + +

+ Useful in AOP (as an expression of the AspectJ cflow concept) but not AOP-specific. +

+ + Rod Johnson + Aleksandar Seovic (.Net) + + + + Detects whether the caller is under the supplied , + according to the current stacktrace. + + + The to look for. + + + if the caller is under the supplied . + + + + + Detects whether the caller is under the supplied + and , according to the current stacktrace. + + + The to look for. + + The name of the method to look for. + + if the caller is under the supplied + and . + + + + + Does the current stack trace contain the supplied ? + + The token to match against. + + if the current stack trace contains the supplied + . + + + + + Creates a new instance of the + class. + + + + + Detects whether the caller is under the supplied , + according to the current stacktrace. + + + + + + Detects whether the caller is under the supplied + and , according to the current stacktrace. + + +

+ Matches the whole method name. +

+ + + + + + Does the current stack trace contain the supplied ? + + +

+ This leaves it up to the caller to decide what matches, but is obviously less of + an abstraction because the caller must know the exact format of the underlying + stack trace. +

+ + + + + + Provides methods to support various naming and other conventions used throughout the framework. + Mainly for internal use within the framework. + + Rob Harrop + Juergen Hoeller + Mark Pollack (.NET) + + + Convert Strings in attribute name format (lowercase, hyphens separating words) + into property name format (camel-cased). For example, transaction-manager is + converted into transactionManager. + + + + + Convenience class that exposes a signature that matches the + delegate. + + +

+ Useful when filtering members via the + mechanism. +

+ + Rick Evans + + + + Creates a new instance of the + class. + + + + + Returns true if the supplied instance + satisfies the supplied (which must be an + implementation). + + + The instance that will be checked to see if + it matches the supplied . + + + The criteria against which to filter the supplied + instance. + + + True if the supplied instance + satisfies the supplied (which must be an + implementation); false if not or the + supplied is not an + implementation or is null. + + + + + Interface that can be implemented by exceptions etc that are error coded. + + +

+ The error code is a , rather than a number, so it can + be given user-readable values, such as "object.failureDescription". +

+ + Rod Johnson + Aleksandar Seovic (.Net) + + + + Return the error code associated with this failure. + + +

+ The GUI can render this anyway it pleases, allowing for I18n etc. +

+ + + The error code associated with this failure, + or the empty string instance if not error-coded. + + + + + Thrown in response to referring to an invalid property (most often via reflection). + + Rick Evans + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + The that is (or rather was) the source of the + offending property. + + + The name of the offending property. + + + + + Creates a new instance of the + class. + + + The that is (or rather was) the source of the + offending property. + + + The name of the offending property. + + + A message about the exception. + + + + + Creates a new instance of the InvalidPropertyException class. + + + The that is (or rather was) the source of the + offending property. + + + The name of the offending property. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + The that is (or rather was) the source of the + offending property. + + + + + The name of the offending property. + + + + + Extension of the interface, expressing a 'priority' + ordering: Order values expressed by IPriorityOrdered objects always + apply before order values of 'plain' Ordered values. + + + This is primarily a special-purpose interface, used for objects + where it is particularly important to determine 'prioritized' + objects first, without even obtaining the remaining objects. + A typical example: Prioritized post-processors in a Spring + + + IPriorityOrdered post-processor objects are initialized in + a special phase, ahead of other post-processor objects. + + Juergen Hoeller + Mark Pollack (.NET) + + + + + + + Criteria that is satisfied if the of each of the + arguments matches each of the parameter s of a given + . + + +

+ If no array is passed to the overloaded constructor, + any method that has no parameters will satisfy an instance of this + class. The same effect could be achieved by passing the + array to the overloaded constructor. +

+ + Rick Evans + Bruno Baia + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + +

+ If the supplied array is null, then this + constructor uses the array. +

+ + + The array that this criteria will use to + check parameter s. + + + + + Does the supplied satisfy the criteria encapsulated by + this instance? + + +

+ This implementation respects the inheritance chain of any parameter + s... i.e. methods that have a base type (or + interface) that is assignable to the in the + same corresponding index of the parameter types will satisfy this + criteria instance. +

+ + The datum to be checked by this criteria instance. + + True if the supplied satisfies the criteria encapsulated + by this instance; false if not or the supplied is null. + + + + + Criteria that is satisfied if the number of generic arguments to a given + matches an arbitrary number. + + +

+ This class supports checking the generic arguments count of both + generic methods and constructors. +

+ + Bruno Baia + + + + Creates a new instance of the + class. + + +

+ This constructor sets the + + property to zero (0). +

+ + + + + Creates a new instance of the + class. + + + The number of generic arguments that a + must have to satisfy this criteria. + + + If the supplied is less + than zero. + + + + + Does the supplied satisfy the criteria encapsulated by + this instance? + + The datum to be checked by this criteria instance. + + True if the supplied satisfies the criteria encapsulated + by this instance; false if not or the supplied is null. + + + + + The number of generic arguments that a + must have to satisfy this criteria. + + + If the supplied value is less than zero. + + + + + Thrown when a method (typically a property getter or setter invoked via reflection) + throws an exception, analogous to a . + + Rod Johnson + Mark Pollack (.NET) + + + + Superclass for exceptions related to a property access, such as a + mismatch or a target invocation exception. + + Rod Johnson + Mark Pollack (.NET) + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + Create a new instance of the PropertyAccessException class. + + + A message about the exception. + + Describes the change attempted on the property. + + + + Create a new instance of the PropertyAccessException class. + + + A message about the exception. + + Describes the change attempted on the property. + + The root exception that is being wrapped. + + + + + Creates a new instance of the PropertyAccessException class. + + + + + Creates a new instance of the PropertyAccessException class. + + + A message about the exception. + + + + + Creates a new instance of the PropertyAccessExceptionsException class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the PropertyAccessExceptionsException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Returns the PropertyChangeEventArgs that resulted in the problem. + + + + + The string error code used to classify the error. + + + + + Creates a new instance of the MethodInvocationException class. + + + + + Creates a new instance of the MethodInvocationException class. + + + A message about the exception. + + + + + Creates a new instance of the MethodInvocationException class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Constructor to use when an exception results from a + . + + + The raised by the invoked property. + + + The that + resulted in an exception. + + + + + Creates a new instance of the MethodInvocationException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + The error code string for this exception. + + + + + Criteria that is satisfied if the method Name of an + instance matches a + supplied string pattern. + + + + Supports the following simple pattern styles: + "xxx*", "*xxx" and "*xxx*" matches, as well as direct equality. + + + Bruno Baia + + + + Creates a new instance of the + class. + + +

+ This constructor sets the + + property to * (any method name). +

+ + + + + Creates a new instance of the + class. + + The pattern that names + must match against in order to satisfy this criteria. + + If the supplied is null or resolve to an empty string. + + + + + Does the supplied satisfy the criteria encapsulated by + this instance? + + The datum to be checked by this criteria instance. + + True if the supplied satisfies the criteria encapsulated + by this instance; false if not or the supplied is null. + + + + + The number of parameters that a + must have to satisfy this criteria. + + + If the supplied value is null or resolve to an empty string. + + + + + Helper class that encapsulates the specification of a method parameter, i.e. + a MethodInfo or ConstructorInfo plus a parameter index. + Useful as a specification object to pass along. + + Juergen Hoeller + Rob Harrop + Mark Pollack (.NET) + + + + Initializes a new instance of the class for the given + MethodInfo. + + The MethodInfo to specify a parameter for. + Index of the parameter. + + + + Initializes a new instance of the class. + + The ConstructorInfo to specify a parameter for. + Index of the parameter. + + + + Create a new MethodParameter for the given method or donstructor. + This is a convenience constructor for scenarios where a + Method or Constructor reference is treated in a generic fashion. + + The method or constructor to specify a parameter for. + Index of the parameter. + the corresponding MethodParameter instance + + + + Parameters the name of the method/constructor parameter. + + the parameter name. + + + + Gets the type of the method/constructor parameter. + + The type of the parameter. (never null) + + + + Gets the wrapped MethodInfo, if any. Note Either MethodInfo or ConstructorInfo is available. + + The MethodInfo, or null if none. + + + + Gets wrapped ConstructorInfo, if any. Note Either MethodInfo or ConstructorInfo is available. + + The ConstructorInfo, or null if none + + + + Criteria that is satisfied if the number of parameters to a given + matches an arbitrary number. + + +

+ This class supports checking the parameter count of both methods and + constructors. +

+

+ Default parameters, etc need to taken into account. +

+ + Rick Evans + + + + Creates a new instance of the + class. + + +

+ This constructor sets the + + property to zero (0). +

+ + + + + Creates a new instance of the + class. + + + The number of parameters that a + must have to satisfy this criteria. + + + If the supplied is less + than zero. + + + + + Does the supplied satisfy the criteria encapsulated by + this instance? + + The datum to be checked by this criteria instance. + + True if the supplied satisfies the criteria encapsulated + by this instance; false if not or the supplied is null. + + + + + The number of parameters that a + must have to satisfy this criteria. + + + If the supplied value is less than zero. + + + + + Criteria that is satisfied if the of each of the + parameters of a given matches each + of the parameter s of a given + . + + +

+ If no array is passed to the overloaded constructor, + any method that has no parameters will satisfy an instance of this + class. The same effect could be achieved by passing the + array to the overloaded constructor. +

+ + Rick Evans + Bruno Baia + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + +

+ If the supplied array is null, then this + constructor uses the array. +

+ + + The array that this criteria will use to + check parameter s. + + + + + Does the supplied satisfy the criteria encapsulated by + this instance? + + The datum to be checked by this criteria instance. + + True if the supplied satisfies the criteria encapsulated + by this instance; false if not or the supplied is null. + + + + + Criteria that is satisfied if the return of a given + matches a given . + + Rick Evans + + + + The return to match against if no + is provided explictly. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The that the return type of a given + must match in order to satisfy + this criteria. + + + + + Does the supplied satisfy the criteria encapsulated by + this instance? + + The datum to be checked by this criteria instance. + + True if the supplied satisfies the criteria encapsulated + by this instance; false if not or the supplied is null. + + + + + The that the return type of a given + must match in order to satisfy + this criteria. + + + + + Thrown in response to a failed attempt to read a property. + + +

+ Typically thrown when attempting to read the value of a write-only + property via reflection. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + The that is (or rather was) the source of the + offending property. + + + The name of the offending property. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Thrown in response to a failed attempt to write a property. + + Mark Pollack (.NET) + + + + Creates a new instance of the NotWritablePropertyException class. + + + + + Creates a new instance of the NotWritablePropertyException class. + + + A message about the exception. + + + + + Creates a new instance of the NotWritablePropertyException class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the NotWritablePropertyException class. + + + The that is (or rather was) the source of the + offending property. + + + The name of the offending property. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the NotWritablePropertyException class + summarizing what property was not writable. + + + The name of the property that is not writable. + + + The in which the property is not writable. + + + + + Creates new NotWritablePropertyException with a root cause. + + + The name of the property that is not writable. + + + The in which the property is not writable. + + + The root cause indicating why the property was not writable. + + + + + Creates a new instance of the NotWritablePropertyException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Thrown in response to encountering a value + when traversing a nested path expression. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The of the object where the property was not found. + + The name of the property not found. + + + + Creates a new instance of the + class. + + + The of the object where the property was not found. + + The name of the property not found. + A message about the exception. + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + The name of the offending property. + + + + + The of the class where the property was last looked for. + + + + + Comparator implementation for objects, sorting by + order value ascending (resp. by priority descending). + + +

+ Non- objects are treated as greatest order values, + thus ending up at the end of a list, in arbitrary order (just like same order values of + objects). +

+ + Juergen Hoeller + Aleksandar Seovic (.Net) + + + + Compares two objects and returns a value indicating whether one is less than, + equal to or greater than the other. + + +

+ Uses direct evaluation instead of + to avoid unnecessary boxing. +

+ + The first object to compare. + The second object to compare. + + -1 if first object is less then second, 1 if it is greater, or 0 if they are equal. + + + + + Handle the case when both objects have equal sort order priority. By default returns 0, + but may be overriden for handling special cases. + + The first object to compare. + The second object to compare. + + -1 if first object is less then second, 1 if it is greater, or 0 if they are equal. + + + + + Provides additional data for the PropertyChanged event. + + +

+ Provides some additional properties over and above the name of the + property that has changed (which is inherited from the + base class). + This allows calling code to determine whether or not a property has + actually changed (i.e. a PropertyChanged event may have been + raised, but the value itself may be equivalent). +

+ + + + + + Create a new instance of the + class. + + + The name of the property that was changed. + The old value of the property. + the new value of the property. + + + + Get the old value for the property. + + + + + + Get the new value of the property. + + + + + + A base class for all + implementations that are regular expression based. + + Rick Evans + + + + The default pattern... matches absolutely anything. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The regular expression pattern to be applied. + + + + + Does the supplied satisfy the criteria encapsulated by + this instance? + + The datum to be checked by this criteria instance. + + True if the supplied satisfies the criteria encapsulated + by this instance; false if not or the supplied is null. + + + + + Convenience method that calls the + + on the supplied . + + The input to match against. + True if the matches. + + + + The regular expression pattern to be applied. + + + + + The regular expression options to be applied. + + + + + The regular expression to be applied. + + + + + Criteria that is satisfied if the Name property of an + instance matches a + supplied regular expression pattern. + + Rick Evans + + + + The default event name pattern... matches pretty much any event name. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The pattern that names + must match against in order to satisfy this criteria. + + + + + Does the supplied satisfy the criteria encapsulated by + this instance? + + The datum to be checked by this criteria instance. + + True if the supplied satisfies the criteria encapsulated + by this instance; false if not or the supplied is null. + + + + + Criteria that is satisfied if the Name property of an + instance matches a + supplied regular expression pattern. + + Rick Evans + + + + The default method name pattern... matches pretty much any method name. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The pattern that names + must match against in order to satisfy this criteria. + + + + + Does the supplied satisfy the criteria encapsulated by + this instance? + + The datum to be checked by this criteria instance. + + True if the supplied satisfies the criteria encapsulated + by this instance; false if not or the supplied is null. + + + + + Exception thrown on a mismatch when trying to set a property + or resolve an argument to a method invocation. + + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + + + + Creates a new instance of the TypeMismatchException class. + + + + + Creates a new instance of the TypeMismatchException class. + + + A message about the exception. + + + + + Creates a new instance of the TypeMismatchException class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the TypeMismatchException class describing the + property and required type that could not used to set a property on the target object. + + + The description of the property that was to be changed. + + The target conversion type. + + + + Creates a new instance of the TypeMismatchException class describing the + property, required type, and underlying exception that could not be used + to set a property on the target object. + + + The description of the property that was to be changed. + + The target conversion type. + The underlying exception. + + + + Creates a new instance of the TypeMismatchException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + The string error code used to classify the exception. + + + + + Abstract base class for implementations. + + Aleksandar Seovic + + + + An interface that defines the methods that have to be implemented by all data bindings. + + Aleksandar Seovic + + + + Binds source object to target object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + + + Binds source object to target object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + Variables that should be used during expression evaluation. + + + + + Binds target object to source object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + + + Binds target object to source object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + Variables that should be used during expression evaluation. + + + + + Sets error message that should be displayed in the case + of a non-fatal binding error. + + + Resource ID of the error message. + + + List of error providers message should be added to. + + + + + The name of the always filled error provider + + + + + Gets or sets a flag specifying whether this binding is valid. + + + true if this binding evaluated without errors; + false otherwise. + + + + + Marks this binding's state as invalid for this validationErrors collection. + Returns false if is null. + + + false, if validationErrors is null + + + + Initializes a new instance of the class. + + + + + Binds source object to target object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + + + Binds target object to source object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + + + Binds source object to target object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + Variables that should be used during expression evaluation. + + + + + Binds target object to source object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + Variables that should be used during expression evaluation. + + + + + Sets error message that should be displayed in the case + of a non-fatal binding error. + + + Resource ID of the error message. + + + List of error providers message should be added to. + + + + + Determines whether the specified is equal to the current . + + + true if the specified is equal to the current ; otherwise, false. + + The to compare with the current . 2 + + + + Serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Gets the unique ID of this binding instance. + + + + + Gets or sets the . + + The binding direction. + + + + Gets the error message. + + The error message. + + + + Gets the error providers. + + + + + Abstract base class for simple, one-to-one implementations. + + Aleksandar Seovic + + + + Initialize a new instance of without any + + + + + Initialize a new instance of with the + specified . + + + + + Binds source object to target object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + Variables that should be used during expression evaluation. + + + + + Concrete implementation if source to target binding. + + + The source object. + + + The target object. + + + Variables that should be used during expression evaluation. + + + + + Binds target object to source object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + Variables that should be used during expression evaluation. + + + + + Concrete implementation of target to source binding. + + + The source object. + + + The target object. + + + Variables that should be used during expression evaluation. + + + + + Gets the source value for the binding. + + + Source object to extract value from. + + + Variables for expression evaluation. + + + The source value for the binding. + + + + + Sets the source value for the binding. + + + The source object to set the value on. + + + The value to set. + + + Variables for expression evaluation. + + + + + Gets the target value for the binding. + + + Source object to extract value from. + + + Variables for expression evaluation. + + + The target value for the binding. + + + + + Sets the target value for the binding. + + + The target object to set the value on. + + + The value to set. + + + Variables for expression evaluation. + + + + + Gets or sets the to use. + + The formatter to use. + + + + Base implementation of the . + + Aleksandar Seovic + + + + An interface that has to be implemented by all data binding containers. + + Aleksandar Seovic + + + + Adds the binding. + + + Binding definition to add. + + + Added instance. + + + + + Adds the binding with a default + binding direction of . + + + This is a convinience method for adding SimpleExpressionBinding, + one of the most often used binding types, to the bindings list. + + + The source expression. + + + The target expression. + + + Added instance. + + + + + Adds the binding. + + + This is a convinience method for adding SimpleExpressionBinding, + one of the most often used binding types, to the bindings list. + + + The source expression. + + + The target expression. + + + Binding direction. + + + Added instance. + + + + + Adds the binding with a default + binding direction of . + + + This is a convinience method for adding SimpleExpressionBinding, + one of the most often used binding types, to the bindings list. + + + The source expression. + + + The target expression. + + + to use for value formatting and parsing. + + + Added instance. + + + + + Adds the binding. + + + This is a convinience method for adding SimpleExpressionBinding, + one of the most often used binding types, to the bindings list. + + + The source expression. + + + The target expression. + + + Binding direction. + + + to use for value formatting and parsing. + + + Added instance. + + + + + Gets a value indicating whether this data binding container + has bindings. + + + true if this data binding container has bindings; + false otherwise. + + + + + Creates a new instance of . + + + + + Adds the binding. + + + Binding definition to add. + + + Added instance. + + + + + Adds the binding with a default + binding direction of . + + + The source expression. + + + The target expression. + + + Added instance. + + + + + Adds the binding. + + + The source expression. + + + The target expression. + + + Binding direction. + + + Added instance. + + + + + Adds the binding with a default + binding direction of . + + + The source expression. + + + The target expression. + + + to use for value formatting and parsing. + + + Added instance. + + + + + Adds the binding. + + + The source expression. + + + The target expression. + + + Binding direction. + + + to use for value formatting and parsing. + + + Added instance. + + + + + Binds source object to target object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + + + Binds source object to target object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + Variables that should be used during expression evaluation. + + + + + Binds target object to source object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + + + Binds target object to source object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + Variables that should be used during expression evaluation. + + + + + Implemented as a NOOP for containers. + of a non-fatal binding error. + + + Resource ID of the error message. + + + List of error providers message should be added to. + + + + + Gets a list of bindings for this container. + + + A list of bindings for this container. + + + + + Gets a value indicating whether this instance has bindings. + + + true if this instance has bindings; otherwise, false. + + + + + BaseBindingManager keeps track of all registered bindings and + represents an entry point for the binding and unbinding process. + + Aleksandar Seovic + + + + Initializes a new instance of the class. + + + + + Enumeration that defines possible values for data binding direction. + + Aleksandar Seovic + + + + Specifies that value from the control property should be bound to a data model. + + + + + Specifies that value from the data model should be bound to control property. + + + + + Specifies that binding is bidirectional. + + + + + Represents an ErrorMessage specific to a binding instance. + + Erich Eichinger + + + + Represents a single validation error message. + + Aleksandar Seovic + Goran Milosavljevic + + + + Default constructor. + + + + + Initializes a new instance of the class. + + Error message resource identifier. + Parameters that should be used for message resolution. + + + + Initializes a new instance of the class copying values from another instance. + + Another Error message instance to copy values from. + + + + This property is reserved, apply the + + to the class instead. + + + An + that describes the XML representation of the object that + is produced by the + + method and consumed by the + + method. + + + + + + Generates an object from its XML representation. + + + The stream + from which the object is deserialized. + + + + + Converts an object into its XML representation. + + + The stream + to which the object is serialized. + + + + + Resolves the message against specified . + + Message source to resolve this error message against. + Resolved error message. + + + + Determines whether the specified is equal to the current . + + + true if the specified is equal to the current ; otherwise, false. + + The to compare with the current . 2 + + + + Serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Gets or sets the resource identifier for this message. + + The resource identifier for this message. + + + + Gets or sets the message parameters. + + The message parameters. + + + + Initializes a new instance of the class. + + the id of the binding this error message is associated with + the message id + optional parameters to this message + + + + Generates an object from its XML representation. + + + The stream + from which the object is deserialized. + + + + + Converts an object into its XML representation. + + + The stream + to which the object is serialized. + + + + + Determines whether the specified is equal to the current . + + + true if the specified is equal to the current ; otherwise, false. + + The to compare with the current . 2 + + + + Serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Get the ID of the binding this message instance relates to. + + + + + Interface that should be implemented by data bound objects, such as + web pages, user controls, windows forms, etc. + + Aleksandar Seovic + + + + Gets the binding manager. + + The binding manager. + + + + implementation that allows + data binding between collections that implement + interface. + + Aleksandar Seovic + + + + Binds source object to target object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + Variables that should be used during expression evaluation. + + + + + Binds target object to source object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + Variables that should be used during expression evaluation. + + + + + Simple, expression-based implementation of that + binds source to target one-to-one. + + Aleksandar Seovic + + + + Initializes a new instance of the class. + + + The source expression. + + + The target expression. + + + + + Initializes a new instance of the class. + + + The source expression. + + + The target expression. + + + The formatter to use. + + + + + Gets the source value for the binding. + + + Source object to extract value from. + + + Variables for expression evaluation. + + + The source value for the binding. + + + + + Sets the source value for the binding. + + + The source object to set the value on. + + + The value to set. + + + Variables for expression evaluation. + + + + + Gets the target value for the binding. + + + Source object to extract value from. + + + Variables for expression evaluation. + + + The target value for the binding. + + + + + Sets the target value for the binding. + + + The target object to set the value on. + + + The value to set. + + + Variables for expression evaluation. + + + + + Gets the source expression. + + The source expression. + + + + Gets the target expression. + + The target expression. + + + + Minimal AST node interface used by ANTLR AST generation and tree-walker. + + + + + Add a (rightmost) child to this node + + + + + + Get the first child of this node; null if no children + + + + + Get the next sibling in line after this one + + + + + Get the token text for this node + + + + + + Get number of children of this node; if leaf, returns 0 + + Number of children + + + + Set the first child of a node. + + + + + + Set the next sibling after this one. + + + + + + Set the token text for this node + + + + + + Set the token type for this node + + + + + + Get the token type for this node + + + + + Event type. + + + + Used for creating Token instances. + + + Used for caching lookahead characters. + + + + This method is executed by ANTLR internally when it detected an illegal + state that cannot be recovered from. + The previous implementation of this method called + and writes directly to , which is usually not + appropriate when a translator is embedded into a larger application. + + Error message. + + + + A creator of Token object instances. + + + + This class and it's sub-classes exists primarily as an optimization + of the reflection-based mechanism(s) previously used exclusively to + create instances of Token objects. + + + Since Lexers in ANTLR use a single Token type, each TokenCreator can + create one class of Token objects (that's why it's not called TokenFactory). + + + + + + Constructs a instance. + + + + + Returns the fully qualified name of the Token type that this + class creates. + + + + + The fully qualified name of the Token type to create. + + + + + Type object used as a template for creating tokens by reflection. + + + + + Returns the fully qualified name of the Token type that this + class creates. + + + + + Constructs a instance. + + + + + Returns the fully qualified name of the Token type that this + class creates. + + + + This type was created in VisualAge. + + + + Report exception errors caught in nextToken() + + + + Parser error-reporting function can be overridden in subclass + + + + Parser warning-reporting function can be overridden in subclass + + + + + Represents a stream of characters fed to the lexer from that can be rewound + via mark()/rewind() methods. + + + + A dynamic array is used to buffer up all the input characters. Normally, + "k" characters are stored in the buffer. More characters may be stored + during guess mode (testing syntactic predicate), or when LT(i>k) is referenced. + Consumption of characters is deferred. In other words, reading the next + character is not done by conume(), but deferred until needed by LA or LT. + + + + + This should NOT be called from anyone other than ParserEventSupport! + + + + This should NOT be called from anyone other than ParserEventSupport! + + + + + Provides an abstract base for implementing subclasses. + + + + This abstract class is provided to make it easier to create s. + You should extend this base class rather than creating your own. + + + + + + Handle the "Done" event. + + Event source object + Event data object + + + + Handle the "CharConsumed" event. + + Event source object + Event data object + + + + Handle the "CharLA" event. + + Event source object + Event data object + + + + Handle the "Mark" event. + + Event source object + Event data object + + + + Handle the "Rewind" event. + + Event source object + Event data object + + + charBufferConsume method comment. + + + + charBufferLA method comment. + + + + + @deprecated as of 2.7.2. This method calls System.exit() and writes + directly to stderr, which is usually not appropriate when + a parser is embedded into a larger application. Since the method is + static, it cannot be overridden to avoid these problems. + ANTLR no longer uses this method internally or in generated code. + + + + + + Specify an object with support code (shared by Parser and TreeParser. + Normally, the programmer does not play with this, using + instead. + + + + + + Specify the type of node to create during tree building. + + Fully qualified AST Node type name. + + + + Specify the type of node to create during tree building. + use now to be consistent with + Token Object Type accessor. + + Fully qualified AST Node type name. + + + + + + + + Get another token object from the token stream + + + + Return the token type of the ith token of lookahead where i=1 + is the current token being examined by the parser (i.e., it + has not been matched yet). + + + + Make sure current lookahead symbol matches token type t. + Throw an exception upon mismatch, which is catch by either the + error handler or by the syntactic predicate. + + + + Make sure current lookahead symbol matches the given set + Throw an exception upon mismatch, which is catch by either the + error handler or by the syntactic predicate. + + + + Parser error-reporting function can be overridden in subclass + + + + Parser error-reporting function can be overridden in subclass + + + + Parser warning-reporting function can be overridden in subclass + + + + User can override to do their own debugging + + + + This should NOT be called from anyone other than ParserEventSupport! + + + + + Provides an abstract base for implementing subclasses. + + + + This abstract class is provided to make it easier to create s. + You should extend this base class rather than creating your own. + + + + + + Handle the "Done" event. + + Event source object + Event data object + + + + Handle the "ReportError" event. + + Event source object + Event data object + + + + Handle the "ReportWarning" event. + + Event source object + Event data object + + + This should NOT be called from anyone other than ParserEventSupport! + + + + A class to assist in firing parser events + NOTE: I intentionally _did_not_ synchronize the event firing and + add/remove listener methods. This is because the add/remove should + _only_ be called by the parser at its start/end, and the _same_thread_ + should be performing the parsing. This should help performance a tad... + + + + + Provides an abstract base for implementing subclasses. + + + + This abstract class is provided to make it easier to create s. + You should extend this base class rather than creating your own. + + + + + + Handle the "Done" event. + + Event source object + Event data object + + + + Handle the "EnterRule" event + + Event source object + Event data object + + + + Handle the "ExitRule" event + + Event source object + Event data object + + + + Handle the "Consume" event. + + Event source object + Event data object + + + + Handle the "ParserLA" event. + + Event source object + Event data object + + + + Handle the "Match" event. + + Event source object + Event data object + + + + Handle the "MatchNot" event. + + Event source object + Event data object + + + + Handle the "MisMatch" event. + + Event source object + Event data object + + + + Handle the "MisMatchNot" event. + + Event source object + Event data object + + + + Handle the "ReportError" event. + + Event source object + Event data object + + + + Handle the "ReportWarning" event. + + Event source object + Event data object + + + + Handle the "SemPreEvaluated" event. + + Event source object + Event data object + + + + Handle the "SynPredFailed" event. + + Event source object + Event data object + + + + Handle the "SynPredStarted" event. + + Event source object + Event data object + + + + Handle the "SynPredSucceeded" event. + + Event source object + Event data object + + + This should NOT be called from anyone other than ParserEventSupport! + + + + + Provides an abstract base for implementing subclasses. + + + + This abstract class is provided to make it easier to create s. + You should extend this base class rather than creating your own. + + + + + + Handle the "Done" event. + + Event source object + Event data object + + + + Handle the "Match" event. + + Event source object + Event data object + + + + Handle the "MatchNot" event. + + Event source object + Event data object + + + + Handle the "MisMatch" event. + + Event source object + Event data object + + + + Handle the "MisMatchNot" event. + + Event source object + Event data object + + + + Provides an abstract base for implementing subclasses. + + + + This abstract class is provided to make it easier to create s. + You should extend this base class rather than creating your own. + + + + + + Handle the "Done" event. + + Event source object + Event data object + + + + Handle the "EnterRule" event + + Event source object + Event data object + + + + Handle the "ExitRule" event + + Event source object + Event data object + + + This should NOT be called from anyone other than ParserEventSupport! + + + + + Provides an abstract base for implementing subclasses. + + + + This abstract class is provided to make it easier to create s. + You should extend this base class rather than creating your own. + + + + + + Handle the "Done" event. + + Event source object + Event data object + + + + Handle the "Consume" event. + + Event source object + Event data object + + + + Handle the "ParserLA" event. + + Event source object + Event data object + + + + Specifies the behaviour required (i.e. parser modifications) + specifically to support parse tree debugging and derivation. + + + + Override the standard matching and rule entry/exit routines + to build parse trees. This class is useful for 2.7.3 where + you can specify a superclass like + + + class TinyCParser extends Parser(ParseTreeDebugParser); + + + + + + Each new rule invocation must have it's own subtree. Tokens are + added to the current root so we must have a stack of subtree roots. + + + + + Track most recently created parse subtree so that when parsing + is finished, we can get to the root. + + + + + For every rule replacement with a production, we bump up count. + + + + + Adds LT(1) to the current parse subtree. + + + + Note that the match() routines add the node before checking for + correct match. This means that, upon mismatched token, there + will a token node in the tree corresponding to where that token + was expected. For no viable alternative errors, no node will + be in the tree as nothing was matched() (the lookahead failed + to predict an alternative). + + + + + + Create a rule node, add to current tree, and make it current root + + + + + + Pop current root; back to adding to old root + + + + + A class to assist in firing parser events + NOTE: I intentionally _did_not_ synchronize the event firing and + add/remove listener methods. This is because the add/remove should + _only_ be called by the parser at its start/end, and the _same_thread_ + should be performing the parsing. This should help performance a tad... + + + + This should NOT be called from anyone other than ParserEventSupport! + + + + + Provides an abstract base for implementing subclasses. + + + + This abstract class is provided to make it easier to create s. + You should extend this base class rather than creating your own. + + + + + + Handle the "Done" event. + + Event source object + Event data object + + + + Handle the "SemPreEvaluated" event. + + Event source object + Event data object + + + + Provides an abstract base for implementing subclasses. + + + + This abstract class is provided to make it easier to create s. + You should extend this base class rather than creating your own. + + + + + + Handle the "Done" event. + + Event source object + Event data object + + + + Handle the "SynPredFailed" event. + + Event source object + Event data object + + + + Handle the "SynPredStarted" event. + + Event source object + Event data object + + + + Handle the "SynPredSucceeded" event. + + Event source object + Event data object + + + This should NOT be called from anyone other than ParserEventSupport! + + + + + AST Support code shared by TreeParser and Parser. + + + + We use delegation to share code (and have only one + bit of code to maintain) rather than subclassing + or superclassing (forces AST support code to be + loaded even when you don't want to do AST stuff). + + + Typically, is used to specify the + homogeneous type of node to create, but you can override + to make heterogeneous nodes etc... + + + + + + Constructs an ASTFactory with the default AST node type of + . + + + + + Constructs an ASTFactory and use the specified AST node type + as the default. + + + Name of default AST node type for this factory. + + + + + Constructs an ASTFactory and use the specified AST node type + as the default. + + + MetaType of default AST node type for this factory. + + + + + Stores the Type of the default AST node class to be used during tree construction. + + + + + Stores the mapping between custom AST NodeTypes and their NodeTypeName/NodeTypeClass + and ASTNodeCreator. + + + + + Stores the mapping between AST node typenames and their token ID. + + + + + Specify an "override" for the type created for + the specified Token type. + + + This method is useful for situations that ANTLR cannot oridinarily deal + with (i.e., when you create a token based upon a nonliteral token symbol + like #[LT(1)]. This is a runtime value and ANTLR cannot determine the token + type (and hence the AST) statically. + + Token type to override. + + Fully qualified AST typename (or null to specify + the factory's default AST type). + + + + + Register an AST Node Type for a given Token type ID. + + The Token type ID. + The AST Node Type to register. + + + + Register an ASTNodeCreator for a given Token type ID. + + The Token type ID. + The creater to register. + + + + Register an ASTNodeCreator to be used for creating node by default. + + The ASTNodeCreator. + + + + Pre-expands the internal list of TokenTypeID-to-ASTNodeType mappings + to the specified size. + This is primarily a convenience method that can be used to prevent + unnecessary and costly re-org of the mappings list. + + Maximum Token Type ID. + + + + Add a child to the current AST + + The AST to add a child to + The child AST to be added + + + + Creates a new uninitialized AST node. Since a specific AST Node Type + wasn't indicated, the new AST node is created using the current default + AST Node type - + + An uninitialized AST node object. + + + + Creates and initializes a new AST node using the specified Token Type ID. + The used for creating this new AST node is + determined by the following: + + the current TokenTypeID-to-ASTNodeType mapping (if any) or, + the otherwise + + + Token type ID to be used to create new AST Node. + An initialized AST node object. + + + + Creates and initializes a new AST node using the specified Token Type ID. + The used for creating this new AST node is + determined by the following: + + the current TokenTypeID-to-ASTNodeType mapping (if any) or, + the otherwise + + + Token type ID to be used to create new AST Node. + Text for initializing the new AST Node. + An initialized AST node object. + + + + Creates a new AST node using the specified AST Node Type name. Once created, + the new AST node is initialized with the specified Token type ID and string. + The used for creating this new AST node is + determined solely by ASTNodeTypeName. + The AST Node type must have a default/parameterless constructor. + + Token type ID to be used to create new AST Node. + Text for initializing the new AST Node. + Fully qualified name of the Type to be used for creating the new AST Node. + An initialized AST node object. + + + + Creates a new AST node using the specified AST Node Type name. + + Token instance to be used to initialize the new AST Node. + + Fully qualified name of the Type to be used for creating the new AST Node. + + A newly created and initialized AST node object. + + Once created, the new AST node is initialized with the specified Token + instance. The used for creating this new AST + node is determined solely by ASTNodeTypeName. + The AST Node type must have a default/parameterless constructor. + + + + + Creates and initializes a new AST node using the specified AST Node instance. + the new AST node is initialized with the specified Token type ID and string. + The used for creating this new AST node is + determined solely by aNode. + The AST Node type must have a default/parameterless constructor. + + AST Node instance to be used for creating the new AST Node. + An initialized AST node object. + + + + Creates and initializes a new AST node using the specified Token instance. + The used for creating this new AST node is + determined by the following: + + the current TokenTypeID-to-ASTNodeType mapping (if any) or, + the otherwise + + + Token instance to be used to create new AST Node. + An initialized AST node object. + + + + Returns a copy of the specified AST Node instance. The copy is obtained by + using the method Clone(). + + AST Node to copy. + An AST Node (or null if t is null). + + + + Duplicate AST Node tree rooted at specified AST node and all of it's siblings. + + Root of AST Node tree. + Root node of new AST Node tree (or null if t is null). + + + + Duplicate AST Node tree rooted at specified AST node. Ignore it's siblings. + + Root of AST Node tree. + Root node of new AST Node tree (or null if t is null). + + + + Make a tree from a list of nodes. The first element in the + array is the root. If the root is null, then the tree is + a simple list not a tree. Handles null children nodes correctly. + For example, build(a, b, null, c) yields tree (a b c). build(null,a,b) + yields tree (nil a b). + + List of Nodes. + AST Node tree. + + + + Make a tree from a list of nodes, where the nodes are contained + in an ASTArray object. + + List of Nodes. + AST Node tree. + + + + Make an AST the root of current AST. + + + + + + + Sets the global default AST Node Type for this ASTFactory instance. + This method also attempts to load the instance + for the specified typename. + + Fully qualified AST Node Type name. + + + + To change where error messages go, can subclass/override this method + and then setASTFactory in Parser and TreeParser. This method removes + a prior dependency on class antlr.Tool. + + + + + + A creator of AST node instances. + + + + This class and it's sub-classes exists primarily as an optimization + of the reflection-based mechanism(s) previously used exclusively to + create instances of AST node objects. + + + Parsers and TreeParsers already use the ASTFactory class in ANTLR whenever + they need to create an AST node objeect. What this class does is to support + performant extensibility of the basic ASTFactory. The ASTFactory can now be + extnded as run-time to support more new AST node types without using needing + to use reflection. + + + + + + Constructs an instance. + + + + + Returns the fully qualified name of the AST type that this + class creates. + + + + + Summary description for ASTVisitor. + + + + + Get number of children of this node; if leaf, returns 0 + + Number of children + + + + Small buffer used to avoid reading individual chars + + + + + Small buffer used to avoid reading individual chars + + + + + Constructs a instance. + + + + + Returns the fully qualified name of the AST type that this + class creates. + + + + + Constructs a instance. + + + + + Returns the fully qualified name of the AST type that this + class creates. + + + + + A token is minimally a token type. Subclasses can add the text matched + for the token and line info. + + + + + Constructs a instance. + + + + + Returns the fully qualified name of the Token type that this + class creates. + + + + + Constructs a instance. + + + + + Returns the fully qualified name of the Token type that this + class creates. + + + + + Summary description for DumpASTVisitor. + + Simple class to dump the contents of an AST to the output + + + + Append a char to the msg buffer. If special, then show escaped version + + Message buffer + Char to append + + + + Walk parse tree and return requested number of derivation steps. + If steps less-than 0, return node text. If steps equals 1, return derivation + string at step. + + derivation steps + + + + + Get derivation and return how many you did (less than requested for + subtree roots. + + string buffer + derivation steps + + + + + Do a step-first walk, building up a buffer of tokens until + you've reached a particular step and print out any rule subroots + insteads of descending. + + derivation buffer + derivation steps + + + + + This token stream tracks the *entire* token stream coming from + a lexer, but does not pass on the whitespace (or whatever else + you want to discard) to the parser. + + + + This class can then be asked for the ith token in the input stream. + Useful for dumping out the input stream exactly after doing some + augmentation or other manipulations. Tokens are index from 0..n-1 + + + You can insert stuff, replace, and delete chunks. Note that the + operations are done lazily--only if you convert the buffer to a + string. This is very efficient because you are not moving data around + all the time. As the buffer of tokens is converted to strings, the + toString() method(s) check to see if there is an operation at the + current index. If so, the operation is done and then normal string + rendering continues on the buffer. This is like having multiple Turing + machine instruction streams (programs) operating on a single input tape. :) + + + Since the operations are done lazily at toString-time, operations do not + screw up the token index values. That is, an insert operation at token + index i does not change the index values for tokens i+1..n-1. + + + Because operations never actually alter the buffer, you may always get + the original token stream back without undoing anything. Since + the instructions are queued up, you can easily simulate transactions and + roll back any changes if there is an error just by removing instructions. + For example, + + For example: + + TokenStreamRewriteEngine rewriteEngine = new TokenStreamRewriteEngine(lexer); + JavaRecognizer parser = new JavaRecognizer(rewriteEngine); + ... + rewriteEngine.insertAfter("pass1", t, "foobar");} + rewriteEngine.insertAfter("pass2", u, "start");} + System.Console.Out.WriteLine(rewriteEngine.ToString("pass1")); + System.Console.Out.WriteLine(rewriteEngine.ToString("pass2")); + + + + You can also have multiple "instruction streams" and get multiple + rewrites from a single pass over the input. Just name the instruction + streams and use that name again when printing the buffer. This could be + useful for generating a C file and also its header file--all from the + same buffer. + + + If you don't use named rewrite streams, a "default" stream is used. + + + Terence Parr, parrt@cs.usfca.edu + University of San Francisco + February 2004 + + + + + + Track the incoming list of tokens + + + + + You may have multiple, named streams of rewrite operations. + I'm calling these things "programs." + Maps string (name) -> rewrite (List) + + + + + Map string (program name) -> Integer index + + + + + track index of tokens + + + + + Who do we suck tokens from? + + + + + Which (whitespace) token(s) to throw out + + + + + Rollback the instruction stream for a program so that + the indicated instruction (via instructionIndex) is no + longer in the stream. + + + UNTESTED! + + + + + + + Reset the program so that no instructions exist + + + + + + If op.index > lastRewriteTokenIndexes, just add to the end. + Otherwise, do linear + + + + + + Execute the rewrite operation by possibly adding to the buffer. + + rewrite buffer + The index of the next token to operate on. + + + + This token tracks it's own index 0..n-1 relative to the beginning + of the stream. It is designed to work with + in TokenStreamRewriteEngine.cs + + + + + Index into token array indicating position in input stream + + + + + @deprecated as of 2.7.2. This method calls System.exit() and writes + directly to stderr, which is usually not appropriate when + a parser is embedded into a larger application. Since the method is + static, it cannot be overridden to avoid these problems. + ANTLR no longer uses this method internally or in generated code. + + + + + + Implementation of the average aggregator. + + Aleksandar Seovic + + + + Defines an interface that should be implemented + by all collection processors and aggregators. + + + + + Processes a list of source items and returns a result. + + + The source list to process. + + + An optional processor arguments array. + + + The processing result. + + + + + Returns the average of the numeric values in the source collection. + + + The source collection to process. + + + Ignored. + + + The average of the numeric values in the source collection. + + + + + Converts all elements in the input list to a given target type. + + Erich Eichinger + + + + Processes a list of source items and returns a result. + + + The source list to process. + + + An optional processor arguments array. + + + The processing result. + + + + + Implementation of the count aggregator. + + Aleksandar Seovic + + + + Returns the number of items in the source collection. + + + The source collection to process. + + + Ignored. + + + The number of items in the source collection, + or zero if the collection is empty or null. + + + + + Converts a string literal to a instance. + + Erich Eichinger + + + + + Erich Eichinger + + + + Implementation of the distinct processor. + + Aleksandar Seovic + + + + Returns distinct items from the collection. + + + The source collection to process. + + + 0: boolean flag specifying whether to include null + in the results or not. Default is false, which means that + null values will not be included in the results. + + + A collection containing distinct source collection elements. + + + If there is more than one argument, or if the single optional argument + is not Boolean. + + + + + Implementation of the maximum aggregator. + + Aleksandar Seovic + + + + Returns the largest item in the source collection. + + + The source collection to process. + + + Ignored. + + + The largest item in the source collection. + + + + + Implementation of the minimum aggregator. + + Aleksandar Seovic + + + + Returns the smallest item in the source collection. + + + The source collection to process. + + + Ignored. + + + The smallest item in the source collection. + + + + + Implementation of the non-null processor. + + Aleksandar Seovic + + + + Returns non-null items from the collection. + + + The source collection to process. + + + Ignored. + + + A collection containing non-null source collection elements. + + + + + Implementation of the 'order by' processor. + + Aleksandar Seovic + Erich Eichinger + + + + Sorts the source collection using custom sort criteria. + + + Please note that your compare function needs to take care about + proper conversion of types to be comparable! + + + The source collection to sort. + + + Sort criteria to use. + + + A sorted array containing collection elements. + + + + + Reverts order of elements in the list + + Erich Eichinger + + + + Processes a list of source items and returns a result. + + + The source list to process. + + + An optional processor arguments array. + + + The processing result. + + + + + Implementation of the sort processor. + + Aleksandar Seovic + + + + Sorts the source collection. + + + Please not that this processor requires that collection elements + are of a uniform type and that they implement + interface. +

+ If you want to perform custom sorting based on element properties + you should consider using instead. + + + The source collection to sort. + + + Ignored. + + + An array containing sorted collection elements. + + + If collection is not empty and it is + neither nor . + + + +

+ Implementation of the sum aggregator. + + Aleksandar Seovic + + + + Returns the sum of the numeric values in the source collection. + + + The source collection to process. + + + Ignored. + + + The sum of the numeric values in the source collection. + + + + + Represents parsed method node in the navigation expression. + + Aleksandar Seovic + + + + Base type for nodes that accept arguments. + + Aleksandar Seovic + + + + Base type for all expression nodes. + + Aleksandar Seovic + + + + For internal purposes only. Use for expression node implementations. + + + This class is only required to enable serialization of parsed Spring expressions since antlr.CommonAST + unfortunately is not marked as [Serializable].
+
+ Note:Since SpringAST implements , deriving classes + have to explicitely override if they need to persist additional + data during serialization. + + + + + The global SpringAST node factory + + + + + Create an instance + + + + + Create an instance from a token + + + + + initialize this instance from an AST + + + + + initialize this instance from an IToken + + + + + initialize this instance from a token type number and a text + + + + + sets the text of this node + + + + + gets the text of this node + + + + + Create a new instance from SerializationInfo + + + + + populate SerializationInfo from this instance + + + + + gets or sets the token type of this node + + + + + gets or sets the text of this node + + + + + Interface that all navigation expression nodes have to implement. + + Aleksandar Seovic + + + + Returns expression value. + + Value of the expression. + + + + Returns expression value. + + Object to evaluate expression against. + Value of the expression. + + + + Returns expression value. + + Object to evaluate expression against. + Expression variables map. + Value of the expression. + + + + Sets expression value. + + Object to evaluate expression against. + New value for the last node of the expression. + + + + Sets expression value. + + Object to evaluate expression against. + Expression variables map. + New value for the last node of the expression. + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns node's value. + + Node's value. + + + + Returns node's value for the given context. + + Object to evaluate node against. + Node's value. + + + + Returns node's value for the given context. + + Object to evaluate node against. + Expression variables map. + Node's value. + + + + Returns node's value for the given context. + + Node's value. + + + + Evaluates this node for the given context, switching local variables map to the ones specified in . + + + + + Sets node's value for the given context. + + Object to evaluate node against. + New value for this node. + + + + Sets node's value for the given context. + + Object to evaluate node against. + Expression variables map. + New value for this node. + + + + Sets node's value for the given context. + + +

+ This is a default implementation of Set method, which + simply throws . +

+

+ This was done in order to avoid redundant Set method implementations, + because most of the node types do not support value setting. +

+ + + + + Returns a string representation of this node instance. + + + + + Evaluates this node, switching local variables map to the ones specified in . + + + + + Holds the state during evaluating an expression. + + + + + Gets/Sets the root context of the current evaluation + + + + + Gets/Sets the current context of the current evaluation + + + + + Gets/Sets global variables of the current evaluation + + + + + Gets/Sets local variables of the current evaluation + + + + + Initializes a new EvaluationContext instance. + + The root context for this evaluation + dictionary of global variables used during this evaluation + + + + Switches current ThisContext. + + + + + Switches current LocalVariables. + + + + + Gets the type of the + + + + + Create a new instance + + + + + Create a new instance + + + + + Append an argument node to the list of child nodes + + + + + + Create a new instance from SerializationInfo + + + + + Initializes the node. + + + + + Asserts the argument count. + + The required count. + + + + Resolves the arguments. + + Current expression evaluation context. + An array of argument values + + + + Resolves the named arguments. + + Current expression evaluation context. + A dictionary of argument name to value mappings. + + + + Resolves the argument. + + Argument position. + Current expression evaluation context. + Resolved argument value. + + + + Resolves the argument without ensuring was called. + + Argument position. + Current expression evaluation context. + Resolved argument value. + + + + Resolves the named argument. + + Argument name. + Current expression evaluation context. + Resolved named argument value. + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Creates new instance of the type defined by this node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents parsed assignment node in the navigation expression. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Assigns value of the right operand to the left one. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents parsed attribute node in the navigation expression. + + Aleksandar Seovic + + + + Represents parsed method node in the navigation expression. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Creates new instance of the type defined by this node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Determines the type of object that should be instantiated. + + + The type name to resolve. + + + The type of object that should be instantiated. + + + If the type cannot be resolved. + + + + + Initializes this node by caching necessary constructor and property info. + + + + + + + Sets the named arguments (properties). + + Instance to set property values on. + Argument (property) name to value mappings. + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Tries to determine attribute type based on the specified + attribute type name. + + + Attribute type name to resolve. + + + Resolved attribute type. + + + If type cannot be resolved. + + + + + Base class for binary operators. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance with the supplied operands + + + + + + + Create a new instance from SerializationInfo + + + + + Evaluate the left operand + + + + + Evaluate the left operand + + + + + Gets the left operand. + + The left operand. + + + + Gets the right operand. + + The right operand. + + + + Represents parsed boolean literal node. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the boolean literal node. + + + This is the entrypoint into evaluating this expression. + + Node's value. + + + + Represents parsed default node in the navigation expression. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns left operand if it is not null, or the right operand if it is. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Container object for the parsed expression. + + +

+ Preparing this object once and reusing it many times for expression + evaluation can result in significant performance improvements, as + expression parsing and reflection lookups are only performed once. +

+ + Aleksandar Seovic + + + + Initializes a new instance of the class + by parsing specified expression string. + + Expression to parse. + + + + Registers lambda expression under the specified . + + Function name to register expression as. + Lambda expression to register. + Variables dictionary that the function will be registered in. + + + + Initializes a new instance of the class + by parsing specified primary expression string. + + Primary expression to parse. + + + + Initializes a new instance of the class + by parsing specified property expression string. + + Property expression to parse. + + + + Initializes a new instance of the class. + + + + + Create a new instance from SerializationInfo + + + + + Evaluates this expression for the specified root object and returns + value of the last node. + + Context to evaluate expressions against. + Current expression evaluation context. + Value of the last node. + + + + Evaluates this expression for the specified root object and sets + value of the last node. + + Context to evaluate expressions against. + Current expression evaluation context. + Value to set last node to. + If navigation expression is empty. + + + + Evaluates this expression for the specified root object and returns + of the last node, if possible. + + Context to evaluate expression against. + Expression variables map. + Value of the last node. + + + + Contains a list of reserved variable names. + You must not use any variable names with the reserved prefix! + + + + + Variable Names using this prefix are reserved for internal framework use + + + + + variable name of the currently processed object factory, if any + + + + + Converts string representation of expression into an instance of . + + Aleksandar Seovic + + + + Can we convert from a the sourcetype to a ? + + +

+ Currently only supports conversion from a instance. +

+ + + A + that provides a format context. + + + A that represents the + you want to convert from. + + if the conversion is possible. + + + + Convert from a value to an + instance. + + + A + that provides a format context. + + + The to use + as the current culture. + + + The value that is to be converted. + + + A array if successful. + + + + + Utility class that enables easy expression evaluation. + + +

+ This class allows users to get or set properties, execute methods, and evaluate + logical and arithmetic expressions. +

+

+ Methods in this class parse expression on every invocation. + If you plan to reuse the same expression many times, you should prepare + the expression once using the static method, + and then call to evaluate it. +

+

+ This can result in significant performance improvements as it avoids expression + parsing and node resolution every time it is called. +

+

+

+ + Aleksandar Seovic + + + + Parses and evaluates specified expression. + + Root object. + Expression to evaluate. + Value of the last node in the expression. + + + + Parses and evaluates specified expression. + + Root object. + Expression to evaluate. + Expression variables map. + Value of the last node in the expression. + + + + Parses and specified expression and sets the value of the + last node to the value of the newValue parameter. + + Root object. + Expression to evaluate. + Value to set last node to. + + + + Parses and specified expression and sets the value of the + last node to the value of the newValue parameter. + + Root object. + Expression to evaluate. + Expression variables map. + Value to set last node to. + + + + Represents parsed expression list node in the navigation expression. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a result of the last expression in a list. + + Context to evaluate expressions against. + Current expression evaluation context. + Result of the last expression in a list + + + + Represents parsed function node. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Evaluates function represented by this node. + + Context to evaluate expressions against. + Current expression evaluation context. + Result of the function evaluation. + + + + Represents parsed hexadecimal integer literal node. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the hexadecimal integer literal node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents parsed indexer node in the navigation expression. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns node's value for the given context. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Sets node's value for the given context. + + Context to evaluate expressions against. + Current expression evaluation context. + New value for this node. + + + + Utility method that is needed by ObjectWrapper and AbstractAutowireCapableObjectFactory. + + Context to resolve property against. + Expression variables map. + PropertyInfo for this node. + + + + Represents parsed integer literal node. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the integer literal node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents lambda expression. + + Aleksandar Seovic + + + + caches argumentNames of this instance + + + + + caches body expression of this lambda function + + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Assigns value of the right operand to the left one. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Evaluates this node, switching local variables map to the ones specified in . + + + + + Gets argument names for this lambda expression. + + + + + Represents parsed list initializer node in the navigation expression. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Creates new instance of the list defined by this node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents local function node. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Evaluates function represented by this node. + + Context to evaluate expressions against. + Current expression evaluation context. + Result of the function evaluation. + + + + Represents parsed variable node. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns value of the local variable represented by this node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Sets value of the local variable represented by this node. + + Context to evaluate expressions against. + Current expression evaluation context. + New value for this node. + + + + Represents parsed map entry node. + + Aleksandar Seovic + + + + Creates a new instance of . + + + + + Create a new instance from SerializationInfo + + + + + Creates new instance of the map entry defined by this node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents parsed map initializer node in the navigation expression. + + Aleksandar Seovic + + + + Creates a new instance of . + + + + + Create a new instance from SerializationInfo + + + + + Creates new instance of the map defined by this node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents parsed method node in the navigation expression. + + Aleksandar Seovic + + + + Static constructor. Initializes a map of special collection processor methods. + + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns node's value for the given context. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Gets the best method given the name, argument values, for a given type. + + The type on which to search for the method. + Name of the method. + The binding flags. + The arg values. + Best matching method or null if none found. + + + + Represents parsed named argument node in the expression. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns the value of the named argument defined by this node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents parsed null literal node. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the null literal node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents arithmetic addition operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the arithmetic addition operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents AND operator (both, bitwise and logical). + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical AND operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents logical BETWEEN operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical IN operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + + true if the left operand is contained within the right operand, false otherwise. + + + + + Represents arithmetic division operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the arithmetic division operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents logical equality operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical equality operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents logical "greater than" operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical "greater than" operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents logical "greater than or equal" operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical "greater than or equal" operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents logical IN operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical IN operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + + true if the left operand is contained within the right operand, false otherwise. + + + + + Represents logical IS operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical IS operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + + true if the left operand is contained within the right operand, false otherwise. + + + + + Represents logical "less than" operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical "less than" operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents logical "less than or equal" operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical "less than or equal" operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents VB-style logical LIKE operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical LIKE operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + + true if the left operand matches the right operand, false otherwise. + + + + + Represents logical MATCHES operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical MATCHES operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + + true if the left operand matches the right operand, false otherwise. + + + + + Represents arithmetic modulus operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the arithmetic modulus operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents arithmetic multiplication operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the arithmetic multiplication operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents NOT operator (both, bitwise and logical). + + Aleksandar Seovic + + + + Base class for unary operators. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Gets the operand. + + The operand. + + + + Create a new instance + + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical NOT operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents logical inequality operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical inequality operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents OR operator (both, bitwise and logical). + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical OR operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents arithmetic exponent operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the arithmetic exponent operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents arithmetic subtraction operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the arithmetic subtraction operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents unary minus operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the unary plus operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents unary plus operator. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the unary plus operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + + Erich Eichinger + + + + Create a new instance + + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the logical AND operator node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents parsed projection node in the navigation expression. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a containing results of evaluation + of projection expression against each node in the context. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents node that navigates to object's property or public field. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Initializes the node. + + The parent. + + + + Attempts to resolve property or field. + + + Type to search for a property or a field. + + + Property or field name. + + + Binding flags to use. + + + Resolved property or field accessor, or null + if specified cannot be resolved. + + + + + Returns node's value for the given context. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Sets node's value for the given context. + + Context to evaluate expressions against. + Current expression evaluation context. + New value for this node. + + + + Retrieves property or field value. + + Context to evaluate expressions against. + Current expression evaluation context. + Property or field value. + + + + Sets property value, doing any type conversions that are necessary along the way. + + Context to evaluate expressions against. + Current expression evaluation context. + New value for this node. + + + + Sets property or field value using either dynamic or standard reflection. + + Object to evaluate node against. + New value for this node, converted to appropriate type. + + + + In the case of read only collections or custom collections that are not assignable from + IList, try to add to the collection. + + Context to evaluate expressions against. + Current expression evaluation context. + New value for this node. + true if was able add to IList, IDictionary, or ISet + + + + Utility method that is needed by ObjectWrapper and AbstractAutowireCapableObjectFactory. + We try as hard as we can, but there are instances when we won't be able to obtain PropertyInfo... + + Context to resolve property against. + PropertyInfo for this node. + + + + Gets a value indicating whether this node represents a property. + + + true if this node is a property; otherwise, false. + + + + + Gets a value indicating whether this node represents a field. + + + true if this node is a field; otherwise, false. + + + + + Represents parsed named argument node in the expression. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns the value of the named argument defined by this node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Overrides getText to allow easy way to get fully + qualified identifier. + + + Fully qualified identifier as a string. + + + + + Represents parsed real literal node. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the real literal node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents a reference to a Spring-managed object. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the integer literal node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents parsed selection node in the navigation expression. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns the first context item that matches selection expression. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents parsed selection node in the navigation expression. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns the last context item that matches selection expression. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents parsed selection node in the navigation expression. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a containing results of evaluation + of selection expression against each node in the context. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents parsed string literal node. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the string literal node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Exception thrown when detecting invalid SpEL syntax + + Erich Eichinger + + + + TODO + + + + + TODO + + + + + + + + + + + + + + + + + + + + Gets a message that provides details on the syntax error. + + + + + The expression that caused the error + + + + + Represents ternary expression node. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns a value for the string literal node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Represents parsed type node in the navigation expression. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns node's value for the given context. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Overrides getText to allow easy way to get fully + qualified typename. + + + Fully qualified typename as a string. + + + + + Represents parsed variable node. + + Aleksandar Seovic + + + + Create a new instance + + + + + Create a new instance from SerializationInfo + + + + + Returns value of the variable represented by this node. + + Context to evaluate expressions against. + Current expression evaluation context. + Node's value. + + + + Sets value of the variable represented by this node. + + Context to evaluate expressions against. + Current expression evaluation context. + New value for this node. + + + + Implementation of that can be used to + format and parse boolean values. + + Erich Eichinger + + + + Interface that should be implemented by all formatters. + + + + Formatters assume that source value is a string, and make no assumptions + about the target value's type, which means that Parse method can return + object of any type. + + + Aleksandar Seovic + + + + Formats the specified value. + + The value to format. + Formatted . + + + + Parses the specified value. + + The value to parse. + Parsed . + + + + Initializes a new instance of the class + using default values + + + + + Initializes a new instance of the class + + + + + Formats the specified boolean value. + + The value to format. + Formatted boolean value. + If is null. + If is not of type . + + + + Parses the specified boolean value according to settings of and + + The boolean value to parse. + Parsed boolean value as a . + If does not match or . + + + + Set/Get value to control casesensitivity of + + + Defaults to true + + + + + Set/Get value to recognize as boolean "true" value + + + Defaults to + + + + + Set/Get value to recognize as boolean "false" value + + + Defaults to + + + + + Implementation of that can be used to + format and parse currency values. + + + + CurrencyFormatter uses currency related properties of the + to format and parse currency values. + + + If you use one of the constructors that accept culture as a parameter + to create an instance of CurrencyFormatter, default NumberFormatInfo + for the specified culture will be used. + + + You can also use properties exposed by the CurrencyFormatter in order + to override some of the default currency formatting parameters. + + + Aleksandar Seovic + + + + Initializes a new instance of the class + using default for the current thread's culture. + + + + + Initializes a new instance of the class + using default for the specified culture. + + The culture name. + + + + Initializes a new instance of the class + using default for the specified culture. + + The culture. + + + + Initializes a new instance of the class + using specified . + + + The instance that defines how + currency values are formatted. + + + + + Formats the specified currency value. + + The value to format. + Formatted currency . + If is null. + If is not a number. + + + + Parses the specified currency value. + + The currency value to parse. + Parsed currency value as a . + + + + Gets or sets the currency decimal digits. + + The currency decimal digits. + + + + + Gets or sets the currency decimal separator. + + The currency decimal separator. + + + + + Gets or sets the currency group sizes. + + The currency group sizes. + + + + + Gets or sets the currency group separator. + + The currency group separator. + + + + + Gets or sets the currency symbol. + + The currency symbol. + + + + + Gets or sets the currency negative pattern. + + The currency negative pattern. + + + + + Gets or sets the currency positive pattern. + + The currency positive pattern. + + + + + Implementation of that can be used to + format and parse values. + + + + DateTimeFormatter uses properties of the + to format and parse values. + + + If you use one of the constructors that accept culture as a parameter + to create an instance of DateTimeFormatter, default DateTimeFormatInfo + for the specified culture will be used. + + + You can also use properties exposed by the DateTimeFormatter in order + to override some of the default formatting parameters. + + + Aleksandar Seovic + + + + Initializes a new instance of the class + using default for the current thread's culture. + + Date/time format string. + + + + Initializes a new instance of the class + using default for the specified culture. + + Date/time format string. + The culture name. + + + + Initializes a new instance of the class + using default for the specified culture. + + Date/time format string. + The culture. + + + + Formats the specified value. + + The value to format. + Formatted value. + If is null. + If is not an instance of . + + + + Parses the specified value. + + The string to parse. + Parsed value. + + + + Provides base functionality for filtering values before they actually get parsed/formatted. + + Erich Eichinger + + + + Creates a new instance of this FilteringFormatter. + + an optional underlying formatter + + If no underlying formatter is specified, the values + get passed through "as-is" after being filtered + + + + + Parses the specified value. + + The value to parse. + Parsed . + + + + Formats the specified value. + + The value to format. + Formatted . + + + + Allows to rewrite a value before it gets parsed by the underlying formatter + + + + + Allows to change a value before it gets formatted by the underlying formatter + + + + + Implementation of that can be used to + format and parse floating point numbers. + + + + This formatter allows you to format and parse numbers that conform + to number style (leading and trailing + white space, leading sign, decimal point, exponent). + + + Aleksandar Seovic + + + + Default format string. + + + + + Initializes a new instance of the class, + using default format string of '{0:F}' and current thread's culture. + + + + + Initializes a new instance of the class, + using specified format string and current thread's culture. + + The format string. + + + + Initializes a new instance of the class, + using default format string of '{0:F}' and specified culture. + + The culture. + + + + Initializes a new instance of the class, + using specified format string and current thread's culture. + + The format string. + The culture name. + + + + Initializes a new instance of the class, + using specified format string and culture. + + The format string. + The culture. + + + + Formats the specified float value. + + The value to format. + Formatted floating point number. + If is null. + If is not a number. + + + + Parses the specified float value. + + The float value to parse. + Parsed float value as a . + + + + Replaces input strings with a given default value, + if they are null or contain whitespaces only, + + Erich Eichinger + + + + Creates a new instance of this HasTextFilteringFormatter using null as default value. + + an optional underlying formatter + + If no underlying formatter is specified, the values + get passed through "as-is" after being filtered + + + + + Creates a new instance of this HasTextFilteringFormatter. + + the default value to be returned, if input text doesn't contain text + an optional underlying formatter + + If no underlying formatter is specified, the values + get passed through "as-is" after being filtered + + + + + If value contains no text, it will be replaced by a defaultValue. + + + + + Implementation of that can be used to + format and parse integer numbers. + + + + This formatter allows you to format and parse numbers that conform + to number style (leading and trailing + white space, leading sign). + + + Aleksandar Seovic + + + + Initializes a new instance of the class, + using default format string of '{0:D}'. + + + + + Initializes a new instance of the class, + using specified format string. + + + + + Formats the specified integer value. + + The value to format. + Formatted integer number. + If is null. + If is not an integer number. + + + + Parses the specified integer value. + + The integer value to parse. + Parsed number value as a . + + + + Implementation of that simply calls . + + + This formatter is a no-operation implementation. + + Erich Eichinger + + + + Initializes a new instance of the class. + + + + + Converts the passed value to a string by calling . + + The value to convert. + to string converted value. + + + + Returns the passed string "as is". + + The value to return. + The value passed into this method. + + + + Implementation of that can be used to + format and parse numbers. + + + + NumberFormatter uses number-related properties of the + to format and parse numbers. + + + This formatter works with both integer and decimal numbers and allows + you to format and parse numbers that conform to + number style (leading and trailing white space and/or sign, thousands separator, + decimal point) + + + If you use one of the constructors that accept culture as a parameter + to create an instance of NumberFormatter, default NumberFormatInfo + for the specified culture will be used. + + + You can also use properties exposed by the NumberFormatter in order + to override some of the default number formatting parameters. + + + Aleksandar Seovic + + + + Initializes a new instance of the class + using default for the current thread's culture. + + + + + Initializes a new instance of the class + using default for the specified culture. + + The culture name. + + + + Initializes a new instance of the class + using default for the specified culture. + + The culture. + + + + Initializes a new instance of the class + using specified . + + + The instance that defines how + numbers are formatted and parsed. + + + + + Formats the specified number value. + + The value to format. + Formatted number . + If is null. + If is not a number. + + + + Parses the specified number value. + + The number value to parse. + Parsed number value as a . + + + + Gets or sets the number of decimal digits. + + The number of decimal digits. + + + + + Gets or sets the decimal separator. + + The decimal separator. + + + + + Gets or sets the number group sizes. + + The number group sizes. + + + + + Gets or sets the number group separator. + + The number group separator. + + + + + Gets or sets the negative pattern. + + The number negative pattern. + + + + + Implementation of that can be used to + format and parse numbers. + + + + PercentFormatter uses percent-related properties of the + to format and parse percentages. + + + If you use one of the constructors that accept culture as a parameter + to create an instance of PercentFormatter, default NumberFormatInfo + for the specified culture will be used. + + + You can also use properties exposed by the PercentFormatter in order + to override some of the default number formatting parameters. + + + Aleksandar Seovic + + + + Initializes a new instance of the class + using default for the current thread's culture. + + + + + Initializes a new instance of the class + using default for the specified culture. + + The culture name. + + + + Initializes a new instance of the class + using default for the specified culture. + + The culture. + + + + Initializes a new instance of the class + using specified . + + + The instance that defines how + numbers are formatted and parsed. + + + + + Formats the specified percentage value. + + The value to format. + Formatted percentage. + If is null. + If is not a number. + + + + Parses the specified percentage value. + + The percentage value to parse. + Parsed percentage value as a . + + + + Gets or sets the number of decimal digits. + + The number of decimal digits. + + + + + Gets or sets the decimal separator. + + The decimal separator. + + + + + Gets or sets the percent group sizes. + + The percent group sizes. + + + + + Gets or sets the percent group separator. + + The percent group separator. + + + + + Gets or sets the negative pattern. + + The percent negative pattern. + + + + + Gets or sets the positive pattern. + + The percent positive pattern. + + + + + Gets or sets the percent symbol. + + The percent symbol. + + + + + Gets or sets the per mille symbol. + + The per mille symbol. + + + + + Loads a list of resources that should be applied from the .NET . + + +

+ This implementation will iterate over all resource managers + within the message source and return a list of all the resources whose name starts with '$this'. +

+

+ All other resources will be ignored, but you can retrieve them by calling one of + GetMessage methods on the message source directly. +

+ + Aleksandar Seovic + + + + Abstract base class that all localizers should extend + + +

+ This class contains the bulk of the localizer logic, including implementation + of the ApplyResources methods that are defined in + interface. +

+

+ All specific localizers need to do is inherit this class and implement + GetResources method that will return a list of + objects that should be applied to a specified target. +

+

+ Custom implementations can use whatever type of resource storage they want, + such as standard .NET resource sets, custom XML files, database, etc. +

+ + Aleksandar Seovic + + + + Defines an interface that localizers have to implement. + + +

+ Localizers are used to automatically apply resources to object's members + using reflection. +

+ + Aleksandar Seovic + + + + Applies resources of the specified culture to the specified target object. + + Target object to apply resources to. + instance to retrieve resources from. + Resource culture to use for resource lookup. + + + + Applies resources to the specified target object, using current thread's culture to resolve resources. + + Target object to apply resources to. + instance to retrieve resources from. + + + + Gets or sets the resource cache instance. + + The resource cache instance. + + + + Applies resources of the specified culture to the specified target object. + + Target object to apply resources to. + instance to retrieve resources from. + Resource culture to use for resource lookup. + + + + Applies resources to the specified target object, using current thread's uiCulture to resolve resources. + + Target object to apply resources to. + instance to retrieve resources from. + + + + Returns a list of instances that should be applied to the target. + + Target to get a list of resources for. + instance to retrieve resources from. + Resource locale. + A list of resources to apply. + + + + Loads resources from the storage and creates a list of instances that should be applied to the target. + + Target to get a list of resources for. + instance to retrieve resources from. + Resource locale. + A list of resources to apply. + + + + Gets or sets the resource cache instance. + + The resource cache instance. + + + + Loads resources from the storage and creates a list of instances that should be applied to the target. + + + This feature is not currently supported on version 1.0 of the .NET platform. + + Target to get a list of resources for. + instance to retrieve resources from. + Resource locale. + A list of resources to apply. + + + + implementation + that simply returns the + value of the + + property (if said property value is not ), or the + of the current thread if it is + . + + Aleksandar Seovic + + + + Strategy interface for + resolution. + + Aleksandar Seovic + + + + Resolves the + from some context. + + +

+ The 'context' is determined by the appropriate implementation class. + An example of such a context might be a thread local bound + , or a + sourced from an HTTP + session. +

+ + + The that should be used + by the caller. + + + + + Sets the . + + +

+ This is an optional operation and does not need to be implemented + such that it actually does anything useful (i.e. it can be a no-op). +

+ + + The new or + to clear the current . + + + + + Returns the default . + + +

+ It tries to get the + from the value of the + + property and falls back to the of the + current thread if the + + is . +

+ + + The default + + + + + Resolves the + from some context. + + +

+ The 'context' in this implementation is the + value of the + + property (if said property value is not ), or the + of the current thread if it is + . +

+ + + The that should be used + by the caller. + + + + + Sets the . + + + The new or + to clear the current . + + + + + + + The default . + + + The default . + + + + + Abstract base class that all resource cache implementations should extend. + + Aleksandar Seovic + + + + Defines an interface that resource cache adapters have to implement. + + Aleksandar Seovic + + + + Gets the list of resources from cache. + + Target to get a list of resources for. + Resource culture. + A list of cached resources for the specified target object and culture. + + + + Puts the list of resources in the cache. + + Target to cache a list of resources for. + Resource culture. + A list of resources to cache. + A list of cached resources for the specified target object and culture. + + + + Gets the list of resources from the cache. + + Target to get a list of resources for. + Resource culture. + A list of cached resources for the specified target object and culture. + + + + Puts the list of resources in the cache. + + Target to cache a list of resources for. + Resource culture. + A list of resources to cache. + A list of cached resources for the specified target object and culture. + + + + Crates resource cache key for the specified target object and culture. + + Target object to apply resources to. + Resource culture to use for resource lookup. + + + + Gets the list of resources from cache. + + Cache key to use for lookup. + A list of cached resources for the specified target object and culture. + + + + Puts the list of resources in the cache. + + Cache key to use for the specified resources. + A list of resources to cache. + A list of cached resources for the specified target object and culture. + + + + Resource cache implementation that doesn't cache resources. + + Aleksandar Seovic + + + + Gets the list of resources from cache. + + Cache key to use for lookup. + Always returns null. + + + + Puts the list of resources in the cache. + + Cache key to use for the specified resources. + A list of resources to cache. + + + + Holds mapping between control property and it's value + as read from the resource file. + + Aleksandar Seovic + + + + Creates instance of resource mapper. + + Target property. + Resource value. + + + + Gets parsed target property expression. See + for more information on object navigation expressions. + + + + + Value of the resource that target property should be set to. + + + + + Utility class to aid in the manipulation of events and delegates. + + Griffin Caprio + + + + Returns a new instance of the requested . + + +

+ Often used to wire subscribers to event publishers. +

+ + + The of delegate to create. + + + The target subscriber object that contains the delegate implementation. + + + referencing the delegate method on the subscriber. + + + A delegate handler that can be added to an events list of handlers, or called directly. + + + + + Queries the input type for a signature matching the input + signature. + + + Typically used to query a potential subscriber to see if they implement an event handler. + + to match against + to query + + matching input + signature, or if there is no match. + + + + + Creates a new instance of the EventManipulationUtilities class. + + +

+ This is a utility class, and as such has no publicly visible constructors. +

+ + + + + Default implementation of the + interface. + + Griffin Caprio + + + + Creates a new instance of the EventRegistry class. + + + + + Adds the input object to the list of publishers. + + + This publishes all events of the source object to any object + wishing to subscribe + + The source object to publish. + + + + Subscribes to all events published, if the subscriber implements + compatible handler methods. + + The subscriber to use. + + + + Subscribes to published events of all objects of a given type, if the + subscriber implements compatible handler methods. + + The subscriber to use. + + The target to subscribe to. + + + + + Unsubscribes to all events published, if the subscriber + implmenets compatible handler methods. + + The subscriber to use + + + + Unsubscribes to the published events of all objects of a given + , if the subscriber implements + compatible handler methods. + + The subscriber to use. + The target to unsubscribe from + + + + The list of event publishers. + + The list of event publishers. + + + + To be implemented by any object that wishes to receive a reference to + an . + + +

+ This interface only applies to objects that have been instantiated + within the context of an + . This interface does + not typically need to be implemented by application code, but is rather + used by classes internal to Spring.NET. +

+ + Mark Pollack + Rick Evans + + + + Set the + associated with the + that created this + object. + + +

+ This property will be set by the relevant + after all of this + object's dependencies have been resolved. This object can use the + supplied + immediately to publish or subscribe to one or more events. +

+ + + + + Marks a property as being 'required': that is, the setter property + must be configured to be dependency-injected with a value. + + Consult the SDK documentation for , + which, by default, checks for the presence of this annotation. + + Rob Harrop + Mark Pollack + + + + A implementation that enforces required properties to have been configured. + Required properties are detected through an attribute, by default, Spring's + attribute. + + + The motivation for the existence of this IObjectPostProcessor is to allow + developers to annotate the setter properties of their own classes with an + arbitrary attribute to indicate that the container must check + for the configuration of a dependency injected value. This neatly pushes + responsibility for such checking onto the container (where it arguably belongs), + and obviates the need (in part) for a developer to code a method that + simply checks that all required properties have actually been set. + + Please note that an 'init' method may still need to implemented (and may + still be desirable), because all that this class does is enforce that a + 'required' property has actually been configured with a value. It does + not check anything else... In particular, it does not check that a + configured value is not null. + + + Rob Harrop + Juergen Hoeller + Mark Pollack (.NET) + + + + Adapter that implements all methods on + as no-ops, which will not change normal processing of each object instantiated + by the container. Subclasses may override merely those methods that they are + actually interested in. + + + Note that this base class is only recommendable if you actually require + functionality. If all you need + is plain functionality, prefer a straight + implementation of that (simpler) interface. + + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + + + + Extension of the interface, + adding a callback for predicting the eventual type of a processed object. + + This interface is a special purpose interface, mainly for + internal use within the framework. In general, application-provided + post-processors should simply implement the plain + interface or derive from the + class. New methods might be added to this interface even in point releases. + + + Juergen Hoeller + Mark Pollack (.NET) + + + + Subinterface of + + that adds a before-instantiation callback and a callback after instantiation but before + explicit properties are set or autowiring occurs. + + + + Typically used to suppress default instantiation for specific target objects, + for example to create proxies with special Spring.Aop.ITargetSources (pooling targets, + lazily initializing targets, etc), or to implement additional injection strategies such as field + injection. + + + This interface is a special purpose interface, mainly for internal use within the framework. + It is recommended to implement the plain interface as far as + possible, or to derive from in order to be shielded + from extension to this interface. + + + Juergen Hoeller + Rick Evans (.NET) + + + + Apply this + + before the target object gets instantiated. + + +

+ The returned object may be a proxy to use instead of the target + object, effectively suppressing the default instantiation of the + target object. +

+

+ If the object is returned by this method is not + , the object creation process will be + short-circuited. The returned object will not be processed any + further; in particular, no further + + callbacks will be applied to it. This mechanism is mainly intended + for exposing a proxy instead of an actual target object. +

+

+ This callback will only be applied to object definitions with an + object class. In particular, it will not be applied to + objects with a "factory-method" (i.e. objects that are to be + instantiated via a layer of indirection anyway). +

+ + + The of the target object that is to be + instantiated. + + + The name of the target object. + + + The object to expose instead of a default instance of the target + object. + + + In the case of any errors. + + + + + + + Perform operations after the object has been instantiated, via a constructor or factory method, + but before Spring property population (from explicit properties or autowiring) occurs. + + The object instance created, but whose properties have not yet been set + Name of the object. + true if properties should be set on the object; false if property population + should be skipped. Normal implementations should return true. Returning false will also + prevent any subsequent InstantiationAwareObjectPostProcessor instances from being + invoked on this object instance. + + + + Post-process the given property values before the factory applies them + to the given object. + + Allows for checking whether all dependencies have been + satisfied, for example based on a "Required" annotation on bean property setters. + Also allows for replacing the property values to apply, typically through + creating a new MutablePropertyValues instance based on the original PropertyValues, + adding or removing specific values. + + + The property values that the factory is about to apply (never null). + he relevant property infos for the target object (with ignored + dependency types - which the factory handles specifically - already filtered out) + The object instance created, but whose properties have not yet + been set. + Name of the object. + The actual property values to apply to the given object (can be the + passed-in PropertyValues instances0 or null to skip property population. + + + + Predicts the type of the object to be eventually returned from this + processors callback. + + The raw Type of the object. + Name of the object. + The type of the object, or null if not predictable. + in case of errors + + + + Determines the candidate constructors to use for the given object. + + The raw Type of the object. + Name of the object. + The candidate constructors, or null if none specified + in case of errors + + + + Predicts the type of the object to be eventually returned from this + processors PostProcessBeforeInstantiation callback. + + The raw Type of the object. + Name of the object. + The type of the object, or null if not predictable. + in case of errors + + + + Determines the candidate constructors to use for the given object. + + The raw Type of the object. + Name of the object. + The candidate constructors, or null if none specified + in case of errors + + + + Apply this + + before the target object gets instantiated. + + +

+ The returned object may be a proxy to use instead of the target + object, effectively suppressing the default instantiation of the + target object. +

+

+ If the object is returned by this method is not + , the object creation process will be + short-circuited. The returned object will not be processed any + further; in particular, no further + + callbacks will be applied to it. This mechanism is mainly intended + for exposing a proxy instead of an actual target object. +

+

+ This callback will only be applied to object definitions with an + object class. In particular, it will not be applied to + objects with a "factory-method" (i.e. objects that are to be + instantiated via a layer of indirection anyway). +

+ + + The of the target object that is to be + instantiated. + + + The name of the target object. + + + The object to expose instead of a default instance of the target + object. + + + In the case of any errors. + + + + + + + Perform operations after the object has been instantiated, via a constructor or factory method, + but before Spring property population (from explicit properties or autowiring) occurs. + + The object instance created, but whose properties have not yet been set + Name of the object. + true if properties should be set on the object; false if property population + should be skipped. Normal implementations should return true. Returning false will also + prevent any subsequent InstantiationAwareObjectPostProcessor instances from being + invoked on this object instance. + + + + Post-process the given property values before the factory applies them + to the given object. + + Allows for checking whether all dependencies have been + satisfied, for example based on a "Required" annotation on bean property setters. + Also allows for replacing the property values to apply, typically through + creating a new MutablePropertyValues instance based on the original PropertyValues, + adding or removing specific values. + + + The property values that the factory is about to apply (never null). + he relevant property infos for the target object (with ignored + dependency types - which the factory handles specifically - already filtered out) + The object instance created, but whose properties have not yet + been set. + Name of the object. + The actual property values to apply to the given object (can be the + passed-in PropertyValues instances0 or null to skip property population. + + + + Apply this + to the given new object instance before any object initialization callbacks. + + +

+ The object will already be populated with property values. + The returned object instance may be a wrapper around the original. +

+ + + The new object instance. + + + The name of the object. + + + The object instance to use, either the original or a wrapped one. + + + In case of errors. + + + + + Apply this to the + given new object instance after any object initialization callbacks. + + +

+ The object will already be populated with property values. The returned object + instance may be a wrapper around the original. +

+ + + The new object instance. + + + The name of the object. + + + The object instance to use, either the original or a wrapped one. + + + In case of errors. + + + + + Cache for validated object names, skipping re-validation for the same object + + + + + Post-process the given property values before the factory applies them + to the given object. Checks for the attribute specified by this PostProcessor's RequiredAttributeType. + + The property values that the factory is about to apply (never null). + The relevant property infos for the target object (with ignored + dependency types - which the factory handles specifically - already filtered out) + The object instance created, but whose properties have not yet + been set. + Name of the object. + + The actual property values to apply to the given object (can be the + passed-in PropertyValues instances or null to skip property population. + + If a required property value has not been specified + in the configuration metadata. + + + + Determines whether the supplied property is required to have a value, that is to be dependency injected. + + + This implementation looks for the existence of a "required" attribute on the supplied PropertyInfo and that + the property has a setter method. + + The target PropertyInfo + + true if the supplied property has been marked as being required;; otherwise, false if + not or if the supplied property does not have a setter method + + + + + Builds an exception message for the given list of invalid properties. + + The list of names of invalid properties. + Name of the object. + The exception message + + + + Sets the type of the required attribute, to be used on a property setter + + + The default required attribute type is the Spring-provided attribute. + This setter property exists so that developers can provide their own + (non-Spring-specific) annotation type to indicate that a property value is required. + + The type of the required attribute. + + + + Base class that provides common functionality needed for several IObjectFactoryPostProcessor + implementations + + Mark Pollack + + + + Allows for custom modification of an application context's object + definitions, adapting the object property values of the context's + underlying object factory. + + +

+ Application contexts can auto-detect + IObjectFactoryPostProcessor objects in their object definitions and + apply them before any other objects get created. +

+

+ Useful for custom config files targeted at system administrators that + override object properties configured in the application context. +

+

+ See PropertyResourceConfigurer and its concrete implementations for + out-of-the-box solutions that address such configuration needs. +

+ + Juergen Hoeller + Rick Evans (.Net) + + + + Modify the application context's internal object factory after its + standard initialization. + + +

+ All object definitions will have been loaded, but no objects will have + been instantiated yet. This allows for overriding or adding properties + even to eager-initializing objects. +

+ + + The object factory used by the application context. + + + In case of errors. + + + + + Modify the application context's internal object factory after its + standard initialization. + + The object factory used by the application context. + +

+ All object definitions will have been loaded, but no objects will have + been instantiated yet. This allows for overriding or adding properties + even to eager-initializing objects. +

+ + + In case of errors. + + + + + Resolves the supplied into a + instance. + + The object that is to be resolved into a + instance. + The error context source. + The error context string. + A resolved . + +

+ This (default) implementation supports resolving + s and s. + Only override this method if you want to key your type alias + on something other than s + and s. +

+ + + If the supplied is , + or the supplied cannot be resolved. + + + + + Return the order value of this object, with a higher value meaning + greater in terms of sorting. + + The order value. + + + + + Simple template superclass for + implementations that allows for the creation of a singleton or a prototype + instance (depending on a flag). + + + If the value of the + + property is (this is the default), this class + will create a single instance of it's object upon initialization and + subsequently return the singleton instance; else, this class will + create a new instance each time (prototype mode). Subclasses must + implement the + + template method to actually create objects. + + Juergen Hoeller + Keith Donald + Simon White (.NET) + + + + Interface to be implemented by objects used within an + that are themselves + factories. + + +

+ If an object implements this interface, it is used as a factory, + not directly as an object. s + can support singletons and prototypes + ()... + please note that an + itself can only ever be a singleton. It is a logic error to configure an + itself to be a prototype. +

+ + An object that implements this interface cannot be used as a normal object. + + + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + Return an instance (possibly shared or independent) of the object + managed by this factory. + + + + If this method is being called in the context of an enclosing IoC container and + returns , the IoC container will consider this factory + object as not being fully initialized and throw a corresponding (and most + probably fatal) exception. + + + + An instance (possibly shared or independent) of the object managed by + this factory. + + + + + Return the of object that this + creates, or + if not known in advance. + + + + + Is the object managed by this factory a singleton or a prototype? + + + + + Invoked by an + after it has injected all of an object's dependencies. + + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + + Return an instance (possibly shared or independent) of the object + managed by this factory. + + + An instance (possibly shared or independent) of the object managed by + this factory. + + + + + + Template method that subclasses must override to construct + the object returned by this factory. + + + Invoked once immediately after the initialization of this + in the case of + a singleton; else, on each call to the + + method. + + + If an exception occured during object creation. + + + A distinct instance of the object created by this factory. + + + + + Performs cleanup on any cached singleton object. + + +

+ Only makes sense in the context of a singleton object. +

+ + + + + + + Is the object managed by this factory a singleton or a prototype? + + +

+ Please note that changing the value of this property after + this factory object instance has been created by an enclosing + Spring.NET IoC container really is a programming error. This + property should really only be set once, prior to the invocation + of the + + callback method. +

+ + + + + + Return the of object that this + creates, or + if not known in advance. + + + + + + The various autowiring modes. + + Rick Evans + + + + Do not autowire. + + + + + Autowire by name. + + + + + Autowire by . + + + + + Autowiring by constructor. + + + + + The autowiring strategy is to be determined by introspection + of the object's . + + + + + Implementation of that + resolves variable name against command line arguments. + + Aleksandar Seovic + + + + Defines contract that different variable sources have to implement. + + +

+ The "variable sources" are objects containing name-value pairs + that allow a variable value to be retrieved for the given name.

+

+ Out of the box, Spring.NET supports a number of variable sources, + that allow users to obtain variable values from .NET config files, + Java-style property files, environment, registry, etc.

+

+ Users can always write their own variable sources implementations, + that will allow them to load variable values from the database or + other proprietary data source.

+ + + + + + + + Aleksandar Seovic + + + + Before requesting a variable resolution, a client should + ask, whether the source can resolve a particular variable name. + + the name of the variable to resolve + true if the variable can be resolved, false otherwise + + + + Resolves variable value for the specified variable name. + + + The name of the variable to resolve. + + + The variable value if able to resolve, null otherwise. + + + + + Default constructor. + Initializes command line arguments from the environment. + + + + + Constructor that allows arguments to be passed externally. + Useful for testing. + + + + + Before requesting a variable resolution, a client should + ask, whether the source can resolve a particular variable name. + + the name of the variable to resolve + true if the variable can be resolved, false otherwise + + + + Resolves variable value for the specified variable name. + + + The name of the variable to resolve. + + + The variable value if able to resolve, null otherwise. + + + + + Initializes command line arguments dictionary. + + + + + Gets or sets a prefix that should be used to + identify arguments to extract values from. + + + A prefix that should be used to identify arguments + to extract values from. Defaults to slash ("/"). + + + + + Gets or sets a character that should be used to + separate argument name from its value. + + + A character that should be used to separate argument + name from its value. Defaults to colon (":"). + + + + + Implementation of that + resolves variable name against name-value sections in + the standard .NET configuration file. + + Aleksandar Seovic + + + + Initializes a new instance of + + + + + Initializes a new instance of from the given + + + + + Initializes a new instance of from the given + + + + + Before requesting a variable resolution, a client should + ask, whether the source can resolve a particular variable name. + + the name of the variable to resolve + true if the variable can be resolved, false otherwise + + + + Resolves variable value for the specified variable name. + + + The name of the variable to resolve. + + + The variable value if able to resolve, null otherwise. + + + + + Initializes properties based on the specified + property file locations. + + + + + Gets or sets a list of section names variables should be loaded from. + + + All sections specified need to be handled by the + in order to be processed successfully. + + + A list of section names variables should be loaded from. + + + + + Convinience property. Gets or sets a single section + to read properties from. + + + The section specified needs to be handled by the + in order to be processed successfully. + + + A section to read properties from. + + + + + Implementation of that + resolves variable name against provided variables. + + + Variable name resolution is case insensitive. + + Bruno Baia + + + + Initializes a new instance of . + + + + + Before requesting a variable resolution, a client should + ask, whether the source can resolve a particular variable name. + + the name of the variable to resolve + true if the variable can be resolved, false otherwise + + + + Resolves variable value for the specified variable name. + + + The name of the variable to resolve. + + + The variable value if able to resolve, null otherwise. + + + + + Gets or sets variables. + + + + + Various utility methods for .NET style .config files. + + +

+ Currently supports reading custom configuration sections and returning them as + objects. +

+ + Simon White + Mark Pollack + + + + Initializes the type members + + + + + Reads the specified configuration section into a + . + + The resource to read. + The section name. + + A newly populated + . + + + If any errors are encountered while attempting to open a stream + from the supplied . + + + If any errors are encountered while loading or reading (this only applies to + v1.1 and greater of the .NET Framework) the actual XML. + + + If any errors are encountered while loading or reading (this only applies to + v1.0 of the .NET Framework). + + + If the configuration section was otherwise invalid. + + + + + Reads the specified configuration section into the supplied + . + + The resource to read. + The section name. + + The collection that is to be populated. May be + . + + + A newly populated + . + + + If any errors are encountered while attempting to open a stream + from the supplied . + + + If any errors are encountered while loading or reading (this only applies to + v1.1 and greater of the .NET Framework) the actual XML. + + + If any errors are encountered while loading or reading (this only applies to + v1.0 of the .NET Framework). + + + If the configuration section was otherwise invalid. + + + + + Reads the specified configuration section into the supplied + . + + The resource to read. + The section name. + + The collection that is to be populated. May be + . + + + If a key already exists, is its value to be appended to the current + value or replaced? + + + The populated + . + + + If any errors are encountered while attempting to open a stream + from the supplied . + + + If any errors are encountered while loading or reading (this only applies to + v1.1 and greater of the .NET Framework) the actual XML. + + + If any errors are encountered while loading or reading (this only applies to + v1.0 of the .NET Framework). + + + If the configuration section was otherwise invalid. + + + + + Read from the specified configuration from the supplied XML + into a + . + + + + Does not support section grouping. The supplied XML + must already be loaded. + + + + The to read from. + + + The configuration section name to read. + + + A newly populated + . + + + If any errors are encountered while reading (this only applies to + v1.1 and greater of the .NET Framework). + + + If any errors are encountered while reading (this only applies to + v1.0 of the .NET Framework). + + + If the configuration section was otherwise invalid. + + + + + Returns the section from the specified resource with the given section name + + + + + Returns the section from the specified resource with the given section name. Use + in case no section handler is specified. + + + + + Returns the typed section from the specified resource with the given section name + + + + + Returns the section from the specified resource with the given section name. Use + in case no section handler is specified. + + + + + Returns the typed result of evaluating the specified . + + if the result's type does not match the expected type + + + + Reads the specified configuration section from the given + + + + + + + + Reads the specified configuration section from the given + + + + + + + + + Determine the configuration section handler type + + + + + Populates the supplied with values from + a .NET application configuration file. + + + The + to add any key-value pairs to. + + + The configuration section name in the a .NET application configuration + file. + + + If a key already exists, is its value to be appended to the current + value or replaced? + + + if the supplied + was found. + + + + + Creates a new instance of the ConfigurationReader class. + + +

+ This is a utility class, and as such has no publicly visible + constructors. +

+ + + + + Implementation of that + resolves variable name connection strings defined in + the standard .NET configuration file. + + +

+ When the <connectionStrings> configuration section is processed by this class, + two variables are defined for each connection string: one for connection string and + the second one for the provider name.

+

+ Variable names are generated by appending '.connectionString' and '.providerName' + literals to the value of the name attribute of the connection string element. + For example:

+ 
+            
+               
+            
+
+

+ will result in two variables being created: myConn.connectionString and myConn.providerName. + You can reference these variables within your object definitions, just like any other variable.

+ + Aleksandar Seovic + + + + Before requesting a variable resolution, a client should + ask, whether the source can resolve a particular variable name. + + the name of the variable to resolve + true if the variable can be resolved, false otherwise + + + + Resolves variable value for the specified variable name. + + + The name of the variable to resolve. + + + The variable value if able to resolve, null otherwise. + + + + + Initializes properties based on the specified + property file locations. + + + + + Holder for constructor argument values for an object. + + +

+ Supports values for a specific index or parameter name (case + insensitive) in the constructor argument list, and generic matches by + . +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + + Can be used as an argument filler for the + + overload when one is not looking for an argument by index. + + + + + Creates a new instance of the + + class. + + + + + Creates a new instance of the + + class. + + + The + to be used to populate this instance. + + + + + Copy all given argument values into this object. + + + The + to be used to populate this instance. + + + + + Add argument value for the given index in the constructor argument list. + + + The index in the constructor argument list. + + + The argument value. + + + + + Add argument value for the given index in the constructor argument list. + + The index in the constructor argument list. + The argument value. + + The of the argument + . + + + + + Add argument value for the given name in the constructor argument list. + + The name in the constructor argument list. + The argument value. + + If the supplied is + or is composed wholly of whitespace. + + + + + Get argument value for the given index in the constructor argument list. + + The index in the constructor argument list. + + The required of the argument. + + + The + + for the argument, or if none set. + + + + + Get argument value for the given name in the constructor argument list. + + The name in the constructor argument list. + + The + + for the argument, or if none set. + + + + + Does this set of constructor arguments contain a named argument matching the + supplied name? + + + + The comparison is performed in a case-insensitive fashion. + + + The named argument to look up. + + if this set of constructor arguments + contains a named argument matching the supplied + name. + + + + + Add generic argument value to be matched by type. + + + The argument value. + + + + + Add generic argument value to be matched by type. + + The argument value. + + The of the argument + . + + + + + Look for a generic argument value that matches the given + . + + + The to match. + + + The + + for the argument, or if none set. + + + + + Look for a generic argument value that matches the given + . + + + The to match. + + + A of + + objects that have already been used in the current resolution + process and should therefore not be returned again; this allows one + to return the next generic argument match in the case of multiple + generic argument values of the same type. + + + The + + for the argument, or if none set. + + + + + Look for an argument value that either corresponds to the given index + in the constructor argument list or generically matches by + . + + + The index in the constructor argument list. + + + The to match. + + + The + + for the argument, or if none is set. + + + + + Look for an argument value that either corresponds to the given index + in the constructor argument list or generically matches by + . + + + The index in the constructor argument list. + + + The to match. + + + A of + + objects that have already been used in the current resolution + process and should therefore not be returned again; this allows one + to return the next generic argument match in the case of multiple + generic argument values of the same type. + + + The + + for the argument, or if none is set. + + + + + Look for an argument value that either corresponds to the given index + in the constructor argument list or generically matches by + . + + + The name of the argument in the constructor argument list. May be + , in which case generic matching by + is assumed. + + + The to match. + + + The + + for the argument, or if none is set. + + + + + Look for an argument value that either corresponds to the given index + in the constructor argument list or generically matches by + . + + + The name of the argument in the constructor argument list. May be + , in which case generic matching by + is assumed. + + + The to match. + + + A of + + objects that have already been used in the current resolution + process and should therefore not be returned again; this allows one + to return the next generic argument match in the case of multiple + generic argument values of the same type. + + + The + + for the argument, or if none is set. + + + + + Look for an argument value that either corresponds to the given index + in the constructor argument list, or to the named argument, or + generically matches by . + + + The index of the argument in the constructor argument list. May be + negative, to denote the fact that we are not looking for an + argument by index (see + . + + + The name of the argument in the constructor argument list. May be + . + + + The to match. + + + A of + + objects that have already been used in the current resolution + process and should therefore not be returned again; this allows one + to return the next generic argument match in the case of multiple + generic argument values of the same type. + + + The + + for the argument, or if none is set. + + + + + Return the map of indexed argument values. + + + An with + indices as keys and + s + as values. + + + + + Return the map of named argument values. + + + An with + named arguments as keys and + s + as values. + + + + + Return the set of generic argument values. + + + A of + s. + + + + + Return the number of arguments held in this instance. + + + + + Returns true if this holder does not contain any argument values, + neither indexed ones nor generic ones. + + + + + Holder for a constructor argument value, with an optional + attribute indicating the target + of the actual constructor argument. + + + + + Creates a new instance of the ValueHolder class. + + + The value of the constructor argument. + + + + + Creates a new instance of the ValueHolder class. + + + The value of the constructor argument. + + + The of the argument + . Can also be one of the common + aliases (int, bool, + float, etc). + + + + + A that represents the current + . + + + A that represents the current + . + + + + + Gets and sets the value for the constructor argument. + + +

+ Only necessary for manipulating a registered value, for example in + s. +

+ + + + + Return the of the constructor + argument. + + + + + + implementation that allows for convenient registration of custom + s. + + + + The use of this class is typically not required; the .NET + mechanism of associating a + with a + via the use of the + is the + recommended (and standard) way. This class primarily exists to cover + those cases where third party classes to which one does not have the + source need to be exposed to the type conversion mechanism. + +

+ Because the + + class implements the + + interface, instances of this class that have been exposed in the + scope of an + will + automatically be picked up by the application context and made + available to the IoC container whenever type conversion is required. If + one is using a + + object definition within the scope of an + , no such automatic + pickup of the + + is performed (custom converters will have to be added manually using the + + method). For most application scenarios, one will get better + mileage using the + abstraction. +

+ + +

+ The following examples all assume XML based configuration, and use + inner object definitions to define the custom + objects (nominally to + avoid polluting the object name space, but also because the + configuration simply reads better that way). +

+ + + + + + + + + + + + + + + + +

+ The following example illustrates a complete (albeit naieve) use case + for this class, including a custom + implementation, said + converters domain class, and the XML configuration that hooks the + converter in place and makes it available to a Spring.NET container for + use during object resolution. +

+

+ The domain class is a simple data-only object that contains the data + required to send an email message (such as the host and user account + name). A developer would prefer to use a string of the form + UserName=administrator,Password=r1l0k1l3y,Host=localhost to + configure the mail settings and just let the container take care of the + conversion. +

+ + namespace ExampleNamespace + { + public sealed class MailSettings + { + private string _userName; + private string _password; + private string _host; + + public string Host + { + get { return _host; } + set { _host = value; } + } + + public string UserName + { + get { return _userName; } + set { _userName = value; } + } + + public string Password + { + get { return _password; } + set { _password = value; } + } + } + + public sealed class MailSettingsConverter : TypeConverter + { + public override bool CanConvertFrom(ITypeDescriptorContext context, Type sourceType) + { + if (typeof (string) == sourceType) + { + return true; + } + return base.CanConvertFrom(context, sourceType); + } + + public override object ConvertFrom(ITypeDescriptorContext context, CultureInfo culture, object value) + { + string text = value as string; + if(text != null) + { + MailSettings mailSettings = new MailSettings(); + string[] tokens = text.Split(','); + for (int i = 0; i < tokens.Length; ++i) + { + string token = tokens[i]; + string[] settings = token.Split('='); + typeof(MailSettings).GetProperty(settings[0]) + .SetValue(mailSettings, settings[1], null); + } + return mailSettings; + } + return base.ConvertFrom(context, culture, value); + } + } + + // a very naieve class that uses the MailSettings class... + public sealed class ExceptionLogger + { + private MailSettings _mailSettings; + + public MailSettings MailSettings { + { + set { _mailSettings = value; } + } + + public void Log(object value) + { + Exception ex = value as Exception; + if(ex != null) + { + // use _mailSettings instance... + } + } + } + } + +

+ The attendant XML configuration for the above classes would be... +

+ + + + + + + + + + + + + + + + Juergen Hoeller + Simon White (.NET) + + + + + + + Registers any custom converters with the supplied + . + + + The object factory to register the converters with. + + + In case of errors. + + + + + Resolves the supplied into a + instance. + + + The object that is to be resolved into a + instance. + + + A resolved instance. + + + If the supplied is , + or the supplied cannot be resolved. + + + + + The custom converters to register. + + +

+ The uses the type name + of the class that requires conversion as the key, and an + instance of the + that will effect + the conversion. Alternatively, the actual + of the class that requires conversion + can be used as the key. +

+ + +

+ + IDictionary converters = new Hashtable(); + converters.Add( "System.Date", new MyCustomDateConverter() ); + // a System.Type instance can also be used as the key... + converters.Add( typeof(Color), new MyCustomRBGColorConverter() ); + +

+ + + + + implementation that + creates delegates. + + +

+ Supports the creation of s for both + instance and methods. +

+ + Rick Evans + + + + Callback method called once all factory properties have been set. + + + In the event of misconfiguration (such as failure to set an essential + property) or if initialization fails. + + + + + + Creates the delegate. + + + If an exception occured during object creation. + + The object returned by this factory. + + + + + The of + created by this factory. + + +

+ Returns the + if accessed prior to the method + being called. +

+ + + + + The of the + created by this factory. + + + + + The name of the method that is to be invoked by the created + delegate. + + + + + The target if the + refers to a method. + + + + + The target object if the + refers to an instance method. + + + + + A generic implementation of an , that delegates post processing to a passed delegate + + + This comes in handy when you want to perform specific tasks on an object factory, e.g. doing special initialization. + + + The example below is taken from a unit test. The snippet causes 'someObject' to be registered each time is called on + the context instance: + + IConfigurableApplicationContext ctx = new XmlApplicationContext(false, "name", false, null); + ctx.AddObjectFactoryPostProcessor(new DelegateObjectFactoryConfigurer( of => + { + of.RegisterSingleton("someObject", someObject); + })); + + + Erich Eichinger + + + + Get or Set the handler to delegate configuration to + + + + + Descriptor for a specific dependency that is about to be injected. + Wraps a constructor parameter, a method parameter or a field, + allowing unified access to their metadata. + + Juergen Hoeller + Mark Pollack + + + + Initializes a new instance of the class for a method or constructor parameter. + Considers the dependency as 'eager' + + The MethodParameter to wrap. + if set to true if the dependency is required. + + + + Initializes a new instance of the class for a method or a constructor parameter. + + The MethodParameter to wrap. + if set to true the dependency is required. + if set to true the dependency is 'eager' in the sense of + eagerly resolving potential target objects for type matching. + + + + Gets a value indicating whether this dependency is required. + + true if required; otherwise, false. + + + + Determine the declared (non-generic) type of the wrapped parameter/field. + + The type of the dependency (never null + + + + Gets a value indicating whether this is eager in the sense of + eagerly resolving potential target beans for type matching. + + true if eager; otherwise, false. + + + + Gets the wrapped MethodParameter, if any. + + The method parameter. + + + + Simple factory for shared instances. + + Juergen Hoeller + Simon White (.NET) + + + + Constructs a new instance of the target dictionary. + + The new instance. + + + + Set the source . + + +

+ This value will be used to populate the + returned by this factory. +

+ + + + + Set the of the + implementation to use. + + +

+ The default is the . +

+ + + If the value is . + + + If the value is an . + + + If the value is an interface. + + + + + The of objects created by this factory. + + + Always returns the . + + + + + A very simple, hashtable-based implementation of + + Erich Eichinger + + + + Creates a new, empty variable source + + + + + Creates a new, empty and case-insensitive variable source + + + + + Create a new variable source from a list of paired string values. + + + + The example below shows, how the dictionary is filled with { 'key1', 'value1' }, { 'key2', 'value2' } pairs: + + new DictionaryVariableSource( new string[] { "key1", "value1", "key2", "value2" } ) + + + + the argument list containing pairs, or null + + + + Initializes a new instance of the DictionaryVariableSource class. + + + + + Creates a new variable source, reading values from another dictionary + and converting them to strings if necessary + + + + + Adds a key/value pair + + this dictionary. allows for fluent config + + + + Before requesting a variable resolution, a client should + ask, whether the source can resolve a particular variable name. + + the name of the variable to resolve + true if the variable can be resolved, false otherwise + + + + Performs a variable name lookup + + + + + Specifies how instances of the + + class must apply environment variables when replacing values. + + Mark Pollack + + + + Never replace environment variables. + + + + + If properties are not specified via a resource, + then resolve using environment variables. + + + + + Apply environment variables first before applying properties from a + resource. + + + + + Implementation of that + resolves variable name against environment variables. + + Aleksandar Seovic + + + + Before requesting a variable resolution, a client should + ask, whether the source can resolve a particular variable name. + + the name of the variable to resolve + true if the variable can be resolved, false otherwise + + + + Resolves variable value for the specified variable name. + + + The name of the variable to resolve. + + + The variable value if able to resolve, null otherwise. + + + + + Holder for event handler values for an object. + + Rick Evans (.NET) + + + + The empty array of s. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The + to be used to populate this instance. + + + + + Copy all given argument values into this object. + + + The + to be used to populate this instance. + + + + + Adds the supplied handler to the collection of event handlers. + + The handler to be added. + + + + The mapping of event names to an + of + s. + + + + + Gets the of events + that have handlers associated with them. + + + + + Gets the of + s for the supplied + event name. + + + + + Immutable placeholder class used for the value of a + object when it's a reference + to a Spring that should be evaluated at runtime. + + Aleksandar Seovic + + + + Creates a new instance of the + + class. + + The expression to resolve. + + + + Returns a string representation of this instance. + + A string representation of this instance. + + + + Gets or sets the expression string. Setting the expression string will cause + the expression to be parsed. + + The expression string. + + + + Return the expression. + + + + + Properties for this expression node. + + + + + implementation that + retrieves a static or non-static public field value. + + +

+ Typically used for retrieving public constants. +

+ + +

+ The following example retrieves the field value... +

+ + + + + + +

+ The previous example could also have been written using the convenience + + property, like so... +

+ + + + + +

+ This class also implements the + interface + (). + If the id (or name) of one's + + object definition is set to the + of the field to be retrieved, then the id (or + name) of one's object definition will be used for the name of the + field lookup. See below for an example of this + concise style of definition. +

+ + + + + + + +

+ The usage for retrieving instance fields is similar. No example is shown + because public instance fields are generally bad practice; but if + you have some legacy code that exposes public instance fields, or if you + just really like coding public instance fields, then you can use this + implementation to + retrieve such field values. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + Interface to be implemented by objects that wish to be aware of their object + name in an . + + +

+ Note that most objects will choose to receive references to collaborating + objects via respective properties. +

+

+ For a list of all object lifecycle methods, see the + API documentation. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + Set the name of the object in the object factory that created this object. + + + The name of the object in the factory. + + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + + + Invoked by an + after it has set all object properties supplied + (and satisfied + and ApplicationContextAware). + + +

+ This method allows the object instance to perform initialization only + possible when all object properties have been set and to throw an + exception in the event of misconfiguration. +

+ + + In the event of misconfiguration (such as failure to set an essential + property) or if initialization fails. + + + + + Return an instance (possibly shared or independent) of the object + managed by this factory. + + + An instance (possibly shared or independent) of the object managed by + this factory. + + + + + + The of the + field to be retrieved. + + + + + Set the name of the object in the object factory that created this object. + + + The name of the object in the factory. + + +

+ In the context of the + + class, the + + value will be interepreted as the value of the + + property if no value has been explicitly assigned to the + + property. This allows for concise object definitions with just an id or name; + see the class documentation for + + for an example of this style of usage. +

+ + + + + The name of the field the value of which is to be retrieved. + + +

+ If the + + has been set (and is not ), then the value of this property + refers to an instance field name; it otherwise refers to a + field name. +

+ + + + + The object instance on which the field is defined. + + + + + The on which the field is defined. + + + + + The of object that this + creates, or + if not known in advance. + + + + + Is the object managed by this factory a singleton or a prototype? + + + + + Extension of the + interface to be implemented by object factories that are capable of + autowiring and expose this functionality for existing object instances. + + Juergen Hoeller + Rick Evans (.NET) + + + + Create a new object instance of the given class with the specified + autowire strategy. + + + The of the object to instantiate. + + + The desired autowiring mode. + + + Whether to perform a dependency check for objects (not applicable to + autowiring a constructor, thus ignored there). + + The new object instance. + + If the wiring fails. + + + + + + Autowire the object properties of the given object instance by name or + . + + + The existing object instance. + + + The desired autowiring mode. + + + Whether to perform a dependency check for the object. + + + If the wiring fails. + + + + + + Apply s + to the given existing object instance, invoking their + + methods. + + +

+ The returned object instance may be a wrapper around the original. +

+ + + The existing object instance. + + + The name of the object. + + + The object instance to use, either the original or a wrapped one. + + + If any post-processing failed. + + + + + + Apply s + to the given existing object instance, invoking their + + methods. + + +

+ The returned object instance may be a wrapper around the original. +

+ + + The existing object instance. + + + The name of the object. + + + The object instance to use, either the original or a wrapped one. + + + If any post-processing failed. + + + + + + Resolve the specified dependency against the objects defined in this factory. + + The descriptor for the dependency. + Name of the object which declares the present dependency. + A list that all names of autowired object (used for + resolving the present dependency) are supposed to be added to. + the resolved object, or null if none found + if dependency resolution failed + + + + Extension of the interface + that injects dependencies into the object managed by the factory. + + Bruno Baia + + + + Gets the template object definition that should be used + to configure the instance of the object managed by this factory. + + + + + SPI interface to be implemented by most if not all listable object factories. + + +

+ Allows for framework-internal plug'n'play, e.g. in + . +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + Configuration interface to be implemented by most if not all object + factories. + + +

+ Provides the means to configure an object factory in addition to the + object factory client methods in the + interface. +

+

+ Allows for framework-internal plug'n'play even when needing access to object + factory configuration methods. +

+

+ When disposed, it will destroy all cached singletons in this factory. Call + when you want to shutdown + the factory. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + Interface that defines a registry for shared object instances. + + + Can be implemented by + implementations in order to expose their singleton management facility + in a uniform manner. + + The interface extends this interface. + + + Juergen Hoeller + Mark Pollack (.NET) + + + + Registers the given existing object as singleton in the object registry, + under the given object name. + + + + The given instance is supposed to be fully initialized; the registry + will not perform any initialization callbacks (in particular, it won't + call IInitializingObject's AfterPropertiesSet method). + The given instance will not receive any destruction callbacks + (like IDisposable's Dispose method) either. + + + If running within a full IObjectFactory: Register an object definition + instead of an existing instance if your object is supposed to receive + initialization and/or destruction callbacks. + + + Typically invoked during registry configuration, but can also be used + for runtime registration of singletons. As a consequence, a registry + implementation should synchronize singleton access; it will have to do + this anyway if it supports a BeanFactory's lazy initialization of singletons. + + + Name of the object. + The singleton object. + + + + + + Return the (raw) singleton object registered under the given name. + + + + Only checks already instantiated singletons; does not return an Object + for singleton object definitions which have not been instantiated yet. + + + The main purpose of this method is to access manually registered singletons + . Can also be used to access a singleton + defined by an object definition that already been created, in a raw fashion. + + + Name of the object to look for. + the registered singleton object, or null if none found + + + + + Check if this registry contains a singleton instance with the given name. + + + + Only checks already instantiated singletons; does not return true + for singleton bean definitions which have not been instantiated yet. + + + The main purpose of this method is to check manually registered singletons + . Can also be used to check whether a + singleton defined by an object definition has already been created. + + + To check whether an object factory contains an object definition with a given name, + use ListableBeanFactory's ContainsObjectDefinition. Calling both + ContainsObjectDefinition and ContainsSingleton answers + whether a specific object factory contains an own object with the given name. + + + Use IObjectFactory's ContainsObject for general checks whether the + factory knows about an object with a given name (whether manually registered singleton + instance or created by bean definition), also checking ancestor factories. + + + Name of the object to look for. + + true if this bean factory contains a singleton instance with the given name; otherwise, false. + + + + + + + + Gets the names of singleton objects registered in this registry. + + + + Only checks already instantiated singletons; does not return names + for singleton bean definitions which have not been instantiated yet. + + + The main purpose of this method is to check manually registered singletons + . Can also be used to check which + singletons defined by an object definition have already been created. + + + The list of names as String array (never null). + + + + + + + Gets the number of singleton beans registered in this registry. + + + + Only checks already instantiated singletons; does not count + singleton object definitions which have not been instantiated yet. + + + The main purpose of this method is to check manually registered singletons + . Can also be used to count the number of + singletons defined by an object definition that have already been created. + + + The number of singleton objects. + + + + + + + Ignore the given dependency type for autowiring. + + +

+ To be invoked during factory configuration. +

+

+ This will typically be used for dependencies that are resolved + in other ways, like + through . +

+ + + The to be ignored. + + + + + Determines whether the specified object name is currently in creation.. + + Name of the object. + + true if the specified object name is currently in creation; otherwise, false. + + + + + Add a new + that will get applied to objects created by this factory. + + +

+ To be invoked during factory configuration. +

+ + + The + to register. + + + + + Given an object name, create an alias. + + +

+ This is typically used to support names that are illegal within + XML ids (which are used for object names). +

+

+ Typically invoked during factory configuration, but can also be + used for runtime registration of aliases. Therefore, a factory + implementation should synchronize alias access. +

+ + The name of the object. + + + The alias that will behave the same as the object name. + + + If there is no object with the given name. + + + If the alias is already in use. + + + + + Register the given custom + for all properties of the given . + + +

+ To be invoked during factory configuration. +

+ + + The required of the property. + + + The to register. + + + + + Set the parent of this object factory. + + +

+ Note that the parent shouldn't be changed: it should only be set outside + a constructor if it isn't available when an object of this class is + created. +

+ + + + + Returns the current number of registered + s. + + + The current number of registered + s. + + + + + Return the registered + for the + given object, allowing access to its property values and constructor + argument values. + + The name of the object. + + The registered + . + + + If there is no object with the given name. + + + In the case of errors. + + + + + Return the registered + for the + given object, allowing access to its property values and constructor + argument values. + + The name of the object. + Whether to search parent object factories. + + The registered + . + + + If there is no object with the given name. + + + In the case of errors. + + + + + Register a new object definition with this registry. + Must support + + and . + + + The name of the object instance to register. + + + The definition of the object instance to register. + + +

+ Must support + and + . +

+ + + If the object definition is invalid. + + + + + Injects dependencies into the supplied instance + using the supplied . + + + The object instance that is to be so configured. + + + The name of the object definition expressing the dependencies that are to + be injected into the supplied instance. + + + An object definition that should be used to configure object. + + + + + + Ensure that all non-lazy-init singletons are instantiated, also + considering s. + + +

+ Typically invoked at the end of factory setup, if desired. +

+

+ As this is a startup method, it should destroy already created singletons if + it fails, to avoid dangling resources. In other words, after invocation + of that method, either all or no singletons at all should be + instantiated. +

+ + + If one of the singleton objects could not be created. + + + + + Register a special dependency type with corresponding autowired value. + + + This is intended for factory/context references that are supposed + to be autowirable but are not defined as objects in the factory: + e.g. a dependency of type ApplicationContext resolved to the + ApplicationContext instance that the object is living in. + + Note there are no such default types registered in a plain IObjectFactory, + not even for the BeanFactory interface itself. + + + Type of the dependency to register. + This will typically be a base interface such as IObjectFactory, with extensions of it resolved + as well if declared as an autowiring dependency (e.g. IListableBeanFactory), + as long as the given value actually implements the extended interface. + + The autowired value. This may also be an + implementation o the interface, + which allows for lazy resolution of the actual target value. + + + + Determines whether the specified object qualifies as an autowire candidate, + to be injected into other beans which declare a dependency of matching type. + This method checks ancestor factories as well. + + Name of the object to check. + The descriptor of the dependency to resolve. + + true if the object should be considered as an autowire candidate; otherwise, false. + + if there is no object with the given name. + + + + May be used to store custom value references in object definition properties. + + + Erich Eichinger + + + + + + the object factory holding the given object definition + + + The name of the object that is having the value of one of its properties resolved. + + + The definition of the named object. + + + The name of the property the value of which is being resolved. + + + The value of the property that is being resolved. + + + + + Subinterface of + that adds + a before-destruction callback. + + + The typical usage will be to invoke custom destruction callbacks on + specific object types, matching corresponding initialization callbacks. + + Juergen Hoeller + Simon White (.NET) + + + + Apply this + to the + given new object instance before its destruction. Can invoke custom + destruction callbacks. + + The new object instance. + The name of the object. + + In case of errors. + + + + + Denotes a special placeholder collection that may contain + s or + other placeholder objects that will need to be resolved. + + +

+ 'A special placeholder collection' means that the elements of this + collection can be placeholders for objects that will be resolved later by + a Spring.NET IoC container, i.e. the elements themselves will be + resolved at runtime by the enclosing IoC container. +

+

+ The core Spring.NET library already provides three implementations of this interface + straight out of the box; they are... +

+ + + + . + + + + + . + + + + + . + + + +

+ If you have a custom collection class (i.e. a class that either implements the + directly or derives from a class that does) + that you would like to expose as a special placeholder collection (i.e. one that can + have s as elements + that will be resolved at runtime by an appropriate Spring.NET IoC container, just + implement this interface. +

+ + +

+ Lets say one has a Bag class (i.e. a collection that supports bag style semantics). +

+ + using System; + + using Spring.Objects.Factory.Support; + + namespace MyNamespace + { + public sealed class Bag : ICollection + { + // ICollection implementation elided for clarity... + + public void Add(object o) + { + // implementation elided for clarity... + } + } + + public class ManagedBag : Bag, IManagedCollection + { + public ICollection Resolve( + string objectName, RootObjectDefinition definition, + string propertyName, ManagedCollectionElementResolver resolver) + { + Bag newBag = new Bag(); + string elementName = propertyName + "[bag-element]"; + foreach(object element in this) + { + object resolvedElement = resolver(objectName, definition, elementName, element); + newBag.Add(resolvedElement); + } + return newBag; + } + } + } + + + Rick Evans + + + + Resolves this managed collection at runtime. + + + The name of the top level object that is having the value of one of it's + collection properties resolved. + + + The definition of the named top level object. + + + The name of the property the value of which is being resolved. + + + The callback that will actually do the donkey work of resolving + this managed collection. + + A fully resolved collection. + + + + Resolves a single element value of a managed collection. + + +

+ If the does not need to be resolved or + converted to an appropriate , the + will be returned as-is. +

+ + + The name of the top level object that is having the value of one of it's + collection properties resolved. + + + The definition of the named top level object. + + + The name of the property the value of which is being resolved. + + + That element of a managed collection that may need to be resolved + to a concrete value. + + A fully resolved element. + + + + Describes an object instance, which has property values, constructor + argument values, and further information supplied by concrete implementations. + + +

+ This is just a minimal interface: the main intention is to allow + + (like PropertyPlaceholderConfigurer) to access and modify property values. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + Return the property values to be applied to a new instance of the object. + + + + + Return the constructor argument values for this object. + + + + + Return the event handlers for any events exposed by this object. + + + + + Return a description of the resource that this object definition + came from (for the purpose of showing context in case of errors). + + + + + Is this object definition a "template", i.e. not meant to be instantiated + itself but rather just serving as an object definition for configuration + templates used by . + + + if this object definition is a "template". + + + + + Is this object definition "abstract", i.e. not meant to be instantiated + itself but rather just serving as parent for concrete child object + definitions. + + + if this object definition is "abstract". + + + + + Return whether this a Singleton, with a single, shared instance + returned on all calls. + + +

+ If , an object factory will apply the Prototype + design pattern, with each caller requesting an instance getting an + independent instance. How this is defined will depend on the + object factory implementation. Singletons are the commoner type. +

+ + + + + Is this object lazily initialized? + +

+ Only applicable to a singleton object. +

+

+ If , it will get instantiated on startup by object factories + that perform eager initialization of singletons. +

+ + + + + The name of the parent definition of this object definition, if any. + + + + + The target scope for this object. + + + + + Get the role hint for this object definition + + + + + Returns the of the object definition (if any). + + + A resolved object . + + + If the of the object definition is not a + resolved or . + + + + + Returns the of the + of the object definition. + + Note that this does not have to be the actual type name used at runtime, + in case of a child definition overrding/inheriting the the type name from its + parent. It can be modifed during object factory post-processing, typically + replacing the original class name with a parsed variant of it. + Hence, do not consider this to be the definitive bean type at runtime + but rather only use it for parsing purposes at the individual object + definition level. + + + + + The autowire mode as specified in the object definition. + + +

+ This determines whether any automagical detection and setting of + object references will happen. Default is + , + which means there's no autowire. +

+ + + + + The object names that this object depends on. + + +

+ The object factory will guarantee that these objects get initialized + before. +

+

+ Note that dependencies are normally expressed through object properties + or constructor arguments. This property should just be necessary for + other kinds of dependencies like statics (*ugh*) or database + preparation on startup. +

+ + + + + The name of the initializer method. + + +

+ The default is , in which case there is no initializer method. +

+ + + + + Return the name of the destroy method. + + +

+ The default is , in which case there is no destroy method. +

+ + + + + The name of the factory method to use (if any). + + +

+ This method will be invoked with constructor arguments, or with no + arguments if none are specified. The static method will be invoked on + the specified . +

+ + + + + The name of the factory object to use (if any). + + + + + Gets a value indicating whether this instance a candidate for getting autowired into some other + object. + + + true if this instance is autowire candidate; otherwise, false. + + + + + Simple factory for shared instances. + + Juergen Hoeller + Simon White (.NET) + + + + Constructs a new instance of the target dictionary. + + The new instance. + + + + Set the source . + + +

+ This value will be used to populate the + returned by this factory. +

+ + + + + Set the of the + implementation to use. + + +

+ The default is the . +

+ + + + + The of objects created by this factory. + + + Always returns the . + + + + + implementation that + creates instances of the class. + + +

+ Typically used for retrieving shared + instances for common topics (such as the 'DAL', 'BLL', etc). The + + property determines the name of the + Common.Logging logger. +

+ + Rick Evans + + + + + Creates a new instance of the + + class. + + + + + Creates a new instance of the + + class. + + + The name of the instance served up by + this factory. + + + If the supplied is + or contains only whitespace character(s). + + + + + Return an instance (possibly shared or independent) of the object + managed by this factory. + + + An instance (possibly shared or independent) of the object + managed by this factory. + + + + + + Invoked by an + after it has set all object properties supplied + (and satisfied the + + and + interfaces). + + + In the event of misconfiguration (such as failure to set an essential + property) or if initialization fails. + + + + + + The name of the instance served up by + this factory. + + + The name of the instance served up by + this factory. + + + If the supplied to the setter is + or contains only whitespace character(s). + + + + + Return the type of object that this + creates, or + if not known in advance. + + + + + + Is the object managed by this factory a singleton or a prototype? + + + + + + Tag subclass used to hold a dictionary of managed elements. + + Juergen Hoeller + Rick Evans (.NET) + + + + Interface representing an object whose value set can be merged with that of a parent object. + + Rob Harrop + Mark Pollack (.NET) + + + + Merges the current value set with that of the supplied object. + + The supplied object is considered the parent, and values in the + callee's value set must override those of the supplied object. + + The parent object to merge with + The result of the merge operation + If the supplied parent is null + If merging is not enabled for this instance, + (i.e. MergeEnabled equals false. + + + + Gets a value indicating whether this instance is merge enabled for this instance + + + true if this instance is merge enabled; otherwise, false. + + + + + Initializes a new, empty instance of the class using the default initial capacity, load factor, hash code provider, and comparer. + + + + + Initializes a new, empty instance of the class using the specified initial capacity, and the default load factor, hash code provider, and comparer. + + The approximate number of elements that the object can initially contain. is less than zero. + + + + Resolves this managed collection at runtime. + + + The name of the top level object that is having the value of one of it's + collection properties resolved. + + + The definition of the named top level object. + + + The name of the property the value of which is being resolved. + + + The callback that will actually do the donkey work of resolving + this managed collection. + + A fully resolved collection. + + + + Merges the current value set with that of the supplied object. + + The supplied object is considered the parent, and values in the + callee's value set must override those of the supplied object. + + The parent object to merge with + The result of the merge operation + If the supplied parent is null + If merging is not enabled for this instance, + (i.e. MergeEnabled equals false. + + + + Gets or sets the unresolved name for the + of the keys of this managed dictionary. + + The unresolved name for the type of the keys of this managed dictionary. + + + + Gets or sets the unresolved name for the + of the values of this managed dictionary. + + The unresolved name for the type of the values of this managed dictionary. + + + + Gets a value indicating whether this instance is merge enabled for this instance + + + true if this instance is merge enabled; otherwise, false. + + + + + Tag subclass used to hold a list of managed elements. + + Rod Johnson + Rick Evans (.NET) + + + + Initializes a new instance of the ManagedList class that is empty and has the default initial capacity. + + + + + Initializes a new instance of the ManagedList class that is empty and has the specified initial capacity. + + The number of elements that the new list can initially store. is less than zero. + + + + Resolves this managed collection at runtime. + + + The name of the top level object that is having the value of one of it's + collection properties resolved. + + + The definition of the named top level object. + + + The name of the property the value of which is being resolved. + + + The callback that will actually do the donkey work of resolving + this managed collection. + + A fully resolved collection. + + + + Merges the current value set with that of the supplied object. + + The supplied object is considered the parent, and values in the + callee's value set must override those of the supplied object. + + The parent object to merge with + The result of the merge operation + If the supplied parent is null + If merging is not enabled for this instance, + (i.e. MergeEnabled equals false. + + + + Gets or sets the unresolved name for the + of the elements of this managed list. + + The unresolved name for the type of the elements of this managed list. + + + + Gets a value indicating whether this instance is merge enabled for this instance + + + true if this instance is merge enabled; otherwise, false. + + + + + Tag class which represent a Spring-managed instance that + supports merging of parent/child definitions. + + + + + Initializes a new instance of the class that is empty, has the default initial capacity and uses the default case-insensitive hash code provider and the default case-insensitive comparer. + + + + + Initializes a new instance of the class that is empty, has the specified initial capacity and uses the default case-insensitive hash code provider and the default case-insensitive comparer. + + The initial number of entries that the can contain. is less than zero. + + + + Merges the current value set with that of the supplied object. + + The supplied object is considered the parent, and values in the + callee's value set must override those of the supplied object. + + The parent object to merge with + The result of the merge operation + If the supplied parent is null + If merging is not enabled for this instance, + (i.e. MergeEnabled equals false. + + + + Gets a value indicating whether this instance is merge enabled for this instance + + + true if this instance is merge enabled; otherwise, false. + + + + + Tag subclass used to hold a set of managed elements. + + Juergen Hoeller + Rick Evans (.NET) + + + + Creates a new set instance based on either a list or a hash table, + depending on which will be more efficient based on the data-set + size. + + + + + Initializes a new instance of the class with a given capacity + + The size. + + + + Resolves this managed collection at runtime. + + + The name of the top level object that is having the value of one of it's + collection properties resolved. + + + The definition of the named top level object. + + + The name of the property the value of which is being resolved. + + + The callback that will actually do the donkey work of resolving + this managed collection. + + A fully resolved collection. + + + + Merges the current value set with that of the supplied object. + + The supplied object is considered the parent, and values in the + callee's value set must override those of the supplied object. + + The parent object to merge with + The result of the merge operation + If the supplied parent is null + If merging is not enabled for this instance, + (i.e. MergeEnabled equals false. + + + + Gets or sets the unresolved name for the + of the elements of this managed set. + + The unresolved name for the type of the elements of this managed set. + + + + Gets a value indicating whether this instance is merge enabled for this instance + + + true if this instance is merge enabled; otherwise, false. + + + + + An that returns a value + that is the result of a or instance method invocation. + + +

+ Note that this class generally is expected to be used for accessing factory methods, + and as such defaults to operating in singleton mode. The first request to + + by the owning object factory will cause a method invocation, the return + value of which will be cached for all subsequent requests. The + property may be set to + , to cause this factory to invoke the target method each + time it is asked for an object. +

+

+ A target method may be specified by setting the + property to a string representing + the method name, with specifying + the that the method is defined on. + Alternatively, a target instance method may be specified, by setting the + property as the target object, and + the property as the name of the + method to call on that target object. Arguments for the method invocation may be + specified by setting the property. +

+

+ Another (esoteric) use case for this factory object is when one needs to call a method + that doesn't return any value (for example, a class method to + force some sort of initialization to happen)... this use case is not supported by + factory-methods, since a return value is needed to become the object. +

+

+ + This class depends on the + + method being called after all properties have been set, as per the + contract. If you are + using this class outside of a Spring.NET IoC container, you must call one of either + or + yourself to ready the object's internal + state, or you will get a nasty . + +

+ + +

+ The following example uses an instance of this class to call a + factory method... +

+ + + + + + + + 1st + 2nd + and 3rd arguments + + + + +

+ The following example is similar to the preceding example; the only pertinent difference is the fact that + a number of different objects are passed as arguments, demonstrating that not only simple value types + are valid as elements of the argument list... +

+ + + + + + + + + + + 1st + + + + + + + http://www.springframework.net/ + + + + + +

+ Named parameters are also supported... this next example yields the same results as + the preceding example (that did not use named arguments). +

+ + + + + + + + + + 1st + and 3rd arguments + 2nd + + + + +

+ Similarly, the following example uses an instance of this class to call an instance method... +

+ + + + + + + + + +

+ The above example could also have been written using an anonymous inner object definition... if the + object on which the method is to be invoked is not going to be used outside of the factory object + definition, then this is the preferred idiom because it limits the scope of the object on which the + method is to be invoked to the surrounding factory object. +

+ + + + + + + + + + Colin Sampaleanu + Juergen Hoeller + Rick Evans (.NET) + Simon White (.NET) + + + + + + Specialisation of the class that tries + to convert the given arguments for the actual target method via an + appropriate implementation. + + Juergen Hoeller + Rick Evans + + + + + Helper class allowing one to declaratively specify a method call for later invocation. + + +

+ Typically not used directly but via its subclasses such as + . +

+

+ Usage: specify either the and + or the + and + properties respectively, and + (optionally) any arguments to the method. Then call the + method to prepare the invoker. + Once prepared, the invoker can be invoked any number of times. +

+ + +

+ The following example uses the class to invoke the + ToString() method on the Foo class using a mixture of both named and unnamed + arguments. +

+ + public class Foo + { + public string ToString(string name, int age, string address) + { + return string.Format("{0}, {1} years old, {2}", name, age, address); + } + + public static void Main() + { + Foo foo = new Foo(); + MethodInvoker invoker = new MethodInvoker(); + invoker.Arguments = new object [] {"Kaneda", "18 Kaosu Gardens, Nakatani Drive, Okinanawa"}; + invoker.AddNamedArgument("age", 29); + invoker.Prepare(); + // at this point, the arguments that will be passed to the method invocation + // will have been resolved into the following ordered array : {"Kaneda", 29, "18 Kaosu Gardens, Nakatani Drive, Okinanawa"} + string details = (string) invoker.Invoke(); + Console.WriteLine (details); + // will print out 'Kaneda, 29 years old, 18 Kaosu Gardens, Nakatani Drive, Okinanawa' + } + } + + + Colin Sampaleanu + Juergen Hoeller + Simon White (.NET) + + + + The used to search for + the method to be invoked. + + + + + The value returned from the invocation of a method that returns void. + + + + + The method that will be invoked. + + + + + Creates a new instance of the class. + + + + + Prepare the specified method. + + +

+ The method can be invoked any number of times afterwards. +

+ + + If all required properties are not set, or a matching argument could not be found + for a named argument (typically down to a typo). + + + If the specified method could not be found. + + + + + Searches for and returns the method that is to be invoked. + + + The return value of this method call will subsequently be returned from the + . + + The method that is to be invoked. + + If no method could be found. + + + If more than one method was found. + + + + + Adds the named argument to this instances mapping of argument names to argument values. + + + The name of an argument on the method that is to be invoked. + + + The value of the named argument on the method that is to be invoked. + + + + + Returns the prepared object that + will be invoked. + + +

+ A possible use case is to determine the return of the method. +

+ + + The prepared object that + will be invoked. + + + + + Invoke the specified method. + + +

+ The invoker needs to have been prepared beforehand (via a call to the + method). +

+ + + The object returned by the method invocation, or + if the method returns void. + + + If at least one of the arguments passed to this + was incompatible with the signature of the invoked method. + + + + + The target on which to call the target method. + + +

+ Only necessary when the target method is ; + else, a target object needs to be specified. +

+ + + + + The target object on which to call the target method. + + +

+ Only necessary when the target method is not ; + else, a target class is sufficient. +

+ + + + + The name of the method to be invoked. + + +

+ Refers to either a method + or a non- method, depending on + whether or not a target object has been set. +

+ + + + + + Arguments for the method invocation. + + +

+ Ordering is significant... the order of the arguments in this + property must match the ordering of the various parameters on the target + method. There does however exist a small possibility for confusion when + the arguments in this property are supplied in addition to one or more named + arguments. In this case, each named argument is slotted into the index position + corresponding to the named argument... once once all named arguments have been + resolved, the arguments in this property are slotted into any remaining (empty) + slots in the method parameter list (see the example in the overview of the + class if this is not clear). +

+

+ If this property is not set, or the value passed to the setter invocation + is or a zero-length array, a method with no (un-named) arguments is assumed. +

+ + + + + + The resolved arguments for the method invocation. + + + + This property is not set until the target method has been resolved via a call to the + method). It is a combination of the + named and plain vanilla arguments properties, and it is this object array that + will actually be passed to the invocation of the target method. + +

+ Setting the value of this property to results in basically clearing out any + previously prepared arguments... another call to the + method will then be required to prepare the arguments again (or the prepared arguments + can be set explicitly if so desired). +

+ + + + + + + Named arguments for the method invocation. + + +

+ The keys of this dictionary are the () names of the + method arguments, and the () values are the actual + argument values themselves. +

+

+ If this property is not set, or the value passed to the setter invocation + is a reference, a method with no named arguments is assumed. +

+ + + + + + Creates a new instance of the + class. + + + + + Prepare the specified method. + + +

+ The method can be invoked any number of times afterwards. +

+ + + If all required properties are not set. + + + If the specified method could not be found. + + + + + Register the given custom + for all properties of the given . + + + The of property. + + + The to register. + + + + + Return an instance (possibly shared or independent) of the object + managed by this factory. + + +

+ Returns the return value of the method that is to be invoked. +

+

+ Will return the same value each time if the + + property value is . +

+ + + An instance (possibly shared or independent) of the object managed by + this factory. + + + + + + Prepares this method invoker. + + + If all required properties are not set. + + + If the specified method could not be found. + + + + + + If a singleton should be created, or a new object on each request. + Defaults to . + + + + + Return the return value of the method + that this factory invokes, or if not + known in advance. + + +

+ If the return value of the method that this factory is to invoke is + , then the + will be returned (in accordance with the + contract that + treats a value as a configuration error). +

+ + + + + + Holder for an with + name and aliases. + + +

+ Recognized by + + for inner object definitions. Registered by + , + which also uses it as general holder for a parsed object definition. +

+

+ Can also be used for programmatic registration of inner object + definitions. If you don't care about the functionality offered by the + interface and the like, + registering + or is good enough. +

+ + Juergen Hoeller + Simon White (.NET) + + + + Creates a new instance of the + class. + + + The object definition to be held by this instance. + + + The name of the object definition. + + + + + Creates a new instance of the + class. + + + The object definition to be held by this instance. + + The name of the object. + + Any aliases for the supplied + + + + + The held by this + instance. + + + + + The name of the object definition. + + + + + Any aliases for the object definition. + + +

+ Guaranteed to never return ; if the associated + + does not have any aliases associated with it, then an empty + array will be returned. +

+ + + + + Visitor class for traversing objects, in particular + the property values and constructor arguments contained in them resolving + object metadata values. + + + Used by and + to parse all string values contained in a ObjectDefinition, resolving any placeholders found. + + Mark Pollack + + + + Initializes a new instance of the class. + + The handler to be called for resolving variables contained in a string. + + + + Initializes a new instance of the class + for subclassing + + Subclasses should override the ResolveStringValue method + + + + Traverse the given ObjectDefinition object and the MutablePropertyValues + and ConstructorArgumentValues contained in them. + + The object definition to traverse. + + + + Visits the ObjectDefinition property ObjectTypeName, replacing string values using + the specified IVariableSource. + + The object definition. + + + + Visits the property values of the ObjectDefinition, replacing string values + using the specified IVariableSource. + + The object definition. + + + + Visits the indexed constructor argument values, replacing string values using the + specified IVariableSource. + + The indexed argument values. + + + + Visits the named constructor argument values, replacing string values using the + specified IVariableSource. + + The named argument values. + + + + Visits the generic constructor argument values, replacing string values using + the specified IVariableSource. + + The genreic argument values. + + + + Configures the constructor argument ValueHolder. + + The vconstructor alue holder. + + + + Resolves the given value taken from an object definition according to its type + + the value to resolve + the resolved value + + + + Visits the ManagedList property ElementTypeName and + calls for list element. + + + + + Visits the ManagedSet property ElementTypeName and + calls for list element. + + + + + Visits the ManagedSet properties KeyTypeName and ValueTypeName and + calls for dictionary's value element. + + + + + Visits the elements of a NameValueCollection and calls + for value of each element. + + + + + calls the to resolve any variables contained in the raw string. + + the raw string value containing variable placeholders to be resolved + If no has been configured. + the resolved string, having variables being replaced, if any + + + + Returns a value that is an + that + returns an object from an + . + + +

+ The primary motivation of this class is to avoid having a client object + directly calling the + + method to get a prototype object out of an + , which would be a + violation of the inversion of control principle. With the use of this + class, the client object can be fed an + as a property + that directly returns one target prototype object. +

+

+ The object referred to by the value of the + + property does not have to be a prototype object, but there is little + to no point in using this class in conjunction with a singleton object. +

+ + +

+ The following XML configuration snippet illustrates the use of this + class... +

+ + + + + + + + + + + + + + + + Colin Sampaleanu + Simon White (.NET) + + + + Interface to be implemented by objects that wish to be aware of their owning + . + + +

+ For example, objects can look up collaborating objects via the factory. +

+

+ Note that most objects will choose to receive references to collaborating + objects via respective properties and / or an appropriate constructor. +

+

+ For a list of all object lifecycle methods, see the + API documentation. +

+ + Rod Johnson + Rick Evans (.NET) + + + + Callback that supplies the owning factory to an object instance. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + In case of initialization errors. + + + + + Returns an instance of the object factory. + + The object factory. + + + + Invoked by an + after it has set all supplied object properties. + + + In the event of misconfiguration (such as failure to set an essential + property) or if initialization fails. + + + + + + Sets the name of the target object. + + + + + The target factory that will be used to perform the lookup + of the object referred to by the + property. + + + The owning + (will never be ). + + + In case of initialization errors. + + + + + + The of object created by this factory. + + + + + Interface defining a factory which can return an object instance + (possibly shared or independent) when invoked. + + + This interface is typically used to encapsulate a generic factory + which returns a new instance (prototype) on each invocation. + It is similar to the , but + implementations of the aforementioned interface are normally meant to be defined + as instances by the user in an , + while implementations of this class are normally meant to be fed as a property to + other objects; as such, the + method + has different exception handling behavior. + + Colin Sampaleanu + Simon White (.NET) + + + + Return an instance (possibly shared or independent) + of the object managed by this factory. + + + An instance of the object (should never be ). + + + + + Creates a new instance of the GenericObjectFactory class. + + + The enclosing + . + + + + + Returns the object created by the enclosed object factory. + + The created object. + + + + An implementation + that exposes an arbitrary target object under a different name. + + +

+ Usually, the target object will reside in a different object + definition file, using this + to link it in + and expose it under a different name. Effectively, this corresponds + to an alias for the target object. +

+ + For XML based object definition files, a <alias> + tag is available that effectively achieves the same. + + + Juergen Hoeller + Rick Evans (.NET) + + + + + Initialize a new default instance + + + + + Initialize this instance with the predefined and . + + + + + + + Return an instance (possibly shared or independent) of the object + managed by this factory. + + + An instance (possibly shared or independent) of the object managed by + this factory. + + + + + + The name of the target object. + + +

+ The target object may potentially be defined in a different object + definition file. +

+ + The name of the target object. + + + + Return the type of object that this + creates, or + if not known in advance. + + + + + + Is the object managed by this factory a singleton or a prototype? + + + + + + Callback that supplies the owning factory to an object instance. + + + The owning + (may not be ). The object can immediately + call methods on the factory. + + + In case of initialization errors. + + + + + + + Erich Eichinger + + + + Role hint indicating that a is a major part of the application. Typically corresponds to a user-defined object. + + + + + Role hint indicating that a is a supporting + part of some larger configuration, typically an outer ComponentDefinition + SUPPORT objects are considered important enough to be aware + of when looking more closely at a particular ComponentDefinition, + but not when looking at the overall configuration of an application. + + + + + Role hint indicating that a is providing an + entirely background role and has no relevance to the end-user. This hint is + used when registering objects that are completely part of the internal workings + of a ComponentDefinition. + + + + + Implementation of that + resolves variable name against Java-style property file. + + + Aleksandar Seovic + + + + Before requesting a variable resolution, a client should + ask, whether the source can resolve a particular variable name. + + the name of the variable to resolve + true if the variable can be resolved, false otherwise + + + + Resolves variable value for the specified variable name. + + + The name of the variable to resolve. + + + The variable value if able to resolve, null otherwise. + + + + + Initializes properties based on the specified + property file locations. + + + + + Gets or sets the locations of the property files + to read properties from. + + + The locations of the property files + to read properties from. + + + + + Convinience property. Gets or sets a single location + to read properties from. + + + A location to read properties from. + + + + + Sets a value indicating whether to ignore resource locations that do not exist. This will call + the Exists property. + + + true if one should ignore missing resources; otherwise, false. + + + + + Overrides default values in one or more object definitions. + + +

+ Instances of this class override already existing values, and is + thus best suited to replacing defaults. If you need to replace + placeholder values, consider using the + + class instead. +

+

+ In contrast to the + + class, the original object definition can have default + values or no values at all for such object properties. If an overriding + configuration file does not have an entry for a certain object property, + the default object value is left as is. Also note that it is not + immediately obvious to discern which object definitions will be mutated by + one or more + s + simply by looking at the object configuration. +

+

+ Each line in a referenced configuration file is expected to take the + following form... +

+ + + +

+ The name.property key refers to the object name and the + property that is to be overridden; and the value is the overridding + value that will be inserted into the appropriate object definition's + named property. +

+

+ Please note that in the case of multiple + s + that define different values for the same object definition value, the + last overridden value will win (due to the fact that the values + supplied by previous + s + will be overridden). +

+ + +

+ The following XML context definition defines an object that has a number + of properties, all of which have default values... +

+ + + + + + + + +

+ What follows is a .NET config file snippet for the above example (assuming + the need to override one of the default values)... +

+ + + + + + + + Juergen Hoeller + Simon White (.NET) + + + + + + + Allows for the configuration of individual object property values from + a .NET .config file. + + +

+ Useful for custom .NET .config files targetted at system administrators + that override object properties configured in the application context. +

+

+ Two concrete implementations are provided in the Spring.NET core library: + + + + + for <add key="placeholderKey" value="..."/> style + overriding (pushing values from a .NET .config file into object + definitions). + + + + + + for replacing "${...}" placeholders (pulling values from a .NET .config + file into object definitions). + + + +

+

+ Please refer to the API documentation for the concrete implementations + listed above for example usage. +

+ + Juergen Hoeller + Simon White (.NET) + + + + + + The default configuration section name to use if none is explictly supplied. + + + + + + Creates a new instance of the + + class. + + +

+ This is an class, and as such exposes no + public constructors. +

+ + + + + Modify the application context's internal object factory after its + standard initialization. + + + The object factory used by the application context. + + + In case of errors. + + + + + + Loads properties from the configuration sections + specified in into . + + The instance to be filled with properties. + + + + Apply the given properties to the supplied + . + + + The + used by the application context. + + The properties to apply. + + If an error occured. + + + + + Validates the supplied . + + +

+ Basically, if external locations are specified, ensure that either + one or a like number of config sections are also specified. +

+ + + The to be validated. + + + + + Simply initializes the supplied + collection with this instances default + (if any). + + + The collection to be so initialized. + + + + + The policy for resolving conflicting property overrides from + several resources. + + +

+ When merging conflicting property overrides from several resources, + should append an override with the same key be appended to the + current value, or should the property override from the last resource + processed override previous values? +

+

+ The default value is ; i.e. a property + override from the last resource to be processed overrides previous + values. +

+ + + if the property override from the last resource + processed overrides previous values. + + + + + Return the order value of this object, where a higher value means greater in + terms of sorting. + + The order value. + + + + + The default properties to be applied. + + +

+ These are to be considered defaults, to be overridden by values + loaded from other resources. +

+ + + + + The location of the .NET .config file that contains the property + overrides that are to be applied. + + + + + The locations of the .NET .config files containing the property + overrides that are to be applied. + + + + + The configuration sections to look for within the .config files. + + + + + + + Should a failure to find a .config file be ignored? + + +

+ is only appropriate if the .config file is + completely optional. The default is . +

+ + + if a failure to find a .config file is to be + ignored. + + + + + Apply the given properties to the supplied + . + + + The + used by the application context. + + The properties to apply. + + If an error occured. + + + + + Process the given key as 'name.property' entry. + + + The object factory containing the object definitions that are to be + processed. + + The key. + The value. + + If an error occurs. + + + If the property was not well formed (i.e. not in the format "name.property"). + + + + + implementation that + evaluates a property path on a given target object. + + +

+ The target object can be specified directly or via an object name (see + example below). +

+

+ Please note that the + is an implementation, and as such has + to comply with the contract of the + interface; more specifically, this means that the end result of the property lookup path + evaluation cannot be ( + implementations are not permitted to return ). If the resut of a + property lookup path evaluates to , an exception will be thrown. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Juergen Hoeller + Rick Evans (.NET) + + + + Return an instance (possibly shared or independent) of the object + managed by this factory. + + + An instance (possibly shared or independent) of the object managed by + this factory. + + + + + + The target object that the property path lookup is to be applied to. + + +

+ This would most likely be an inner object, but can of course be + any object reference. +

+ + + The target object that the property path lookup is to be applied to. + + + + + + The (object) name of the target object that the property path lookup + is to be applied to. + + +

+ Please note that any leading or trailing whitespace will be + trimmed from this name prior to resolution. The implication of this is that + one cannot use the + class in conjunction with object names that start or end with whitespace. +

+ + + The (object) name of the target object that the property path lookup + is to be applied to. + + + + + + The property (lookup) path to be applied to the target object. + + +

+ Please note that any leading or trailing whitespace will be + trimmed from this path prior to resolution. Whitespace is not a valid + identifier for property names (in part or whole) in CLS-based languages, + so this is a not unreasonable action. Please also note that whitespace + that is embedded within the property path will be left as-is (which may + or may not result in an error being thrown, depending on the context of + the whitespace). +

+ + +

+ Examples of such property lookup paths can be seen below; note that + property lookup paths can be nested to an arbitrary level. +

+ + name.length + accountManager.account['the key'].name + accounts[0].name + + + + The property (lookup) path to be applied to the target object. + + + + + The 'expected' of the result from evaluating the + property path. + + +

+ This is not necessary for directly specified target objects, or + singleton target objects, where the can + be determined via reflection. Just specify this in case of a + prototype target, provided that you need matching by type (for + example, for autowiring). +

+

+ It is permissable to set the value of this property to + (which in any case is the default value). +

+ + + The 'expected' of the result from evaluating the + property path. + + + + + Return the of object that this + creates, or + if not known in advance. + + + + + + Is the object managed by this factory a singleton or a prototype? + + + + + + Set the name of the object in the object factory that created this object. + + +

+ The object name of this + + will be interpreted as "objectName.property" pattern, if neither the + + + have been supplied (set). +

+

+ This allows for concise object definitions with just an id or name. +

+ + + The name of the object in the factory. + + + + + Callback that supplies the owning factory to an object instance. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + + In case of initialization errors. + + + + + Resolves placeholder values in one or more object definitions. + + +

+ The default placeholder syntax follows the NAnt style: ${...}. + Instances of this class can be configured in the same way as any other + object in a Spring.NET container, and so custom placeholder prefix + and suffix values can be set via the + and properties. +

+ +

+ The following example XML context definition defines an object that has + a number of placeholders. The placeholders can easily be distinguished + by the presence of the ${} characters. +

+ + + + + + + + +

+ The associated XML configuration file for the above example containing the + values for the placeholders would contain a snippet such as .. +

+ + + + + + + + +

+ The preceding XML snippet listing the various property keys and their + associated values needs to be inserted into the .NET config file of + your application (or Web.config file for your ASP.NET web application, + as the case may be), like so... +

+ + + + + + + + + +

+ + checks simple property values, lists, dictionaries, sets, constructor + values, object type name, and object names in + runtime object references ( + ). + Furthermore, placeholder values can also cross-reference other + placeholders, in the manner of the following example where the + rootPath property is cross-referenced by the subPath + property. +

+ + + + + + + + +

+ In contrast to the + + class, this configurer only permits the replacement of explicit + placeholders in object definitions. Therefore, the original definition + cannot specify any default values for its object properties, and the + placeholder configuration file is expected to contain an entry for each + defined placeholder. That is, if an object definition contains a + placeholder ${foo}, there should be an associated + <add key="foo" value="..."/> entry in the + referenced placeholder configuration file. Default property values + can be defined via the inherited + + collection to overcome any perceived limitation of this feature. +

+

+ If a configurer cannot resolve a placeholder, and the value of the + + property is currently set to , an + + will be thrown. If you want to resolve properties from multiple configuration + resources, simply specify multiple resources via the + + property. Finally, please note that you can also define multiple + + instances, each with their own custom placeholder syntax. +

+ + Juergen Hoeller + Simon White (.NET) + + + + + + + The default placeholder prefix. + + + + + The default placeholder suffix. + + + + + Initializes the new instance + + + + + Apply the given properties to the supplied + . + + + The + used by the application context. + + The properties to apply. + + If an error occured. + + + + + Parse values recursively to be able to resolve cross-references between + placeholder values. + + + The map of constructor arguments / property values. + + The string to be resolved. + The placeholders that have already been visited + during the current resolution attempt (used to detect circular references + between placeholders). Only non-null if we're parsing a nested placeholder. + + If an error occurs. + + The resolved string. + + + + Resolve the given placeholder using the given name value collection, + performing an environment variables check according to the given mode. + + +

+ The default implementation delegates to + + before/afer the environment variable check. Subclasses can override + this for custom resolution strategies, including customized points + for the environment properties check. +

+ + The placeholder to resolve + + The merged name value collection of this configurer. + + The environment variable mode. + + The resolved value or if none. + + + + + + Resolve the given placeholder using the given name value collection. + + +

+ This (the default) implementation simply looks up the value of the + supplied key. +

+

+ Subclasses can override this for customized placeholder-to-key + mappings or custom resolution strategies, possibly just using the + given name value collection as fallback. +

+ + The placeholder to resolve. + + The merged name value collection of this configurer. + + The resolved value. + + + + The placeholder prefix (the default is ${). + + + + + + The placeholder suffix (the default is }) + + + + + + Indicates whether unresolved placeholders should be ignored. + + + + + Controls how environment variables will be used to + replace property placeholders. + + +

+ See the overview of the + + enumeration for the available options. +

+ + + + + implementation that + retrieves a or non-static public property value. + + +

+ Typically used for retrieving public property values. +

+ + Rick Evans (.NET) + + + + Creates a new instance of the + class. + + + + + Invoked by an + after it has set all object properties supplied + (and satisfied + and ApplicationContextAware). + + + In the event of misconfiguration (such as failure to set an essential + property) or if initialization fails. + + + + + Template method that subclasses must override to construct the object + returned by this factory. + + + If an exception occured during object creation. + + The object returned by this factory. + + + + The of the static property + to be retrieved. + + + + + Arguments for the property invocation. + + +

+ If this property is not set, or the value passed to the setter invocation + is a null or zero-length array, a property with no arguments is assumed. +

+ + + + + The name of the property the value of which is to be retrieved. + + +

+ Refers to either a property or a non-static property, + depending on a target object being set. +

+ + + + + The object instance on which the property is defined. + + + + + The on which the property is defined. + + + + + Return the type of object that this + creates, or + if not known in advance. + + + + + Implementation of that + resolves variable name against registry key. + + Aleksandar Seovic + + + + Before requesting a variable resolution, a client should + ask, whether the source can resolve a particular variable name. + + the name of the variable to resolve + true if the variable can be resolved, false otherwise + + + + Resolves variable value for the specified variable name. + + + The name of the variable to resolve. + + + This implementation resolves REG_SZ as well as REG_MULTI_SZ values. In case of a REG_MULTI_SZ value, + strings are concatenated to a comma-separated list following + + + The variable value if able to resolve, null otherwise. + + + + + Gets or sets the registry key to obtain variable values from. + + + The registry key to obtain variable values from. + + + + + + implementation that allows for convenient registration of custom + IResource implementations. + + +

+ Because the + class implements the + + interface, instances of this class that have been exposed in the + scope of an + will + automatically be picked up by the application context and made + available to the IoC container whenever resolution of IResources is required. +

+ + Mark Pollack + + + + + + Registers custom IResource implementations. The supplied + is not used since IResourse implementations + are registered with a global + + + The object factory. + + + In case of errors. + + + + + The IResource implementations, i.e. resource handlers, to register. + + +

+ The has the + contains the resource protocol name as the key and type as the value. + The key name can either be a string or an object, in which case + ToString() will be used to obtain the string name. + The value can be the fully qualified name of the IResource + implementation, a string, or + an actual of the IResource class + +

+ + + + + A convenience class to create a + given the resource base + name and assembly name. + + +

+ This is currently the preferred way of injecting resources into view + tier components (such as Windows Forms GUIs and ASP.NET ASPX pages). + A GUI component (typically a Windows Form) is injected with + an instance, and can + then proceed to use the various GetXxx() methods on the + to retrieve images, + strings, custom resources, etc. +

+ + Mark Pollack + + + + + + + Creates a . + + + If an exception occured during object creation. + + The object returned by this factory. + + + + + + Invoked by an + after it has set all object properties supplied + (and satisfied the + + and + interfaces). + + + In the event of misconfiguration (such as failure to set an essential + property) or if initialization fails. + + + + + + The root name of the resources. + + +

+ For example, the root name for the resource file named + "MyResource.en-US.resources" is "MyResource". +

+ + The namespace is also prefixed before the resource file name. + + + + + + The string representation of the assembly that contains the resource. + + + + + The . + + + + + Immutable placeholder class used for the value of a + object when it's a reference + to another object in this factory to be resolved at runtime. + + Rod Johnson + Rick Evans (.NET) + + + + Creates a new instance of the + + class. + + +

+ This does not mark this object as being a reference to + another object in any parent factory. +

+ + The name of the target object. + + + + Creates a new instance of the + + class. + + +

+ This variant constructor allows a client to specifiy whether or not + this object is a reference to another object in a parent factory. +

+ + The name of the target object. + + Whether this object is an explicit reference to an object in a + parent factory. + + + + + Returns a string representation of this instance. + + A string representation of this instance. + + + + Return the target object name. + + + + + Is this is an explicit reference to an object in the parent + factory? + + + if this is an explicit reference to an + object in the parent factory. + + + + + Simple factory object for shared instances. + + Juergen Hoeller + Simon White (.NET) + + + + Constructs a new instance of the target set. + + The new instance. + + + + Set the source . + + +

+ This value will be used to populate the + returned by this factory. +

+ + + + + Set the of the + implementation to use. + + +

+ The default is the . +

+ + + + + The of objects created by this factory. + + + Always returns the . + + + + + Configure all ISharedStateAware objects, delegating concrete handling to the list of . + + + + + Creates a new empty instance. + + + + + Creates a new preconfigured instance. + + + priority value affecting order of invocation of this processor. See interface. + + + + Iterates over configured list of s until + the first provider is found that
+ a) true == provider.CanProvideState( instance, name )
+ b) null != provider.GetSharedState( instance, name )
+ + + + + A NoOp for this processor + + + The new object instance. + + + The name of the object. + + + the original . + + + + + Return the order value of this object, where a higher value means greater in + terms of sorting. + + +

+ Normally starting with 0 or 1, with indicating + greatest. Same order values will result in arbitrary positions for the affected + objects. +

+

+ Higher value can be interpreted as lower priority, consequently the first object + has highest priority. +

+ + The order value. + + + + Get/Set the (already ordererd!) list of instances. + + + If this list is not set, the containing object factory will automatically + be scanned for instances. + + + + + Implementation of that + resolves variable name against special folders (as defined by + enumeration). + + Aleksandar Seovic + + + + Before requesting a variable resolution, a client should + ask, whether the source can resolve a particular variable name. + + the name of the variable to resolve + true if the variable can be resolved, false otherwise + + + + Resolves specified special folder to its full path. + + + The name of the special folder to resolve. Should be one of the values + defined by the enumeration. + + + The folder path if able to resolve, null otherwise. + + + + + + implementation that allows for convenient registration of custom + type aliases. + + + Type aliases can be used instead of fully qualified type names anywhere + a type name is expected in a Spring.NET configuration file. +

+ Because the + class implements the + + interface, instances of this class that have been exposed in the + scope of an + will + automatically be picked up by the application context and made + available to the IoC container whenever resolution of type aliases is required. +

+ + Mark Pollack + + + + + + Registers any type aliases. The supplied + is not used since type aliases + are registered with a global + + + The object factory. + + + In case of errors. + + + + + The type aliases to register. + + +

+ The has the + contains the alias name as the key and type as the value. + The key name can either be a string or an object, in which case + ToString() will be used to obtain the string name. + the value can be the fully qualified name of the type as a string or + an actual of the class that + being aliased. +

+ + + + + Holder for a typed value. + + +

+ Can be added to object definitions to explicitly specify + a target type for a value, + for example for collection + elements. +

+

+ This holder just stores the value and the target + . The actual conversion will be performed by + the surrounding object factory. +

+ + Juergen Hoeller + Rick Evans (.NET) + Bruno Baia (.NET) + + + + Creates a new instance of the + + class. + + + + + Initializes a new instance of the class. + + The value. + + + + Creates a new instance of the + + class. + + + The value that is to be converted. + + + The to convert to. + + + If the supplied is + . + + + + + Creates a new instance of the + + class. + + + The value that is to be converted. + + + The unresolved type to convert to. + + + If the supplied is a + or an empty string. + + + + + Determine the type to convert to, resolving it from a specified type name if necessary. + + The resolved type to convert to. + + + + The value that is to be converted. + + +

+ Obviously if the + + is the , no conversion + will actually be performed. +

+ + + + + The to convert to. + + + If the setter is supplied with a value. + + + + + The unresolved type to convert to. + + + If the setter is supplied with a value or an empty string. + + + + + Gets a value indicating whether this instance has target type. + + + true if this instance has target type; otherwise, false. + + + + + Provides methods for type-safe accessing s. + + Erich Eichinger + + + + Initialize a new instance of an + + The underlying to read values from. + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The expected format of the variable's value + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The expected format of the variable's value + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + A that contains the value of the specified variable + or , if returns null. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + A that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns an of 's type that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + An of 's type that contains the value of the specified variable + or , if returns null. + + + + + Returns an of 's type that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns null. + + If false, suppresses exceptions if the result + of cannot be parsed + and returns instead. + + An of 's type that contains the value of the specified variable + or , if cannot be parsed. + + + + + Returns a that contains the value of the specified variable. + + The name of the variable to be read. + The value to be returned if returns or . + + A that contains the value of the specified variable + or , if returns null. + + + + + Resolves placeholder values in one or more object definitions + + + The placeholder syntax follows the NAnt style: ${...}. + Placeholders values are resolved against a list of + s. In case of multiple definitions + for the same property placeholder name, the first one in the + list is used. + Variable substitution is performed on simple property values, + lists, dictionaries, sets, constructor + values, object type name, and object names in + runtime object references ( + ). + Furthermore, placeholder values can also cross-reference other + placeholders, in the manner of the following example where the + rootPath property is cross-referenced by the subPath + property. + + + + + + + + + + If a configurer cannot resolve a placeholder, and the value of the + + property is currently set to , an + + will be thrown. + + Mark Pollack + + + + The default placeholder prefix. + + + + + The default placeholder suffix. + + + + + Create a new instance without any variable sources + + + + + Create a new instance and initialize with the given variable source + + + + + + Create a new instance and initialize with the given list of variable sources + + + + + Modify the application context's internal object factory after its + standard initialization. + + The object factory used by the application context. + +

+ All object definitions will have been loaded, but no objects will have + been instantiated yet. This allows for overriding or adding properties + even to eager-initializing objects. +

+ + + In case of errors. + + + + + Apply the property replacement using the specified s for all + object in the supplied + . + + + The + used by the application context. + + + If an error occured. + + + + + Sets the list of s that will be used to resolve placeholder names. + + A list of s. + + + + Sets that will be used to resolve placeholder names. + + A instance. + + + + The placeholder prefix (the default is ${). + + + + + + The placeholder suffix (the default is }) + + + + + + Indicates whether unresolved placeholders should be ignored. + + + + + Return the order value of this object, where a higher value means greater in + terms of sorting. + + The order value. + + + + + Initializes a new instance of the Location class. + + + + + + + Initializes a new instance of the Location class. + + + + + + Thrown when an + encounters an internal error, and its definitions are invalid. + + +

+ An example of a situation when this exception would be thrown is + in the case of an XML document containing object definitions being + malformed. +

+ + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + Creates a new instance of the ObjectDefinitionStoreException class. + + + + + Creates a new instance of the ObjectDefinitionStoreException class. + + + A message about the exception. + + + + + Creates a new instance of the ObjectDefinitionStoreException class. + + + The description of the resource that the object definition came from + + + The name of the object that triggered the exception. + + + A message about the exception. + + + + + Initializes a new instance of the class. + + + The description of the resource that the object definition came from + + The detail message (used as exception message as-is) + The root cause. (may be null + + + + Creates a new instance of the ObjectDefinitionStoreException class. + + + The resource location (e.g. an XML object definition file) associated + with the offending object definition. + + + A message about the exception. + + + The name of the object that triggered the exception. + + + + + Creates a new instance of the ObjectDefinitionStoreException class. + + + The resource location (e.g. an XML object definition file) associated + with the offending object definition. + + + A message about the exception. + + + The name of the object that triggered the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the ObjectDefinitionStoreException class. + + + The description of the resource that the object definition came from + + + A message about the exception. + + + The name of the object that triggered the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the ObjectDefinitionStoreException class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the ObjectDefinitionStoreException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + The description of the resource associated with the object + + + + + The name of the object that trigger the exception. + + + + + The name of the object that triggered the exception (if any). + + + + + The description of the resource associated with the object (if any). + + + + + Initializes a new instance of the ObjectDefinitionParsingException class. + + + + + Creates a new instance of the ObjectDefinitionParsingException class. + + + + + Creates a new instance of the ObjectDefinitionParsingException class. + + + A message about the exception. + + + + + Creates a new instance of the ObjectDefinitionParsingException class. + + + The description of the resource that the object definition came from + + + The name of the object that triggered the exception. + + + A message about the exception. + + + + + Initializes a new instance of the class. + + + The description of the resource that the object definition came from + + The detail message (used as exception message as-is) + The root cause. (may be null + + + + Creates a new instance of the ObjectDefinitionParsingException class. + + + The resource location (e.g. an XML object definition file) associated + with the offending object definition. + + + A message about the exception. + + + The name of the object that triggered the exception. + + + + + Creates a new instance of the ObjectDefinitionParsingException class. + + + The resource location (e.g. an XML object definition file) associated + with the offending object definition. + + + A message about the exception. + + + The name of the object that triggered the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the ObjectDefinitionParsingException class. + + + The description of the resource that the object definition came from + + + A message about the exception. + + + The name of the object that triggered the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the ObjectDefinitionParsingException class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Initializes a new instance of the class. + + The message. + The location. + + + + Initializes a new instance of the Problem class. + + + + + + + + Context that gets passed along an object definition reading process, + encapsulating all relevant configuraiton as well as state. + + Rob Harrop + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + The resource. + + + + Gets the resource. + + The resource. + + + + Abstract superclass + that implements default object creation. + + +

+ Provides object creation, initialization and wiring, supporting + autowiring and constructor resolution. Handles runtime object + references, managed collections, and object destruction. +

+

+ The main template method to be implemented by subclasses is + , + used for autowiring by type. Note that this class does not implement object + definition registry capabilities + ( + does). +

+ + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + Abstract superclass for + implementations. + + +

+ This class provides singleton / prototype determination, singleton caching, + object definition aliasing, + handling, and object definition merging for child object definitions. +

+ + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + Marker object to be temporarily registered in the singleton cache, + while instantiating an object (in order to be able to detect circular references). + + + + + Used as value in hashtable that keeps track of singleton names currently in the + process of being created. Would not be necessary if we created a case insensitive implementation of + ISet. + + + + + The instance for this class. + + + + + Cache of singleton objects created by s: FactoryObject name -> product + + + + + Creates a new instance of the + class. + + +

+ This constructor implicitly creates an + + that treats the names of objects in this factory in a case-sensitive fashion. +

+

+ This is an class, and as such exposes no public constructors. +

+ + + + + Creates a new instance of the + class. + + +

+ This is an class, and as such exposes no public constructors. +

+ + + if the names of objects in this factory are to be treated in a + case-sensitive fashion. + + + + + Creates a new instance of the + class. + + +

+ This is an class, and as such exposes no public constructors. +

+ + + if the names of objects in this factory are to be treated in a + case-sensitive fashion. + + + Any parent object factory; may be . + + + + + Return an instance (possibly shared or independent) of the given object name. + + The name of the object to return. + + The the object may match. Can be an interface or + superclass of the actual class. For example, if the value is the + class, this method will succeed whatever the + class of the returned instance. + + + The arguments to use if creating a prototype using explicit arguments to + a factory method. If there is no factory method and the + supplied array is not , then + match the argument values by type and call the object's constructor. + + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + If the object is not of the required type. + + + If the supplied is . + + + + + + Apply the property values of the object definition with the supplied + to the supplied . + + +

+ The object definition can either define a fully self-contained object, + reusing it's property values, or just property values meant to be used + for existing object instances. +

+ + + The existing object that the property values for the named object will + be applied to. + + + The name of the object definition associated with the property values that are + to be applied. + + + In case of errors. + + + + + Apply the property values of the object definition with the supplied + to the supplied . + + +

+ The object definition can either define a fully self-contained object, + reusing it's property values, or just property values meant to be used + for existing object instances. +

+ + + The existing object that the property values for the named object will + be applied to. + + + The name of the object definition associated with the property values that are + to be applied. + + + An object definition that should be used to apply property values. + + + In case of errors. + + + + + Create an object instance for the given object definition. + + The name of the object. + + The object definition for the object that is to be instantiated. + + + The arguments to use if creating a prototype using explicit arguments to + a static factory method. It is invalid to use a non- arguments value + in any other case. + + + Whether eager caching of singletons is allowed... typically true for + singlton objects, but never true for inner object definitions. + + + Create instance only - suppress injecting dependencies yet. + + + A new instance of the object. + + + In case of errors. + + +

+ The object definition will already have been merged with the parent + definition in case of a child definition. +

+

+ All the other methods in this class invoke this method, although objects + may be cached after being instantiated by this method. All object + instantiation within this class is performed by this method. +

+ + + + + Destroy the target object. + + +

+ Must destroy objects that depend on the given object before the object itself, + nor throw an exception. +

+ + + The name of the object. + + + The target object instance to destroyed. + + + + + Does this object factory contain an object definition with the + supplied ? + + +

+ Does not consider any hierarchy this factory may participate in. + Invoked by + + when no cached singleton instance is found. +

+ + + The name of the object to look for. + + + if this object factory contains an object + definition with the supplied . + + + + + Adds the supplied (object) to this factory's + singleton cache. + + +

+ To be called for eager registration of singletons, e.g. to be able to + resolve circular references. +

+ + If a singleton has already been registered under the same name as + the supplied , then the old singleton will + be replaced. + + + The name of the object. + The singleton object. + + If the argument is + or consists wholly of whitespace characters; or if the + is . + + + + + Return the object name, stripping out the factory dereference prefix if + necessary, and resolving aliases to canonical names. + + + The transformed name of the object. + + + + + Ensures, that the given name is prefixed with + if it incidentially already starts with this prefix. This avoids troubles when dereferencing + the object name during + + + + + Determines whether the specified name is defined as an alias as opposed + to the name of an actual object definition. + + The object name to check. + + true if the specified name is alias; otherwise, false. + + + + + Return a , + even by traversing parent if the parameter is a child definition. + + + The name of the object. + + + Are ancestors to be included in the merge? + + +

+ Will ask the parent object factory if not found in this instance. +

+ + + A merged + with overridden properties. + + + + + Return a , + even by traversing parent if the parameter is a child definition. + + + A merged + with overridden properties. + + + + + Creates the root object definition. + + The template definition to base root definition on. + Root object definition. + + + + Register a new object definition with this registry. + + + The name of the object instance to register. + + + The definition of the object instance to register. + + + If the object definition is invalid. + + + + + + Return the registered + for the + given object, allowing access to its property values and constructor + argument values. + + The name of the object. + + The registered + . + + + If there is no object with the given name. + + + In the case of errors. + + + + + Return the registered + for the + given object, allowing access to its property values and constructor + argument values. + + The name of the object. + Whether to search parent object factories. + + The registered + . + + + If there is no object with the given name. + + + In the case of errors. + + + + + Gets the type for the given FactoryObject. + + The factory object instance to check. + the FactoryObject's object type + + + + Gets the object type for the given FactoryObject definition, as far as possible. + Only called if there is no singleton instance registered for the target object already. + + + The default implementation creates the FactoryObject via GetObject + to call its ObjectType property. Subclasses are encouraged to optimize + this, typically by just instantiating the FactoryObject but not populating it yet, + trying whether its ObjectType property already returns a type. + If no type found, a full FactoryObject creation as performed by this implementation + should be used as fallback. + + Name of the object. + The merged object definition for the object. + The type for the object if determinable, or null otherwise + + + + Predict the eventual object type (of the processed object instance) for the + specified object. + + + Does not need to handle FactoryObjects specifically, since it is only + supposed to operate on the raw object type. + This implementation is simplistic in that it is not able to + handle factory methods and InstantiationAwareBeanPostProcessors. + It only predicts the object type correctly for a standard object. + To be overridden in subclasses, applying more sophisticated type detection. + + Name of the object. + The merged object definition to determine the type for. May be null + The type of the object, or null if not predictable + + + + Get the object for the given object instance, either the object + instance itself or its created object in case of an + . + + + The name that may include the factory dereference prefix. + + The object instance. + + The singleton instance of the object. + + + + + Get the object for the given object instance, either the object + instance itself or its created object in case of an + . + + The object instance. + + The name that may include the factory dereference prefix (=the requested name). + + + The canonical object name + + the merged object definition + + The singleton instance of the object. + + + + + Obtain an object to expose from the given IFactoryObject. + + The IFactoryObject instance. + Name of the object. + The merged object definition. + The object obtained from the IFactoryObject + If IFactoryObject object creation failed. + + + + Post-process the given object that has been obtained from the FactoryObject. + The resulting object will be exposed for object references. + + The default implementation simply returns the given object + as-is. Subclasses may override this, for example, to apply + post-processors. + The instance obtained from the IFactoryObject. + Name of the object. + The object instance to expose + if any post-processing failed. + + + + Convenience method to pull an + from this factory. + + + The name of the factory object to be retrieved. If this name is not a valid + name, it will be converted + into one. + + + The associated with the + supplied . + + + + + Is the supplied a factory object dereference? + + + + + Determines whether the type of the given object definition matches the + specified target type. + + Allows for lazy load of the actual object type, provided that the + type match can be determined otherwise. + The default implementation simply delegates to the standard + ResolveObjectType method. Subclasses may override this to use + a differnt strategy. + + Name of the object (for error handling purposes). + The merged object definition to determine the type for. + Type to match against (never null). + + true if object definition matches tye specified target type; otherwise, false. + + if we failed to load the type." + + + + Resolves the type of the object for the specified object definition resolving + an object type name to a Type (if necessary) and storing the resolved Type + in the object definition for further use. + + The merged object definition to dertermine the type for. + Name of the object (for error handling purposes). + + + + + Is the object (definition) with the supplied an + ? + + The name of the object to be checked. + + the object (definition) with the supplied + an ? + + + + + Remove the object identified by the supplied + from this factory's singleton cache. + + + The name of the object that is to be removed from the singleton + cache. + + + If the argument is or + consists wholly of whitespace characters. + + + + + Return the names of objects in the singleton cache that match the given + object type (including subclasses). + + + The class or interface to match, or for all object names. + + +

+ Will not consider s + as the type of their created objects is not known before instantiation. +

+

+ Does not consider any hierarchy this factory may participate in. +

+ + + The names of objects in the singleton cache that match the given + object type (including subclasses), or an empty array if none. + + + + + Determines whether the object with the given name matches the specified type. + + More specifically, check whether a GetObject call for the given name + would return an object that is assignable to the specified target type. + Translates aliases back to the corresponding canonical bean name. + Will ask the parent factory if the bean cannot be found in this factory instance. + + The name of the object to query. + Type of the target to match against. + + true if the object type matches; otherwise, false + if it doesn't match or cannot be determined yet. + + Ff there is no object with the given name + + + + + Determines the of the object with the + supplied . + + +

+ More specifically, checks the of object that + would return. + For an , returns the + of object that the + creates. +

+

+ Please note that (prototype) objects created via a factory method or + objects are handled + slightly differently, in that we don't want to needlessly create + instances of such objects just to determine the + of object that they create. +

+ + The name of the object to query. + + The of the object or + if not determinable. + + + + + Determines the of the object defined + by the supplied object . + + +

+ This, the default, implementation returns + to indicate that the type cannot be determined. Subclasses are + encouraged to try to determine the actual return + here, matching their strategy of resolving + factory methods in the + Spring.Objects.Factory.Support.AbstractObjectFactory.CreateObject + implementation. +

+ + + The name associated with the supplied object . + + + The + that the is to be determined for. + + + The of the object defined by the supplied + object ; or if the + cannot be determined. + + + + + Returns the names of the objects in the singleton cache. + + +

+ Does not consider any hierarchy this factory may participate in. +

+ + The names of the objects in the singleton cache. + + + + Returns the number of objects in the singleton cache. + + +

+ Does not consider any hierarchy this factory may participate in. +

+ + The number of objects in the singleton cache. + + + + Destroys the named singleton object. + + +

+ Delegates to + + if a corresponding singleton instance is found. +

+ + + The name of the singleton object that is to be destroyed. + + + + + + Check the supplied merged object definition for any possible + validation errors. + + + The object definition to be checked for validation errors. + + + The name of the object associated with the supplied object definition. + + + The the object may match. Can be an interface or + superclass of the actual class. For example, if the value is the + class, this method will succeed whatever the + class of the returned instance. + + + The arguments to use if creating a prototype using explicit arguments to + a factory method. If there is no factory method and the + supplied array is not , then + match the argument values by type and call the object's constructor. + + + In the case of object validation errors. + + + + + Parent object factory, for object inheritance support + + + + + Dependency types to ignore on dependency check and autowire, as Set of + Type objects: for example, string. Default is none. + + + + + ObjectPostProcessors to apply in CreateObject + + + + + Indicates whether any IInstantiationAwareBeanPostProcessors have been registered + + + + + Indicates whether any IDestructionAwareBeanPostProcessors have been registered + + + + + Set of registered singletons, containing the bean names in registration order + + + + + Set that holds all inner objects created by this factory that implement the IDisposable + interface, to be destroyed on call to Dispose. + + + + + Determines whether the local object factory contains a bean of the given name, + ignoring object defined in ancestor contexts. + This is an alternative to ContainsObject, ignoring an object + of the given name from an ancestor object factory. + + The name of the object to query. + + true if objects with the specified name is defined in the local factory; otherwise, false. + + + + + Is this object a singleton? + + + + + + Determines whether the specified object name is prototype. That is, will GetObject + always return independent instances? + + The name of the object to query + + true if the specified object name will always deliver independent instances; otherwise, false. + + This method returning false does not clearly indicate a singleton object. + It indicated non-independent instances, which may correspond to a scoped object as + well. use the IsSingleton property to explicitly check for a shared + singleton instance. + Translates aliases back to the corresponding canonical object name. Will ask the + parent factory if the object can not be found in this factory instance. + + + if there is no object with the given name. + + + + Does this object factory or one of its parent factories contain an object with the given name? + + + This method scans the object factory hierarchy starting with the current factory instance upwards. + Use if you want to explicitely check just this object factory instance. + + . + + + + Return the aliases for the given object name, if defined. + + . + + + + Return an unconfigured(!) instance (possibly shared or independent) of the given object name. + + + + This method will only instantiate the requested object. It does NOT inject any dependencies! + + + + + Return an instance (possibly shared or independent) of the given object name. + + . + + + + Return an instance (possibly shared or independent) of the given object name. + + + + + + Return an instance (possibly shared or independent) of the given object name. + + +

+ This method allows an object factory to be used as a replacement for the + Singleton or Prototype design pattern. +

+

+ Note that callers should retain references to returned objects. There is no + guarantee that this method will be implemented to be efficient. For example, + it may be synchronized, or may need to run an RDBMS query. +

+

+ Will ask the parent factory if the object cannot be found in this factory + instance. +

+ + The name of the object to return. + + The arguments to use if creating a prototype using explicit arguments to + a static factory method. If there is no factory method and the + arguments are not null, then match the argument values by type and + call the object's constructor. + + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + If the supplied is . + + + + + Return an instance (possibly shared or independent) of the given object name, + optionally injecting dependencies. + + The name of the object to return. + + The the object may match. Can be an interface or + superclass of the actual class. For example, if the value is the + class, this method will succeed whatever the + class of the returned instance. + + + The arguments to use if creating a prototype using explicit arguments to + a factory method. If there is no factory method and the + supplied array is not , then + match the argument values by type and call the object's constructor. + + whether to inject dependencies or not. + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + If the object is not of the required type. + + + If the supplied is . + + + + + + + Checks, if the passed instance is of the required type. + + the name of the object + the actual instance + the type contract the given instance must adhere. + the object instance passed in via (for more fluent usage) + + if is null or not assignable to . + + + + + Creates a singleton instance for the specified object name and definition. + + + The object name (will be used as the key in the singleton cache key). + + The object definition. + + The arguments to use if creating a prototype using explicit arguments to + a static factory method. If there is no factory method and the + arguments are not null, then match the argument values by type and + call the object's constructor. + + The created object instance. + + + + Injects dependencies into the supplied instance + using the named object definition. + + + + + + Injects dependencies into the supplied instance + using the supplied . + + + + + + Destroy all cached singletons in this factory. + + + + + Ignore the given dependency type for autowiring + + . + + + + Determines whether the specified object name is currently in creation.. + + Name of the object. + + true if the specified object name is currently in creation; otherwise, false. + + + + + Add a new + that will get applied to objects created by this factory. + + + The + to register. + + . + + + + Given an object name, create an alias. + + . + + + + Register the given custom + for all properties of the given . + + . + + + + Register the given existing object as singleton in the object factory, + under the given object name. + + . + + + + Does this object factory contains a singleton instance with the + supplied ? + + + + + + Tries to find a cached object for the specified name. + + Teh object name to look for. + The cached object if found, otherwise. + + + + Determines whether the given object name is already in use within this factory, + i.e. whether there is a local object or alias registered under this name or + an inner object created with this name. + + Name of the object to check. + + true if is object name in use; otherwise, false. + + + + + Gets the singleton lock for a given object name. + + Name of the object. + lock object + + + + Returns, whether this factory treats object names case sensitive or not. + + + + + Gets the of + s + that will be applied to objects created by this factory. + + + + + Gets the set of classes that will be ignored for autowiring. + + +

+ The elements of this are + s. +

+ + + + + Returns, whether this object factory instance contains objects. + + + + + Returns, whether this object factory instance contains objects. + + + + + Gets the temporary object that is placed + into the singleton cache during object resolution. + + + + + Set that holds all inner objects created by this factory that implement the IDisposable + interface, to be destroyed on call to Dispose. + + + + + The parent object factory, or if there is none. + + + The parent object factory, or if there is none. + + + + + Return an instance (possibly shared or independent) of the given object name. + + . + + + + Returns the current number of registered + s. + + + The current number of registered + s. + + . + + + + Gets the names of singleton objects registered in this registry. + + The list of names as String array (never null). + + + Only checks already instantiated singletons; does not return names + for singleton bean definitions which have not been instantiated yet. + + + The main purpose of this method is to check manually registered singletons + . Can also be used to check which + singletons defined by an object definition have already been created. + + + + + + + + + Gets the number of singleton beans registered in this registry. + + The number of singleton objects. + + + Only checks already instantiated singletons; does not count + singleton object definitions which have not been instantiated yet. + + + The main purpose of this method is to check manually registered singletons + . Can also be used to count the number of + singletons defined by an object definition that have already been created. + + + + + + + + + Makes a distinction between sort order and object identity. + This is important when used with , since most + implementations assume Order == Identity + + + + + Handle the case when both objects have equal sort order priority. By default returns 0, + but may be overriden for handling special cases. + + The first object to compare. + The second object to compare. + + -1 if first object is less then second, 1 if it is greater, or 0 if they are equal. + + + + + The used during the invocation and + searching for of methods. + + + + + The instance for this class. + + + + + Creates a new instance of the + + class. + + +

+ This is an class, and as such exposes no public constructors. +

+ + Flag specifying whether to make this object factory case sensitive or not. + + + + Creates a new instance of the + + class. + + +

+ This is an class, and as such exposes no public constructors. +

+ + Flag specifying whether to make this object factory case sensitive or not. + The parent object factory, or if none. + + + + Predict the eventual object type (of the processed object instance) for the + specified object. + + Name of the object. + The merged object definition to determine the type for. May be null + + The type of the object, or null if not predictable + + + + + Determines the of the object defined + by the supplied object . + + + The name associated with the supplied object . + + + The + that the is to be determined for. + + + The of the object defined by the supplied + object ; or if the + cannot be determined. + + + + + Apply the property values of the object definition with the supplied + to the supplied . + + + The existing object that the property values for the named object will + be applied to. + + + The name of the object definition associated with the property values that are + to be applied. + + + + + Apply the property values of the object definition with the supplied + to the supplied . + + + The existing object that the property values for the named object will + be applied to. + + + The name of the object definition associated with the property values that are + to be applied. + + + An object definition that should be used to apply property values. + + + + + Apply any + s. + + +

+ The returned instance may be a wrapper around the original. +

+ + + The of the object that is to be + instantiated. + + + The name of the object that is to be instantiated. + + + An instance to use in place of the original instance. + + + In case of errors. + + + + + Apply the given property values, resolving any runtime references + to other objects in this object factory. + + + The object name passed for better exception information. + + + The definition of the named object. + + + The wrapping the target object. + + + The new property values. + + +

+ Must use deep copy, so that we don't permanently modify this property. +

+ + + + + Create the value resolver strategy to use for resolving raw property values + + + + + Return an array of object-type property names that are unsatisfied. + + +

+ These are probably unsatisfied references to other objects in the + factory. Does not include simple properties like primitives or + s. +

+ + + An array of object-type property names that are unsatisfied. + + + The definition of the named object. + + + The wrapping the target object. + + + + + Destroy all cached singletons in this factory. + + +

+ To be called on shutdown of a factory. +

+ + + + + Populate the object instance in the given + with the property values from the + object definition. + + + The name of the object. + + + The definition of the named object. + + + The wrapping the target object. + + + + + Wires up any exposed events in the object instance in the given + with any event handler + values from the . + + + The name of the object. + + + The definition of the named object. + + + The wrapping the target object. + + + + + Fills in any missing property values with references to + other objects in this factory if autowire is set to + . + + + The object name to be autowired by . + + + The definition of the named object to update through autowiring. + + + The wrapping the target object (and + from which we can rip out information concerning the object). + + + The property values to register wired objects with. + + + + + Defines "autowire by type" (object properties by type) behavior. + + +

+ This is like PicoContainer default, in which there must be exactly one object + of the property type in the object factory. This makes object factories simple + to configure for small namespaces, but doesn't work as well as standard Spring + behavior for bigger applications. +

+ + + The object name to be autowired by . + + + The definition of the named object to update through autowiring. + + + The wrapping the target object (and + from which we can rip out information concerning the object). + + + The property values to register wired objects with. + + + + + Ignore the given dependency type for autowiring + + + This will typically be used by application contexts to register + dependencies that are resolved in other ways, like IOjbectFactory through + IObjectFactoryAware or IApplicationContext through IApplicationContextAware. + By default, IObjectFactoryAware and IObjectName interfaces are ignored. + For further types to ignore, invoke this method for each type. + + . + + + + Create an object instance for the given object definition. + + The name of the object. + + The object definition for the object that is to be instantiated. + + + The arguments to use if creating a prototype using explicit arguments to + a static factory method. It is invalid to use a non- arguments value + in any other case. + + + Whether eager caching of singletons is allowed... typically true for + singlton objects, but never true for inner object definitions. + + + Suppress injecting dependencies yet. + + + A new instance of the object. + + + In case of errors. + + +

+ The object definition will already have been merged with the parent + definition in case of a child definition. +

+

+ All the other methods in this class invoke this method, although objects + may be cached after being instantiated by this method. All object + instantiation within this class is performed by this method. +

+ + + + + Add the created, but yet unpopulated singleton to the singleton cache + to be able to resolve circular references + + the name of the object to add to the cache. + the definition used to create and populated the object. + the raw object instance. + + Derived classes may override this method to select the right cache based on the object definition. + + + + + Remove the specified singleton from the singleton cache that has + been added before by a call to + + the name of the object to remove from the cache. + the definition used to create and populated the object. + + Derived classes may override this method to select the right cache based on the object definition. + + + + + Creates an instance from the passed in + using constructor + + The name of the object to create - used for error messages. + The describing the object to be created. + optional arguments to pass to the constructor + An wrapping the already instantiated object + + + + Instantiates the given object using its default constructor + + Name of the object. + The definition. + IObjectWrapper for the new instance + + + + Determines candidate constructors to use for the given object, checking all registered + + + Raw type of the object. + Name of the object. + the candidate constructors, or null if none specified + In case of errors + + + + + Instantiate an object instance using a named factory method. + + +

+ The method may be static, if the + parameter specifies a class, rather than a + instance, or an + instance variable on a factory object itself configured using Dependency + Injection. +

+

+ Implementation requires iterating over the static or instance methods + with the name specified in the supplied + (the method may be overloaded) and trying to match with the parameters. + We don't have the types attached to constructor args, so trial and error + is the only way to go here. +

+ + + The name associated with the supplied . + + + The definition describing the instance that is to be instantiated. + + + Any arguments to the factory method that is to be invoked. + + + The result of the factory method invocation (the instance). + + + + + "autowire constructor" (with constructor arguments by type) behaviour. + + The name of the object to autowire by type. + The object definition to update through autowiring. + The chosen candidate constructors. + The argument values passed in programmatically via the GetObject method, + or null if none (-> use constructor argument values from object definition) + + An for the new instance. + + + + Also applied if explicit constructor argument values are specified, + matching all remaining arguments with objects from the object factory. + + + This corresponds to constructor injection: in this mode, a Spring.NET + object factory is able to host components that expect constructor-based + dependency resolution. + + + + + + Perform a dependency check that all properties exposed have been set, if desired. + + +

+ Dependency checks can be objects (collaborating objects), simple (primitives + and ), or all (both). +

+ + + The name of the object. + + + The definition of the named object. + + + The wrapping the target object. + + + The property values to be checked. + + + If all of the checked dependencies were not satisfied. + + + + + Extract a filtered set of PropertyInfos from the given IObjectWrapper, excluding + ignored dependency types. + + The object wrapper the object was created with. + The filtered PropertyInfos + + + + Determine whether the given bean property is excluded from dependency checks. + This implementation excludes properties whose type matches an ignored dependency type + or which are defined by an ignored dependency interface. + + + + the of the object property + whether the object property is excluded + + + + Give an object a chance to react now all its properties are set, + and a chance to know about its owning object factory (this object). + + +

+ This means checking whether the object implements + and / or + , and invoking the + necessary callback(s) if it does. +

+

+ Custom init methods are resolved in a case-insensitive manner. +

+ + + The new object instance we may need to initialise. + + + The name the object has in the factory. Used for logging output. + + + The definition of the target object instance. + + + + + Invoke the specified custom destroy method on the given object. + + +

+ This implementation invokes a no-arg method if found, else checking + for a method with a single boolean argument (passing in "true", + assuming a "force" parameter), else logging an error. +

+

+ Can be overridden in subclasses for custom resolution of destroy + methods with arguments. +

+

+ Custom destroy methods are resolved in a case-insensitive manner. +

+ + + + + Destroy the target object. + + +

+ Must destroy objects that depend on the given object before the object itself. + Should not throw any exceptions. +

+ + + The name of the object. + + + The target object instance to destroyed. + + + + + Destroys all of the objects registered as dependant on the + object (definition) identified by the supplied . + + + The name of the root object (definition) that is itself being destroyed. + + + + + Resolve a reference to another object in the factory. + + + The name of the object that is having the value of one of its properties resolved. + + + The definition of the named object. + + + The name of the property the value of which is being resolved. + + + The runtime reference containing the value of the property. + + A reference to another object in the factory. + + + + Find object instances that match the required . + + +

+ Called by autowiring. If a subclass cannot obtain information about object + names by , a corresponding exception should be thrown. +

+ + + The of the objects to look up. + + + An of object names and object + instances that match the required , or + if none are found. + + + In case of errors. + + + + + Return the names of the objects that depend on the given object. + Called by DestroyObject, to be able to destroy depending objects first. + + + The name of the object to find depending objects for. + + + The array of names of depending objects, or the empty string array if none. + + + In case of errors. + + + + + Injects dependencies into the supplied instance + using the named object definition. + + + The object instance that is to be so configured. + + + The name of the object definition expressing the dependencies that are to + be injected into the supplied instance. + + + + + + Injects dependencies into the supplied instance + using the supplied . + + + The object instance that is to be so configured. + + + The name of the object definition expressing the dependencies that are to + be injected into the supplied instance. + + + An object definition that should be used to configure object. + + + + + + Configures object instance by injecting dependencies, satisfying Spring lifecycle + interfaces and applying object post-processors. + + + The name of the object definition expressing the dependencies that are to + be injected into the supplied instance. + + + An object definition that should be used to configure object. + + + A wrapped object instance that is to be so configured. + + + + + + Applies the PostProcessAfterInitialization callback of all + registered IObjectPostProcessors, giving them a chance to post-process + the object obtained from IFactoryObjects (for example, to auto-proxy them) + + The instance obtained from the IFactoryObject. + Name of the object. + The object instance to expose + if any post-processing failed. + + + + Create a new object instance of the given class with the specified + autowire strategy. + + + The of the object to instantiate. + + + The desired autowiring mode. + + + Whether to perform a dependency check for objects (not applicable to + autowiring a constructor, thus ignored there). + + The new object instance. + + If the wiring fails. + + + + + + Autowire the object properties of the given object instance by name or + . + + + The existing object instance. + + + The desired autowiring mode. + + + Whether to perform a dependency check for the object. + + + If the wiring fails. + + + If the supplied is not one of the + or + + values. + + + + + + Apply s + to the given existing object instance, invoking their + + methods. + + + The existing object instance. + + + The name of the object. + + + The object instance to use, either the original or a wrapped one. + + + If any post-processing failed. + + + + + + Apply s + to the given existing object instance, invoking their + + methods. + + + The existing object instance. + + + The name of the object. + + + The object instance to use, either the original or a wrapped one. + + + If any post-processing failed. + + + + + + Resolve the specified dependency against the objects defined in this factory. + + The descriptor for the dependency. + Name of the object which declares the present dependency. + A list that all names of autowired object (used for + resolving the present dependency) are supposed to be added to. + + the resolved object, or null if none found + + if dependency resolution failed + + + + Cache of filtered PropertyInfos: object Type -> PropertyInfo array + + + + + Dependency interfaces to ignore on dependency check and autowire, as Set of + Class objects. By default, only the IObjectFactoryAware and IObjectNameAware + interfaces are ignored. + + + + + The + implementation to be used to instantiate managed objects. + + + + + An + implementation that provides some convenience support for + derived classes. + + +

+ This class is reserved for internal use within the framework; it is + not intended to be used by application developers using Spring.NET. +

+ + Rick Evans + + + + Permits the (re)implementation of an arbitrary method on a Spring.NET + IoC container managed object. + + +

+ Encapsulates the notion of the Method-Injection form of Dependency + Injection. +

+

+ Methods that are dependency injected with implementations of this + interface may be (but need not be) , in which + case the container will create a concrete subclass of the + class prior to instantiation. +

+

+ Do not use this mechanism as a means of AOP. See the reference + manual for examples of appropriate usages of this interface. +

+ + Rod Johnson + Rick Evans (.NET) + + + + Reimplement the supplied . + + + The instance whose is to be + (re)implemented. + + + The method that is to be (re)implemented. + + The target method's arguments. + + The result of the (re)implementation of the method call. + + + + + Creates a new instance of the + + class. + + +

+ This is an class, and as such has no + publicly visible constructors. +

+ + + The object definition that is the target of the method replacement. + + + The enclosing IoC container with which the above + is associated. + + + If either of the supplied arguments is . + + + + + Is ; derived classes must supply an implementation. + + + The instance whose is to be + (re)implemented. + + + The method that is to be (re)implemented. + + The target method's arguments. + The result of the object lookup. + + + + Helper method for subclasses to retrieve the appropriate + for the + supplied . + + + The to use to retrieve + the appropriate + . + + + The appropriate + . + + + + + Helper method for subclasses to lookup an object from an enclosing + IoC container. + + + The name of the object that is to be looked up. + + + The named object. + + + + + Common base class for object definitions, factoring out common + functionality from + and + . + + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + Describes a configurable object instance, which has property values, + constructor argument values, and further information supplied by concrete + implementations. + + Rick Evans + + + + Return the property values to be applied to a new instance of the object. + + + + + Return the constructor argument values for this object. + + + + + The method overrides (if any) for this object. + + + The method overrides (if any) for this object; may be an + empty collection but is guaranteed not to be + . + + + + + Return the event handlers for any events exposed by this object. + + + + + Get or set the role hint for this object definition + + + + + Return a description of the resource that this object definition + came from (for the purpose of showing context in case of errors). + + + + + Is this object definition "abstract", i.e. not meant to be instantiated + itself but rather just serving as parent for concrete child object + definitions. + + + if this object definition is "abstract". + + + + + Returns the of the object definition (if any). + + + A resolved object . + + + If the of the object definition is not a + resolved or . + + + + + Returns the of the + of the object definition (if any). + + + + + Return whether this a Singleton, with a single, shared instance + returned on all calls. + + +

+ If , an object factory will apply the Prototype + design pattern, with each caller requesting an instance getting an + independent instance. How this is defined will depend on the + object factory implementation. Singletons are the commoner type. +

+ + + + + Is this object lazily initialized? + +

+ Only applicable to a singleton object. +

+

+ If , it will get instantiated on startup by object factories + that perform eager initialization of singletons. +

+ + + + + The autowire mode as specified in the object definition. + + +

+ This determines whether any automagical detection and setting of + object references will happen. Default is + , + which means there's no autowire. +

+ + + + + The dependency check code. + + + + + The object names that this object depends on. + + +

+ The object factory will guarantee that these objects get initialized + before. +

+

+ Note that dependencies are normally expressed through object properties + or constructor arguments. This property should just be necessary for + other kinds of dependencies like statics (*ugh*) or database + preparation on startup. +

+ + + + + The name of the initializer method. + + +

+ The default is , in which case there is no initializer method. +

+ + + + + Return the name of the destroy method. + + +

+ The default is , in which case there is no destroy method. +

+ + + + + The name of the factory method to use (if any). + + +

+ This method will be invoked with constructor arguments, or with no + arguments if none are specified. The static method will be invoked on + the specified . +

+ + + + + The name of the factory object to use (if any). + + + + + Gets or sets a value indicating whether this instance a candidate for getting autowired into some other + object. + + + true if this instance is autowire candidate; otherwise, false. + + + + + Creates a new instance of the + + class. + + +

+ This is an class, and as such exposes no + public constructors. +

+ + + + + Creates a new instance of the + + class. + + +

+ This is an class, and as such exposes no + public constructors. +

+ + + + + Creates a new instance of the + + class. + + + The object definition used to initialise the member fields of this + instance. + + +

+ This is an class, and as such exposes no + public constructors. +

+ + + + + Resolves the type of the object, resolving it from a specified + object type name if necessary. + + + A resolved instance. + + + If the type cannot be resolved. + + + + + Validate this object definition. + + + In the case of a validation failure. + + + + + Validates all + + + + + Validate the supplied . + + + The + to be validated. + + + + + Override settings in this object definition from the supplied + object definition. + + + The object definition used to override the member fields of this instance. + + + + + Returns a that represents the current + . + + + A that represents the current + . + + + + + The name of the parent definition of this object definition, if any. + + + + + The property values that are to be applied to the object + upon creation. + + +

+ Setting the value of this property to + will merely result in a new (and empty) + + collection being assigned to the property value. +

+ + + The property values (if any) for this object; may be an + empty collection but is guaranteed not to be + . + + + + + Does this definition have any + ? + + + if this definition has at least one + . + + + + + The constructor argument values for this object. + + +

+ Setting the value of this property to + will merely result in a new (and empty) + + collection being assigned. +

+ + + The constructor argument values (if any) for this object; may be an + empty collection but is guaranteed not to be + . + + + + + The event handler values for this object. + + +

+ Setting the value of this property to + will merely result in a new (and empty) + + collection being assigned. +

+ + + The event handler values (if any) for this object; may be an + empty collection but is guaranteed not to be + . + + + + + The method overrides (if any) for this object. + + +

+ Setting the value of this property to + will merely result in a new (and empty) + + collection being assigned to the property value. +

+ + + The method overrides (if any) for this object; may be an + empty collection but is guaranteed not to be + . + + + + + The name of the target scope for the object. + Defaults to "singleton", ootb alternative is "prototype". Extended object factories + might support further scopes. + + + + + Get or set the role hint for this object definition + + + + + Is this definition a singleton, with + a single, shared instance returned on all calls to an enclosing + container (typically an + or + ). + + +

+ If , an object factory will apply the + prototype design pattern, with each caller requesting an + instance getting an independent instance. How this is defined + will depend on the object factory implementation. singletons + are the commoner type. +

+ + + + + + Gets a value indicating whether this instance is prototype, with an independent instance + returned for each call. + + + true if this instance is prototype; otherwise, false. + + + + + Is this object lazily initialized? + +

+ Only applicable to a singleton object. +

+

+ If , it will get instantiated on startup + by object factories that perform eager initialization of + singletons. +

+ + + + + Is this object definition a "template", i.e. not meant to be instantiated + itself but rather just serving as an object definition for configuration + templates used by . + + + if this object definition is a "template". + + + + + Is this object definition "abstract", i.e. not meant to be + instantiated itself but rather just serving as a parent for concrete + child object definitions. + + + if this object definition is "abstract". + + + + + The of the object definition (if any). + + + A resolved object . + + + If the of the object definition is not a + resolved or . + + + + + + Is the of the object definition a resolved + ? + + + + + Returns the of the + of the object definition (if any). + + + + + A description of the resource that this object definition + came from (for the purpose of showing context in case of errors). + + + + + The autowire mode as specified in the object definition. + + +

+ This determines whether any automagical detection and setting of + object references will happen. The default is + , + which means that no autowiring will be performed. +

+ + + + + Gets the resolved autowire mode. + + +

+ This resolves + + to one of + + or + . +

+ + + + + The dependency checking mode. + + +

+ The default is + . +

+ + + + + The object names that this object depends on. + + +

+ The object factory will guarantee that these objects get initialized + before this object definition. +

+ + Dependencies are normally expressed through object properties + or constructor arguments. This property should just be necessary for + other kinds of dependencies such as statics (*ugh*) or database + preparation on startup. + + + + + + Gets or sets a value indicating whether this instance a candidate for getting autowired into some other + object. + + + true if this instance is autowire candidate; otherwise, false. + + + + + The name of the initializer method. + + +

+ The default value is the constant, + in which case there is no initializer method. +

+ + + + + Return the name of the destroy method. + + +

+ The default value is the constant, + in which case there is no destroy method. +

+ + + + + The name of the factory method to use (if any). + + +

+ This method will be invoked with constructor arguments, or with no + arguments if none are specified. The + method will be invoked on the specified + . +

+ + + + + The name of the factory object to use (if any). + + + + + Does this object definition have any constructor argument values? + + + if his object definition has at least one + element in it's + + property. + + + + + Abstract base class for object definition readers. + + +

+ Provides common properties like the object registry to work on. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + Simple interface for object definition readers. + + Juergen Hoeller + Rick Evans + + + + Load object definitions from the supplied . + + + The resource for the object definitions that are to be loaded. + + + The number of object definitions found + + + In the case of loading or parsing errors. + + + + + Load object definitions from the supplied . + + + The resources for the object definitions that are to be loaded. + + + The number of object definitions found + + + In the case of loading or parsing errors. + + + + + Loads the object definitions from the specified resource location. + + The resource location, to be loaded with the + IResourceLoader location . + + The number of object definitions found + + + + + Loads the object definitions from the specified resource locations. + + The the resource locations to be loaded with the + IResourceLoader of this object definition reader. + + The number of object definitions found + + + + + Gets the + + instance that this reader works on. + + + + + The against which any class names + will be resolved into instances. + + + + + The to use for anonymous + objects (wihtout explicit object name specified). + + + + + Gets the resource loader to use for resource locations. + + There is also a method + available for loading object definitions from a resource location. This is + a convenience to avoid explicit ResourceLoader handling. + The resource loader. + + + + The instance for this class (and derived classes). + + + + + Creates a new instance of the + + class. + + + The + instance that this reader works on. + + +

+ This is an class, and as such exposes no public constructors. +

+ + + + + Creates a new instance of the + + class. + + + The + instance that this reader works on. + + + The against which any class names + will be resolved into instances. + + +

+ This is an class, and as such exposes no public constructors. +

+ + + + + Load object definitions from the supplied . + + + The resource for the object definitions that are to be loaded. + + + The number of object definitions that were loaded. + + + In the case of loading or parsing errors. + + + + + Load object definitions from the supplied . + + + The resources for the object definitions that are to be loaded. + + + The number of object definitions found + + + In the case of loading or parsing errors. + + + + + Loads the object definitions from the specified resource location. + + The resource location, to be loaded with the + IResourceLoader location . + + The number of object definitions found + + + + + Loads the object definitions from the specified resource locations. + + The the resource locations to be loaded with the + IResourceLoader of this object definition reader. + + The number of object definitions found + + + + + Gets the + + instance that this reader works on. + + + + + The to use for anonymous + objects (wihtout explicit object name specified). + + + + + + The against which any class names + will be resolved into instances. + + + + + Gets or sets the resource loader to use for resource locations. + + The resource loader. + + + + Utility class that contains various methods useful for the implementation of + autowire-capable object factories. + + Juergen Hoeller + Rick Evans (.NET) + + + + Creates a new instance of the AutowireUtils class. + + +

+ This is a utility class, and as such has no publicly + visible constructors. +

+ + + + + Gets those s + that are applicable for autowiring the supplied . + + + The + (definition) that is being autowired by constructor. + + + The absolute minimum number of arguments that any returned constructor + must have. If this parameter is equal to zero (0), then all constructors + are valid (regardless of their argument count), including any default + constructor. + + + Those s + that are applicable for autowiring the supplied . + + + + + Determine a weight that represents the class hierarchy difference between types and + arguments. + + +

+ A direct match, i.e. type MyInteger -> arg of class MyInteger, does not increase + the result - all direct matches means weight zero (0). A match between the argument type + and a MyInteger instance argument would increase the weight by + 1, due to the superclass () being one (1) steps up in the + class hierarchy being the last one that still matches the required type. +

+

+ Therefore, with an argument of type , a + constructor taking a argument would be + preferred to a constructor taking an argument + which would be preferred to a constructor taking an + argument which would in turn be preferred + to a constructor taking an argument. +

+

+ All argument weights get accumulated. +

+ + + The argument s to match. + + The arguments to match. + The accumulated weight for all arguments. + + + + Algorithm that judges the match between the declared parameter types of a candidate method + and a specific list of arguments that this method is supposed to be invoked with. + + + Determines a weight that represents the class hierarchy difference between types and + arguments. The following a an example based on the Java class hierarchy for Integer. + A direct match, i.e. type Integer -> arg of class Integer, does not increase + the result - all direct matches means weight 0. A match between type Object and arg of + class Integer would increase the weight by 2, due to the superclass 2 steps up in the + hierarchy (i.e. Object) being the last one that still matches the required type Object. + Type Number and class Integer would increase the weight by 1 accordingly, due to the + superclass 1 step up the hierarchy (i.e. Number) still matching the required type Number. + Therefore, with an arg of type Integer, a constructor (Integer) would be preferred to a + constructor (Number) which would in turn be preferred to a constructor (Object). + All argument weights get accumulated. + + The param types. + The args. + + + + + Determines whether the given object property is excluded from dependency checks. + + The PropertyInfo of the object property. + + true if is excluded from dependency check; otherwise, false. + + + + + Sorts the supplied , preferring + public constructors and "greedy" ones (that have lots of arguments). + + +

+ The result will contain public constructors first, with a decreasing number + of arguments, then non-public constructors, again with a decreasing number + of arguments. +

+ + + The array to be sorted. + + + + + Determines whether the setter property is defined in any of the given interfaces. + + The PropertyInfo of the object property + The ISet of interfaces. + + true if setter property is defined in interface; otherwise, false. + + + + + Creates the autowire candidate resolver. + + A SimpleAutowireCandidateResolver + + + + Returns the list of that are not satisfied by . + + the filtered list. Is never null + + + + Object definition for definitions that inherit settings from their + parent (object definition). + + +

+ Will use the + of the parent object definition if none is specified, but can also + override it. In the latter case, the child's + + must be compatible with the parent, i.e. accept the parent's property values + and constructor argument values (if any). +

+

+ A will + inherit all of the , + , and + from it's parent + object definition, with the option to add new values. If the + , + , + and / or + + properties are specified, they will override the corresponding parent settings. +

+

+ The remaining settings will always be taken from the child definition: + , + , + , + , + and + +

+ + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + + Creates a new instance of the + + class. + + + The name of the parent object. + + + + + Creates a new instance of the + + class. + + + The name of the parent object. + + + The additional property values (if any) of the child. + + + + + Creates a new instance of the + + class. + + + The name of the parent object. + + + The + to be applied to a new instance of the object. + + + The additional property values (if any) of the child. + + + + + Creates a new instance of the + + class. + + + The name of the parent object. + + + The class of the object to instantiate. + + + The + to be applied to a new instance of the object. + + + The additional property values (if any) of the child. + + + + + Creates a new instance of the + + class. + + + The name of the parent object. + + + The of the object to + instantiate. + + + The + to be applied to a new instance of the object. + + + The additional property values (if any) of the child. + + + + + Validate this object definition. + + +

+ A common cause of validation failures is a missing value for the + + property; by + their very nature require that the + + be set. +

+ + + In the case of a validation failure. + + + + + A that represents the current + . + + + A that represents the current + . + + + + + The name of the parent object definition. + + + This value is required. + + + The name of the parent object definition. + + + + + Helper class for resolving constructors and factory methods. + Performs constructor resolution through argument matching. + + + Operates on a and an . + Used by . + + Juergen Hoeller + Mark Pollack + + + + Initializes a new instance of the class for the given factory + and instantiation strategy. + + The object factory to work with. + The object factory as IAutowireCapableObjectFactory. + The instantiation strategy for creating objects. + the resolver to resolve property value placeholders if any + + + + "autowire constructor" (with constructor arguments by type) behavior. + Also applied if explicit constructor argument values are specified, + matching all remaining arguments with objects from the object factory. + + + This corresponds to constructor injection: In this mode, a Spring + object factory is able to host components that expect constructor-based + dependency resolution. + + Name of the object. + The merged object definition for the object. + The chosen chosen candidate constructors (or null if none). + The explicit argument values passed in programmatically via the getBean method, + or null if none (-> use constructor argument values from object definition) + An IObjectWrapper for the new instance + + + + Gets the constructor instantiation info given the object definition. + + Name of the object. + The RootObjectDefinition + The explicitly chosen ctors. + The explicit chose ctor args. + A ConstructorInstantiationInfo containg the specified constructor in the RootObjectDefinition or + one based on type matching. + + + + Instantiate an object instance using a named factory method. + + +

+ The method may be static, if the + parameter specifies a class, rather than a + instance, or an + instance variable on a factory object itself configured using Dependency + Injection. +

+

+ Implementation requires iterating over the static or instance methods + with the name specified in the supplied + (the method may be overloaded) and trying to match with the parameters. + We don't have the types attached to constructor args, so trial and error + is the only way to go here. +

+ + + The name associated with the supplied . + + + The definition describing the instance that is to be instantiated. + + + Any arguments to the factory method that is to be invoked. + + + The result of the factory method invocation (the instance). + + + + + Create an array of arguments to invoke a constructor or static factory method, + given the resolved constructor arguments values. + + When return value is null the out parameter UnsatisfiedDependencyExceptionData will contain + information for use in throwing a UnsatisfiedDependencyException by the caller. This avoids using + exceptions for flow control as in the original implementation. + + + + Resolves the + of the supplied . + + The name of the object that is being resolved by this factory. + The rod. + The wrapper. + The cargs. + Where the resolved constructor arguments will be placed. + + The minimum number of arguments that any constructor for the supplied + must have. + + +

+ 'Resolve' can be taken to mean that all of the s + constructor arguments is resolved into a concrete object that can be plugged + into one of the s constructors. Runtime object + references to other objects in this (or a parent) factory are resolved, + type conversion is performed, etc. +

+

+ These resolved values are plugged into the supplied + object, because we wouldn't want to touch + the s constructor arguments in case it (or any of + its constructor arguments) is a prototype object definition. +

+

+ This method is also used for handling invocations of static factory methods. +

+ + + + + Returns an array of all of those + methods exposed on the + that match the supplied criteria. + + + Methods that have this name (can be in the form of a regular expression). + + + Methods that have exactly this many arguments. + + + Methods that are static / instance. + + + The on which the methods (if any) are to be found. + + + An array of all of those + methods exposed on the + that match the supplied criteria. + + + + + Concrete implementation of the + and + + interfaces. + + +

+ This class is a full-fledged object factory based on object definitions + that is usable straight out of the box. +

+

+ Can be used as an object factory in and of itself, or as a superclass + for custom object factory implementations. Note that readers for + specific object definition formats are typically implemented separately + rather than as object factory subclasses. +

+

+ For an alternative implementation of the + interface, + have a look at the + + class, which manages existing object instances rather than creating new + ones based on object definitions. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + Flag specifying whether to make this object factory case sensitive or not. + + + + Creates a new instance of the + class. + + The parent object factory. + + + + Creates a new instance of the + class. + + Flag specifying whether to make this object factory case sensitive or not. + The parent object factory. + + + + Find object instances that match the . + + +

+ Called by autowiring. If a subclass cannot obtain information about object + names by , a corresponding exception should be thrown. +

+ + + The type of the objects to look up. + + + An of object names and object + instances that match the , or + if none is found. + + + In case of errors. + + + + + Return the names of the objects that depend on the given object. + + +

+ Called by the + + so that dependant objects are able to be disposed of first. +

+ + + The name of the object to find depending objects for. + + + The array of names of depending objects, or the empty string array if none. + + + In case of errors. + + + + + Check whether the specified object matches the supplied . + + The name of the object to check. + + The to check for. + + + if the object matches the supplied , + or if the supplied is . + + + + + The instance for this class. + + + + + Whether to allow re-registration of a different definition with the + same name. + + + + + The mapping of object definition objects, keyed by object name. + + + + + List of object definition names, in registration order. + + + + + Resolver to use for checking if an object definition is an autowire candidate + + + + + IDictionary from dependency type to corresponding autowired value + + + + + Check if this registry contains a object definition with the given + name. + + + The name of the object to look for. + + + if this object factory contains an object + definition with the given name. + + + + + + Register a new object definition with this registry. + + + The name of the object instance to register. + + + The definition of the object instance to register. + + + If the object definition is invalid. + + + + + + Ensure that all non-lazy-init singletons are instantiated, also + considering s. + + + If one of the singleton objects could not be created. + + + + + + Register a special dependency type with corresponding autowired value. + + Type of the dependency to register. + This will typically be a base interface such as IObjectFactory, with extensions of it resolved + as well if declared as an autowiring dependency (e.g. IListableBeanFactory), + as long as the given value actually implements the extended interface. + The autowired value. This may also be an + implementation o the interface, + which allows for lazy resolution of the actual target value. + + This is intended for factory/context references that are supposed + to be autowirable but are not defined as objects in the factory: + e.g. a dependency of type ApplicationContext resolved to the + ApplicationContext instance that the object is living in. + + Note there are no such default types registered in a plain IObjectFactory, + not even for the IObjectFactory interface itself. + + + + + + Return the registered + for the + given object, allowing access to its property values and constructor + argument values. + + The name of the object. + + The registered , + or null, if specified object definitions does not exist. + + + If is null or empty string. + + + + + + Return the registered + for the + given object, allowing access to its property values and constructor + argument values. + + The name of the object. + Whether to search parent object factories. + + The registered , + or null, if specified object definitions does not exist. + + + If is null or empty string. + + + + + + Return the names of all objects defined in this factory. + + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + + Return the names of objects matching the given + (including subclasses), judging from the object definitions. + + + The (class or interface) to match, or + for all object names. + + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + + Return the names of objects matching the given + (including subclasses), judging from the object definitions. + + + The (class or interface) to match, or + for all object names. + + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + + Return the names of objects matching the given + (including subclasses), judging from the object definitions. + + + The (class or interface) to match, or + for all object names. + + + Whether to include prototype objects too or just singletons (also applies to + s). + + + Whether to include s too + or just normal objects. + + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + + Return the object instances that match the given object + (including subclasses), judging from either object + definitions or the value of + in the case of + s. + + + The (class or interface) to match. + + + A of the matching objects, + containing the object names as keys and the corresponding object instances + as values. + + + If the objects could not be created. + + + + + + Return the object instances that match the given object + (including subclasses). + + + The (class or interface) to match. + + + Whether to include prototype objects too or just singletons (also applies to + s). + + + Whether to include s too + or just normal objects. + + + An of the matching objects, + containing the object names as keys and the corresponding object instances + as values. + + + If any of the objects could not be created. + + + + + + Return the object instances that match the given object + (including subclasses). + + + The (class or interface) to match. + + + Whether to include prototype objects too or just singletons (also applies to + s). + + + Whether to include s too + or just normal objects. + + + An of the matching objects, + containing the object names as keys and the corresponding object instances + as values. + + + If any of the objects could not be created. + + + + + + Check whether the specified bean would need to be eagerly initialized + in order to determine its type. + + a factory-bean reference that the bean definition defines a factory method for + whether eager initialization is necessary + + + + Check whether the given bean is defined as a . + + the name of the object + the corresponding object definition + + + + Resolve the specified dependency against the objects defined in this factory. + + The descriptor for the dependency. + Name of the object which declares the present dependency. + A list that all names of autowired object (used for + resolving the present dependency) are supposed to be added to. + + the resolved object, or null if none found + + if dependency resolution failed + + + + Raises the no such object definition exception for an unresolvable dependency + + The type. + The dependency description. + The descriptor. + + + + Determines whether the specified object qualifies as an autowire candidate, + to be injected into other beans which declare a dependency of matching type. + This method checks ancestor factories as well. + + Name of the object to check. + The descriptor of the dependency to resolve. + + true if the object should be considered as an autowire candidate; otherwise, false. + + if there is no object with the given name. + + + + Determine whether the specified object definition qualifies as an autowire candidate, + to be injected into other beans which declare a dependency of matching type. + + Name of the object definition to check. + The merged object definiton to check. + The descriptor of the dependency to resolve. + + true if the object should be considered as an autowire candidate; otherwise, false. + + + + + Should object definitions registered under the same name as an + existing object definition be allowed? + + +

+ If , then the new object definition will + replace (override) the existing object definition. If + , an exception will be thrown when + an attempt is made to register an object definition under the same + name as an already existing object definition. +

+

+ The default is . +

+ + + is the registration of an object definition + under the same name as an existing object definition is allowed. + + + + + Get or set custom autowire candidate resolver for this IObjectFactory to use + when deciding whether a bean definition should be considered as a + candidate for autowiring. Never null + + + + + Return the number of objects defined in this registry. + + + The number of objects defined in this registry. + + + + + + Default implementation of the + + interface. + + +

+ Does not support per + loading. +

+ + Aleksandar Seovic + + + + Central interface for factories that can create + + instances. + + +

+ Allows for replaceable object definition factories using the Strategy + pattern. +

+ + Aleksandar Seovic + + + + Factory style method for getting concrete + + instances. + + + The FullName of the of the defined object. + + The name of the parent object definition (if any). + + The against which any class names + will be resolved into instances. It can be null to register the + object class just by name. + + + An + + instance. + + + + + Factory style method for getting concrete + + instances. + + /// If no parent is specified, a RootObjectDefinition is created, otherwise a + ChildObjectDefinition. + The of the defined object. + The name of the parent object definition (if any). + The against which any class names + will be resolved into instances. + + An + + instance. + + + + + Default implementation of the interface, deleagting to + 's GenerateObjectName. + + Note that this implementation is only able to handle + subclasses such as + and + + Juergen Hoeller + Mark Pollack (.NET) + + + + Strategy interface for generating object names for object definitions + + Juergen Hoeller + Mark Pollack (.NET) + + + + Generates an object name for the given object definition. + + The object definition to generate a name for. + The object definitions registry that the given definition is + supposed to be registerd with + the generated object name + + + + Generates an object name for the given object definition. + + The object definition to generate a name for. + The object definitions registry that the given definition is + supposed to be registerd with + the generated object name + + + + An + implementation that delegates to an + that is + obtained as the result of a lookup in an associated IoC container. + + +

+ This class is reserved for internal use within the framework; it is + not intended to be used by application developers using Spring.NET. +

+ + Rick Evans + + + + Creates a new instance of the + + class. + + + The object definition that is the target of the method replacement. + + + The enclosing IoC container with which the above + is associated. + + + If either of the supplied arguments is . + + + + + Reimplements the supplied by delegating to + another + looked up in an enclosing IoC container. + + + The instance whose is to be + (re)implemented. + + + The method that is to be (re)implemented. + + The target method's arguments. + + The result of the delegated call to the looked up + . + + + + + The various modes of dependency checking. + + Rick Evans (.NET) + + + + DO not do any dependency checking. + + + + + Check object references. + + + + + Just check primitive (string, int, etc) values. + + + + + Check everything. + + + + + GenericObjectDefinition is a one-stop shop for standard object definition purposes. + Like any object definition, it allows for specifying a class plus optionally + constructor argument values and property values. Additionally, deriving from a + parent bean definition can be flexibly configured through the "parentName" property. + + In general, use this class for the purpose of + registering user-visible object definitions (which a post-processor might operate on, + potentially even reconfiguring the parent name). + Use / + where parent/child relationships happen to be pre-determined. + + + + Juergen Hoeller + Erich Eichinger + + + + Creates a new to be configured through its + object properties and configuration methods. + + + + + Creates a new as deep copy of the given + object definition. + + the original object definition to copy from + + + + Returns a representation of this + for debugging purposes. + + + + + The name of the parent object definition. + + + This value is required. + + + The name of the parent object definition. + + + + + Strategy interface for determining whether a specific object definition + qualifies as an autowire candidate for a specific dependency. + + Mark Fisher + Juergen hoeller + Mark Pollack (.NET) + + + + Determines whether the given object definition qualifies as an + autowire candidate for the given dependency. + + The object definition including object name and aliases. + The descriptor for the target method parameter or field. + + true if the object definition qualifies as autowire candidate; otherwise, false. + + + + + Responsible for creating instances corresponding to a + . + + Rod Johnson + Rick Evans (.NET) + + + + Instantiate an instance of the object described by the supplied + from the supplied . + + + The definition of the object that is to be instantiated. + + + The name associated with the object definition. The name can be the null + or zero length string if we're autowiring an object that doesn't belong + to the supplied . + + + The owning + + + An instance of the object described by the supplied + from the supplied . + + + + + Instantiate an instance of the object described by the supplied + from the supplied . + + + The definition of the object that is to be instantiated. + + + The name associated with the object definition. The name can be the null + or zero length string if we're autowiring an object that doesn't belong + to the supplied . + + + The owning + + + The to be used to instantiate + the object. + + + Any arguments to the supplied . May be null. + + + An instance of the object described by the supplied + from the supplied . + + + + + Instantiate an instance of the object described by the supplied + from the supplied . + + + The definition of the object that is to be instantiated. + + + The name associated with the object definition. The name can be the null + or zero length string if we're autowiring an object that doesn't belong + to the supplied . + + + The owning + + + The to be used to get the object. + + + Any arguments to the supplied . May be null. + + + An instance of the object described by the supplied + from the supplied . + + + + + Represents an override of a method that looks up an object in the same IoC context. + + +

+ Methods eligible for lookup override must not have arguments. +

+ + Rod Johnson + Rick Evans (.NET) + + + + Represents the override of a method on a managed object by the IoC container. + + +

+ Note that the override mechanism is not intended as a generic means of + inserting crosscutting code: use AOP for that. +

+ + Rod Johnson + Rick Evans (.NET) + + + + Creates a new instance of the + class. + + +

+ This is an class, and as such exposes no + public constructors. +

+ + + The name of the method that is to be overridden. + + + If the supplied is or + contains only whitespace character(s). + + + + + Does this + match the supplied ? + + +

+ By 'match' one means does this particular + + instance apply to the supplied ? +

+

+ This allows for argument list checking as well as method name checking. +

+ + The method to be checked. + + if this override matches the supplied + . + + + + + The name of the method that is to be overridden. + + + + + Is the method that is ot be injected + () + to be considered as overloaded? + + +

+ If (the default), then argument type matching + will be performed (because one would not want to override the wrong + method). +

+

+ Setting the value of this property to can be used + to optimize runtime performance (ever so slightly). +

+ + + + + Creates a new instance of the + class. + + +

+ Methods eligible for lookup override must not have arguments. +

+ + + The name of the method that is to be overridden. + + + The name of the object in the current IoC context that the + dependency injected method must return. + + + If either of the supplied arguments is or + contains only whitespace character(s). + + + + + Does this + match the supplied ? + + The method to be checked. + + if this override matches the supplied . + + + If the supplied is . + + + + + A that represents the current + . + + + A that represents the current + . + + + + + The name of the object in the current IoC context that the + dependency injected method must return. + + + + + An + implementation that simply returns the result of a lookup in an + associated IoC container. + + +

+ This class is Spring.NET's implementation of Dependency Lookup via + Method Injection. +

+

+ This class is reserved for internal use within the framework; it is + not intended to be used by application developers using Spring.NET. +

+ + Rick Evans + + + + Creates a new instance of the + class. + + + The object definition that is the target of the method replacement. + + + The enclosing IoC container with which the above + is associated. + + + If either of the supplied arguments is . + + + + + Reimplements the supplied by returning the + result of an object lookup in an enclosing IoC container. + + + The instance whose is to be + (re)implemented. + + + The method that is to be (re)implemented. + + The target method's arguments. + + The result of the object lookup. + + + + + An + implementation that supports method injection. + + +

+ Classes that want to take advantage of method injection must meet some + stringent criteria. Every method that is to be method injected + must be defined as either or + . An + will be thrown if these criteria are not met. +

+ + Rick Evans + + + + Simple object instantiation strategy for use in + implementations. + + +

+ Does not support method injection, although it provides hooks for subclasses + to override to add method injection support, for example by overriding methods. +

+ + Rod Johnson + Rick Evans (.NET) + + + + + The shared instance for this class (and derived classes). + + + + + Instantiate an instance of the object described by the supplied + from the supplied . + + + The definition of the object that is to be instantiated. + + + The name associated with the object definition. The name can be the null + or zero length string if we're autowiring an object that doesn't belong + to the supplied . + + + The owning + + + An instance of the object described by the supplied + from the supplied . + + + + + Gets the zero arg ConstructorInfo object, if the type offers such functionality. + + The type. + Zero argument ConstructorInfo + + If the type does not have a zero-arg constructor. + + + + + Instantiate an instance of the object described by the supplied + from the supplied . + + + The definition of the object that is to be instantiated. + + + The name associated with the object definition. The name can be the null + or zero length string if we're autowiring an object that doesn't belong + to the supplied . + + + The owning + + + The to be used to instantiate + the object. + + + Any arguments to the supplied . May be null. + + + An instance of the object described by the supplied + from the supplied . + + + + + Instantiate an instance of the object described by the supplied + from the supplied . + + + The definition of the object that is to be instantiated. + + + The name associated with the object definition. The name can be the null + or zero length string if we're autowiring an object that doesn't belong + to the supplied . + + + The owning + + + The to be used to get the object. + + + Any arguments to the supplied . May be null. + + + An instance of the object described by the supplied + from the supplied . + + + + + Instantiate an instance of the object described by the supplied + from the supplied , + injecting methods as appropriate. + + +

+ The default implementation of this method is to throw a + . +

+

+ Derived classes can override this method if they can instantiate an object + with the Method Injection specified in the supplied + . Instantiation should use a no-arg constructor. +

+ + + The definition of the object that is to be instantiated. + + + The name associated with the object definition. The name can be a + or zero length string if we're autowiring an object that + doesn't belong to the supplied . + + + The owning + + + An instance of the object described by the supplied + from the supplied . + + + + + Instantiate an instance of the object described by the supplied + from the supplied , + injecting methods as appropriate. + + +

+ The default implementation of this method is to throw a + . +

+

+ Derived classes can override this method if they can instantiate an object + with the Method Injection specified in the supplied + . Instantiation should use the supplied + and attendant . +

+ + + The definition of the object that is to be instantiated. + + + The name associated with the object definition. The name can be the null + or zero length string if we're autowiring an object that doesn't belong + to the supplied . + + + The owning + + + The to be used to instantiate + the object. + + + Any arguments to the supplied . May be null. + + + An instance of the object described by the supplied + from the supplied . + + + + + The name of the dynamic assembly that holds dynamically created code + + + + + A cache of generated instances, keyed on + the object name for which the was generated. + + + + + Instantiate an instance of the object described by the supplied + from the supplied , + injecting methods as appropriate. + + + The definition of the object that is to be instantiated. + + + The name associated with the object definition. The name can be the + or zero length string if we're autowiring an + object that doesn't belong to the supplied + . + + + The owning + + + An instance of the object described by the supplied + from the supplied . + + + + + + Instantiate an instance of the object described by the supplied + from the supplied , + injecting methods as appropriate. + + + The definition of the object that is to be instantiated. + + + The name associated with the object definition. The name can be the + or zero length string if we're autowiring an + object that doesn't belong to the supplied + . + + + The owning + + + The to be used to instantiate + the object. + + + Any arguments to the supplied . May be null. + + + An instance of the object described by the supplied + from the supplied . + + + + + + Instantiate an instance of the object described by the supplied + from the supplied , + injecting methods as appropriate. + + +

+ This method dynamically generates a subclass that supports method + injection for the supplied . It then + instantiates an new instance of said type using the constructor + identified by the supplied , + passing the supplied to said + constructor. It then manually injects (generic) method replacement + and method lookup instances (of + ) into + the new instance: those methods that are 'method-injected' will + then delegate to the approriate + + instance to effect the actual method injection. +

+ + + The definition of the object that is to be instantiated. + + + The name associated with the object definition. The name can be the + or zero length string if we're autowiring an + object that doesn't belong to the supplied + . + + + The owning + + + The parameter s to use to find the + appropriate constructor to invoke. + + + The aguments that are to be passed to the appropriate constructor + when the object is being instantiated. + + + A new instance of the defined by the + supplied . + + + + + A factory that generates subclasses of those + classes that have been configured for the Method-Injection form of + Dependency Injection. + + +

+ This class is designed as for one-shot usage; i.e. it must + be used to generate exactly one method injected subclass and + then discarded (it maintains state in instance fields). +

+ + + + + The name of the generated + property (for method replacement). + + +

+ Exists so that clients of this class can use this name to set properties reflectively + on the dynamically generated subclass. +

+ + + + + The name of the generated + property (for method lookup). + + +

+ Exists so that clients of this class can use this name to set properties reflectively + on the dynamically generated subclass. +

+ + + + + Creates a new instance of the + class. + + + The in which + the generated is to be defined. + + + The object definition that is the target of the method injection. + + + If either of the supplied arguments is . + + + + + Builds a suitable for Method-Injection. + + + A suitable for Method-Injection. + + + + + Defines overrides for those methods that are configured with an appropriate + . + + + The overarching that is defining + the generated . + + + + + Override the supplied with the logic + encapsulated by the + + defined by the supplied . + + + The builder for the subclass that is being generated. + + + The method on the superclass that is to be overridden. + + + The field defining the + + that the overridden method will delegate to to do the 'actual' + method injection logic. + + + + + Generates the MSIL for actually returning a return value if the + supplied is not + . + + + The definition of the return value; if , it + means that no return value is to required (a void + return type). + + + The to emit + the MSIL to. + + + + + Generates the MSIL for a return value if the supplied + returns a value. + + + The method to be checked. + + + The to emit + the MSIL to. + + + The return value, or if the method does not + return a value (has a void return type). + + + + + Pushes (sets up) the arguments for a call to the + + method of an appropriate + . + + + The parameters to the original method (will be bundled + up into a generic object[] and passed as the third + argument to the + + invocation. + + + The to emit + the MSIL to. + + + + + Simply generates the IL for a write only property for the + . + + + The in which the property is defined. + + + The name of the (to be) generated property. + + + The (instance) field that the property is to 'set'. + + + + + A collection (with set semantics) of method overrides, determining which, if any, + methods on a managed object the Spring.NET IoC container will override at runtime. + + Rod Johnson + Rick Evans + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + +

+ Deep copy constructoe. +

+ + + The instance supplying initial overrides for this new instance. + + + + + Copy all given method overrides into this object. + + + The overrides to be copied into this object. + + + + + Adds the supplied to the overrides contained + within this instance. + + + The to be + added. + + + + + Adds the supplied to the overloaded method names + contained within this instance. + + + The overloaded method name to be added. + + + + + Returns true if the supplied is present within + the overloaded method names contained within this instance. + + + The overloaded method name to be checked. + + + True if the supplied is present within + the overloaded method names contained within this instance. + + + + + Return the override for the given method, if any. + + + The method to check for overrides for. + + + the override for the given method, if any. + + + + + Returns an that can iterate + through a collection. + + +

+ The returned is the + exposed by the + + property. +

+ + + An that can iterate through a + collection. + + + + + The collection of method overrides. + + + + + Returns true if this instance contains no overrides. + + + + + Programmatic means of constructing a using the builder pattern. Intended primarily + for use when implementing custom namespace parsers. + + Set methods are used instead of properties, so that chaining of methods can be used to create + 'one-liner'definitions that set multiple properties at one. + Rod Johnson + Rob Harrop + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class, private + to force use of factory methods. + + + + + Creates a new used to construct a . + + + + + Creates a new used to construct a . + + the of the object that the definition is being created for + + + + Creates a new used to construct a . + + the name of the of the object that the definition is being created for + + + + Create a new ObjectDefinitionBuilder used to construct a root object definition. + + The object definition factory. + The type name of the object. + A new ObjectDefinitionBuilder instance. + + + + Create a new ObjectDefinitionBuilder used to construct a root object definition. + + The object definition factory. + Name of the object type. + Name of the factory method. + A new ObjectDefinitionBuilder instance. + + + + Create a new ObjectDefinitionBuilder used to construct a root object definition. + + The object definition factory. + Type of the object. + A new ObjectDefinitionBuilder instance. + + + + Create a new ObjectDefinitionBuilder used to construct a root object definition. + + The object definition factory. + Type of the object. + Name of the factory method. + A new ObjectDefinitionBuilder instance. + + + + Create a new ObjectDefinitionBuilder used to construct a child object definition.. + + The object definition factory. + Name of the parent object. + + + + + Adds the property value under the given name. + + The name. + The value. + The current ObjectDefinitionBuilder. + + + + Adds a reference to the specified object name under the property specified. + + The name. + Name of the object. + The current ObjectDefinitionBuilder. + + + + Adds an index constructor arg value. The current index is tracked internally and all addtions are + at the present point + + The constructor arg value. + The current ObjectDefinitionBuilder. + + + + Adds a reference to the named object as a constructor argument. + + Name of the object. + + + + + Sets the name of the factory method to use for this definition. + + The factory method. + The current ObjectDefinitionBuilder. + + + + Sets the name of the factory object to use for this definition. + + The factory object. + The factory method. + The current ObjectDefinitionBuilder. + + + + Sets whether or not this definition describes a singleton object. + + if set to true [singleton]. + The current ObjectDefinitionBuilder. + + + + Sets whether objects or not this definition is abstract. + + if set to true [flag]. + The current ObjectDefinitionBuilder. + + + + Sets whether objects for this definition should be lazily initialized or not. + + if set to true [lazy]. + The current ObjectDefinitionBuilder. + + + + Sets the autowire mode for this definition. + + The autowire mode. + The current ObjectDefinitionBuilder. + + + + Sets the dependency check mode for this definition. + + The dependency check. + The current ObjectDefinitionBuilder. + + + + Sets the name of the destroy method for this definition. + + Name of the method. + The current ObjectDefinitionBuilder. + + + + Sets the name of the init method for this definition. + + Name of the method. + The current ObjectDefinitionBuilder. + + + + Sets the resource description for this definition. + + The resource description. + The current ObjectDefinitionBuilder. + + + + Adds the specified object name to the list of objects that this definition depends on. + + Name of the object. + The current ObjectDefinitionBuilder. + + + + Gets the current object definition in its raw (unvalidated) form. + + The raw object definition. + + + + Validate and gets the object definition. + + The object definition. + + + + Utility methods that are useful for + + implementations. + + Juergen Hoeller + Rick Evans (.NET) + + + + + The string used as a separator in the generation of synthetic id's + for those object definitions explicitly that aren't assigned one. + + +

+ If a name or parent object definition + name is not unique, "#1", "#2" etc will be appended, until such + time that the name becomes unique. +

+ + + + + Registers the supplied with the + supplied . + + +

+ This is a convenience method that registers the + + of the supplied under the + + property value of said . If the + supplied has any + , + then those aliases will also be registered with the supplied + . +

+ + + The object definition holder containing the + that + is to be registered. + + + The registry that the supplied + is to be registered with. + + + If either of the supplied arguments is . + + + If the could not be registered + with the . + + + + + Generates an object definition name for the supplied + that is guaranteed to be unique + within the scope of the supplied . + + The + that requires a generated name. + The + + that the supplied is to be + registered with (needed so that the uniqueness of any generated + name can be guaranteed). + if set to true if the given object + definition will be registed as an inner object or as a top level objener objects + verses top level objects. + + An object definition name for the supplied + that is guaranteed to be unique + within the scope of the supplied and + never . + + + If either of the or + arguments is . + + + If a unique name cannot be generated. + + + + + Generates the name of the object for a top-level object definition unique within the given object factory. + + The object definition to generate an object name for. + The registry to check for existing names. + The generated object name + if no unique name can be generated for the given + object definition + + + + Factory method for getting concrete + instances. + + + The name of the event handler method. This may be straight text, a regular + expression, , or empty. + + + The name of the event being wired. This too may be straight text, a regular + expression, , or empty. + + + A concrete + instance. + + + + + Creates a new instance of the + class. + + +

+ This is a utility class, and as such exposes no public constructors. +

+ + + + + Thrown when the validation of an object definition failed. + + Juergen Hoeller + Rick Evans (.NET) + + + + Creates a new instance of the + + class. + + + + + Creates a new instance of the + + class. + + The detail message. + + + + Creates a new instance of the + + class. + + + The detail message. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the ObjectDefinitionValidationException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Helper class for use in object factory implementations, + resolving values contained in object definition objects + into the actual values applied to the target object instance. + + + Used by . + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + The object factory. + + + + Given a property value, return a value, resolving any references to other + objects in the factory if necessary. + + +

+ The value could be : + + +

+ An , + which leads to the creation of a corresponding new object instance. + Singleton flags and names of such "inner objects" are always ignored: inner objects + are anonymous prototypes. +

+ + +

+ A , which must + be resolved. +

+ + +

+ An . This is a + special placeholder collection that may contain + s or + collections that will need to be resolved. +

+ + +

+ An ordinary object or , in which case it's left alone. +

+ + +

+ + + The name of the object that is having the value of one of its properties resolved. + + + The definition of the named object. + + + The name of the property the value of which is being resolved. + + + The value of the property that is being resolved. + + + + + TODO + + + The name of the object that is having the value of one of its properties resolved. + + + The definition of the named object. + + + The name of the property the value of which is being resolved. + + + The value of the property that is being resolved. + + + + + Resolve the target type of the passed . + + The who's target type is to be resolved + The resolved target type, if any. otherwise. + + + + Resolves an inner object definition. + + + The name of the object that surrounds this inner object definition. + + + The name of the inner object definition... note: this is a synthetic + name assigned by the factory (since it makes no sense for inner object + definitions to have names). + + + The name of the property the value of which is being resolved. + + + The definition of the inner object that is to be resolved. + + + if the owner of the property is a singleton. + + + The resolved object as defined by the inner object definition. + + + + + Checks the given bean name whether it is unique. If not already unique, + a counter is added, increasing the counter until the name is unique. + + Original Name of the inner object. + The Adapted name for the inner object + + + + Resolve a reference to another object in the factory. + + + The name of the object that is having the value of one of its properties resolved. + + + The definition of the named object. + + + The name of the property the value of which is being resolved. + + + The runtime reference containing the value of the property. + + A reference to another object in the factory. + + + + The possible object scope values. + + Aleksandar Seovic + + + + + + + + + Application scope. + + + + + Session scope. + + + + + Request scope. + + + + + + + + + + Default scope (currently + ). + + + + + + Object definition reader for a simple properties format. + + + Provides object definition registration methods for + and + instances. Typically applied to a + . + + Rod Johnson + Juergen Hoeller + Simon White (.NET) + + + + Value of a T/F attribute that represents true. + Anything else represents false. Case seNsItive. + + + + + Separator between object name and property name. + + + + + Prefix for the class property of a root object definition. + + + + + Special string added to distinguish if the object will be + a singleton. + + +

+ Default is true. +

+ + +

+ owner.(singleton)=true +

+ + + + + Special string added to distinguish if the object will be + lazily initialised. + + +

+ Default is false. +

+ + +

+ owner.(lazy-init)=true +

+ + + + + Reserved "property" to indicate the parent of a child object definition. + + + + + Property suffix for references to other objects in the current + : e.g. + owner.dog(ref)=fido. + + +

+ Whether this is a reference to a singleton or a prototype + will depend on the definition of the target object. +

+ + + + + Prefix before values referencing other objects. + + + + + Creates a new instance of the + + class. + + + The + instance that this reader works on. + + + + + Load object definitions from the supplied . + + + The resource for the object definitions that are to be loaded. + + + The number of object definitions that were loaded. + + + In the case of loading or parsing errors. + + + + + Load object definitions from the specified properties file. + + + The resource descriptor for the properties file. + + + The match or filter for object definition names, e.g. 'objects.' + + in case of loading or parsing errors + the number of object definitions found + + + + Register object definitions contained in a + , using all property keys (i.e. + not filtering by prefix). + + + The containing object definitions. + + + In case of loading or parsing errors. + + The number of object definitions registered. + + + + Register object definitions contained in a + . + + +

+ Similar syntax as for an . + This method is useful to enable standard .NET internationalization support. +

+ + + The containing object definitions. + + + The match or filter for object definition names, e.g. 'objects.' + + + In case of loading or parsing errors. + + The number of object definitions registered. + + + + Register object definitions contained in an + , using all property keys + (i.e. not filtering by prefix). + + + The containing object definitions. + + + In case of loading or parsing errors. + + The number of object definitions registered. + + + + Registers object definitions contained in an + using all property keys ( i.e. not filtering by prefix ) + + The containing + object definitions. + + + In case of loading or parsing errors. + + The number of object definitions registered. + + + + Register object definitions contained in a + . + + +

+ Ignores ineligible properties. +

+ + IDictionary name -> property (String or Object). Property values + will be strings if coming from a Properties file etc. Property names + (keys) must be strings. Type keys must be strings. + + + The match or filter within the keys in the map: e.g. 'objects.' + + + In case of loading or parsing errors. + + The number of object definitions found. + + + + Register object definitions contained in a + . + + +

+ Ignores ineligible properties. +

+ + IDictionary name -> property (String or Object). Property values + will be strings if coming from a Properties file etc. Property names + (keys) must be strings. Type keys must be strings. + + + The match or filter within the keys in the map: e.g. 'objects.' + + + The description of the resource that the + came from (for logging purposes). + + + In case of loading or parsing errors. + + The number of object definitions found. + + + + Get all property values, given a prefix (which will be stripped) + and add the object they define to the factory with the given name + + The name of the object to define. + + The containing string pairs. + + The prefix of each entry, which will be stripped. + + The description of the resource that the + came from (for logging purposes). + + + In case of loading or parsing errors. + + + + + Name of default parent object + + + + + Gets or sets object definition factory to use. + + + + + A plain-vanilla object definition. + + +

+ This is the most common type of object definition; + instances + do not derive from a parent + , and usually + (but not always - see below) have an + + and (optionally) some + and + . +

+

+ Note that + instances do not have to specify an + : + This can be useful for deriving + instances + from such definitions, each with it's own + , + inheriting common property values and other settings from the parent. +

+ + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + + class. + + + The of the object to instantiate. + + + + + Creates a new instance of the + + class. + + + The of the object to instantiate. + + + if this object definition defines a singleton object. + + + + + Creates a new instance of the + class + for a singleton, providing property values and constructor arguments. + + + The of the object to instantiate. + + + The + to be applied to a new instance of the object. + + + The to be applied to + a new instance of the object. + + + + + Creates a new instance of the + class + for a singleton using the supplied + . + + + The of the object to instantiate. + + + The autowiring mode. + + + + + Creates a new instance of the + class + for a singleton using the supplied + . + + + The of the object to instantiate. + + + The autowiring mode. + + + Whether to perform a dependency check for objects (not + applicable to autowiring a constructor, thus ignored there) + + + + + Creates a new instance of the + class + with the given singleton status, providing property values. + + + The of the object to instantiate. + + + The to be applied to + a new instance of the object. + + + + + Creates a new instance of the + class + with the given singleton status, providing property values. + + + The of the object to instantiate. + + + The to be applied to + a new instance of the object. + + + if this object definition defines a singleton object. + + + + + Creates a new instance of the + class + for a singleton, providing property values and constructor arguments. + + +

+ Takes an object class name to avoid eager loading of the object class. +

+ + + The assembly qualified of the object to instantiate. + + + The to be applied to + a new instance of the object. + + + The + to be applied to a new instance of the object. + + + + + Creates a new instance of the + class. + + +

+ Deep copy constructor. +

+ + + The definition that is to be copied. + + + + + Validate this object definition. + + + In the case of a validation failure. + + + + + A that represents the current + . + + + A that represents the current + . + + + + + Is always null for a . + + + It is safe to request this property's value. Setting any other value than null will + raise an . + + Raised on any attempt to set a non-null value on this property. + + + + A implementation to use that checks + the object definitions only (no attributes) + + Mark Fisher + Mark Pollack (.NET) + + + + Determines whether the given object definition qualifies as an + autowire candidate for the given dependency. + + The object definition including object name and aliases. + The descriptor for the target method parameter or field. + + true if the object definition qualifies as autowire candidate; otherwise, false. + + + + + Static factory that permits the registration of existing singleton instances. + + +

+ Does not have support for prototype objects, aliases, and post startup object + configuration. +

+

+ Serves as a simple example implementation of the + interface, that manages existing object instances as opposed to creating new ones + based on object definitions. +

+

+ The + method is not supported by this class; this class deals exclusively with + existing singleton instances, thus the methods mentioned previously make little sense in this context. +

+ + Rod Johnson + Juergen Hoeller + Simon White (.NET) + + + + Map from object name to object instance. + + + + + This method is not supported by . + + + + + + Return an instance of the given object name. + + The name of the object to return. + The instance of the object. + + is not currently supported. + + + + + + Return an instance (possibly shared or independent) of the given object name. + + +

+ This method allows an object factory to be used as a replacement for the + Singleton or Prototype design pattern. +

+

+ Note that callers should retain references to returned objects. There is no + guarantee that this method will be implemented to be efficient. For example, + it may be synchronized, or may need to run an RDBMS query. +

+

+ Will ask the parent factory if the object cannot be found in this factory + instance. +

+ + The name of the object to return. + + The arguments to use if creating a prototype using explicit arguments to + a static factory method. If there is no factory method and the + arguments are not null, then match the argument values by type and + call the object's constructor. + + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + If the supplied is . + + + + + Return an instance (possibly shared or independent) of the given object name. + + The name of the object to return. + + The the object may match. Can be an interface or + superclass of the actual class. For example, if the value is the + class, this method will succeed whatever the + class of the returned instance. + + + The arguments to use if creating a prototype using explicit arguments to + a factory method. If there is no factory method and the + supplied array is not , then + match the argument values by type and call the object's constructor. + + The instance of the object. + + If there's no such object definition. + + + If the object could not be created. + + + If the object is not of the required type. + + + If the supplied is . + + + + + + Return an instance of the given object name. + + The name of the object to return. + + the object may match. Can be an interface or + superclass of the actual class. For example, if the value is the + class, this method will succeed whatever the + class of the returned instance. + + The instance of the object. + + + + + Does this object factory contain an object with the given name? + + The name of the object to query. + True if an object with the given name is defined. + + + + Is this object a singleton? + + +

+ That is, will + or + always return the same object? +

+ + The name of the object to query. + True if the named object is a singleton. + + If there's no such object definition. + + + + + Determines whether the specified object name is prototype. That is, will GetObject + always return independent instances? + + This method returning false does not clearly indicate a singleton object. + It indicated non-independent instances, which may correspond to a scoped object as + well. use the IsSingleton property to explicitly check for a shared + singleton instance. + Translates aliases back to the corresponding canonical object name. Will ask the + parent factory if the object can not be found in this factory instance. + + + + The name of the object to query + + true if the specified object name will always deliver independent instances; otherwise, false. + + if there is no object with the given name. + + + + Determine the type of the object with the given name. + + +

+ More specifically, checks the type of object that + would return. + For an , returns the type + of object that the creates. +

+ + The name of the object to query. + + The of the object or if + not determinable. + + + + + Determines whether the object with the given name matches the specified type. + + The name of the object to query. + Type of the target to match against. + + true if the object type matches; otherwise, false + if it doesn't match or cannot be determined yet. + + Ff there is no object with the given name + + + + + Return the aliases for the given object name, if defined. + + The object name to check for aliases. + The aliases, or an empty array if none. + + If there's no such object definition. + + + + + Not supported. + + The name of the object. + + The registered + . + + + Always, as object definitions are not supported by this + implementation. + + + + + Return the registered + for the + given object, allowing access to its property values and constructor + argument values. + + The name of the object. + Whether to search parent object factories. + + The registered + . + + + If there is no object with the given name. + + + In the case of errors. + + + + + Return the names of all objects defined in this factory. + + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + Return the names of objects matching the given + (including subclasses), judging from the object definitions. + + + The (class or interface) to match, or + for all object names. + + +

+ Will not consider s, + as the type of their created objects is not known before instantiation. +

+ + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + Return the names of objects matching the given + (including subclasses), judging from the object definitions. + + + The (class or interface) to match, or + for all object names. + + +

+ Does consider objects created by s, + or rather it considers the type of objects created by + (which means that + s will be instantiated). +

+

+ Does not consider any hierarchy this factory may participate in. +

+ + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + Return the names of objects matching the given + (including subclasses), judging from the object definitions. + + +

+ Since this implementation of the + + interface does not support the notion of ptototype objects, the + parameter is ignored. +

+ + + The (class or interface) to match, or + for all object names. + + + Whether to include prototype objects too or just singletons (also applies to + s). Ignored. + + + Whether to include s too + or just normal objects. + + + The names of all objects defined in this factory, or an empty array if none + are defined. + + + + + + Tests whether this object factory contains an object definition for the + specified object name. + + The object name to query. + + True if an object defintion is contained within this object factory. + + + + + Return the object instances that match the given object + (including subclasses), judging from either object + definitions or the value of + in the case of + s. + + +

+ This version of the + method matches all kinds of object definitions, be they singletons, prototypes, or + s. Typically, the results + of this method call will be the same as a call to + IListableObjectFactory.GetObjectsOfType(type,true,true) . +

+ + + The (class or interface) to match. + + + A of the matching objects, + containing the object names as keys and the corresponding object instances + as values. + + + If the objects could not be created. + + + + + Return the object instances that match the given object + (including subclasses), judging from either object + definitions or the value of + in the case of + s. + + + The (class or interface) to match. + + + Whether to include prototype objects too or just singletons (also applies to + s). + + + Whether to include s too + or just normal objects. + + + A of the matching objects, + containing the object names as keys and the corresponding object instances + as values. + + + If the objects could not be created. + + + + + Add a new singleton object. + + + The name to be associated with the object name. + + The singleton object. + + + + Injects dependencies into the supplied instance + using the named object definition. + + + The object instance that is to be so configured. + + + The name of the object definition expressing the dependencies that are to + be injected into the supplied instance. + + + This feature is not currently supported. + + + + + + Injects dependencies into the supplied instance + using the supplied . + + + The object instance that is to be so configured. + + + The name of the object definition expressing the dependencies that are to + be injected into the supplied instance. + + + An object definition that should be used to configure object. + + + + + + Defines a method to release allocated unmanaged resources. + + + + + Determine whether this object factory treats object names case-sensitive or not. + + + + + Return the number of objects defined in the factory. + + + The number of objects defined in the factory. + + + + + Return an instance of the given object name. + + The name of the object to return. + The instance of the object. + + + + + Abstract implementation providing + a number of convenience methods and a + template method + that subclasses must override to provide the actual parsing logic. + + + Use this implementation when you want + to parse some arbitrarily complex XML into one or more + ObjectDefinitions. If you just want to parse some + XML into a single IObjectDefinition, you may wish to consider + the simpler convenience extensions of this class, namely + and + + + Rob Harrop + Juergen Hoeller + Rick Evans + Mark Pollack (.NET) + + + + Interface used to handle custom, top-level tags. + + Implementations are free to turn the metadata in the custom tag into as + many as required. + + Rob Harrop + Mark Pollack (.NET) + + + + Parse the specified XmlElement and register the resulting + ObjectDefinitions with the IObjectDefinitionRegistry + embedded in the supplied + + +

+ This method is never invoked if the parser is namespace aware + and was called to process the root node. +

+ + + The element to be parsed. + + + TThe object encapsulating the current state of the parsing process. + Provides access to a IObjectDefinitionRegistry + + + The primary object definition. + + + + + Constant for the ID attribute + + + + + Parse the specified XmlElement and register the resulting + ObjectDefinitions with the IObjectDefinitionRegistry + embedded in the supplied + + The element to be parsed. + TThe object encapsulating the current state of the parsing process. + Provides access to a IObjectDefinitionRegistry + The primary object definition. + +

+ This method is never invoked if the parser is namespace aware + and was called to process the root node. +

+ + + + + Resolves the ID for the supplied . + + + When using generation, a name is generated automatically. + Otherwise, the ID is extracted from the "id" attribute, potentially with a + fallback to a generated id. + + The element that the object definition has been built from. + The object definition to be registered. + The the object encapsulating the current state of the parsing process; + provides access to a + the resolved id + + if no unique name could be generated for the given object definition + + + + + Registers the supplied with the supplied + . + + Subclasses can override this method to control whether or not the supplied + is actually even registered, or to + register even more objects. + + The default implementation registers the supplied + with the supplied only if the IsNested + parameter is false, because one typically does not want inner objects + to be registered as top level objects. + + + + The object definition to be registered. + The registry that the bean is to be registered with. + + + + Returns the value of the element's attribute or null, if the attribute is not specified. + + + This is a helper for bypassing the behavior of + to return if the attribute does not exist. + + + + + Returns the value of the element's attribute or , + if the attribute is not specified. + + + This is a helper for bypassing the behavior of + to return if the attribute does not exist. + + + + + Central template method to actually parse the supplied XmlElement + into one or more IObjectDefinitions. + + The element that is to be parsed into one or more s + The the object encapsulating the current state of the parsing process; + provides access to a + The primary IObjectDefinition resulting from the parsing of the supplied XmlElement + + + + Gets a value indicating whether an ID should be generated instead of read + from the passed in XmlElement. + + Note that this flag is about always generating an ID; the parser + won't even check for an "id" attribute in this case. + + true if should generate id; otherwise, false. + + + + Gets a value indicating whether an ID should be generated instead if the + passed in XmlElement does not specify an "id" attribute explicitly. + + Disabled by default; subclasses can override this to enable ID generation + as fallback: The parser will first check for an "id" attribute in this case, + only falling back to a generated ID if no value was specified. + + true if should generate id if no value was specified; otherwise, false. + + + + + Convenient base class for when there exists a one-to-one mapping + between attribute names on the element that is to be parsed and + the property names on the Type being configured. + + + + + Mark Pollack + + + + Base Type for those implementations that + need to parse and define just a single IObjectDefinition. + + + Extend this parser Type when you want to create a single object definition + from an arbitrarily complex XML element. You may wish to consider extending + the when you want to create a + single Object definition from a relatively simple custom XML element. + The resulting ObjectDefinition will be automatically registered + with the ObjectDefinitionRegistry. Your job simply is to parse the + custom XML element into a single ObjectDefinition + + Rob Harrop + Juergen Hoeller + Rick Evans + Mark Pollack (.NET) + + + + Central template method to actually parse the supplied XmlElement + into one or more IObjectDefinitions. + + The element that is to be parsed into one or more s + The the object encapsulating the current state of the parsing process; + provides access to a + + The primary IObjectDefinition resulting from the parsing of the supplied XmlElement + + + + + Determine the name for the parent of the currently parsed object, + in case of the current object being defined as a child object. + The default implementation returns null + indicating a root object definition. + + + the name of the parent object for the currently parsed object. + + + + Gets the type of the object corresponding to the supplied XmlElement. + + Note that, for application classes, it is generally preferable to override + GetObjectTypeName instad, in order to avoid a direct + dependence on the object implementation class. The ObjectDefinitionParser + and its IXmlObjectDefinitionParser (namespace parser) can be used within an + IDE add-in then, even if the application classses are not available in the add-ins + AppDomain. + + The element. + The Type of the class that is being defined via parsing the supplied + Element. + + + + Gets the name of the object type name (FullName) corresponding to the supplied XmlElement. + + The element. + The type name of the object that is being defined via parsing the supplied + XmlElement. + + + + Parse the supplied XmlElement and populate the supplied ObjectDefinitionBuilder as required. + + The default implementation delegates to the DoParse version without + ParameterContext argument. + The element. + The parser context. + The builder used to define the IObjectDefinition. + + + + Parse the supplied XmlElement and populate the supplied ObjectDefinitionBuilder as required. + + The default implementation does nothing. + The element. + The builder used to define the IObjectDefinition. + + + + Default implementation of the interface. + Resolves namespace URIs to implementation types based on mappings. + + Erich Eichinger + + + + + + Used by to locate + implementations for a particular namespace URI. + + TODO (EE): clarify naming of INamespaceParser (SPR/NET) vs. INamespaceHandler (SPR/Java), thus internal for now + Erich Eichinger + + + + + + + Lookup a for the given namespace URI. + + the namespace URI + the located namespace handler or null + + + + Resolve the namespace URI and return the corresponding + implementation. + + the namespace URI to get the matching parser for. + the matching parser or null + + + + XML resource reader. + + +

+ Navigates through an XML resource and invokes parsers registered + with the . +

+ + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + SPI for parsing an XML document that contains Spring object definitions. + Used by for actually parsing a DOM + document. + + Instantiated per document to parse: Implementations can hold state in + instance variables during the execution of the RegisterObjectDefinitions + method, for example global settings that are defined for all object definitions + in the document. + + Juergen Hoeller + Rob Harrop + Mark Pollack (.NET) + + + + + Read object definitions from the given DOM element, and register + them with the given object registry. + + The DOM element containing object definitions, usually the + root (document) element. + The current context of the reader. Includes + the resource being parsed + + The number of object definitions that were loaded. + + + In case of parsing errors. + + + + + The shared instance for this class (and derived classes). + + + + + Creates a new instance of the DefaultObjectDefinitionDocumentReader class. + + + + + Read object definitions from the given DOM element, and register + them with the given object registry. + + The DOM element containing object definitions, usually the + root (document) element. + The current context of the reader. Includes + the resource being parsed + + The number of object definitions that were loaded. + + + In case of parsing errors. + + + + + Parses object definitions starting at the given + using the passed . + + The root element to start parsing from. + The instance to use. + + in case an error happens during parsing and registering object definitions + + + + + Process an alias element. + + + + + Process the object element + + + + + Loads external XML object definitions from the resource described by the supplied + . + + The XML element describing the resource. + + If the resource could not be imported. + + + + + Parses the given alias element, registering the alias with the registry. + + The alias element. + The registry. + + + + Parse an object definition and register it with the object factory.. + + The element containing the object definition. + The helper. + + + + + + Allow the XML to be extensible by processing any custom element types last, + after we finished processing the objct definitions. This method is a natural + extension point for any other custom post-processing of the XML. + + The default implementation is empty. Subclasses can override this method to + convert custom elements into standard Spring object definitions, for example. + Implementors have access to the parser's object definition reader and the + underlying XML resource, through the corresponding properties. + + + The root. + + + + Allow the XML to be extensible by processing any custom element types first, + before we start to process the object definitions. + + This method is a natural + extension point for any other custom pre-processing of the XML. +

The default implementation is empty. Subclasses can override this method to + convert custom elements into standard Spring object definitions, for example. + Implementors have access to the parser's object definition reader and the + underlying XML resource, through the corresponding properties. +

+ + The root element of the XML document. + + + + Creates an instance for the given and element. + + the to create the + the root to start reading from + a new instance + + + + Gets the reader context. + + The reader context. + + + + Simple class that holds the defaults specified at the <objects> + level in a standard Spring XML object definition document: + default-lazy-init, default-autowire, etc. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Gets or sets the autowire setting for the document that's currently parsed. + + The autowire. + + + + Gets or sets the dependency-check setting for the document that's currently parsed + + The dependency check. + + + + Gets or sets the lazy-init flag for the document that's currently parsed. + + The lazy init. + + + + Gets or sets the merge setting for the document that's currently parsed. + + The merge. + + + + Strategy interface for parsing XML object definitions. Equivalent to Spring/Java's NamespaceHandler interface. + + +

+ Used by + for actually parsing a DOM document or + fragment. +

+ + Juergen Hoeller + Rick Evans (.NET) + Sandu Turcan (.NET) + + + + Invoked by after construction but before any + elements have been parsed. + + + + + Parse the specified element and register any resulting + IObjectDefinitions with the IObjectDefinitionRegistry that is + embedded in the supplied ParserContext. + + + Implementations should return the primary IObjectDefinition + that results from the parse phase if they wish to used nested + inside (for example) a <property> tag. + Implementations may return null if they will not + be used in a nested scenario. + + + The element to be parsed into one or more IObjectDefinitions + The object encapsulating the current state of the parsing + process. + + The primary IObjectDefinition (can be null as explained above) + + + + + Parse the specified XmlNode and decorate the supplied ObjectDefinitionHolder, + returning the decorated definition. + + The XmlNode may either be an XmlAttribute or an XmlElement, depending on + whether a custom attribute or element is being parsed. + Implementations may choose to return a completely new definition, + which will replace the original definition in the resulting IApplicationContext/IObjectFactory. + + The supplied ParserContext can be used to register any additional objects needed to support + the main definition. + + The source element or attribute that is to be parsed. + The current object definition. + The object encapsulating the current state of the parsing + process. + The decorated definition (to be registered in the IApplicationContext/IObjectFactory), + or simply the original object definition if no decoration is required. A null value is strickly + speaking invalid, but will leniently treated like the case where the original object definition + gets returned. + + + + Attribute that should be used to specify the default namespace + and schema location for a custom namespace parser. + + Aleksandar Seovic + + + + Creates a new instance of . + + + + + Gets or sets the default namespace for the configuration parser. + + + The default namespace for the configuration parser. + + + + + Gets or sets the default schema location for the configuration parser. + + + The default schema location for the configuration parser. + + + If the property is set, the will always resolve to an assembly-resource + and the set will be interpreted relative to this assembly. + + + + + Gets or sets a type from the assembly containing the schema + + + If this property is set, the will always resolve to an assembly-resource + and the will be interpreted relative to this assembly. + + + + + Provides a resolution mechanism for configuration parsers. + + +

+ The uses this registry + class to find the parser handling a specific namespace. +

+ + Aleksandar Seovic + + + + Name of the .Net config section that contains definitions + for custom config parsers. + + + + + Creates a new instance of the NamespaceParserRegistry class. + + + + + Reset the list of registered parsers to "factory"-setting + + use for unit tests only + + + + Registers the type for wellknown namespaces + + true if the parser could be registered, false otherwise + + + + Constructs a "assembly://..." qualified schemaLocation url using the given type + to obtain the assembly name. + + + + + Returns a parser for the given namespace. + + + The namespace for which to lookup the parser implementation. + + + A parser for a given , or + if no parser was found. + + + + + Returns a schema collection containing validation schemas for all registered parsers. + + + A schema collection containing validation schemas for all registered parsers. + + + + + Pegisters parser, using default namespace and schema location + as defined by the . + + + The of the parser that will be activated + when an element in its default namespace is encountered. + + + If is . + + + + + Associates a parser with a namespace. + + + + Parsers registered with the same as that + of a parser that has previously been registered will overwrite the existing + parser. + + + + The of the parser that will be activated + when the attendant is + encountered. + + + The namespace with which to associate instance of the parser. + + + The location of the XML schema that should be used for validation + of the XML elements that belong to the specified namespace + (can be any valid Spring.NET resource URI). + + + If the is not a + that implements the + interface. + + + If is . + + + + + Pegisters parser, using default namespace and schema location + as defined by the . + + + The parser instance. + + + If is . + + + + + Associates a parser with a namespace. + + + + Parsers registered with the same as that + of a parser that has previously been registered will overwrite the existing + parser. + + + + The namespace with which to associate instance of the parser. + + + The parser instance. + + + The location of the XML schema that should be used for validation + of the XML elements that belong to the specified namespace + (can be any valid Spring.NET resource URI). + + + If is , or if + is not specified and parser class + does not have default value defined using . + + + + + Register a schema as well-known + + + + + + + Returns default values for the parser namespace and schema location as + defined by the . + + + A type of the parser. + + + A instance containing + default values for the parser namsepace and schema location + + + + + Resolves xml entities by using the infrastructure. + + + + + Adapts the interface to . + Only for smooth transition between 1.x and 2.0 style namespace handling, will be dropped for 2.0 + + + + + Support class for implementing custom namespace parsers. + + Parsing of individual elements is done via a ObjectDefintionParser. + Provides the RegisterObjectDefinitionParser for registering a ObjectDefintionParser + to handle a specific element. + Rob Harrop + Juergen Hoeller + Mark Pollack (.NET) + + + + Invoked by after construction but before any + elements have been parsed. + + + + + Parses an element under the root node, typically + an object definition or import statement. + + + The element to be parsed. + + + The parser context. + + + The number of object defintions created from this element. + + + + + Parse the specified XmlNode and decorate the supplied ObjectDefinitionHolder, + returning the decorated definition. + + The XmlNode may either be an XmlAttribute or an XmlElement, depending on + whether a custom attribute or element is being parsed. + Implementations may choose to return a completely new definition, + which will replace the original definition in the resulting IApplicationContext/IObjectFactory. + + The supplied ParserContext can be used to register any additional objects needed to support + the main definition. + + The source element or attribute that is to be parsed. + The current object definition. + The object encapsulating the current state of the parsing + process. + The decorated definition (to be registered in the IApplicationContext/IObjectFactory), + or simply the original object definition if no decoration is required. A null value is strickly + speaking invalid, but will leniently treated like the case where the original object definition + gets returned. + + + + Register the specified for the given + + + + + Constants defining the structure and values associated with the + Spring.NET XML object definition format. + + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + Value of a boolean attribute that represents + . + + +

+ Anything else represents . +

+ + + + + Signifies that a default value is to be applied. + + + + + Defines an external XML object definition resource. + + + + + Specifies the relative path to an external XML object definition + resource. + + + + + Defines an alias for an object definition. + + + + + Specifies the alias of an object definition. + + + + + Specifies the default lazy initialization mode. + + + + + Specifies the default dependency checking mode. + + + + + Specifies the default autowire mode. + + + + + Specifies the default collection merge mode. + + + + + Defines a single named object. + + + + + Element containing informative text describing the purpose of the + enclosing element. + + +

+ Always optional. +

+

+ Used primarily for user documentation of XML object definition + documents. +

+ + + + + Specifies a . + + +

+ Does not have to be fully assembly qualified, but it is recommended + that the names of one's objects are + specified explicitly. +

+ + + + + The name or alias of the parent object definition that a child + object definition inherits from. + + + + + Objects can be identified by an id, to enable reference checking. + + +

+ There are constraints on a valid XML id: if you want to reference + your object in .NET code using a name that's illegal as an XML id, + use the optional "name" attribute + (). + If neither given, the objects name is + used as id. +

+ + + + + Can be used to create one or more aliases illegal in an id. + + +

+ Multiple aliases can be separated by any number of spaces, + semicolons, or commas + (). +

+

+ Always optional. +

+ + + + + Is this object a "singleton" (one shared instance, which will + be returned by all calls to + with the id), or a + "prototype" (independent instance resulting from each call to + ). + + +

+ Singletons are most commonly used, and are ideal for multi-threaded + service objects. +

+ + + + + + Controls object scope. Only applicable to ASP.NET web applications. + + +

+ Scope can be defined as either application, session or request. It + defines when "singleton" instances are initialized, but has no + effect on prototype definitions. +

+ + + + + The names of the objects that this object depends on being + initialized. + + +

+ The object factory will guarantee that these objects + get initialized before this object definition. +

+ + Dependencies are normally expressed through object properties or + constructor arguments. This property should just be necessary for + other kinds of dependencies such as statics (*ugh*) or database + preparation on startup. + + + + + + Optional attribute for the name of the custom initialization method + to invoke after setting object properties. + + +

+ The method must have no arguments. +

+ + + + + Optional attribute for the name of the custom destroy method to + invoke on object factory shutdown. + + +

+ Valid destroy methods have either of the following signatures... + + void MethodName() + void MethodName(bool force) + +

+ + Only invoked on singleton objects! + + + + + + A constructor argument : the constructor-arg tag can have an + optional type attribute, to specify the exact type of the + constructor argument + + +

+ Only needed to avoid ambiguities, e.g. in case of 2 single + argument constructors that can both be converted from a + . +

+ + + + + The constructor-arg tag can have an optional index attribute, + to specify the exact index in the constructor argument list. + + +

+ Only needed to avoid ambiguities, e.g. in case of 2 arguments of + the same type. +

+ + + + + The constructor-arg tag can have an optional named parameter + attribute, to specify a named parameter in the constructor + argument list. + + + + + Is this object "abstract", i.e. not meant to be instantiated itself + but rather just serving as parent for concrete child object + definitions? + + +

+ Default is . Specify + to tell the object factory to not try to instantiate that + particular object in any case. +

+ + + + + A property definition : object definitions can have zero or more + properties. + + +

+ Spring.NET supports primitives, references to other objects in the + same or related factories, lists, dictionaries, and name value + collections. +

+ + + + + A reference to another managed object or static + . + + + + + ID refs must specify a name of the target object. + + + + + A reference to the name of another managed object in the same + context. + + + + + A reference to the name of another managed object in the same + context. + + +

+ Local references, using the "local" attribute, have to use object + ids; they can be checked by a parser, thus should be preferred for + references within the same object factory XML file. +

+ + + + + Alternative to type attribute for factory-method usage. + + +

+ If this is specified, no type attribute should be used. This should + be set to the name of an object in the current or ancestor + factories that contains the relevant factory method. This allows + the factory itself to be configured using Dependency Injection, and + an instance (rather than static) method to be used. +

+ + + + + Optional attribute specifying the name of a factory method to use + to create this object. + + +

+ Use constructor-arg elements to specify arguments to the factory + method, if it takes arguments. Autowiring does not apply to + factory methods. +

+

+ If the "type" attribute is present, the factory method will be a + static method on the type specified by the "type" attribute on + this object definition. Often this will be the same type as that + of the constructed object - for example, when the factory method + is used as an alternative to a constructor. However, it may be on + a different type. In that case, the created object will *not* be + of the type specified in the "type" attribute. This is analogous + to behaviour. +

+

+ If the "factory-object" attribute is present, the "type" attribute + is not used, and the factory method will be an instance method on + the object returned from a + + call with the specified object name. The factory object may be + defined as a singleton or a prototype. +

+

+ The factory method can have any number of arguments. Use indexed + constructor-arg elements in conjunction with the factory-method + attribute. +

+

+ Setter Injection can be used in conjunction with a factory method. + Method Injection cannot, as the factory method returns an instance, + which will be used when the container creates the object. +

+ + + + + A list can contain multiple inner object, ref, collection, or + value elements. + + +

+ Lists are untyped, pending generics support, although references + will be strongly typed. +

+

+ A list can also map to an array type. The necessary conversion is + automatically performed by the + . +

+ + + + + A set can contain multiple inner object, ref, collection, or value + elements. + + +

+ Sets are untyped, pending generics support, although references + will be strongly typed. +

+ + + + + A Spring.NET map is a mapping from a string key to object (a .NET + ). + + +

+ Dictionaries may be empty. +

+ + + + + A lookup key (for a dictionary or name / value collection). + + + + + A lookup key (for a dictionary or name / value collection). + + + + + Contains a string representation of a value. + + +

+ This is used by name-value, ctor argument, and property elements. +

+ + + + + Contains delimiters that should be used to split delimited string values. + + +

+ This is used by name-value element. +

+ + + + + A reference to another objects. + + +

+ Used as a convenience shortcut on property and constructor-arg + elements to refer to other objects. +

+ + + + + Contains a string representation of an expression. + + +

+ This is used by ctor argument and property elements. +

+ + + + + A map entry can be an inner object, ref, collection, or value. + + +

+ The name of the property is given by the "key" attribute. +

+ + + + + Contains a string representation of a property value. + + +

+ The property may be a string, or may be converted to the + required using the + + machinery. This makes it possible for application developers to + write custom + implementations that can convert strings to objects. +

+ + This is recommended for simple objects only. Configure more complex + objects by setting properties to references to other objects. + + + + + + Contains a string representation of an expression. + + + + + Denotes value. + + +

+ Necessary because an empty "value" tag will resolve to an empty + , which will not be resolved to + value unless a special + does so. +

+ + + + + 'name-values' elements differ from dictionary elements in that + values must be strings. + + +

+ May be empty. +

+ + + + + Element content is the string value of the property. + + +

+ The "key" attribute is the name of the property. +

+ + + + + The lazy initialization mode for an individual object definition. + + + + + The dependency checking mode for an individual object definition. + + + + + Defines a subscription to one or more events published by one or + more event sources. + + + + + The name of an event handling method. + + +

+ Defaults to On${event}. + Note : this default will probably change before the first 1.0 + release. +

+ + + + + The name of an event. + + + + + The autowiring mode for an individual object definition. + + + + + Shortcut alternative to specifying a key element in a + dictionary entry element with <ref object="..."/>. + + + + + Shortcut alternative to specifying a value element in a + dictionary entry element with <ref object="..."/>. + + + + + Specify if the collection values should be merged with the parent. + + + + + The string of characters that delimit object names. + + + + + A lookup method causes the IoC container to override a given method and return + the object with the name given in the attendant object attribute. + + +

+ This is a form of Method Injection. +

+

+ It's particularly useful as an alternative to implementing the + interface, + in order to be able to make + + calls for non-singleton instances at runtime. In this case, Method Injection + is a less invasive alternative. +

+ + + + + The name of a lookup method. This method must take no arguments. + + + + + The name of the object in the IoC container that the lookup method + must resolve to. + + +

+ Often this object will be a prototype, in which case the lookup method + will return a distinct instance on every invocation. This is useful + for single-threaded objects. +

+ + + + + A replaced method causes the IoC container to override a given method + with an (arbitrary) implementation at runtime. + + +

+ This (again) is a form of Method Injection. +

+ + + + + Name of the method whose implementation should be replaced by the + IoC container. + + +

+ If this method is not overloaded, there's no need to use arg-type + subelements. +

+

+ If this method is overloaded, arg-type subelements must be + used for all override definitions for the method. +

+ + + + + The object name of an implementation of the + interface. + + +

+ This may be a singleton or prototype. If it's a prototype, a new + instance will be used for each method replacement. Singleton usage + is the norm. +

+ + + + + Subelement of replaced-method identifying an argument for a + replaced method in the event of method overloading. + + + + + + Specification of the of an overloaded method + argument as a . + + +

+ For convenience, this may be a substring of the FQN. E.g. all the following would match + : +

+

+ + + System.String + + + string + + + str + + +

+ + + + + + Check everything. + + + + + Just check primitive (string, int, etc) values. + + + + + Check object references. + + + + + Autowire by name. + + + + + Autowire by . + + + + + Autowiring by constructor. + + + + + The autowiring strategy is to be determined by introspection + of the object's . + + + + + Creates a new instance of the + + class. + + +

+ This is a utility class, and as such has no publicly visible + constructors. +

+ + + + + Stateful class used to parse XML object definitions. + + Not all parsing code has been refactored into this class. See + BeanDefinitionParserDelegate in Java for how this class should evolve. + Rob Harrop + Juergen Hoeller + Rod Johnson + Mark Pollack (.NET) + + + + The shared instance for this class (and derived classes). + + + + + Initializes a new instance of the class. + + The reader context. + + + + Initializes a new instance of the class. + + The reader context. + The root element of the definition document to parse + + + + Initialize the default lazy-init, dependency check, and autowire settings. + + The root element + + + + Determines whether the Spring object namespace is equal to the the specified namespace URI. + + The namespace URI. + + true if is the default Spring namespace; otherwise, false. + + + + + Decorates the object definition if required. + + The element. + The holder. + + + + + Parse a standard object definition into a + , + including object name and aliases. + + The element containing the object definition. + + The parsed object definition wrapped within an + + instance. + + + + Object elements specify their canonical name via the "id" attribute + and their aliases as a delimited "name" attribute. + + + If no "id" is specified, uses the first name in the "name" attribute + as the canonical name, registering all others as aliases. + + + + + + Parse a standard object definition into a + , + including object name and aliases. + + The element containing the object definition. + The containing object definition if is a nested element. + + The parsed object definition wrapped within an + + instance. + + + + Object elements specify their canonical name via the "id" attribute + and their aliases as a delimited "name" attribute. + + + If no "id" is specified, uses the first name in the "name" attribute + as the canonical name, registering all others as aliases. + + + + + + Create an instance from the given and . + + + This method may be used as a last resort to post-process an object definition before it gets added to the registry. + + + + + Allows deriving classes to post process the name and aliases for the current element. By default + does nothing and returns the unmodified . + + + The list passed in may be modified by an implementation of this method to reflect special needs. + + the object name obtained by the default algorithm from 'id' and 'name' attributes so far. + the object aliases obtained by the default algorithm from 'name' attribute so far. + the currently processed element. + the containing object definition, may be null + the new object name to be used. + + + + Validate that the specified object name and aliases have not been used already. + + + + + Parses an element in a custom namespace. + + + the parsed object definition or null if not supported by the corresponding parser. + + + + Parses an element in a custom namespace. + + + if a nested element, the containing object definition + the parsed object definition or null if not supported by the corresponding parser. + + + + Given a string containing delimited object names, returns + a string array split on the object name delimeter. + + + The string containing delimited object names. + + + A string array split on the object name delimeter. + + + + + + Determines whether the string represents a 'true' boolean value. + + The value. + + true if is 'true' string value; otherwise, false. + + + + + Convenience method to create a builder for a root object definition. + + Name of the object type. + A builder for a root object definition. + + + + Convenience method to create a builder for a root object definition. + + Type of the object. + a builder for a root object definition + + + + Returns the value of the element's attribute or null, if the attribute is not specified. + + + This is a helper for bypassing the behavior of + to return if the attribute does not exist. + + + + + Returns the value of the element's attribute or , + if the attribute is not specified. + + + This is a helper for bypassing the behavior of + to return if the attribute does not exist. + + + + + Report a parser error. + + + + + Gets the defaults definition object, or null if the + default have not yet been initialized. + + The defaults. + + + + Gets the reader context. + + The reader context. + + + + Creates an instance + populated with the object definitions supplied in the configuration + section. + + +

+ Applications will typically want to use an + , and instantiate it + via the use of the + class (which is similar in functionality to this class). This class is + provided for those times when only an + is required. +

+ Creates an instance of the class XmlObjectFactory + + +

+ +

+ + Mark Pollack (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a + instance populated with the object definitions supplied in the + configuration section. + + + The configuration settings in a corresponding parent configuration + section. + + + The configuration context when called from the ASP.NET + configuration system. Otherwise, this parameter is reserved and + is . + + + The for the section. + + + A instance + populated with the object definitions supplied in the configuration + section. + + + + + Default implementation of the + interface. + + +

+ Parses object definitions according to the standard Spring.NET schema. +

+

+ This schema is typically located at + http://www.springframework.net/xsd/spring-objects.xsd. +

+ + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + The namespace URI for the standard Spring.NET object definition schema. + + + + + The shared instance for this class (and derived classes). + + + + + Invoked by after construction but before any + elements have been parsed. + + This is a NoOp + + + + Parse the specified XmlElement and register the resulting + ObjectDefinitions with the IObjectDefinitionRegistry + embedded in the supplied + + The element to be parsed. + TThe object encapsulating the current state of the parsing process. + Provides access to a IObjectDefinitionRegistry + The primary object definition. + +

+ This method is never invoked if the parser is namespace aware + and was called to process the root node. +

+ + + + + Parse the specified element and register any resulting + IObjectDefinitions with the IObjectDefinitionRegistry that is + embedded in the supplied ParserContext. + + The element to be parsed into one or more IObjectDefinitions + The object encapsulating the current state of the parsing + process. + + The primary IObjectDefinition (can be null as explained above) + + + Implementations should return the primary IObjectDefinition + that results from the parse phase if they wish to used nested + inside (for example) a <property> tag. + Implementations may return null if they will not + be used in a nested scenario. + + + + + + Parse the specified XmlNode and decorate the supplied ObjectDefinitionHolder, + returning the decorated definition. + + The XmlNode may either be an XmlAttribute or an XmlElement, depending on + whether a custom attribute or element is being parsed. + Implementations may choose to return a completely new definition, + which will replace the original definition in the resulting IApplicationContext/IObjectFactory. + + The supplied ParserContext can be used to register any additional objects needed to support + the main definition. + + The source element or attribute that is to be parsed. + The current object definition. + The object encapsulating the current state of the parsing + process. + The decorated definition (to be registered in the IApplicationContext/IObjectFactory), + or simply the original object definition if no decoration is required. A null value is strickly + speaking invalid, but will leniently treated like the case where the original object definition + gets returned. + + + + Loads external XML object definitions from the resource described by the supplied + . + + The XML element describing the resource. + The parser context. + + If the resource could not be imported. + + + + Parses an event listener definition. + + The name associated with the object that the event handler is being defined on. + + The events being populated. + + The element containing the event listener definition. + + + The namespace-aware parser. + + + + + Parse an object definition and register it with the object factory.. + + The element containing the object definition. + The parser context. + + + + + Parse an object definition and register it with the object factory.. + + The element containing the object definition. + The parser context. + + + + + Parse an object definition and register it with the object factory.. + + The element containing the object definition. + The parser context. + + + + + Parse a standard object definition into a + , + including object name and aliases. + + The element containing the object definition. + The parser context. + if set to true if we are processing an inner + object definition. + + The object (definition) wrapped within an + + instance. + + +

+ Object elements specify their canonical name via the "id" attribute + and their aliases as a delimited "name" attribute. +

+

+ If no "id" is specified, uses the first name in the "name" attribute + as the canonical name, registering all others as aliases. +

+ + + + + Calculates an id for an object definition. + + +

+ Called when an object definition has not been explicitly defined + with an id. +

+ + + The element containing the object definition. + + + The list of names defined for the object; may be + or even empty. + + + A calculated object definition id. + + + + + Parse a standard object definition. + + The element containing the object definition. + The id of the object definition. + parsing state holder + The object (definition). + + + + Parse method override argument subelements of the given object element. + + + + + Parse element and add parsed element to + + + + + Parse element and add parsed element to + + + + + Parse constructor argument subelements of the given object element. + + + + + Parse event handler subelements of the given object element. + + + + + Parse property value subelements of the given object element. + + + The name of the object (definition) associated with the property element (s) + + + The element containing the top level object definition. + + + The namespace-aware parser. + + + The property (s) associated with the object (definition). + + + + + Parse a constructor-arg element. + + + The name of the object (definition) associated with the ctor arg. + + + The list of constructor args associated with the object (definition). + + + The name of the element containing the ctor arg definition. + + + The namespace-aware parser. + + + + + Parse a property element. + + + The name of the object (definition) associated with the property. + + + The list of properties associated with the object (definition). + + + The name of the element containing the property definition. + + + The namespace-aware parser. + + + + + Get the value of a property element (may be a list). + +

+ Please note that even though this method is named GetPropertyValue, + it is called by both the property and constructor argument element + handlers. +

+ + The property element. + + The name of the object associated with the property. + + + The namespace-aware parser. + + + + + Parse a value, ref or collection subelement of a property element. + + + Subelement of property element; we don't know which yet. + + + The name of the object (definition) associated with the top level property. + + + The namespace-aware parser. + + + + + Gets a list definition. + + + The element describing the list definition. + + + The name of the object (definition) associated with the list definition. + + + The namespace-aware parser. + + The list definition. + + + + Gets a set definition. + + + The element describing the set definition. + + + The name of the object (definition) associated with the set definition. + + + The namespace-aware parser. + + The set definition. + + + + Gets a dictionary definition. + + The element describing the dictionary definition. + The name of the object (definition) associated with the dictionary definition. + The namespace-aware parser. + The dictionary definition. + + + + Selects sub-elements with a given + name. + + +

+ Uses a namespace manager if necessary. +

+ + + The element to be searched in. + + + The name of the child nodes to look for. + + + The child s of the supplied + with the supplied + . + + + + + Selects a single sub-element with a given + name. + + +

+ Uses a namespace manager if necessary. +

+ + + The element to be searched in. + + + The name of the child node to look for. + + + The first child of the supplied + with the supplied + . + + + + + Gets a name value collection mapping definition. + + + The element describing the name value collection mapping definition. + + + The name of the object (definition) associated with the + name value collection mapping definition. + + the context carrying parsing state information + The name value collection definition. + + + + Returns the text of the supplied , + or the empty string value if said is empty. + + +

+ If the supplied is , + then the empty string value will be returned. +

+ + + + + Strips the dependency check value out of the supplied string. + + +

+ If the supplied is an invalid dependency + checking mode, the invalid value will be logged and this method will + return the value. + No exception will be raised. +

+ + + The string containing the dependency check value. + + The dependency check value. + + + + + Strips the autowiring mode out of the supplied string. + + +

+ If the supplied is an invalid autowiring mode, + the invalid value will be logged and this method will return the + value. No exception will be raised. +

+ + + The string containing the autowiring mode definition. + + The autowiring mode. + + + + + Given a string containing delimited object names, returns + a string array split on the object name delimeter. + + + The string containing delimited object names. + + + A string array split on the object name delimeter. + + + + + + Context that gets passed along an object definition parsing process, encapsulating + all relevant configuraiton as well as state. + + + + + Initializes a new instance of the class. + + The parser helper. + + + + Initializes a new instance of the class. + + The parser helper. + The containing object definition. + + + + Initializes a new instance of the class. + + The reader context. + The parser helper. + + + + Initializes a new instance of the class. + + The reader context. + The parser helper. + The containing object definition. + + + + Gets the reader context. + + The reader context. + + + + Gets the registry. + + The registry. + + + + Gets the parser helper. + + The parser helper. + + + + Gets the containing object definition. + + The containing object definition. + + + + Gets a value indicating whether this instance is nested. + + true if this instance is nested; otherwise, false. + + + + Gets a value indicating whether this instance is default lazy init. + + + true if this instance is default lazy init; otherwise, false. + + + + + Represents the replacement of a method on a managed object by the IoC + container. + + +

+ Note that this mechanism is not intended as a generic means of + inserting crosscutting code: use AOP for that. +

+ + Rod Johnson + Rick Evans (.NET) + + + + Creates a new instance of the + class. + + + The name of the method that is to be overridden. + + + The object name of the + instance in the surrounding IoC container. + + + If either of the supplied arguments is or + contains only whitespace character(s). + + + + + Add a fragment of a instance's + such as 'Exception or System.Excep to identify an argument + for a dependency injected method. + + + A (sub) string of a instance's . + + + If the supplied is or + contains only whitespace character(s). + + + + + + Does this + match the supplied ? + + The method to be checked. + + if this override matches the supplied . + + + If the supplied is . + + + + + A that represents the current + . + + + A that represents the current + . + + + + + The object name of the + instance in the surrounding IoC container. + + + + + Object definition reader for Spring's default XML object definition format. + + +

+ Typically applied to a + instance. +

+

+ This class registers each object definition with the given object factory superclass, + and relies on the latter's implementation of the + interface. +

+

+ It supports singletons, prototypes, and references to either of these kinds of object. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + Creates a new instance of the + class. + + + The + instance that this reader works on. + + + + + Creates a new instance of the + class. + + + The + instance that this reader works on. + + + The to be used for parsing. + + + + + Creates a new instance of the + class. + + + The + instance that this reader works on. + + + The to be used for parsing. + + the to use for creating new s + + + + Load object definitions from the supplied XML . + + + The XML resource for the object definitions that are to be loaded. + + + The number of object definitions that were loaded. + + + In the case of loading or parsing errors. + + + + + Actually load object definitions from the specified XML file. + + The input stream to read from. + The resource for the XML data. + + + + + Validation callback for a validating XML reader. + + The source of the event. + Any data pertinent to the event. + + + + Register the object definitions contained in the given DOM document. + + The DOM document. + + The original resource from where the + was read. + + + The number of object definitions that were registered. + + + In case of parsing errors. + + + + + Creates the to use for actually + reading object definitions from an XML document. + + Default implementation instantiates the specified + or if no reader type is specified. + + + + + Creates the to be passed along + during the object definition reading process. + + The underlying that is currently processed. + A new + + + + Create a instance for handling custom namespaces. + + + TODO (EE): make protected virtual, see remarks on + + + + + The to be used for parsing. + + + + + Sets the IObjectDefinitionDocumentReader implementation to use, responsible for + the actual reading of the XML object definition document.stype of the document reader. + + The type of the document reader. + + + + Specify a to use. If none is specified a default + instance will be created by + + + + + Specify a for creating instances of . + + + + + For retrying the parse process + + + + + Convenience extension of + + that reads object definitions from an XML document or element. + + +

+ Delegates to + + underneath; effectively equivalent to using a + for a + . +

+ + objects doesn't need to be the root element of + the XML document: this class will parse all object definition elements in the + XML stream. + +

+ This class registers each object definition with the + + superclass, and relies on the latter's implementation of the + interface. It supports + singletons, prototypes and references to either of these kinds of object. +

+ + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + + Creates a new instance of the class, + with the given resource, which must be parsable using DOM. + + + The XML resource to load object definitions from. + + + In the case of loading or parsing errors. + + + + + Creates a new instance of the class, + with the given resource, which must be parsable using DOM. + + + The XML resource to load object definitions from. + + Flag specifying whether to make this object factory case sensitive or not. + + In the case of loading or parsing errors. + + + + + Creates a new instance of the class, + with the given resource, which must be parsable using DOM, and the + given parent factory. + + + The XML resource to load object definitions from. + + The parent object factory (may be ). + + In the case of loading or parsing errors. + + + + + Creates a new instance of the class, + with the given resource, which must be parsable using DOM, and the + given parent factory. + + + The XML resource to load object definitions from. + + Flag specifying whether to make this object factory case sensitive or not. + The parent object factory (may be ). + + In the case of loading or parsing errors. + + + + + Gets object definition reader to use. + + + + + Extension of specific to use with an XmlObjectDefinitionReader. + Provides access to configured in + + + + + The maximum length of any XML fragment displayed in the error message + reporting. + + +

+ Hopefully this will display enough context so that a user + can pinpoint the cause of the error. +

+ + + + + Initializes a new instance of the class. + + The resource. + The reader. + + + + Initializes a new instance of the class. + + The resource. + The reader. + The factory to use for creating new instances. + + + + Generates the name of the object. + + The object definition. + the generated object name + + + + Registers the name of the with generated. + + The object definition. + the generated object name + + + + Reports a parse error by loading a + with helpful contextual + information and throwing said exception. + + +

+ Derived classes can of course override this method in order to implement + validators capable of displaying a full list of errors found in the + definition. +

+ + + The node that triggered the parse error. + + + The name of the object that triggered the exception. + + + A message about the exception. + + + Always throws an instance of this exception class, that will + contain helpful contextual infomation about the parse error. + + + + + + Reports a parse error by loading a + with helpful contextual + information and throwing said exception. + + +

+ Derived classes can of course override this method in order to implement + validators capable of displaying a full list of errors found in the + definition. +

+ + + The node that triggered the parse error. + + + The name of the object that triggered the exception. + + + A message about the error. + + + The root cause of the parse error (if any - may be ). + + + Always throws an instance of this exception class, that will + contain helpful contextual infomation about the parse error. + + + + + This method can be overwritten in order to implement validators + capable of displaying a full list of errors found in the definition. + + + The node that triggered the parse error. + + + A message about the exception. + + + + + Gets the reader. + + The reader. + + + + Gets the resource loader. + + The resource loader. + + + + Gets the registry. + + The registry. + + + + Gets or sets the object definition factory. + + The object definition factory. + + + + Get the instance to lookup parsers for custom namespaces. + + + + + Exception thrown if an + is not fully + initialized, for example if it is involved in a circular reference. + + +

+ This is usually indicated by any of the variants of the + + method returning . +

+

+ A circular reference with an + cannot be solved by eagerly caching singleton instances (as is the + case with normal objects. The reason is that every + needs to be fully + initialized before it can return the created object, while only specific + normal objects need to be initialized - that is, if a collaborating object + actually invokes them on initialization instead of just storing the reference. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + Thrown when an + encounters an error when attempting to create an object from an object + definition. + + Juergen Hoeller + Rick Evans (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The name of the object that triggered the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The name of the object that triggered the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The description of the resource associated with the object. + + + A message about the exception. + + + The name of the object that triggered the exception. + + + + + Creates a new instance of the + class. + + + The description of the resource associated with the object. + + + A message about the exception. + + + The name of the object that triggered the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + The name of the object that triggered the exception (if any). + + + + + The description of the resource associated with the object (if any). + + + + + Describes the creation failure trace of this exception. + + + + + Creates a new instance of the + FactoryObjectNotInitializedException class. + + + + + Creates a new instance of the FactoryObjectNotInitializedException class. + + + A message about the exception. + + + + + Creates a new instance of the FactoryObjectNotInitializedException class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + FactoryObjectCircularReferenceException class. + + + The name of the object that triggered the exception. + + + A message about the exception. + + + + + Creates a new instance of the FactoryObjectCircularReferenceException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception thrown when an + is asked for an object instance name for which it cannot find a definition. + + Rod Johnson + Rick Evans (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + Name of the missing object. + + + A further, detailed message describing the problem. + + + + + Initializes a new instance of the class. + + The required type of the object. + A description of the originating dependency. + A message describing the problem. + + + + Creates a new instance of the + class. + + + The of the missing object. + + + A further, detailed message describing the problem. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + Return the required of object, if it was a + lookup by that failed. + + + + + Return the name of the missing object, if it was a lookup by name that + failed. + + + + + Thrown in case of a reference to an object that is currently in creation. + + +

+ Typically happens when constructor autowiring matches the currently + constructed object. +

+ + Juergen Hoeller + Rick Evans + + + + The default error message text to be used, if none is specified. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The name of the object that triggered the exception. + + + + + Creates a new instance of the + class. + + + The name of the object that triggered the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The name of the object that triggered the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The name of the object that triggered the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The description of the resource associated with the object. + + + A message about the exception. + + + The name of the object that triggered the exception. + + + + + Creates a new instance of the + class. + + + The description of the resource associated with the object. + + + A message about the exception. + + + The name of the object that triggered the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the ObjectCurrentlyInCreationException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception thrown when an + encounters an error when attempting to parse an object + definition. + + Federico Spinazzi (.NET) + + + + Creates a new instance of the ObjectDefinitionException class. + + + + + Creates a new instance of the ObjectDefinitionException class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the ObjectDefinitionException class. + + + The value of the xml class attribute thet can be resolved + as a type + + + + + Creates a new instance of the ObjectDefinitionException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + The message about the exception. + + + + + Convenience methods operating on object factories, returning object instances, + names, or counts. + + +

+ The nesting hierarchy of an object factory is taken into account by the various methods + exposed by this class. +

+ + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + Used to dereference an + and distinguish it from managed objects created by the factory. + + +

+ For example, if the managed object identified as foo is a + factory, getting &foo will return the factory, not the + instance returned by the factory. +

+ + + + + The string used as a separator in the generation of synthetic id's + for those object definitions explicitly that aren't assigned one. + + +

+ If a name or parent object definition + name is not unique, "#1", "#2" etc will be appended, until such + time that the name becomes unique. +

+ + + + + Creates a new instance of the + class. + + +

+ This is a utility class, and as such has no publicly visible + constructors. +

+ + + + + Count all object definitions in any hierarchy in which this + factory participates. + + +

+ Includes counts of ancestor object factories. +

+

+ Objects that are "overridden" (specified in a descendant factory + with the same name) are counted only once. +

+ + The object factory. + + The count of objects including those defined in ancestor factories. + + + + + Return all object names in the factory, including ancestor factories. + + The object factory. + The array of object names, or an empty array if none. + + + + Get all object names for the given type, including those defined in ancestor + factories. + + +

+ Will return unique names in case of overridden object definitions. +

+

+ Does consider objects created by s + if is set to true, + which means that s will get initialized. +

+ + + If this isn't also an + , + this method will return the same as it's own + + method. + + + The that objects must match. + + + Whether to include prototype objects too or just singletons + (also applies to instances). + + + Whether to include instances + too or just normal objects. + + + The array of object names, or an empty array if none. + + + + + Get all object names for the given type, including those defined in ancestor + factories. + + +

+ Will return unique names in case of overridden object definitions. +

+

+ Does consider objects created by s, + or rather it considers the type of objects created by + (which means that + s will be instantiated). +

+ + + If this isn't also an + , + this method will return the same as it's own + + method. + + + The that objects must match. + + + The array of object names, or an empty array if none. + + + + + Return all objects of the given type or subtypes, also picking up objects + defined in ancestor object factories if the current object factory is an + . + + +

+ The return list will only contain objects of this type. + Useful convenience method when we don't care about object names. +

+ + The object factory. + The of object to match. + + Whether to include prototype objects too or just singletons + (also applies to instances). + + + Whether to include instances + too or just normal objects. + + + If the objects could not be created. + + + The of object instances, or an + empty if none. + + + + + Return a single object of the given type or subtypes, also picking up objects defined + in ancestor object factories if the current object factory is an + . + + +

+ Useful convenience method when we expect a single object and don't care + about the object name. +

+ + The object factory. + The of object to match. + + Whether to include prototype objects too or just singletons + (also applies to instances). + + + Whether to include instances + too or just normal objects. + + + If the object could not be created. + + + If more than one instance of an object was found. + + + A single object of the given type or subtypes. + + + + + Return a single object of the given type or subtypes, not looking in + ancestor factories. + + +

+ Useful convenience method when we expect a single object and don't care + about the object name. +

+ + The object factory. + The of object to match. + + Whether to include prototype objects too or just singletons + (also applies to instances). + + + Whether to include instances + too or just normal objects. + + + If the object could not be created. + + + If not exactly one instance of an object was found. + + + A single object of the given type or subtypes. + + + + + Return a single object of the given type or subtypes, not looking in + ancestor factories. + + +

+ Useful convenience method when we expect a single object and don't care + about the object name. + This version of ObjectOfType automatically includes prototypes and + instances. +

+ + The object factory. + The of object to match. + + If the object could not be created. + + + If not exactly one instance of an object was found. + + + A single object of the given type or subtypes. + + + + + Return the object name, stripping out the factory dereference prefix if necessary. + + The name of the object. + The object name sans any factory dereference prefix. + + + + Given an (object) name, builds a corresponding factory object name such that + the return value can be used as a lookup name for a factory object. + + + The name to be used to build the resulting factory object name. + + + The transformed into its factory object name + equivalent. + + + + + + + Is the supplied a factory dereference? + + +

+ That is, does the supplied begin with + the + ? +

+ + The name to check. + + if the supplied is a + factory dereference; if not, or the + aupplied is or + consists solely of the + + value. + + + + + + Exception that an object implementation is suggested to throw if its own + factory-aware initialization code fails. + thrown by object factory methods + themselves should simply be propagated as-is. + + +

+ Note that non-factory-aware initialization methods like AfterPropertiesSet () + or a custom "init-method" can throw any exception. +

+ + Juergen Hoeller + Rick Evans (.NET) + + + + Creates a new instance of the ObjectInitializationException class. + + + + + Creates a new instance of the ObjectInitializationException class. + + + A message about the exception. + + + + + Creates a new instance of the ObjectInitializationException class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the ObjectInitializationException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Thrown in response to an attempt to lookup a factory object, and + the object identified by the lookup key is not a factory. + + +

+ An object is a factory if it implements (either directly or indirectly + via inheritance) the + interface. +

+ + Rod Johnson + Rick Evans (.NET) + + + + Thrown when an object doesn't match the required . + + Rod Johnson + Rick Evans (.NET) + + + + Creates a new instance of the ObjectNotOfRequiredTypeException class. + + + + + Creates a new instance of the ObjectNotOfRequiredTypeException class. + + + A message about the exception. + + + + + Creates a new instance of the ObjectNotOfRequiredTypeException class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the ObjectNotOfRequiredTypeException class. + + + Name of the object requested. + + + The required of the actual object + instance that was retrieved. + + + The instance actually returned, whose class did not match the + expected . + + + + + Creates a new instance of the ObjectNotOfRequiredTypeException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + The actual of the actual object + instance that was retrieved. + + + + + The required of the actual object + instance that was retrieved. + + + + + The instance actually returned, whose class did not match the + expected . + + + + + The name of the object requested. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The name of the object that was being retrieved from the factory. + + + The object instance that was retrieved. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception thrown when an object depends on other objects or simple properties + that were not specified in the object factory definition, although dependency + checking was enabled. + + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + Creates a new instance of the UnsatisfiedDependencyException class. + + + + + Creates a new instance of the UnsatisfiedDependencyException class. + + + A message about the exception. + + + + + Creates a new instance of the UnsatisfiedDependencyException class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the UnsatisfiedDependencyException class. + + + The description of the resource associated with the object. + + + The name of the object that has the unsatisfied dependency. + + + The constructor argument index at which the dependency is + unsatisfied. + + + The of the constructor argument at + which the dependency is unsatisfied. + + + A message about the exception. + + + + + Creates a new instance of the UnsatisfiedDependencyException class. + + + The description of the resource associated with the object. + + + The name of the object that has the unsatisfied dependency. + + + The name identifying the property on which the dependency is + unsatisfied. + + + A message about the exception. + + + + + Creates a new instance of the UnsatisfiedDependencyException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Base class implementation for classes that describe an event handler. + + Rick Evans + + + + Describes an event handler. + + Rick Evans + + + + Wires up the specified handler to the named event on the + supplied event source. + + + The object (an object instance, a , etc) + exposing the named event. + + + The handler for the event (an object instance, a + , etc). + + + + + The source of the event. + + + + + The name of the method that is going to handle the event. + + + + + The name of the event that is being wired up. + + + + + Creates a new instance of the + class. + + +

+ This is an class, and as such exposes no public constructors. +

+ + + + + Creates a new instance of the + class. + + + The object (possibly unresolved) that is exposing the event. + + + The name of the method on the handler that is going to handle the event. + + +

+ This is an class, and as such exposes no public constructors. +

+ + + + + Wires up the specified handler to the named event on the + supplied event source. + + + The object (an object instance, a , etc) + exposing the named event. + + + The handler for the event (an object instance, a + , etc). + + + + + Returns a stringified representation of this object. + + A stringified representation of this object. + + + + The source of the event (may be unresolved, as in the case + of a + value). + + + + + The name of the method that is going to handle the event. + + + + + The name of the event that is being wired up. + + + + + Convenience base class for implementations. + + + + + Abstracts the state sharing strategy used + by + + Erich Eichinger + + + + Indicate, whether the given instance can be served by this factory + + the instance to serve state + the name of the instance + + a boolean value indicating, whether state can + be served for the given instance or not. + + + + + Returns the shared state for the given instance. + + the instance to obtain shared state for. + the name of this instance + a dictionary containing shared state for or null. + + + + Gets a dictionary acc. to the type of . + If no dictionary is found, create it according to + + the instance to obtain shared state for + the name of the instance. + + A dictionary containing the 's state, + or null if no state can be served by this provider. + + + + + Creates a dictionary to hold the shared state identified by . + + a key to create the dictionary for. + a dictionary according to and . + + + + Indicate, whether the given instance will be served by this provider + + the instance to serve state + the name of the instance + + a boolean value indicating, whether state shall + be resolved for the given instance or not. + + + + + Create the key used for obtaining the state dictionary for . + + the instance to create the key for + the name of the instance. + + the key identifying the state dictionary to be used for + or null, if this state manager doesn't serve the given instance. + + + + Implementations may choose to return null from this method to indicate, + that they won't serve state for the given instance. + + + Note:Keys returned by this method are always treated case-sensitive! + + + + + + Create shared state dictionaries case-sensitive or case-insensitive? + + + + + A number indicating the priority of this ( for more). + + + + + Base class for all + implemenations that actually perform event wiring. + + Rick Evans + + + + Creates a new instance of the + class. + + +

+ This is an class, and as such exposes no public constructors. +

+ + + + + Creates a new instance of the + class. + + + The object (possibly unresolved) that is exposing the event. + + + The name of the method on the handler that is going to handle the event. + + +

+ This is an class, and as such exposes no public constructors. +

+ + + + + Wires up the specified handler to the named event on the + supplied event source. + + + The object (an object instance, a , etc) + exposing the named event. + + + The handler for the event (an object instance, a + , etc). + + + + + Gets the event handler. + + + The instance that is registering for the event notification. + + + Event metadata about the event. + + + The event handler. + + + + + Resolves the method metadata that describes the method that is to be used + as the argument to a delegate constructor. + + + The exposing the method. + + + The of the delegate (e.g. System.EventHandler). + + + The custom binding flags to use when searching for the method. + + The method metadata. + + If the method could not be found. + + + + + Describes an implementation + that autowires events to handler methods. + + Rick Evans + + + + Creates a new instance of the + class. + + + + + Wires up the specified handler to the named event on the supplied event source. + + + The object (an object instance, a , etc) + exposing the named event. + + + The handler for the event (an object instance, a , + etc). + + + + + The name of the method that is going to handle the event. + + + + + Performs the matching up of handler methods to one or more source events. + + +

+ This class merely marshals the matching of handler methods to the events exposed + by an event source, and then delegates to a concrete + implementation (such as + or + ) to do the heavy lifting of + actually wiring a handler method to an event. +

+

+ Note : the order in which handler's are wired up to events is non-deterministic. +

+ + + + + Creates a new instance of the + class. + + + The object exposing the event (s) being wired up. + + + The name of the event that is being wired up. + + + The object exposing the method (s) being wired to the event. + + + The name of the method that is going to handle the event. + + + + + Wires up events on the source to methods exposed on the handler. + + + + + Wires up the supplied event to any handler methods that match the event + signature. + + The event being wired up. + + + + Only replaces the first occurrence of the placeholder. + + The event whose name is going to be used. + + The method name customised for the name of the supplied event. + + + + + The object exposing the event (s) being wired up. + + + + + The object exposing the method (s) being wired to an event source. + + + + + The of the object that is handling any events. + + + + + The name of the method that is going to handle the event. + + + + + The name of the event that is being wired up. + + + + + Serves shared state on a by-type basis. + + + + + Creates a new instance matching all types by default. + + + + + Creates a new instance matching only specified list of types. + + the list of types to serve. + + + + Indicate, whether the given instance will be served by this provider + + the instance to serve state + the name of the instance + + a boolean value indicating, whether state shall + be resolved for the given instance or not. + + + + + Returns the for the given . + + the instance to obtain the key for. + the name of the instance (ignored by this provider) + instance.GetType() if it matches the list. Null otherwise. + + This method will only be called if returned true previously. + + + + + Limit object types to be served by this state manager. + + + Only objects assignable to one of the types in this list + will be served state by this manager. + + + + + Describes an event handler for an object instance. + + Rick Evans + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The object (possibly unresolved) that is exposing the event. + + + The name of the method on the handler that is going to handle the event. + + + + + Gets the event handler. + + + The instance that is registering for the event notification. + + + Event metadata about the event. + + + The event handler. + + + + + Definition for sorting object instances by a property. + + Juergen Hoeller + Simon White (.NET) + + + + The name of the property to sort by. + + + + + Whether upper and lower case in string values should be ignored. + + + True if the sorting should be performed in a case-insensitive fashion. + + + + + If the sorting should be ascending or descending. + + + True if the sorting should be in the ascending order. + + + + + Mutable implementation of the + interface that + supports toggling the ascending value on setting the same property again. + + Juergen Hoeller + Jean-Pierre Pawlak + Simon White (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class using + the specified . + + + The to use + as a source for initial property values. + + + + + Creates a new instance of the + class. + + + The name of the property to sort by. + + + Whether upper and lower case in string values should be ignored. + + + Whether or not the sorting should be ascending or descending. + + + + + Creates a new instance of the + class. + + + Whether or not the + + property should be toggled if the same name is set on the + + property. + + + + + Overrides the default method + + + The object to test against this instance for equality. + + + True if the supplied is equal to this instance. + + + + + Overrides the default method. + + The hashcode for this instance. + + + + The name of the property to sort by. + + + + + Whether upper and lower case in string values should be ignored. + + + True if the sorting should be performed in a case-insensitive fashion. + + + + + If the sorting should be ascending or descending. + + + True if the sorting should be in the ascending order. + + + + + Performs a comparison of two objects, using the specified object property via + an . + + Juergen Hoeller + Jean-Pierre Pawlak + Simon White (.NET) + + + + Creates a new instance of the + class. + + + The to use for any + sorting. + + + If the supplied is . + + + + + Compares two objects and returns a value indicating whether one is less + than, equal to or greater than the other. + + The first object to compare. + The second object to compare. + + + + + Get the 's property + value for the given object. + + The object to get the property value for. + The property value. + + + + Sort the given according to the + given sort definition. + + + The to be sorted. + + The parameters to sort by. + + In the case of a missing property name. + + + If the supplied is . + + + + + Gets the to + use for any sorting. + + + The to use for + any sorting. + + + + + Describes an event handler for a static class method. + + Rick Evans + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The object (possibly unresolved) that is exposing the event. + + + The name of the method on the handler that is going to handle the event. + + + + + Gets the event handler. + + + The instance that is registering for the event notification. + + + Event metadata about the event. + + + The event handler. + + + + + The central interface of Spring.NET's low-level object infrastructure. + + +

+ Typically not directly used by application code but rather implicitly + via an . +

+

+ Implementing classes have the ability to get and set property values + (individually or in bulk), get property descriptors and query the + readability and writability of properties. +

+

+ This interface supports nested properties enabling the setting + of properties on subproperties to an unlimited depth. +

+

+ If a property update causes an exception, a + will be thrown. Bulk + updates continue after exceptions are encountered, throwing an exception + wrapping all exceptions encountered during the update. +

+

+ implementations can be used + repeatedly, with their "target" or wrapped object changed. +

+ + Rod Johnson + Mark Pollack (.NET) + + + Get the value of a property. + + The name of the property to get the value of. May be nested. + + The value of the property. + + if the property isn't readable, or if the getting the value throws + an exception. + + + + + Get the for a particular + property. + + + The property to be retrieved. + + + The for the particular + property. + + + + + Get the for a particular property. + + + The property the of which is to be retrieved. + + + The for a particular property.. + + + + + Get all of the instances for + all of the properties of the wrapped object. + + + An array of instances. + + + + + Set a property value. + + +

+ This is the preferred way to update an individual property. +

+ + The new property value. + + + + Set a property value. + + +

+ This method is provided for convenience only. The + + method is more powerful. +

+ + + The name of the property to set value of. + + The new property value. + + + Set a number of property values in bulk. + +

+ This is the preferred way to perform a bulk update. +

+

+ Note that performing a bulk update differs from performing a single update, + in that an implementation of this class will continue to update properties + if a recoverable error (such as a vetoed property change or a type + mismatch, but not an invalid property name or the like) is + encountered, throwing a + containing + all the individual errors. This exception can be examined later to see all + binding errors. Properties that were successfully updated stay changed. +

+

+ Does not allow the setting of unknown fields. Equivalent to + + with an argument of false for the second parameter. +

+ + + The collection of instances to + set on the wrapped object. + + + + + Set a number of property values in bulk with full control over behavior. + + +

+ Note that performing a bulk update differs from performing a single update, + in that an implementation of this class will continue to update properties + if a recoverable error (such as a vetoed property change or a type + mismatch, but not an invalid property name or the like) is + encountered, throwing a + containing + all the individual errors. This exception can be examined later to see all + binding errors. Properties that were successfully updated stay changed. +

+

Does not allow the setting of unknown fields. +

+ + + The to set on the target object + + + Should we ignore unknown values (not found in the object!?) + + + + + The object wrapped by the wrapper (cannot be ). + + +

+ Implementations are required to allow the type of the wrapped + object to change. +

+ + The object wrapped by this wrapper. + + + + Convenience method to return the + of the wrapped object. + + The of the wrapped object. + + + + A collection style container for + instances. + + Rod Johnson + Mark Pollack (.NET) + + + + Return the instance with the + given name. + + The name to search for. + the , or null if a + the with the supplied + did not exist in this collection. + + + + + Is there a instance for this + property name? + + The name to search for. + + True if there is a instance for + the supplied . + + + + + Return the difference (changes, additions, but not removals) of + property values between the supplied argument and the values + contained in the collection. + + +

+ Subclasses should also override Equals. +

+ + The old property values. + + An containing any changes, or + an empty instance if there were + no changes. + + + + + Return an array of the objects + held in this object. + + An array of the objects held + in this object. + + + + + This interface should be implemented by classes that want to + have access to the shared state. + + +

+ Shared state is very useful if you have data that needs to be shared by all instances + of e.g. the same webform (or other IHttpHandlers). +

+

+ For example, Spring.Web.UI.Page class implements this interface, which allows + each page derived from it to cache localizalization resources and parsed data binding + expressions only once and then reuse the cached values, regardless of how many instances + of the page are created. +

+ + + + + Gets or sets the that should be used + to store shared state for this instance. + + + + + Default implementation of the + interface. + + +

+ Allows simple manipulation of properties, and provides constructors to + support deep copy and construction from a number of collection types such as + and + . +

+ + Rod Johnson + Mark Pollack (.NET) + Rick Evans (.NET) + + + + The list of objects. + + + + + Creates a new instance of the + class. + + +

+ The returned instance is initially empty... + s can be added with the various + overloaded , + , + , + and + methods. +

+ + + + + + + Creates a new instance of the + class. + + +

+ Deep copy constructor. Guarantees + references are independent, although it can't deep copy objects currently + referenced by individual objects. +

+ + + + + Creates a new instance of the + class. + + + The with property values + keyed by property name, which must be a . + + + + + Overloaded version of Add that takes a property name and a property value. + + + The name of the property. + + + The value of the property. + + + + + Add the supplied object, + replacing any existing one for the respective property. + + + The object to add. + + + + + Merges the value of the supplied 'new' with that of + the current if merging is supported and enabled. + + + The new pv. + The current pv. + The possibly merged PropertyValue + + + + Add all property values from the given + . + + + The map of property values, the keys of which must be + s. + + + + + Add all property values from the given + . + + + The list of s to be added. + + + + + Remove the given , if contained. + + + The to remove. + + + + + Removes the named , if contained. + + + The name of the property. + + + + + Modify a object held in this object. Indexed from 0. + + + + + Return the property value given the name. + + + The property name is checked in a case-insensitive fashion. + + + The name of the property. + + + The property value. + + + + + Does the container of properties contain one of this name. + + The name of the property to search for. + + True if the property is contained in this collection, false otherwise. + + + + + Return the difference (changes, additions, but not removals) of + property values between the supplied argument and the values + contained in the collection. + + Another property values collection. + + The collection of property values that are different than the supplied one. + + + + + Returns an that can iterate + through a collection. + + +

+ The returned is the + exposed by the + + property. +

+ + + An that can iterate through a + collection. + + + + + Convert the object to a string representation. + + + A string representation of the object. + + + + + Property to retrieve the array of property values. + + + + + Default implementation of the + interface that should be sufficient for all normal uses. + + +

+ will convert + and array + values to the corresponding target arrays, if necessary. Custom + s that deal with + s or arrays can be written against a + comma delimited as + arrays are converted in such a format if the array itself is not assignable. +

+ + Rod Johnson + Juergen Hoeller + Jean-Pierre Pawlak + Mark Pollack (.NET) + Aleksandar Seovic(.NET) + + + The wrapped object. + + + + The ILog instance for this class. We'll create a lot of these objects, + so we don't want a new instance every time. + + + + + Creates a new instance of the class. + + +

+ The wrapped target instance will need to be set afterwards. +

+ + + + + + Creates a new instance of the class. + + + The object wrapped by this . + + + If the supplied is . + + + + + Creates a new instance of the class, + instantiating a new instance of the specified and using + it as the . + + +

+ Please note that the passed as the + argument must have a no-argument constructor. + If it does not, an exception will be thrown when this class attempts + to instantiate the supplied using it's + (non-existent) constructor. +

+ + + The to instantiate and wrap. + + + If the is , or if the + invocation of the s default (no-arg) constructor + fails (due to invalid arguments, insufficient permissions, etc). + + + + Gets the value of a property. + + The name of the property to get the value of. + + The value of the property. + + If there is no such property, if the property isn't readable, or + if getting the property value throws an exception. + + + + Gets the value of a property. + + The property expression that should be used to retrieve the property value. + + The value of the property. + + If there is no such property, if the property isn't readable, or + if getting the property value throws an exception. + + + + + Sets a property value. + + +

+ This method is provided for convenience only. The + + method is more powerful. +

+ + + The name of the property to set value of. + + The new value. + + + + Sets a property value. + + + The property expression that should be used to set the property value. + + The new value. + + + + Sets a property value. + + +

+ This is the preferred way to update an individual property. +

+ + + The object containing new property value. + + + + Set a number of property values in bulk. + +

+ Does not allow unknown fields. Equivalent to + + with and for + arguments. +

+ + + The to set on the target + object. + + + If an error is encountered while setting a property. + + + On a mismatch while setting a property, insufficient permissions, etc. + + + + + + Perform a bulk update with full control over behavior. + + +

+ This method may throw a reflection-based exception, if there is a critical + failure such as no matching field... less serious exceptions will be accumulated + and thrown as a single . +

+ + + The s to set on the target object. + + + Should we ignore unknown values (not found in the object!?). + + + If an error is encountered while setting a property (only thrown if the + parameter is set to ). + + + On a mismatch while setting a property, insufficient permissions, etc. + + + + + + Returns PropertyInfo for the specified property + + The name of the property to search for. + The for the specified property. + If cannot be determined. + + + + Get the for a particular property. + + + The property the of which is to be retrieved. + + + The for a particular property.. + + + + + Returns MemberInfo for the specified property or field + + The name of the property or field to search for. + The or for the specified property or field. + If does not resolve to a property or field. + + + + Get the properties of the wrapped object. + + + An array of s. + + + + + This method is expensive! Only call for diagnostics and debugging reasons, + not in production. + + + A string describing the state of this object. + + + + + Attempts to parse property expression first and falls back to full expression + if that fails. Performance optimization. + + Property expression to parse. + Parsed proeprty expression. + + + + The object wrapped by this . + + + If the object cannot be changed; or an attempt is made to set the + value of this property to . + + + + + Convenience method to return the of the wrapped object. + + +

+ Do not use this (convenience) method prior to setting the + property. +

+ + + The of the wrapped object. + + + If the property + is . + + + + + Return the collection of property descriptors. + + + + + Combined exception, composed of individual binding + s. + + +

+ An object of this class is created at the beginning of the binding + process, and errors added to it as necessary. +

+

+ The binding process continues when it encounters application-level + s, applying those changes + that can be applied and storing rejected changes in an instance of this class. +

+ + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + + + + Creates a new instance of the PropertyAccessExceptionsException class. + + + + + Creates a new instance of the PropertyAccessExceptionsException class. + + + A message about the exception. + + + + + Creates a new instance of the PropertyAccessExceptionsException class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Create new empty PropertyAccessExceptionsException. + We'll add errors to it as we attempt to bind properties. + + + + + Creates a new instance of the PropertyAccessExceptionsException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Populates a with + the data needed to serialize the target object. + + + The to populate + with data. + + + The destination (see ) + for this serialization. + + + + + The IObjectWrapper wrapping the target object at the root of the exception. + + + + The list of PropertyAccessException objects. + + + + Return the + for the supplied , or + if there isn't one. + + + + + Describe the number of exceptions contained in this container class. + + A description of the instance contents. + + + + Return the that generated + this exception. + + + + + Return the object we're binding to. + + + + + If this returns zero (0), no errors were encountered during binding. + + + + + Return an array of the s + stored in this object. + + +

+ Will return the empty array (not ) if there were no errors. +

+ + + + + Describe the group of exceptions. + + + + + Holds information and value for an individual property. + + +

+ Using an object here, rather than just storing all properties in a + map keyed by property name, allows for more flexibility, and the + ability to handle indexed properties in a special way if necessary. +

+

+ Note that the value doesn't need to be the final required + : an + implementation must + handle any necessary conversion, as this object doesn't know anything + about the objects it will be applied to. +

+ + Rod Johnson + Mark Pollack (.NET) + + + + Creates a new instance of the + class. + + The name of the property. + + The value of the property (possibly before type conversion). + + + If the supplied is or + contains only whitespace character(s). + + + + + Creates a new instance of the + class. + + The name of the property. + + The value of the property (possibly before type conversion). + + Pre-parsed property name. + + If the supplied or + is , or if the name contains only whitespace characters. + + + + + Print a string representation of the property. + + A string representation of the property. + + + + Determines whether the supplied + is equal to the current . + + The other instance. + + if they are equal in content. + + + + + Serves as a hash function for a particular type, suitable for use + in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + The name of the property. + The name of the property. + + + + Parsed property expression. + + + + + Return the value of the property. + + +

+ Note that type conversion will not have occurred here. + It is the responsibility of the + implementation to + perform type conversion. +

+ + The (possibly unresolved) value of the property. + + + + A simple pool implementation + + +

+ Based on the implementation found in Concurrent Programming in Java, + 2nd ed., by Doug Lea. +

+ + Doug Lea + Federico Spinazzi + Mark Pollack + + + + A simple pooling interface for managing and monitoring a pool + of objects. + + +

+ Based on the Jakarta Commons Pool API. +

+ + Federico Spinazzi + + + + + Obtain an instance from the pool. + + +

+ By contract, clients must return the borrowed + instance using + or a related method as defined in an implementation or + sub-interface. +

+ + An instance from the pool. + + In case the pool is unusable. + + + + + + Return an instance to the pool. + + +

+ By contract, the object must have been obtained using + + or a related method as defined in an implementation or sub-interface. +

+ + The instance to be returned to the pool. + + + + + Create an object using the factory set by + the property + or other implementation dependent mechanism + and place it into the pool. + + +

+ This is an optional operation. AddObject is useful for "pre-loading" a + pool with idle objects. +

+ + + If the implementation does not support the operation. + + + + + Close the pool and free any resources associated with it. + + + + + Clear objects sitting idle in the pool, releasing any + associated resources. + + +

+ This is an optional operation. +

+ + + If the implementation does not support the operation. + + + + + Gets the number of instances currently borrowed from the pool. + + +

+ This is an optional operation. +

+ + + If the implementation does not support the operation. + + + + + Gets the number of instances currently idle in the pool. + + +

+ This is an optional operation. +

+

+ This may be considered an approximation of the number of objects + that can be borrowed without creating any new instances. +

+ + + If the implementation does not support the operation. + + + + + Set the factory used to create new instances. + + +

+ This is an optional operation. +

+ + + If the implementation does not support the operation. + + + + + Set of permits + + + + + Creates a new instance of the + class. + + + The factory used to instantiate and manage the lifecycle of pooled objects. + + The initial size of the pool. + + If the supplied is . + + + If the supplied is less than or equal to zero. + + + + + Obtain an instance from the pool. + + + In case the pool is unusable. + + + + + + + Return an instance to the pool. + + The instance to be returned to the pool. + + + + + + Create an object using the factory set by + the property + or other implementation dependent mechanism + and place it into the pool. + + +

+ This implementation always throws a + . +

+ + + If the implementation does not support the operation. + + + + + Synchronized borrow logic. + + + + + + Synchronized release logic. + + + The object to release to the pool. + + + if the object was not a busy one. + + + + + Instantiates the supplied number of instances and adds + them to the pool. + + + The initial number of objects to build. + + + If the supplied number of is + less than or equal to zero. + + + + + Close the pool and free any resources associated with it. + + + + + Clear objects sitting idle in the pool, releasing any + associated resources. + + +

+ This implementation always throws a + . +

+ + + If the implementation does not support the operation. + + + + + Change the state of the pool to unusable. + + + + + Gets the number of instances currently borrowed from the pool. + + + If the implementation does not support the operation. + + + + + + Gets the number of instances currently idle in the pool. + + + If the implementation does not support the operation. + + + + + + Set the factory used to create new instances. + + +

+ This implementation always throws a + . +

+ + + If the implementation does not support the operation. + + + + + Defines lifecycle methods for objects that are to be used in an + implementation. + + +

+ The following methods summarize the contract between an + and an + an . +

+ + + + is called whenever a new instance is needed. + + + + is invoked on every instance before it is returned from + the pool. + + + + is invoked on every instance when it is returned to the pool. + + + + is invoked on every instance when it is being dropped from the + pool (see + + + +

+ Based on the Jakarta Commons Pool API. +

+ + Federico Spinazzi + + + + + Creates an instance that can be returned by the pool. + + + An instance that can be returned by the pool. + + + + + Destroys an instance no longer needed by the pool. + + +

+ Invoked on every instance when it is being "dropped" + from the pool (whether due to the return value from a call to the + + method, or for reasons specific to the pool implementation.) +

+ + The instance to be destroyed. + + + + Ensures that the instance is safe to be returned by the pool. + Returns false if this object should be destroyed. + + +

+ Invoked in an implementation-specific fashion to determine if an + instance is still valid to be returned by the pool. + It will only be invoked on an "activated" instance. +

+ + The instance to validate. + + if this object is not valid and + should be dropped from the pool, otherwise . + + + + + Reinitialize an instance to be returned by the pool. + + +

+ Invoked on every instance before it is returned from the pool. +

+ + The instance to be activated. + + + + Uninitialize an instance to be returned to the pool. + + +

+ Invoked on every instance when it is returned to the pool. +

+ + The instance returned to the pool. + + + + Base class for all pooling exceptions. + + Federico Spinazzi + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Base class for method builders that contains common functionalities. + + Bruno Baia + + + + Defines interface that proxy method builders have to implement. + + Aleksandar Seovic + Bruno Baia + + + + Dynamically builds proxy method. + + The method to proxy. + + The interface definition of the method, if applicable. + + + The for the proxy method. + + + + + The type builder to use. + + + + + The implementation to use. + + + + + Indicates whether interfaces should be implemented explicitly. + + + + + Creates a new instance of the method builder. + + The type builder to use. + + The implementation to use. + + + if the interface is to be + implemented explicitly; otherwise . + + + + + Dynamically builds proxy method. + + The method to proxy. + + The interface definition of the method, if applicable. + + + The for the proxy method. + + + + + Generates the IL instructions that pushes + the proxy instance on stack. + + The IL generator to use. + + + + Generates the IL instructions that pushes + the target instance on which calls should be delegated to. + + The IL generator to use. + + + + Defines proxy method for the target object. + + The method to proxy. + + The interface definition of the method, if applicable. + + + if the supplied is to be + implemented explicitly; otherwise . + + + The for the proxy method. + + + + + Defines generic method parameters based on proxied method metadata. + + + The to use. + + The method to proxy. + + + + Generates the proxy method. + + The IL generator to use. + The method to proxy. + + The interface definition of the method, if applicable. + + + + + Calls target method directly. + + The IL generator to use. + The method to invoke. + + + + Emits code to ensure that target on stack understands the method and throw a sensible exception otherwise. + + The IL generator to use. + The method to test for + the name of the target to be used in error messages + + + + Calls base method directly. + + The IL generator to use. + The method to proxy. + + + + Replaces a raw reference with a reference to a proxy. + + +

+ If the target object returns reference to itself -- 'this' -- + we need to treat it as a special case and return a reference + to a proxy object instead. +

+ + The IL generator to use. + The location of the return value. + + + + Generates code that throws . + + IL generator to use. + the type of the exception to throw + Error message to use. + + + + Base class for proxy builders that can be used + to create a proxy for any class. + + +

+ This class provides a set of template + methods that derived classes can override to provide custom behaviour + appropriate to the type of proxy that is being generated (one of + inheritance or composition-based proxying). +

+ + Aleksandar Seovic + Bruno Baia + + + + Describes the operations for a generic proxy type builder that can be + used to create a proxy type for any class. + + Aleksandar Seovic + + + + Creates the proxy type. + + The generated proxy class. + + + + The name of the proxy . + + The name of the proxy . + + + + The of the target object. + + + + + The of the class that the proxy must + inherit from. + + + + + Gets or sets the list of interfaces proxy should implement. + + + + + Should we proxy target attributes? + + + by default. + Target type attributes, method attributes, method's return type attributes + and method's parameter attributes are copied to the proxy. + + + + + The list of custom s that the proxy + class must be decorated with. + + +

+ Note that the list is composed of instances of the actual + s that are to be applied, not the + s of the s. +

+ + +

+ The following code snippets show examples of how to decorate the + the proxied class with one or more s. +

+ + // get a concrete implementation of an IProxyTypeBuilder... + IProxyTypeBuilder builder = ... ; + builder.TargetType = typeof( ... ); + + IDictionary typeAtts = new Hashtable(); + builder.TypeAttributes = typeAtts; + + // applies a single Attribute to the proxied class... + typeAtts = new Attribute[] { new MyCustomAttribute() }); + + // applies a number of Attributes to the proxied class... + typeAtts = new Attribute[] + { + new MyCustomAttribute(), + new AnotherAttribute(), + }); + + + + + + The custom s that the proxy + members must be decorated with. + + +

+ This dictionary must use simple s for keys + (denoting the member names that the attributes are to be applied to), + with the corresponding values being + s. +

+

+ The key may be wildcarded using the '*' character... if so, + then those proxy members that match against the key will be + decorated with the attendant list of + s. This naturally implies that using + the '*' character as a key will result in the attendant list + of s being applied to every member of + the proxied class. +

+ + +

+ The following code snippets show examples of how to decorate the + members of a proxied class with one or more + s. +

+ + // get a concrete implementation of an IProxyTypeBuilder... + IProxyTypeBuilder builder = ... ; + builder.TargetType = typeof( ... ); + + IDictionary memAtts = new Hashtable(); + builder.MemberAttributes = memAtts; + + // applies a single Attribute to all members of the proxied class... + memAtts ["*"] = new Attribute[] { new MyCustomAttribute() }); + + // applies a number of Attributes to all members of the proxied class... + memAtts ["*"] = new Attribute[] + { + new MyCustomAttribute(), + new AnotherAttribute(), + }); + + // applies a single Attribute to those members of the proxied class + // that have identifiers starting with 'Do' ... + memAtts ["Do*"] = new Attribute[] { new MyCustomAttribute() }); + + // applies a number of Attributes to those members of the proxied class + // that have identifiers starting with 'Do' ... + memAtts ["Do*"] = new Attribute[] + { + new MyCustomAttribute(), + new AnotherAttribute(), + }); + + + + + + Describes the operations that generates IL instructions + used to build the proxy type. + + Bruno Baia + + + + Generates the IL instructions that pushes + the proxy instance on stack. + + The IL generator to use. + + + + Generates the IL instructions that pushes + the target instance on which calls should be delegated to. + + The IL generator to use. + + + + The shared instance for this class (and derived classes). + + + + + Creates the proxy type. + + The generated proxy class. + + + + Generates the IL instructions that pushes + the proxy instance on stack. + + The IL generator to use. + + + + Generates the IL instructions that pushes + the target instance on which calls should be delegated to. + + The IL generator to use. + + + + Creates an appropriate type builder. + + The name to use for the proxy type name. + The type to extends if provided. + The type builder to use. + + + + Applies attributes to the proxy class. + + The type builder to use. + The proxied class. + + + + + + Applies attributes to the proxied method. + + The method builder to use. + The proxied method. + + + + + + Applies attributes to the proxied method's return type. + + The method builder to use. + The proxied method. + + + + + Applies attributes to proxied method's parameters. + + The method builder to use. + The proxied method. + + + + + Calculates and returns the list of attributes that apply to the + specified type. + + The type to find attributes for. + + A list of custom attributes that should be applied to type. + + + + + + + Calculates and returns the list of attributes that apply to the + specified method. + + The method to find attributes for. + + A list of custom attributes that should be applied to method. + + + + + + + Calculates and returns the list of attributes that apply to the + specified method's return type. + + The method to find attributes for. + + A list of custom attributes that should be applied to method's return type. + + + + + + Calculates and returns the list of attributes that apply to the + specified method's parameters. + + The method to find attributes for. + The method's parameter to find attributes for. + + A list of custom attributes that should be applied to the specified method's parameter. + + + + + + Check that the specified object is matching the passed attribute type. + + +

+ The specified object can be of different type : +

+ + + + + + System.Reflection.CustomAttributeData (Only with .NET 2.0) + + + + + + + The object instance to check. + The attribute type to test against. + + if the object instance matches the attribute type; + otherwise . + + + + + Defines the types of the parameters for the specified constructor. + + The constructor to use. + The types for constructor's parameters. + + + + Implements constructors for the proxy class. + + + The builder to use. + + + + + Generates the proxy constructor. + + The constructor builder to use. + The IL generator to use. + The constructor to use. + + + + Implements an interface. + + + Generates proxy methods that belongs to the interface + using the specified . + + The type builder to use. + + The implementation to use + + The interface to implement. + + The of the target object. + + + + + Implements an interface. + + + Generates proxy methods that belongs to the interface + using the specified . + + The type builder to use. + + The implementation to use + + The interface to implement. + + The of the target object. + + + if target virtual methods should not be proxied; + otherwise . + + + + + Gets the mapping of the interface to proxy + into the actual methods on the target type + that does not need to implement that interface. + + +

+ If the target type does not implement the interface, + we return the interfaces methods as the target methods for many reasons : +

    +
  • + The target object can change for an object that implements the interface. + (See 'Spring.Aop.Framework.DynamicProxy.IAdvisedProxyMethodBuilder' + implementation in the Spring AOP framework for an example) +
    • +
  • + Allow Transparent proxies to be proxied. + (See Spring Remoting framework for an example) +
    • +
  • + Allow null target to be proxied. + (See Spring AOP framework which avoid calls to the target object + by intercepting all methods. Think "dynamic mock") + (See 'Spring.Web.Services.WebServiceProxyFactory' implementation for another example) +
    • +
+

+ + + The of the target object. + + The interface to implement. + + An interface mapping for the interface to proxy. + + + + + Inherit from a type. + + + Generates proxy methods for base virtual methods + using the specified . + + + The builder to use for code generation. + + + The implementation to use to override base virtual methods. + + The to inherit from. + + + + Inherit from a type. + + + Generates proxy methods for base virtual methods + using the specified . + + + The builder to use for code generation. + + + The implementation to use to override base virtual methods. + + The to inherit from. + + if only members declared at the level + of the supplied 's hierarchy should be proxied; + otherwise . + + + + + Implements the specified . + + The type builder to use. + The type the property is defined on. + The property to proxy. + The implemented methods map. + + + + Implements the specified event. + + The type builder to use. + The type the event is defined on. + The event to proxy. + The implemented methods map. + + + + Returns an array of s that represent + the proxiable interfaces. + + + An interface is proxiable if it's not marked with the + . + + + The array of interfaces from which + we want to get the proxiable interfaces. + + + An array containing the interface s. + + + + + Checks if specified interface is of a special type + that should never be proxied (i.e. ISerializable). + + Interface type to check. + + true if it is, false otherwise. + + + + + The name of the proxy . + + The name of the proxy . + + + + The of the target object. + + + + + The of the class that the proxy must + inherit from. + + +

+ The default value of this property is the + . +

+ + + + + Gets or sets the list of interfaces proxy should implement. + + + The default value of this property is all the interfaces + implemented or inherited by the target type. + + + + + Should we proxy target attributes? + + + + + + The list of custom s that the proxy + class must be decorated with. + + + + + + The custom s that the proxy + members must be decorated with. + + + + + + Implementation of IProxyMethodBuilder that delegates method calls to the base class. + + Bruno Baia + + + + Creates a new instance of the method builder. + + The type builder to use. + + The implementation to use. + + + if the interface is to be + implemented explicitly; otherwise . + + + + + Generates the proxy method. + + The IL generator to use. + The method to proxy. + + The interface definition of the method, if applicable. + + + + + Builds a proxy type using composition. + + + + In order for this builder to work, the target must implement + one or more interfaces. + + + Aleksandar Seovic + Bruno Baia + + + + Target instance calls should be delegated to. + + + + + Creates a new instance of the + class. + + + + + Creates a proxy that delegates calls to an instance of the + target object. + + +

+ Only interfaces can be proxied using composition, so the target + must implement one or more interfaces. +

+ + The generated proxy class. + + If the + does not implement any interfaces. + + + + + Create an to create interface implementations + + + + + Allows subclasses to generate additional code + + + + + Generates the IL instructions that pushes + the target instance on which calls should be delegated to. + + The IL generator to use. + + + + Deaclares a field that holds the target object instance. + + + The builder to use for code generation. + + + + + Generates the proxy constructor. + + +

+ This implementation creates instance of the target object for delegation + using constructor arguments. +

+ + The constructor builder to use. + The IL generator to use. + The constructor to delegate the creation to. + + + + Gets or sets a value indicating whether interfaces should be implemented explicitly. + + + if they should be; otherwise, . + + + + + Allows easy access to existing and creation of new dynamic proxies. + + Aleksandar Seovic + Bruno Baia + + + + The name of the assembly that defines proxy types created. + + + + + The attributes of the proxy type to generate. + + + + + Creates an appropriate type builder. + + The proxy type name. + The type to extends if provided. + The type builder to use. + + + + Saves dynamically generated assembly to disk. + Can only be called in DEBUG_DYNAMIC mode, per ConditionalAttribute rules. + + + + + Builds a proxy type using inheritance. + + + + In order for this builder to work, target methods have to be either + , or belong to an interface. + + + Aleksandar Seovic + Bruno Baia + + + + Creates a new instance of the + class. + + + + + Creates a proxy that inherits the proxied object's class. + + +

+ Only (non-final) methods can be proxied, + unless they are members of one of the interfaces that target class + implements. In that case, methods will be proxied using explicit + interface implementation, which means that client code will have + to cast the proxy to a specific interface in order to invoke the + methods. +

+ + The generated proxy class. + + + + Generates the IL instructions that pushes + the target instance on which calls should be delegated to. + + The IL generator to use. + + + + Generates the proxy constructor. + + +

+ This implementation delegates the call to a base class constructor. +

+ + The constructor builder to use. + The IL generator to use. + + The base class constructor to delegate the call to. + + + + + Gets or sets a value indicating whether inherited members should be proxied. + + + if they should be; otherwise, . + + + + + This attribute can be used to mark interfaces that should not be proxied + + Bruno Baia + + + + Creates a new instance of the + class. + + + + + Implementation of IProxyMethodBuilder that delegates method calls to target object. + + Bruno Baia + + + + Creates a new instance of the method builder. + + The type builder to use. + + The implementation to use. + + + if the interface is to be + implemented explicitly; otherwise . + + + + + Generates the proxy method. + + The IL generator to use. + The method to proxy. + + The interface definition of the method, if applicable. + + + + + Base class for dynamic members. + + Aleksandar Seovic + + + + Method attributes constant. + + + + + Sets up target instance for invocation. + + IL generator to use. + Type of target instance. + + + + Sets up invocation argument. + + IL generator to use. + Argument type. + Argument position. + + + + Generates method invocation code. + + IL generator to use. + Flag specifying whether method is static. + Flag specifying whether method is on the value type. + Method to invoke. + + + + Generates code to process return value if necessary. + + IL generator to use. + Type of the return value. + + + + Generates code that throws . + + IL generator to use. + Error message to use. + + + + Defines constructors that dynamic constructor class has to implement. + + + + + Invokes dynamic constructor. + + + Constructor arguments. + + + A constructor value. + + + + + Safe wrapper for the dynamic constructor. + + + will attempt to use dynamic + constructor if possible, but it will fall back to standard + reflection if necessary. + + + + + Obtains cached constructor info or creates a new entry, if none is found. + + + + + Creates a new instance of the safe constructor wrapper. + + Constructor to wrap. + + + + Invokes dynamic constructor. + + + Constructor arguments. + + + A constructor value. + + + + + Factory class for dynamic constructors. + + Aleksandar Seovic + + + + Creates dynamic constructor instance for the specified . + + Constructor info to create dynamic constructor for. + Dynamic constructor for the specified . + + + + Defines methods that dynamic field class has to implement. + + + + + Gets the value of the dynamic field for the specified target object. + + + Target object to get field value from. + + + A field value. + + + + + Gets the value of the dynamic field for the specified target object. + + + Target object to set field value on. + + + A new field value. + + + + + Safe wrapper for the dynamic field. + + + will attempt to use dynamic + field if possible, but it will fall back to standard + reflection if necessary. + + + + + Obtains cached fieldInfo or creates a new entry, if none is found. + + + + + Creates a new instance of the safe field wrapper. + + Field to wrap. + + + + Gets the value of the dynamic field for the specified target object. + + + Target object to get field value from. + + + A field value. + + + + + Gets the value of the dynamic field for the specified target object. + + + Target object to set field value on. + + + A new field value. + + + + + Holds cached Getter/Setter delegates for a Field + + + + + Factory class for dynamic fields. + + Aleksandar Seovic + + + + Creates dynamic field instance for the specified . + + Field info to create dynamic field for. + Dynamic field for the specified . + + + + Defines methods that dynamic indexer class has to implement. + + + + + Gets the value of the dynamic indexer for the specified target object. + + + Target object to get the indexer value from. + + + Indexer argument. + + + A indexer value. + + + + + Gets the value of the dynamic indexer for the specified target object. + + + Target object to get the indexer value from. + + + Indexer argument. + + + A indexer value. + + + + + Gets the value of the dynamic indexer for the specified target object. + + + Target object to get the indexer value from. + + + Indexer arguments. + + + A indexer value. + + + + + Gets the value of the dynamic indexer for the specified target object. + + + Target object to set the indexer value on. + + + Indexer argument. + + + A new indexer value. + + + + + Gets the value of the dynamic indexer for the specified target object. + + + Target object to set the indexer value on. + + + Indexer argument. + + + A new indexer value. + + + + + Gets the value of the dynamic indexer for the specified target object. + + + Target object to set the indexer value on. + + + Indexer arguments. + + + A new indexer value. + + + + + Safe wrapper for the dynamic indexer. + + + will attempt to use dynamic + indexer if possible, but it will fall back to standard + reflection if necessary. + + + + + Creates a new instance of the safe indexer wrapper. + + Indexer to wrap. + + + + Gets the value of the dynamic indexer for the specified target object. + + + Target object to get indexer value from. + + + Indexer arguments. + + + A indexer value. + + + + + Gets the value of the dynamic indexer for the specified target object. + + + Target object to get the indexer value from. + + + Indexer argument. + + + A indexer value. + + + + + Gets the value of the dynamic indexer for the specified target object. + + + Target object to get indexer value from. + + + Indexer arguments. + + + A indexer value. + + + + + Sets the value of the dynamic indexer for the specified target object. + + + Target object to set indexer value on. + + + Indexer arguments. + + + A new indexer value. + + + + + Sets the value of the dynamic indexer for the specified target object. + + + Target object to set indexer value on. + + + Indexer arguments. + + + A new indexer value. + + + + + Sets the value of the dynamic indexer for the specified target object. + + + Target object to set indexer value on. + + + Indexer arguments. + + + A new indexer value. + + + + + Internal PropertyInfo accessor. + + + + + Factory class for dynamic indexers. + + Aleksandar Seovic + + + + Prevent instantiation + + + + + Creates dynamic indexer instance for the specified . + + Indexer info to create dynamic indexer for. + Dynamic indexer for the specified . + + + + Defines methods that dynamic method class has to implement. + + + + + Invokes dynamic method on the specified target object. + + + Target object to invoke method on. + + + Method arguments. + + + A method return value. + + + + + Safe wrapper for the dynamic method. + + + will attempt to use dynamic + method if possible, but it will fall back to standard + reflection if necessary. + + + + + Creates a new instance of the safe method wrapper. + + Method to wrap. + + + + Invokes dynamic method. + + + Target object to invoke method on. + + + Method arguments. + + + A method return value. + + + + + Gets the class, that declares this method + + + + + Factory class for dynamic methods. + + Aleksandar Seovic + + + + Creates dynamic method instance for the specified . + + Method info to create dynamic method for. + Dynamic method for the specified . + + + + Defines methods that dynamic property class has to implement. + + + + + Gets the value of the dynamic property for the specified target object. + + + Target object to get property value from. + + + A property value. + + + + + Gets the value of the dynamic property for the specified target object. + + + Target object to set property value on. + + + A new property value. + + + + + Gets the value of the dynamic property for the specified target object. + + + Target object to get property value from. + + Optional index values for indexed properties. This value should be null reference for non-indexed properties. + + A property value. + + + + + Gets the value of the dynamic property for the specified target object. + + + Target object to set property value on. + + + A new property value. + + Optional index values for indexed properties. This value should be null reference for non-indexed properties. + + + + Safe wrapper for the dynamic property. + + + will attempt to use dynamic + property if possible, but it will fall back to standard + reflection if necessary. + + + + + Obtains cached property info or creates a new entry, if none is found. + + + + + Creates a new instance of the safe property wrapper. + + Property to wrap. + + + + Gets the value of the dynamic property for the specified target object. + + + Target object to get property value from. + + + A property value. + + + + + Gets the value of the dynamic property for the specified target object. + + + Target object to get property value from. + + Optional index values for indexed properties. This value should be null reference for non-indexed properties. + + A property value. + + + + + Gets the value of the dynamic property for the specified target object. + + + Target object to set property value on. + + + A new property value. + + + + + Gets the value of the dynamic property for the specified target object. + + + Target object to set property value on. + + + A new property value. + + Optional index values for indexed properties. This value should be null reference for non-indexed properties. + + + + Internal PropertyInfo accessor. + + + + + Holds cached Getter/Setter delegates for a Property + + + + + Factory class for dynamic properties. + + Aleksandar Seovic + + + + Creates safe dynamic property instance for the specified . + + +

This factory method will create a dynamic property with a "safe" wrapper.

+

Safe wrapper will attempt to use generated dynamic property if possible, + but it will fall back to standard reflection if necessary.

+ + Property info to create dynamic property for. + Safe dynamic property for the specified . + + + + + Creates dynamic property instance for the specified . + + Property info to create dynamic property for. + Dynamic property for the specified . + + + + Represents a Get method + + the target instance when calling an instance method + the value return by the Get method + + + + Represents a Set method + + the target instance when calling an instance method + the value to be set + + + + Represents an Indexer Get method + + the target instance when calling an instance method + + the value return by the Get method + + + + Represents a Set method + + the target instance when calling an instance method + the value to be set + + + + + Represents a method + + the target instance when calling an instance method + arguments to be passed to the method + the value return by the method. null when calling a void method + + + + Represents a constructor + + arguments to be passed to the method + the new object instance + + + + Represents a callback method used to create an from a instance. + + + + + Represents a callback method used to create an from a instance. + + + + + Represents a callback method used to create an from a instance. + + + + + Represents a callback method used to create an from a instance. + + + + + Represents a callback method used to create an from a instance. + + + + + Allows easy access to existing and creation of new dynamic relection members. + + Aleksandar Seovic + + + + The name of the assembly that defines reflection types created. + + + + + The attributes of the reflection type to generate. + + + + + Cache for dynamic property types. + + + + + Cache for dynamic field types. + + + + + Cache for dynamic indexer types. + + + + + Cache for dynamic method types. + + + + + Cache for dynamic constructor types. + + + + + Creates an appropriate type builder. + + + The base name to use for the reflection type name. + + The type builder to use. + + + + Returns dynamic property if one exists. + + Property to look up. + callback function that will be called to create the dynamic property + An for the given property info. + + + + Returns dynamic field if one exists. + + Field to look up. + callback function that will be called to create the dynamic field + An for the given field info. + + + + Returns dynamic indexer if one exists. + + Indexer to look up. + callback function that will be called to create the dynamic indexer + An for the given indexer. + + + + Returns dynamic method if one exists. + + Method to look up. + callback function that will be called to create the dynamic method + An for the given method. + + + + Returns dynamic constructor if one exists. + + Constructor to look up. + callback function that will be called to create the dynamic constructor + An for the given constructor. + + + + Saves dynamically generated assembly to disk. + Can only be called in DEBUG mode, per ConditionalAttribute rules. + + + + + Create a new Get method delegate for the specified field using + + the field to create the delegate for + a delegate that can be used to read the field + + + + Create a new Set method delegate for the specified field using + + the field to create the delegate for + a delegate that can be used to read the field. + + If the field's returns true, the returned method + will throw an when called. + + + + + Create a new Get method delegate for the specified property using + + the property to create the delegate for + a delegate that can be used to read the property. + + If the property's returns false, the returned method + will throw an when called. + + + + + Create a new Set method delegate for the specified property using + + the property to create the delegate for + a delegate that can be used to write the property. + + If the property's returns false, the returned method + will throw an when called. + + + + + Create a new method delegate for the specified method using + + the method to create the delegate for + a delegate that can be used to invoke the method. + + + + Creates a new delegate for the specified constructor. + + the constructor to create the delegate for + delegate that can be used to invoke the constructor. + + + + Creates a instance with the highest possible code access security. + + + If allowed by security policy, associates the method with the s declaring type. + Otherwise associates the dynamic method with . + + + + + Delegates a Method(object target, params object[] args) call to the actual underlying method. + + + + + Generates code to process return value if necessary. + + IL generator to use. + Type of the return value. + + + + Converts to an instance of if necessary to + e.g. avoid e.g. double/int cast exceptions. + + + + This method mimics the behavior of the compiler that + automatically performs casts like int to double in "Math.Sqrt(4)".
+ See about implicit, widening type conversions on MSDN - Type Conversion Tables + + + Note: is expected to be a value type! + + + + + + Generates code that throws . + + IL generator to use. + Error message to use. + + + + Indicates that an annotated class is a "component". + Such classes are considered as candidates for future features such + as auto-detection when using attribute-based configuration and assembly scanning. + + Other class-level annotations may be considered as identifying + a component as well, typically a special kind of component: + e.g. the Repository attribute. + + Mark Fisher + Mark Pollack (.NET) + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The name of the component. + + + + Gets or sets the name of the component + + The name of the component. + + + + Indicates that an annotated class is a "Repository" (or "DAO"). + + + A class with this attribute is eligible for Spring DataAccessException translation. A class + with the Repository attribute is also clarified as to its role in the overall application + architecture for the purpose of tools, aspects, etc. + + This attribute also serves as a specialization of the ComponentAttribute, allowing implementation + classes to be autodetected in future releases through assembly scanning. + + + Rod Johnson + Jueren Hoeller + Mark Pollack (.NET) + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The name of the repository. + + + + Indicates that an annotated class is a "Service" (e.g. a business service facade). + + + + This attribute also serves as a specialization of the ComponentAttribute, allowing implementation + classes to be autodetected in future releases through assembly scanning. + + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The name. + + + + Implements by using . + + Erich Eichinger + + + + Specifies the contract a strategy must be implement to store and + retrieve data that is specific to the executing thread. + + + All implementations of this interface must treat keys case-sensitive. + + Erich Eichinger + + + + Retrieves an object with the specified . + + The name of the item. + + The object in the current thread's context associated with the + specified or null if no object has been stored previously + + + + + Stores a given object and associates it with the specified . + + The name with which to associate the new item. + The object to store in the current thread's context. + + + + Empties a data slot with the specified name. + + + If the object with the specified is not found, the method does nothing. + + The name of the object to remove. + + + + Retrieves an object with the specified name. + + The name of the item. + The object in the call context associated with the specified name or null if no object has been stored previously + + + + Stores a given object and associates it with the specified name. + + The name with which to associate the new item. + The object to store in the call context. + + + + Empties a data slot with the specified name. + + The name of the data slot to empty. + + + + Acquire/Release protocol, base of many concurrency utilities. + + + +

objects isolate waiting and notification for particular logical + states, resource availability, events, and the like that are shared + across multiple threads.

+ +

Use of s sometimes (but by no means always) adds + flexibility and efficiency compared to the use of plain + .Net monitor methods and locking, and are sometimes (but by no means + always) simpler to program with.

+ +

Used for implementation of a

+ + + Doug Lea + Federico Spinazzi (.Net) + + + Wait (possibly forever) until successful passage. + Fail only upon interuption. Interruptions always result in + `clean' failures. On failure, you can be sure that it has not + been acquired, and that no + corresponding release should be performed. Conversely, + a normal return guarantees that the acquire was successful. + + + + + Potentially enable others to pass. +

+ Because release does not raise exceptions, + it can be used in `finally' clauses without requiring extra + embedded try/catch blocks. But keep in mind that + as with any java method, implementations may + still throw unchecked exceptions such as Error or NullPointerException + when faced with uncontinuable errors. However, these should normally + only be caught by higher-level error handlers. +

+ + + + + Wait at most msecs to pass; report whether passed. +

+ The method has best-effort semantics: + The msecs bound cannot + be guaranteed to be a precise upper bound on wait time in Java. + Implementations generally can only attempt to return as soon as possible + after the specified bound. Also, timers in Java do not stop during garbage + collection, so timeouts can occur just because a GC intervened. + So, msecs arguments should be used in + a coarse-grained manner. Further, + implementations cannot always guarantee that this method + will return at all without blocking indefinitely when used in + unintended ways. For example, deadlocks may be encountered + when called in an unintended context. +

+ + the number of milleseconds to wait + An argument less than or equal to zero means not to wait at all. + However, this may still require + access to a synchronization lock, which can impose unbounded + delay if there is a lot of contention among threads. + + true if acquired + + + A latch is a boolean condition that is set at most once, ever. + Once a single release is issued, all acquires will pass. +

+ Sample usage. Here are a set of classes that use + a latch as a start signal for a group of worker threads that + are created and started beforehand, and then later enabled. +

+ + class Worker implements IRunnable { + private readonly Latch startSignal; + Worker(Latch l) + { + startSignal = l; + } + + public void Run() { + startSignal.acquire(); + DoWork(); + } + + void DoWork() { ... } + } + + class Driver { // ... + void Main() { + Latch go = new Latch(); + for (int i = 0; i < N; ++i) // make threads + new Thread(new ThreadStart(new Worker(go)).Start(); + DoSomethingElse(); // don't let run yet + go.Release(); // let all threads proceed + } + } + + + Doug Lea + Federico Spinazzi (.Net) + + + + can acquire ? + + + + + Method mainly used by clients who are trying to get the latch + + + + Wait at most msecs millisconds for a permit + + + + Enable all current and future acquires to pass + + + + + An abstraction to safely store "ThreadStatic" data. + + + By default, is used to store thread-specific data. + You may switch the storage strategy by calling .

+ NOTE: Access to the underlying storage is not synchronized for performance reasons. + You should call only once at application startup! + + Erich Eichinger + + +

+ Holds the current strategy. + + + Access to this variable is not synchronized on purpose for performance reasons. + Setting a different strategy should happen only once + at application startup. + + + + + Set the new strategy. + + + + + Retrieves an object with the specified name. + + The name of the item. + The object in the context associated with the specified name or null if no object has been stored previously + + + + Stores a given object and associates it with the specified name. + + The name with which to associate the new item. + The object to store in the current thread's context. + + + + Empties a data slot with the specified name. + + The name of the data slot to empty. + + + +

Base class for counting semaphores based on Semaphore implementation + from Doug Lea.

+ + + +

Conceptually, a semaphore + maintains a set of permits. Each acquire() blocks if + necessary until a permit is available, and then takes it.

+ +

Each release adds a permit. However, no actual permit objects are used; + the Semaphore just keeps a count of the number available + and acts accordingly.

+ +

A semaphore initialized to 1 can serve as a mutual exclusion lock.

+ + Used for implementation of a + + Doug Lea + Federico Spinazzi (.Net) + + + + current number of available permits + + + + +

Create a Semaphore with the given initial number of permits.

+

Using a seed of 1 makes the semaphore act as a mutual + exclusion lock.

+ +

Negative seeds are also allowed, + in which case no acquires will proceed until the number of + releases has pushed the number of permits past 0.

+ + + + + Release a permit + + + + + Acquire a permit + + + + + Wait at most msecs millisconds for a permit + + number of ms to wait + true if aquired + + + Release N permits. release(n) is + equivalent in effect to: + 
+            for (int i = 0; i < n; ++i) release();
+
+ But may be more efficient in some semaphore implementations. + + if n is negative. + + + + + Return the current number of available permits. + Returns an accurate, but possibly unstable value, + that may change immediately after returning. + + + + + Utility class to use an with the + C# using () {} idiom + + + + + Creates a new trying to the given + + + the to be held + + + + Creates a new trying to the given + + + the to be held + millisecond to try to acquire the lock + + + + Releases the held + + + + + initializes and acquire access to the + + + + + + Implements by using a hashtable. + + Erich Eichinger + + + + Retrieves an object with the specified name. + + The name of the item. + The object in the call context associated with the specified name or null if no object has been stored previously + + + + Stores a given object and associates it with the specified name. + + The name with which to associate the new item. + The object to store in the call context. + + + + Empties a data slot with the specified name. + + The name of the data slot to empty. + + + Thrown by synchronization classes that report + timeouts via exceptions. The exception is treated + as a form (subclass) of InterruptedException. This both + simplifies handling, and conceptually reflects the fact that + timed-out operations are artificially interrupted by timers. + + + + + The approximate time that the operation lasted before + this timeout exception was thrown. + + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class with the + specified message. + + + A message about the exception. + + + + + Creates a new instance of the + class with the + specified message. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Override of GetObjectData to allow for private serialization + + serialization info + streaming context + + + Constructs a TimeoutException with given duration value. + + + + + Constructs a TimeoutException with the + specified duration value and detail message. + + + + + Gets the approximate time that the operation lasted before + this timeout exception was thrown. + + + + A TimeoutSync is an adaptor class that transforms all + calls to acquire to instead invoke attempt with a predetermined + timeout value. + + + + + + the adapted sync + + + + + timeout value + + + + Create a TimeoutSync using the given Sync object, and + using the given timeout value for all calls to acquire. + + + + + Try to acquire the sync before the timeout + + In case a time out occurred + + + + + + + + + + + + + + Support to account for differences between java nad .NET: +
    +
+ + + + + .NET threads have not a method to check if they have been interrupted. + Moreover, differently from java threads, when entering locked + blocks, Monitor, Sleep, SpinWait and so on, a + will be raised by the runtime. +

Spring.Threading classes usually call this method before entering a lock block, to mirror java code +

Usually this is non issue because the same exception will be raised entering the monitor + associated with the lock () +

+ + if the thread has been interrupted + + + + Normalize the given so that + is is comparable with . + + Date. + + + + + + + + + the difference between millisecodns of the first and second date + + + + Returns the number of nanoseconds for the current value of + + Current number of nanoseconds + + + + Returns the number of nano seconds represented by the + + to use + Number of nano seconds for + + + + Returns a representing the number of nanoseconds passed in via . + + Number of nanoseconds. + representing the number of nanoseconds passed in. + + + + Placeholder for java.lang.System.currentTimeMillis + + The current machine time in milliseconds + + + + Has been interrupted this thread + + + + + Miscellaneous generic collection utility methods. + + + Mainly for internal use within the framework. + + Mark Pollack (.NET) + + + + Determine whether a given collection only contains + a single unique object + + + + + + + Determines whether the contains the specified . + + The collection to check. + The object to locate in the collection. + if the element is in the collection, otherwise. + + + + Determines whether the collection contains all the elements in the specified collection. + + The collection to check. + Collection whose elements would be checked for containment. + true if the target collection contains all the elements of the specified collection. + + + + Removes all the elements from the target collection that are contained in the source collection. + + Collection where the elements will be removed. + Elements to remove from the target collection. + + + + Various utility methods relating to the manipulation of arrays. + + Aleksandar Seovic + + + + Checks if the given array or collection has elements and none of the elements is null. + + the collection to be checked. + true if the collection has a length and contains only non-null elements. + + + + Use this sort method instead of to overcome + bugs in Mono. + + + + + Checks if the given array or collection is null or has no elements. + + + + + + + Tests equality of two single-dimensional arrays by checking each element + for equality. + + The first array to be checked. + The second array to be checked. + True if arrays are the same, false otherwise. + + + + Returns hash code for an array that is generated based on the elements. + + + Hash code returned by this method is guaranteed to be the same for + arrays with equal elements. + + + Array to calculate hash code for. + + + A hash code for the specified array. + + + + + Returns string representation of an array. + + + Array to return as a string. + + + String representation of the specified . + + + + + Concatenates 2 arrays of compatible element types + + + If either of the arguments is null, the other array is returned as the result. + The array element types may differ as long as they are assignable. The result array will be of the "smaller" element type. + + + + + Assertion utility methods that simplify things such as argument checks. + + +

+ Not intended to be used directly by applications. +

+ + Aleksandar Seovic + Erich Eichinger + + + + Checks, whether may be invoked on . + Supports testing transparent proxies. + + the target instance or null + the name of the target to be used in error messages + the method to test for + + if is null + + + if it is not possible to invoke on + + + + + checks, whether supports the methods of . + Supports testing transparent proxies. + + the target instance or null + the name of the target to be used in error messages + the type to test for + + if is null + + + if it is not possible to invoke methods of + type on + + + + + Checks the value of the supplied and throws an + if it is . + + The object to check. + The argument name. + + If the supplied is . + + + + + Checks the value of the supplied and throws an + if it is . + + The object to check. + The argument name. + + An arbitrary message that will be passed to any thrown + . + + + If the supplied is . + + + + + Checks the value of the supplied string and throws an + if it is or + contains only whitespace character(s). + + The string to check. + The argument name. + + If the supplied is or + contains only whitespace character(s). + + + + + Checks the value of the supplied string and throws an + if it is or + contains only whitespace character(s). + + The string to check. + The argument name. + + An arbitrary message that will be passed to any thrown + . + + + If the supplied is or + contains only whitespace character(s). + + + + + Checks the value of the supplied and throws + an if it is or contains no elements. + + The array or collection to check. + The argument name. + + If the supplied is or + contains no elements. + + + + + Checks the value of the supplied and throws + an if it is or contains no elements. + + The array or collection to check. + The argument name. + An arbitrary message that will be passed to any thrown . + + If the supplied is or + contains no elements. + + + + + Checks the value of the supplied and throws + an if it is , contains no elements or only null elements. + + The array or collection to check. + The argument name. + + If the supplied is , + contains no elements or only null elements. + + + + + Checks whether the specified can be cast + into the . + + + The argument to check. + + + The name of the argument to check. + + + The required type for the argument. + + + An arbitrary message that will be passed to any thrown + . + + + + + Assert a boolean expression, throwing ArgumentException + if the test result is false. + + a boolean expression. + The exception message to use if the assertion fails. + + if expression is false + + + + + Assert a boolean expression, throwing ArgumentException + if the test result is false. + + a boolean expression. + + if expression is false + + + + + Assert a bool expression, throwing InvalidOperationException + if the expression is false. + + a boolean expression. + The exception message to use if the assertion fails + if expression is false + + + + Creates a new instance of the class. + + +

+ This is a utility class, and as such exposes no public constructors. +

+ + + + + General utility methods for working with annotations + + + + + Find a single Attribute of the type 'attributeType' from the supplied class, + traversing it interfaces and super classes if no attribute can be found on the + class iteslf. + + + This method explicitly handles class-level attributes which are not declared as + inherited as well as attributes on interfaces. + + The class to look for attributes on . + Type of the attribibute to look for. + the attribute of the given type found, or null + + + + Miscellaneous collection utility methods. + + + Mainly for internal use within the framework. + + Mark Pollack (.NET) + + + + Checks if the given array or collection has elements and none of the elements is null. + + the collection to be checked. + true if the collection has a length and contains only non-null elements. + + + + Checks if the given array or collection is null or has no elements. + + + + + + + Determine whether a given collection only contains + a single unique object + + + + + + + Determines whether the contains the specified . + + The collection to check. + The object to locate in the collection. + if the element is in the collection, otherwise. + + + + Adds the specified to the specified . + + The collection to add the element to. + The object to add to the collection. + + + + Adds the specified to the specified . + + The enumerable to add the element to. + The object to add to the collection. + + + + Determines whether the collection contains all the elements in the specified collection. + + The collection to check. + Collection whose elements would be checked for containment. + true if the target collection contains all the elements of the specified collection. + + + + Removes all the elements from the target collection that are contained in the source collection. + + Collection where the elements will be removed. + Elements to remove from the target collection. + + + + Converts an instance to an instance. + + The instance to be converted. + An instance in which its elements are the elements of the instance. + if the is null. + + + + Copies the elements of the to a + new array of the specified element type. + + The instance to be converted. + The element of the destination array to create and copy elements to + An array of the specified element type containing copies of the elements of the . + + + + Returns the first element contained in both, and . + + The implementation assumes that <<< + the source enumerable. may be null + the list of candidates to match against elements. may be null + the first element found in both enumerables or null + + + + Finds a value of the given type in the given collection. + + The collection to search. + The type to look for. + a value of the given type found, or null if none. + If more than one value of the given type is found + + + + Finds a value of the given type in the given collection. + + The collection to search. + The type to look for. + a collection of matching values of the given type found, empty if none found, or null if the input collection was null. + + + + Find a value of one of the given types in the given Collection, + searching the Collection for a value of the first type, then + searching for a value of the second type, etc. + + The collection to search. + The types to look for, in prioritized order. + a value of the given types found, or null if none + If more than one value of the given type is found + + + + Determines whether the specified collection is null or empty. + + The collection to check. + + true if the specified collection is empty or null; otherwise, false. + + + + + Determines whether the specified collection is null or empty. + + The collection to check. + + true if the specified collection is empty or null; otherwise, false. + + + + + Determines whether the specified dictionary is null empty. + + The dictionary to check. + + true if the specified dictionary is empty or null; otherwise, false. + + + + + A simple stable sorting routine - far from being efficient, only for small collections. + + + + + + + + A simple stable sorting routine - far from being efficient, only for small collections. + + + Sorting is not(!) done in-place. Instead a sorted copy of the original input is returned. + + input collection of items to sort + the for comparing 2 items in . + a new collection of stable sorted items. + + + + A simple stable sorting routine - far from being efficient, only for small collections. + + + Sorting is not(!) done in-place. Instead a sorted copy of the original input is returned. + + input collection of items to sort + the for comparing 2 items in . + a new collection of stable sorted items. + + + + A simple stable sorting routine - far from being efficient, only for small collections. + + + Sorting is not(!) done in-place. Instead a sorted copy of the original input is returned. + + input collection of items to sort + the for comparing 2 items in . + a new collection of stable sorted items. + + + + A callback method used for comparing to items. + + + + the first object to compare + the second object to compare + Value Condition Less than zero x is less than y. Zero x equals y. Greater than zero x is greater than y. + + + + + + Utility class containing helper methods for object comparison. + + Aleksandar Seovic + + + Compares two objects. + First object. + Second object. + + 0, if objects are equal; + less than zero, if the first object is smaller than the second one; + greater than zero, if the first object is greater than the second one. + + + + Utility class for .NET configuration files management. + + Aleksandar Seovic + + + + Avoid BeforeFieldInit pitfall + + + + + Parses the configuration section. + + +

+ Primary purpose of this method is to allow us to parse and + load configuration sections using the same API regardless + of the .NET framework version. +

+

+ If Microsoft paid a bit more attention to preserving backwards + compatibility we would not even need it, but... :( +

+ + Name of the configuration section. + Object created by a corresponding . + + + + Refresh the configuration section. + + +

+ Primary purpose of this method is to allow us to parse and + load configuration sections using the same API regardless + of the .NET framework version. +

+

+ If Microsoft paid a bit more attention to preserving backwards + compatibility we would not even need it, but... :( +

+ + Name of the configuration section. + + + + Creates the configuration exception. + + The message to display to the client when the exception is thrown. + The inner exception. + Name of the configuration file. + The line where exception occured. + Configuration exception. + + + + Creates the configuration exception. + + The message to display to the client when the exception is thrown. + Name of the configuration file. + The line where exception occured. + Configuration exception. + + + + Creates the configuration exception. + + The message to display to the client when the exception is thrown. + The inner exception. + XML node where exception occured. + Configuration exception. + + + + Creates the configuration exception. + + The message to display to the client when the exception is thrown. + XML node where exception occured. + Configuration exception. + + + + Creates the configuration exception. + + The message to display to the client when the exception is thrown. + The inner exception. + Configuration exception. + + + + Creates the configuration exception. + + The message to display to the client when the exception is thrown. + Configuration exception. + + + + Creates the configuration exception. + + Configuration exception. + + + + Determines whether the specified exception is configuration exception. + + The exception to check. + + true if the specified exception is configuration exception; otherwise, false. + + + + + Returns the line number of the specified node. + + Node to get the line number for. + The line number of the specified node. + + + + Returns the name of the file specified node is defined in. + + Node to get the file name for. + The name of the file specified node is defined in. + + + + Sets the current to be used by . + + + íf implements , this method invokes + on the new configSystem to chain them.
+ Note, that this method requires reflection on internals of + + the configuration system to set + bypasses the check if the current system has already been initialized + the previous config system, if any + + + + Resets the global configuration system instance. Use for unit testing only! + + + + + An holding information about its original text source location. + + Erich Eichinger + + + + Holds text position information for e.g. error reporting purposes. + + + + + + + Gets a string specifying the file/resource name related to the configuration details. + + + + + Gets an integer specifying the line number related to the configuration details. + + + + + Gets an integer specifying the line position related to the configuration details. + + + + + Creates a new instance of , storing a copy of the passed + . + + + + + Creates a duplicate of this node. + + true to recursively clone the subtree under the specified node; false to clone only the node itself + + + + The name of the resource this element was read from + + + + + The line number within the resource this element was read from + + + + + The line position within the resource this element was read from. + + + + + An implementation, who's elements retain information + about their location in the original XML text document the were read from. + + + When loading a document, the used must implement . + Typical XmlReader implementations like support this interface. + + Erich Eichinger + + + + Overridden to create a retaining the current + text position information. + + + + + Overridden to create a retaining the current + text position information. + + + + + Load the document from the given . + Child nodes will store as their property. + + the name of the resource + The XML source + + + + Load the document from the given . + + The XML source + + + + Load the document from the given . + Child nodes will store as their property. + + the name of the resource + The XML source + + + + Load the document from the given . + Child nodes will store as their property. + + the name of the resource + The XML source + + + + Load the document from the given . + Child nodes will store as their property. + + the name of the resource + The XML source + + + + Load the document from the given . + Child nodes will store as their property. + + the name of the resource + The XML source + + + + Load the document from the given . + Child nodes will store null as their property. + + The XML source + + + + Creates an object based on the information in the . The reader must be positioned on a node or attribute. + Child nodes will store as their property. + + + The new XmlNode or null if no more nodes exist. + + the name of the resource + The XML source + The reader is positioned on a node type that does not translate to a valid DOM node (for example, EndElement or EndEntity). + + + + Creates an object based on the information in the . The reader must be positioned on a node or attribute. + Child nodes will store null as their property. + + + The new XmlNode or null if no more nodes exist. + + The XML source + The reader is positioned on a node type that does not translate to a valid DOM node (for example, EndElement or EndEntity). + + + + Get info about the current text position during loading a document. + Outside loading a document, the properties of + will always be null. + + + + + Holds the current text position during loading a document + + + + + An holding information about its original text source location. + + Erich Eichinger + + + + Creates a new instance of , storing a copy of the passed + . + + + + + Creates a duplicate of this node. + + true to recursively clone the subtree under the specified node; false to clone only the node itself + + + + The name of the resource this element was read from + + + + + The line number within the resource this element was read from + + + + + The line position within the resource this element was read from. + + + + + Collects information on the constructor to use to create the instance and the argument instances to pass into the + constructor. + + + + + Initializes a new instance of the class. + + The constructor info. + The arg instances. + + + + Gets the constructor info. + + The constructor info. + + + + Gets the arg instances. + + The arg instances. + + + + Discovers the attributes of a + and provides access to the + s metadata. + + Rick Evans + + + + The method name associated with a delegate invocation. + + + + + Creates a new instance of the + class. + + + The event used to extract the delegate + from. + + + if the supplied is + . + + + + + Creates a new instance of the + class. + + + The delegate . + + + If the supplied is not a subclass of the + class, or is . + + + + + Checks to see if the method encapsulated by the supplied method + metadata is compatible with the method signature associated with + this delegate type. + + The method to be checked. + + if the method signature is compatible with + the signature of this delegate; if not, or + if the supplied parameter is + . + + + + + Gets the s of the parameters of the + method signature associated with this delegate type. + + +

+ This method will never return ; the returned + array may be empty, but it most certainly + will not be . +

+ + + A array of the parameter + s; or the + array if the method signature has no parameters. + + + + + Gets the return of the + method signature associated with this delegate type. + + The return . + + + + Gets the metadata about the method signature associated + with this delegate type. + + + The metadata about the method signature associated + with this delegate type. + + + + + Determines whether the supplied + is a type. + + + The to be checked. + + + if the supplied + is a ; + if not or the supplied + is . + + + + + Checks if the signature of the supplied + is compatible with the signature expected by the supplied + . + + The event to be checked against. + + The method signature to check for compatibility. + + + if the signature of the supplied + is compatible with the signature + expected by the supplied ; + if not or either of the supplied + parameters is . + + + + + + The of the delegate. + + + + + Use this class for obtaining instances for dynamic code generation. + + +

+ The purpose of this class is to provide a simple abstraction for creating and managing dynamic assemblies. +

+ + Using this factory you can't define several modules within a single dynamic assembly - only a simple one2one relation between assembly/module is used. + + + +

The following excerpt from demonstrates usage:

+ + public class DynamicProxyManager + { + public const string PROXY_ASSEMBLY_NAME = "Spring.Proxy"; + + public static TypeBuilder CreateTypeBuilder(string name, Type baseType) + { + // Generates type name + string typeName = String.Format("{0}.{1}_{2}", PROXY_ASSEMBLY_NAME, name, Guid.NewGuid().ToString("N")); + ModuleBuilder module = DynamicCodeManager.GetModuleBuilder(PROXY_ASSEMBLY_NAME); + return module.DefineType(typeName, PROXY_TYPE_ATTRIBUTES); + } + } + + + Erich Eichinger + + + + + + + prevent instantiation + + + + + Returns the for the dynamic module within the specified assembly. + + + If the assembly does not exist yet, it will be created.
+ This factory caches any dynamic assembly it creates - calling GetModule() twice with + the same name will *not* create 2 distinct modules! + + The assembly-name of the module to be returned + the that can be used to define new types within the specified assembly + + + + Persists the specified dynamic assembly to the file-system + + the name of the dynamic assembly to persist + + Can only be called in DEBUG_DYNAMIC mode, per ConditionalAttribute rules. + + + + + Removes all registered s. + + + + + A utility class for raising events in a generic and consistent fashion. + + Rick Evans + + + + Create a new EventRaiser instance + + + + + Raises the event encapsulated by the supplied + , passing the supplied + to the event. + + The event to be raised. + The arguments to the event. + a map of sink/exception entries that occurred during event raising + + + + Invokes the supplied , passing the supplied + to the sink. + + The sink to be invoked. + The arguments to the sink. + the map of sink/exception entries to add any exception to + + + + Raises events defensively. + + +

+ Raising events defensively means that as the raised event is passed to each handler, + any thrown by a handler will be caught and silently + ignored. +

+ + Rick Evans + + + + Defensively invokes the supplied , passing the + supplied to the sink. + + The sink to be invoked. + The arguments to the sink. + the map of sink/exception entries to add any exception to + + + + Implement this interface to create your own, delegating + and set them using + + + + + + + + + + + A strategy for handling errors. This is especially useful for handling + errors that occur during asynchronous execution as in such cases it may not be + possible to throw the error to the original caller. + + Mark Fisher + Mark Pollack (.NET) + + + + Handles the error. + + The exception. + + + + Utility methods for IO handling + + + + + Copies one stream into another. + (Don't forget to call on the destination stream!) + + + Does not close the input stream! + + + + + Reads a stream into a byte array. + + + Does not close the input stream! + + + + + Various utility methods relating to numbers. + + +

+ Mainly for internal use within the framework. +

+ + Aleksandar Seovic + + + + Determines whether the supplied is an integer. + + The object to check. + + if the supplied is an integer. + + + + + Determines whether the supplied is a decimal number. + + The object to check. + + if the supplied is a decimal number. + + + + + Determines whether the supplied is of numeric type. + + The object to check. + + true if the specified object is of numeric type; otherwise, false. + + + + + Determines whether the supplied can be converted to an integer. + + The object to check. + + if the supplied can be converted to an integer. + + + + + Determines whether the supplied can be converted to an integer. + + The object to check. + + if the supplied can be converted to an integer. + + + + + Determines whether the supplied can be converted to a number. + + The object to check. + + true if the specified object is decimal number; otherwise, false. + + + + + Is the supplied equal to zero (0)? + + The number to check. + + id the supplied is equal to zero (0). + + + + + Negates the supplied . + + The number to negate. + The supplied negated. + + If the supplied is not a supported numeric type. + + + + + Returns the bitwise not (~) of the supplied . + + The number. + The value of ~. + + If the supplied is not a supported numeric type. + + + + + Bitwise ANDs (&) the specified integral values. + + The first number. + The second number. + + If one of the supplied arguments is not a supported integral types. + + + + + Bitwise ORs (|) the specified integral values. + + The first number. + The second number. + + If one of the supplied arguments is not a supported integral types. + + + + + Bitwise XORs (^) the specified integral values. + + The first number. + The second number. + + If one of the supplied arguments is not a supported integral types. + + + + + Adds the specified numbers. + + The first number. + The second number. + + + + Subtracts the specified numbers. + + The first number. + The second number. + + + + Multiplies the specified numbers. + + The first number. + The second number. + + + + Divides the specified numbers. + + The first number. + The second number. + + + + Calculates remainder for the specified numbers. + + The first number (dividend). + The second number (divisor). + + + + Raises first number to the power of the second one. + + The first number. + The second number. + + + + Coerces the types so they can be compared. + + The right. + The left. + + + + Creates a new instance of the class. + + +

+ This is a utility class, and as such exposes no public constructors. +

+ + + + + Helper methods with regard to objects, types, properties, etc. + + +

+ Not intended to be used directly by applications. +

+ + Rod Johnson + Juergen Hoeller + Rick Evans (.NET) + + + + The instance for this class. + + + + + An empty object array. + + + + + Creates a new instance of the class. + + +

+ This is a utility class, and as such exposes no public constructors. +

+ + + + + Instantiates the type using the assembly specified to load the type. + + This is a convenience in the case of needing to instantiate a type but not + wanting to specify in the string the version, culture and public key token. + The assembly. + Name of the type. + + + If the or is + + + If cannot load the type from the assembly or the call to InstantiateType(Type) fails. + + + + + Convenience method to instantiate a using + its no-arg constructor. + + +

+ As this method doesn't try to instantiate s + by name, it should avoid loading issues. +

+ + + The to instantiate* + + A new instance of the . + + If the is + + + If the is an abstract class, an interface, + an open generic type or does not have a public no-argument constructor. + + + + + Gets the zero arg ConstructorInfo object, if the type offers such functionality. + + The type. + Zero argument ConstructorInfo + + If the type is an interface, abstract, open generic type, or does not have a zero-arg constructor. + + + + + Determines whether the specified type is instantiable, i.e. not an interface, abstract class or contains + open generic type parameters. + + The type. + + + + Convenience method to instantiate a using + the given constructor. + + +

+ As this method doesn't try to instantiate s + by name, it should avoid loading issues. +

+ + + The constructor to use for the instantiation. + + + The arguments to be passed to the constructor. + + A new instance. + + If the is + + + If the 's declaring type is an abstract class, + an interface, an open generic type or does not have a public no-argument constructor. + + + + + Checks whether the supplied is not a transparent proxy and is + assignable to the supplied . + + +

+ Neccessary when dealing with server-activated remote objects, because the + object is of the type TransparentProxy and regular is testing for assignable + types does not work. +

+

+ Transparent proxy instances always return when tested + with the 'is' operator (C#). This method only checks if the object + is assignable to the type if it is not a transparent proxy. +

+ + The target to be checked. + The value that should be assigned to the type. + + if the supplied is not a + transparent proxy and is assignable to the supplied . + + + + + Determine if the given is assignable from the + given value, assuming setting by reflection and taking care of transparent proxies. + + +

+ Considers primitive wrapper classes as assignable to the + corresponding primitive types. +

+

+ For example used in an object factory's constructor resolution. +

+ + The target . + The value that should be assigned to the type. + True if the type is assignable from the value. + + + + Check if the given represents a + "simple" property, + i.e. a primitive, a , a + , or a corresponding array. + + +

+ Used to determine properties to check for a "simple" dependency-check. +

+ + + The to check. + + + + + Check if the given class represents a primitive array, + i.e. boolean, byte, char, short, int, long, float, or double. + + + + + Determines whether the specified array is null or empty. + + The array to check. + + true if the specified array is null empty; otherwise, false. + + + + + Determine if the given objects are equal, returning + if both are respectively + if only one is . + + The first object to compare. + The second object to compare. + + if the given objects are equal. + + + + + Returns the first element in the supplied . + + + The to use to enumerate + elements. + + + The first element in the supplied . + + + If the supplied did not have any elements. + + + + + Returns the first element in the supplied . + + + The to use to enumerate + elements. + + + The first element in the supplied . + + + If the supplied did not have any elements. + + + If the supplied is . + + + + + Returns the element at the specified index using the supplied + . + + + The to use to enumerate + elements until the supplied is reached. + + + The index of the element in the enumeration to return. + + + The element at the specified index using the supplied + . + + + If the supplied was less than zero, or the + supplied did not contain enough elements + to be able to reach the supplied . + + + + + Returns the element at the specified index using the supplied + . + + + The to use to enumerate + elements until the supplied is reached. + + + The index of the element in the enumeration to return. + + + The element at the specified index using the supplied + . + + + If the supplied was less than zero, or the + supplied did not contain enough elements + to be able to reach the supplied . + + + If the supplied is . + + + + + Gets the qualified name of the given method, consisting of + fully qualified interface/class name + "." method name. + + The method. + qualified name of the method. + + + + Return a String representation of an object's overall identity. + + The object (may be null). + The object's identity as String representation, + or an empty String if the object was null + + + + + Gets a hex String form of an object's identity hash code. + + The obj. + The object's identity code in hex notation + + + + Support matching of file system paths in a manner similar to that of the + NAnt FileSet. + + +

+ Any (back)slashes are converted to forward slashes. +

+ + + + // true + PathMatcher.Match("c:/*.bat", @"c:\autoexec.bat"); + PathMatcher.Match("c:\fo*\*.bat", @"c:/foobar/autoexec.bat"); + PathMatcher.Match("c:\fo?\*.bat", @"c:/foo/autoexec.bat"); + // false + PathMatcher.Match("c:\fo?\*.bat", @"c:/fo/autoexec.bat"); + + + Federico Spinazzi + + + + Determines if a given path matches a NAnt-like pattern. + + + A forward or back-slashed fileset-like pattern. + + A forward or back-slashed full path. + should the match consider the case + + if the path is matched by the pattern; + otherwise . + + + + + Determines if a given path matches a NAnt-like pattern. + + + A forward or back-slashed fileset-like pattern. + + A forward or back-slashed full path. + + if the path is matched by the pattern; + otherwise . + + + + + Replaces back(slashes) with forward slashes. + + + The path or the pattern to modify. + + A forward-slashed string. + + + + Helper method to convert a NAnt-like pattern into the + appropriate pattern for a regular expression. + + The NAnt-like pattern. + A regex-compatible pattern. + + + + Creates a new instance of the class. + + +

+ This is a utility class, and as such exposes no public constructors. +

+ + + + Utility methods for simple pattern matching, in particular for + Spring's typical "xxx*", "*xxx" and "*xxx*" pattern styles. + + Juergen Hoeller + Mark Pollack + + + Match a String against the given pattern, supporting the following simple + pattern styles: "xxx*", "*xxx" and "*xxx*" matches, as well as direct equality. + + the pattern to match against + + the String to match + + whether the String matches the given pattern + + + + Match a String against the given patterns, supporting the following simple + pattern styles: "xxx*", "*xxx" and "*xxx*" matches, as well as direct equality. + + the patterns to match against + + the String to match + + whether the String matches any of the given patterns + + + + + An implementation of the Java Properties class. + + + For the complete syntax see java.util.Properties JavaDoc. + This class supports an extended syntax. There may also be sole keys on a line, in that case values are treated as null. + + + key1 = value + key2: + key3 + + will result in the name/value pairs: + + key1:="value" + key2:=string.Empty + key3:=<null> + + note, that to specify a null value, the key must not be followed by any character except newline. + + + Simon White + + + + Creates an empty property list with no default values. + + + + + Creates a property list with the specified initial properties. + + The initial properties. + + + + Reads a property list (key and element pairs) from the input stream. + + The stream to load from. + + + + Reads a property list (key and element pairs) from a text reader. + + The text reader to load from. + + + + Reads a property list (key and element pairs) from the input stream. + + the dictionary to put it in + The stream to load from. + + + + Reads a property list (key and element pairs) from a text reader. + + the dictionary to put it in + The text reader to load from. + + + + Strips whitespace from the front of the specified string. + + The string. + The string with all leading whitespace removed. + + + + Splits the specified string into a key / value pair. + + The line to split. + An array containing the key / value pair. + + + + Searches for the property with the specified key in this property list. + + The key. + The property, or null if the key was not found. + + + + Searches for the property with the specified key in this property list. + + The key. + + The default value to be returned if the key is not found. + + The property, or the default value. + + + + Writes this property list out to the specified stream. + + The stream to write to. + + + + Sets the specified property key / value pair. + + The key. + The value. + + + + Writes the properties in this instance out to the supplied stream. + + The stream to write to. + Arbitrary header information. + + + + Removes the key / value pair identified by the supplied key. + + + The key identifying the key / value pair to be removed. + + + + + Adds the specified key / object pair to this collection. + + The key. + The value. + + + + Adds the specified key / object pair to this collection. + + + + + Various reflection related methods that are missing from the standard library. + + Rod Johnson + Juergen Hoeller + Aleksandar Seovic (.NET) + Stan Dvoychenko (.NET) + Bruno Baia (.NET) + + + + Convenience value that will + match all private and public, static and instance members on a class + in a case inSenSItivE fashion. + + + + + Avoid BeforeFieldInit problem + + + + + Checks, if the specified type is a nullable + + + + + Returns signature for the specified , method name and argument + s. + + The the method is in. + The method name. + + The argument s. + + The method signature. + + + + Returns method for the specified , method + name and argument + s. + + + Searches with BindingFlags + When dealing with interface methods, you probable want to 'normalize' method references by calling + . + + + + The target to find the method on. + + The method to find. + + The argument s. May be + if the method has no arguments. + + The target method. + + + + + Resolves a given to the representing the actual implementation. + + + see article How To Get an Explicit Interface Implementation Method. + + a + the type to lookup + the representing the actual implementation method of the specified + + + + Returns an array of parameter s for the specified method + or constructor. + + The method (or constructor). + An array containing the parameter s. + + If is . + + + + + Returns an array of parameter s for the + specified parameter info array. + + The parameter info array. + An array containing parameter s. + + If is or any of the + elements is . + + + + + Returns an array of s that represent + the names of the generic type parameter. + + The method. + An array containing the parameter names. + + If is . + + + + + Returns an array of s that represent + the names of the generic type parameter. + + The parameter info array. + An array containing parameter names. + + If is or any of the + elements is . + + + + + From a given list of methods, selects the method having an exact match on the given ' types. + + the list of methods to choose from + the arguments to the method + the method matching exactly the passed ' types + + If more than 1 matching methods are found in the list. + + + + + From a given list of methods, selects the method having an exact match on the given ' types. + + the type of method (used for exception reporting only) + the list of methods to choose from + the arguments to the method + the method matching exactly the passed ' types + + If more than 1 matching methods are found in the list. + + + + + From a given list of constructors, selects the constructor having an exact match on the given ' types. + + the list of constructors to choose from + the arguments to the method + the constructor matching exactly the passed ' types + + If more than 1 matching methods are found in the list. + + + + + Packages arguments into argument list containing parameter array as a last argument. + + Argument vaklues to package. + Total number of oarameters. + Type of the param array element. + Packaged arguments. + + + + Convenience method to convert an interface + to a array that contains + all the interfaces inherited and the specified interface. + + The interface to convert. + An array of interface s. + + If the specified is not an interface. + + + If is . + + + + + Is the supplied the default indexer for the + supplied ? + + + The name of the property on the supplied to be checked. + + + The to be checked. + + + if the supplied is the + default indexer for the supplied . + + + If the supplied is . + + + + + Is the supplied declared on one of these interfaces? + + The method to check. + The array of interfaces we want to check. + + if the method is declared on one of these interfaces. + + + If any of the s specified is not an interface. + + + If or any of the specified interfaces is + . + + + + + Returns the default value for the specified + + +

+ Follows the standard .NET conventions for default values where + relevant; for example, all numeric types default to the value + 0. +

+ + + The to return default value for. + + + The default value for the specified . + + + If the supplied is an enumerated type that + has no values. + + + + + Returns an array consisting of the default values for the supplied + . + + + The array of s to return default values for. + + + An array consisting of the default values for the supplied + . + + + If any of the elements in the supplied + array is an enumerated type that has no values. + + + + + + Checks that the parameter s of the + supplied match the parameter + s of the supplied + . + + The method to be checked. + + The array of parameter s to check against. + + + if the parameter s + match. + + + + + Returns an array containing the s of the + objects in the supplied array. + + + The objects array for which the corresponding s + are needed. + + + An array containing the s of the objects + in the supplied array; this array will be empty (but not + if the supplied + is null or has no elements. + + +

+ [C#]
+ Given an array containing the following objects, + [83, "Foo", new object ()], the + array returned from this method call would consist of the following + elements... + [Int32, String, Object]. +

+ + + + + Given the return its representation as + it would appear in the source code files. + + + Largely intended to handle generic types where .ToString() will typically return: + "System.Collections.Generic.List`1[System.Collections.Generic.Dictionary`2[System.String,System.Int32]]" + and this method will instead return: + "System.Collections.Generic.List<System.Collections.Generic.Dictionary<string,int>>" + + The type. + Friendly string representing the Type + + + + Does the given and/or it's superclasses + have at least one or more methods with the given name (with any + argument types)? + + +

+ Includes non-public methods in the methods searched. +

+ + + The to be checked. + + + The name of the method to be searched for. Case inSenSItivE. + + + if the given or / and it's + superclasses have at least one or more methods (with any argument types); + if not, or either of the parameters is . + + + + + Within , counts the number of overloads for the method with the given (case-insensitive!) + + The type to be searched + the name of the method for which overloads shall be counted + The number of overloads for method within type + + + + Creates a . + + +

+ Note that if a non- + is supplied, any read write properties exposed by the + will be used to overwrite values that may have been passed in via the + . That is, the will be used + to initialize the custom attribute, and then any read-write properties on the + will be plugged in. +

+ + + The desired . + + + Any constructor arguments for the attribute (may be + in the case of no arguments). + + + Source attribute to copy properties from (may be ). + + A custom attribute builder. + + If the parameter is . + + + If the parameter is not a + that derives from the class. + + + + + + Creates a . + + + The desired . + + + Source attribute to copy properties from (may be ). + + A custom attribute builder. + + + + Creates a . + + + The source attribute to copy properties from. + + A custom attribute builder. + + If the supplied is + . + + + + + Creates a . + + + The desired . + + A custom attribute builder. + + + + Creates a . + + + The desired . + + + Any constructor arguments for the attribute (may be + in the case of no arguments). + + A custom attribute builder. + + + + Creates a . + + + The to create + the custom attribute builder from. + + A custom attribute builder. + + + + Calculates and returns the list of attributes that apply to the + specified type or method. + + The type or method to find attributes for. + + A list of custom attributes (CustomAttributeData or Attribute instances) + that should be applied to type or method. + + + + + Tries to find matching methods in the specified + for each method in the supplied list. + + + The to look for matching methods in. + + The methods to match. + + A flag that specifies whether to throw an exception if a matching + method is not found. + + A list of the matched methods. + + If either of the or + parameters are . + + + + + Returns the of the supplied + . + + +

+ If the is a + instance, the return value of this method call with be the + parameter cast to a + . If the is + anything other than a , the return value + will be the result of invoking the 's + method. +

+ + + A or instance. + + + The argument if it is a + or the result of invoking + on the argument if it + is an . + + + If the is . + + + + + Unwraps the supplied + and returns the inner exception preserving the stack trace. + + + The to unwrap. + + The unwrapped exception. + + + + Is the supplied can be accessed outside the assembly ? + + The type to check. + + if the type can be accessed outside the assembly; + Otherwise . + + + + + Determines whether the specified type is nullable. + + The type. + + true if the specified type is ullable]; otherwise, false. + + + + + Is the supplied can be accessed + from the supplied friendly assembly ? + + The type to check. + The friendly assembly name. + + if the type can be accessed + from the supplied friendly assembly; Otherwise . + + + + + Gets all of the interfaces implemented by + the specified . + + + The object to get the interfaces of. + + + All of the interfaces implemented by the + . + + + + + Returns the explicit that is the root cause of an exception. + + + If the InnerException property of the current exception is a null reference + or a , returns the current exception. + + The last exception thrown. + + The first explicit exception thrown in a chain of exceptions. + + + + + Copies all fields from one object to another. + + + The types of both objects must be related. This means, that either of the following is true: + + fromObject.GetType() == toObject.GetType() + fromObject.GetType() is derived from toObject.GetType() + toObject.GetType() is derived from fromObject.GetType() + + + The source object + The object, who's fields will be populated with values from the source object + If the object's types are not related + + + + Convenience method that uses reflection to return the value of a non-public field of a given object. + + Useful in certain instances during testing to avoid the need to add protected properties, etc. to a class just to facilitate testing. + The instance of the object from which to retrieve the field value. + Name of the field on the object from which to retrieve the value. + + + + + Convenience method that uses reflection to set the value of a non-public field of a given object. + + Useful in certain instances during testing to avoid the need to add protected properties, etc. to a class just to facilitate testing. + The instance of the object from which to set the field value. + Name of the field on the object to which to set the value. + The field value to set. + + + + Creates a . + + Bruno Baia + + + + Creates a new instance of the + class. + + The custom attribute type. + + + + Creates a new instance of the + class. + + The custom attribute type. + The custom attribute constructor arguments. + + + + Adds the specified values to the constructor argument list + used to create the custom attribute. + + An array of argument values. + + + + Adds a property value to the custom attribute. + + The property name. + The property value. + + + + Creates the . + + The created . + + + + Utility class to be used from within this assembly for executing security critical code + NEVER EVER MAKE THIS PUBLIC! + + Erich Eichinger + + + + Miscellaneous utility methods. + + +

+ Mainly for internal use within the framework. +

+ + Rod Johnson + Juergen Hoeller + Keith Donald + Aleksandar Seovic (.NET) + Mark Pollack (.NET) + Rick Evans (.NET) + Erich Eichinger (.NET) + + + + The string that signals the start of an Ant-style expression. + + + + + The string that signals the end of an Ant-style expression. + + + + + An empty array of instances. + + + + + Creates a new instance of the class. + + +

+ This is a utility class, and as such exposes no public constructors. +

+ + + + + Tokenize the given into a + array. + + +

+ If is , returns an empty + array. +

+

+ If is or the empty + , returns a array with one + element: itself. +

+ + The to tokenize. + + The delimiter characters, assembled as a . + + + Trim the tokens via . + + + Omit empty tokens from the result array. + An array of the tokens. + + + + Tokenize the given into a + array. + + +

+ If is , returns an empty + array. +

+

+ If is or the empty + , returns a array with one + element: itself. +

+ + The to tokenize. + + The delimiter characters, assembled as a . + + + Trim the tokens via . + + + Omit empty tokens from the result array. + + + Pairs of quote characters. within a pair of quotes are ignored + + An array of the tokens. + + + + Convert a CSV list into an array of s. + + + Values may also be quoted using doublequotes. + + A CSV list. + + An array of s, or the empty array + if is . + + + + + Take a which is a delimited list + and convert it to a array. + + +

+ If the supplied is a + or zero-length string, then a single element + array composed of the supplied + will be + eturned. If the supplied + is , then an empty, + zero-length array will be returned. +

+ + + The to be parsed. + + + The delimeter (this will not be returned). Note that only the first + character of the supplied is used. + + + An array of the tokens in the list. + + + + + Convenience method to return an + as a delimited + (e.g. CSV) . + + + The to parse. + + + The delimiter to use (probably a ','). + + The delimited string representation. + + + + Convenience method to return an + as a CSV + . + + + The to display. + + The delimited string representation. + + + + Convenience method to return an array as a CSV + . + + + The array to parse. Elements may be of any type ( + will be called on each + element). + + + + + Convenience method to return a + array as a delimited (e.g. CSV) . + + + The array to parse. Elements may be of any type ( + will be called on each + element). + + + The delimiter to use (probably a ','). + + + + Checks if a string has length. + + The string to check, may be . + + + if the string has length and is not + . + + + + StringUtils.HasLength(null) = false + StringUtils.HasLength("") = false + StringUtils.HasLength(" ") = true + StringUtils.HasLength("Hello") = true + + + + + + Checks if a has text. + + +

+ More specifically, returns if the string is + not , it's is > + zero (0), and it has at least one non-whitespace character. +

+ + + The string to check, may be . + + + if the is not + , + > zero (0), and does not consist + solely of whitespace. + + + + StringUtils.HasText(null) = false + StringUtils.HasText("") = false + StringUtils.HasText(" ") = false + StringUtils.HasText("12345") = true + StringUtils.HasText(" 12345 ") = true + + + + + + Checks if a is + or an empty string. + + +

+ More specifically, returns if the string is + , it's is equal + to zero (0), or it is composed entirely of whitespace + characters. +

+ + + The string to check, may (obviously) be . + + + if the is + , has a length equal to zero (0), or + is composed entirely of whitespace characters. + + + + StringUtils.IsNullOrEmpty(null) = true + StringUtils.IsNullOrEmpty("") = true + StringUtils.IsNullOrEmpty(" ") = true + StringUtils.IsNullOrEmpty("12345") = false + StringUtils.IsNullOrEmpty(" 12345 ") = false + + + + + + Returns , if it contains non-whitespaces. null otherwise. + + + + + Strips first and last character off the string. + + The string to strip. + The stripped string. + + + + Returns a list of Ant-style expressions from the specified text. + + The text to inspect. + + A list of expressions that exist in the specified text. + + + If any of the expressions in the supplied + is empty (${}). + + + + + Replaces Ant-style expression placeholder with expression value. + + +

+ +

+ + The string to set the value in. + The name of the expression to set. + The expression value. + + A new string with the expression value set; the + value if the supplied + is , has a length + equal to zero (0), or is composed entirely of whitespace + characters. + + + + + Surrounds (prepends and appends) the string value of the supplied + to the supplied . + + +

+ The return value of this method call is always guaranteed to be non + . If every value passed as a parameter to this method is + , the string will be returned. +

+ + + The prefix and suffix that respectively will be prepended and + appended to the target . If this value + is not a value, it's attendant + value will be used. + + + The target that is to be surrounded. If this value is not a + value, it's attendant + value will be used. + + The surrounded string. + + + + Surrounds (prepends and appends) the string values of the supplied + and to the supplied + . + + +

+ The return value of this method call is always guaranteed to be non + . If every value passed as a parameter to this method is + , the string will be returned. +

+ + + The value that will be prepended to the . If this value + is not a value, it's attendant + value will be used. + + + The target that is to be surrounded. If this value is not a + value, it's attendant + value will be used. + + + The value that will be appended to the . If this value + is not a value, it's attendant + value will be used. + + The surrounded string. + + + + Converts escaped characters (for example "\t") within a string + to their real character. + + The string to convert. + The converted string. + + + + Utility class containing miscellaneous system-level functionality. + + Aleksandar Seovic + + + + Registers assembly resolver that iterates over the + assemblies loaded into the current + in order to find an assembly that cannot be resolved. + + + This method has to be called if you need to serialize dynamically + generated types in transient assemblies, such as Spring AOP proxies, + because standard .NET serialization engine always tries to load + assembly from the disk. + + + + + Returns true if running on Mono + + Tests for the presence of the type Mono.Runtime + + + + Returns true if running on CLR 4.0 under InProc SxS mode + + + + + Gets the thread id for the current thread. Use thread name is available, + otherwise use CurrentThread.GetHashCode() for .NET 1.0/1.1 and + CurrentThread.ManagedThreadId otherwise. + + The thread id. + + + + Holds text position information for e.g. error reporting purposes. + + + + + + + Creates a new TextPositionInfo instance. + + + + + Creates a new TextPositionInfo instance, copying values from another instance. + + + + + The filename related to this text position + + + + + The line number related to this text position + + + + + The line position related to this text position + + + + + UniqueKey allows for generating keys unique to a type or particular instance and a partial name, + that can e.g. be used as keys in . + + + // shows usage type-scoped keys + UniqueKey classAKey = UniqueKey.GetTypeScoped(typeof(ClassA), "myKey"); + UniqueKey classBKey = UniqueKey.GetTypeScoped(typeof(ClassB), "myKey"); + + HttpContext.Current.Items.Add( classAKey, "some value unqiue for class A having key 'myKey'"); + object value = HttpContext.Current.Items[ UniqueKey.GetTypeScoped(typeof(ClassA), "myKey") ]; + Assert.AreEqual( "some value unique for class A having key 'myKey'", value); + + HttpContext.Current.Items.Add( classBKey, "some value unqiue for class B having key 'myKey'"); + object value = HttpContext.Current.Items[ UniqueKey.GetTypeScoped(typeof(ClassB), "myKey") ]; + Assert.AreEqual( "some value unique for class B having key 'myKey'", value); + + + + + Initialize a new instance of from its string representation. + See and See for details. + + The string representation of the new instance. + + + + Compares this instance to another. + + + + + Compares this instance to another. + + + + + Returns the hash code for this key. + + + + + + Returns a string representation of this key. + + + + + Creates a new key instance unique to the given instance. + + The instance the key shall be unique to + The partial key to be made unique + + + If is of type + + + + Creates a new key instance unique to the given type. + + The type the key shall be unique to + The partial key to be made unique + + + + Returns a key unique for the given instance. + + The instance the key shall be unique to + The partial key to be made unique + A key formatted as typename[instance-id].partialkey + + + + Returns a key unique for the given type. + + The type the key shall be unique to + The partial key to be made unique + A key formatted as typename.partialkey + + + + XML utility methods. + + Aleksandar Seovic + + + + Gets an appropriate implementation + for the supplied . + + The XML that is going to be read. + XML schemas that should be used for validation. + Validation event handler. + + A validating implementation. + + + + + Gets an appropriate implementation + for the supplied . + + The XML that is going to be read. + to be used for resolving external references + XML schemas that should be used for validation. + Validation event handler. + + A validating implementation. + + + + + Gets an appropriate implementation + for the supplied . + + The XML that is going to be read. + + A non-validating implementation. + + + + + Implementation of that adds error message + to the validation errors container. + + Aleksandar Seovic + + + + Abstract base class that should be extended by all + validation actions. + + +

+ This class implements template Execute method + and defines OnValid and OnInvalid methods that + can be overriden + by specific validation actions. +

+ + Aleksandar Seovic + + + + An action that should be executed after validator is evaluated. + + +

+ This interface allows us to define the actions that should be executed + after validation in a generic fashion. +

+

+ For example, addition of error messages to validation errors collection + is performed by one specific implementation of this interface, . +

+ + Aleksandar Seovic + + + + Executes the action. + + Whether associated validator is valid or not. + Validation context. + Additional context parameters. + Validation errors container. + + + + Initializes a new instance of the class. + + + + + Executes the action. + + Whether associated validator is valid or not. + Validation context. + Additional context parameters. + Validation errors container. + + + + Called when associated validator is valid. + + Validation context. + Additional context parameters. + Validation errors container. + + + + Called when associated validator is not valid. + + Validation context. + Additional context parameters. + Validation errors container. + + + + Evaluates 'when' expression. + + Root context to use for expression evaluation. + Additional context parameters. + True if the condition is true, False otherwise. + + + + Gets or sets the expression that determines if this validator should be evaluated. + + The expression that determines if this validator should be evaluated. + + + + Initializes a new instance of the class. + + Error message resource identifier. + Names of the error providers this message should be added to. + + + + Called when associated validator is invalid. + + Validation context. + Additional context parameters. + Validation errors container. + + + + Resolves the error message. + + Validation context to resolve message parameters against. + Additional context parameters. + Resolved error message + + + + Resolves the message parameters. + + List of parameters to resolve. + Validation context to resolve parameters against. + Additional context parameters. + Resolved message parameters. + + + + Sets the expressions that should be resolved to error message parameters. + + The expressions that should be resolved to error message parameters. + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + Expression that defines the exception to throw when the validator is not valid. + + + + Initializes a new instance of the class with an expression + that defines the exception to throw. + + + + + Called when associated validator is invalid. + + Validation context. + Additional context parameters. + Validation errors container. + + + + Gets or sets the exception to throw + + The throws. + + + + Implementation of that allows you + to define Spring.NET expressions that should be evaluated after + validation. + + Aleksandar Seovic + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + Expression to execute when validator is valid. + Expression to execute when validator is not valid. + + + + Initializes a new instance of the class. + + Expression to execute when validator is valid. + Expression to execute when validator is not valid. + + + + Called when associated validator is valid. + + Validation context. + Additional context parameters. + Validation errors container. + + + + Called when associated validator is invalid. + + Validation context. + Additional context parameters. + Validation errors container. + + + + Gets or sets the expression to execute when validator is valid. + + The expression to execute when validator is valid. + + + + Gets or sets the expression to execute when validator is not valid. + + The expression to execute when validator is not valid. + + + + Implementation of the custom configuration parser for validator definitions. + + Aleksandar Seovic + + + + Initializes a new instance of the class. + + + + + Parse the specified element and register any resulting + IObjectDefinitions with the IObjectDefinitionRegistry that is + embedded in the supplied ParserContext. + + The element to be parsed into one or more IObjectDefinitions + The object encapsulating the current state of the parsing + process. + + The primary IObjectDefinition (can be null as explained above) + + + Implementations should return the primary IObjectDefinition + that results from the parse phase if they wish to used nested + inside (for example) a <property> tag. + Implementations may return null if they will not + be used in a nested scenario. + + + + + + Parses the validator definition. + + Validator's identifier. + The element to parse. + The parser helper. + Validator object definition. + + + + Parses the attribute of the given from the XmlElement and, if available, adds a property of the given with + the parsed value. + + + + + Parses and potentially registers a validator. + + + Only validators that have id attribute specified are registered + as separate object definitions within application context. + + Validator XML element. + The parser helper. + Validator object definition. + + + + Gets the name of the object type for the specified element. + + The element. + The name of the object type. + + + + Creates an error message action based on the specified message element. + + The message element. + The parser helper. + The error message action definition. + + + + Creates a generic action based on the specified element. + + The action definition element. + The parser helper. + Generic validation action definition. + + + + Creates object definition for the validator reference. + + The action definition element. + The parser helper. + Generic validation action definition. + + + + Evaluates validator test using condition evaluator. + + Aleksandar Seovic + + + + Base class that defines common properties for all single validators. + + +

+ Custom single validators should always extend this class instead of + simply implementing interface, in + order to inherit common validator functionality. +

+ + Aleksandar Seovic + Erich Eichinger + + + + Base class that defines common properties for all validators. + + +

+ Custom validators should always extend this class instead of + simply implementing interface, in + order to inherit common validator functionality. +

+ + Aleksandar Seovic + Erich Eichinger + + + + An object that can validate application-specific objects. + + +

+ The primary motivation for this interface is to enable validation to be + decoupled from the (user) interface and placed in business objects. +

+

+ Application developers writing their own custom + implementations will + typically not implement this interface directly. In most cases, custom + validators woud be better served deriving from the + class, with the + custom validation ligic being implemented in an override of the + + + template method. +

+ + Aleksandar Seovic + + + + + Validates the specified object. + + The object to validate. + + The instance to add any error + messages to in the case of validation failure. + + + if validation was successful. + + + + + Validates the specified object. + + The object to validate. + Additional context parameters. + + The instance to add any error + messages to in the case of validation failure. + + + if validation was successful. + + + + + Creates a new instance of the class. + + + + + Creates a new instance of the class. + + The expression that determines if this validator should be evaluated. + + + + Creates a new instance of the class. + + The expression that determines if this validator should be evaluated. + + + + Validates the specified object. + + The object to validate. + instance to add error messages to. + True if validation was successful, False otherwise. + + + + Validates the specified object. + + The object to validate. + Additional context parameters. + instance to add error messages to. + True if validation was successful, False otherwise. + + + + Evaluates when expression. + + Root context to use for expression evaluation. + Additional context parameters. + True if the condition is true, False otherwise. + + + + Processes the error messages. + + Whether validator is valid or not. + Validation context. + Additional context parameters. + Validation errors container. + + + + Gets or sets the expression that determines if this validator should be evaluated. + + The expression that determines if this validator should be evaluated. + + + + Gets or sets the validation actions. + + The actions that should be executed after validation. + + + + Creates a new instance of the validator without any + and criteria + + + + + Creates a new instance of the class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + + + + Creates a new instance of the class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + + + + Validates the specified object. + + The object to validate. + Additional context parameters. + instance to add error messages to. + True if validation was successful, False otherwise. + + + + Validates test object. + + Object to validate. + True if specified object is valid, False otherwise. + + + + Evaluates test expression. + + Root context to use for expression evaluation. + Additional context parameters. + Result of the test expression evaluation, or validation context if test is null. + + + + Gets or sets the test expression. + + The test expression. + + + + Creates a new instance of the class. + + + + + Creates a new instance of the class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + + + + Creates a new instance of the class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + + + + Evaluates the test using condition evaluator. + + +

+ Test can be any logical expression that is supported by the Spring.NET logical + expression evaluation engine, and can use any variables that can be resolved + by the variable resolver used by the validation engine. +

+ + The object to validate. + + if the supplied is valid. + + + + + Perform credit card validations. + + + By default, all supported card types are allowed. You can specify + which credit card type validator should be used by setting + the value of property to a concrete + instance. + + + + + Creates a new instance of the UrlValidator class. + + + + + Creates a new instance of the UrlValidator class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + Credit Card type validator to use. + + + + Creates a new instance of the UrlValidator class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + Credit Card type validator to use. + + + + Validates the supplied . + + + In the case of the class, + the test should be a string variable that will be evaluated and the object + obtained as a result of this evaluation will be checked if it is + a valid credit card number. + + The object to validate. + + if the supplied is valid + credit card number. + + + + + Checks if the is a valid credit card number. + + + The card number to validate. + + + true if the card number is valid. + + + + + Validates card number with the specified validator. + + + Credit card number to validate. + + + true if credit card number is a valid number of credit card type specified. + + + + + Checks for a valid credit card number. + + + Credit Card Number. + + + true if the card number passes the LuhnCheck. + + + + + Credit card type validator to use. + + + Can be concrete implementations of + interface. The following are available implementations: + , , , + . + + + + + CreditCardType interface defines how validation is performed + for one type/brand of credit card. + + + + + Returns true if the card number matches this type of + credit card. + + + The card number, never null. + + + true if the number matches. + + + + + Visa credit card type validation support. + + + + + Indicates, wheter the given credit card number matches a visa number. + + + + + American Express credit card type validation support. + + + + + Indicates, wheter the given credit card number matches an amex number. + + + + + Discover credit card type validation support. + + + + + Indicates, wheter the given credit card number matches a discover number. + + + + + Mastercard credit card type validation support. + + + + + Indicates, wheter the given credit card number matches a mastercard number. + + + + + Perform email validations. + + +

+ This implementation is not guaranteed to catch all possible errors in an + email address. For example, an address like nobody@noplace.nowhere will + pass validator, even though there is no TLD "nowhere". + + Goran Milosavljevic + + +

+ Creates a new instance of the EmailValidator class. + + + + + Creates a new instance of the EmailValidator class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + + + + Creates a new instance of the EmailValidator class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + + + + Validates the supplied . + + + In the case of the class, + the test should be a string variable that will be evaluated and the object + obtained as a result of this evaluation will be checked if it is + a valid e-mail address. + + The object to validate. + + if the supplied is valid + e-mail address. + + + + + Regular expression used for validation of object passed to this . + + + + + Validates that the object is valid ISBN-10 or ISBN-13 value. + + Goran Milosavljevic + + + + Creates a new instance of the ISBNValidator class. + + + + + Creates a new instance of the ISBNValidator class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + + + + Creates a new instance of the ISBNValidator class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + + + + Validates the supplied . + + + In the case of the class, + the test should be a string variable that will be evaluated and the object + obtained as a result of this evaluation will be tested using the ISBN-10 or + ISBN-13 validation rules. + + The object to validate. + + if the supplied is valid ISBN. + + + + + Validates against ISBN-10 or ISBN-13 validation + rules. + + + ISBN string to validate. + + + true if is a valid ISBN-10 or ISBN-13 code. + + + + + ISBN-10 consists of 4 groups of numbers separated by either + dashes (-) or spaces. + + + The first group is 1-5 characters, second 1-7, third 1-6, + and fourth is 1 digit or an X. + + + + + ISBN-13 consists of 5 groups of numbers separated by either + dashes (-) or spaces. + + + The first group is 978 or 979, the second group is + 1-5 characters, third 1-7, fourth 1-6, and fifth is 1 digit. + + + + + Validates that object matches specified regular expression. + + +

+ The test expression must evaluate to a ; + otherwise, an exception is thrown. +

+ + Aleksandar Seovic + + + + Creates a new instance of the class. + + + + + Creates a new instance of the class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + The regular expression to match against. + + + + Creates a new instance of the class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + The regular expression to match against. + + + + Validates an object. + + Object to validate. + + if the supplied + object is valid. + + + If the supplied is not a + + + + + + The regular expression text to match against. + + The regular expression text. + + + + Gets or sets a value indicating whether to do a partial match instead of a full match. + Default is false. + + + + + The for the regular expression evaluation. + + The regular expression evaluation options. + + + + + Validates that required value is not empty. + + +

+ This validator uses following rules to determine if target value is valid: + + + + + + + + + + + + + + + + + + + + + + + + + +
Target Valid Value
A .Not or an empty string.
A .Not and not .
One of the number types.Not zero.
A .Not or whitespace.
Any reference type other than .Not .
+

+

+ You cannot use this validator to validate any value types other than the ones + specified in the table above. +

+ + Aleksandar Seovic + + + + Creates a new instance of the class. + + + + + Creates a new instance of the class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + + + + Creates a new instance of the class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + + + + Validates the supplied . + + + In the case of the class, + the test should be a variable expression that will be evaluated and the object + obtained as a result of this evaluation will be tested using the rules described + in the class overview of the + class. + + The object to validate. + + if the supplied is valid. + + + + + Validates that the value is valid URL. + + Goran Milosavljevic + + + + Creates a new instance of the UrlValidator class. + + + + + Creates a new instance of the UrlValidator class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + + + + Creates a new instance of the UrlValidator class. + + The expression to validate. + The expression that determines if this validator should be evaluated. + + + + Validates the supplied . + + + In the case of the class, + the test should be a string variable that will be evaluated and the object + obtained as a result of this evaluation will be tested using the URL validation rules. + + The object to validate. + + if the supplied is valid. + + + + + Regular expression used for validation of object passed to this . + + + + + implementation that supports grouping of validators. + + +

+ This validator will be valid when one or more of the validators in the Validators + collection are valid. +

+

+ ValidationErrors property will return a union of all validation error messages + for the contained validators, but only if this validator is not valid (meaning, when none + of the contained validators are valid). +

+

Note, that defaults to true for this validator type!

+ + Aleksandar Seovic + Erich Eichinger + + + + Base class for composite validators + + + + + Initializes a new instance + + + + + Initializes a new instance + + The expression that determines if this validator should be evaluated. + + + + Initializes a new instance + + The expression that determines if this validator should be evaluated. + + + + Validates the specified object. + + The object to validate. + Additional context parameters. + instance to add error messages to. + True if validation was successful, False otherwise. + + + + Actual implementation how to validate the specified object. + + The object to validate. + Additional context parameters. + instance to add error messages to. + True if validation was successful, False otherwise. + + + + Gets or sets the child validators. + + The validators. + + + + When set true, shortcircuits evaluation. + + + Setting this property true causes the evaluation process to prematurely abort + if the end result is known. Any remaining child validators will not be considered then. + Setting this value false causes implementations to evaluate all child validators, regardless + of the potentially already known result. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The expression that determines if this validator should be evaluated. + + + + Initializes a new instance of the class. + + The expression that determines if this validator should be evaluated. + + + + Validates the specified object. + + The object to validate. + Additional context parameters. + instance to add error messages to. + True if validation was successful, False otherwise. + + + + implementation that supports validating collections. + + +

+ This validator will be valid only when all of the validators in the Validators + collection are valid for all of the objects in the specified collection. +

+

+ You can specify if you want to validate all of the collection elements regardless of the errors by + setting the property to false. +

+

Note, that defaults to true for this validator type!

+

+ If you set the IncludeElementErrors property to true, + ValidationErrors collection will contain a union of all validation error messages + for the contained validators; + Otherwise it will contain only error messages that were set for this Validator. +

+ + Damjan Tomic + Aleksandar Seovic + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The bool that determines if all elements of the collection should be evaluated. + regardless of the Errors + + The bool that determines whether Validate method should collect + all error messages returned by the item validators + + + + Initializes a new instance of the class. + + The expression that determines if this validator should be evaluated. + The bool that determines if this all elements of the collection should be evaluated. + regardless of the Errors + + The bool that determines whether Validate method should collect + all error messages returned by the item validators + + + + Initializes a new instance of the class. + + The expression that determines if this validator should be evaluated. + The bool that determines if this all elements of the collection should be evaluated. + regardless of the Errors + + The bool that determines whether Validate method should collect + all error messages returned by the item validators + + + + Validates the specified collection of objects. + If the IncludeElementErrors property was set to true, + collection will contain a union of all validation error messages + for the contained validators; + Otherwise it will contain only error messages that were set for this Validator. + + The collection to validate. + Additional context parameters. + instance to add error messages to. + True if validation was successful, False otherwise. + + + + Actual implementation how to validate the specified object. + + The object to validate. + Additional context parameters. + instance to add error messages to. + True if validation was successful, False otherwise. + + + + Gets or sets the value that indicates whether to validate all elements of the collection + regardless of the errors. + + This is just an alias for property + + + + Gets or sets the value that indicates whether to capture all the errors of the specific + elements of the collection + + + + + Gets or sets the expression that should be used to narrow validation context. + + The expression that should be used to narrow validation context. + + + + implementation that supports grouping of validators. + + +

+ This validator will be valid when one and only one of the validators in the Validators collection are valid +

+

+ ValidationErrors property will return a union of all validation error messages + for the contained validators, but only if this validator is not valid (meaning, when none + of the contained validators are valid). +

+

+ By default, this validator group uses == true semantics. +

+ + Aleksandar Seovic + Erich Eichinger + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The expression that determines if this validator should be evaluated. + + + + Initializes a new instance of the class. + + The expression that determines if this validator should be evaluated. + + + + Actual implementation how to validate the specified object. + + The object to validate. + Additional context parameters. + instance to add error messages to. + True if validation was successful, False otherwise. + + + + An interface that validation errors containers have to implement. + + Aleksandar Seovic + + + + Adds the supplied to this + instance's collection of errors. + + + The provider that should be used for message grouping; can't be + . + + The error message to add. + + If the supplied or is . + + + + + Merges another instance of into this one. + + +

+ If the supplied is , + then no errors will be added to this instance, and this method will + (silently) return. +

+ + + The validation errors to merge; can be . + + + + + Gets the list of errors for the supplied error . + + +

+ If there are no errors for the supplied , + an empty will be returned. +

+ + Error key that was used to group messages. + + A list of all s for the supplied lookup . + + + + + Gets the list of resolved error messages for the supplied lookup . + + +

+ If there are no errors for the supplied lookup , + an empty will be returned. +

+ + Error key that was used to group messages. + to resolve messages against. + + A list of resolved error messages for the supplied lookup . + + + + + Does this instance contain any validation errors? + + +

+ If this returns , this means that it (obviously) + contains no validation errors. +

+ + if this instance is empty. + + + + Gets the list of all error providers. + + + + + Allows developers to specify which validator should be used + to validate method argument. + + Damjan Tomic + Aleksandar Seovic + + + + Creates an attribute instance. + + + The name of the validator to use (must be defined within + Spring application context). + + + + + Gets the name of the validator to use. + + The name of the validator to use. + + + + A container for validation errors. + + +

+ This class groups validation errors by validator names and allows + access to both the complete errors collection and to the errors for a + certain validator. +

+ + Aleksandar Seovic + Goran Milosavljevic + + + + Default constructor. + + + + + This property is reserved, apply the + + to the class instead. + + + An that describes the + XML representation of the object that is produced by + the + method and consumed by the + + method. + + + + + Generates an object from its XML representation. + + + The stream + from which the object is deserialized. + + + + + Converts an object into its XML representation. + + + The stream + to which the object is serialized. + + + + + Adds the supplied to this + instance's collection of errors. + + + The provider that should be used for message grouping; can't be + . + + The error message to add. + + If the supplied or is . + + + + + Merges another instance of into this one. + + +

+ If the supplied is , + then no errors will be added to this instance, and this method will + (silently) return. +

+ + + The validation errors to merge; can be . + + + + + Gets the list of errors for the supplied lookup . + + +

+ If there are no errors for the supplied lookup , + an empty will be returned. +

+ + Error key that was used to group messages. + + A list of all s for the supplied lookup . + + + + + Gets the list of resolved error messages for the supplied lookup . + + +

+ If there are no errors for the supplied lookup , + an empty will be returned. +

+ + Error key that was used to group messages. + to resolve messages against. + + A list of resolved error messages for the supplied lookup . + + + + + Does this instance contain any validation errors? + + +

+ If this returns , this means that it (obviously) + contains no validation errors. +

+ + if this instance is empty. + + + + Gets the list of all providers. + + + + + Thrown by the validation advice if the method parameters validation fails. + + Aleksandar Seovic + + + + Creates a new instance of the ValidationException class. + + + + + Creates a new instance of the ValidationException class with + specified validation errors. + + + Validation errors. + + + + + Creates a new instance of the ValidationException class with the + specified message. + + + A message about the exception. + + + + + Creates a new instance of the ValidationException class with the + specified message and validation errors. + + + A message about the exception. + + + Validation errors. + + + + + Creates a new instance of the ValidationException class with the + specified message and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the ValidationException class with the + specified message, root cause and validation errors. + + + A message about the exception. + + + The root exception that is being wrapped. + + + Validation errors. + + + + + Creates a new instance of the ValidationException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Implements object serialization. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Gets validation errors. + + Validation errors. + + + + implementation that supports grouping of validators. + + +

+ This validator will be valid only when all of the validators in the Validators + collection are valid. +

+

+ ValidationErrors property will return a union of all validation error messages + for the contained validators. +

+ + Aleksandar Seovic + Erich Eichinger + + + + Initializes a new instance + + + + + Initializes a new instance + + The expression that determines if this validator should be evaluated. + + + + Initializes a new instance + + The expression that determines if this validator should be evaluated. + + + + Actual implementation how to validate the specified object. + + The object to validate. + Additional context parameters. + instance to add error messages to. + True if validation was successful, False otherwise. + + + + Represents a reference to an externally defined validator object + + +

+ This class allows validation groups to reference validators that + are defined outside of the group itself. +

+

+ It also allows users to narrow the context for the referenced validator + by specifying value for the Context property. +

+ + Aleksandar Seovic + + + + Creates a new instance of the class. + + + + + Creates a new instance of the class. + + + The expression that determines if this validator should be evaluated. + + + + + Creates a new instance of the class. + + + The expression that determines if this validator should be evaluated. + + + + + Validates the specified object. + + The object to validate. + instance to add error messages to. + True if validation was successful, False otherwise. + + + + Validates the specified object. + + The object to validate. + Additional context parameters. + instance to add error messages to. + True if validation was successful, False otherwise. + + + + Gets or sets the name of the referenced validator. + + The name of the referenced validator. + + + + Gets or sets the expression that should be used to narrow validation context. + + The expression that should be used to narrow validation context. + + + + Gets or sets the expression that determines if this validator should be evaluated. + + The expression that determines if this validator should be evaluated. + + + + Callback that supplies the owning factory to an object instance. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + In case of initialization errors. + + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate20.dll b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate20.dll new file mode 100644 index 00000000..26b751ed Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate20.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate20.pdb b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate20.pdb new file mode 100644 index 00000000..3c781aaa Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate20.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate20.xml b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate20.xml new file mode 100644 index 00000000..7ee37713 --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate20.xml @@ -0,0 +1,6095 @@ + + + + Spring.Data.NHibernate20 + + + + + Convenient FactoryObject for defining Hibernate FilterDefinitions. + Exposes a corresponding Hibernate FilterDefinition object. + + + +

+ Typically defined as an inner object within a LocalSessionFactoryObject + definition, as the list element for the "filterDefinitions" object property. + For example: +

+ + 
+            <objectn id="sessionFactory" type="Spring.Data.NHibernate.LocalSessionFactoryObject, Spring.Data.NHibernate">
+              ...
+              <property name="FilterDefinitions">
+               <list>
+                  <object type="Spring.Data.NHibernate.FilterDefinitionFactoryObject, Spring.Data.NHibernate">
+                    <property name="FilterName" value="myFilter"/>
+                    <property name="ParameterTypes">
+                      <props>
+                        <prop key="MyParam">string</prop>
+                        <prop key="MyOtherParam">long</prop>
+                      </props>
+                    </property>
+                  </object>
+                </list>
+              </property>
+              ...
+            </object>
+
+

+ Alternatively, specify an object id (or name) attribute for the inner object, + instead of the "FilterName" property. +

+ + Juergen Hoeller + Marko Lahma (.NET) + + + $Id: FilterDefiniitionFactoryObject.cs,v 1.1 2008/04/07 20:12:53 lahma Exp $ + + + + Initializes the filter definitions. + + + + + Returns the singleton filter definition. + + + + + + Set the name of the filter. + + + + + Set the parameter types for the filter, + with parameter names as keys and type names as values. + + + + + + Specify a default filter condition for the filter, if any. + + + + + If no explicit filter name has been specified, the object name of + the FilterDefinitionFactoryObject will be used. + + + + + + Returns the type of the object this factory produces. + + + + + Returns whether this factory produces singletons, always true. + + + + + Hibernate-specific subclass of ObjectRetrievalFailureException. + + + Converts Hibernate's UnresolvableObjectException, ObjectNotFoundException, + ObjectDeletedException, and WrongClassException. + + Mark Pollack (.NET) + $Id: HibernateObjectRetrievalFailureException.cs,v 1.1 2008/04/07 20:12:53 lahma Exp $ + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Creates a new instance of the HibernateObjectRetrievalFailureException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Hibernate-specific subclass of ObjectOptimisticLockingFailureException. + + + Converts Hibernate's StaleObjectStateException. + + Mark Pollack (.NET) + $Id: HibernateOptimisticLockingFailureException.cs,v 1.2 2008/04/23 11:41:41 lahma Exp $ + + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The StaleStateException. + + + + Creates a new instance of the HibernateOptimisticLockingFailureException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + An IFactoryObject that creates a local Hibernate SessionFactory instance. + Behaves like a SessionFactory instance when used as bean reference, + e.g. for HibernateTemplate's "SessionFactory" property. + + + The typical usage will be to register this as singleton factory + in an application context and give objects references to application services + that need it. + + Hibernate configuration settings can be set using the IDictionary property 'HibernateProperties'. + + + This class implements the interface, + as autodetected by Spring's + for AOP-based translation of PersistenceExceptionTranslationPostProcessor. + Hence, the presence of e.g. LocalSessionFactoryBean automatically enables + a PersistenceExceptionTranslationPostProcessor to translate Hibernate exceptions. + + + Mark Pollack (.NET) + + + + The shared instance for this class (and derived classes). + + + + + Initializes a new instance of the class. + + + + + Return the singleon session factory. + + The singleon session factory. + + + + Initialize the SessionFactory for the given or the + default location. + + + + + Close the SessionFactory on application context shutdown. + + + + + Subclasses can override this method to perform custom initialization + of the Configuration instance used for ISessionFactory creation. + + + The properties of this LocalSessionFactoryObject will be applied to + the Configuration object that gets returned here. +

The default implementation creates a new Configuration instance. + A custom implementation could prepare the instance in a specific way, + or use a custom Configuration subclass. +

+ + The configuration instance. + + + + To be implemented by subclasses that want to to perform custom + post-processing of the Configuration object after this FactoryObject + performed its default initialization. + + The current configuration object. + + + + Executes schema update if requested. + + + + + Execute schema drop script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaExport class, to be invoked on application setup. + + + Fetch the LocalSessionFactoryBean itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfb = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute schema creation script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaExport class, to be invoked on application setup. + + + Fetch the LocalSessionFactoryObject itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfo = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute schema update script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaUpdate class, for automatically executing schema update scripts + on application startup. Can also be invoked manually. + + + Fetch the LocalSessionFactoryObject itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfo = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute the given schema script on the given ADO.NET Connection. + + + Note that the default implementation will log unsuccessful statements + and continue to execute. Override the ExecuteSchemaStatement + method to treat failures differently. + + The connection to use. + The SQL statement to execute. + + + + Execute the given schema SQL on the given ADO.NET command. + + + Note that the default implementation will log unsuccessful statements + and continue to execute. Override this method to treat failures differently. + + + + + + + Subclasses can override this method to perform custom initialization + of the SessionFactory instance, creating it via the given Configuration + object that got prepared by this LocalSessionFactoryObject. + + +

The default implementation invokes Configuration's BuildSessionFactory. + A custom implementation could prepare the instance in a specific way, + or use a custom ISessionFactory subclass. +

+ + The ISessionFactory instance. + + + + Implementation of the PersistenceExceptionTranslator interface, + as autodetected by Spring's PersistenceExceptionTranslationPostProcessor. + Converts the exception if it is a HibernateException; + else returns null to indicate an unknown exception. + translate the given exception thrown by a persistence framework to a + corresponding exception from Spring's generic DataAccessException hierarchy, + if possible. + + The exception thrown. + + the corresponding DataAccessException (or null if the + exception could not be translated. + + + + + + Convert the given HibernateException to an appropriate exception from the + Spring's DAO Exception hierarchy. + Will automatically apply a specified IAdoExceptionTranslator to a + Hibernate ADOException, else rely on Hibernate's default translation. + + The Hibernate exception that occured. + A corresponding DataAccessException + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + ADOException that occured, wrapping underlying ADO.NET exception. + + the corresponding DataAccessException instance + + + + + Setting the Application Context determines were resources are loaded from + + + + + Gets or sets the to use for loading mapping assemblies etc. + + + + + Sets the assemblies to load that contain mapping files. + + The mapping assemblies. + + + + Sets the hibernate configuration files to load, i.e. hibernate.cfg.xml. + + + + + Sets the locations of Spring IResources that contain mapping + files. + + The location of mapping resources. + + + + Return the Configuration object used to build the SessionFactory. + Allows access to configuration metadata stored there (rarely needed). + + The hibernate configuration. + + + + Set NHibernate configuration properties, like "hibernate.dialect". + + The hibernate properties. + +

Can be used to override values in a NHibernate XML config file, + or to specify all necessary properties locally. +

+

Note: Do not specify a transaction provider here when using + Spring-driven transactions. It is also advisable to omit connection + provider settings and use a Spring-set IDbProvider instead. +

+ + + + + Get or set the DataSource to be used by the SessionFactory. + + The db provider. + + If set, this will override corresponding settings in Hibernate properties. + Note: If this is set, the Hibernate settings should not define + a connection string + (hibernate.connection.connection_string) to avoid meaningless double configuration. + + + + + + Gets or sets a value indicating whether to expose a transaction aware session factory. + + + true if want to expose transaction aware session factory; otherwise, false. + + + + + Set a NHibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + Will get applied to any new Session created by this factory. +

Such an interceptor can either be set at the SessionFactory level, i.e. on + LocalSessionFactoryObject, or at the Session level, i.e. on HibernateTemplate, + HibernateInterceptor, and HibernateTransactionManager. It's preferable to set + it on LocalSessionFactoryObject or HibernateTransactionManager to avoid repeated + configuration and guarantee consistent behavior in transactions.

+ + + + + + + Set a Hibernate NamingStrategy for the SessionFactory, determining the + physical column and table names given the info in the mapping document. + + + + + Specify the Hibernate type definitions to register with the SessionFactory, + as Spring IObjectDefinition instances. This is an alternative to specifying + <typedef> elements in Hibernate mapping files. +

Unfortunately, Hibernate itself does not define a complete object that + represents a type definition, hence the need for Spring's TypeDefinitionBean.

+ @see TypeDefinitionBean + @see org.hibernate.cfg.Mappings#addTypeDef(String, String, java.util.Properties) + + + + + Specify the NHibernate FilterDefinitions to register with the SessionFactory. + This is an alternative to specifying <filter-def> elements in + Hibernate mapping files. + + + Typically, the passed-in FilterDefinition objects will have been defined + as Spring FilterDefinitionFactoryBeans, probably as inner beans within the + LocalSessionFactoryObject definition. + + + + + + Specify the cache strategies for entities (persistent classes or named entities). + This configuration setting corresponds to the <class-cache> entry + in the "hibernate.cfg.xml" configuration format. +

For example: + 

+            <property name="entityCacheStrategies">
+              <props>
+                <prop key="MyCompany.Customer">read-write</prop>
+                <prop key="MyCompany.Product">read-only,myRegion</prop>
+              </props>
+            </property>
+

+ + + + + Specify the cache strategies for persistent collections (with specific roles). + This configuration setting corresponds to the <collection-cache> entry + in the "hibernate.cfg.xml" configuration format. +

For example: + 

+            <property name="CollectionCacheStrategies">
+              <props>
+                <prop key="MyCompany.Order.Items">read-write</prop>
+                <prop key="MyCompany.Product.Categories">read-only,myRegion</prop>
+              </props>
+            </property>
+

+ + + + + Specify the NHibernate event listeners to register, with listener types + as keys and listener objects as values. +

+ Instead of a single listener object, you can also pass in a list + or set of listeners objects as value. +

+ + listener objects as values + + See the NHibernate documentation for further details on listener types + and associated listener interfaces. + + + + + Set whether to execute a schema update after SessionFactory initialization. +

+ For details on how to make schema update scripts work, see the NHibernate + documentation, as this class leverages the same schema update script support + in as NHibernate's own SchemaUpdate tool. +

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Return the type or subclass. + + The type created by this factory + + + + Returns true + + true + + + + Holds the references and configuration settings for a instance. + References are resolved by looking up the given object names in the root obtained by . + + + + + Holds the references and configuration settings for a instance. + + + + + Default value for property. + + + + + Default value for property. + + + + + Initialize a new instance of with default values. + + + Calling this constructor from your derived class leaves and + uninitialized. See and for more. + + + + + Initialize a new instance of with the given sessionFactory + and default values for all other settings. + + + The instance to be used for obtaining instances. + + + Calling this constructor marks all properties initialized. + + + + + Initialize a new instance of with the given values and references. + + + The instance to be used for obtaining instances. + + + Specify the to be set on each session provided by the instance. + + + Set whether to use a single session for each request. See property for details. + + + Specify the flushmode to be applied on each session provided by the instance. + + + Calling this constructor marks all properties initialized. + + + + + Override this method to resolve an instance according to your chosen strategy. + + + + + Override this method to resolve an instance according to your chosen strategy. + + + + + Gets the configured instance to be used. + + + If the entity interceptor is not set by the constructor, this property calls + to obtain an instance. This allows derived classes to + override the behaviour of how to obtain the concrete instance. + + + + + Gets the configured instance to be used. + + + If this property is requested for the first time, is called. + This allows derived classes to override the behaviour of how to obtain the concrete instance. + + If the instance cannot be resolved. + + + + Set whether to use a single session for each request. Default is "true". + If set to false, each data access operation or transaction will use + its own session (like without Open Session in View). Each of those + sessions will be registered for deferred close, though, actually + processed at request completion. + + + + + Gets or Sets the flushmode to be applied on each newly created session. + + + This property defaults to to ensure that modifying objects outside the boundaries + of a transaction will not be persisted. It is recommended to not change this value but wrap any modifying operation + within a transaction. + + + + + The default session factory name to use when retrieving the Hibernate session factory from + the root context. + + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + The configuration section to read setting variables from. + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + The variable source to obtain settings from. + + + + Resolve the entityInterceptor by looking up + in the root application context. + + The resolved instance or + + + + Resolve the by looking up + in the root application context. + + The resolved instance or + + + + Convenient super class for Hibernate data access objects. + + + Requires a SessionFactory to be set, providing a HibernateTemplate + based on it to subclasses. Can alternatively be initialized directly with + a HibernateTemplate, to reuse the latter's settings such as the SessionFactory, + exception translator, flush mode, etc + + This base call is mainly intended for HibernateTemplate usage. + + This class will create its own HibernateTemplate if only a SessionFactory + is passed in. The "allowCreate" flag on that HibernateTemplate will be "true" + by default. A custom HibernateTemplate instance can be used through overriding + CreateHibernateTemplate. + + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Create a HibernateTemplate for the given ISessionFactory. + + + Only invoked if populating the DAO with a ISessionFactory reference! +

Can be overridden in subclasses to provide a HibernateTemplate instance + with different configuration, or a custom HibernateTemplate subclass. +

+ + + + + Check if the hibernate template property has been set. + + + + + Get a Hibernate Session, either from the current transaction or + a new one. The latter is only allowed if "allowCreate" is true. + + Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Either rely on a thread-bound + Session (via HibernateInterceptor), or use it in combination with + ReleaseSession. + + In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. + + + if a non-transactional Session should be created when no + transactional Session can be found for the current thread + + Hibernate session. + + If the Session couldn't be created + + + if no thread-bound Session found and allowCreate false + + + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Close the given Hibernate Session, created via this DAO's SessionFactory, + if it isn't bound to the thread. + + + Typically used in plain Hibernate code, in combination with the + Session property and ConvertHibernateAccessException. + + The session to close. + + + + Gets or sets the hibernate template. + + Set the HibernateTemplate for this DAO explicitly, + as an alternative to specifying a SessionFactory. + + The hibernate template. + + + + Gets or sets the session factory to be used by this DAO. + Will automatically create a HibernateTemplate for the given SessionFactory. + + The session factory. + + + + Get a Hibernate Session, either from the current transaction or a new one. + The latter is only allowed if the "allowCreate" setting of this object's + HibernateTemplate is true. + + +

Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Use it in combination with + ReleaseSession. +

+

In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. +

+ + The Hibernate session. + + + + Provide support for the open session in view pattern for lazily loaded hibernate objects + used in ASP.NET pages. + + jjx: http://forum.springframework.net/member.php?u=29 + Mark Pollack (.NET) + Erich Eichinger + Harald Radi + + + + Implementation of SessionScope that associates a single session within the using scope. + + + It is recommended to be used in the following type of scenario: + + using (new SessionScope()) + { + ... do multiple operation, possibly in multiple transactions. + } + + At the end of "using", the session is automatically closed. All transactions within the scope use the same session, + if you are using Spring's HibernateTemplate or using Spring's implementation of NHibernate 1.2's + ICurrentSessionContext interface. + + + It is assumed that the session factory object name is called "SessionFactory". In case that you named the object + in different way you can specify your can specify it in the application settings using the key + Spring.Data.NHibernate.Support.SessionScope.SessionFactoryObjectName. Values for EntityInterceptorObjectName + and SingleSessionMode can be specified similarly. + + + Note: + The session is managed on a per thread basis on the thread that opens the scope instance. This means that you must + never pass a reference to a instance over to another thread! + + + Robert M. (.NET) + Harald Radi (.NET) + + + + The logging instance. + + + + + Initializes a new instance of the class in single session mode, + associating a session with the thread. The session is opened lazily on demand. + + + + + Initializes a new instance of the class. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The name of the configuration section to read configuration settings from. + See for more info. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The name of the configuration section to read configuration settings from. + See for more info. + + The type, who's full name is used for prefixing appSetting keys + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The instance to be used for obtaining instances. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The instance to be used for obtaining instances. + + + Specify the to be set on each session provided by this instance. + + + Set whether to use a single session for each request. See property for details. + + + Specify the flushmode to be applied on each session provided by this instance. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + An instance holding the scope configuration + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Sets a flag, whether this scope is in "open" state on the current logical thread. + + + + + Gets/Sets a flag, whether this scope manages it's own session for the current logical thread or not. + + false if session is managed by this module. false otherwise + + + + Call Close(), + + + + + Opens a new session or participates in an existing session and + registers with spring's . + + + + + Close the current view's session and unregisters + from spring's . + + + + + Set whether to use a single session for each request. Default is "true". + If set to false, each data access operation or transaction will use + its own session (like without Open Session in View). Each of those + sessions will be registered for deferred close, though, actually + processed at request completion. + + + + + Gets the flushmode to be applied on each newly created session. + + + This property defaults to to ensure that modifying objects outside the boundaries + of a transaction will not be persisted. It is recommended to not change this value but wrap any modifying operation + within a transaction. + + + + + Get or set the configured SessionFactory + + + + + Get or set the configured EntityInterceptor + + + + + Gets a flag, whether this scope is in "open" state on the current logical thread. + + + + + Gets a flag, whether this scope manages it's own session for the current logical thread or not. + + + + + This sessionHolder creates a default session only if it is needed. + + + Although a NHibernateSession deferes creation of db-connections until they are really + needed, instantiation a session is imho still more expensive than this LazySessionHolder. (EE) + + + + + Session holder, wrapping a NHibernate ISession and a NHibernate Transaction. + HibernateTransactionManager binds instances of this class + to the thread, for a given ISessionFactory. + + + Note: This is an SPI class, not intended to be used by applications. + + Mark Pollack (.NET) + + + + May be used by derived classes to create an empty SessionHolder. + + + When using this ctor in your derived class, you MUST override ! + + + + + Initializes a new instance of the class. + + The session. + + + + Initializes a new instance of the class. + + The key to store the session under. + The hibernate session. + + + + May be overridden in a derived class to e.g. lazily create a session + + + + + Gets the session given key identifier + + The key. + A hibernate session + + + + Gets the session given the key and removes the session from + the dictionary storage. + + The key. + A hibernate session + + + + Adds the session to the dictionary storage using the default key. + + The hibernate session. + + + + Adds the session to the dictionary storage using the supplied key. + + The key. + The hibernate session. + + + + Removes the session from the dictionary storage for the given key. + + The key. + The session that was previously contained in the + dictionary storage. + + + + Determines whether the holder the specified session. + + The session. + + true if the holder contains the specified session; otherwise, false. + + + + + Clear the transaction state of this resource holder. + + + + + Gets the session using the default key + + The hibernate session. + + + + Gets the first session based on iteration over + the IDictionary storage. + + Any hibernate session. + + + + Gets a value indicating whether dictionary of + hibernate sessions is empty. + + + true if this session holder is empty; otherwise, false. + + + + + Gets a value indicating whether this SessionHolder + does not hold non default session. + + + true if does not hold non default session; otherwise, false. + + + + + Gets or sets the hibernate transaction. + + The transaction. + + + + Gets or sets the ADO.NET Connection used to create the session. + + The ADO.NET connection. + + + + Gets or sets the previous flush mode. + + The previous flush mode. + + + + Gets a value indicating whether the PreviousFlushMode property + was set. + + + true if assigned PreviousFlushMode property; otherwise, false. + + + + + Gets the validated session. + + The validated session. + + + + Initialize a new instance. + + + + + Create a new session on demand + + + + + Ensure session is closed (if any) and remove circular references to avoid memory leaks! + + + + + Initializes a new instance of the class. Creates a SessionScope, + but does not yet associate a session with a thread, that is left to the lifecycle of the request. + + + + + Register context handler and look up SessionFactoryObjectName under the application configuration key, + Spring.Data.NHibernate.Support.OpenSessionInViewModule.SessionFactoryObjectName if not using the default value + (i.e. sessionFactory) and look up the SingleSession setting under the application configuration key, + Spring.Data.NHibernate.Support.OpenSessionInViewModule.SingleSession if not using the default value of true. + + The standard HTTP application context + + + + A do nothing dispose method. + + + + + Hibernate-specific subclass of UncategorizedDataAccessException, + for ADO.NET exceptions that Hibernate rethrew and could not be + mapped into the DAO exception heirarchy. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception from the underlying data access API - ADO.NET + + + + + Creates a new instance of the HibernateSystemException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Hibernate-specific subclass of InvalidDataAccessResourceUsageException, + thrown on invalid HQL query syntax. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Initializes a new instance of the class. + + The ex. + + + + Creates a new instance of the HibernateQueryException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Gets the query string that was invalid. + + The query string that was invalid. + + + + Hibernate-specific subclass of UncategorizedDataAccessException, + for Hibernate system errors that do not match any concrete + Spring.Dao exceptions. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message. + + + + Creates a new instance of the HibernateSystemException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Initializes a new instance of the class. + + The cause. + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Helper class that simplifies NHibernate data access code + + +

Typically used to implement data access or business logic services that + use NHibernate within their implementation but are Hibernate-agnostic in their + interface. The latter or code calling the latter only have to deal with + domain objects.

+ +

The central method is Execute supporting Hibernate access code + implementing the HibernateCallback interface. It provides NHibernate Session + handling such that neither the IHibernateCallback implementation nor the calling + code needs to explicitly care about retrieving/closing NHibernate Sessions, + or handling Session lifecycle exceptions. For typical single step actions, + there are various convenience methods (Find, Load, SaveOrUpdate, Delete). +

+ +

Can be used within a service implementation via direct instantiation + with a ISessionFactory reference, or get prepared in an application context + and given to services as an object reference. Note: The ISessionFactory should + always be configured as an object in the application context, in the first case + given to the service directly, in the second case to the prepared template. +

+ +

This class can be considered as direct alternative to working with the raw + Hibernate Session API (through SessionFactoryUtils.Session). +

+ +

LocalSessionFactoryObject is the preferred way of obtaining a reference + to a specific NHibernate ISessionFactory. +

+ + Mark Pollack (.NET) + + + + Base class for HibernateTemplate defining common + properties like SessionFactory and flushing behavior. + + +

Not intended to be used directly. See HibernateTemplate. +

+ + Mark Pollack (.NET) + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Apply the flush mode that's been specified for this accessor + to the given Session. + + The current Hibernate Session. + if set to true + if executing within an existing transaction. + + the previous flush mode to restore after the operation, + or null if none + + + + + Flush the given Hibernate Session if necessary. + + The current Hibernate Session. + if set to true + if executing within an existing transaction. + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + ADOException that occured, wrapping underlying ADO.NET exception. + + the corresponding DataAccessException instance + + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + + + Note that a direct SQLException can just occur when callback code + performs direct ADO.NET access via ISession.Connection(). + + + The ADO.NET exception. + The corresponding DataAccessException instance + + + + Prepare the given IQuery object, applying cache settings and/or + a transaction timeout. + + The query object to prepare. + + + + Apply the given name parameter to the given Query object. + + The query object. + Name of the parameter + The value of the parameter + The NHibernate type of the parameter (or null if none specified) + + + + Prepare the given Criteria object, applying cache settings and/or + a transaction timeout. + + + Note that for NHibernate 1.2 this only works if the + implementation is of the type CriteriaImpl, which should generally + be the case. The SetFetchSize method is not available on the + ICriteria interface + + This is a no-op for NHibernate 1.0.x since + the SetFetchSize method is not on the ICriteria interface and + the implementation class is has internal access. + + To remove the method completely for Spring's NHibernate 1.0 + support while reusing code for NHibernate 1.2 would not be + possible. So now this ineffectual operation is left in tact for + NHibernate 1.0.2 support. + + The criteria object to prepare + + + + Ensure SessionFactory is not null + + If SessionFactory property is null. + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Set the object factory instance. + + The object factory instance. + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Gets a Session for use by this template. + + The session. + + - Returns a new Session in case of "alwaysUseNewSession" (using the same ADO.NET connection as a transaction Session, if applicable) + - a pre-bound Session in case of "AllowCreate" is set to false (not the default) + - or a pre-bound Session or new Session if no transactional or other pre-bound Session exists. + + + + + Helper class to determine if the FlushMode enumeration + was changed from its default value + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The flush mode. + + + + Gets or sets a value indicating whether the FlushMode + property was set.. + + true if FlushMode was set; otherwise, false. + + + + Gets or sets the FlushMode. + + The FlushMode. + + + + Interface that specifies a basic set of Hibernate operations. + + + Implemented by HibernateTemplate. Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + + Mark Pollack (.NET) + + + + Interface that specifies a set of Hibernate operations that + are common across versions of Hibernate. + + + Base interface for generic and non generic IHibernateOperations interfaces + Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + Mark Pollack (.NET) + + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + In case of Hibernate errors + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + Tthe persistent instance to delete. + The lock mode to obtain. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Delete all given persistent instances. + + The persistent instances to delete. + + This can be combined with any of the find methods to delete by query + in two lines of code, similar to Session's delete by query methods. + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the specified action assuming that the result object is a List. + + + This is a convenience method for executing Hibernate find calls or + queries within an action. + + The calback object that specifies the Hibernate action. + A IList returned by the action, or null + + In case of Hibernate errors + + + + Execute a query for persistent instances. + + a query expressed in Hibernate's query language + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + a query expressed in Hibernate's query language + the value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + a query expressed in Hibernate's query language + the values of the parameters + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + a List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + + a persistent type. + An identifier of the persistent instance. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + A persistent class. + An identifier of the persistent instance. + The lock mode. + the persistent instance, or null if not found + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + Type of the entity. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + Type of the entity. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + Type of the entity. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Save or update all given persistent instances, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instances to save or update + (to be associated with the Hibernate Session)he entities. + In case of Hibernate errors + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The default for creating a new non-transactional + session when no transactional Session can be found for the current thread + is set to true. + The session factory to create sessions. + + + + Initializes a new instance of the class. + + The session factory to create sessions. + if set to true allow creation + of a new non-transactional when no transactional Session can be found + for the current thread. + + + + Delegate function that clears the session. + + The hibernate session. + null + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + + The type. + An identifier of the persistent instance. + The persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The type. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + Type of the entity. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + Type of the entity. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + Type of the entity. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update all given persistent instances, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instances to save or update + (to be associated with the Hibernate Session)he entities. + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + Tthe persistent instance to delete. + The lock mode to obtain. + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + If length for argument values and types are not equal. + + + + Delete all given persistent instances. + + The persistent instances to delete. + + This can be combined with any of the find methods to delete by query + in two lines of code, similar to Session's delete by query methods. + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + + + + Execute the action specified by the given action object within a Session. + + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the specified action assuming that the result object is a List. + + + This is a convenience method for executing Hibernate find calls or + queries within an action. + + The calback object that specifies the Hibernate action. + A IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + + + + Execute a query for persistent instances. + + a query expressed in Hibernate's query language + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + a query expressed in Hibernate's query language + the value of the parameter + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + a query expressed in Hibernate's query language + the values of the parameters + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Create a close-suppressing proxy for the given Hibernate Session. + The proxy also prepares returned Query and Criteria objects. + + The session. + The session proxy. + + + + Check whether write operations are allowed on the given Session. + + + Default implementation throws an InvalidDataAccessApiUsageException + in case of FlushMode.Never. Can be overridden in subclasses. + + The current Hibernate session. + If write operation is attempted in read-only mode + + + + + Compares if the flush mode enumerations, Spring's + TemplateFlushMode and NHibernates FlushMode have equal + settings. + + The template flush mode. + The NHibernate flush mode. + + Returns true if both are Never, Auto, or Commit, false + otherwise. + + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + If object factory is not set and need to retrieve entity interceptor by name. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets whether to check that the Hibernate Session is not in read-only mode + in case of write operations (save/update/delete). + + + true if check that the Hibernate Session is not in read-only mode + in case of write operations; otherwise, false. + + + Default is "true", for fail-fast behavior when attempting write operations + within a read-only transaction. Turn this off to allow save/update/delete + on a Session with flush mode NEVER. + + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Set the object factory instance. + + The object factory instance + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the proxy factory. + + This may be useful to set if you create many instances of + HibernateTemplate and/or HibernateDaoSupport. This allows the same + ProxyFactory implementation to be used thereby limiting the + number of dynamic proxy types created in the temporary assembly, which + are never garbage collected due to .NET runtime semantics. + + The proxy factory. + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Callback interface for NHibernate code. + + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + Mark Pollack (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + A result object, or null if none. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + PlatformTransactionManager implementation for a single Hibernate SessionFactory. + Binds a Hibernate Session from the specified factory to the thread, potentially + allowing for one thread Session per factory + + + SessionFactoryUtils and HibernateTemplate are aware of thread-bound Sessions and participate in such + transactions automatically. Using either of those is required for Hibernate + access code that needs to support this transaction handling mechanism. + + Supports custom isolation levels at the start of the transaction + , and timeouts that get applied as appropriate + Hibernate query timeouts. To support the latter, application code must either use + HibernateTemplate (which by default applies the timeouts) or call + SessionFactoryUtils.applyTransactionTimeout for each created + Hibernate Query object. + + Note that you can specify a Spring IDbProvider instance which if shared with + a corresponding instance of AdoTemplate will allow for mixing ADO.NET/NHibernate + operations within a single transaction. + + Mark Pollack (.NET) + + + + Just needed for entityInterceptorBeanName. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The session factory. + + + + Return the current transaction object. + + The current transaction object. + + If transaction support is not available. + + + In the case of lookup or system errors. + + + + + Check if the given transaction object indicates an existing, + i.e. already begun, transaction. + + + Transaction object returned by + . + + True if there is an existing transaction. + + In the case of system errors. + + + + + Begin a new transaction with the given transaction definition. + + + Transaction object returned by + . + + + instance, describing + propagation behavior, isolation level, timeout etc. + + + Does not have to care about applying the propagation behavior, + as this has already been handled by this abstract manager. + + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + + Transaction object returned by + . + + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + Transaction synchronization will already have been suspended. + + + If suspending is not supported by the transaction manager implementation. + + + in case of system errors. + + + + + Resume the resources of the current transaction. + + + Transaction object returned by + . + + + The object that holds suspended resources as returned by + . + + + Transaction synchronization will be resumed afterwards. + + + If suspending is not supported by the transaction manager implementation. + + + In the case of system errors. + + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + +

+ An implementation does not need to check the rollback-only flag. +

+ + + In the case of system errors. + + + + + Perform an actual rollback on the given transaction. + + The status representation of the transaction. + + An implementation does not need to check the new transaction flag. + + + In the case of system errors. + + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + The status representation of the transaction. + + In the case of system errors. + + + + + Gets the ADO.NET IDbTransaction object from the NHibernate ITransaction object. + + The hibernate transaction. + The ADO.NET transaction. Null if could not get the transaction. Warning + messages will be logged in that case. + + + + Convert the given HibernateException to an appropriate exception from + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The HibernateException that occured. + The corresponding DataAccessException instance + + + + Convert the given ADOException to an appropriate exception from the + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The ADOException that occured, wrapping the underlying + ADO.NET thrown exception. + The translator to convert hibernate ADOExceptions. + + The corresponding DataAccessException instance + + + + + Cleanup resources after transaction completion. + + Transaction object returned by + . + + + This implemenation unbinds the SessionFactory and + DbProvider from thread local storage and closes the + ISession. + +

+ Called after + and + + execution on any outcome. +

+

+ Should not throw any exceptions but just issue warnings on errors. +

+ + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Gets or sets the db provider. + + The db provider. + + + + Gets or sets a Hibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + When getting, return the current Hibernate entity interceptor, or null if none. + + The entity interceptor. + + Resolves an entity interceptor object name via the object factory, + if necessary. + Will get applied to any new Session created by this transaction manager. + Such an interceptor can either be set at the SessionFactory level, + i.e. on LocalSessionFactoryObject, or at the Session level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. + + If object factory is null and need to get entity interceptor via object name. + + + + Sets the object name of a Hibernate entity interceptor that + allows to inspect and change property values before writing to and reading from the database. + + The name of the entity interceptor object. + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + + + + Gets or sets the ADO.NET exception translator for this transaction manager. + + + Applied to ADO.NET Exceptions (wrapped by Hibernate's ADOException) + + The ADO exception translator. + + + + Gets the default IAdoException translator, lazily creating it if nece + + The default IAdoException translator. + + + + Gets or sets the SessionFactory that this instance should manage transactions for. + + The session factory. + + + + Gets the resource factory that this transaction manager operates on, + For the HibenratePlatformTransactionManager this the SessionFactory + + The SessionFactory. + + + + Set whether to autodetect a ADO.NET connection used by the Hibernate SessionFactory, + if set via LocalSessionFactoryObject's DbProvider. Default is "true". + + + true if [autodetect data source]; otherwise, false. + + +

Can be turned off to deliberately ignore an available IDbProvider, + to not expose Hibernate transactions as ADO.NET transactions for that IDbProvider. +

+ + + + + The object factory just needs to be known for resolving entity interceptor + It does not need to be set for any other mode of operation. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + + + + Return whether the transaction is internally marked as rollback-only. + + + True of the transaction is marked as rollback-only. + + + + Enumeration for the various Hibernate flush modes. + + Mark Pollack (.NET) + + + Never flush is a good strategy for read-only units of work. + + + Hibernate will not track and look for changes in this case, + avoiding any overhead of modification detection. +

In case of an existing ISession, TemplateFlushMode.Never will turn + the hibenrate flush mode + to FlushMode.Never for the scope of the current operation, resetting the previous + flush mode afterwards. +

+ + + + Automatic flushing is the default mode for a Hibernate Session. + + + A session will get flushed on transaction commit, and on certain find + operations that might involve already modified instances, but not + after each unit of work like with eager flushing. +

In case of an existing Session, TemplateFlushMode.Auto + will participate in the existing flush mode, not modifying + it for the current operation. + This in particular means that this setting will not modify an existing + hibernate flush mode FlushMode.Never, in contrast to TemplateFlushMode.Eager. +

+ + + + + Eager flushing leads to immediate synchronization with the database, + even if in a transaction. + + + This causes inconsistencies to show up and throw + a respective exception immediately, and ADO access code that participates + in the same transaction will see the changes as the database is already + aware of them then. But the drawbacks are: +
    +
  • additional communication roundtrips with the database, instead of a + single batch at transaction commit;
    • +
  • the fact that an actual database rollback is needed if the Hibernate + transaction rolls back (due to already submitted SQL statements).
    • +
+

In case of an existing Session, TemplateFlushMode.Eager + will turn the NHibernate flush mode + to FlushMode.Auto for the scope of the current operation and issue a flush at the + end, resetting the previous flush mode afterwards. +

+ + + + + Flushing at commit only is intended for units of work where no + intermediate flushing is desired, not even for find operations + that might involve already modified instances. + + +

In case of an existing Session, TemplateFlushMode.Commit + will turn the NHibernate flush mode + to FlushMode.Commit for the scope of the current operation, resetting the previous + flush mode afterwards. The only exception is an existing flush mode + FlushMode.Never, which will not be modified through this setting. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning an IList of result objects created within the callback. + Note that there's special support for single step actions: + see HibernateTemplate.find etc. +

+ + The type of result object + Sree Nivask (.NET) + + + + Convenient super class for Hibernate data access objects. + + + Requires a SessionFactory to be set, providing a HibernateTemplate + based on it to subclasses. Can alternatively be initialized directly with + a HibernateTemplate, to reuse the latter's settings such as the SessionFactory, + exception translator, flush mode, etc + + This base call is mainly intended for HibernateTemplate usage. + + This class will create its own HibernateTemplate if only a SessionFactory + is passed in. The "allowCreate" flag on that HibernateTemplate will be "true" + by default. A custom HibernateTemplate instance can be used through overriding + CreateHibernateTemplate. + + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Create a HibernateTemplate for the given ISessionFactory. + + + Only invoked if populating the DAO with a ISessionFactory reference! +

Can be overridden in subclasses to provide a HibernateTemplate instance + with different configuration, or a custom HibernateTemplate subclass. +

+ + The new HibernateTemplate instance + + + + Check if the hibernate template property has been set. + + If HibernateTemplate property is null. + + + + Get a Hibernate Session, either from the current transaction or + a new one. The latter is only allowed if "allowCreate" is true. + + Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Either rely on a thread-bound + Session (via HibernateInterceptor), or use it in combination with + ReleaseSession. + + In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. + + + if a non-transactional Session should be created when no + transactional Session can be found for the current thread + + Hibernate session. + + If the Session couldn't be created + + + if no thread-bound Session found and allowCreate false + + + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Close the given Hibernate Session, created via this DAO's SessionFactory, + if it isn't bound to the thread. + + + Typically used in plain Hibernate code, in combination with the + Session property and ConvertHibernateAccessException. + + The session to close. + + + + Gets or sets the hibernate template. + + Set the HibernateTemplate for this DAO explicitly, + as an alternative to specifying a SessionFactory. + + The hibernate template. + + + + Gets or sets the session factory to be used by this DAO. + Will automatically create a HibernateTemplate for the given SessionFactory. + + The session factory. + + + + Get a Hibernate Session, either from the current transaction or a new one. + The latter is only allowed if the "allowCreate" setting of this object's + HibernateTemplate is true. + + +

Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Use it in combination with + ReleaseSession. +

+

In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. +

+ + The Hibernate session. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning the result object created within the callback. + Note that there's special support for single step actions: + see HibernateTemplate.find etc. +

+ + The type of result object + Sree Nivask (.NET) + + + + Generic version of the Helper class that simplifies NHibernate data access code + + +

Typically used to implement data access or business logic services that + use NHibernate within their implementation but are Hibernate-agnostic in their + interface. The latter or code calling the latter only have to deal with + domain objects.

+ +

The central method is Execute() supporting Hibernate access code which + implements the HibernateCallback interface. It provides NHibernate Session + handling such that neither the IHibernateCallback implementation nor the calling + code needs to explicitly care about retrieving/closing NHibernate Sessions, + or handling Session lifecycle exceptions. For typical single step actions, + there are various convenience methods (Find, Load, SaveOrUpdate, Delete). +

+ +

Can be used within a service implementation via direct instantiation + with a ISessionFactory reference, or get prepared in an application context + and given to services as an object reference. Note: The ISessionFactory should + always be configured as an object in the application context, in the first case + given to the service directly, in the second case to the prepared template. +

+ +

This class can be considered as a direct alternative to working with the raw + Hibernate Session API (through SessionFactoryUtils.Session). +

+ +

LocalSessionFactoryObject is the preferred way of obtaining a reference + to a specific NHibernate ISessionFactory. +

+ + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Interface that specifies a basic set of Hibernate operations. + + + Implemented by HibernateTemplate. Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Return the persistent instance of the given entity type + with the given identifier, or if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The id of the object to get. + the persistent instance, or if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + The object type to load. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + The object type to load. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + The object type to load. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances. + + The object type to find. + a query expressed in Hibernate's query language + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the value of the parameter + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + The object type to find. + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the values of the parameters + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lenths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type retrieved. + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type retrieved. + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type to find. + The delegate callback object that specifies the Hibernate action. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type to find. + The FindHibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type to find. + The callback object that specifies the Hibernate action. + + A generic IList returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + + + + Execute the action specified by the given action object within a Session assuming that an IList is returned. + + The object type to find. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + an IList returned by the action, or null + + In case of Hibernate errors + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + Allows creation of a new non-transactional session when no + transactional Session can be found for the current thread + The session factory to create sessions. + + + + Initializes a new instance of the class. + + The session factory to create sessions. + if set to true allow creation + of a new non-transactional session when no transactional Session can be found + for the current thread. + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + Tthe persistent instance to delete. + The lock mode to obtain. + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The id of the object to get. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + The object type to load. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + The object type to load. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + The object type to load. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances. + + The object type to find. + a query expressed in Hibernate's query language + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the value of the parameter + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + The object type to find. + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the values of the parameters + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type retrieved. + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type retrieved. + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session assuming that an IList is returned. + + The object type to find. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + an IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type to find. + The delegate callback object that specifies the Hibernate action. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type to find. + The FindHibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type to find. + The callback object that specifies the Hibernate action. + + A generic IList returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Set the object factory instance. + + The object factory instance + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Gets the classic hibernate template for access to non-generic methods. + + The classic hibernate template. + + + + Gets or sets the proxy factory. + + This may be useful to set if you create many instances of + HibernateTemplate and/or HibernateDaoSupport. This allows the same + ProxyFactory implementation to be used thereby limiting the + number of dynamic proxy types created in the temporary assembly, which + are never garbage collected due to .NET runtime semantics. + + The proxy factory. + + + + Callback interface (Generic version) for NHibernate code. + + The type of result object + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + + Sree Nivask (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + A result object. + The active Hibernate session + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Callback interface (Generic version) for NHibernate code that + returns a List of objects. + + The type of result object + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + Collection result object. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Helper class featuring methods for Hibernate Session handling, + allowing for reuse of Hibernate Session instances within transactions. + Also provides support for exception translation. + + Mark Pollack (.NET) + + + + The instance for this class. + + + + + The ordering value for synchronizaiton this session resources. + Set to be lower than ADO.NET synchronization. + + + + + Initializes a new instance of the class. + + + + + Get a new Hibernate Session from the given SessionFactory. + Will return a new Session even if there already is a pre-bound + Session for the given SessionFactory. + + + Within a transaction, this method will create a new Session + that shares the transaction's ADO.NET Connection. More specifically, + it will use the same ADO.NET Connection as the pre-bound Hibernate Session. + + The session factory to create the session with. + The Hibernate entity interceptor, or null if none. + The new session. + If could not open Hibernate session + + + + Get a Hibernate Session for the given SessionFactory. Is aware of and will + return any existing corresponding Session bound to the current thread, for + example when using HibernateTransactionManager. Will always create a new + Session otherwise. + + + Supports setting a Session-level Hibernate entity interceptor that allows + to inspect and change property values before writing to and reading from the + database. Such an interceptor can also be set at the SessionFactory level + (i.e. on LocalSessionFactoryObject), on HibernateTransactionManager, or on + HibernateInterceptor/HibernateTemplate. + + The session factory to create the + session with. + Hibernate entity interceptor, or null if none. + AdoExceptionTranslator to use for flushing the + Session on transaction synchronization (can be null; only used when actually + registering a transaction synchronization). + The Hibernate Session + + If the session couldn't be created. + + + If no thread-bound Session found and allowCreate is false. + + + + + Get a Hibernate Session for the given SessionFactory. Is aware of and will + return any existing corresponding Session bound to the current thread, for + example when using . Will create a new Session + otherwise, if allowCreate is true. + + The session factory to create the session with. + if set to true create a non-transactional Session when no + transactional Session can be found for the current thread. + The hibernate session + + If the session couldn't be created. + + + If no thread-bound Session found and allowCreate is false. + + + + + Get a Hibernate Session for the given SessionFactory. + + Is aware of and will return any existing corresponding + Session bound to the current thread, for example whenusing + . Will create a new + Session otherwise, if "allowCreate" is true. +

Throws the orginal HibernateException, in contrast to + . +

+ The session factory. + if set to true [allow create]. + The Hibernate Session + + if the Session couldn't be created + + + If no thread-bound Session found and allowCreate is false. + + + + + Open a new Session from the factory. + + The session factory to create the session with. + Hibernate entity interceptor, or null if none. + the newly opened session + + + + Perform the actual closing of the Hibernate Session + catching and logging any cleanup exceptions thrown. + + The hibernate session to close + + + + Return whether the given Hibernate Session is transactional, that is, + bound to the current thread by Spring's transaction facilities. + + The hibernate session to check + The session factory that the session + was created with, can be null. + + true if the session transactional; otherwise, false. + + + + + Converts a Hibernate ADOException to a Spring DataAccessExcption, extracting the underlying error code from + ADO.NET. Will extract the ADOException Message and SqlString properties and pass them to the translate method + of the provided IAdoExceptionTranslator. + + The IAdoExceptionTranslator, may be a user provided implementation as configured on + HibernateTemplate. + + The ADOException throw + The translated DataAccessException or UncategorizedAdoException in case of an error in translation + itself. + + + + Convert the given HibernateException to an appropriate exception from the + Spring.Dao hierarchy. Note that it is advisable to + handle AdoException specifically by using a AdoExceptionTranslator for the + underlying ADO.NET exception. + + The Hibernate exception that occured. + DataAccessException instance + + + + Close the given Session, created via the given factory, + if it is not managed externally (i.e. not bound to the thread). + + The hibernate session to close + The hibernate SessionFactory that + the session was created with. + + + + Close the given Session or register it for deferred close. + + The session. + The session factory. + + + + Initialize deferred close for the current thread and the given SessionFactory. + Sessions will not be actually closed on close calls then, but rather at a + processDeferredClose call at a finishing point (like request completion). + + The session factory. + + + + Return if deferred close is active for the current thread + and the given SessionFactory. + The session factory. + + true if [is deferred close active] [the specified session factory]; otherwise, false. + + If SessionFactory argument is null. + + + + Process Sessions that have been registered for deferred close + for the given SessionFactory. + + The session factory. + If there is no session factory associated with the thread. + + + + Applies the current transaction timeout, if any, to the given + criteria object + + The Hibernate Criteria object. + Hibernate SessionFactory that the Criteria was created for + (can be null). + If criteria argument is null. + + + + Applies the current transaction timeout, if any, to the given + Hibenrate query object. + + The Hibernate Query object. + Hibernate SessionFactory that the Query was created for + (can be null). + If query argument is null. + + + + Gets the Spring IDbProvider given the ISessionFactory. + + The matching is performed by comparing the assembly qualified + name string of the hibernate Driver.ConnectionType to those in + the DbProviderFactory definitions. No connections are created + in performing this comparison. + The session factory. + The corresponding IDbProvider, null if no mapping was found. + If DbProviderFactory's ApplicaitonContext is not + an instance of IConfigurableApplicaitonContext. + + + + Create a IAdoExceptionTranslator from the given SessionFactory. + + If a corresponding IDbProvider is found, a ErrorcodeExceptionTranslator + for the IDbProvider is created. Otherwise, a FallbackException is created. + The session factory to create the translator for + An IAdoExceptionTranslator + + + + Implementation of NHibernates 1.2's ICurrentSessionContext interface + that delegates to Spring's SessionFactoryUtils for providing a + Spirng-managed current Session. + + Used by Spring's LocalSessionFactoryBean if told to expose + a transaction-aware SessionFactory. +

This ICurrentSessionContext implementation can also be specified in + custom ISessionFactory setup through the + "hibernate.current_session_context_class" property, with the fully + qualified name of this class as value.

 + Juergen Hoeller + Mark Pollack (.NET) + + + + + Initializes a new instance of the class + + The NHibernate session factory. + + + + Retrieve the Spring-managed Session for the current thread. + + Current session associated with the thread + On errors retrieving thread bound session. + + + + NHibnerations actions taken during the transaction lifecycle. + + Mark Pollack (.NET) + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Suspend this synchronization. + + +

+ Unbind Hibernate resources (SessionHolder) from + + if managing any. +

+ + + + + Resume this synchronization. + + +

+ Rebind Hibernate resources from + + if managing any. +

+ + + + + Invoked before transaction commit (before + ) + + + If the transaction is defined as a read-only transaction. + + +

+ Can flush transactional sessions to the database. +

+

+ Note that exceptions will get propagated to the commit caller and + cause a rollback of the transaction. +

+ + + + + Invoked before transaction commit (before + ) + Can e.g. flush transactional O/R Mapping sessions to the database + + + + This callback does not mean that the transaction will actually be + commited. A rollback decision can still occur after this method + has been called. This callback is rather meant to perform work + that's only relevant if a commit still has a chance + to happen, such as flushing SQL statements to the database. + + + Note that exceptions will get propagated to the commit caller and cause a + rollback of the transaction. + + (note: do not throw TransactionException subclasses here!) + + + + + + Invoked after transaction commit/rollback. + + + Status according to + + + Can e.g. perform resource cleanup, in this case after transaction completion. +

+ Note that exceptions will get propagated to the commit or rollback + caller, although they will not influence the outcome of the transaction. +

+ + + + + Return the order value of this object, where a higher value means greater in + terms of sorting. + + +

+ Normally starting with 0 or 1, with indicating + greatest. Same order values will result in arbitrary positions for the affected + objects. +

+

+ Higher value can be interpreted as lower priority, consequently the first object + has highest priority. +

+ + The order value. + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate21.dll b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate21.dll new file mode 100644 index 00000000..a8bebbbc Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate21.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate21.pdb b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate21.pdb new file mode 100644 index 00000000..995ad94c Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate21.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate21.xml b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate21.xml new file mode 100644 index 00000000..fab25108 --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate21.xml @@ -0,0 +1,6711 @@ + + + + Spring.Data.NHibernate21 + + + + + The Spring for .NET-backed ByteCodeprovider for NHibernate + + Fabio Maulo + + + + Creates a new bytecode Provider instance using the specified object factory + + + + + + Retrieve the delegate for this provider + capable of generating reflection optimization components. + + The class to be reflected upon.All property getters to be accessed via reflection.All property setters to be accessed via reflection. + The reflection optimization delegate. + + + + The specific factory for this provider capable of + generating run-time proxies for lazy-loading purposes. + + + + + NHibernate's object instaciator. + + + For entities and its implementations. + + + + + Instanciator of NHibernate's collections default types. + + + + + + + Fabio Maulo + + + + + + + + + + + + + + + Implement this method to perform extra treatments before and after + the call to the supplied . + + +

+ Polite implementations would certainly like to invoke + . +

+ + + The method invocation that is being intercepted. + + + The result of the call to the + method of + the supplied ; this return value may + well have been intercepted by the interceptor. + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + + + Fabio Maulo + + + + + + + + + Creates an instance of the specified type. + + The type of object to create. + A reference to the created object. + + + + Creates an instance of the specified type. + + The type of object to create.true if a public or nonpublic default constructor can match; false if only a public default constructor can match. + A reference to the created object + + + + Creates an instance of the specified type using the constructor that best matches the specified parameters. + + The type of object to create.An array of constructor arguments. + A reference to the created object. + + + + A Spring for .NET backed implementation for creating + NHibernate proxies. + + + Erich Eichinger + + + + Creates a new proxy. + + The id value for the proxy to be generated. + The session to which the generated proxy will be associated. + The generated proxy. + Indicates problems generating requested proxy. + + + + Creates a Spring for .NET backed instance. + + Erich Eichinger + + + + Build a proxy factory specifically for handling runtime lazy loading. + + The lazy-load proxy factory. + + + + + + + + + + + + + + + + + + Fabio Maulo + + + + + + + + + + + + Perform instantiation of an instance of the underlying class. + + The new instance. + + + + + + + + + + Delegates to an implementation of ISessionFactory that can select among multiple instances based on + thread local storage. + + + + + An IFactoryObject that creates a local Hibernate SessionFactory instance. + Behaves like a SessionFactory instance when used as bean reference, + e.g. for HibernateTemplate's "SessionFactory" property. + + + The typical usage will be to register this as singleton factory + in an application context and give objects references to application services + that need it. + + Hibernate configuration settings can be set using the IDictionary property 'HibernateProperties'. + + + This class implements the interface, + as autodetected by Spring's + for AOP-based translation of PersistenceExceptionTranslationPostProcessor. + Hence, the presence of e.g. LocalSessionFactoryBean automatically enables + a PersistenceExceptionTranslationPostProcessor to translate Hibernate exceptions. + + + Mark Pollack (.NET) + + + + The shared instance for this class (and derived classes). + + + + + Initializes a new instance of the class. + + + + + Return the singleon session factory. + + The singleon session factory. + + + + Initialize the SessionFactory for the given or the + default location. + + + + + Close the SessionFactory on application context shutdown. + + + + + Subclasses can override this method to perform custom initialization + of the Configuration instance used for ISessionFactory creation. + + + The properties of this LocalSessionFactoryObject will be applied to + the Configuration object that gets returned here. +

The default implementation creates a new Configuration instance. + A custom implementation could prepare the instance in a specific way, + or use a custom Configuration subclass. +

+ + The configuration instance. + + + + To be implemented by subclasses that want to to register further mappings + on the Configuration object after this FactoryObject registered its specified + mappings. + + + Invoked before the BuildMappings call, + so that it can still extend and modify the mapping information. + + the current Configuration object + + + + To be implemented by subclasses that want to to perform custom + post-processing of the Configuration object after this FactoryObject + performed its default initialization. + + The current configuration object. + + + + Executes schema update if requested. + + + + + Execute schema drop script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaExport class, to be invoked on application setup. + + + Fetch the LocalSessionFactoryBean itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfb = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute schema creation script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaExport class, to be invoked on application setup. + + + Fetch the LocalSessionFactoryObject itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfo = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute schema update script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaUpdate class, for automatically executing schema update scripts + on application startup. Can also be invoked manually. + + + Fetch the LocalSessionFactoryObject itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfo = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute the given schema script on the given ADO.NET Connection. + + + Note that the default implementation will log unsuccessful statements + and continue to execute. Override the ExecuteSchemaStatement + method to treat failures differently. + + The connection to use. + The SQL statement to execute. + + + + Execute the given schema SQL on the given ADO.NET command. + + + Note that the default implementation will log unsuccessful statements + and continue to execute. Override this method to treat failures differently. + + + + + + + Subclasses can override this method to perform custom initialization + of the SessionFactory instance, creating it via the given Configuration + object that got prepared by this LocalSessionFactoryObject. + + +

The default implementation invokes Configuration's BuildSessionFactory. + A custom implementation could prepare the instance in a specific way, + or use a custom ISessionFactory subclass. +

+ + The ISessionFactory instance. + + + + Implementation of the PersistenceExceptionTranslator interface, + as autodetected by Spring's PersistenceExceptionTranslationPostProcessor. + Converts the exception if it is a HibernateException; + else returns null to indicate an unknown exception. + translate the given exception thrown by a persistence framework to a + corresponding exception from Spring's generic DataAccessException hierarchy, + if possible. + + The exception thrown. + + the corresponding DataAccessException (or null if the + exception could not be translated. + + + + + + Convert the given HibernateException to an appropriate exception from the + Spring's DAO Exception hierarchy. + Will automatically apply a specified IAdoExceptionTranslator to a + Hibernate ADOException, else rely on Hibernate's default translation. + + The Hibernate exception that occured. + A corresponding DataAccessException + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + ADOException that occured, wrapping underlying ADO.NET exception. + + the corresponding DataAccessException instance + + + + + Setting the Application Context determines were resources are loaded from + + + + + Gets or sets the to use for loading mapping assemblies etc. + + + + + Sets the assemblies to load that contain mapping files. + + The mapping assemblies. + + + + Sets the hibernate configuration files to load, i.e. hibernate.cfg.xml. + + + + + Sets the locations of Spring IResources that contain mapping + files. + + The location of mapping resources. + + + + Return the Configuration object used to build the SessionFactory. + Allows access to configuration metadata stored there (rarely needed). + + The hibernate configuration. + + + + Set NHibernate configuration properties, like "hibernate.dialect". + + The hibernate properties. + +

Can be used to override values in a NHibernate XML config file, + or to specify all necessary properties locally. +

+

Note: Do not specify a transaction provider here when using + Spring-driven transactions. It is also advisable to omit connection + provider settings and use a Spring-set IDbProvider instead. +

+ + + + + Get or set the DataSource to be used by the SessionFactory. + + The db provider. + + If set, this will override corresponding settings in Hibernate properties. + Note: If this is set, the Hibernate settings should not define + a connection string + (hibernate.connection.connection_string) to avoid meaningless double configuration. + + + + + + Gets or sets a value indicating whether to expose a transaction aware session factory. + + + true if want to expose transaction aware session factory; otherwise, false. + + + + + Set a NHibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + Will get applied to any new Session created by this factory. +

Such an interceptor can either be set at the SessionFactory level, i.e. on + LocalSessionFactoryObject, or at the Session level, i.e. on HibernateTemplate, + HibernateInterceptor, and HibernateTransactionManager. It's preferable to set + it on LocalSessionFactoryObject or HibernateTransactionManager to avoid repeated + configuration and guarantee consistent behavior in transactions.

+ + + + + + + Set a Hibernate NamingStrategy for the SessionFactory, determining the + physical column and table names given the info in the mapping document. + + + + + Specify the Hibernate type definitions to register with the SessionFactory, + as Spring IObjectDefinition instances. This is an alternative to specifying + <typedef> elements in Hibernate mapping files. +

Unfortunately, Hibernate itself does not define a complete object that + represents a type definition, hence the need for Spring's TypeDefinitionBean.

+ @see TypeDefinitionBean + @see org.hibernate.cfg.Mappings#addTypeDef(String, String, java.util.Properties) + + + + + Specify the NHibernate FilterDefinitions to register with the SessionFactory. + This is an alternative to specifying <filter-def> elements in + Hibernate mapping files. + + + Typically, the passed-in FilterDefinition objects will have been defined + as Spring FilterDefinitionFactoryBeans, probably as inner beans within the + LocalSessionFactoryObject definition. + + + + + + Specify the cache strategies for entities (persistent classes or named entities). + This configuration setting corresponds to the <class-cache> entry + in the "hibernate.cfg.xml" configuration format. +

For example: + 

+            <property name="entityCacheStrategies">
+              <props>
+                <prop key="MyCompany.Customer">read-write</prop>
+                <prop key="MyCompany.Product">read-only,myRegion</prop>
+              </props>
+            </property>
+

+ + + + + Specify the cache strategies for persistent collections (with specific roles). + This configuration setting corresponds to the <collection-cache> entry + in the "hibernate.cfg.xml" configuration format. +

For example: + 

+            <property name="CollectionCacheStrategies">
+              <props>
+                <prop key="MyCompany.Order.Items">read-write</prop>
+                <prop key="MyCompany.Product.Categories">read-only,myRegion</prop>
+              </props>
+            </property>
+

+ + + + + Specify the NHibernate event listeners to register, with listener types + as keys and listener objects as values. +

+ Instead of a single listener object, you can also pass in a list + or set of listeners objects as value. +

+ + listener objects as values + + See the NHibernate documentation for further details on listener types + and associated listener interfaces. + + + + + Set whether to execute a schema update after SessionFactory initialization. +

+ For details on how to make schema update scripts work, see the NHibernate + documentation, as this class leverages the same schema update script support + in as NHibernate's own SchemaUpdate tool. +

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Sets custom byte code provider implementation to be used. This corresponds to setting + the property before NHibernate session factory + configuration. + + + + + Return the type or subclass. + + The type created by this factory + + + + Returns true + + true + + + + Subclasses can override this method to perform custom initialization + of the SessionFactory instance, creating it via the given Configuration + object that got prepared by this LocalSessionFactoryObject. + + +

The default implementation invokes Configuration's BuildSessionFactory. + A custom implementation could prepare the instance in a specific way, + or use a custom ISessionFactory subclass. +

+ + The ISessionFactory instance. + + + + PostProcessConfiguration + + + + + + DelegatingSessionFactory class + + + + + PlatformTransactionManager implementation for a single Hibernate SessionFactory. + Binds a Hibernate Session from the specified factory to the thread, potentially + allowing for one thread Session per factory + + + SessionFactoryUtils and HibernateTemplate are aware of thread-bound Sessions and participate in such + transactions automatically. Using either of those is required for Hibernate + access code that needs to support this transaction handling mechanism. + + Supports custom isolation levels at the start of the transaction + , and timeouts that get applied as appropriate + Hibernate query timeouts. To support the latter, application code must either use + HibernateTemplate (which by default applies the timeouts) or call + SessionFactoryUtils.applyTransactionTimeout for each created + Hibernate Query object. + + Note that you can specify a Spring IDbProvider instance which if shared with + a corresponding instance of AdoTemplate will allow for mixing ADO.NET/NHibernate + operations within a single transaction. + + Mark Pollack (.NET) + + + + Just needed for entityInterceptorBeanName. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The session factory. + + + + Return the current transaction object. + + The current transaction object. + + If transaction support is not available. + + + In the case of lookup or system errors. + + + + + Check if the given transaction object indicates an existing, + i.e. already begun, transaction. + + + Transaction object returned by + . + + True if there is an existing transaction. + + In the case of system errors. + + + + + Begin a new transaction with the given transaction definition. + + + Transaction object returned by + . + + + instance, describing + propagation behavior, isolation level, timeout etc. + + + Does not have to care about applying the propagation behavior, + as this has already been handled by this abstract manager. + + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + + Transaction object returned by + . + + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + Transaction synchronization will already have been suspended. + + + If suspending is not supported by the transaction manager implementation. + + + in case of system errors. + + + + + Resume the resources of the current transaction. + + + Transaction object returned by + . + + + The object that holds suspended resources as returned by + . + + + Transaction synchronization will be resumed afterwards. + + + If suspending is not supported by the transaction manager implementation. + + + In the case of system errors. + + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + +

+ An implementation does not need to check the rollback-only flag. +

+ + + In the case of system errors. + + + + + Does the tx scope commit. + + The status. + + + + Perform an actual rollback on the given transaction. + + The status representation of the transaction. + + An implementation does not need to check the new transaction flag. + + + In the case of system errors. + + + + + Does the tx scope rollback. + + The status. + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + The status representation of the transaction. + + In the case of system errors. + + + + + Does the tx scope set rollback only. + + The status. + + + + Gets the ADO.NET IDbTransaction object from the NHibernate ITransaction object. + + The hibernate transaction. + The ADO.NET transaction. Null if could not get the transaction. Warning + messages will be logged in that case. + + + + Convert the given HibernateException to an appropriate exception from + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The HibernateException that occured. + The corresponding DataAccessException instance + + + + Convert the given ADOException to an appropriate exception from the + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The ADOException that occured, wrapping the underlying + ADO.NET thrown exception. + The translator to convert hibernate ADOExceptions. + + The corresponding DataAccessException instance + + + + + Cleanup resources after transaction completion. + + Transaction object returned by + . + + + This implemenation unbinds the SessionFactory and + DbProvider from thread local storage and closes the + ISession. + +

+ Called after + and + + execution on any outcome. +

+

+ Should not throw any exceptions but just issue warnings on errors. +

+ + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Gets or sets the db provider. + + The db provider. + + + + Gets or sets a Hibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + When getting, return the current Hibernate entity interceptor, or null if none. + + The entity interceptor. + + Resolves an entity interceptor object name via the object factory, + if necessary. + Will get applied to any new Session created by this transaction manager. + Such an interceptor can either be set at the SessionFactory level, + i.e. on LocalSessionFactoryObject, or at the Session level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. + + If object factory is null and need to get entity interceptor via object name. + + + + Sets the object name of a Hibernate entity interceptor that + allows to inspect and change property values before writing to and reading from the database. + + The name of the entity interceptor object. + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + + + + Gets or sets the ADO.NET exception translator for this transaction manager. + + + Applied to ADO.NET Exceptions (wrapped by Hibernate's ADOException) + + The ADO exception translator. + + + + Gets the default IAdoException translator, lazily creating it if nece + + The default IAdoException translator. + + + + Gets or sets the SessionFactory that this instance should manage transactions for. + + The session factory. + + + + Gets the resource factory that this transaction manager operates on, + For the HibenratePlatformTransactionManager this the SessionFactory + + The SessionFactory. + + + + Set whether to autodetect a ADO.NET connection used by the Hibernate SessionFactory, + if set via LocalSessionFactoryObject's DbProvider. Default is "true". + + + true if [autodetect data source]; otherwise, false. + + +

Can be turned off to deliberately ignore an available IDbProvider, + to not expose Hibernate transactions as ADO.NET transactions for that IDbProvider. +

+ + + + + The object factory just needs to be known for resolving entity interceptor + It does not need to be set for any other mode of operation. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + + + + Return whether the transaction is internally marked as rollback-only. + + + True of the transaction is marked as rollback-only. + + + + SimpleDelegatingSessionFactory class + + + + + Connection string config element name + + + + + public Constructor + + + + + + TargetSessionFactory + + + + + Holds the references and configuration settings for a instance. + References are resolved by looking up the given object names in the root obtained by . + + + + + Holds the references and configuration settings for a instance. + + + + + Default value for property. + + + + + Default value for property. + + + + + Initialize a new instance of with default values. + + + Calling this constructor from your derived class leaves and + uninitialized. See and for more. + + + + + Initialize a new instance of with the given sessionFactory + and default values for all other settings. + + + The instance to be used for obtaining instances. + + + Calling this constructor marks all properties initialized. + + + + + Initialize a new instance of with the given values and references. + + + The instance to be used for obtaining instances. + + + Specify the to be set on each session provided by the instance. + + + Set whether to use a single session for each request. See property for details. + + + Specify the flushmode to be applied on each session provided by the instance. + + + Calling this constructor marks all properties initialized. + + + + + Override this method to resolve an instance according to your chosen strategy. + + + + + Override this method to resolve an instance according to your chosen strategy. + + + + + Gets the configured instance to be used. + + + If the entity interceptor is not set by the constructor, this property calls + to obtain an instance. This allows derived classes to + override the behaviour of how to obtain the concrete instance. + + + + + Gets the configured instance to be used. + + + If this property is requested for the first time, is called. + This allows derived classes to override the behaviour of how to obtain the concrete instance. + + If the instance cannot be resolved. + + + + Set whether to use a single session for each request. Default is "true". + If set to false, each data access operation or transaction will use + its own session (like without Open Session in View). Each of those + sessions will be registered for deferred close, though, actually + processed at request completion. + + + + + Gets or Sets the flushmode to be applied on each newly created session. + + + This property defaults to to ensure that modifying objects outside the boundaries + of a transaction will not be persisted. It is recommended to not change this value but wrap any modifying operation + within a transaction. + + + + + The default session factory name to use when retrieving the Hibernate session factory from + the root context. + + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + The configuration section to read setting variables from. + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + The variable source to obtain settings from. + + + + Resolve the entityInterceptor by looking up + in the root application context. + + The resolved instance or + + + + Resolve the by looking up + in the root application context. + + The resolved instance or + + + + Convenient super class for Hibernate data access objects. + + + Requires a SessionFactory to be set, providing a HibernateTemplate + based on it to subclasses. Can alternatively be initialized directly with + a HibernateTemplate, to reuse the latter's settings such as the SessionFactory, + exception translator, flush mode, etc + + This base call is mainly intended for HibernateTemplate usage. + + This class will create its own HibernateTemplate if only a SessionFactory + is passed in. The "allowCreate" flag on that HibernateTemplate will be "true" + by default. A custom HibernateTemplate instance can be used through overriding + CreateHibernateTemplate. + + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Create a HibernateTemplate for the given ISessionFactory. + + + Only invoked if populating the DAO with a ISessionFactory reference! +

Can be overridden in subclasses to provide a HibernateTemplate instance + with different configuration, or a custom HibernateTemplate subclass. +

+ + + + + Check if the hibernate template property has been set. + + + + + Get a Hibernate Session, either from the current transaction or + a new one. The latter is only allowed if "allowCreate" is true. + + Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Either rely on a thread-bound + Session (via HibernateInterceptor), or use it in combination with + ReleaseSession. + + In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. + + + if a non-transactional Session should be created when no + transactional Session can be found for the current thread + + Hibernate session. + + If the Session couldn't be created + + + if no thread-bound Session found and allowCreate false + + + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Close the given Hibernate Session, created via this DAO's SessionFactory, + if it isn't bound to the thread. + + + Typically used in plain Hibernate code, in combination with the + Session property and ConvertHibernateAccessException. + + The session to close. + + + + Gets or sets the hibernate template. + + Set the HibernateTemplate for this DAO explicitly, + as an alternative to specifying a SessionFactory. + + The hibernate template. + + + + Gets or sets the session factory to be used by this DAO. + Will automatically create a HibernateTemplate for the given SessionFactory. + + The session factory. + + + + Get a Hibernate Session, either from the current transaction or a new one. + The latter is only allowed if the "allowCreate" setting of this object's + HibernateTemplate is true. + + +

Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Use it in combination with + ReleaseSession. +

+

In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. +

+ + The Hibernate session. + + + + Provide support for the open session in view pattern for lazily loaded hibernate objects + used in ASP.NET pages. + + jjx: http://forum.springframework.net/member.php?u=29 + Mark Pollack (.NET) + Erich Eichinger + Harald Radi + + + + Implementation of SessionScope that associates a single session within the using scope. + + + It is recommended to be used in the following type of scenario: + + using (new SessionScope()) + { + ... do multiple operation, possibly in multiple transactions. + } + + At the end of "using", the session is automatically closed. All transactions within the scope use the same session, + if you are using Spring's HibernateTemplate or using Spring's implementation of NHibernate 1.2's + ICurrentSessionContext interface. + + + It is assumed that the session factory object name is called "SessionFactory". In case that you named the object + in different way you can specify your can specify it in the application settings using the key + Spring.Data.NHibernate.Support.SessionScope.SessionFactoryObjectName. Values for EntityInterceptorObjectName + and SingleSessionMode can be specified similarly. + + + Note: + The session is managed on a per thread basis on the thread that opens the scope instance. This means that you must + never pass a reference to a instance over to another thread! + + + Robert M. (.NET) + Harald Radi (.NET) + + + + The logging instance. + + + + + Initializes a new instance of the class in single session mode, + associating a session with the thread. The session is opened lazily on demand. + + + + + Initializes a new instance of the class. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The name of the configuration section to read configuration settings from. + See for more info. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The name of the configuration section to read configuration settings from. + See for more info. + + The type, who's full name is used for prefixing appSetting keys + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The instance to be used for obtaining instances. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The instance to be used for obtaining instances. + + + Specify the to be set on each session provided by this instance. + + + Set whether to use a single session for each request. See property for details. + + + Specify the flushmode to be applied on each session provided by this instance. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + An instance holding the scope configuration + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Sets a flag, whether this scope is in "open" state on the current logical thread. + + + + + Gets/Sets a flag, whether this scope manages it's own session for the current logical thread or not. + + false if session is managed by this module. false otherwise + + + + Call Close(), + + + + + Opens a new session or participates in an existing session and + registers with spring's . + + + + + Close the current view's session and unregisters + from spring's . + + + + + Set whether to use a single session for each request. Default is "true". + If set to false, each data access operation or transaction will use + its own session (like without Open Session in View). Each of those + sessions will be registered for deferred close, though, actually + processed at request completion. + + + + + Gets the flushmode to be applied on each newly created session. + + + This property defaults to to ensure that modifying objects outside the boundaries + of a transaction will not be persisted. It is recommended to not change this value but wrap any modifying operation + within a transaction. + + + + + Get or set the configured SessionFactory + + + + + Get or set the configured EntityInterceptor + + + + + Gets a flag, whether this scope is in "open" state on the current logical thread. + + + + + Gets a flag, whether this scope manages it's own session for the current logical thread or not. + + + + + This sessionHolder creates a default session only if it is needed. + + + Although a NHibernateSession deferes creation of db-connections until they are really + needed, instantiation a session is imho still more expensive than this LazySessionHolder. (EE) + + + + + Session holder, wrapping a NHibernate ISession and a NHibernate Transaction. + HibernateTransactionManager binds instances of this class + to the thread, for a given ISessionFactory. + + + Note: This is an SPI class, not intended to be used by applications. + + Mark Pollack (.NET) + + + + May be used by derived classes to create an empty SessionHolder. + + + When using this ctor in your derived class, you MUST override ! + + + + + Initializes a new instance of the class. + + The session. + + + + Initializes a new instance of the class. + + The key to store the session under. + The hibernate session. + + + + May be overridden in a derived class to e.g. lazily create a session + + + + + Gets the session given key identifier + + The key. + A hibernate session + + + + Gets the session given the key and removes the session from + the dictionary storage. + + The key. + A hibernate session + + + + Adds the session to the dictionary storage using the default key. + + The hibernate session. + + + + Adds the session to the dictionary storage using the supplied key. + + The key. + The hibernate session. + + + + Removes the session from the dictionary storage for the given key. + + The key. + The session that was previously contained in the + dictionary storage. + + + + Determines whether the holder the specified session. + + The session. + + true if the holder contains the specified session; otherwise, false. + + + + + Clear the transaction state of this resource holder. + + + + + Gets the session using the default key + + The hibernate session. + + + + Gets the first session based on iteration over + the IDictionary storage. + + Any hibernate session. + + + + Gets a value indicating whether dictionary of + hibernate sessions is empty. + + + true if this session holder is empty; otherwise, false. + + + + + Gets a value indicating whether this SessionHolder + does not hold non default session. + + + true if does not hold non default session; otherwise, false. + + + + + Gets or sets the hibernate transaction. + + The transaction. + + + + Gets or sets the ADO.NET Connection used to create the session. + + The ADO.NET connection. + + + + Gets or sets the previous flush mode. + + The previous flush mode. + + + + Gets a value indicating whether the PreviousFlushMode property + was set. + + + true if assigned PreviousFlushMode property; otherwise, false. + + + + + Gets the validated session. + + The validated session. + + + + Initialize a new instance. + + + + + Create a new session on demand + + + + + Ensure session is closed (if any) and remove circular references to avoid memory leaks! + + + + + Initializes a new instance of the class. Creates a SessionScope, + but does not yet associate a session with a thread, that is left to the lifecycle of the request. + + + + + Register context handler and look up SessionFactoryObjectName under the application configuration key, + Spring.Data.NHibernate.Support.OpenSessionInViewModule.SessionFactoryObjectName if not using the default value + (i.e. sessionFactory) and look up the SingleSession setting under the application configuration key, + Spring.Data.NHibernate.Support.OpenSessionInViewModule.SingleSession if not using the default value of true. + + The standard HTTP application context + + + + A do nothing dispose method. + + + + + Hibernate-specific subclass of UncategorizedDataAccessException, + for ADO.NET exceptions that Hibernate rethrew and could not be + mapped into the DAO exception heirarchy. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception from the underlying data access API - ADO.NET + + + + + Creates a new instance of the HibernateSystemException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Hibernate-specific subclass of InvalidDataAccessResourceUsageException, + thrown on invalid HQL query syntax. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Initializes a new instance of the class. + + The ex. + + + + Creates a new instance of the HibernateQueryException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Gets the query string that was invalid. + + The query string that was invalid. + + + + Hibernate-specific subclass of UncategorizedDataAccessException, + for Hibernate system errors that do not match any concrete + Spring.Dao exceptions. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message. + + + + Creates a new instance of the HibernateSystemException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Initializes a new instance of the class. + + The cause. + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Helper class that simplifies NHibernate data access code + + +

Typically used to implement data access or business logic services that + use NHibernate within their implementation but are Hibernate-agnostic in their + interface. The latter or code calling the latter only have to deal with + domain objects.

+ +

The central method is Execute supporting Hibernate access code + implementing the HibernateCallback interface. It provides NHibernate Session + handling such that neither the IHibernateCallback implementation nor the calling + code needs to explicitly care about retrieving/closing NHibernate Sessions, + or handling Session lifecycle exceptions. For typical single step actions, + there are various convenience methods (Find, Load, SaveOrUpdate, Delete). +

+ +

Can be used within a service implementation via direct instantiation + with a ISessionFactory reference, or get prepared in an application context + and given to services as an object reference. Note: The ISessionFactory should + always be configured as an object in the application context, in the first case + given to the service directly, in the second case to the prepared template. +

+ +

This class can be considered as direct alternative to working with the raw + Hibernate Session API (through SessionFactoryUtils.Session). +

+ +

LocalSessionFactoryObject is the preferred way of obtaining a reference + to a specific NHibernate ISessionFactory. +

+ + Mark Pollack (.NET) + + + + Base class for HibernateTemplate defining common + properties like SessionFactory and flushing behavior. + + +

Not intended to be used directly. See HibernateTemplate. +

+ + Mark Pollack (.NET) + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Apply the flush mode that's been specified for this accessor + to the given Session. + + The current Hibernate Session. + if set to true + if executing within an existing transaction. + + the previous flush mode to restore after the operation, + or null if none + + + + + Flush the given Hibernate Session if necessary. + + The current Hibernate Session. + if set to true + if executing within an existing transaction. + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + ADOException that occured, wrapping underlying ADO.NET exception. + + the corresponding DataAccessException instance + + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + + + Note that a direct SQLException can just occur when callback code + performs direct ADO.NET access via ISession.Connection(). + + + The ADO.NET exception. + The corresponding DataAccessException instance + + + + Prepare the given IQuery object, applying cache settings and/or + a transaction timeout. + + The query object to prepare. + + + + Apply the given name parameter to the given Query object. + + The query object. + Name of the parameter + The value of the parameter + The NHibernate type of the parameter (or null if none specified) + + + + Prepare the given Criteria object, applying cache settings and/or + a transaction timeout. + + + Note that for NHibernate 1.2 this only works if the + implementation is of the type CriteriaImpl, which should generally + be the case. The SetFetchSize method is not available on the + ICriteria interface + + This is a no-op for NHibernate 1.0.x since + the SetFetchSize method is not on the ICriteria interface and + the implementation class is has internal access. + + To remove the method completely for Spring's NHibernate 1.0 + support while reusing code for NHibernate 1.2 would not be + possible. So now this ineffectual operation is left in tact for + NHibernate 1.0.2 support. + + The criteria object to prepare + + + + Ensure SessionFactory is not null + + If SessionFactory property is null. + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Set the object factory instance. + + The object factory instance. + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Gets a Session for use by this template. + + The session. + + - Returns a new Session in case of "alwaysUseNewSession" (using the same ADO.NET connection as a transaction Session, if applicable) + - a pre-bound Session in case of "AllowCreate" is set to false (not the default) + - or a pre-bound Session or new Session if no transactional or other pre-bound Session exists. + + + + + Helper class to determine if the FlushMode enumeration + was changed from its default value + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The flush mode. + + + + Gets or sets a value indicating whether the FlushMode + property was set.. + + true if FlushMode was set; otherwise, false. + + + + Gets or sets the FlushMode. + + The FlushMode. + + + + Interface that specifies a basic set of Hibernate operations. + + + Implemented by HibernateTemplate. Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + + Mark Pollack (.NET) + + + + Interface that specifies a set of Hibernate operations that + are common across versions of Hibernate. + + + Base interface for generic and non generic IHibernateOperations interfaces + Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + Mark Pollack (.NET) + + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + In case of Hibernate errors + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + Tthe persistent instance to delete. + The lock mode to obtain. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Delete all given persistent instances. + + The persistent instances to delete. + + This can be combined with any of the find methods to delete by query + in two lines of code, similar to Session's delete by query methods. + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the specified action assuming that the result object is a List. + + + This is a convenience method for executing Hibernate find calls or + queries within an action. + + The calback object that specifies the Hibernate action. + A IList returned by the action, or null + + In case of Hibernate errors + + + + Execute a query for persistent instances. + + a query expressed in Hibernate's query language + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + a query expressed in Hibernate's query language + the value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + a query expressed in Hibernate's query language + the values of the parameters + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + a List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + + a persistent type. + An identifier of the persistent instance. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + A persistent class. + An identifier of the persistent instance. + The lock mode. + the persistent instance, or null if not found + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + Type of the entity. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + Type of the entity. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + Type of the entity. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Save or update all given persistent instances, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instances to save or update + (to be associated with the Hibernate Session)he entities. + In case of Hibernate errors + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The default for creating a new non-transactional + session when no transactional Session can be found for the current thread + is set to true. + The session factory to create sessions. + + + + Initializes a new instance of the class. + + The session factory to create sessions. + if set to true allow creation + of a new non-transactional when no transactional Session can be found + for the current thread. + + + + Delegate function that clears the session. + + The hibernate session. + null + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + + The type. + An identifier of the persistent instance. + The persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The type. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + Type of the entity. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + Type of the entity. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + Type of the entity. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update all given persistent instances, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instances to save or update + (to be associated with the Hibernate Session)he entities. + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + Tthe persistent instance to delete. + The lock mode to obtain. + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + If length for argument values and types are not equal. + + + + Delete all given persistent instances. + + The persistent instances to delete. + + This can be combined with any of the find methods to delete by query + in two lines of code, similar to Session's delete by query methods. + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + + + + Execute the action specified by the given action object within a Session. + + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the specified action assuming that the result object is a List. + + + This is a convenience method for executing Hibernate find calls or + queries within an action. + + The calback object that specifies the Hibernate action. + A IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + + + + Execute a query for persistent instances. + + a query expressed in Hibernate's query language + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + a query expressed in Hibernate's query language + the value of the parameter + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + a query expressed in Hibernate's query language + the values of the parameters + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Create a close-suppressing proxy for the given Hibernate Session. + The proxy also prepares returned Query and Criteria objects. + + The session. + The session proxy. + + + + Check whether write operations are allowed on the given Session. + + + Default implementation throws an InvalidDataAccessApiUsageException + in case of FlushMode.Never. Can be overridden in subclasses. + + The current Hibernate session. + If write operation is attempted in read-only mode + + + + + Compares if the flush mode enumerations, Spring's + TemplateFlushMode and NHibernates FlushMode have equal + settings. + + The template flush mode. + The NHibernate flush mode. + + Returns true if both are Never, Auto, or Commit, false + otherwise. + + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + If object factory is not set and need to retrieve entity interceptor by name. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets whether to check that the Hibernate Session is not in read-only mode + in case of write operations (save/update/delete). + + + true if check that the Hibernate Session is not in read-only mode + in case of write operations; otherwise, false. + + + Default is "true", for fail-fast behavior when attempting write operations + within a read-only transaction. Turn this off to allow save/update/delete + on a Session with flush mode NEVER. + + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Set the object factory instance. + + The object factory instance + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the proxy factory. + + This may be useful to set if you create many instances of + HibernateTemplate and/or HibernateDaoSupport. This allows the same + ProxyFactory implementation to be used thereby limiting the + number of dynamic proxy types created in the temporary assembly, which + are never garbage collected due to .NET runtime semantics. + + The proxy factory. + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Callback interface for NHibernate code. + + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + Mark Pollack (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + A result object, or null if none. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + PlatformTransactionManager implementation for a single Hibernate SessionFactory. + Binds a Hibernate Session from the specified factory to the thread, potentially + allowing for one thread Session per factory + + + SessionFactoryUtils and HibernateTemplate are aware of thread-bound Sessions and participate in such + transactions automatically. Using either of those is required for Hibernate + access code that needs to support this transaction handling mechanism. + + Supports custom isolation levels at the start of the transaction + , and timeouts that get applied as appropriate + Hibernate query timeouts. To support the latter, application code must either use + HibernateTemplate (which by default applies the timeouts) or call + SessionFactoryUtils.applyTransactionTimeout for each created + Hibernate Query object. + + Note that you can specify a Spring IDbProvider instance which if shared with + a corresponding instance of AdoTemplate will allow for mixing ADO.NET/NHibernate + operations within a single transaction. + + Mark Pollack (.NET) + + + + Just needed for entityInterceptorBeanName. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The session factory. + + + + Return the current transaction object. + + The current transaction object. + + If transaction support is not available. + + + In the case of lookup or system errors. + + + + + Check if the given transaction object indicates an existing, + i.e. already begun, transaction. + + + Transaction object returned by + . + + True if there is an existing transaction. + + In the case of system errors. + + + + + Begin a new transaction with the given transaction definition. + + + Transaction object returned by + . + + + instance, describing + propagation behavior, isolation level, timeout etc. + + + Does not have to care about applying the propagation behavior, + as this has already been handled by this abstract manager. + + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + + Transaction object returned by + . + + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + Transaction synchronization will already have been suspended. + + + If suspending is not supported by the transaction manager implementation. + + + in case of system errors. + + + + + Resume the resources of the current transaction. + + + Transaction object returned by + . + + + The object that holds suspended resources as returned by + . + + + Transaction synchronization will be resumed afterwards. + + + If suspending is not supported by the transaction manager implementation. + + + In the case of system errors. + + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + +

+ An implementation does not need to check the rollback-only flag. +

+ + + In the case of system errors. + + + + + Perform an actual rollback on the given transaction. + + The status representation of the transaction. + + An implementation does not need to check the new transaction flag. + + + In the case of system errors. + + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + The status representation of the transaction. + + In the case of system errors. + + + + + Gets the ADO.NET IDbTransaction object from the NHibernate ITransaction object. + + The hibernate transaction. + The ADO.NET transaction. Null if could not get the transaction. Warning + messages will be logged in that case. + + + + Convert the given HibernateException to an appropriate exception from + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The HibernateException that occured. + The corresponding DataAccessException instance + + + + Convert the given ADOException to an appropriate exception from the + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The ADOException that occured, wrapping the underlying + ADO.NET thrown exception. + The translator to convert hibernate ADOExceptions. + + The corresponding DataAccessException instance + + + + + Cleanup resources after transaction completion. + + Transaction object returned by + . + + + This implemenation unbinds the SessionFactory and + DbProvider from thread local storage and closes the + ISession. + +

+ Called after + and + + execution on any outcome. +

+

+ Should not throw any exceptions but just issue warnings on errors. +

+ + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Gets or sets the db provider. + + The db provider. + + + + Gets or sets a Hibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + When getting, return the current Hibernate entity interceptor, or null if none. + + The entity interceptor. + + Resolves an entity interceptor object name via the object factory, + if necessary. + Will get applied to any new Session created by this transaction manager. + Such an interceptor can either be set at the SessionFactory level, + i.e. on LocalSessionFactoryObject, or at the Session level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. + + If object factory is null and need to get entity interceptor via object name. + + + + Sets the object name of a Hibernate entity interceptor that + allows to inspect and change property values before writing to and reading from the database. + + The name of the entity interceptor object. + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + + + + Gets or sets the ADO.NET exception translator for this transaction manager. + + + Applied to ADO.NET Exceptions (wrapped by Hibernate's ADOException) + + The ADO exception translator. + + + + Gets the default IAdoException translator, lazily creating it if nece + + The default IAdoException translator. + + + + Gets or sets the SessionFactory that this instance should manage transactions for. + + The session factory. + + + + Gets the resource factory that this transaction manager operates on, + For the HibenratePlatformTransactionManager this the SessionFactory + + The SessionFactory. + + + + Set whether to autodetect a ADO.NET connection used by the Hibernate SessionFactory, + if set via LocalSessionFactoryObject's DbProvider. Default is "true". + + + true if [autodetect data source]; otherwise, false. + + +

Can be turned off to deliberately ignore an available IDbProvider, + to not expose Hibernate transactions as ADO.NET transactions for that IDbProvider. +

+ + + + + The object factory just needs to be known for resolving entity interceptor + It does not need to be set for any other mode of operation. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + + + + Return whether the transaction is internally marked as rollback-only. + + + True of the transaction is marked as rollback-only. + + + + Enumeration for the various Hibernate flush modes. + + Mark Pollack (.NET) + + + Never flush is a good strategy for read-only units of work. + + + Hibernate will not track and look for changes in this case, + avoiding any overhead of modification detection. +

In case of an existing ISession, TemplateFlushMode.Never will turn + the hibenrate flush mode + to FlushMode.Never for the scope of the current operation, resetting the previous + flush mode afterwards. +

+ + + + Automatic flushing is the default mode for a Hibernate Session. + + + A session will get flushed on transaction commit, and on certain find + operations that might involve already modified instances, but not + after each unit of work like with eager flushing. +

In case of an existing Session, TemplateFlushMode.Auto + will participate in the existing flush mode, not modifying + it for the current operation. + This in particular means that this setting will not modify an existing + hibernate flush mode FlushMode.Never, in contrast to TemplateFlushMode.Eager. +

+ + + + + Eager flushing leads to immediate synchronization with the database, + even if in a transaction. + + + This causes inconsistencies to show up and throw + a respective exception immediately, and ADO access code that participates + in the same transaction will see the changes as the database is already + aware of them then. But the drawbacks are: +
    +
  • additional communication roundtrips with the database, instead of a + single batch at transaction commit;
    • +
  • the fact that an actual database rollback is needed if the Hibernate + transaction rolls back (due to already submitted SQL statements).
    • +
+

In case of an existing Session, TemplateFlushMode.Eager + will turn the NHibernate flush mode + to FlushMode.Auto for the scope of the current operation and issue a flush at the + end, resetting the previous flush mode afterwards. +

+ + + + + Flushing at commit only is intended for units of work where no + intermediate flushing is desired, not even for find operations + that might involve already modified instances. + + +

In case of an existing Session, TemplateFlushMode.Commit + will turn the NHibernate flush mode + to FlushMode.Commit for the scope of the current operation, resetting the previous + flush mode afterwards. The only exception is an existing flush mode + FlushMode.Never, which will not be modified through this setting. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning an IList of result objects created within the callback. + Note that there's special support for single step actions: + see HibernateTemplate.find etc. +

+ + The type of result object + Sree Nivask (.NET) + + + + Convenient super class for Hibernate data access objects. + + + Requires a SessionFactory to be set, providing a HibernateTemplate + based on it to subclasses. Can alternatively be initialized directly with + a HibernateTemplate, to reuse the latter's settings such as the SessionFactory, + exception translator, flush mode, etc + + This base call is mainly intended for HibernateTemplate usage. + + This class will create its own HibernateTemplate if only a SessionFactory + is passed in. The "allowCreate" flag on that HibernateTemplate will be "true" + by default. A custom HibernateTemplate instance can be used through overriding + CreateHibernateTemplate. + + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Create a HibernateTemplate for the given ISessionFactory. + + + Only invoked if populating the DAO with a ISessionFactory reference! +

Can be overridden in subclasses to provide a HibernateTemplate instance + with different configuration, or a custom HibernateTemplate subclass. +

+ + The new HibernateTemplate instance + + + + Check if the hibernate template property has been set. + + If HibernateTemplate property is null. + + + + Get a Hibernate Session, either from the current transaction or + a new one. The latter is only allowed if "allowCreate" is true. + + Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Either rely on a thread-bound + Session (via HibernateInterceptor), or use it in combination with + ReleaseSession. + + In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. + + + if a non-transactional Session should be created when no + transactional Session can be found for the current thread + + Hibernate session. + + If the Session couldn't be created + + + if no thread-bound Session found and allowCreate false + + + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Close the given Hibernate Session, created via this DAO's SessionFactory, + if it isn't bound to the thread. + + + Typically used in plain Hibernate code, in combination with the + Session property and ConvertHibernateAccessException. + + The session to close. + + + + Gets or sets the hibernate template. + + Set the HibernateTemplate for this DAO explicitly, + as an alternative to specifying a SessionFactory. + + The hibernate template. + + + + Gets or sets the session factory to be used by this DAO. + Will automatically create a HibernateTemplate for the given SessionFactory. + + The session factory. + + + + Get a Hibernate Session, either from the current transaction or a new one. + The latter is only allowed if the "allowCreate" setting of this object's + HibernateTemplate is true. + + +

Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Use it in combination with + ReleaseSession. +

+

In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. +

+ + The Hibernate session. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning the result object created within the callback. + Note that there's special support for single step actions: + see HibernateTemplate.find etc. +

+ + The type of result object + Sree Nivask (.NET) + + + + Generic version of the Helper class that simplifies NHibernate data access code + + +

Typically used to implement data access or business logic services that + use NHibernate within their implementation but are Hibernate-agnostic in their + interface. The latter or code calling the latter only have to deal with + domain objects.

+ +

The central method is Execute() supporting Hibernate access code which + implements the HibernateCallback interface. It provides NHibernate Session + handling such that neither the IHibernateCallback implementation nor the calling + code needs to explicitly care about retrieving/closing NHibernate Sessions, + or handling Session lifecycle exceptions. For typical single step actions, + there are various convenience methods (Find, Load, SaveOrUpdate, Delete). +

+ +

Can be used within a service implementation via direct instantiation + with a ISessionFactory reference, or get prepared in an application context + and given to services as an object reference. Note: The ISessionFactory should + always be configured as an object in the application context, in the first case + given to the service directly, in the second case to the prepared template. +

+ +

This class can be considered as a direct alternative to working with the raw + Hibernate Session API (through SessionFactoryUtils.Session). +

+ +

LocalSessionFactoryObject is the preferred way of obtaining a reference + to a specific NHibernate ISessionFactory. +

+ + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Interface that specifies a basic set of Hibernate operations. + + + Implemented by HibernateTemplate. Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Return the persistent instance of the given entity type + with the given identifier, or if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The id of the object to get. + the persistent instance, or if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + The object type to load. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + The object type to load. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + The object type to load. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances. + + The object type to find. + a query expressed in Hibernate's query language + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the value of the parameter + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + The object type to find. + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the values of the parameters + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lenths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type retrieved. + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type retrieved. + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type to find. + The delegate callback object that specifies the Hibernate action. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type to find. + The FindHibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type to find. + The callback object that specifies the Hibernate action. + + A generic IList returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + + + + Execute the action specified by the given action object within a Session assuming that an IList is returned. + + The object type to find. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + an IList returned by the action, or null + + In case of Hibernate errors + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + Allows creation of a new non-transactional session when no + transactional Session can be found for the current thread + The session factory to create sessions. + + + + Initializes a new instance of the class. + + The session factory to create sessions. + if set to true allow creation + of a new non-transactional session when no transactional Session can be found + for the current thread. + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + Tthe persistent instance to delete. + The lock mode to obtain. + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The id of the object to get. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + The object type to load. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + The object type to load. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + The object type to load. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances. + + The object type to find. + a query expressed in Hibernate's query language + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the value of the parameter + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + The object type to find. + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the values of the parameters + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type retrieved. + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type retrieved. + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session assuming that an IList is returned. + + The object type to find. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + an IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type to find. + The delegate callback object that specifies the Hibernate action. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type to find. + The FindHibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type to find. + The callback object that specifies the Hibernate action. + + A generic IList returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Set the object factory instance. + + The object factory instance + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Gets the classic hibernate template for access to non-generic methods. + + The classic hibernate template. + + + + Gets or sets the proxy factory. + + This may be useful to set if you create many instances of + HibernateTemplate and/or HibernateDaoSupport. This allows the same + ProxyFactory implementation to be used thereby limiting the + number of dynamic proxy types created in the temporary assembly, which + are never garbage collected due to .NET runtime semantics. + + The proxy factory. + + + + Callback interface (Generic version) for NHibernate code. + + The type of result object + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + + Sree Nivask (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + A result object. + The active Hibernate session + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Callback interface (Generic version) for NHibernate code that + returns a List of objects. + + The type of result object + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + Collection result object. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Helper class featuring methods for Hibernate Session handling, + allowing for reuse of Hibernate Session instances within transactions. + Also provides support for exception translation. + + Mark Pollack (.NET) + + + + The instance for this class. + + + + + The ordering value for synchronizaiton this session resources. + Set to be lower than ADO.NET synchronization. + + + + + Initializes a new instance of the class. + + + + + Get a new Hibernate Session from the given SessionFactory. + Will return a new Session even if there already is a pre-bound + Session for the given SessionFactory. + + + Within a transaction, this method will create a new Session + that shares the transaction's ADO.NET Connection. More specifically, + it will use the same ADO.NET Connection as the pre-bound Hibernate Session. + + The session factory to create the session with. + The Hibernate entity interceptor, or null if none. + The new session. + If could not open Hibernate session + + + + Get a Hibernate Session for the given SessionFactory. Is aware of and will + return any existing corresponding Session bound to the current thread, for + example when using HibernateTransactionManager. Will always create a new + Session otherwise. + + + Supports setting a Session-level Hibernate entity interceptor that allows + to inspect and change property values before writing to and reading from the + database. Such an interceptor can also be set at the SessionFactory level + (i.e. on LocalSessionFactoryObject), on HibernateTransactionManager, or on + HibernateInterceptor/HibernateTemplate. + + The session factory to create the + session with. + Hibernate entity interceptor, or null if none. + AdoExceptionTranslator to use for flushing the + Session on transaction synchronization (can be null; only used when actually + registering a transaction synchronization). + The Hibernate Session + + If the session couldn't be created. + + + If no thread-bound Session found and allowCreate is false. + + + + + Get a Hibernate Session for the given SessionFactory. Is aware of and will + return any existing corresponding Session bound to the current thread, for + example when using . Will create a new Session + otherwise, if allowCreate is true. + + The session factory to create the session with. + if set to true create a non-transactional Session when no + transactional Session can be found for the current thread. + The hibernate session + + If the session couldn't be created. + + + If no thread-bound Session found and allowCreate is false. + + + + + Get a Hibernate Session for the given SessionFactory. + + Is aware of and will return any existing corresponding + Session bound to the current thread, for example whenusing + . Will create a new + Session otherwise, if "allowCreate" is true. +

Throws the orginal HibernateException, in contrast to + . +

+ The session factory. + if set to true [allow create]. + The Hibernate Session + + if the Session couldn't be created + + + If no thread-bound Session found and allowCreate is false. + + + + + Open a new Session from the factory. + + The session factory to create the session with. + Hibernate entity interceptor, or null if none. + the newly opened session + + + + Perform the actual closing of the Hibernate Session + catching and logging any cleanup exceptions thrown. + + The hibernate session to close + + + + Return whether the given Hibernate Session is transactional, that is, + bound to the current thread by Spring's transaction facilities. + + The hibernate session to check + The session factory that the session + was created with, can be null. + + true if the session transactional; otherwise, false. + + + + + Converts a Hibernate ADOException to a Spring DataAccessExcption, extracting the underlying error code from + ADO.NET. Will extract the ADOException Message and SqlString properties and pass them to the translate method + of the provided IAdoExceptionTranslator. + + The IAdoExceptionTranslator, may be a user provided implementation as configured on + HibernateTemplate. + + The ADOException throw + The translated DataAccessException or UncategorizedAdoException in case of an error in translation + itself. + + + + Convert the given HibernateException to an appropriate exception from the + Spring.Dao hierarchy. Note that it is advisable to + handle AdoException specifically by using a AdoExceptionTranslator for the + underlying ADO.NET exception. + + The Hibernate exception that occured. + DataAccessException instance + + + + Close the given Session, created via the given factory, + if it is not managed externally (i.e. not bound to the thread). + + The hibernate session to close + The hibernate SessionFactory that + the session was created with. + + + + Close the given Session or register it for deferred close. + + The session. + The session factory. + + + + Initialize deferred close for the current thread and the given SessionFactory. + Sessions will not be actually closed on close calls then, but rather at a + processDeferredClose call at a finishing point (like request completion). + + The session factory. + + + + Return if deferred close is active for the current thread + and the given SessionFactory. + The session factory. + + true if [is deferred close active] [the specified session factory]; otherwise, false. + + If SessionFactory argument is null. + + + + Process Sessions that have been registered for deferred close + for the given SessionFactory. + + The session factory. + If there is no session factory associated with the thread. + + + + Applies the current transaction timeout, if any, to the given + criteria object + + The Hibernate Criteria object. + Hibernate SessionFactory that the Criteria was created for + (can be null). + If criteria argument is null. + + + + Applies the current transaction timeout, if any, to the given + Hibenrate query object. + + The Hibernate Query object. + Hibernate SessionFactory that the Query was created for + (can be null). + If query argument is null. + + + + Gets the Spring IDbProvider given the ISessionFactory. + + The matching is performed by comparing the assembly qualified + name string of the hibernate Driver.ConnectionType to those in + the DbProviderFactory definitions. No connections are created + in performing this comparison. + The session factory. + The corresponding IDbProvider, null if no mapping was found. + If DbProviderFactory's ApplicaitonContext is not + an instance of IConfigurableApplicaitonContext. + + + + Create a IAdoExceptionTranslator from the given SessionFactory. + + If a corresponding IDbProvider is found, a ErrorcodeExceptionTranslator + for the IDbProvider is created. Otherwise, a FallbackException is created. + The session factory to create the translator for + An IAdoExceptionTranslator + + + + Implementation of NHibernates 1.2's ICurrentSessionContext interface + that delegates to Spring's SessionFactoryUtils for providing a + Spirng-managed current Session. + + Used by Spring's LocalSessionFactoryBean if told to expose + a transaction-aware SessionFactory. +

This ICurrentSessionContext implementation can also be specified in + custom ISessionFactory setup through the + "hibernate.current_session_context_class" property, with the fully + qualified name of this class as value.

 + Juergen Hoeller + Mark Pollack (.NET) + + + + + Initializes a new instance of the class + + The NHibernate session factory. + + + + Retrieve the Spring-managed Session for the current thread. + + Current session associated with the thread + On errors retrieving thread bound session. + + + + NHibnerations actions taken during the transaction lifecycle. + + Mark Pollack (.NET) + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Suspend this synchronization. + + +

+ Unbind Hibernate resources (SessionHolder) from + + if managing any. +

+ + + + + Resume this synchronization. + + +

+ Rebind Hibernate resources from + + if managing any. +

+ + + + + Invoked before transaction commit (before + ) + + + If the transaction is defined as a read-only transaction. + + +

+ Can flush transactional sessions to the database. +

+

+ Note that exceptions will get propagated to the commit caller and + cause a rollback of the transaction. +

+ + + + + Invoked before transaction commit (before + ) + Can e.g. flush transactional O/R Mapping sessions to the database + + + + This callback does not mean that the transaction will actually be + commited. A rollback decision can still occur after this method + has been called. This callback is rather meant to perform work + that's only relevant if a commit still has a chance + to happen, such as flushing SQL statements to the database. + + + Note that exceptions will get propagated to the commit caller and cause a + rollback of the transaction. + + (note: do not throw TransactionException subclasses here!) + + + + + + Invoked after transaction commit/rollback. + + + Status according to + + + Can e.g. perform resource cleanup, in this case after transaction completion. +

+ Note that exceptions will get propagated to the commit or rollback + caller, although they will not influence the outcome of the transaction. +

+ + + + + Return the order value of this object, where a higher value means greater in + terms of sorting. + + +

+ Normally starting with 0 or 1, with indicating + greatest. Same order values will result in arbitrary positions for the affected + objects. +

+

+ Higher value can be interpreted as lower priority, consequently the first object + has highest priority. +

+ + The order value. + + + + Convenient FactoryObject for defining Hibernate FilterDefinitions. + Exposes a corresponding Hibernate FilterDefinition object. + + + +

+ Typically defined as an inner object within a LocalSessionFactoryObject + definition, as the list element for the "filterDefinitions" object property. + For example: +

+ + 
+            <objectn id="sessionFactory" type="Spring.Data.NHibernate.LocalSessionFactoryObject, Spring.Data.NHibernate">
+              ...
+              <property name="FilterDefinitions">
+               <list>
+                  <object type="Spring.Data.NHibernate.FilterDefinitionFactoryObject, Spring.Data.NHibernate">
+                    <property name="FilterName" value="myFilter"/>
+                    <property name="ParameterTypes">
+                      <props>
+                        <prop key="MyParam">string</prop>
+                        <prop key="MyOtherParam">long</prop>
+                      </props>
+                    </property>
+                  </object>
+                </list>
+              </property>
+              ...
+            </object>
+
+

+ Alternatively, specify an object id (or name) attribute for the inner object, + instead of the "FilterName" property. +

+ + Juergen Hoeller + Marko Lahma (.NET) + + + $Id: FilterDefiniitionFactoryObject.cs,v 1.1 2008/04/07 20:12:53 lahma Exp $ + + + + Initializes the filter definitions. + + + + + Returns the singleton filter definition. + + + + + + Set the name of the filter. + + + + + Set the parameter types for the filter, + with parameter names as keys and type names as values. + + + + + + Specify a default filter condition for the filter, if any. + + + + + If no explicit filter name has been specified, the object name of + the FilterDefinitionFactoryObject will be used. + + + + + + Returns the type of the object this factory produces. + + + + + Returns whether this factory produces singletons, always true. + + + + + Hibernate-specific subclass of ObjectRetrievalFailureException. + + + Converts Hibernate's UnresolvableObjectException, ObjectNotFoundException, + ObjectDeletedException, and WrongClassException. + + Mark Pollack (.NET) + $Id: HibernateObjectRetrievalFailureException.cs,v 1.1 2008/04/07 20:12:53 lahma Exp $ + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Creates a new instance of the HibernateObjectRetrievalFailureException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Hibernate-specific subclass of ObjectOptimisticLockingFailureException. + + + Converts Hibernate's StaleObjectStateException. + + Mark Pollack (.NET) + $Id: HibernateOptimisticLockingFailureException.cs,v 1.2 2008/04/23 11:41:41 lahma Exp $ + + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The StaleStateException. + + + + Creates a new instance of the HibernateOptimisticLockingFailureException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate30.dll b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate30.dll new file mode 100644 index 00000000..c9e4dfab Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate30.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate30.pdb b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate30.pdb new file mode 100644 index 00000000..d6ce2d8c Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate30.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate30.xml b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate30.xml new file mode 100644 index 00000000..23e2e704 --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate30.xml @@ -0,0 +1,6711 @@ + + + + Spring.Data.NHibernate30 + + + + + Holds the references and configuration settings for a instance. + References are resolved by looking up the given object names in the root obtained by . + + + + + Holds the references and configuration settings for a instance. + + + + + Default value for property. + + + + + Default value for property. + + + + + Initialize a new instance of with default values. + + + Calling this constructor from your derived class leaves and + uninitialized. See and for more. + + + + + Initialize a new instance of with the given sessionFactory + and default values for all other settings. + + + The instance to be used for obtaining instances. + + + Calling this constructor marks all properties initialized. + + + + + Initialize a new instance of with the given values and references. + + + The instance to be used for obtaining instances. + + + Specify the to be set on each session provided by the instance. + + + Set whether to use a single session for each request. See property for details. + + + Specify the flushmode to be applied on each session provided by the instance. + + + Calling this constructor marks all properties initialized. + + + + + Override this method to resolve an instance according to your chosen strategy. + + + + + Override this method to resolve an instance according to your chosen strategy. + + + + + Gets the configured instance to be used. + + + If the entity interceptor is not set by the constructor, this property calls + to obtain an instance. This allows derived classes to + override the behaviour of how to obtain the concrete instance. + + + + + Gets the configured instance to be used. + + + If this property is requested for the first time, is called. + This allows derived classes to override the behaviour of how to obtain the concrete instance. + + If the instance cannot be resolved. + + + + Set whether to use a single session for each request. Default is "true". + If set to false, each data access operation or transaction will use + its own session (like without Open Session in View). Each of those + sessions will be registered for deferred close, though, actually + processed at request completion. + + + + + Gets or Sets the flushmode to be applied on each newly created session. + + + This property defaults to to ensure that modifying objects outside the boundaries + of a transaction will not be persisted. It is recommended to not change this value but wrap any modifying operation + within a transaction. + + + + + The default session factory name to use when retrieving the Hibernate session factory from + the root context. + + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + The configuration section to read setting variables from. + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + The variable source to obtain settings from. + + + + Resolve the entityInterceptor by looking up + in the root application context. + + The resolved instance or + + + + Resolve the by looking up + in the root application context. + + The resolved instance or + + + + Convenient super class for Hibernate data access objects. + + + Requires a SessionFactory to be set, providing a HibernateTemplate + based on it to subclasses. Can alternatively be initialized directly with + a HibernateTemplate, to reuse the latter's settings such as the SessionFactory, + exception translator, flush mode, etc + + This base call is mainly intended for HibernateTemplate usage. + + This class will create its own HibernateTemplate if only a SessionFactory + is passed in. The "allowCreate" flag on that HibernateTemplate will be "true" + by default. A custom HibernateTemplate instance can be used through overriding + CreateHibernateTemplate. + + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Create a HibernateTemplate for the given ISessionFactory. + + + Only invoked if populating the DAO with a ISessionFactory reference! +

Can be overridden in subclasses to provide a HibernateTemplate instance + with different configuration, or a custom HibernateTemplate subclass. +

+ + + + + Check if the hibernate template property has been set. + + + + + Get a Hibernate Session, either from the current transaction or + a new one. The latter is only allowed if "allowCreate" is true. + + Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Either rely on a thread-bound + Session (via HibernateInterceptor), or use it in combination with + ReleaseSession. + + In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. + + + if a non-transactional Session should be created when no + transactional Session can be found for the current thread + + Hibernate session. + + If the Session couldn't be created + + + if no thread-bound Session found and allowCreate false + + + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Close the given Hibernate Session, created via this DAO's SessionFactory, + if it isn't bound to the thread. + + + Typically used in plain Hibernate code, in combination with the + Session property and ConvertHibernateAccessException. + + The session to close. + + + + Gets or sets the hibernate template. + + Set the HibernateTemplate for this DAO explicitly, + as an alternative to specifying a SessionFactory. + + The hibernate template. + + + + Gets or sets the session factory to be used by this DAO. + Will automatically create a HibernateTemplate for the given SessionFactory. + + The session factory. + + + + Get a Hibernate Session, either from the current transaction or a new one. + The latter is only allowed if the "allowCreate" setting of this object's + HibernateTemplate is true. + + +

Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Use it in combination with + ReleaseSession. +

+

In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. +

+ + The Hibernate session. + + + + Provide support for the open session in view pattern for lazily loaded hibernate objects + used in ASP.NET pages. + + jjx: http://forum.springframework.net/member.php?u=29 + Mark Pollack (.NET) + Erich Eichinger + Harald Radi + + + + Implementation of SessionScope that associates a single session within the using scope. + + + It is recommended to be used in the following type of scenario: + + using (new SessionScope()) + { + ... do multiple operation, possibly in multiple transactions. + } + + At the end of "using", the session is automatically closed. All transactions within the scope use the same session, + if you are using Spring's HibernateTemplate or using Spring's implementation of NHibernate 1.2's + ICurrentSessionContext interface. + + + It is assumed that the session factory object name is called "SessionFactory". In case that you named the object + in different way you can specify your can specify it in the application settings using the key + Spring.Data.NHibernate.Support.SessionScope.SessionFactoryObjectName. Values for EntityInterceptorObjectName + and SingleSessionMode can be specified similarly. + + + Note: + The session is managed on a per thread basis on the thread that opens the scope instance. This means that you must + never pass a reference to a instance over to another thread! + + + Robert M. (.NET) + Harald Radi (.NET) + + + + The logging instance. + + + + + Initializes a new instance of the class in single session mode, + associating a session with the thread. The session is opened lazily on demand. + + + + + Initializes a new instance of the class. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The name of the configuration section to read configuration settings from. + See for more info. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The name of the configuration section to read configuration settings from. + See for more info. + + The type, who's full name is used for prefixing appSetting keys + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The instance to be used for obtaining instances. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The instance to be used for obtaining instances. + + + Specify the to be set on each session provided by this instance. + + + Set whether to use a single session for each request. See property for details. + + + Specify the flushmode to be applied on each session provided by this instance. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + An instance holding the scope configuration + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Sets a flag, whether this scope is in "open" state on the current logical thread. + + + + + Gets/Sets a flag, whether this scope manages it's own session for the current logical thread or not. + + false if session is managed by this module. false otherwise + + + + Call Close(), + + + + + Opens a new session or participates in an existing session and + registers with spring's . + + + + + Close the current view's session and unregisters + from spring's . + + + + + Set whether to use a single session for each request. Default is "true". + If set to false, each data access operation or transaction will use + its own session (like without Open Session in View). Each of those + sessions will be registered for deferred close, though, actually + processed at request completion. + + + + + Gets the flushmode to be applied on each newly created session. + + + This property defaults to to ensure that modifying objects outside the boundaries + of a transaction will not be persisted. It is recommended to not change this value but wrap any modifying operation + within a transaction. + + + + + Get or set the configured SessionFactory + + + + + Get or set the configured EntityInterceptor + + + + + Gets a flag, whether this scope is in "open" state on the current logical thread. + + + + + Gets a flag, whether this scope manages it's own session for the current logical thread or not. + + + + + This sessionHolder creates a default session only if it is needed. + + + Although a NHibernateSession deferes creation of db-connections until they are really + needed, instantiation a session is imho still more expensive than this LazySessionHolder. (EE) + + + + + Session holder, wrapping a NHibernate ISession and a NHibernate Transaction. + HibernateTransactionManager binds instances of this class + to the thread, for a given ISessionFactory. + + + Note: This is an SPI class, not intended to be used by applications. + + Mark Pollack (.NET) + + + + May be used by derived classes to create an empty SessionHolder. + + + When using this ctor in your derived class, you MUST override ! + + + + + Initializes a new instance of the class. + + The session. + + + + Initializes a new instance of the class. + + The key to store the session under. + The hibernate session. + + + + May be overridden in a derived class to e.g. lazily create a session + + + + + Gets the session given key identifier + + The key. + A hibernate session + + + + Gets the session given the key and removes the session from + the dictionary storage. + + The key. + A hibernate session + + + + Adds the session to the dictionary storage using the default key. + + The hibernate session. + + + + Adds the session to the dictionary storage using the supplied key. + + The key. + The hibernate session. + + + + Removes the session from the dictionary storage for the given key. + + The key. + The session that was previously contained in the + dictionary storage. + + + + Determines whether the holder the specified session. + + The session. + + true if the holder contains the specified session; otherwise, false. + + + + + Clear the transaction state of this resource holder. + + + + + Gets the session using the default key + + The hibernate session. + + + + Gets the first session based on iteration over + the IDictionary storage. + + Any hibernate session. + + + + Gets a value indicating whether dictionary of + hibernate sessions is empty. + + + true if this session holder is empty; otherwise, false. + + + + + Gets a value indicating whether this SessionHolder + does not hold non default session. + + + true if does not hold non default session; otherwise, false. + + + + + Gets or sets the hibernate transaction. + + The transaction. + + + + Gets or sets the ADO.NET Connection used to create the session. + + The ADO.NET connection. + + + + Gets or sets the previous flush mode. + + The previous flush mode. + + + + Gets a value indicating whether the PreviousFlushMode property + was set. + + + true if assigned PreviousFlushMode property; otherwise, false. + + + + + Gets the validated session. + + The validated session. + + + + Initialize a new instance. + + + + + Create a new session on demand + + + + + Ensure session is closed (if any) and remove circular references to avoid memory leaks! + + + + + Initializes a new instance of the class. Creates a SessionScope, + but does not yet associate a session with a thread, that is left to the lifecycle of the request. + + + + + Register context handler and look up SessionFactoryObjectName under the application configuration key, + Spring.Data.NHibernate.Support.OpenSessionInViewModule.SessionFactoryObjectName if not using the default value + (i.e. sessionFactory) and look up the SingleSession setting under the application configuration key, + Spring.Data.NHibernate.Support.OpenSessionInViewModule.SingleSession if not using the default value of true. + + The standard HTTP application context + + + + A do nothing dispose method. + + + + + Hibernate-specific subclass of UncategorizedDataAccessException, + for ADO.NET exceptions that Hibernate rethrew and could not be + mapped into the DAO exception heirarchy. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception from the underlying data access API - ADO.NET + + + + + Creates a new instance of the HibernateSystemException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Hibernate-specific subclass of InvalidDataAccessResourceUsageException, + thrown on invalid HQL query syntax. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Initializes a new instance of the class. + + The ex. + + + + Creates a new instance of the HibernateQueryException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Gets the query string that was invalid. + + The query string that was invalid. + + + + Hibernate-specific subclass of UncategorizedDataAccessException, + for Hibernate system errors that do not match any concrete + Spring.Dao exceptions. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message. + + + + Creates a new instance of the HibernateSystemException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Initializes a new instance of the class. + + The cause. + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Helper class that simplifies NHibernate data access code + + +

Typically used to implement data access or business logic services that + use NHibernate within their implementation but are Hibernate-agnostic in their + interface. The latter or code calling the latter only have to deal with + domain objects.

+ +

The central method is Execute supporting Hibernate access code + implementing the HibernateCallback interface. It provides NHibernate Session + handling such that neither the IHibernateCallback implementation nor the calling + code needs to explicitly care about retrieving/closing NHibernate Sessions, + or handling Session lifecycle exceptions. For typical single step actions, + there are various convenience methods (Find, Load, SaveOrUpdate, Delete). +

+ +

Can be used within a service implementation via direct instantiation + with a ISessionFactory reference, or get prepared in an application context + and given to services as an object reference. Note: The ISessionFactory should + always be configured as an object in the application context, in the first case + given to the service directly, in the second case to the prepared template. +

+ +

This class can be considered as direct alternative to working with the raw + Hibernate Session API (through SessionFactoryUtils.Session). +

+ +

LocalSessionFactoryObject is the preferred way of obtaining a reference + to a specific NHibernate ISessionFactory. +

+ + Mark Pollack (.NET) + + + + Base class for HibernateTemplate defining common + properties like SessionFactory and flushing behavior. + + +

Not intended to be used directly. See HibernateTemplate. +

+ + Mark Pollack (.NET) + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Apply the flush mode that's been specified for this accessor + to the given Session. + + The current Hibernate Session. + if set to true + if executing within an existing transaction. + + the previous flush mode to restore after the operation, + or null if none + + + + + Flush the given Hibernate Session if necessary. + + The current Hibernate Session. + if set to true + if executing within an existing transaction. + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + ADOException that occured, wrapping underlying ADO.NET exception. + + the corresponding DataAccessException instance + + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + + + Note that a direct SQLException can just occur when callback code + performs direct ADO.NET access via ISession.Connection(). + + + The ADO.NET exception. + The corresponding DataAccessException instance + + + + Prepare the given IQuery object, applying cache settings and/or + a transaction timeout. + + The query object to prepare. + + + + Apply the given name parameter to the given Query object. + + The query object. + Name of the parameter + The value of the parameter + The NHibernate type of the parameter (or null if none specified) + + + + Prepare the given Criteria object, applying cache settings and/or + a transaction timeout. + + + Note that for NHibernate 1.2 this only works if the + implementation is of the type CriteriaImpl, which should generally + be the case. The SetFetchSize method is not available on the + ICriteria interface + + This is a no-op for NHibernate 1.0.x since + the SetFetchSize method is not on the ICriteria interface and + the implementation class is has internal access. + + To remove the method completely for Spring's NHibernate 1.0 + support while reusing code for NHibernate 1.2 would not be + possible. So now this ineffectual operation is left in tact for + NHibernate 1.0.2 support. + + The criteria object to prepare + + + + Ensure SessionFactory is not null + + If SessionFactory property is null. + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Set the object factory instance. + + The object factory instance. + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Gets a Session for use by this template. + + The session. + + - Returns a new Session in case of "alwaysUseNewSession" (using the same ADO.NET connection as a transaction Session, if applicable) + - a pre-bound Session in case of "AllowCreate" is set to false (not the default) + - or a pre-bound Session or new Session if no transactional or other pre-bound Session exists. + + + + + Helper class to determine if the FlushMode enumeration + was changed from its default value + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The flush mode. + + + + Gets or sets a value indicating whether the FlushMode + property was set.. + + true if FlushMode was set; otherwise, false. + + + + Gets or sets the FlushMode. + + The FlushMode. + + + + Interface that specifies a basic set of Hibernate operations. + + + Implemented by HibernateTemplate. Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + + Mark Pollack (.NET) + + + + Interface that specifies a set of Hibernate operations that + are common across versions of Hibernate. + + + Base interface for generic and non generic IHibernateOperations interfaces + Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + Mark Pollack (.NET) + + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + In case of Hibernate errors + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + Tthe persistent instance to delete. + The lock mode to obtain. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Delete all given persistent instances. + + The persistent instances to delete. + + This can be combined with any of the find methods to delete by query + in two lines of code, similar to Session's delete by query methods. + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the specified action assuming that the result object is a List. + + + This is a convenience method for executing Hibernate find calls or + queries within an action. + + The calback object that specifies the Hibernate action. + A IList returned by the action, or null + + In case of Hibernate errors + + + + Execute a query for persistent instances. + + a query expressed in Hibernate's query language + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + a query expressed in Hibernate's query language + the value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + a query expressed in Hibernate's query language + the values of the parameters + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + a List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + + a persistent type. + An identifier of the persistent instance. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + A persistent class. + An identifier of the persistent instance. + The lock mode. + the persistent instance, or null if not found + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + Type of the entity. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + Type of the entity. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + Type of the entity. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Save or update all given persistent instances, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instances to save or update + (to be associated with the Hibernate Session)he entities. + In case of Hibernate errors + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The default for creating a new non-transactional + session when no transactional Session can be found for the current thread + is set to true. + The session factory to create sessions. + + + + Initializes a new instance of the class. + + The session factory to create sessions. + if set to true allow creation + of a new non-transactional when no transactional Session can be found + for the current thread. + + + + Delegate function that clears the session. + + The hibernate session. + null + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + + The type. + An identifier of the persistent instance. + The persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The type. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + Type of the entity. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + Type of the entity. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + Type of the entity. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update all given persistent instances, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instances to save or update + (to be associated with the Hibernate Session)he entities. + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + Tthe persistent instance to delete. + The lock mode to obtain. + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + If length for argument values and types are not equal. + + + + Delete all given persistent instances. + + The persistent instances to delete. + + This can be combined with any of the find methods to delete by query + in two lines of code, similar to Session's delete by query methods. + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + + + + Execute the action specified by the given action object within a Session. + + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the specified action assuming that the result object is a List. + + + This is a convenience method for executing Hibernate find calls or + queries within an action. + + The calback object that specifies the Hibernate action. + A IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + + + + Execute a query for persistent instances. + + a query expressed in Hibernate's query language + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + a query expressed in Hibernate's query language + the value of the parameter + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + a query expressed in Hibernate's query language + the values of the parameters + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Create a close-suppressing proxy for the given Hibernate Session. + The proxy also prepares returned Query and Criteria objects. + + The session. + The session proxy. + + + + Check whether write operations are allowed on the given Session. + + + Default implementation throws an InvalidDataAccessApiUsageException + in case of FlushMode.Never. Can be overridden in subclasses. + + The current Hibernate session. + If write operation is attempted in read-only mode + + + + + Compares if the flush mode enumerations, Spring's + TemplateFlushMode and NHibernates FlushMode have equal + settings. + + The template flush mode. + The NHibernate flush mode. + + Returns true if both are Never, Auto, or Commit, false + otherwise. + + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + If object factory is not set and need to retrieve entity interceptor by name. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets whether to check that the Hibernate Session is not in read-only mode + in case of write operations (save/update/delete). + + + true if check that the Hibernate Session is not in read-only mode + in case of write operations; otherwise, false. + + + Default is "true", for fail-fast behavior when attempting write operations + within a read-only transaction. Turn this off to allow save/update/delete + on a Session with flush mode NEVER. + + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Set the object factory instance. + + The object factory instance + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the proxy factory. + + This may be useful to set if you create many instances of + HibernateTemplate and/or HibernateDaoSupport. This allows the same + ProxyFactory implementation to be used thereby limiting the + number of dynamic proxy types created in the temporary assembly, which + are never garbage collected due to .NET runtime semantics. + + The proxy factory. + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Callback interface for NHibernate code. + + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + Mark Pollack (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + A result object, or null if none. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + PlatformTransactionManager implementation for a single Hibernate SessionFactory. + Binds a Hibernate Session from the specified factory to the thread, potentially + allowing for one thread Session per factory + + + SessionFactoryUtils and HibernateTemplate are aware of thread-bound Sessions and participate in such + transactions automatically. Using either of those is required for Hibernate + access code that needs to support this transaction handling mechanism. + + Supports custom isolation levels at the start of the transaction + , and timeouts that get applied as appropriate + Hibernate query timeouts. To support the latter, application code must either use + HibernateTemplate (which by default applies the timeouts) or call + SessionFactoryUtils.applyTransactionTimeout for each created + Hibernate Query object. + + Note that you can specify a Spring IDbProvider instance which if shared with + a corresponding instance of AdoTemplate will allow for mixing ADO.NET/NHibernate + operations within a single transaction. + + Mark Pollack (.NET) + + + + Just needed for entityInterceptorBeanName. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The session factory. + + + + Return the current transaction object. + + The current transaction object. + + If transaction support is not available. + + + In the case of lookup or system errors. + + + + + Check if the given transaction object indicates an existing, + i.e. already begun, transaction. + + + Transaction object returned by + . + + True if there is an existing transaction. + + In the case of system errors. + + + + + Begin a new transaction with the given transaction definition. + + + Transaction object returned by + . + + + instance, describing + propagation behavior, isolation level, timeout etc. + + + Does not have to care about applying the propagation behavior, + as this has already been handled by this abstract manager. + + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + + Transaction object returned by + . + + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + Transaction synchronization will already have been suspended. + + + If suspending is not supported by the transaction manager implementation. + + + in case of system errors. + + + + + Resume the resources of the current transaction. + + + Transaction object returned by + . + + + The object that holds suspended resources as returned by + . + + + Transaction synchronization will be resumed afterwards. + + + If suspending is not supported by the transaction manager implementation. + + + In the case of system errors. + + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + +

+ An implementation does not need to check the rollback-only flag. +

+ + + In the case of system errors. + + + + + Perform an actual rollback on the given transaction. + + The status representation of the transaction. + + An implementation does not need to check the new transaction flag. + + + In the case of system errors. + + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + The status representation of the transaction. + + In the case of system errors. + + + + + Gets the ADO.NET IDbTransaction object from the NHibernate ITransaction object. + + The hibernate transaction. + The ADO.NET transaction. Null if could not get the transaction. Warning + messages will be logged in that case. + + + + Convert the given HibernateException to an appropriate exception from + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The HibernateException that occured. + The corresponding DataAccessException instance + + + + Convert the given ADOException to an appropriate exception from the + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The ADOException that occured, wrapping the underlying + ADO.NET thrown exception. + The translator to convert hibernate ADOExceptions. + + The corresponding DataAccessException instance + + + + + Cleanup resources after transaction completion. + + Transaction object returned by + . + + + This implemenation unbinds the SessionFactory and + DbProvider from thread local storage and closes the + ISession. + +

+ Called after + and + + execution on any outcome. +

+

+ Should not throw any exceptions but just issue warnings on errors. +

+ + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Gets or sets the db provider. + + The db provider. + + + + Gets or sets a Hibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + When getting, return the current Hibernate entity interceptor, or null if none. + + The entity interceptor. + + Resolves an entity interceptor object name via the object factory, + if necessary. + Will get applied to any new Session created by this transaction manager. + Such an interceptor can either be set at the SessionFactory level, + i.e. on LocalSessionFactoryObject, or at the Session level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. + + If object factory is null and need to get entity interceptor via object name. + + + + Sets the object name of a Hibernate entity interceptor that + allows to inspect and change property values before writing to and reading from the database. + + The name of the entity interceptor object. + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + + + + Gets or sets the ADO.NET exception translator for this transaction manager. + + + Applied to ADO.NET Exceptions (wrapped by Hibernate's ADOException) + + The ADO exception translator. + + + + Gets the default IAdoException translator, lazily creating it if nece + + The default IAdoException translator. + + + + Gets or sets the SessionFactory that this instance should manage transactions for. + + The session factory. + + + + Gets the resource factory that this transaction manager operates on, + For the HibenratePlatformTransactionManager this the SessionFactory + + The SessionFactory. + + + + Set whether to autodetect a ADO.NET connection used by the Hibernate SessionFactory, + if set via LocalSessionFactoryObject's DbProvider. Default is "true". + + + true if [autodetect data source]; otherwise, false. + + +

Can be turned off to deliberately ignore an available IDbProvider, + to not expose Hibernate transactions as ADO.NET transactions for that IDbProvider. +

+ + + + + The object factory just needs to be known for resolving entity interceptor + It does not need to be set for any other mode of operation. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + + + + Return whether the transaction is internally marked as rollback-only. + + + True of the transaction is marked as rollback-only. + + + + Enumeration for the various Hibernate flush modes. + + Mark Pollack (.NET) + + + Never flush is a good strategy for read-only units of work. + + + Hibernate will not track and look for changes in this case, + avoiding any overhead of modification detection. +

In case of an existing ISession, TemplateFlushMode.Never will turn + the hibenrate flush mode + to FlushMode.Never for the scope of the current operation, resetting the previous + flush mode afterwards. +

+ + + + Automatic flushing is the default mode for a Hibernate Session. + + + A session will get flushed on transaction commit, and on certain find + operations that might involve already modified instances, but not + after each unit of work like with eager flushing. +

In case of an existing Session, TemplateFlushMode.Auto + will participate in the existing flush mode, not modifying + it for the current operation. + This in particular means that this setting will not modify an existing + hibernate flush mode FlushMode.Never, in contrast to TemplateFlushMode.Eager. +

+ + + + + Eager flushing leads to immediate synchronization with the database, + even if in a transaction. + + + This causes inconsistencies to show up and throw + a respective exception immediately, and ADO access code that participates + in the same transaction will see the changes as the database is already + aware of them then. But the drawbacks are: +
    +
  • additional communication roundtrips with the database, instead of a + single batch at transaction commit;
    • +
  • the fact that an actual database rollback is needed if the Hibernate + transaction rolls back (due to already submitted SQL statements).
    • +
+

In case of an existing Session, TemplateFlushMode.Eager + will turn the NHibernate flush mode + to FlushMode.Auto for the scope of the current operation and issue a flush at the + end, resetting the previous flush mode afterwards. +

+ + + + + Flushing at commit only is intended for units of work where no + intermediate flushing is desired, not even for find operations + that might involve already modified instances. + + +

In case of an existing Session, TemplateFlushMode.Commit + will turn the NHibernate flush mode + to FlushMode.Commit for the scope of the current operation, resetting the previous + flush mode afterwards. The only exception is an existing flush mode + FlushMode.Never, which will not be modified through this setting. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning an IList of result objects created within the callback. + Note that there's special support for single step actions: + see HibernateTemplate.find etc. +

+ + The type of result object + Sree Nivask (.NET) + + + + Convenient super class for Hibernate data access objects. + + + Requires a SessionFactory to be set, providing a HibernateTemplate + based on it to subclasses. Can alternatively be initialized directly with + a HibernateTemplate, to reuse the latter's settings such as the SessionFactory, + exception translator, flush mode, etc + + This base call is mainly intended for HibernateTemplate usage. + + This class will create its own HibernateTemplate if only a SessionFactory + is passed in. The "allowCreate" flag on that HibernateTemplate will be "true" + by default. A custom HibernateTemplate instance can be used through overriding + CreateHibernateTemplate. + + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Create a HibernateTemplate for the given ISessionFactory. + + + Only invoked if populating the DAO with a ISessionFactory reference! +

Can be overridden in subclasses to provide a HibernateTemplate instance + with different configuration, or a custom HibernateTemplate subclass. +

+ + The new HibernateTemplate instance + + + + Check if the hibernate template property has been set. + + If HibernateTemplate property is null. + + + + Get a Hibernate Session, either from the current transaction or + a new one. The latter is only allowed if "allowCreate" is true. + + Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Either rely on a thread-bound + Session (via HibernateInterceptor), or use it in combination with + ReleaseSession. + + In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. + + + if a non-transactional Session should be created when no + transactional Session can be found for the current thread + + Hibernate session. + + If the Session couldn't be created + + + if no thread-bound Session found and allowCreate false + + + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Close the given Hibernate Session, created via this DAO's SessionFactory, + if it isn't bound to the thread. + + + Typically used in plain Hibernate code, in combination with the + Session property and ConvertHibernateAccessException. + + The session to close. + + + + Gets or sets the hibernate template. + + Set the HibernateTemplate for this DAO explicitly, + as an alternative to specifying a SessionFactory. + + The hibernate template. + + + + Gets or sets the session factory to be used by this DAO. + Will automatically create a HibernateTemplate for the given SessionFactory. + + The session factory. + + + + Get a Hibernate Session, either from the current transaction or a new one. + The latter is only allowed if the "allowCreate" setting of this object's + HibernateTemplate is true. + + +

Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Use it in combination with + ReleaseSession. +

+

In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. +

+ + The Hibernate session. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning the result object created within the callback. + Note that there's special support for single step actions: + see HibernateTemplate.find etc. +

+ + The type of result object + Sree Nivask (.NET) + + + + Generic version of the Helper class that simplifies NHibernate data access code + + +

Typically used to implement data access or business logic services that + use NHibernate within their implementation but are Hibernate-agnostic in their + interface. The latter or code calling the latter only have to deal with + domain objects.

+ +

The central method is Execute() supporting Hibernate access code which + implements the HibernateCallback interface. It provides NHibernate Session + handling such that neither the IHibernateCallback implementation nor the calling + code needs to explicitly care about retrieving/closing NHibernate Sessions, + or handling Session lifecycle exceptions. For typical single step actions, + there are various convenience methods (Find, Load, SaveOrUpdate, Delete). +

+ +

Can be used within a service implementation via direct instantiation + with a ISessionFactory reference, or get prepared in an application context + and given to services as an object reference. Note: The ISessionFactory should + always be configured as an object in the application context, in the first case + given to the service directly, in the second case to the prepared template. +

+ +

This class can be considered as a direct alternative to working with the raw + Hibernate Session API (through SessionFactoryUtils.Session). +

+ +

LocalSessionFactoryObject is the preferred way of obtaining a reference + to a specific NHibernate ISessionFactory. +

+ + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Interface that specifies a basic set of Hibernate operations. + + + Implemented by HibernateTemplate. Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Return the persistent instance of the given entity type + with the given identifier, or if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The id of the object to get. + the persistent instance, or if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + The object type to load. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + The object type to load. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + The object type to load. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances. + + The object type to find. + a query expressed in Hibernate's query language + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the value of the parameter + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + The object type to find. + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the values of the parameters + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lenths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type retrieved. + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type retrieved. + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type to find. + The delegate callback object that specifies the Hibernate action. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type to find. + The FindHibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type to find. + The callback object that specifies the Hibernate action. + + A generic IList returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + + + + Execute the action specified by the given action object within a Session assuming that an IList is returned. + + The object type to find. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + an IList returned by the action, or null + + In case of Hibernate errors + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + Allows creation of a new non-transactional session when no + transactional Session can be found for the current thread + The session factory to create sessions. + + + + Initializes a new instance of the class. + + The session factory to create sessions. + if set to true allow creation + of a new non-transactional session when no transactional Session can be found + for the current thread. + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + Tthe persistent instance to delete. + The lock mode to obtain. + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The id of the object to get. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + The object type to load. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + The object type to load. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + The object type to load. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances. + + The object type to find. + a query expressed in Hibernate's query language + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the value of the parameter + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + The object type to find. + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the values of the parameters + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type retrieved. + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type retrieved. + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session assuming that an IList is returned. + + The object type to find. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + an IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type to find. + The delegate callback object that specifies the Hibernate action. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type to find. + The FindHibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type to find. + The callback object that specifies the Hibernate action. + + A generic IList returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Set the object factory instance. + + The object factory instance + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Gets the classic hibernate template for access to non-generic methods. + + The classic hibernate template. + + + + Gets or sets the proxy factory. + + This may be useful to set if you create many instances of + HibernateTemplate and/or HibernateDaoSupport. This allows the same + ProxyFactory implementation to be used thereby limiting the + number of dynamic proxy types created in the temporary assembly, which + are never garbage collected due to .NET runtime semantics. + + The proxy factory. + + + + Callback interface (Generic version) for NHibernate code. + + The type of result object + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + + Sree Nivask (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + A result object. + The active Hibernate session + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Callback interface (Generic version) for NHibernate code that + returns a List of objects. + + The type of result object + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + Collection result object. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Helper class featuring methods for Hibernate Session handling, + allowing for reuse of Hibernate Session instances within transactions. + Also provides support for exception translation. + + Mark Pollack (.NET) + + + + The instance for this class. + + + + + The ordering value for synchronizaiton this session resources. + Set to be lower than ADO.NET synchronization. + + + + + Initializes a new instance of the class. + + + + + Get a new Hibernate Session from the given SessionFactory. + Will return a new Session even if there already is a pre-bound + Session for the given SessionFactory. + + + Within a transaction, this method will create a new Session + that shares the transaction's ADO.NET Connection. More specifically, + it will use the same ADO.NET Connection as the pre-bound Hibernate Session. + + The session factory to create the session with. + The Hibernate entity interceptor, or null if none. + The new session. + If could not open Hibernate session + + + + Get a Hibernate Session for the given SessionFactory. Is aware of and will + return any existing corresponding Session bound to the current thread, for + example when using HibernateTransactionManager. Will always create a new + Session otherwise. + + + Supports setting a Session-level Hibernate entity interceptor that allows + to inspect and change property values before writing to and reading from the + database. Such an interceptor can also be set at the SessionFactory level + (i.e. on LocalSessionFactoryObject), on HibernateTransactionManager, or on + HibernateInterceptor/HibernateTemplate. + + The session factory to create the + session with. + Hibernate entity interceptor, or null if none. + AdoExceptionTranslator to use for flushing the + Session on transaction synchronization (can be null; only used when actually + registering a transaction synchronization). + The Hibernate Session + + If the session couldn't be created. + + + If no thread-bound Session found and allowCreate is false. + + + + + Get a Hibernate Session for the given SessionFactory. Is aware of and will + return any existing corresponding Session bound to the current thread, for + example when using . Will create a new Session + otherwise, if allowCreate is true. + + The session factory to create the session with. + if set to true create a non-transactional Session when no + transactional Session can be found for the current thread. + The hibernate session + + If the session couldn't be created. + + + If no thread-bound Session found and allowCreate is false. + + + + + Get a Hibernate Session for the given SessionFactory. + + Is aware of and will return any existing corresponding + Session bound to the current thread, for example whenusing + . Will create a new + Session otherwise, if "allowCreate" is true. +

Throws the orginal HibernateException, in contrast to + . +

+ The session factory. + if set to true [allow create]. + The Hibernate Session + + if the Session couldn't be created + + + If no thread-bound Session found and allowCreate is false. + + + + + Open a new Session from the factory. + + The session factory to create the session with. + Hibernate entity interceptor, or null if none. + the newly opened session + + + + Perform the actual closing of the Hibernate Session + catching and logging any cleanup exceptions thrown. + + The hibernate session to close + + + + Return whether the given Hibernate Session is transactional, that is, + bound to the current thread by Spring's transaction facilities. + + The hibernate session to check + The session factory that the session + was created with, can be null. + + true if the session transactional; otherwise, false. + + + + + Converts a Hibernate ADOException to a Spring DataAccessExcption, extracting the underlying error code from + ADO.NET. Will extract the ADOException Message and SqlString properties and pass them to the translate method + of the provided IAdoExceptionTranslator. + + The IAdoExceptionTranslator, may be a user provided implementation as configured on + HibernateTemplate. + + The ADOException throw + The translated DataAccessException or UncategorizedAdoException in case of an error in translation + itself. + + + + Convert the given HibernateException to an appropriate exception from the + Spring.Dao hierarchy. Note that it is advisable to + handle AdoException specifically by using a AdoExceptionTranslator for the + underlying ADO.NET exception. + + The Hibernate exception that occured. + DataAccessException instance + + + + Close the given Session, created via the given factory, + if it is not managed externally (i.e. not bound to the thread). + + The hibernate session to close + The hibernate SessionFactory that + the session was created with. + + + + Close the given Session or register it for deferred close. + + The session. + The session factory. + + + + Initialize deferred close for the current thread and the given SessionFactory. + Sessions will not be actually closed on close calls then, but rather at a + processDeferredClose call at a finishing point (like request completion). + + The session factory. + + + + Return if deferred close is active for the current thread + and the given SessionFactory. + The session factory. + + true if [is deferred close active] [the specified session factory]; otherwise, false. + + If SessionFactory argument is null. + + + + Process Sessions that have been registered for deferred close + for the given SessionFactory. + + The session factory. + If there is no session factory associated with the thread. + + + + Applies the current transaction timeout, if any, to the given + criteria object + + The Hibernate Criteria object. + Hibernate SessionFactory that the Criteria was created for + (can be null). + If criteria argument is null. + + + + Applies the current transaction timeout, if any, to the given + Hibenrate query object. + + The Hibernate Query object. + Hibernate SessionFactory that the Query was created for + (can be null). + If query argument is null. + + + + Gets the Spring IDbProvider given the ISessionFactory. + + The matching is performed by comparing the assembly qualified + name string of the hibernate Driver.ConnectionType to those in + the DbProviderFactory definitions. No connections are created + in performing this comparison. + The session factory. + The corresponding IDbProvider, null if no mapping was found. + If DbProviderFactory's ApplicaitonContext is not + an instance of IConfigurableApplicaitonContext. + + + + Create a IAdoExceptionTranslator from the given SessionFactory. + + If a corresponding IDbProvider is found, a ErrorcodeExceptionTranslator + for the IDbProvider is created. Otherwise, a FallbackException is created. + The session factory to create the translator for + An IAdoExceptionTranslator + + + + Implementation of NHibernates 1.2's ICurrentSessionContext interface + that delegates to Spring's SessionFactoryUtils for providing a + Spirng-managed current Session. + + Used by Spring's LocalSessionFactoryBean if told to expose + a transaction-aware SessionFactory. +

This ICurrentSessionContext implementation can also be specified in + custom ISessionFactory setup through the + "hibernate.current_session_context_class" property, with the fully + qualified name of this class as value.

 + Juergen Hoeller + Mark Pollack (.NET) + + + + + Initializes a new instance of the class + + The NHibernate session factory. + + + + Retrieve the Spring-managed Session for the current thread. + + Current session associated with the thread + On errors retrieving thread bound session. + + + + NHibnerations actions taken during the transaction lifecycle. + + Mark Pollack (.NET) + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Suspend this synchronization. + + +

+ Unbind Hibernate resources (SessionHolder) from + + if managing any. +

+ + + + + Resume this synchronization. + + +

+ Rebind Hibernate resources from + + if managing any. +

+ + + + + Invoked before transaction commit (before + ) + + + If the transaction is defined as a read-only transaction. + + +

+ Can flush transactional sessions to the database. +

+

+ Note that exceptions will get propagated to the commit caller and + cause a rollback of the transaction. +

+ + + + + Invoked before transaction commit (before + ) + Can e.g. flush transactional O/R Mapping sessions to the database + + + + This callback does not mean that the transaction will actually be + commited. A rollback decision can still occur after this method + has been called. This callback is rather meant to perform work + that's only relevant if a commit still has a chance + to happen, such as flushing SQL statements to the database. + + + Note that exceptions will get propagated to the commit caller and cause a + rollback of the transaction. + + (note: do not throw TransactionException subclasses here!) + + + + + + Invoked after transaction commit/rollback. + + + Status according to + + + Can e.g. perform resource cleanup, in this case after transaction completion. +

+ Note that exceptions will get propagated to the commit or rollback + caller, although they will not influence the outcome of the transaction. +

+ + + + + Return the order value of this object, where a higher value means greater in + terms of sorting. + + +

+ Normally starting with 0 or 1, with indicating + greatest. Same order values will result in arbitrary positions for the affected + objects. +

+

+ Higher value can be interpreted as lower priority, consequently the first object + has highest priority. +

+ + The order value. + + + + Convenient FactoryObject for defining Hibernate FilterDefinitions. + Exposes a corresponding Hibernate FilterDefinition object. + + + +

+ Typically defined as an inner object within a LocalSessionFactoryObject + definition, as the list element for the "filterDefinitions" object property. + For example: +

+ + 
+            <objectn id="sessionFactory" type="Spring.Data.NHibernate.LocalSessionFactoryObject, Spring.Data.NHibernate">
+              ...
+              <property name="FilterDefinitions">
+               <list>
+                  <object type="Spring.Data.NHibernate.FilterDefinitionFactoryObject, Spring.Data.NHibernate">
+                    <property name="FilterName" value="myFilter"/>
+                    <property name="ParameterTypes">
+                      <props>
+                        <prop key="MyParam">string</prop>
+                        <prop key="MyOtherParam">long</prop>
+                      </props>
+                    </property>
+                  </object>
+                </list>
+              </property>
+              ...
+            </object>
+
+

+ Alternatively, specify an object id (or name) attribute for the inner object, + instead of the "FilterName" property. +

+ + Juergen Hoeller + Marko Lahma (.NET) + + + $Id: FilterDefiniitionFactoryObject.cs,v 1.1 2008/04/07 20:12:53 lahma Exp $ + + + + Initializes the filter definitions. + + + + + Returns the singleton filter definition. + + + + + + Set the name of the filter. + + + + + Set the parameter types for the filter, + with parameter names as keys and type names as values. + + + + + + Specify a default filter condition for the filter, if any. + + + + + If no explicit filter name has been specified, the object name of + the FilterDefinitionFactoryObject will be used. + + + + + + Returns the type of the object this factory produces. + + + + + Returns whether this factory produces singletons, always true. + + + + + Hibernate-specific subclass of ObjectRetrievalFailureException. + + + Converts Hibernate's UnresolvableObjectException, ObjectNotFoundException, + ObjectDeletedException, and WrongClassException. + + Mark Pollack (.NET) + $Id: HibernateObjectRetrievalFailureException.cs,v 1.1 2008/04/07 20:12:53 lahma Exp $ + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Creates a new instance of the HibernateObjectRetrievalFailureException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Hibernate-specific subclass of ObjectOptimisticLockingFailureException. + + + Converts Hibernate's StaleObjectStateException. + + Mark Pollack (.NET) + $Id: HibernateOptimisticLockingFailureException.cs,v 1.2 2008/04/23 11:41:41 lahma Exp $ + + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The StaleStateException. + + + + Creates a new instance of the HibernateOptimisticLockingFailureException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + An IFactoryObject that creates a local Hibernate SessionFactory instance. + Behaves like a SessionFactory instance when used as bean reference, + e.g. for HibernateTemplate's "SessionFactory" property. + + + The typical usage will be to register this as singleton factory + in an application context and give objects references to application services + that need it. + + Hibernate configuration settings can be set using the IDictionary property 'HibernateProperties'. + + + This class implements the interface, + as autodetected by Spring's + for AOP-based translation of PersistenceExceptionTranslationPostProcessor. + Hence, the presence of e.g. LocalSessionFactoryBean automatically enables + a PersistenceExceptionTranslationPostProcessor to translate Hibernate exceptions. + + + Mark Pollack (.NET) + + + + The shared instance for this class (and derived classes). + + + + + Initializes a new instance of the class. + + + + + Return the singleon session factory. + + The singleon session factory. + + + + Initialize the SessionFactory for the given or the + default location. + + + + + Close the SessionFactory on application context shutdown. + + + + + Subclasses can override this method to perform custom initialization + of the Configuration instance used for ISessionFactory creation. + + + The properties of this LocalSessionFactoryObject will be applied to + the Configuration object that gets returned here. +

The default implementation creates a new Configuration instance. + A custom implementation could prepare the instance in a specific way, + or use a custom Configuration subclass. +

+ + The configuration instance. + + + + To be implemented by subclasses that want to to register further mappings + on the Configuration object after this FactoryObject registered its specified + mappings. + + + Invoked before the BuildMappings call, + so that it can still extend and modify the mapping information. + + the current Configuration object + + + + To be implemented by subclasses that want to to perform custom + post-processing of the Configuration object after this FactoryObject + performed its default initialization. + + The current configuration object. + + + + Executes schema update if requested. + + + + + Execute schema drop script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaExport class, to be invoked on application setup. + + + Fetch the LocalSessionFactoryBean itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfb = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute schema creation script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaExport class, to be invoked on application setup. + + + Fetch the LocalSessionFactoryObject itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfo = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute schema update script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaUpdate class, for automatically executing schema update scripts + on application startup. Can also be invoked manually. + + + Fetch the LocalSessionFactoryObject itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfo = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute the given schema script on the given ADO.NET Connection. + + + Note that the default implementation will log unsuccessful statements + and continue to execute. Override the ExecuteSchemaStatement + method to treat failures differently. + + The connection to use. + The SQL statement to execute. + + + + Execute the given schema SQL on the given ADO.NET command. + + + Note that the default implementation will log unsuccessful statements + and continue to execute. Override this method to treat failures differently. + + + + + + + Subclasses can override this method to perform custom initialization + of the SessionFactory instance, creating it via the given Configuration + object that got prepared by this LocalSessionFactoryObject. + + +

The default implementation invokes Configuration's BuildSessionFactory. + A custom implementation could prepare the instance in a specific way, + or use a custom ISessionFactory subclass. +

+ + The ISessionFactory instance. + + + + Implementation of the PersistenceExceptionTranslator interface, + as autodetected by Spring's PersistenceExceptionTranslationPostProcessor. + Converts the exception if it is a HibernateException; + else returns null to indicate an unknown exception. + translate the given exception thrown by a persistence framework to a + corresponding exception from Spring's generic DataAccessException hierarchy, + if possible. + + The exception thrown. + + the corresponding DataAccessException (or null if the + exception could not be translated. + + + + + + Convert the given HibernateException to an appropriate exception from the + Spring's DAO Exception hierarchy. + Will automatically apply a specified IAdoExceptionTranslator to a + Hibernate ADOException, else rely on Hibernate's default translation. + + The Hibernate exception that occured. + A corresponding DataAccessException + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + ADOException that occured, wrapping underlying ADO.NET exception. + + the corresponding DataAccessException instance + + + + + Setting the Application Context determines were resources are loaded from + + + + + Gets or sets the to use for loading mapping assemblies etc. + + + + + Sets the assemblies to load that contain mapping files. + + The mapping assemblies. + + + + Sets the hibernate configuration files to load, i.e. hibernate.cfg.xml. + + + + + Sets the locations of Spring IResources that contain mapping + files. + + The location of mapping resources. + + + + Return the Configuration object used to build the SessionFactory. + Allows access to configuration metadata stored there (rarely needed). + + The hibernate configuration. + + + + Set NHibernate configuration properties, like "hibernate.dialect". + + The hibernate properties. + +

Can be used to override values in a NHibernate XML config file, + or to specify all necessary properties locally. +

+

Note: Do not specify a transaction provider here when using + Spring-driven transactions. It is also advisable to omit connection + provider settings and use a Spring-set IDbProvider instead. +

+ + + + + Get or set the DataSource to be used by the SessionFactory. + + The db provider. + + If set, this will override corresponding settings in Hibernate properties. + Note: If this is set, the Hibernate settings should not define + a connection string + (hibernate.connection.connection_string) to avoid meaningless double configuration. + + + + + + Gets or sets a value indicating whether to expose a transaction aware session factory. + + + true if want to expose transaction aware session factory; otherwise, false. + + + + + Set a NHibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + Will get applied to any new Session created by this factory. +

Such an interceptor can either be set at the SessionFactory level, i.e. on + LocalSessionFactoryObject, or at the Session level, i.e. on HibernateTemplate, + HibernateInterceptor, and HibernateTransactionManager. It's preferable to set + it on LocalSessionFactoryObject or HibernateTransactionManager to avoid repeated + configuration and guarantee consistent behavior in transactions.

+ + + + + + + Set a Hibernate NamingStrategy for the SessionFactory, determining the + physical column and table names given the info in the mapping document. + + + + + Specify the Hibernate type definitions to register with the SessionFactory, + as Spring IObjectDefinition instances. This is an alternative to specifying + <typedef> elements in Hibernate mapping files. +

Unfortunately, Hibernate itself does not define a complete object that + represents a type definition, hence the need for Spring's TypeDefinitionBean.

+ @see TypeDefinitionBean + @see org.hibernate.cfg.Mappings#addTypeDef(String, String, java.util.Properties) + + + + + Specify the NHibernate FilterDefinitions to register with the SessionFactory. + This is an alternative to specifying <filter-def> elements in + Hibernate mapping files. + + + Typically, the passed-in FilterDefinition objects will have been defined + as Spring FilterDefinitionFactoryBeans, probably as inner beans within the + LocalSessionFactoryObject definition. + + + + + + Specify the cache strategies for entities (persistent classes or named entities). + This configuration setting corresponds to the <class-cache> entry + in the "hibernate.cfg.xml" configuration format. +

For example: + 

+            <property name="entityCacheStrategies">
+              <props>
+                <prop key="MyCompany.Customer">read-write</prop>
+                <prop key="MyCompany.Product">read-only,myRegion</prop>
+              </props>
+            </property>
+

+ + + + + Specify the cache strategies for persistent collections (with specific roles). + This configuration setting corresponds to the <collection-cache> entry + in the "hibernate.cfg.xml" configuration format. +

For example: + 

+            <property name="CollectionCacheStrategies">
+              <props>
+                <prop key="MyCompany.Order.Items">read-write</prop>
+                <prop key="MyCompany.Product.Categories">read-only,myRegion</prop>
+              </props>
+            </property>
+

+ + + + + Specify the NHibernate event listeners to register, with listener types + as keys and listener objects as values. +

+ Instead of a single listener object, you can also pass in a list + or set of listeners objects as value. +

+ + listener objects as values + + See the NHibernate documentation for further details on listener types + and associated listener interfaces. + + + + + Set whether to execute a schema update after SessionFactory initialization. +

+ For details on how to make schema update scripts work, see the NHibernate + documentation, as this class leverages the same schema update script support + in as NHibernate's own SchemaUpdate tool. +

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Sets custom byte code provider implementation to be used. This corresponds to setting + the property before NHibernate session factory + configuration. + + + + + Return the type or subclass. + + The type created by this factory + + + + Returns true + + true + + + + The Spring for .NET-backed ByteCodeprovider for NHibernate + + Fabio Maulo + + + + Creates a new bytecode Provider instance using the specified object factory + + + + + + Retrieve the delegate for this provider + capable of generating reflection optimization components. + + The class to be reflected upon.All property getters to be accessed via reflection.All property setters to be accessed via reflection. + The reflection optimization delegate. + + + + The specific factory for this provider capable of + generating run-time proxies for lazy-loading purposes. + + + + + NHibernate's object instaciator. + + + For entities and its implementations. + + + + + Instanciator of NHibernate's collections default types. + + + + + + + Fabio Maulo + + + + + + + + + + + + + + + Implement this method to perform extra treatments before and after + the call to the supplied . + + +

+ Polite implementations would certainly like to invoke + . +

+ + + The method invocation that is being intercepted. + + + The result of the call to the + method of + the supplied ; this return value may + well have been intercepted by the interceptor. + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + + + Fabio Maulo + + + + + + + + + Creates an instance of the specified type. + + The type of object to create. + A reference to the created object. + + + + Creates an instance of the specified type. + + The type of object to create.true if a public or nonpublic default constructor can match; false if only a public default constructor can match. + A reference to the created object + + + + Creates an instance of the specified type using the constructor that best matches the specified parameters. + + The type of object to create.An array of constructor arguments. + A reference to the created object. + + + + A Spring for .NET backed implementation for creating + NHibernate proxies. + + + Erich Eichinger + + + + Creates a new proxy. + + The id value for the proxy to be generated. + The session to which the generated proxy will be associated. + The generated proxy. + Indicates problems generating requested proxy. + + + + Creates a Spring for .NET backed instance. + + Erich Eichinger + + + + Build a proxy factory specifically for handling runtime lazy loading. + + The lazy-load proxy factory. + + + + + + + + + + + + + + + + + + Fabio Maulo + + + + + + + + + + + + Perform instantiation of an instance of the underlying class. + + The new instance. + + + + + + + + + + Delegates to an implementation of ISessionFactory that can select among multiple instances based on + thread local storage. + + + + + Subclasses can override this method to perform custom initialization + of the SessionFactory instance, creating it via the given Configuration + object that got prepared by this LocalSessionFactoryObject. + + +

The default implementation invokes Configuration's BuildSessionFactory. + A custom implementation could prepare the instance in a specific way, + or use a custom ISessionFactory subclass. +

+ + The ISessionFactory instance. + + + + PostProcessConfiguration + + + + + + DelegatingSessionFactory class + + + + + PlatformTransactionManager implementation for a single Hibernate SessionFactory. + Binds a Hibernate Session from the specified factory to the thread, potentially + allowing for one thread Session per factory + + + SessionFactoryUtils and HibernateTemplate are aware of thread-bound Sessions and participate in such + transactions automatically. Using either of those is required for Hibernate + access code that needs to support this transaction handling mechanism. + + Supports custom isolation levels at the start of the transaction + , and timeouts that get applied as appropriate + Hibernate query timeouts. To support the latter, application code must either use + HibernateTemplate (which by default applies the timeouts) or call + SessionFactoryUtils.applyTransactionTimeout for each created + Hibernate Query object. + + Note that you can specify a Spring IDbProvider instance which if shared with + a corresponding instance of AdoTemplate will allow for mixing ADO.NET/NHibernate + operations within a single transaction. + + Mark Pollack (.NET) + + + + Just needed for entityInterceptorBeanName. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The session factory. + + + + Return the current transaction object. + + The current transaction object. + + If transaction support is not available. + + + In the case of lookup or system errors. + + + + + Check if the given transaction object indicates an existing, + i.e. already begun, transaction. + + + Transaction object returned by + . + + True if there is an existing transaction. + + In the case of system errors. + + + + + Begin a new transaction with the given transaction definition. + + + Transaction object returned by + . + + + instance, describing + propagation behavior, isolation level, timeout etc. + + + Does not have to care about applying the propagation behavior, + as this has already been handled by this abstract manager. + + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + + Transaction object returned by + . + + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + Transaction synchronization will already have been suspended. + + + If suspending is not supported by the transaction manager implementation. + + + in case of system errors. + + + + + Resume the resources of the current transaction. + + + Transaction object returned by + . + + + The object that holds suspended resources as returned by + . + + + Transaction synchronization will be resumed afterwards. + + + If suspending is not supported by the transaction manager implementation. + + + In the case of system errors. + + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + +

+ An implementation does not need to check the rollback-only flag. +

+ + + In the case of system errors. + + + + + Does the tx scope commit. + + The status. + + + + Perform an actual rollback on the given transaction. + + The status representation of the transaction. + + An implementation does not need to check the new transaction flag. + + + In the case of system errors. + + + + + Does the tx scope rollback. + + The status. + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + The status representation of the transaction. + + In the case of system errors. + + + + + Does the tx scope set rollback only. + + The status. + + + + Gets the ADO.NET IDbTransaction object from the NHibernate ITransaction object. + + The hibernate transaction. + The ADO.NET transaction. Null if could not get the transaction. Warning + messages will be logged in that case. + + + + Convert the given HibernateException to an appropriate exception from + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The HibernateException that occured. + The corresponding DataAccessException instance + + + + Convert the given ADOException to an appropriate exception from the + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The ADOException that occured, wrapping the underlying + ADO.NET thrown exception. + The translator to convert hibernate ADOExceptions. + + The corresponding DataAccessException instance + + + + + Cleanup resources after transaction completion. + + Transaction object returned by + . + + + This implemenation unbinds the SessionFactory and + DbProvider from thread local storage and closes the + ISession. + +

+ Called after + and + + execution on any outcome. +

+

+ Should not throw any exceptions but just issue warnings on errors. +

+ + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Gets or sets the db provider. + + The db provider. + + + + Gets or sets a Hibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + When getting, return the current Hibernate entity interceptor, or null if none. + + The entity interceptor. + + Resolves an entity interceptor object name via the object factory, + if necessary. + Will get applied to any new Session created by this transaction manager. + Such an interceptor can either be set at the SessionFactory level, + i.e. on LocalSessionFactoryObject, or at the Session level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. + + If object factory is null and need to get entity interceptor via object name. + + + + Sets the object name of a Hibernate entity interceptor that + allows to inspect and change property values before writing to and reading from the database. + + The name of the entity interceptor object. + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + + + + Gets or sets the ADO.NET exception translator for this transaction manager. + + + Applied to ADO.NET Exceptions (wrapped by Hibernate's ADOException) + + The ADO exception translator. + + + + Gets the default IAdoException translator, lazily creating it if nece + + The default IAdoException translator. + + + + Gets or sets the SessionFactory that this instance should manage transactions for. + + The session factory. + + + + Gets the resource factory that this transaction manager operates on, + For the HibenratePlatformTransactionManager this the SessionFactory + + The SessionFactory. + + + + Set whether to autodetect a ADO.NET connection used by the Hibernate SessionFactory, + if set via LocalSessionFactoryObject's DbProvider. Default is "true". + + + true if [autodetect data source]; otherwise, false. + + +

Can be turned off to deliberately ignore an available IDbProvider, + to not expose Hibernate transactions as ADO.NET transactions for that IDbProvider. +

+ + + + + The object factory just needs to be known for resolving entity interceptor + It does not need to be set for any other mode of operation. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + + + + Return whether the transaction is internally marked as rollback-only. + + + True of the transaction is marked as rollback-only. + + + + SimpleDelegatingSessionFactory class + + + + + Connection string config element name + + + + + public Constructor + + + + + + TargetSessionFactory + + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate31.dll b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate31.dll new file mode 100644 index 00000000..13703fe0 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate31.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate31.pdb b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate31.pdb new file mode 100644 index 00000000..2b5e34c8 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate31.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate31.xml b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate31.xml new file mode 100644 index 00000000..53b56aea --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate31.xml @@ -0,0 +1,6711 @@ + + + + Spring.Data.NHibernate31 + + + + + Holds the references and configuration settings for a instance. + References are resolved by looking up the given object names in the root obtained by . + + + + + Holds the references and configuration settings for a instance. + + + + + Default value for property. + + + + + Default value for property. + + + + + Initialize a new instance of with default values. + + + Calling this constructor from your derived class leaves and + uninitialized. See and for more. + + + + + Initialize a new instance of with the given sessionFactory + and default values for all other settings. + + + The instance to be used for obtaining instances. + + + Calling this constructor marks all properties initialized. + + + + + Initialize a new instance of with the given values and references. + + + The instance to be used for obtaining instances. + + + Specify the to be set on each session provided by the instance. + + + Set whether to use a single session for each request. See property for details. + + + Specify the flushmode to be applied on each session provided by the instance. + + + Calling this constructor marks all properties initialized. + + + + + Override this method to resolve an instance according to your chosen strategy. + + + + + Override this method to resolve an instance according to your chosen strategy. + + + + + Gets the configured instance to be used. + + + If the entity interceptor is not set by the constructor, this property calls + to obtain an instance. This allows derived classes to + override the behaviour of how to obtain the concrete instance. + + + + + Gets the configured instance to be used. + + + If this property is requested for the first time, is called. + This allows derived classes to override the behaviour of how to obtain the concrete instance. + + If the instance cannot be resolved. + + + + Set whether to use a single session for each request. Default is "true". + If set to false, each data access operation or transaction will use + its own session (like without Open Session in View). Each of those + sessions will be registered for deferred close, though, actually + processed at request completion. + + + + + Gets or Sets the flushmode to be applied on each newly created session. + + + This property defaults to to ensure that modifying objects outside the boundaries + of a transaction will not be persisted. It is recommended to not change this value but wrap any modifying operation + within a transaction. + + + + + The default session factory name to use when retrieving the Hibernate session factory from + the root context. + + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + The configuration section to read setting variables from. + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + The variable source to obtain settings from. + + + + Resolve the entityInterceptor by looking up + in the root application context. + + The resolved instance or + + + + Resolve the by looking up + in the root application context. + + The resolved instance or + + + + Convenient super class for Hibernate data access objects. + + + Requires a SessionFactory to be set, providing a HibernateTemplate + based on it to subclasses. Can alternatively be initialized directly with + a HibernateTemplate, to reuse the latter's settings such as the SessionFactory, + exception translator, flush mode, etc + + This base call is mainly intended for HibernateTemplate usage. + + This class will create its own HibernateTemplate if only a SessionFactory + is passed in. The "allowCreate" flag on that HibernateTemplate will be "true" + by default. A custom HibernateTemplate instance can be used through overriding + CreateHibernateTemplate. + + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Create a HibernateTemplate for the given ISessionFactory. + + + Only invoked if populating the DAO with a ISessionFactory reference! +

Can be overridden in subclasses to provide a HibernateTemplate instance + with different configuration, or a custom HibernateTemplate subclass. +

+ + + + + Check if the hibernate template property has been set. + + + + + Get a Hibernate Session, either from the current transaction or + a new one. The latter is only allowed if "allowCreate" is true. + + Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Either rely on a thread-bound + Session (via HibernateInterceptor), or use it in combination with + ReleaseSession. + + In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. + + + if a non-transactional Session should be created when no + transactional Session can be found for the current thread + + Hibernate session. + + If the Session couldn't be created + + + if no thread-bound Session found and allowCreate false + + + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Close the given Hibernate Session, created via this DAO's SessionFactory, + if it isn't bound to the thread. + + + Typically used in plain Hibernate code, in combination with the + Session property and ConvertHibernateAccessException. + + The session to close. + + + + Gets or sets the hibernate template. + + Set the HibernateTemplate for this DAO explicitly, + as an alternative to specifying a SessionFactory. + + The hibernate template. + + + + Gets or sets the session factory to be used by this DAO. + Will automatically create a HibernateTemplate for the given SessionFactory. + + The session factory. + + + + Get a Hibernate Session, either from the current transaction or a new one. + The latter is only allowed if the "allowCreate" setting of this object's + HibernateTemplate is true. + + +

Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Use it in combination with + ReleaseSession. +

+

In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. +

+ + The Hibernate session. + + + + Provide support for the open session in view pattern for lazily loaded hibernate objects + used in ASP.NET pages. + + jjx: http://forum.springframework.net/member.php?u=29 + Mark Pollack (.NET) + Erich Eichinger + Harald Radi + + + + Implementation of SessionScope that associates a single session within the using scope. + + + It is recommended to be used in the following type of scenario: + + using (new SessionScope()) + { + ... do multiple operation, possibly in multiple transactions. + } + + At the end of "using", the session is automatically closed. All transactions within the scope use the same session, + if you are using Spring's HibernateTemplate or using Spring's implementation of NHibernate 1.2's + ICurrentSessionContext interface. + + + It is assumed that the session factory object name is called "SessionFactory". In case that you named the object + in different way you can specify your can specify it in the application settings using the key + Spring.Data.NHibernate.Support.SessionScope.SessionFactoryObjectName. Values for EntityInterceptorObjectName + and SingleSessionMode can be specified similarly. + + + Note: + The session is managed on a per thread basis on the thread that opens the scope instance. This means that you must + never pass a reference to a instance over to another thread! + + + Robert M. (.NET) + Harald Radi (.NET) + + + + The logging instance. + + + + + Initializes a new instance of the class in single session mode, + associating a session with the thread. The session is opened lazily on demand. + + + + + Initializes a new instance of the class. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The name of the configuration section to read configuration settings from. + See for more info. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The name of the configuration section to read configuration settings from. + See for more info. + + The type, who's full name is used for prefixing appSetting keys + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The instance to be used for obtaining instances. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The instance to be used for obtaining instances. + + + Specify the to be set on each session provided by this instance. + + + Set whether to use a single session for each request. See property for details. + + + Specify the flushmode to be applied on each session provided by this instance. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + An instance holding the scope configuration + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Sets a flag, whether this scope is in "open" state on the current logical thread. + + + + + Gets/Sets a flag, whether this scope manages it's own session for the current logical thread or not. + + false if session is managed by this module. false otherwise + + + + Call Close(), + + + + + Opens a new session or participates in an existing session and + registers with spring's . + + + + + Close the current view's session and unregisters + from spring's . + + + + + Set whether to use a single session for each request. Default is "true". + If set to false, each data access operation or transaction will use + its own session (like without Open Session in View). Each of those + sessions will be registered for deferred close, though, actually + processed at request completion. + + + + + Gets the flushmode to be applied on each newly created session. + + + This property defaults to to ensure that modifying objects outside the boundaries + of a transaction will not be persisted. It is recommended to not change this value but wrap any modifying operation + within a transaction. + + + + + Get or set the configured SessionFactory + + + + + Get or set the configured EntityInterceptor + + + + + Gets a flag, whether this scope is in "open" state on the current logical thread. + + + + + Gets a flag, whether this scope manages it's own session for the current logical thread or not. + + + + + This sessionHolder creates a default session only if it is needed. + + + Although a NHibernateSession deferes creation of db-connections until they are really + needed, instantiation a session is imho still more expensive than this LazySessionHolder. (EE) + + + + + Session holder, wrapping a NHibernate ISession and a NHibernate Transaction. + HibernateTransactionManager binds instances of this class + to the thread, for a given ISessionFactory. + + + Note: This is an SPI class, not intended to be used by applications. + + Mark Pollack (.NET) + + + + May be used by derived classes to create an empty SessionHolder. + + + When using this ctor in your derived class, you MUST override ! + + + + + Initializes a new instance of the class. + + The session. + + + + Initializes a new instance of the class. + + The key to store the session under. + The hibernate session. + + + + May be overridden in a derived class to e.g. lazily create a session + + + + + Gets the session given key identifier + + The key. + A hibernate session + + + + Gets the session given the key and removes the session from + the dictionary storage. + + The key. + A hibernate session + + + + Adds the session to the dictionary storage using the default key. + + The hibernate session. + + + + Adds the session to the dictionary storage using the supplied key. + + The key. + The hibernate session. + + + + Removes the session from the dictionary storage for the given key. + + The key. + The session that was previously contained in the + dictionary storage. + + + + Determines whether the holder the specified session. + + The session. + + true if the holder contains the specified session; otherwise, false. + + + + + Clear the transaction state of this resource holder. + + + + + Gets the session using the default key + + The hibernate session. + + + + Gets the first session based on iteration over + the IDictionary storage. + + Any hibernate session. + + + + Gets a value indicating whether dictionary of + hibernate sessions is empty. + + + true if this session holder is empty; otherwise, false. + + + + + Gets a value indicating whether this SessionHolder + does not hold non default session. + + + true if does not hold non default session; otherwise, false. + + + + + Gets or sets the hibernate transaction. + + The transaction. + + + + Gets or sets the ADO.NET Connection used to create the session. + + The ADO.NET connection. + + + + Gets or sets the previous flush mode. + + The previous flush mode. + + + + Gets a value indicating whether the PreviousFlushMode property + was set. + + + true if assigned PreviousFlushMode property; otherwise, false. + + + + + Gets the validated session. + + The validated session. + + + + Initialize a new instance. + + + + + Create a new session on demand + + + + + Ensure session is closed (if any) and remove circular references to avoid memory leaks! + + + + + Initializes a new instance of the class. Creates a SessionScope, + but does not yet associate a session with a thread, that is left to the lifecycle of the request. + + + + + Register context handler and look up SessionFactoryObjectName under the application configuration key, + Spring.Data.NHibernate.Support.OpenSessionInViewModule.SessionFactoryObjectName if not using the default value + (i.e. sessionFactory) and look up the SingleSession setting under the application configuration key, + Spring.Data.NHibernate.Support.OpenSessionInViewModule.SingleSession if not using the default value of true. + + The standard HTTP application context + + + + A do nothing dispose method. + + + + + Hibernate-specific subclass of UncategorizedDataAccessException, + for ADO.NET exceptions that Hibernate rethrew and could not be + mapped into the DAO exception heirarchy. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception from the underlying data access API - ADO.NET + + + + + Creates a new instance of the HibernateSystemException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Hibernate-specific subclass of InvalidDataAccessResourceUsageException, + thrown on invalid HQL query syntax. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Initializes a new instance of the class. + + The ex. + + + + Creates a new instance of the HibernateQueryException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Gets the query string that was invalid. + + The query string that was invalid. + + + + Hibernate-specific subclass of UncategorizedDataAccessException, + for Hibernate system errors that do not match any concrete + Spring.Dao exceptions. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message. + + + + Creates a new instance of the HibernateSystemException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Initializes a new instance of the class. + + The cause. + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Helper class that simplifies NHibernate data access code + + +

Typically used to implement data access or business logic services that + use NHibernate within their implementation but are Hibernate-agnostic in their + interface. The latter or code calling the latter only have to deal with + domain objects.

+ +

The central method is Execute supporting Hibernate access code + implementing the HibernateCallback interface. It provides NHibernate Session + handling such that neither the IHibernateCallback implementation nor the calling + code needs to explicitly care about retrieving/closing NHibernate Sessions, + or handling Session lifecycle exceptions. For typical single step actions, + there are various convenience methods (Find, Load, SaveOrUpdate, Delete). +

+ +

Can be used within a service implementation via direct instantiation + with a ISessionFactory reference, or get prepared in an application context + and given to services as an object reference. Note: The ISessionFactory should + always be configured as an object in the application context, in the first case + given to the service directly, in the second case to the prepared template. +

+ +

This class can be considered as direct alternative to working with the raw + Hibernate Session API (through SessionFactoryUtils.Session). +

+ +

LocalSessionFactoryObject is the preferred way of obtaining a reference + to a specific NHibernate ISessionFactory. +

+ + Mark Pollack (.NET) + + + + Base class for HibernateTemplate defining common + properties like SessionFactory and flushing behavior. + + +

Not intended to be used directly. See HibernateTemplate. +

+ + Mark Pollack (.NET) + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Apply the flush mode that's been specified for this accessor + to the given Session. + + The current Hibernate Session. + if set to true + if executing within an existing transaction. + + the previous flush mode to restore after the operation, + or null if none + + + + + Flush the given Hibernate Session if necessary. + + The current Hibernate Session. + if set to true + if executing within an existing transaction. + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + ADOException that occured, wrapping underlying ADO.NET exception. + + the corresponding DataAccessException instance + + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + + + Note that a direct SQLException can just occur when callback code + performs direct ADO.NET access via ISession.Connection(). + + + The ADO.NET exception. + The corresponding DataAccessException instance + + + + Prepare the given IQuery object, applying cache settings and/or + a transaction timeout. + + The query object to prepare. + + + + Apply the given name parameter to the given Query object. + + The query object. + Name of the parameter + The value of the parameter + The NHibernate type of the parameter (or null if none specified) + + + + Prepare the given Criteria object, applying cache settings and/or + a transaction timeout. + + + Note that for NHibernate 1.2 this only works if the + implementation is of the type CriteriaImpl, which should generally + be the case. The SetFetchSize method is not available on the + ICriteria interface + + This is a no-op for NHibernate 1.0.x since + the SetFetchSize method is not on the ICriteria interface and + the implementation class is has internal access. + + To remove the method completely for Spring's NHibernate 1.0 + support while reusing code for NHibernate 1.2 would not be + possible. So now this ineffectual operation is left in tact for + NHibernate 1.0.2 support. + + The criteria object to prepare + + + + Ensure SessionFactory is not null + + If SessionFactory property is null. + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Set the object factory instance. + + The object factory instance. + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Gets a Session for use by this template. + + The session. + + - Returns a new Session in case of "alwaysUseNewSession" (using the same ADO.NET connection as a transaction Session, if applicable) + - a pre-bound Session in case of "AllowCreate" is set to false (not the default) + - or a pre-bound Session or new Session if no transactional or other pre-bound Session exists. + + + + + Helper class to determine if the FlushMode enumeration + was changed from its default value + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The flush mode. + + + + Gets or sets a value indicating whether the FlushMode + property was set.. + + true if FlushMode was set; otherwise, false. + + + + Gets or sets the FlushMode. + + The FlushMode. + + + + Interface that specifies a basic set of Hibernate operations. + + + Implemented by HibernateTemplate. Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + + Mark Pollack (.NET) + + + + Interface that specifies a set of Hibernate operations that + are common across versions of Hibernate. + + + Base interface for generic and non generic IHibernateOperations interfaces + Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + Mark Pollack (.NET) + + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + In case of Hibernate errors + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + Tthe persistent instance to delete. + The lock mode to obtain. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Delete all given persistent instances. + + The persistent instances to delete. + + This can be combined with any of the find methods to delete by query + in two lines of code, similar to Session's delete by query methods. + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the specified action assuming that the result object is a List. + + + This is a convenience method for executing Hibernate find calls or + queries within an action. + + The calback object that specifies the Hibernate action. + A IList returned by the action, or null + + In case of Hibernate errors + + + + Execute a query for persistent instances. + + a query expressed in Hibernate's query language + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + a query expressed in Hibernate's query language + the value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + a query expressed in Hibernate's query language + the values of the parameters + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + a List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + + a persistent type. + An identifier of the persistent instance. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + A persistent class. + An identifier of the persistent instance. + The lock mode. + the persistent instance, or null if not found + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + Type of the entity. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + Type of the entity. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + Type of the entity. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Save or update all given persistent instances, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instances to save or update + (to be associated with the Hibernate Session)he entities. + In case of Hibernate errors + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The default for creating a new non-transactional + session when no transactional Session can be found for the current thread + is set to true. + The session factory to create sessions. + + + + Initializes a new instance of the class. + + The session factory to create sessions. + if set to true allow creation + of a new non-transactional when no transactional Session can be found + for the current thread. + + + + Delegate function that clears the session. + + The hibernate session. + null + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + + The type. + An identifier of the persistent instance. + The persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The type. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + Type of the entity. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + Type of the entity. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + Type of the entity. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update all given persistent instances, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instances to save or update + (to be associated with the Hibernate Session)he entities. + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + Tthe persistent instance to delete. + The lock mode to obtain. + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + If length for argument values and types are not equal. + + + + Delete all given persistent instances. + + The persistent instances to delete. + + This can be combined with any of the find methods to delete by query + in two lines of code, similar to Session's delete by query methods. + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + + + + Execute the action specified by the given action object within a Session. + + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the specified action assuming that the result object is a List. + + + This is a convenience method for executing Hibernate find calls or + queries within an action. + + The calback object that specifies the Hibernate action. + A IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + + + + Execute a query for persistent instances. + + a query expressed in Hibernate's query language + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + a query expressed in Hibernate's query language + the value of the parameter + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + a query expressed in Hibernate's query language + the values of the parameters + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Create a close-suppressing proxy for the given Hibernate Session. + The proxy also prepares returned Query and Criteria objects. + + The session. + The session proxy. + + + + Check whether write operations are allowed on the given Session. + + + Default implementation throws an InvalidDataAccessApiUsageException + in case of FlushMode.Never. Can be overridden in subclasses. + + The current Hibernate session. + If write operation is attempted in read-only mode + + + + + Compares if the flush mode enumerations, Spring's + TemplateFlushMode and NHibernates FlushMode have equal + settings. + + The template flush mode. + The NHibernate flush mode. + + Returns true if both are Never, Auto, or Commit, false + otherwise. + + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + If object factory is not set and need to retrieve entity interceptor by name. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets whether to check that the Hibernate Session is not in read-only mode + in case of write operations (save/update/delete). + + + true if check that the Hibernate Session is not in read-only mode + in case of write operations; otherwise, false. + + + Default is "true", for fail-fast behavior when attempting write operations + within a read-only transaction. Turn this off to allow save/update/delete + on a Session with flush mode NEVER. + + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Set the object factory instance. + + The object factory instance + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the proxy factory. + + This may be useful to set if you create many instances of + HibernateTemplate and/or HibernateDaoSupport. This allows the same + ProxyFactory implementation to be used thereby limiting the + number of dynamic proxy types created in the temporary assembly, which + are never garbage collected due to .NET runtime semantics. + + The proxy factory. + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Callback interface for NHibernate code. + + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + Mark Pollack (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + A result object, or null if none. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + PlatformTransactionManager implementation for a single Hibernate SessionFactory. + Binds a Hibernate Session from the specified factory to the thread, potentially + allowing for one thread Session per factory + + + SessionFactoryUtils and HibernateTemplate are aware of thread-bound Sessions and participate in such + transactions automatically. Using either of those is required for Hibernate + access code that needs to support this transaction handling mechanism. + + Supports custom isolation levels at the start of the transaction + , and timeouts that get applied as appropriate + Hibernate query timeouts. To support the latter, application code must either use + HibernateTemplate (which by default applies the timeouts) or call + SessionFactoryUtils.applyTransactionTimeout for each created + Hibernate Query object. + + Note that you can specify a Spring IDbProvider instance which if shared with + a corresponding instance of AdoTemplate will allow for mixing ADO.NET/NHibernate + operations within a single transaction. + + Mark Pollack (.NET) + + + + Just needed for entityInterceptorBeanName. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The session factory. + + + + Return the current transaction object. + + The current transaction object. + + If transaction support is not available. + + + In the case of lookup or system errors. + + + + + Check if the given transaction object indicates an existing, + i.e. already begun, transaction. + + + Transaction object returned by + . + + True if there is an existing transaction. + + In the case of system errors. + + + + + Begin a new transaction with the given transaction definition. + + + Transaction object returned by + . + + + instance, describing + propagation behavior, isolation level, timeout etc. + + + Does not have to care about applying the propagation behavior, + as this has already been handled by this abstract manager. + + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + + Transaction object returned by + . + + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + Transaction synchronization will already have been suspended. + + + If suspending is not supported by the transaction manager implementation. + + + in case of system errors. + + + + + Resume the resources of the current transaction. + + + Transaction object returned by + . + + + The object that holds suspended resources as returned by + . + + + Transaction synchronization will be resumed afterwards. + + + If suspending is not supported by the transaction manager implementation. + + + In the case of system errors. + + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + +

+ An implementation does not need to check the rollback-only flag. +

+ + + In the case of system errors. + + + + + Perform an actual rollback on the given transaction. + + The status representation of the transaction. + + An implementation does not need to check the new transaction flag. + + + In the case of system errors. + + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + The status representation of the transaction. + + In the case of system errors. + + + + + Gets the ADO.NET IDbTransaction object from the NHibernate ITransaction object. + + The hibernate transaction. + The ADO.NET transaction. Null if could not get the transaction. Warning + messages will be logged in that case. + + + + Convert the given HibernateException to an appropriate exception from + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The HibernateException that occured. + The corresponding DataAccessException instance + + + + Convert the given ADOException to an appropriate exception from the + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The ADOException that occured, wrapping the underlying + ADO.NET thrown exception. + The translator to convert hibernate ADOExceptions. + + The corresponding DataAccessException instance + + + + + Cleanup resources after transaction completion. + + Transaction object returned by + . + + + This implemenation unbinds the SessionFactory and + DbProvider from thread local storage and closes the + ISession. + +

+ Called after + and + + execution on any outcome. +

+

+ Should not throw any exceptions but just issue warnings on errors. +

+ + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Gets or sets the db provider. + + The db provider. + + + + Gets or sets a Hibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + When getting, return the current Hibernate entity interceptor, or null if none. + + The entity interceptor. + + Resolves an entity interceptor object name via the object factory, + if necessary. + Will get applied to any new Session created by this transaction manager. + Such an interceptor can either be set at the SessionFactory level, + i.e. on LocalSessionFactoryObject, or at the Session level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. + + If object factory is null and need to get entity interceptor via object name. + + + + Sets the object name of a Hibernate entity interceptor that + allows to inspect and change property values before writing to and reading from the database. + + The name of the entity interceptor object. + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + + + + Gets or sets the ADO.NET exception translator for this transaction manager. + + + Applied to ADO.NET Exceptions (wrapped by Hibernate's ADOException) + + The ADO exception translator. + + + + Gets the default IAdoException translator, lazily creating it if nece + + The default IAdoException translator. + + + + Gets or sets the SessionFactory that this instance should manage transactions for. + + The session factory. + + + + Gets the resource factory that this transaction manager operates on, + For the HibenratePlatformTransactionManager this the SessionFactory + + The SessionFactory. + + + + Set whether to autodetect a ADO.NET connection used by the Hibernate SessionFactory, + if set via LocalSessionFactoryObject's DbProvider. Default is "true". + + + true if [autodetect data source]; otherwise, false. + + +

Can be turned off to deliberately ignore an available IDbProvider, + to not expose Hibernate transactions as ADO.NET transactions for that IDbProvider. +

+ + + + + The object factory just needs to be known for resolving entity interceptor + It does not need to be set for any other mode of operation. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + + + + Return whether the transaction is internally marked as rollback-only. + + + True of the transaction is marked as rollback-only. + + + + Enumeration for the various Hibernate flush modes. + + Mark Pollack (.NET) + + + Never flush is a good strategy for read-only units of work. + + + Hibernate will not track and look for changes in this case, + avoiding any overhead of modification detection. +

In case of an existing ISession, TemplateFlushMode.Never will turn + the hibenrate flush mode + to FlushMode.Never for the scope of the current operation, resetting the previous + flush mode afterwards. +

+ + + + Automatic flushing is the default mode for a Hibernate Session. + + + A session will get flushed on transaction commit, and on certain find + operations that might involve already modified instances, but not + after each unit of work like with eager flushing. +

In case of an existing Session, TemplateFlushMode.Auto + will participate in the existing flush mode, not modifying + it for the current operation. + This in particular means that this setting will not modify an existing + hibernate flush mode FlushMode.Never, in contrast to TemplateFlushMode.Eager. +

+ + + + + Eager flushing leads to immediate synchronization with the database, + even if in a transaction. + + + This causes inconsistencies to show up and throw + a respective exception immediately, and ADO access code that participates + in the same transaction will see the changes as the database is already + aware of them then. But the drawbacks are: +
    +
  • additional communication roundtrips with the database, instead of a + single batch at transaction commit;
    • +
  • the fact that an actual database rollback is needed if the Hibernate + transaction rolls back (due to already submitted SQL statements).
    • +
+

In case of an existing Session, TemplateFlushMode.Eager + will turn the NHibernate flush mode + to FlushMode.Auto for the scope of the current operation and issue a flush at the + end, resetting the previous flush mode afterwards. +

+ + + + + Flushing at commit only is intended for units of work where no + intermediate flushing is desired, not even for find operations + that might involve already modified instances. + + +

In case of an existing Session, TemplateFlushMode.Commit + will turn the NHibernate flush mode + to FlushMode.Commit for the scope of the current operation, resetting the previous + flush mode afterwards. The only exception is an existing flush mode + FlushMode.Never, which will not be modified through this setting. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning an IList of result objects created within the callback. + Note that there's special support for single step actions: + see HibernateTemplate.find etc. +

+ + The type of result object + Sree Nivask (.NET) + + + + Convenient super class for Hibernate data access objects. + + + Requires a SessionFactory to be set, providing a HibernateTemplate + based on it to subclasses. Can alternatively be initialized directly with + a HibernateTemplate, to reuse the latter's settings such as the SessionFactory, + exception translator, flush mode, etc + + This base call is mainly intended for HibernateTemplate usage. + + This class will create its own HibernateTemplate if only a SessionFactory + is passed in. The "allowCreate" flag on that HibernateTemplate will be "true" + by default. A custom HibernateTemplate instance can be used through overriding + CreateHibernateTemplate. + + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Create a HibernateTemplate for the given ISessionFactory. + + + Only invoked if populating the DAO with a ISessionFactory reference! +

Can be overridden in subclasses to provide a HibernateTemplate instance + with different configuration, or a custom HibernateTemplate subclass. +

+ + The new HibernateTemplate instance + + + + Check if the hibernate template property has been set. + + If HibernateTemplate property is null. + + + + Get a Hibernate Session, either from the current transaction or + a new one. The latter is only allowed if "allowCreate" is true. + + Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Either rely on a thread-bound + Session (via HibernateInterceptor), or use it in combination with + ReleaseSession. + + In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. + + + if a non-transactional Session should be created when no + transactional Session can be found for the current thread + + Hibernate session. + + If the Session couldn't be created + + + if no thread-bound Session found and allowCreate false + + + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Close the given Hibernate Session, created via this DAO's SessionFactory, + if it isn't bound to the thread. + + + Typically used in plain Hibernate code, in combination with the + Session property and ConvertHibernateAccessException. + + The session to close. + + + + Gets or sets the hibernate template. + + Set the HibernateTemplate for this DAO explicitly, + as an alternative to specifying a SessionFactory. + + The hibernate template. + + + + Gets or sets the session factory to be used by this DAO. + Will automatically create a HibernateTemplate for the given SessionFactory. + + The session factory. + + + + Get a Hibernate Session, either from the current transaction or a new one. + The latter is only allowed if the "allowCreate" setting of this object's + HibernateTemplate is true. + + +

Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Use it in combination with + ReleaseSession. +

+

In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. +

+ + The Hibernate session. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning the result object created within the callback. + Note that there's special support for single step actions: + see HibernateTemplate.find etc. +

+ + The type of result object + Sree Nivask (.NET) + + + + Generic version of the Helper class that simplifies NHibernate data access code + + +

Typically used to implement data access or business logic services that + use NHibernate within their implementation but are Hibernate-agnostic in their + interface. The latter or code calling the latter only have to deal with + domain objects.

+ +

The central method is Execute() supporting Hibernate access code which + implements the HibernateCallback interface. It provides NHibernate Session + handling such that neither the IHibernateCallback implementation nor the calling + code needs to explicitly care about retrieving/closing NHibernate Sessions, + or handling Session lifecycle exceptions. For typical single step actions, + there are various convenience methods (Find, Load, SaveOrUpdate, Delete). +

+ +

Can be used within a service implementation via direct instantiation + with a ISessionFactory reference, or get prepared in an application context + and given to services as an object reference. Note: The ISessionFactory should + always be configured as an object in the application context, in the first case + given to the service directly, in the second case to the prepared template. +

+ +

This class can be considered as a direct alternative to working with the raw + Hibernate Session API (through SessionFactoryUtils.Session). +

+ +

LocalSessionFactoryObject is the preferred way of obtaining a reference + to a specific NHibernate ISessionFactory. +

+ + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Interface that specifies a basic set of Hibernate operations. + + + Implemented by HibernateTemplate. Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Return the persistent instance of the given entity type + with the given identifier, or if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The id of the object to get. + the persistent instance, or if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + The object type to load. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + The object type to load. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + The object type to load. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances. + + The object type to find. + a query expressed in Hibernate's query language + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the value of the parameter + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + The object type to find. + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the values of the parameters + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lenths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type retrieved. + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type retrieved. + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type to find. + The delegate callback object that specifies the Hibernate action. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type to find. + The FindHibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type to find. + The callback object that specifies the Hibernate action. + + A generic IList returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + + + + Execute the action specified by the given action object within a Session assuming that an IList is returned. + + The object type to find. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + an IList returned by the action, or null + + In case of Hibernate errors + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + Allows creation of a new non-transactional session when no + transactional Session can be found for the current thread + The session factory to create sessions. + + + + Initializes a new instance of the class. + + The session factory to create sessions. + if set to true allow creation + of a new non-transactional session when no transactional Session can be found + for the current thread. + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + Tthe persistent instance to delete. + The lock mode to obtain. + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The id of the object to get. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + The object type to load. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + The object type to load. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + The object type to load. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances. + + The object type to find. + a query expressed in Hibernate's query language + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the value of the parameter + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + The object type to find. + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the values of the parameters + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type retrieved. + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type retrieved. + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session assuming that an IList is returned. + + The object type to find. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + an IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type to find. + The delegate callback object that specifies the Hibernate action. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type to find. + The FindHibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type to find. + The callback object that specifies the Hibernate action. + + A generic IList returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Set the object factory instance. + + The object factory instance + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Gets the classic hibernate template for access to non-generic methods. + + The classic hibernate template. + + + + Gets or sets the proxy factory. + + This may be useful to set if you create many instances of + HibernateTemplate and/or HibernateDaoSupport. This allows the same + ProxyFactory implementation to be used thereby limiting the + number of dynamic proxy types created in the temporary assembly, which + are never garbage collected due to .NET runtime semantics. + + The proxy factory. + + + + Callback interface (Generic version) for NHibernate code. + + The type of result object + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + + Sree Nivask (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + A result object. + The active Hibernate session + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Callback interface (Generic version) for NHibernate code that + returns a List of objects. + + The type of result object + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + Collection result object. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Helper class featuring methods for Hibernate Session handling, + allowing for reuse of Hibernate Session instances within transactions. + Also provides support for exception translation. + + Mark Pollack (.NET) + + + + The instance for this class. + + + + + The ordering value for synchronizaiton this session resources. + Set to be lower than ADO.NET synchronization. + + + + + Initializes a new instance of the class. + + + + + Get a new Hibernate Session from the given SessionFactory. + Will return a new Session even if there already is a pre-bound + Session for the given SessionFactory. + + + Within a transaction, this method will create a new Session + that shares the transaction's ADO.NET Connection. More specifically, + it will use the same ADO.NET Connection as the pre-bound Hibernate Session. + + The session factory to create the session with. + The Hibernate entity interceptor, or null if none. + The new session. + If could not open Hibernate session + + + + Get a Hibernate Session for the given SessionFactory. Is aware of and will + return any existing corresponding Session bound to the current thread, for + example when using HibernateTransactionManager. Will always create a new + Session otherwise. + + + Supports setting a Session-level Hibernate entity interceptor that allows + to inspect and change property values before writing to and reading from the + database. Such an interceptor can also be set at the SessionFactory level + (i.e. on LocalSessionFactoryObject), on HibernateTransactionManager, or on + HibernateInterceptor/HibernateTemplate. + + The session factory to create the + session with. + Hibernate entity interceptor, or null if none. + AdoExceptionTranslator to use for flushing the + Session on transaction synchronization (can be null; only used when actually + registering a transaction synchronization). + The Hibernate Session + + If the session couldn't be created. + + + If no thread-bound Session found and allowCreate is false. + + + + + Get a Hibernate Session for the given SessionFactory. Is aware of and will + return any existing corresponding Session bound to the current thread, for + example when using . Will create a new Session + otherwise, if allowCreate is true. + + The session factory to create the session with. + if set to true create a non-transactional Session when no + transactional Session can be found for the current thread. + The hibernate session + + If the session couldn't be created. + + + If no thread-bound Session found and allowCreate is false. + + + + + Get a Hibernate Session for the given SessionFactory. + + Is aware of and will return any existing corresponding + Session bound to the current thread, for example whenusing + . Will create a new + Session otherwise, if "allowCreate" is true. +

Throws the orginal HibernateException, in contrast to + . +

+ The session factory. + if set to true [allow create]. + The Hibernate Session + + if the Session couldn't be created + + + If no thread-bound Session found and allowCreate is false. + + + + + Open a new Session from the factory. + + The session factory to create the session with. + Hibernate entity interceptor, or null if none. + the newly opened session + + + + Perform the actual closing of the Hibernate Session + catching and logging any cleanup exceptions thrown. + + The hibernate session to close + + + + Return whether the given Hibernate Session is transactional, that is, + bound to the current thread by Spring's transaction facilities. + + The hibernate session to check + The session factory that the session + was created with, can be null. + + true if the session transactional; otherwise, false. + + + + + Converts a Hibernate ADOException to a Spring DataAccessExcption, extracting the underlying error code from + ADO.NET. Will extract the ADOException Message and SqlString properties and pass them to the translate method + of the provided IAdoExceptionTranslator. + + The IAdoExceptionTranslator, may be a user provided implementation as configured on + HibernateTemplate. + + The ADOException throw + The translated DataAccessException or UncategorizedAdoException in case of an error in translation + itself. + + + + Convert the given HibernateException to an appropriate exception from the + Spring.Dao hierarchy. Note that it is advisable to + handle AdoException specifically by using a AdoExceptionTranslator for the + underlying ADO.NET exception. + + The Hibernate exception that occured. + DataAccessException instance + + + + Close the given Session, created via the given factory, + if it is not managed externally (i.e. not bound to the thread). + + The hibernate session to close + The hibernate SessionFactory that + the session was created with. + + + + Close the given Session or register it for deferred close. + + The session. + The session factory. + + + + Initialize deferred close for the current thread and the given SessionFactory. + Sessions will not be actually closed on close calls then, but rather at a + processDeferredClose call at a finishing point (like request completion). + + The session factory. + + + + Return if deferred close is active for the current thread + and the given SessionFactory. + The session factory. + + true if [is deferred close active] [the specified session factory]; otherwise, false. + + If SessionFactory argument is null. + + + + Process Sessions that have been registered for deferred close + for the given SessionFactory. + + The session factory. + If there is no session factory associated with the thread. + + + + Applies the current transaction timeout, if any, to the given + criteria object + + The Hibernate Criteria object. + Hibernate SessionFactory that the Criteria was created for + (can be null). + If criteria argument is null. + + + + Applies the current transaction timeout, if any, to the given + Hibenrate query object. + + The Hibernate Query object. + Hibernate SessionFactory that the Query was created for + (can be null). + If query argument is null. + + + + Gets the Spring IDbProvider given the ISessionFactory. + + The matching is performed by comparing the assembly qualified + name string of the hibernate Driver.ConnectionType to those in + the DbProviderFactory definitions. No connections are created + in performing this comparison. + The session factory. + The corresponding IDbProvider, null if no mapping was found. + If DbProviderFactory's ApplicaitonContext is not + an instance of IConfigurableApplicaitonContext. + + + + Create a IAdoExceptionTranslator from the given SessionFactory. + + If a corresponding IDbProvider is found, a ErrorcodeExceptionTranslator + for the IDbProvider is created. Otherwise, a FallbackException is created. + The session factory to create the translator for + An IAdoExceptionTranslator + + + + Implementation of NHibernates 1.2's ICurrentSessionContext interface + that delegates to Spring's SessionFactoryUtils for providing a + Spirng-managed current Session. + + Used by Spring's LocalSessionFactoryBean if told to expose + a transaction-aware SessionFactory. +

This ICurrentSessionContext implementation can also be specified in + custom ISessionFactory setup through the + "hibernate.current_session_context_class" property, with the fully + qualified name of this class as value.

 + Juergen Hoeller + Mark Pollack (.NET) + + + + + Initializes a new instance of the class + + The NHibernate session factory. + + + + Retrieve the Spring-managed Session for the current thread. + + Current session associated with the thread + On errors retrieving thread bound session. + + + + NHibnerations actions taken during the transaction lifecycle. + + Mark Pollack (.NET) + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Suspend this synchronization. + + +

+ Unbind Hibernate resources (SessionHolder) from + + if managing any. +

+ + + + + Resume this synchronization. + + +

+ Rebind Hibernate resources from + + if managing any. +

+ + + + + Invoked before transaction commit (before + ) + + + If the transaction is defined as a read-only transaction. + + +

+ Can flush transactional sessions to the database. +

+

+ Note that exceptions will get propagated to the commit caller and + cause a rollback of the transaction. +

+ + + + + Invoked before transaction commit (before + ) + Can e.g. flush transactional O/R Mapping sessions to the database + + + + This callback does not mean that the transaction will actually be + commited. A rollback decision can still occur after this method + has been called. This callback is rather meant to perform work + that's only relevant if a commit still has a chance + to happen, such as flushing SQL statements to the database. + + + Note that exceptions will get propagated to the commit caller and cause a + rollback of the transaction. + + (note: do not throw TransactionException subclasses here!) + + + + + + Invoked after transaction commit/rollback. + + + Status according to + + + Can e.g. perform resource cleanup, in this case after transaction completion. +

+ Note that exceptions will get propagated to the commit or rollback + caller, although they will not influence the outcome of the transaction. +

+ + + + + Return the order value of this object, where a higher value means greater in + terms of sorting. + + +

+ Normally starting with 0 or 1, with indicating + greatest. Same order values will result in arbitrary positions for the affected + objects. +

+

+ Higher value can be interpreted as lower priority, consequently the first object + has highest priority. +

+ + The order value. + + + + Convenient FactoryObject for defining Hibernate FilterDefinitions. + Exposes a corresponding Hibernate FilterDefinition object. + + + +

+ Typically defined as an inner object within a LocalSessionFactoryObject + definition, as the list element for the "filterDefinitions" object property. + For example: +

+ + 
+            <objectn id="sessionFactory" type="Spring.Data.NHibernate.LocalSessionFactoryObject, Spring.Data.NHibernate">
+              ...
+              <property name="FilterDefinitions">
+               <list>
+                  <object type="Spring.Data.NHibernate.FilterDefinitionFactoryObject, Spring.Data.NHibernate">
+                    <property name="FilterName" value="myFilter"/>
+                    <property name="ParameterTypes">
+                      <props>
+                        <prop key="MyParam">string</prop>
+                        <prop key="MyOtherParam">long</prop>
+                      </props>
+                    </property>
+                  </object>
+                </list>
+              </property>
+              ...
+            </object>
+
+

+ Alternatively, specify an object id (or name) attribute for the inner object, + instead of the "FilterName" property. +

+ + Juergen Hoeller + Marko Lahma (.NET) + + + $Id: FilterDefiniitionFactoryObject.cs,v 1.1 2008/04/07 20:12:53 lahma Exp $ + + + + Initializes the filter definitions. + + + + + Returns the singleton filter definition. + + + + + + Set the name of the filter. + + + + + Set the parameter types for the filter, + with parameter names as keys and type names as values. + + + + + + Specify a default filter condition for the filter, if any. + + + + + If no explicit filter name has been specified, the object name of + the FilterDefinitionFactoryObject will be used. + + + + + + Returns the type of the object this factory produces. + + + + + Returns whether this factory produces singletons, always true. + + + + + Hibernate-specific subclass of ObjectRetrievalFailureException. + + + Converts Hibernate's UnresolvableObjectException, ObjectNotFoundException, + ObjectDeletedException, and WrongClassException. + + Mark Pollack (.NET) + $Id: HibernateObjectRetrievalFailureException.cs,v 1.1 2008/04/07 20:12:53 lahma Exp $ + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Creates a new instance of the HibernateObjectRetrievalFailureException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Hibernate-specific subclass of ObjectOptimisticLockingFailureException. + + + Converts Hibernate's StaleObjectStateException. + + Mark Pollack (.NET) + $Id: HibernateOptimisticLockingFailureException.cs,v 1.2 2008/04/23 11:41:41 lahma Exp $ + + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The StaleStateException. + + + + Creates a new instance of the HibernateOptimisticLockingFailureException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + An IFactoryObject that creates a local Hibernate SessionFactory instance. + Behaves like a SessionFactory instance when used as bean reference, + e.g. for HibernateTemplate's "SessionFactory" property. + + + The typical usage will be to register this as singleton factory + in an application context and give objects references to application services + that need it. + + Hibernate configuration settings can be set using the IDictionary property 'HibernateProperties'. + + + This class implements the interface, + as autodetected by Spring's + for AOP-based translation of PersistenceExceptionTranslationPostProcessor. + Hence, the presence of e.g. LocalSessionFactoryBean automatically enables + a PersistenceExceptionTranslationPostProcessor to translate Hibernate exceptions. + + + Mark Pollack (.NET) + + + + The shared instance for this class (and derived classes). + + + + + Initializes a new instance of the class. + + + + + Return the singleon session factory. + + The singleon session factory. + + + + Initialize the SessionFactory for the given or the + default location. + + + + + Close the SessionFactory on application context shutdown. + + + + + Subclasses can override this method to perform custom initialization + of the Configuration instance used for ISessionFactory creation. + + + The properties of this LocalSessionFactoryObject will be applied to + the Configuration object that gets returned here. +

The default implementation creates a new Configuration instance. + A custom implementation could prepare the instance in a specific way, + or use a custom Configuration subclass. +

+ + The configuration instance. + + + + To be implemented by subclasses that want to to register further mappings + on the Configuration object after this FactoryObject registered its specified + mappings. + + + Invoked before the BuildMappings call, + so that it can still extend and modify the mapping information. + + the current Configuration object + + + + To be implemented by subclasses that want to to perform custom + post-processing of the Configuration object after this FactoryObject + performed its default initialization. + + The current configuration object. + + + + Executes schema update if requested. + + + + + Execute schema drop script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaExport class, to be invoked on application setup. + + + Fetch the LocalSessionFactoryBean itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfb = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute schema creation script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaExport class, to be invoked on application setup. + + + Fetch the LocalSessionFactoryObject itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfo = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute schema update script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaUpdate class, for automatically executing schema update scripts + on application startup. Can also be invoked manually. + + + Fetch the LocalSessionFactoryObject itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfo = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute the given schema script on the given ADO.NET Connection. + + + Note that the default implementation will log unsuccessful statements + and continue to execute. Override the ExecuteSchemaStatement + method to treat failures differently. + + The connection to use. + The SQL statement to execute. + + + + Execute the given schema SQL on the given ADO.NET command. + + + Note that the default implementation will log unsuccessful statements + and continue to execute. Override this method to treat failures differently. + + + + + + + Subclasses can override this method to perform custom initialization + of the SessionFactory instance, creating it via the given Configuration + object that got prepared by this LocalSessionFactoryObject. + + +

The default implementation invokes Configuration's BuildSessionFactory. + A custom implementation could prepare the instance in a specific way, + or use a custom ISessionFactory subclass. +

+ + The ISessionFactory instance. + + + + Implementation of the PersistenceExceptionTranslator interface, + as autodetected by Spring's PersistenceExceptionTranslationPostProcessor. + Converts the exception if it is a HibernateException; + else returns null to indicate an unknown exception. + translate the given exception thrown by a persistence framework to a + corresponding exception from Spring's generic DataAccessException hierarchy, + if possible. + + The exception thrown. + + the corresponding DataAccessException (or null if the + exception could not be translated. + + + + + + Convert the given HibernateException to an appropriate exception from the + Spring's DAO Exception hierarchy. + Will automatically apply a specified IAdoExceptionTranslator to a + Hibernate ADOException, else rely on Hibernate's default translation. + + The Hibernate exception that occured. + A corresponding DataAccessException + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + ADOException that occured, wrapping underlying ADO.NET exception. + + the corresponding DataAccessException instance + + + + + Setting the Application Context determines were resources are loaded from + + + + + Gets or sets the to use for loading mapping assemblies etc. + + + + + Sets the assemblies to load that contain mapping files. + + The mapping assemblies. + + + + Sets the hibernate configuration files to load, i.e. hibernate.cfg.xml. + + + + + Sets the locations of Spring IResources that contain mapping + files. + + The location of mapping resources. + + + + Return the Configuration object used to build the SessionFactory. + Allows access to configuration metadata stored there (rarely needed). + + The hibernate configuration. + + + + Set NHibernate configuration properties, like "hibernate.dialect". + + The hibernate properties. + +

Can be used to override values in a NHibernate XML config file, + or to specify all necessary properties locally. +

+

Note: Do not specify a transaction provider here when using + Spring-driven transactions. It is also advisable to omit connection + provider settings and use a Spring-set IDbProvider instead. +

+ + + + + Get or set the DataSource to be used by the SessionFactory. + + The db provider. + + If set, this will override corresponding settings in Hibernate properties. + Note: If this is set, the Hibernate settings should not define + a connection string + (hibernate.connection.connection_string) to avoid meaningless double configuration. + + + + + + Gets or sets a value indicating whether to expose a transaction aware session factory. + + + true if want to expose transaction aware session factory; otherwise, false. + + + + + Set a NHibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + Will get applied to any new Session created by this factory. +

Such an interceptor can either be set at the SessionFactory level, i.e. on + LocalSessionFactoryObject, or at the Session level, i.e. on HibernateTemplate, + HibernateInterceptor, and HibernateTransactionManager. It's preferable to set + it on LocalSessionFactoryObject or HibernateTransactionManager to avoid repeated + configuration and guarantee consistent behavior in transactions.

+ + + + + + + Set a Hibernate NamingStrategy for the SessionFactory, determining the + physical column and table names given the info in the mapping document. + + + + + Specify the Hibernate type definitions to register with the SessionFactory, + as Spring IObjectDefinition instances. This is an alternative to specifying + <typedef> elements in Hibernate mapping files. +

Unfortunately, Hibernate itself does not define a complete object that + represents a type definition, hence the need for Spring's TypeDefinitionBean.

+ @see TypeDefinitionBean + @see org.hibernate.cfg.Mappings#addTypeDef(String, String, java.util.Properties) + + + + + Specify the NHibernate FilterDefinitions to register with the SessionFactory. + This is an alternative to specifying <filter-def> elements in + Hibernate mapping files. + + + Typically, the passed-in FilterDefinition objects will have been defined + as Spring FilterDefinitionFactoryBeans, probably as inner beans within the + LocalSessionFactoryObject definition. + + + + + + Specify the cache strategies for entities (persistent classes or named entities). + This configuration setting corresponds to the <class-cache> entry + in the "hibernate.cfg.xml" configuration format. +

For example: + 

+            <property name="entityCacheStrategies">
+              <props>
+                <prop key="MyCompany.Customer">read-write</prop>
+                <prop key="MyCompany.Product">read-only,myRegion</prop>
+              </props>
+            </property>
+

+ + + + + Specify the cache strategies for persistent collections (with specific roles). + This configuration setting corresponds to the <collection-cache> entry + in the "hibernate.cfg.xml" configuration format. +

For example: + 

+            <property name="CollectionCacheStrategies">
+              <props>
+                <prop key="MyCompany.Order.Items">read-write</prop>
+                <prop key="MyCompany.Product.Categories">read-only,myRegion</prop>
+              </props>
+            </property>
+

+ + + + + Specify the NHibernate event listeners to register, with listener types + as keys and listener objects as values. +

+ Instead of a single listener object, you can also pass in a list + or set of listeners objects as value. +

+ + listener objects as values + + See the NHibernate documentation for further details on listener types + and associated listener interfaces. + + + + + Set whether to execute a schema update after SessionFactory initialization. +

+ For details on how to make schema update scripts work, see the NHibernate + documentation, as this class leverages the same schema update script support + in as NHibernate's own SchemaUpdate tool. +

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Sets custom byte code provider implementation to be used. This corresponds to setting + the property before NHibernate session factory + configuration. + + + + + Return the type or subclass. + + The type created by this factory + + + + Returns true + + true + + + + The Spring for .NET-backed ByteCodeprovider for NHibernate + + Fabio Maulo + + + + Creates a new bytecode Provider instance using the specified object factory + + + + + + Retrieve the delegate for this provider + capable of generating reflection optimization components. + + The class to be reflected upon.All property getters to be accessed via reflection.All property setters to be accessed via reflection. + The reflection optimization delegate. + + + + The specific factory for this provider capable of + generating run-time proxies for lazy-loading purposes. + + + + + NHibernate's object instaciator. + + + For entities and its implementations. + + + + + Instanciator of NHibernate's collections default types. + + + + + + + Fabio Maulo + + + + + + + + + + + + + + + Implement this method to perform extra treatments before and after + the call to the supplied . + + +

+ Polite implementations would certainly like to invoke + . +

+ + + The method invocation that is being intercepted. + + + The result of the call to the + method of + the supplied ; this return value may + well have been intercepted by the interceptor. + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + + + Fabio Maulo + + + + + + + + + Creates an instance of the specified type. + + The type of object to create. + A reference to the created object. + + + + Creates an instance of the specified type. + + The type of object to create.true if a public or nonpublic default constructor can match; false if only a public default constructor can match. + A reference to the created object + + + + Creates an instance of the specified type using the constructor that best matches the specified parameters. + + The type of object to create.An array of constructor arguments. + A reference to the created object. + + + + A Spring for .NET backed implementation for creating + NHibernate proxies. + + + Erich Eichinger + + + + Creates a new proxy. + + The id value for the proxy to be generated. + The session to which the generated proxy will be associated. + The generated proxy. + Indicates problems generating requested proxy. + + + + Creates a Spring for .NET backed instance. + + Erich Eichinger + + + + Build a proxy factory specifically for handling runtime lazy loading. + + The lazy-load proxy factory. + + + + + + + + + + + + + + + + + + Fabio Maulo + + + + + + + + + + + + Perform instantiation of an instance of the underlying class. + + The new instance. + + + + + + + + + + Delegates to an implementation of ISessionFactory that can select among multiple instances based on + thread local storage. + + + + + Subclasses can override this method to perform custom initialization + of the SessionFactory instance, creating it via the given Configuration + object that got prepared by this LocalSessionFactoryObject. + + +

The default implementation invokes Configuration's BuildSessionFactory. + A custom implementation could prepare the instance in a specific way, + or use a custom ISessionFactory subclass. +

+ + The ISessionFactory instance. + + + + PostProcessConfiguration + + + + + + DelegatingSessionFactory class + + + + + PlatformTransactionManager implementation for a single Hibernate SessionFactory. + Binds a Hibernate Session from the specified factory to the thread, potentially + allowing for one thread Session per factory + + + SessionFactoryUtils and HibernateTemplate are aware of thread-bound Sessions and participate in such + transactions automatically. Using either of those is required for Hibernate + access code that needs to support this transaction handling mechanism. + + Supports custom isolation levels at the start of the transaction + , and timeouts that get applied as appropriate + Hibernate query timeouts. To support the latter, application code must either use + HibernateTemplate (which by default applies the timeouts) or call + SessionFactoryUtils.applyTransactionTimeout for each created + Hibernate Query object. + + Note that you can specify a Spring IDbProvider instance which if shared with + a corresponding instance of AdoTemplate will allow for mixing ADO.NET/NHibernate + operations within a single transaction. + + Mark Pollack (.NET) + + + + Just needed for entityInterceptorBeanName. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The session factory. + + + + Return the current transaction object. + + The current transaction object. + + If transaction support is not available. + + + In the case of lookup or system errors. + + + + + Check if the given transaction object indicates an existing, + i.e. already begun, transaction. + + + Transaction object returned by + . + + True if there is an existing transaction. + + In the case of system errors. + + + + + Begin a new transaction with the given transaction definition. + + + Transaction object returned by + . + + + instance, describing + propagation behavior, isolation level, timeout etc. + + + Does not have to care about applying the propagation behavior, + as this has already been handled by this abstract manager. + + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + + Transaction object returned by + . + + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + Transaction synchronization will already have been suspended. + + + If suspending is not supported by the transaction manager implementation. + + + in case of system errors. + + + + + Resume the resources of the current transaction. + + + Transaction object returned by + . + + + The object that holds suspended resources as returned by + . + + + Transaction synchronization will be resumed afterwards. + + + If suspending is not supported by the transaction manager implementation. + + + In the case of system errors. + + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + +

+ An implementation does not need to check the rollback-only flag. +

+ + + In the case of system errors. + + + + + Does the tx scope commit. + + The status. + + + + Perform an actual rollback on the given transaction. + + The status representation of the transaction. + + An implementation does not need to check the new transaction flag. + + + In the case of system errors. + + + + + Does the tx scope rollback. + + The status. + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + The status representation of the transaction. + + In the case of system errors. + + + + + Does the tx scope set rollback only. + + The status. + + + + Gets the ADO.NET IDbTransaction object from the NHibernate ITransaction object. + + The hibernate transaction. + The ADO.NET transaction. Null if could not get the transaction. Warning + messages will be logged in that case. + + + + Convert the given HibernateException to an appropriate exception from + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The HibernateException that occured. + The corresponding DataAccessException instance + + + + Convert the given ADOException to an appropriate exception from the + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The ADOException that occured, wrapping the underlying + ADO.NET thrown exception. + The translator to convert hibernate ADOExceptions. + + The corresponding DataAccessException instance + + + + + Cleanup resources after transaction completion. + + Transaction object returned by + . + + + This implemenation unbinds the SessionFactory and + DbProvider from thread local storage and closes the + ISession. + +

+ Called after + and + + execution on any outcome. +

+

+ Should not throw any exceptions but just issue warnings on errors. +

+ + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Gets or sets the db provider. + + The db provider. + + + + Gets or sets a Hibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + When getting, return the current Hibernate entity interceptor, or null if none. + + The entity interceptor. + + Resolves an entity interceptor object name via the object factory, + if necessary. + Will get applied to any new Session created by this transaction manager. + Such an interceptor can either be set at the SessionFactory level, + i.e. on LocalSessionFactoryObject, or at the Session level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. + + If object factory is null and need to get entity interceptor via object name. + + + + Sets the object name of a Hibernate entity interceptor that + allows to inspect and change property values before writing to and reading from the database. + + The name of the entity interceptor object. + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + + + + Gets or sets the ADO.NET exception translator for this transaction manager. + + + Applied to ADO.NET Exceptions (wrapped by Hibernate's ADOException) + + The ADO exception translator. + + + + Gets the default IAdoException translator, lazily creating it if nece + + The default IAdoException translator. + + + + Gets or sets the SessionFactory that this instance should manage transactions for. + + The session factory. + + + + Gets the resource factory that this transaction manager operates on, + For the HibenratePlatformTransactionManager this the SessionFactory + + The SessionFactory. + + + + Set whether to autodetect a ADO.NET connection used by the Hibernate SessionFactory, + if set via LocalSessionFactoryObject's DbProvider. Default is "true". + + + true if [autodetect data source]; otherwise, false. + + +

Can be turned off to deliberately ignore an available IDbProvider, + to not expose Hibernate transactions as ADO.NET transactions for that IDbProvider. +

+ + + + + The object factory just needs to be known for resolving entity interceptor + It does not need to be set for any other mode of operation. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + + + + Return whether the transaction is internally marked as rollback-only. + + + True of the transaction is marked as rollback-only. + + + + SimpleDelegatingSessionFactory class + + + + + Connection string config element name + + + + + public Constructor + + + + + + TargetSessionFactory + + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate32.dll b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate32.dll new file mode 100644 index 00000000..e8e235c7 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate32.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate32.pdb b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate32.pdb new file mode 100644 index 00000000..b11f1039 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate32.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Data.NHibernate32.xml b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate32.xml new file mode 100644 index 00000000..e51ea37b --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Data.NHibernate32.xml @@ -0,0 +1,6711 @@ + + + + Spring.Data.NHibernate32 + + + + + Holds the references and configuration settings for a instance. + References are resolved by looking up the given object names in the root obtained by . + + + + + Holds the references and configuration settings for a instance. + + + + + Default value for property. + + + + + Default value for property. + + + + + Initialize a new instance of with default values. + + + Calling this constructor from your derived class leaves and + uninitialized. See and for more. + + + + + Initialize a new instance of with the given sessionFactory + and default values for all other settings. + + + The instance to be used for obtaining instances. + + + Calling this constructor marks all properties initialized. + + + + + Initialize a new instance of with the given values and references. + + + The instance to be used for obtaining instances. + + + Specify the to be set on each session provided by the instance. + + + Set whether to use a single session for each request. See property for details. + + + Specify the flushmode to be applied on each session provided by the instance. + + + Calling this constructor marks all properties initialized. + + + + + Override this method to resolve an instance according to your chosen strategy. + + + + + Override this method to resolve an instance according to your chosen strategy. + + + + + Gets the configured instance to be used. + + + If the entity interceptor is not set by the constructor, this property calls + to obtain an instance. This allows derived classes to + override the behaviour of how to obtain the concrete instance. + + + + + Gets the configured instance to be used. + + + If this property is requested for the first time, is called. + This allows derived classes to override the behaviour of how to obtain the concrete instance. + + If the instance cannot be resolved. + + + + Set whether to use a single session for each request. Default is "true". + If set to false, each data access operation or transaction will use + its own session (like without Open Session in View). Each of those + sessions will be registered for deferred close, though, actually + processed at request completion. + + + + + Gets or Sets the flushmode to be applied on each newly created session. + + + This property defaults to to ensure that modifying objects outside the boundaries + of a transaction will not be persisted. It is recommended to not change this value but wrap any modifying operation + within a transaction. + + + + + The default session factory name to use when retrieving the Hibernate session factory from + the root context. + + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + The configuration section to read setting variables from. + + + + Initializes a new instance. + + The type, who's name will be used to prefix setting variables with + The variable source to obtain settings from. + + + + Resolve the entityInterceptor by looking up + in the root application context. + + The resolved instance or + + + + Resolve the by looking up + in the root application context. + + The resolved instance or + + + + Convenient super class for Hibernate data access objects. + + + Requires a SessionFactory to be set, providing a HibernateTemplate + based on it to subclasses. Can alternatively be initialized directly with + a HibernateTemplate, to reuse the latter's settings such as the SessionFactory, + exception translator, flush mode, etc + + This base call is mainly intended for HibernateTemplate usage. + + This class will create its own HibernateTemplate if only a SessionFactory + is passed in. The "allowCreate" flag on that HibernateTemplate will be "true" + by default. A custom HibernateTemplate instance can be used through overriding + CreateHibernateTemplate. + + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Create a HibernateTemplate for the given ISessionFactory. + + + Only invoked if populating the DAO with a ISessionFactory reference! +

Can be overridden in subclasses to provide a HibernateTemplate instance + with different configuration, or a custom HibernateTemplate subclass. +

+ + + + + Check if the hibernate template property has been set. + + + + + Get a Hibernate Session, either from the current transaction or + a new one. The latter is only allowed if "allowCreate" is true. + + Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Either rely on a thread-bound + Session (via HibernateInterceptor), or use it in combination with + ReleaseSession. + + In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. + + + if a non-transactional Session should be created when no + transactional Session can be found for the current thread + + Hibernate session. + + If the Session couldn't be created + + + if no thread-bound Session found and allowCreate false + + + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Close the given Hibernate Session, created via this DAO's SessionFactory, + if it isn't bound to the thread. + + + Typically used in plain Hibernate code, in combination with the + Session property and ConvertHibernateAccessException. + + The session to close. + + + + Gets or sets the hibernate template. + + Set the HibernateTemplate for this DAO explicitly, + as an alternative to specifying a SessionFactory. + + The hibernate template. + + + + Gets or sets the session factory to be used by this DAO. + Will automatically create a HibernateTemplate for the given SessionFactory. + + The session factory. + + + + Get a Hibernate Session, either from the current transaction or a new one. + The latter is only allowed if the "allowCreate" setting of this object's + HibernateTemplate is true. + + +

Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Use it in combination with + ReleaseSession. +

+

In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. +

+ + The Hibernate session. + + + + Provide support for the open session in view pattern for lazily loaded hibernate objects + used in ASP.NET pages. + + jjx: http://forum.springframework.net/member.php?u=29 + Mark Pollack (.NET) + Erich Eichinger + Harald Radi + + + + Implementation of SessionScope that associates a single session within the using scope. + + + It is recommended to be used in the following type of scenario: + + using (new SessionScope()) + { + ... do multiple operation, possibly in multiple transactions. + } + + At the end of "using", the session is automatically closed. All transactions within the scope use the same session, + if you are using Spring's HibernateTemplate or using Spring's implementation of NHibernate 1.2's + ICurrentSessionContext interface. + + + It is assumed that the session factory object name is called "SessionFactory". In case that you named the object + in different way you can specify your can specify it in the application settings using the key + Spring.Data.NHibernate.Support.SessionScope.SessionFactoryObjectName. Values for EntityInterceptorObjectName + and SingleSessionMode can be specified similarly. + + + Note: + The session is managed on a per thread basis on the thread that opens the scope instance. This means that you must + never pass a reference to a instance over to another thread! + + + Robert M. (.NET) + Harald Radi (.NET) + + + + The logging instance. + + + + + Initializes a new instance of the class in single session mode, + associating a session with the thread. The session is opened lazily on demand. + + + + + Initializes a new instance of the class. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The name of the configuration section to read configuration settings from. + See for more info. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The name of the configuration section to read configuration settings from. + See for more info. + + The type, who's full name is used for prefixing appSetting keys + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The instance to be used for obtaining instances. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + + The instance to be used for obtaining instances. + + + Specify the to be set on each session provided by this instance. + + + Set whether to use a single session for each request. See property for details. + + + Specify the flushmode to be applied on each session provided by this instance. + + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Initializes a new instance of the class. + + An instance holding the scope configuration + + If set to true associate a session with the thread. If false, another + collaborating class will associate the session with the thread, potentially by calling + the Open method on this class. + + + + + Sets a flag, whether this scope is in "open" state on the current logical thread. + + + + + Gets/Sets a flag, whether this scope manages it's own session for the current logical thread or not. + + false if session is managed by this module. false otherwise + + + + Call Close(), + + + + + Opens a new session or participates in an existing session and + registers with spring's . + + + + + Close the current view's session and unregisters + from spring's . + + + + + Set whether to use a single session for each request. Default is "true". + If set to false, each data access operation or transaction will use + its own session (like without Open Session in View). Each of those + sessions will be registered for deferred close, though, actually + processed at request completion. + + + + + Gets the flushmode to be applied on each newly created session. + + + This property defaults to to ensure that modifying objects outside the boundaries + of a transaction will not be persisted. It is recommended to not change this value but wrap any modifying operation + within a transaction. + + + + + Get or set the configured SessionFactory + + + + + Get or set the configured EntityInterceptor + + + + + Gets a flag, whether this scope is in "open" state on the current logical thread. + + + + + Gets a flag, whether this scope manages it's own session for the current logical thread or not. + + + + + This sessionHolder creates a default session only if it is needed. + + + Although a NHibernateSession deferes creation of db-connections until they are really + needed, instantiation a session is imho still more expensive than this LazySessionHolder. (EE) + + + + + Session holder, wrapping a NHibernate ISession and a NHibernate Transaction. + HibernateTransactionManager binds instances of this class + to the thread, for a given ISessionFactory. + + + Note: This is an SPI class, not intended to be used by applications. + + Mark Pollack (.NET) + + + + May be used by derived classes to create an empty SessionHolder. + + + When using this ctor in your derived class, you MUST override ! + + + + + Initializes a new instance of the class. + + The session. + + + + Initializes a new instance of the class. + + The key to store the session under. + The hibernate session. + + + + May be overridden in a derived class to e.g. lazily create a session + + + + + Gets the session given key identifier + + The key. + A hibernate session + + + + Gets the session given the key and removes the session from + the dictionary storage. + + The key. + A hibernate session + + + + Adds the session to the dictionary storage using the default key. + + The hibernate session. + + + + Adds the session to the dictionary storage using the supplied key. + + The key. + The hibernate session. + + + + Removes the session from the dictionary storage for the given key. + + The key. + The session that was previously contained in the + dictionary storage. + + + + Determines whether the holder the specified session. + + The session. + + true if the holder contains the specified session; otherwise, false. + + + + + Clear the transaction state of this resource holder. + + + + + Gets the session using the default key + + The hibernate session. + + + + Gets the first session based on iteration over + the IDictionary storage. + + Any hibernate session. + + + + Gets a value indicating whether dictionary of + hibernate sessions is empty. + + + true if this session holder is empty; otherwise, false. + + + + + Gets a value indicating whether this SessionHolder + does not hold non default session. + + + true if does not hold non default session; otherwise, false. + + + + + Gets or sets the hibernate transaction. + + The transaction. + + + + Gets or sets the ADO.NET Connection used to create the session. + + The ADO.NET connection. + + + + Gets or sets the previous flush mode. + + The previous flush mode. + + + + Gets a value indicating whether the PreviousFlushMode property + was set. + + + true if assigned PreviousFlushMode property; otherwise, false. + + + + + Gets the validated session. + + The validated session. + + + + Initialize a new instance. + + + + + Create a new session on demand + + + + + Ensure session is closed (if any) and remove circular references to avoid memory leaks! + + + + + Initializes a new instance of the class. Creates a SessionScope, + but does not yet associate a session with a thread, that is left to the lifecycle of the request. + + + + + Register context handler and look up SessionFactoryObjectName under the application configuration key, + Spring.Data.NHibernate.Support.OpenSessionInViewModule.SessionFactoryObjectName if not using the default value + (i.e. sessionFactory) and look up the SingleSession setting under the application configuration key, + Spring.Data.NHibernate.Support.OpenSessionInViewModule.SingleSession if not using the default value of true. + + The standard HTTP application context + + + + A do nothing dispose method. + + + + + Hibernate-specific subclass of UncategorizedDataAccessException, + for ADO.NET exceptions that Hibernate rethrew and could not be + mapped into the DAO exception heirarchy. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception from the underlying data access API - ADO.NET + + + + + Creates a new instance of the HibernateSystemException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Hibernate-specific subclass of InvalidDataAccessResourceUsageException, + thrown on invalid HQL query syntax. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Initializes a new instance of the class. + + The ex. + + + + Creates a new instance of the HibernateQueryException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Gets the query string that was invalid. + + The query string that was invalid. + + + + Hibernate-specific subclass of UncategorizedDataAccessException, + for Hibernate system errors that do not match any concrete + Spring.Dao exceptions. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message. + + + + Creates a new instance of the HibernateSystemException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Initializes a new instance of the class. + + The cause. + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Helper class that simplifies NHibernate data access code + + +

Typically used to implement data access or business logic services that + use NHibernate within their implementation but are Hibernate-agnostic in their + interface. The latter or code calling the latter only have to deal with + domain objects.

+ +

The central method is Execute supporting Hibernate access code + implementing the HibernateCallback interface. It provides NHibernate Session + handling such that neither the IHibernateCallback implementation nor the calling + code needs to explicitly care about retrieving/closing NHibernate Sessions, + or handling Session lifecycle exceptions. For typical single step actions, + there are various convenience methods (Find, Load, SaveOrUpdate, Delete). +

+ +

Can be used within a service implementation via direct instantiation + with a ISessionFactory reference, or get prepared in an application context + and given to services as an object reference. Note: The ISessionFactory should + always be configured as an object in the application context, in the first case + given to the service directly, in the second case to the prepared template. +

+ +

This class can be considered as direct alternative to working with the raw + Hibernate Session API (through SessionFactoryUtils.Session). +

+ +

LocalSessionFactoryObject is the preferred way of obtaining a reference + to a specific NHibernate ISessionFactory. +

+ + Mark Pollack (.NET) + + + + Base class for HibernateTemplate defining common + properties like SessionFactory and flushing behavior. + + +

Not intended to be used directly. See HibernateTemplate. +

+ + Mark Pollack (.NET) + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Apply the flush mode that's been specified for this accessor + to the given Session. + + The current Hibernate Session. + if set to true + if executing within an existing transaction. + + the previous flush mode to restore after the operation, + or null if none + + + + + Flush the given Hibernate Session if necessary. + + The current Hibernate Session. + if set to true + if executing within an existing transaction. + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + ADOException that occured, wrapping underlying ADO.NET exception. + + the corresponding DataAccessException instance + + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + + + Note that a direct SQLException can just occur when callback code + performs direct ADO.NET access via ISession.Connection(). + + + The ADO.NET exception. + The corresponding DataAccessException instance + + + + Prepare the given IQuery object, applying cache settings and/or + a transaction timeout. + + The query object to prepare. + + + + Apply the given name parameter to the given Query object. + + The query object. + Name of the parameter + The value of the parameter + The NHibernate type of the parameter (or null if none specified) + + + + Prepare the given Criteria object, applying cache settings and/or + a transaction timeout. + + + Note that for NHibernate 1.2 this only works if the + implementation is of the type CriteriaImpl, which should generally + be the case. The SetFetchSize method is not available on the + ICriteria interface + + This is a no-op for NHibernate 1.0.x since + the SetFetchSize method is not on the ICriteria interface and + the implementation class is has internal access. + + To remove the method completely for Spring's NHibernate 1.0 + support while reusing code for NHibernate 1.2 would not be + possible. So now this ineffectual operation is left in tact for + NHibernate 1.0.2 support. + + The criteria object to prepare + + + + Ensure SessionFactory is not null + + If SessionFactory property is null. + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Set the object factory instance. + + The object factory instance. + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Gets a Session for use by this template. + + The session. + + - Returns a new Session in case of "alwaysUseNewSession" (using the same ADO.NET connection as a transaction Session, if applicable) + - a pre-bound Session in case of "AllowCreate" is set to false (not the default) + - or a pre-bound Session or new Session if no transactional or other pre-bound Session exists. + + + + + Helper class to determine if the FlushMode enumeration + was changed from its default value + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The flush mode. + + + + Gets or sets a value indicating whether the FlushMode + property was set.. + + true if FlushMode was set; otherwise, false. + + + + Gets or sets the FlushMode. + + The FlushMode. + + + + Interface that specifies a basic set of Hibernate operations. + + + Implemented by HibernateTemplate. Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + + Mark Pollack (.NET) + + + + Interface that specifies a set of Hibernate operations that + are common across versions of Hibernate. + + + Base interface for generic and non generic IHibernateOperations interfaces + Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + Mark Pollack (.NET) + + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + In case of Hibernate errors + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + Tthe persistent instance to delete. + The lock mode to obtain. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Delete all given persistent instances. + + The persistent instances to delete. + + This can be combined with any of the find methods to delete by query + in two lines of code, similar to Session's delete by query methods. + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the specified action assuming that the result object is a List. + + + This is a convenience method for executing Hibernate find calls or + queries within an action. + + The calback object that specifies the Hibernate action. + A IList returned by the action, or null + + In case of Hibernate errors + + + + Execute a query for persistent instances. + + a query expressed in Hibernate's query language + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + a query expressed in Hibernate's query language + the value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + a query expressed in Hibernate's query language + the values of the parameters + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + a List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + + a persistent type. + An identifier of the persistent instance. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + A persistent class. + An identifier of the persistent instance. + The lock mode. + the persistent instance, or null if not found + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + Type of the entity. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + Type of the entity. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + Type of the entity. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Save or update all given persistent instances, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instances to save or update + (to be associated with the Hibernate Session)he entities. + In case of Hibernate errors + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The default for creating a new non-transactional + session when no transactional Session can be found for the current thread + is set to true. + The session factory to create sessions. + + + + Initializes a new instance of the class. + + The session factory to create sessions. + if set to true allow creation + of a new non-transactional when no transactional Session can be found + for the current thread. + + + + Delegate function that clears the session. + + The hibernate session. + null + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + + The type. + An identifier of the persistent instance. + The persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The type. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + Type of the entity. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + Type of the entity. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + Type of the entity. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update all given persistent instances, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instances to save or update + (to be associated with the Hibernate Session)he entities. + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + Tthe persistent instance to delete. + The lock mode to obtain. + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + If length for argument values and types are not equal. + + + + Delete all given persistent instances. + + The persistent instances to delete. + + This can be combined with any of the find methods to delete by query + in two lines of code, similar to Session's delete by query methods. + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + + + + Execute the action specified by the given action object within a Session. + + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning a result object, i.e. a domain + object or a collection of domain objects. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the specified action assuming that the result object is a List. + + + This is a convenience method for executing Hibernate find calls or + queries within an action. + + The calback object that specifies the Hibernate action. + A IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + + + + Execute a query for persistent instances. + + a query expressed in Hibernate's query language + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + a query expressed in Hibernate's query language + the value of the parameter + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + a query expressed in Hibernate's query language + the values of the parameters + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A List containing 0 or more persistent instances + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The name of a Hibernate query in a mapping file + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + A query expressed in Hibernate's query language + The values of the parameters + A List containing 0 or more persistent instances + In case of Hibernate errors + + + + Create a close-suppressing proxy for the given Hibernate Session. + The proxy also prepares returned Query and Criteria objects. + + The session. + The session proxy. + + + + Check whether write operations are allowed on the given Session. + + + Default implementation throws an InvalidDataAccessApiUsageException + in case of FlushMode.Never. Can be overridden in subclasses. + + The current Hibernate session. + If write operation is attempted in read-only mode + + + + + Compares if the flush mode enumerations, Spring's + TemplateFlushMode and NHibernates FlushMode have equal + settings. + + The template flush mode. + The NHibernate flush mode. + + Returns true if both are Never, Auto, or Commit, false + otherwise. + + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + If object factory is not set and need to retrieve entity interceptor by name. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets whether to check that the Hibernate Session is not in read-only mode + in case of write operations (save/update/delete). + + + true if check that the Hibernate Session is not in read-only mode + in case of write operations; otherwise, false. + + + Default is "true", for fail-fast behavior when attempting write operations + within a read-only transaction. Turn this off to allow save/update/delete + on a Session with flush mode NEVER. + + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Set the object factory instance. + + The object factory instance + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the proxy factory. + + This may be useful to set if you create many instances of + HibernateTemplate and/or HibernateDaoSupport. This allows the same + ProxyFactory implementation to be used thereby limiting the + number of dynamic proxy types created in the temporary assembly, which + are never garbage collected due to .NET runtime semantics. + + The proxy factory. + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Callback interface for NHibernate code. + + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + Mark Pollack (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + A result object, or null if none. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + PlatformTransactionManager implementation for a single Hibernate SessionFactory. + Binds a Hibernate Session from the specified factory to the thread, potentially + allowing for one thread Session per factory + + + SessionFactoryUtils and HibernateTemplate are aware of thread-bound Sessions and participate in such + transactions automatically. Using either of those is required for Hibernate + access code that needs to support this transaction handling mechanism. + + Supports custom isolation levels at the start of the transaction + , and timeouts that get applied as appropriate + Hibernate query timeouts. To support the latter, application code must either use + HibernateTemplate (which by default applies the timeouts) or call + SessionFactoryUtils.applyTransactionTimeout for each created + Hibernate Query object. + + Note that you can specify a Spring IDbProvider instance which if shared with + a corresponding instance of AdoTemplate will allow for mixing ADO.NET/NHibernate + operations within a single transaction. + + Mark Pollack (.NET) + + + + Just needed for entityInterceptorBeanName. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The session factory. + + + + Return the current transaction object. + + The current transaction object. + + If transaction support is not available. + + + In the case of lookup or system errors. + + + + + Check if the given transaction object indicates an existing, + i.e. already begun, transaction. + + + Transaction object returned by + . + + True if there is an existing transaction. + + In the case of system errors. + + + + + Begin a new transaction with the given transaction definition. + + + Transaction object returned by + . + + + instance, describing + propagation behavior, isolation level, timeout etc. + + + Does not have to care about applying the propagation behavior, + as this has already been handled by this abstract manager. + + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + + Transaction object returned by + . + + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + Transaction synchronization will already have been suspended. + + + If suspending is not supported by the transaction manager implementation. + + + in case of system errors. + + + + + Resume the resources of the current transaction. + + + Transaction object returned by + . + + + The object that holds suspended resources as returned by + . + + + Transaction synchronization will be resumed afterwards. + + + If suspending is not supported by the transaction manager implementation. + + + In the case of system errors. + + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + +

+ An implementation does not need to check the rollback-only flag. +

+ + + In the case of system errors. + + + + + Perform an actual rollback on the given transaction. + + The status representation of the transaction. + + An implementation does not need to check the new transaction flag. + + + In the case of system errors. + + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + The status representation of the transaction. + + In the case of system errors. + + + + + Gets the ADO.NET IDbTransaction object from the NHibernate ITransaction object. + + The hibernate transaction. + The ADO.NET transaction. Null if could not get the transaction. Warning + messages will be logged in that case. + + + + Convert the given HibernateException to an appropriate exception from + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The HibernateException that occured. + The corresponding DataAccessException instance + + + + Convert the given ADOException to an appropriate exception from the + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The ADOException that occured, wrapping the underlying + ADO.NET thrown exception. + The translator to convert hibernate ADOExceptions. + + The corresponding DataAccessException instance + + + + + Cleanup resources after transaction completion. + + Transaction object returned by + . + + + This implemenation unbinds the SessionFactory and + DbProvider from thread local storage and closes the + ISession. + +

+ Called after + and + + execution on any outcome. +

+

+ Should not throw any exceptions but just issue warnings on errors. +

+ + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Gets or sets the db provider. + + The db provider. + + + + Gets or sets a Hibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + When getting, return the current Hibernate entity interceptor, or null if none. + + The entity interceptor. + + Resolves an entity interceptor object name via the object factory, + if necessary. + Will get applied to any new Session created by this transaction manager. + Such an interceptor can either be set at the SessionFactory level, + i.e. on LocalSessionFactoryObject, or at the Session level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. + + If object factory is null and need to get entity interceptor via object name. + + + + Sets the object name of a Hibernate entity interceptor that + allows to inspect and change property values before writing to and reading from the database. + + The name of the entity interceptor object. + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + + + + Gets or sets the ADO.NET exception translator for this transaction manager. + + + Applied to ADO.NET Exceptions (wrapped by Hibernate's ADOException) + + The ADO exception translator. + + + + Gets the default IAdoException translator, lazily creating it if nece + + The default IAdoException translator. + + + + Gets or sets the SessionFactory that this instance should manage transactions for. + + The session factory. + + + + Gets the resource factory that this transaction manager operates on, + For the HibenratePlatformTransactionManager this the SessionFactory + + The SessionFactory. + + + + Set whether to autodetect a ADO.NET connection used by the Hibernate SessionFactory, + if set via LocalSessionFactoryObject's DbProvider. Default is "true". + + + true if [autodetect data source]; otherwise, false. + + +

Can be turned off to deliberately ignore an available IDbProvider, + to not expose Hibernate transactions as ADO.NET transactions for that IDbProvider. +

+ + + + + The object factory just needs to be known for resolving entity interceptor + It does not need to be set for any other mode of operation. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + + + + Return whether the transaction is internally marked as rollback-only. + + + True of the transaction is marked as rollback-only. + + + + Enumeration for the various Hibernate flush modes. + + Mark Pollack (.NET) + + + Never flush is a good strategy for read-only units of work. + + + Hibernate will not track and look for changes in this case, + avoiding any overhead of modification detection. +

In case of an existing ISession, TemplateFlushMode.Never will turn + the hibenrate flush mode + to FlushMode.Never for the scope of the current operation, resetting the previous + flush mode afterwards. +

+ + + + Automatic flushing is the default mode for a Hibernate Session. + + + A session will get flushed on transaction commit, and on certain find + operations that might involve already modified instances, but not + after each unit of work like with eager flushing. +

In case of an existing Session, TemplateFlushMode.Auto + will participate in the existing flush mode, not modifying + it for the current operation. + This in particular means that this setting will not modify an existing + hibernate flush mode FlushMode.Never, in contrast to TemplateFlushMode.Eager. +

+ + + + + Eager flushing leads to immediate synchronization with the database, + even if in a transaction. + + + This causes inconsistencies to show up and throw + a respective exception immediately, and ADO access code that participates + in the same transaction will see the changes as the database is already + aware of them then. But the drawbacks are: +
    +
  • additional communication roundtrips with the database, instead of a + single batch at transaction commit;
    • +
  • the fact that an actual database rollback is needed if the Hibernate + transaction rolls back (due to already submitted SQL statements).
    • +
+

In case of an existing Session, TemplateFlushMode.Eager + will turn the NHibernate flush mode + to FlushMode.Auto for the scope of the current operation and issue a flush at the + end, resetting the previous flush mode afterwards. +

+ + + + + Flushing at commit only is intended for units of work where no + intermediate flushing is desired, not even for find operations + that might involve already modified instances. + + +

In case of an existing Session, TemplateFlushMode.Commit + will turn the NHibernate flush mode + to FlushMode.Commit for the scope of the current operation, resetting the previous + flush mode afterwards. The only exception is an existing flush mode + FlushMode.Never, which will not be modified through this setting. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning an IList of result objects created within the callback. + Note that there's special support for single step actions: + see HibernateTemplate.find etc. +

+ + The type of result object + Sree Nivask (.NET) + + + + Convenient super class for Hibernate data access objects. + + + Requires a SessionFactory to be set, providing a HibernateTemplate + based on it to subclasses. Can alternatively be initialized directly with + a HibernateTemplate, to reuse the latter's settings such as the SessionFactory, + exception translator, flush mode, etc + + This base call is mainly intended for HibernateTemplate usage. + + This class will create its own HibernateTemplate if only a SessionFactory + is passed in. The "allowCreate" flag on that HibernateTemplate will be "true" + by default. A custom HibernateTemplate instance can be used through overriding + CreateHibernateTemplate. + + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Create a HibernateTemplate for the given ISessionFactory. + + + Only invoked if populating the DAO with a ISessionFactory reference! +

Can be overridden in subclasses to provide a HibernateTemplate instance + with different configuration, or a custom HibernateTemplate subclass. +

+ + The new HibernateTemplate instance + + + + Check if the hibernate template property has been set. + + If HibernateTemplate property is null. + + + + Get a Hibernate Session, either from the current transaction or + a new one. The latter is only allowed if "allowCreate" is true. + + Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Either rely on a thread-bound + Session (via HibernateInterceptor), or use it in combination with + ReleaseSession. + + In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. + + + if a non-transactional Session should be created when no + transactional Session can be found for the current thread + + Hibernate session. + + If the Session couldn't be created + + + if no thread-bound Session found and allowCreate false + + + + + + Convert the given HibernateException to an appropriate exception from the + org.springframework.dao hierarchy. Will automatically detect + wrapped ADO.NET Exceptions and convert them accordingly. + + HibernateException that occured. + + The corresponding DataAccessException instance + + + The default implementation delegates to SessionFactoryUtils + and convertAdoAccessException. Can be overridden in subclasses. + + + + + Close the given Hibernate Session, created via this DAO's SessionFactory, + if it isn't bound to the thread. + + + Typically used in plain Hibernate code, in combination with the + Session property and ConvertHibernateAccessException. + + The session to close. + + + + Gets or sets the hibernate template. + + Set the HibernateTemplate for this DAO explicitly, + as an alternative to specifying a SessionFactory. + + The hibernate template. + + + + Gets or sets the session factory to be used by this DAO. + Will automatically create a HibernateTemplate for the given SessionFactory. + + The session factory. + + + + Get a Hibernate Session, either from the current transaction or a new one. + The latter is only allowed if the "allowCreate" setting of this object's + HibernateTemplate is true. + + +

Note that this is not meant to be invoked from HibernateTemplate code + but rather just in plain Hibernate code. Use it in combination with + ReleaseSession. +

+

In general, it is recommended to use HibernateTemplate, either with + the provided convenience operations or with a custom HibernateCallback + that provides you with a Session to work on. HibernateTemplate will care + for all resource management and for proper exception conversion. +

+ + The Hibernate session. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning the result object created within the callback. + Note that there's special support for single step actions: + see HibernateTemplate.find etc. +

+ + The type of result object + Sree Nivask (.NET) + + + + Generic version of the Helper class that simplifies NHibernate data access code + + +

Typically used to implement data access or business logic services that + use NHibernate within their implementation but are Hibernate-agnostic in their + interface. The latter or code calling the latter only have to deal with + domain objects.

+ +

The central method is Execute() supporting Hibernate access code which + implements the HibernateCallback interface. It provides NHibernate Session + handling such that neither the IHibernateCallback implementation nor the calling + code needs to explicitly care about retrieving/closing NHibernate Sessions, + or handling Session lifecycle exceptions. For typical single step actions, + there are various convenience methods (Find, Load, SaveOrUpdate, Delete). +

+ +

Can be used within a service implementation via direct instantiation + with a ISessionFactory reference, or get prepared in an application context + and given to services as an object reference. Note: The ISessionFactory should + always be configured as an object in the application context, in the first case + given to the service directly, in the second case to the prepared template. +

+ +

This class can be considered as a direct alternative to working with the raw + Hibernate Session API (through SessionFactoryUtils.Session). +

+ +

LocalSessionFactoryObject is the preferred way of obtaining a reference + to a specific NHibernate ISessionFactory. +

+ + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Interface that specifies a basic set of Hibernate operations. + + + Implemented by HibernateTemplate. Not often used, but a useful option + to enhance testability, as it can easily be mocked or stubbed. +

Provides HibernateTemplate's data access methods that mirror + various Session methods. See the NHibernate ISession documentation + for details on those methods. +

+ + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Return the persistent instance of the given entity type + with the given identifier, or if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The id of the object to get. + the persistent instance, or if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + The object type to load. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + The object type to load. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + The object type to load. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances. + + The object type to find. + a query expressed in Hibernate's query language + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the value of the parameter + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + The object type to find. + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the values of the parameters + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lenths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type retrieved. + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type retrieved. + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type to find. + The delegate callback object that specifies the Hibernate action. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type to find. + The FindHibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type to find. + The callback object that specifies the Hibernate action. + + A generic IList returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + + + + Execute the action specified by the given action object within a Session assuming that an IList is returned. + + The object type to find. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + an IList returned by the action, or null + + In case of Hibernate errors + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + Allows creation of a new non-transactional session when no + transactional Session can be found for the current thread + The session factory to create sessions. + + + + Initializes a new instance of the class. + + The session factory to create sessions. + if set to true allow creation + of a new non-transactional session when no transactional Session can be found + for the current thread. + + + + Remove all objects from the Session cache, and cancel all pending saves, + updates and deletes. + + + + + Delete the given persistent instance. + + The persistent instance to delete. + In case of Hibernate errors + + + + Delete the given persistent instance. + + Tthe persistent instance to delete. + The lock mode to obtain. + + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The value of the parameter. + The Hibernate type of the parameter (or null). + The number of entity instances deleted. + In case of Hibernate errors + + + + Delete all objects returned by the query. + + a query expressed in Hibernate's query language. + The values of the parameters. + Hibernate types of the parameters (or null) + The number of entity instances deleted. + In case of Hibernate errors + + + + Flush all pending saves, updates and deletes to the database. + + + Only invoke this for selective eager flushing, for example when ADO.NET code + needs to see certain changes within the same transaction. Else, it's preferable + to rely on auto-flushing at transaction completion. + + In case of Hibernate errors + + + + Load the persistent instance with the given identifier + into the given object, throwing an exception if not found. + + Entity the object (of the target class) to load into. + An identifier of the persistent instance. + If object not found. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + + The persistent instance to re-read. + In case of Hibernate errors + + + + Re-read the state of the given persistent instance. + Obtains the specified lock mode for the instance. + + The persistent instance to re-read. + The lock mode to obtain. + In case of Hibernate errors + + + + Determines whether the given object is in the Session cache. + + the persistence instance to check. + + true if session cache contains the specified entity; otherwise, false. + + In case of Hibernate errors + + + + Remove the given object from the Session cache. + + The persistent instance to evict. + In case of Hibernate errors + + + + Obtain the specified lock level upon the given object, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The he persistent instance to lock. + The lock mode to obtain. + If not found + In case of Hibernate errors + + + + Persist the given transient instance. + + The transient instance to persist. + The generated identifier. + In case of Hibernate errors + + + + Persist the given transient instance with the given identifier. + + The transient instance to persist. + The identifier to assign. + In case of Hibernate errors + + + + Update the given persistent instance. + + The persistent instance to update. + In case of Hibernate errors + + + + Update the given persistent instance. + Obtains the specified lock mode if the instance exists, implicitly + checking whether the corresponding database entry still exists + (throwing an OptimisticLockingFailureException if not found). + + The persistent instance to update. + The lock mode to obtain. + In case of Hibernate errors + + + + Save or update the given persistent instance, + according to its id (matching the configured "unsaved-value"?). + + Tthe persistent instance to save or update + (to be associated with the Hibernate Session). + In case of Hibernate errors + + + + Save or update the contents of given persistent object, + according to its id (matching the configured "unsaved-value"?). + Will copy the contained fields to an already loaded instance + with the same id, if appropriate. + + The persistent object to save or update. + (not necessarily to be associated with the Hibernate Session) + + The actually associated persistent object. + (either an already loaded instance with the same id, or the given object) + In case of Hibernate errors + + + + Copy the state of the given object onto the persistent object with the same identifier. + If there is no persistent instance currently associated with the session, it will be loaded. + Return the persistent instance. If the given instance is unsaved, + save a copy of and return it as a newly persistent instance. + The given instance does not become associated with the session. + This operation cascades to associated instances if the association is mapped with cascade="merge". + The semantics of this method are defined by JSR-220. + + The persistent object to merge. + (not necessarily to be associated with the Hibernate Session) + + An updated persistent instance + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The id of the object to get. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity type + with the given identifier, or null if not found. + Obtains the specified lock mode if the instance exists. + + The object type to get. + The lock mode to obtain. + The lock mode. + the persistent instance, or null if not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + + The object type to load. + An identifier of the persistent instance. + The persistent instance + If not found + In case of Hibernate errors + + + + Return the persistent instance of the given entity class + with the given identifier, throwing an exception if not found. + Obtains the specified lock mode if the instance exists. + + The object type to load. + An identifier of the persistent instance. + The lock mode. + The persistent instance + If not found + In case of Hibernate errors + + + + Return all persistent instances of the given entity class. + Note: Use queries or criteria for retrieving a specific subset. + + The object type to load. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances. + + The object type to find. + a query expressed in Hibernate's query language + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a "?" parameter in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the value of the parameter + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding one value + to a "?" parameter of the given type in the query string. + + The object type to find. + a query expressed in Hibernate's query language + The value of the parameter. + Hibernate type of the parameter (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to "?" parameters in the query string. + + The object type to find. + a query expressed in Hibernate's query language + the values of the parameters + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a number of + values to "?" parameters of the given types in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + Hibernate types of the parameters (or null) + + a generic List containing 0 or more persistent instances + + In case of Hibernate errors + If values and types are not null and their lengths are not equal + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + a generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding + one value to a named parameter in the query string. + + The object type to find. + The name of a Hibernate query in a mapping file + The name of the parameter + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding a + number of values to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The names of the parameters + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a "?" parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The value of the parameter + Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding a + number of values to "?" parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If values and types are not null and their lengths differ. + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + one value to a named parameter in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + Name of the parameter + The value of the parameter + The Hibernate type of the parameter (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a named query for persistent instances, binding + number of values to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The names of the parameters + The values of the parameters. + Hibernate types of the parameters (or null) + A generic List containing 0 or more persistent instances + In case of Hibernate errors + If paramNames length is not equal to values length or + if paramNames length is not equal to types length (when types is not null) + + + + Execute a named query for persistent instances, binding the properties + of the given object to named parameters in the query string. + A named query is defined in a Hibernate mapping file. + + The object type to find. + The name of a Hibernate query in a mapping file + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute a query for persistent instances, binding the properties + of the given object to named parameters in the query string. + + The object type to find. + A query expressed in Hibernate's query language + The values of the parameters + A generic List containing 0 or more persistent instances + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type retrieved. + The delegate callback object that specifies the Hibernate action. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type retrieved. + The HibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + The callback object that specifies the Hibernate action. + + a result object returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type retrieved. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + a result object returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session assuming that an IList is returned. + + The object type to find. + callback object that specifies the Hibernate action. + if set to true expose the native hibernate session to + callback code. + + an IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + The object type to find. + The delegate callback object that specifies the Hibernate action. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the delegate within a Session. + + The object type to find. + The FindHibernateDelegate that specifies the action + to perform. + if set to true expose the native hibernate session to + callback code. + A generic IList returned by the action, or null + + In case of Hibernate errors + + + + Execute the action specified by the given action object within a Session. + + The object type to find. + The callback object that specifies the Hibernate action. + + A generic IList returned by the action, or null + + + Application exceptions thrown by the action object get propagated to the + caller (can only be unchecked). Hibernate exceptions are transformed into + appropriate DAO ones. Allows for returning the result object. +

Note: Callback code is not supposed to handle transactions itself! + Use an appropriate transaction manager like HibernateTransactionManager. + Generally, callback code must not touch any Session lifecycle methods, + like close, disconnect, or reconnect, to let the template do its work. +

+ + + + + Gets or sets if a new Session should be created when no transactional Session + can be found for the current thread. + + + true if allowed to create non-transaction session; + otherwise, false. + + +

HibernateTemplate is aware of a corresponding Session bound to the + current thread, for example when using HibernateTransactionManager. + If allowCreate is true, a new non-transactional Session will be created + if none found, which needs to be closed at the end of the operation. + If false, an InvalidOperationException will get thrown in this case. +

+ + + + + Gets or sets a value indicating whether to always + use a new Hibernate Session for this template. + + true if always use new session; otherwise, false. + +

+ Default is "false"; if activated, all operations on this template will + work on a new NHibernate ISession even in case of a pre-bound ISession + (for example, within a transaction). +

+

Within a transaction, a new NHibernate ISession used by this template + will participate in the transaction through using the same ADO.NET + Connection. In such a scenario, multiple Sessions will participate + in the same database transaction. +

+

Turn this on for operations that are supposed to always execute + independently, without side effects caused by a shared NHibernate ISession. +

+ + + + + Set whether to expose the native Hibernate Session to IHibernateCallback + code. Default is "false": a Session proxy will be returned, + suppressing close calls and automatically applying + query cache settings and transaction timeouts. + + true if expose native session; otherwise, false. + + + + Gets or sets the template flush mode. + + + Default is Auto. Will get applied to any new ISession + created by the template. + + The template flush mode. + + + + Gets or sets the entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + + + Will get applied to any new ISession created by this object. +

Such an interceptor can either be set at the ISessionFactory level, + i.e. on LocalSessionFactoryObject, or at the ISession level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. +

+ + The interceptor. + + + + Set the object name of a Hibernate entity interceptor that allows to inspect + and change property values before writing to and reading from the database. + + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + The name of the entity interceptor in the object factory/application context. + + + + Gets or sets the session factory that should be used to create + NHibernate ISessions. + + The session factory. + + + + Set the object factory instance. + + The object factory instance + + + + Gets or sets a value indicating whether to + cache all queries executed by this template. + + + If this is true, all IQuery and ICriteria objects created by + this template will be marked as cacheable (including all + queries through find methods). +

To specify the query region to be used for queries cached + by this template, set the QueryCacheRegion property. +

+ + true if cache queries; otherwise, false. + + + + Gets or sets the name of the cache region for queries executed by this template. + + + If this is specified, it will be applied to all IQuery and ICriteria objects + created by this template (including all queries through find methods). +

The cache region will not take effect unless queries created by this + template are configured to be cached via the CacheQueries property. +

+ + The query cache region. + + + + Gets or sets the fetch size for this HibernateTemplate. + + The size of the fetch. + This is important for processing + large result sets: Setting this higher than the default value will increase + processing speed at the cost of memory consumption; setting this lower can + avoid transferring row data that will never be read by the application. +

Default is 0, indicating to use the driver's default.

+ + + + + Gets or sets the maximum number of rows for this HibernateTemplate. + + The max results. + + This is important + for processing subsets of large result sets, avoiding to read and hold + the entire result set in the database or in the ADO.NET driver if we're + never interested in the entire result in the first place (for example, + when performing searches that might return a large number of matches). +

Default is 0, indicating to use the driver's default.

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Gets the classic hibernate template for access to non-generic methods. + + The classic hibernate template. + + + + Gets or sets the proxy factory. + + This may be useful to set if you create many instances of + HibernateTemplate and/or HibernateDaoSupport. This allows the same + ProxyFactory implementation to be used thereby limiting the + number of dynamic proxy types created in the temporary assembly, which + are never garbage collected due to .NET runtime semantics. + + The proxy factory. + + + + Callback interface (Generic version) for NHibernate code. + + The type of result object + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + + Sree Nivask (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + A result object. + The active Hibernate session + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Callback interface (Generic version) for NHibernate code that + returns a List of objects. + + The type of result object + To be used with HibernateTemplate execute + method. The typical implementation will call + Session.load/find/save/update to perform + some operations on persistent objects. + + Sree Nivask (.NET) + Mark Pollack (.NET) + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + Collection result object. + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Gets called by HibernateTemplate with an active + Hibernate Session. Does not need to care about activating or closing + the Session, or handling transactions. + + +

+ Allows for returning a result object created within the callback, i.e. + a domain object or a collection of domain objects. Note that there's + special support for single step actions: see HibernateTemplate.find etc. +

+ + + + + Helper class featuring methods for Hibernate Session handling, + allowing for reuse of Hibernate Session instances within transactions. + Also provides support for exception translation. + + Mark Pollack (.NET) + + + + The instance for this class. + + + + + The ordering value for synchronizaiton this session resources. + Set to be lower than ADO.NET synchronization. + + + + + Initializes a new instance of the class. + + + + + Get a new Hibernate Session from the given SessionFactory. + Will return a new Session even if there already is a pre-bound + Session for the given SessionFactory. + + + Within a transaction, this method will create a new Session + that shares the transaction's ADO.NET Connection. More specifically, + it will use the same ADO.NET Connection as the pre-bound Hibernate Session. + + The session factory to create the session with. + The Hibernate entity interceptor, or null if none. + The new session. + If could not open Hibernate session + + + + Get a Hibernate Session for the given SessionFactory. Is aware of and will + return any existing corresponding Session bound to the current thread, for + example when using HibernateTransactionManager. Will always create a new + Session otherwise. + + + Supports setting a Session-level Hibernate entity interceptor that allows + to inspect and change property values before writing to and reading from the + database. Such an interceptor can also be set at the SessionFactory level + (i.e. on LocalSessionFactoryObject), on HibernateTransactionManager, or on + HibernateInterceptor/HibernateTemplate. + + The session factory to create the + session with. + Hibernate entity interceptor, or null if none. + AdoExceptionTranslator to use for flushing the + Session on transaction synchronization (can be null; only used when actually + registering a transaction synchronization). + The Hibernate Session + + If the session couldn't be created. + + + If no thread-bound Session found and allowCreate is false. + + + + + Get a Hibernate Session for the given SessionFactory. Is aware of and will + return any existing corresponding Session bound to the current thread, for + example when using . Will create a new Session + otherwise, if allowCreate is true. + + The session factory to create the session with. + if set to true create a non-transactional Session when no + transactional Session can be found for the current thread. + The hibernate session + + If the session couldn't be created. + + + If no thread-bound Session found and allowCreate is false. + + + + + Get a Hibernate Session for the given SessionFactory. + + Is aware of and will return any existing corresponding + Session bound to the current thread, for example whenusing + . Will create a new + Session otherwise, if "allowCreate" is true. +

Throws the orginal HibernateException, in contrast to + . +

+ The session factory. + if set to true [allow create]. + The Hibernate Session + + if the Session couldn't be created + + + If no thread-bound Session found and allowCreate is false. + + + + + Open a new Session from the factory. + + The session factory to create the session with. + Hibernate entity interceptor, or null if none. + the newly opened session + + + + Perform the actual closing of the Hibernate Session + catching and logging any cleanup exceptions thrown. + + The hibernate session to close + + + + Return whether the given Hibernate Session is transactional, that is, + bound to the current thread by Spring's transaction facilities. + + The hibernate session to check + The session factory that the session + was created with, can be null. + + true if the session transactional; otherwise, false. + + + + + Converts a Hibernate ADOException to a Spring DataAccessExcption, extracting the underlying error code from + ADO.NET. Will extract the ADOException Message and SqlString properties and pass them to the translate method + of the provided IAdoExceptionTranslator. + + The IAdoExceptionTranslator, may be a user provided implementation as configured on + HibernateTemplate. + + The ADOException throw + The translated DataAccessException or UncategorizedAdoException in case of an error in translation + itself. + + + + Convert the given HibernateException to an appropriate exception from the + Spring.Dao hierarchy. Note that it is advisable to + handle AdoException specifically by using a AdoExceptionTranslator for the + underlying ADO.NET exception. + + The Hibernate exception that occured. + DataAccessException instance + + + + Close the given Session, created via the given factory, + if it is not managed externally (i.e. not bound to the thread). + + The hibernate session to close + The hibernate SessionFactory that + the session was created with. + + + + Close the given Session or register it for deferred close. + + The session. + The session factory. + + + + Initialize deferred close for the current thread and the given SessionFactory. + Sessions will not be actually closed on close calls then, but rather at a + processDeferredClose call at a finishing point (like request completion). + + The session factory. + + + + Return if deferred close is active for the current thread + and the given SessionFactory. + The session factory. + + true if [is deferred close active] [the specified session factory]; otherwise, false. + + If SessionFactory argument is null. + + + + Process Sessions that have been registered for deferred close + for the given SessionFactory. + + The session factory. + If there is no session factory associated with the thread. + + + + Applies the current transaction timeout, if any, to the given + criteria object + + The Hibernate Criteria object. + Hibernate SessionFactory that the Criteria was created for + (can be null). + If criteria argument is null. + + + + Applies the current transaction timeout, if any, to the given + Hibenrate query object. + + The Hibernate Query object. + Hibernate SessionFactory that the Query was created for + (can be null). + If query argument is null. + + + + Gets the Spring IDbProvider given the ISessionFactory. + + The matching is performed by comparing the assembly qualified + name string of the hibernate Driver.ConnectionType to those in + the DbProviderFactory definitions. No connections are created + in performing this comparison. + The session factory. + The corresponding IDbProvider, null if no mapping was found. + If DbProviderFactory's ApplicaitonContext is not + an instance of IConfigurableApplicaitonContext. + + + + Create a IAdoExceptionTranslator from the given SessionFactory. + + If a corresponding IDbProvider is found, a ErrorcodeExceptionTranslator + for the IDbProvider is created. Otherwise, a FallbackException is created. + The session factory to create the translator for + An IAdoExceptionTranslator + + + + Implementation of NHibernates 1.2's ICurrentSessionContext interface + that delegates to Spring's SessionFactoryUtils for providing a + Spirng-managed current Session. + + Used by Spring's LocalSessionFactoryBean if told to expose + a transaction-aware SessionFactory. +

This ICurrentSessionContext implementation can also be specified in + custom ISessionFactory setup through the + "hibernate.current_session_context_class" property, with the fully + qualified name of this class as value.

 + Juergen Hoeller + Mark Pollack (.NET) + + + + + Initializes a new instance of the class + + The NHibernate session factory. + + + + Retrieve the Spring-managed Session for the current thread. + + Current session associated with the thread + On errors retrieving thread bound session. + + + + NHibnerations actions taken during the transaction lifecycle. + + Mark Pollack (.NET) + + + + The instance for this class. + + + + + Initializes a new instance of the class. + + + + + Suspend this synchronization. + + +

+ Unbind Hibernate resources (SessionHolder) from + + if managing any. +

+ + + + + Resume this synchronization. + + +

+ Rebind Hibernate resources from + + if managing any. +

+ + + + + Invoked before transaction commit (before + ) + + + If the transaction is defined as a read-only transaction. + + +

+ Can flush transactional sessions to the database. +

+

+ Note that exceptions will get propagated to the commit caller and + cause a rollback of the transaction. +

+ + + + + Invoked before transaction commit (before + ) + Can e.g. flush transactional O/R Mapping sessions to the database + + + + This callback does not mean that the transaction will actually be + commited. A rollback decision can still occur after this method + has been called. This callback is rather meant to perform work + that's only relevant if a commit still has a chance + to happen, such as flushing SQL statements to the database. + + + Note that exceptions will get propagated to the commit caller and cause a + rollback of the transaction. + + (note: do not throw TransactionException subclasses here!) + + + + + + Invoked after transaction commit/rollback. + + + Status according to + + + Can e.g. perform resource cleanup, in this case after transaction completion. +

+ Note that exceptions will get propagated to the commit or rollback + caller, although they will not influence the outcome of the transaction. +

+ + + + + Return the order value of this object, where a higher value means greater in + terms of sorting. + + +

+ Normally starting with 0 or 1, with indicating + greatest. Same order values will result in arbitrary positions for the affected + objects. +

+

+ Higher value can be interpreted as lower priority, consequently the first object + has highest priority. +

+ + The order value. + + + + Convenient FactoryObject for defining Hibernate FilterDefinitions. + Exposes a corresponding Hibernate FilterDefinition object. + + + +

+ Typically defined as an inner object within a LocalSessionFactoryObject + definition, as the list element for the "filterDefinitions" object property. + For example: +

+ + 
+            <objectn id="sessionFactory" type="Spring.Data.NHibernate.LocalSessionFactoryObject, Spring.Data.NHibernate">
+              ...
+              <property name="FilterDefinitions">
+               <list>
+                  <object type="Spring.Data.NHibernate.FilterDefinitionFactoryObject, Spring.Data.NHibernate">
+                    <property name="FilterName" value="myFilter"/>
+                    <property name="ParameterTypes">
+                      <props>
+                        <prop key="MyParam">string</prop>
+                        <prop key="MyOtherParam">long</prop>
+                      </props>
+                    </property>
+                  </object>
+                </list>
+              </property>
+              ...
+            </object>
+
+

+ Alternatively, specify an object id (or name) attribute for the inner object, + instead of the "FilterName" property. +

+ + Juergen Hoeller + Marko Lahma (.NET) + + + $Id: FilterDefiniitionFactoryObject.cs,v 1.1 2008/04/07 20:12:53 lahma Exp $ + + + + Initializes the filter definitions. + + + + + Returns the singleton filter definition. + + + + + + Set the name of the filter. + + + + + Set the parameter types for the filter, + with parameter names as keys and type names as values. + + + + + + Specify a default filter condition for the filter, if any. + + + + + If no explicit filter name has been specified, the object name of + the FilterDefinitionFactoryObject will be used. + + + + + + Returns the type of the object this factory produces. + + + + + Returns whether this factory produces singletons, always true. + + + + + Hibernate-specific subclass of ObjectRetrievalFailureException. + + + Converts Hibernate's UnresolvableObjectException, ObjectNotFoundException, + ObjectDeletedException, and WrongClassException. + + Mark Pollack (.NET) + $Id: HibernateObjectRetrievalFailureException.cs,v 1.1 2008/04/07 20:12:53 lahma Exp $ + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The ex. + + + + Creates a new instance of the HibernateObjectRetrievalFailureException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Hibernate-specific subclass of ObjectOptimisticLockingFailureException. + + + Converts Hibernate's StaleObjectStateException. + + Mark Pollack (.NET) + $Id: HibernateOptimisticLockingFailureException.cs,v 1.2 2008/04/23 11:41:41 lahma Exp $ + + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Initializes a new instance of the class. + + The ex. + + + + Initializes a new instance of the class. + + The StaleStateException. + + + + Creates a new instance of the HibernateOptimisticLockingFailureException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + An IFactoryObject that creates a local Hibernate SessionFactory instance. + Behaves like a SessionFactory instance when used as bean reference, + e.g. for HibernateTemplate's "SessionFactory" property. + + + The typical usage will be to register this as singleton factory + in an application context and give objects references to application services + that need it. + + Hibernate configuration settings can be set using the IDictionary property 'HibernateProperties'. + + + This class implements the interface, + as autodetected by Spring's + for AOP-based translation of PersistenceExceptionTranslationPostProcessor. + Hence, the presence of e.g. LocalSessionFactoryBean automatically enables + a PersistenceExceptionTranslationPostProcessor to translate Hibernate exceptions. + + + Mark Pollack (.NET) + + + + The shared instance for this class (and derived classes). + + + + + Initializes a new instance of the class. + + + + + Return the singleon session factory. + + The singleon session factory. + + + + Initialize the SessionFactory for the given or the + default location. + + + + + Close the SessionFactory on application context shutdown. + + + + + Subclasses can override this method to perform custom initialization + of the Configuration instance used for ISessionFactory creation. + + + The properties of this LocalSessionFactoryObject will be applied to + the Configuration object that gets returned here. +

The default implementation creates a new Configuration instance. + A custom implementation could prepare the instance in a specific way, + or use a custom Configuration subclass. +

+ + The configuration instance. + + + + To be implemented by subclasses that want to to register further mappings + on the Configuration object after this FactoryObject registered its specified + mappings. + + + Invoked before the BuildMappings call, + so that it can still extend and modify the mapping information. + + the current Configuration object + + + + To be implemented by subclasses that want to to perform custom + post-processing of the Configuration object after this FactoryObject + performed its default initialization. + + The current configuration object. + + + + Executes schema update if requested. + + + + + Execute schema drop script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaExport class, to be invoked on application setup. + + + Fetch the LocalSessionFactoryBean itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfb = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute schema creation script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaExport class, to be invoked on application setup. + + + Fetch the LocalSessionFactoryObject itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfo = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute schema update script, determined by the Configuration object + used for creating the SessionFactory. A replacement for NHibernate's + SchemaUpdate class, for automatically executing schema update scripts + on application startup. Can also be invoked manually. + + + Fetch the LocalSessionFactoryObject itself rather than the exposed + SessionFactory to be able to invoke this method, e.g. via + LocalSessionFactoryObject lsfo = (LocalSessionFactoryObject) ctx.GetObject("mySessionFactory");. +

+ Uses the SessionFactory that this bean generates for accessing a ADO.NET + connection to perform the script. +

+ + + + + Execute the given schema script on the given ADO.NET Connection. + + + Note that the default implementation will log unsuccessful statements + and continue to execute. Override the ExecuteSchemaStatement + method to treat failures differently. + + The connection to use. + The SQL statement to execute. + + + + Execute the given schema SQL on the given ADO.NET command. + + + Note that the default implementation will log unsuccessful statements + and continue to execute. Override this method to treat failures differently. + + + + + + + Subclasses can override this method to perform custom initialization + of the SessionFactory instance, creating it via the given Configuration + object that got prepared by this LocalSessionFactoryObject. + + +

The default implementation invokes Configuration's BuildSessionFactory. + A custom implementation could prepare the instance in a specific way, + or use a custom ISessionFactory subclass. +

+ + The ISessionFactory instance. + + + + Implementation of the PersistenceExceptionTranslator interface, + as autodetected by Spring's PersistenceExceptionTranslationPostProcessor. + Converts the exception if it is a HibernateException; + else returns null to indicate an unknown exception. + translate the given exception thrown by a persistence framework to a + corresponding exception from Spring's generic DataAccessException hierarchy, + if possible. + + The exception thrown. + + the corresponding DataAccessException (or null if the + exception could not be translated. + + + + + + Convert the given HibernateException to an appropriate exception from the + Spring's DAO Exception hierarchy. + Will automatically apply a specified IAdoExceptionTranslator to a + Hibernate ADOException, else rely on Hibernate's default translation. + + The Hibernate exception that occured. + A corresponding DataAccessException + + + + Converts the ADO.NET access exception to an appropriate exception from the + org.springframework.dao hierarchy. Can be overridden in subclasses. + + ADOException that occured, wrapping underlying ADO.NET exception. + + the corresponding DataAccessException instance + + + + + Setting the Application Context determines were resources are loaded from + + + + + Gets or sets the to use for loading mapping assemblies etc. + + + + + Sets the assemblies to load that contain mapping files. + + The mapping assemblies. + + + + Sets the hibernate configuration files to load, i.e. hibernate.cfg.xml. + + + + + Sets the locations of Spring IResources that contain mapping + files. + + The location of mapping resources. + + + + Return the Configuration object used to build the SessionFactory. + Allows access to configuration metadata stored there (rarely needed). + + The hibernate configuration. + + + + Set NHibernate configuration properties, like "hibernate.dialect". + + The hibernate properties. + +

Can be used to override values in a NHibernate XML config file, + or to specify all necessary properties locally. +

+

Note: Do not specify a transaction provider here when using + Spring-driven transactions. It is also advisable to omit connection + provider settings and use a Spring-set IDbProvider instead. +

+ + + + + Get or set the DataSource to be used by the SessionFactory. + + The db provider. + + If set, this will override corresponding settings in Hibernate properties. + Note: If this is set, the Hibernate settings should not define + a connection string + (hibernate.connection.connection_string) to avoid meaningless double configuration. + + + + + + Gets or sets a value indicating whether to expose a transaction aware session factory. + + + true if want to expose transaction aware session factory; otherwise, false. + + + + + Set a NHibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + Will get applied to any new Session created by this factory. +

Such an interceptor can either be set at the SessionFactory level, i.e. on + LocalSessionFactoryObject, or at the Session level, i.e. on HibernateTemplate, + HibernateInterceptor, and HibernateTransactionManager. It's preferable to set + it on LocalSessionFactoryObject or HibernateTransactionManager to avoid repeated + configuration and guarantee consistent behavior in transactions.

+ + + + + + + Set a Hibernate NamingStrategy for the SessionFactory, determining the + physical column and table names given the info in the mapping document. + + + + + Specify the Hibernate type definitions to register with the SessionFactory, + as Spring IObjectDefinition instances. This is an alternative to specifying + <typedef> elements in Hibernate mapping files. +

Unfortunately, Hibernate itself does not define a complete object that + represents a type definition, hence the need for Spring's TypeDefinitionBean.

+ @see TypeDefinitionBean + @see org.hibernate.cfg.Mappings#addTypeDef(String, String, java.util.Properties) + + + + + Specify the NHibernate FilterDefinitions to register with the SessionFactory. + This is an alternative to specifying <filter-def> elements in + Hibernate mapping files. + + + Typically, the passed-in FilterDefinition objects will have been defined + as Spring FilterDefinitionFactoryBeans, probably as inner beans within the + LocalSessionFactoryObject definition. + + + + + + Specify the cache strategies for entities (persistent classes or named entities). + This configuration setting corresponds to the <class-cache> entry + in the "hibernate.cfg.xml" configuration format. +

For example: + 

+            <property name="entityCacheStrategies">
+              <props>
+                <prop key="MyCompany.Customer">read-write</prop>
+                <prop key="MyCompany.Product">read-only,myRegion</prop>
+              </props>
+            </property>
+

+ + + + + Specify the cache strategies for persistent collections (with specific roles). + This configuration setting corresponds to the <collection-cache> entry + in the "hibernate.cfg.xml" configuration format. +

For example: + 

+            <property name="CollectionCacheStrategies">
+              <props>
+                <prop key="MyCompany.Order.Items">read-write</prop>
+                <prop key="MyCompany.Product.Categories">read-only,myRegion</prop>
+              </props>
+            </property>
+

+ + + + + Specify the NHibernate event listeners to register, with listener types + as keys and listener objects as values. +

+ Instead of a single listener object, you can also pass in a list + or set of listeners objects as value. +

+ + listener objects as values + + See the NHibernate documentation for further details on listener types + and associated listener interfaces. + + + + + Set whether to execute a schema update after SessionFactory initialization. +

+ For details on how to make schema update scripts work, see the NHibernate + documentation, as this class leverages the same schema update script support + in as NHibernate's own SchemaUpdate tool. +

+ + + + + Set the ADO.NET exception translator for this instance. + Applied to System.Data.Common.DbException (or provider specific exception type + in .NET 1.1) thrown by callback code, be it direct + DbException or wrapped Hibernate ADOExceptions. +

The default exception translator is either a ErrorCodeExceptionTranslator + if a DbProvider is available, or a FalbackExceptionTranslator otherwise +

+ + The ADO exception translator. + + + + Sets custom byte code provider implementation to be used. This corresponds to setting + the property before NHibernate session factory + configuration. + + + + + Return the type or subclass. + + The type created by this factory + + + + Returns true + + true + + + + The Spring for .NET-backed ByteCodeprovider for NHibernate + + Fabio Maulo + + + + Creates a new bytecode Provider instance using the specified object factory + + + + + + Retrieve the delegate for this provider + capable of generating reflection optimization components. + + The class to be reflected upon.All property getters to be accessed via reflection.All property setters to be accessed via reflection. + The reflection optimization delegate. + + + + The specific factory for this provider capable of + generating run-time proxies for lazy-loading purposes. + + + + + NHibernate's object instaciator. + + + For entities and its implementations. + + + + + Instanciator of NHibernate's collections default types. + + + + + + + Fabio Maulo + + + + + + + + + + + + + + + Implement this method to perform extra treatments before and after + the call to the supplied . + + +

+ Polite implementations would certainly like to invoke + . +

+ + + The method invocation that is being intercepted. + + + The result of the call to the + method of + the supplied ; this return value may + well have been intercepted by the interceptor. + + + If any of the interceptors in the chain or the target object itself + throws an exception. + + + + + + + Fabio Maulo + + + + + + + + + Creates an instance of the specified type. + + The type of object to create. + A reference to the created object. + + + + Creates an instance of the specified type. + + The type of object to create.true if a public or nonpublic default constructor can match; false if only a public default constructor can match. + A reference to the created object + + + + Creates an instance of the specified type using the constructor that best matches the specified parameters. + + The type of object to create.An array of constructor arguments. + A reference to the created object. + + + + A Spring for .NET backed implementation for creating + NHibernate proxies. + + + Erich Eichinger + + + + Creates a new proxy. + + The id value for the proxy to be generated. + The session to which the generated proxy will be associated. + The generated proxy. + Indicates problems generating requested proxy. + + + + Creates a Spring for .NET backed instance. + + Erich Eichinger + + + + Build a proxy factory specifically for handling runtime lazy loading. + + The lazy-load proxy factory. + + + + + + + + + + + + + + + + + + Fabio Maulo + + + + + + + + + + + + Perform instantiation of an instance of the underlying class. + + The new instance. + + + + + + + + + + Delegates to an implementation of ISessionFactory that can select among multiple instances based on + thread local storage. + + + + + Subclasses can override this method to perform custom initialization + of the SessionFactory instance, creating it via the given Configuration + object that got prepared by this LocalSessionFactoryObject. + + +

The default implementation invokes Configuration's BuildSessionFactory. + A custom implementation could prepare the instance in a specific way, + or use a custom ISessionFactory subclass. +

+ + The ISessionFactory instance. + + + + PostProcessConfiguration + + + + + + DelegatingSessionFactory class + + + + + PlatformTransactionManager implementation for a single Hibernate SessionFactory. + Binds a Hibernate Session from the specified factory to the thread, potentially + allowing for one thread Session per factory + + + SessionFactoryUtils and HibernateTemplate are aware of thread-bound Sessions and participate in such + transactions automatically. Using either of those is required for Hibernate + access code that needs to support this transaction handling mechanism. + + Supports custom isolation levels at the start of the transaction + , and timeouts that get applied as appropriate + Hibernate query timeouts. To support the latter, application code must either use + HibernateTemplate (which by default applies the timeouts) or call + SessionFactoryUtils.applyTransactionTimeout for each created + Hibernate Query object. + + Note that you can specify a Spring IDbProvider instance which if shared with + a corresponding instance of AdoTemplate will allow for mixing ADO.NET/NHibernate + operations within a single transaction. + + Mark Pollack (.NET) + + + + Just needed for entityInterceptorBeanName. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The session factory. + + + + Return the current transaction object. + + The current transaction object. + + If transaction support is not available. + + + In the case of lookup or system errors. + + + + + Check if the given transaction object indicates an existing, + i.e. already begun, transaction. + + + Transaction object returned by + . + + True if there is an existing transaction. + + In the case of system errors. + + + + + Begin a new transaction with the given transaction definition. + + + Transaction object returned by + . + + + instance, describing + propagation behavior, isolation level, timeout etc. + + + Does not have to care about applying the propagation behavior, + as this has already been handled by this abstract manager. + + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + + Transaction object returned by + . + + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + Transaction synchronization will already have been suspended. + + + If suspending is not supported by the transaction manager implementation. + + + in case of system errors. + + + + + Resume the resources of the current transaction. + + + Transaction object returned by + . + + + The object that holds suspended resources as returned by + . + + + Transaction synchronization will be resumed afterwards. + + + If suspending is not supported by the transaction manager implementation. + + + In the case of system errors. + + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + +

+ An implementation does not need to check the rollback-only flag. +

+ + + In the case of system errors. + + + + + Does the tx scope commit. + + The status. + + + + Perform an actual rollback on the given transaction. + + The status representation of the transaction. + + An implementation does not need to check the new transaction flag. + + + In the case of system errors. + + + + + Does the tx scope rollback. + + The status. + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + The status representation of the transaction. + + In the case of system errors. + + + + + Does the tx scope set rollback only. + + The status. + + + + Gets the ADO.NET IDbTransaction object from the NHibernate ITransaction object. + + The hibernate transaction. + The ADO.NET transaction. Null if could not get the transaction. Warning + messages will be logged in that case. + + + + Convert the given HibernateException to an appropriate exception from + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The HibernateException that occured. + The corresponding DataAccessException instance + + + + Convert the given ADOException to an appropriate exception from the + the Spring.Dao hierarchy. Can be overridden in subclasses. + + The ADOException that occured, wrapping the underlying + ADO.NET thrown exception. + The translator to convert hibernate ADOExceptions. + + The corresponding DataAccessException instance + + + + + Cleanup resources after transaction completion. + + Transaction object returned by + . + + + This implemenation unbinds the SessionFactory and + DbProvider from thread local storage and closes the + ISession. + +

+ Called after + and + + execution on any outcome. +

+

+ Should not throw any exceptions but just issue warnings on errors. +

+ + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Gets or sets the db provider. + + The db provider. + + + + Gets or sets a Hibernate entity interceptor that allows to inspect and change + property values before writing to and reading from the database. + When getting, return the current Hibernate entity interceptor, or null if none. + + The entity interceptor. + + Resolves an entity interceptor object name via the object factory, + if necessary. + Will get applied to any new Session created by this transaction manager. + Such an interceptor can either be set at the SessionFactory level, + i.e. on LocalSessionFactoryObject, or at the Session level, i.e. on + HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. + It's preferable to set it on LocalSessionFactoryObject or HibernateTransactionManager + to avoid repeated configuration and guarantee consistent behavior in transactions. + + If object factory is null and need to get entity interceptor via object name. + + + + Sets the object name of a Hibernate entity interceptor that + allows to inspect and change property values before writing to and reading from the database. + + The name of the entity interceptor object. + + Will get applied to any new Session created by this transaction manager. +

Requires the object factory to be known, to be able to resolve the object + name to an interceptor instance on session creation. Typically used for + prototype interceptors, i.e. a new interceptor instance per session. +

+

Can also be used for shared interceptor instances, but it is recommended + to set the interceptor reference directly in such a scenario. +

+ + + + + Gets or sets the ADO.NET exception translator for this transaction manager. + + + Applied to ADO.NET Exceptions (wrapped by Hibernate's ADOException) + + The ADO exception translator. + + + + Gets the default IAdoException translator, lazily creating it if nece + + The default IAdoException translator. + + + + Gets or sets the SessionFactory that this instance should manage transactions for. + + The session factory. + + + + Gets the resource factory that this transaction manager operates on, + For the HibenratePlatformTransactionManager this the SessionFactory + + The SessionFactory. + + + + Set whether to autodetect a ADO.NET connection used by the Hibernate SessionFactory, + if set via LocalSessionFactoryObject's DbProvider. Default is "true". + + + true if [autodetect data source]; otherwise, false. + + +

Can be turned off to deliberately ignore an available IDbProvider, + to not expose Hibernate transactions as ADO.NET transactions for that IDbProvider. +

+ + + + + The object factory just needs to be known for resolving entity interceptor + It does not need to be set for any other mode of operation. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + + + + Return whether the transaction is internally marked as rollback-only. + + + True of the transaction is marked as rollback-only. + + + + SimpleDelegatingSessionFactory class + + + + + Connection string config element name + + + + + public Constructor + + + + + + TargetSessionFactory + + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Data.dll b/Resources/Libraries/Spring.NET/Spring.Data.dll new file mode 100644 index 00000000..6606df30 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Data.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Data.pdb b/Resources/Libraries/Spring.NET/Spring.Data.pdb new file mode 100644 index 00000000..388bf919 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Data.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Data.xml b/Resources/Libraries/Spring.NET/Spring.Data.xml new file mode 100644 index 00000000..0c8cbe15 --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Data.xml @@ -0,0 +1,11693 @@ + + + + Spring.Data + + + + + Spring AOP exception translation aspect for use at Repository or DAO layer level. + Translates native persistence exceptions into Spring's DataAccessException hierarchy, + based on a given PersistenceExceptionTranslator. + + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + The persistence exception translator to use. + Type of the repository attribute to check for. + + + + Initializes a new instance of the class. + + The object factory to obtain all IPersistenceExceptionTranslators from. + Type of the repository attribute to check for. + + + + Return the advice part of this aspect. + + + +

+ An advice may be an interceptor, a throws advice, before advice, + introduction etc. +

+ + + The advice that should apply if the pointcut matches. + + + + + The that drives this advisor. + + + + + + Object post-processor that automatically applies persistence exception + translation to any bean that carries the + attribute, adding a corresponding + to the exposed proxy (either an existing AOP proxy or a newly generated + proxy that implements all of the target's interfaces). + + + Translates native resource exceptions to Spring's + hierarchy. Autodetects object that implement the + interface, which are subsequently asked to translate candidate exceptions. + + All of Spring's applicable resource factories implement the + IPersistenceExceptionTranslator interface out of the box. + As a consequence, all that is usually needed to enable automatic exception + translation is marking all affected objects (such as DAOs) with the + Repository annotation, along with defining this post-processor + in the application context. + + + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + + + + + + + + Just return the passed in object instance + + The new object instance. + The name of the object. + + The passed in object instance + + + In case of errors. + + + + + Add PersistenceExceptionTranslationAdvice to candidate object if it is a match. + Create AOP proxy if necessary or add advice to existing advice chain. + + The new object instance. + The name of the object. + + The object instance to use, wrapped with either the original or a wrapped one. + + + In case of errors. + + + + + Sets the type of the repository attribute. The default required attribute type is the + attirbute. This setter property exists so that developers + can provide their own (non-Spring-specific) attribute type to indicate that a class has a + repository role. + + The desitred type of the repository attribute. + + + + Callback that supplies the owning factory to an object instance. + + + + + Miscellaneous utility methods for DAO implementations. + Useful with any data access technology. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Implementation of PersistenceExceptionTranslator that supports chaining, + allowing the addition of PersistenceExceptionTranslator instances in order. + Returns non-null on the first (if any) match. + + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + + + + Interface implemented by Spring integrations with data access technologies + that throw exceptions. + + + This allows consistent usage of combined exception translation functionality, + without forcing a single translator to understand every single possible type + of exception. + + Rod Johnson + Mark Pollack (.NET) + + + + Translate the given exception thrown by a persistence framework to a + corresponding exception from Spring's generic DataAccessException hierarchy, + if possible. + + + + Do not translate exceptions that are not understand by this translator: + for example, if coming from another persistence framework, or resulting + from user code and unrelated to persistence. + + + Of particular importance is the correct translation to + for example on constraint violation. Implementations may use Spring ADO.NET Framework's + sophisticated exception translation to provide further information in the event of SQLException as a root cause. + + + The exception thrown. + the corresponding DataAccessException (or null if the + exception could not be translated, as in this case it may result from + user code rather than an actual persistence problem) + + + + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + + + + Adds the translator to the translator list. + + The translator. + + + + Translate the given exception thrown by a persistence framework to a + corresponding exception from Spring's generic DataAccessException hierarchy, + if possible. + + The exception thrown. + + the corresponding DataAccessException (or null if the + exception could not be translated, as in this case it may result from + user code rather than an actual persistence problem) + + + + Do not translate exceptions that are not understand by this translator: + for example, if coming from another persistence framework, or resulting + from user code and unrelated to persistence. + + + Of particular importance is the correct translation to + for example on constraint violation. Implementations may use Spring ADO.NET Framework's + sophisticated exception translation to provide further information in the event of SQLException as a root cause. + + + + + + + + Gets all registered IPersistenceExceptionTranslator as an array. + + The IPersistenceExceptionTranslators. + + + + Generic base class for DAOs, defining template methods for DAO initialization. + + + Extended by Spring's specific DAO support classes, such as: + AdoDaoSupport, HibernateDaoSupport, etc. + + Mark Pollack (.NET) + + + + The shared instance for this class (and derived classes). + + + + + Initializes a new instance of the class. + + + + + Abstract subclasses must override this to check their configuration. + + +

Implementors should be marked as sealed, to make it clear that + concrete subclasses are not supposed to override this template method themselves. +

+ + + + + Concrete subclasses can override this for custom initialization behavior. + + + Gets called after population of this instance's object properties. + Exception thrown if InitDao fails will be rethrown as + a ObjectInitializationException. + + + + + Miscellaneous utility methods for DAO implementations. + Useful with any data access technology. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Return a translated exception if this is appropriate, or null if the exception could + not be translated. + + The raw exception we may wish to translate. + The PersistenceExceptionTranslator to use to perform the translation. + A translated exception if translation is possible, or or null if the exception could + not be translated. + + + + AOP MethodInterceptor that provides persistence exception translation + based on a given PersistenceExceptionTranslator. + + + Delegates to the given to translate + an Exception thrown into Spring's DataAccessException hierarchy + (if appropriate). + + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + Needs to be configured with a PersistenceExceptionTranslator afterwards. + + + + + Initializes a new instance of the class for the + given IPersistenceExceptionTranslator + + The persistence exception translator to use. + + + + Initializes a new instance of the class, autodetecting + IPersistenceExceptionTranslators in the given object factory. + + The object factory to obtain all IPersistenceExceptionTranslators from. + + + + Ensures that the property PersistenceExceptionTranslator has been set. + Invoked by an + after it has injected all of an object's dependencies. + + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Detects the petsistence exception translators in the given object factory. + + The object factory for obtaining all IPersistenceExceptionTranslators. + A chained IPersistenceExceptionTranslator, combining all PersistenceExceptionTranslators found in the factory + + + + + + Return a translated exception if this is appropriate, otherwise rethrow the original exception. + + + + + + + Sets the persistence exception translator. The default is to autodetect all IPersistenceExceptionTranslators + in the containing object factory, using them in a chain. + + The persistence exception translator. + + + + Callback that supplies the owning factory to an object instance. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + In case of initialization errors. + + + + + Exception thrown on failure to aquire a lock during an update i.e a select for + update statement. + + +

+ This exception will be thrown either by O/R mapping tools or by custom DAO + implementations. +

+ + Rod Johnson + Griffin Caprio (.NET) + + + + Exception thrown on a pessimistic locking violation. + + + Serves as a superclass for more specific exceptions, like + CannotAcquireLockException and DeadlockLoserDataAccessException + + + This exception will be thrown either by O/R mapping tools or by custom DAO + implementations. + + + Rod Johnson + Mark Pollack (.NET) + + + + Exception thrown on concurrency failure. This exception should be + sublassed to indicate the type of failure - optimistic locking, + failure to acquire lock, etc. + + +

+ This exception will be thrown either by O/R mapping tools or by custom DAO + implementations. +

+ + Thomas Risberg + Griffin Caprio (.NET) + + + + Root of the hierarchy of data access exception that are considered transient - + where a previously failed operation might be able to succeed when the operation + is retried without any intervention by application-level functionality. + + Thomas Risberg + Mark Pollack (.NET) + + + + Root of the hierarchy of data access exceptions + + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception thrown on failure to complete a transaction in serialized mode due to + update conflicts. + + +

+ This exception will be thrown either by O/R mapping tools or by custom DAO + implementations. +

+ + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception thrown when we couldn't cleanup after a data access operation, + but the actual operation went OK. + + +

+ For example, this exception or a subclass might be thrown if an ADO.NET + connection couldn't be closed after it had been used successfully. +

+

+ Note that data access code might perform resource cleanup in a + finally block and therefore log cleanup failure rather than rethrow it, + to keep the original data access exception, if any. +

+ + Rod Johnson + Griffin Caprio (.NET) + + + + Root of the hierarchy of data access exception that are considered non-transient - + where a retry of the same operation would fail unless the cause of the Exception is + corrected. + + Thomas Risberg + Mark Pollack (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Data access exception thrown when a resource fails completely: + for example, if we can't connect to a database using ADO.NET. + + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception thrown when an attempt to insert or update data + results in violation of an integrity constraint. + + +

+ Note that this is not purely a relational concept; unique primary keys are + required by most database types. +

+ + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception thrown if certain expected data could not be retrieved, e.g. + when looking up specific data via a known identifier. + + +

+ This exception will be thrown either by O/R mapping tools or by custom DAO + implementations. +

+ + Juergen Hoeller + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Generic exception thrown when the current process was + a deadlock loser, and its transaction rolled back. + + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Data access exception thrown when a result was not of the expected size, + for example when expecting a single row but getting 0 or more than 1 rows. + + Mark Pollack (.NET) + Juergen Hoeller + + + + Data access exception thrown when a result was not of the expected size, + for example when expecting a single row but getting 0 or more than 1 rows. + + Juergen Hoeller + Griffin Caprio (.NET) + + + + Exception thrown on incorrect usage of the API, such as failing to "compile" a query + object that needed compilation before execution. + + +

+ This represents a problem in our data access framework, not the underlying data access + infrastructure. +

+ + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + The expected result size. + The actual result size (or -1 if unknown). + + + + Creates a new instance of the + class. + > + + A message about the exception. + + The expected result size. + The actual result size (or -1 if unknown). + + + + Initializes a new instance of the class. + + A message about the exception + The expected result size. + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Override of + to allow for private serialization. + + + The + that holds the serialized object data about the exception. + + + The + that contains contextual information about the source or destination. + + + + Return the expected result size. + + + Return the actual result size (or -1 if unknown). + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message. + + + + Initializes a new instance of the class. + + The message. + The inner exception. + + + + Creates a new instance of the + class. + + The expected size. + + + + Creates a new instance of the + class. + + A message about the exception. + The expected size. + + + + Initializes a new instance of the class. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The parameter is . + The class name is or is zero (0). + + + + Data access exception thrown when something unintended appears to have + happened with an update, but the transaction hasn't already been rolled back. + + +

+ Thrown, for example, when we wanted to update 1 row in an RDBMS but actually + updated 3. +

+ + Rod Johnson + Griffin Caprio (.NET) + + + + Root for exceptions thrown when we use a data access resource incorrectly. + + +

+ Thrown for example on specifying bad SQL when using a RDBMS. + Resource-specific subclasses will probably be supplied by data access packages. +

+ + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + Return whether or not data was updated. + + True if data was updated (as opposed to being incorrectly + updated). If this property returns false, there's nothing to roll back. + + + + + Data access exception thrown when a resource fails completely and the failure is permanent. + + Thomas Risberg + Mark Pollack (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception thrown on an optimistic locking violation for a mapped object. + Provides information about the persistent class and the identifier. + + Mark Pollack (.NET) + + + + Exception thrown on an optimistic locking violation. + + +

+ This exception will be thrown either by O/R mapping tools or by custom DAO + implementations. +

+ + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + A message about the exception.. + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception from the underlying data access API + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + When overridden in a derived class, sets the + with information about the exception. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The parameter is a null reference ( in Visual Basic). + + + + Exception thrown if a mapped object could not be retrieved via its identifier. + Provides information about the persistent class and the identifier. + + Mark Pollack (.NET) + + + + Creates a new instance of the + class. + + + + + Initializes a new instance of the class. + + A message about the exception. + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception from the underlying data access API + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + When overridden in a derived class, sets the + with information about the exception. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The parameter is a null reference ( in Visual Basic). + + + + Exception thrown when the underlyingresource denied a permission to + access a specific element, such as a specific database table. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + RDta access exception thrown when a resource fails temporarily and the operation can be + retried. + + Thomas Risberg + Mark Pollack (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception thrown on mismatch between CLS type and database type: + for example on an attempt to set an object of the wrong type + in an RDBMS column. + + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Normal superclass when we can't distinguish anything more specific + than "something went wrong with the underlying resource": for example, + a SQLException from Sql Server that we can't pinpoint more precisely. + + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception (from the underlying data access API, such as ADO.NET). + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Provides database metdata information. + + Mark Pollack (.NET) + + + + Provides minimal database metadata information to support the + functionality in Spring.NET ADO.NET Framework. + + + Mark Pollack (.NET) + + + + Gets a descriptive name of the product. + + Example: Microsoft SQL Server, provider V2.0.0.0 in framework .NET V2.0 + The name of the product. + + + + Gets the type of the connection. The fully qualified type name is given since some providers, + notably for SqlServerCe, do not use the same namespace for all data access types. + + Example: System.Data.SqlClient.SqlCommand, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the connection. + + + + Gets the type of the command. + + Example: System.Data.SqlClient.SqlCommand, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the command. + + + + Gets the type of the parameter. + + Example: System.Data.SqlClient.SqlParameter, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the parameter. + + + + Gets the type of the data adapter. + + Example: System.Data.SqlClient.SqlDataAdapter, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the data adapter. + + + + Gets the type of the command builder. + + Example: System.Data.SqlClient.SqlCommandBuilder, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the command builder. + + + + Gets the type of the exception. + + Example: System.Data.SqlClient.SqlException, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the exception. + + + + Gets the error code exception expression. + + Example Errors[0].Number.ToString() for Sql Server + The error code exception expression. + + + + Gets the command builder derive parameters method. + + If the value 'not supported' is specified then this method will throw an ArgumentException + Example: DeriveParameters + The command builder derive parameters method. + + + + Provide the prefix used to indentify named parameters in SQL text. + + @ for Sql Server + + + + Does the driver require the use of the parameter prefix when + specifying the name of the parameter in the Command's + Parameter collection. + + If true, then commamd.Parameters["@parameterName"] is + used, otherwise, command.Parameters["parameterName"]. + + + + + Gets a value indicating whether the Provider requires + the use of a named prefix in the SQL string. + + + The OLE DB/ODBC .NET Provider does not support named parameters for + passing parameters to an SQL Statement or a stored procedure called + by an IDbCommand when CommandType is set to Text. + + + true if use parameter prefix in SQL; otherwise, false. + + + + + For providers that allow you to choose between binding parameters + to a command by name (true) or by position (false). + + + + + Gets the type of the parameter db. + + Example: System.Data.SqlDbType, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the parameter db. + + + + Gets the parameter db type property. + + Example: SqlDbType for SqlServer + The parameter db type property. + + + + Gets the parameter is nullable property. + + Example: IsNullable for Sql Server + The parameter is nullable property. + + + + Gets or sets the error codes. + + The collection of error codes to map error code integer values to Spring's DAO exception hierarchy + The error codes. + + + + Initializes a new instance of the class. + + Name of the product. + Name of the assembly. + Type of the connection. + Type of the command. + Type of the parameter. + Type of the data adapter. + Type of the command builder. + The command builder derive parameters method. + Type of the parameter db. + The parameter db type property. + The parameter is nullable property. + The parameter name prefix. + Type of the exception. + if set to true [use parameter name prefix in parameter collection]. + if set to true [use parameter prefix in SQL]. + if set to true [bind by name]. + The error code exception expression. + + + + Gets a value indicating whether to use param name prefix in parameter collection. + + + true if should use param name prefix in parameter collection; otherwise, false. + + + + + Gets the name of the assembly. + + Example: System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The name of the assembly. + + + + Gets a descriptive name of the product. + + Example: Microsoft SQL Server, provider V2.0.0.0 in framework .NET V2.0 + The name of the product. + + + + Gets the type of the connection. The fully qualified type name is given since some providers, + notably for SqlServerCe, do not use the same namespace for all data access types. + + Example: System.Data.SqlClient.SqlCommand, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the connection. + + + + Gets the type of the command. + + Example: System.Data.SqlClient.SqlCommand, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the command. + + + + Gets the type of the parameter. + + Example: System.Data.SqlClient.SqlParameter, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the parameter. + + + + Gets the type of the data adapter. + + Example: System.Data.SqlClient.SqlDataAdapter, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the data adapter. + + + + Gets the type of the command builder. + + Example: System.Data.SqlClient.SqlCommandBuilder, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the command builder. + + + + Gets the command builder derive parameters method. + + If the value 'not supported' is specified then this method will throw an ArgumentException + Example: DeriveParameters + The command builder derive parameters method. + + + + Provide the prefix used to indentify named parameters in SQL text. + + @ for Sql Server + + + + Gets the type of the exception. + + Example: System.Data.SqlClient.SqlException, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the exception. + + + + Does the driver require the use of the parameter prefix when + specifying the name of the parameter in the Command's + Parameter collection. + + + If true, then commamd.Parameters["@parameterName"] is + used, otherwise, command.Parameters["parameterName"]. + + + + + Gets a value indicating whether the Provider requires + the use of a named prefix in the SQL string. + + + true if use parameter prefix in SQL; otherwise, false. + + + The OLE DB/ODBC .NET Provider does not support named parameters for + passing parameters to an SQL Statement or a stored procedure called + by an IDbCommand when CommandType is set to Text. + + + + + For providers that allow you to choose between binding parameters + to a command by name (true) or by position (false). + + + + + + Gets the type of the parameter db. + + Example: System.Data.SqlDbType, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + The type of the parameter db. + + + + Gets the parameter db type property. + + Example: SqlDbType for SqlServer + The parameter db type property. + + + + Gets the parameter is nullable property. + + Example: IsNullable for Sql Server + The parameter is nullable property. + + + + Gets or sets the error codes. + + The collection of error codes to map error code integer values to Spring's DAO exception hierarchy + The error codes. + + + + Gets the error code exception expression. + + Example Errors[0].Number.ToString() for Sql Server + The error code exception expression. + + + + A parameter class used by + + Mark Pollack (.NET) + + + + A parameter interface used by + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + Sets the SourceVersion to be Default and the ParameterDirection to be Input. + + + + + A more portable means to create a collection of ADO.NET + parameters. + + Mark Pollack (.NET) + + + + Determines whether this collection contains the specified parameter name. + + Name of the parameter. + + true if contains the specified parameter name; otherwise, false. + + + + + Add an instance of . + + + + + + Add a parameter specifying the all the individual properties of a + IDbDataParameter. + + + + + + + + + + + + The newly created parameter + + + + + + + + + + + + + + + The newly created parameter + + + + Adds a value to the parameter collection + + This method can not be used with stored procedures for + providers that require named parameters. However, it is of + great convenience for other cases. + The value of the parameter. + Index of added parameter. + + + + Adds a range of vlaues to the parameter collection. + + This method can not be used with stored procedures for + providers that require named parameters. However, it is of + great convenience for other cases. + + + + + Gets the underlying standard ADO.NET for the specified parameter name. + + + + + Gets the underlying standard ADO.NET for the specified index. + + + + + Returns the underlying standard ADO.NET parameters collection. + + + + + Initializes a new instance of the class. + + + + + Assists in creating a collection of parameters by keeping track of all + IDbParameters its creates. After creating a number of parameters ask for the collection + with the GetParameters methods. + + This builder is stateful, you must create a new one for each collection + of parameters you would like to create. + Mark Pollack (.NET) + + + + A builder to create a collection of ADO.NET parameters. + + The chaining of IDbParameter methods does the + building of the parameter details while the builder class + itself keeps track of the collection. + + Mark Pollack (.NET) + + + + Creates a IDbParameter object and adds it to an internal collection for + later retrieval via the GetParameters method. + + + + + + Gets all the parameters created and configured via the Create method. + + An instance of IDbParameters + + + + The shared log instance for this class (and derived classes). + + + + + Initializes a new instance of the class. + + + + + Implemenation of of DbProvider that uses metadata to create provider specific ADO.NET objects. + + + + + Factory interface to create provider specific ADO.NET objects. + + + + + Returns a new command object for executing SQL statments/Stored Procedures + against the database. + + An new + + + + Returns a new instance of the providers CommandBuilder class. + + In .NET 1.1 there was no common base class or interface + for command builders, hence the return signature is object to + be portable (but more loosely typed) across .NET 1.1/2.0 + A new Command Builder + + + + Returns a new connection object to communicate with the database. + + A new + + + + Returns a new adapter objects for use with offline DataSets. + + A new + + + + Returns a new parameter object for binding values to parameter + placeholders in SQL statements or Stored Procedure variables. + + A new + + + + Creates the name of the parameter in the format appropriate to use inside IDbCommand.CommandText. + + In most cases this adds the parameter prefix to the name passed into this method. + The unformatted name of the parameter. + The parameter name formatted foran IDbCommand.CommandText. + + + + Creates the name ofthe parameter in the format appropriate for an IDataParameter, i.e. to be + part of a IDataParameterCollection. + + The unformatted name of the parameter. + The parameter name formatted for an IDataParameter + + + + Extracts the provider specific error code as a string. + + The data access exception. + The provider specific error code + + + + Determines whether the provided exception is in fact related + to database access. This can be provider dependent in .NET 1.1 since + there isn't a common base class for ADO.NET exceptions. + + The exception thrown when performing data access + operations. + + true if is a valid data access exception for the specified + exception; otherwise, false. + + + + + Return metadata information about the database provider + + + + + Connection string used to create connections. + + + + + Initializes a new instance of the class. + + The db metadata. + + + + Returns a new command object for executing SQL statments/Stored Procedures + against the database. + + An new + + + + Returns a new instance of the providers CommandBuilder class. + + A new Command Builder + In .NET 1.1 there was no common base class or interface + for command builders, hence the return signature is object to + be portable (but more loosely typed) across .NET 1.1/2.0 + + + + Returns a new connection object to communicate with the database. + + A new + + + + Returns a new adapter objects for use with offline DataSets. + + A new + + + + Returns a new parameter object for binding values to parameter + placeholders in SQL statements or Stored Procedure variables. + + A new + + + + Creates the name of the parameter in the format appropriate to use inside IDbCommand.CommandText. + + The unformatted name of the parameter. + + The parameter name formatted foran IDbCommand.CommandText. + + In most cases this adds the parameter prefix to the name passed into this method. + + + + Creates the name ofthe parameter in the format appropriate for an IDataParameter, i.e. to be + part of a IDataParameterCollection. + + The unformatted name of the parameter. + + The parameter name formatted for an IDataParameter + + + + + Extracts the provider specific error code as a string. + + The data access exception. + The provider specific error code + + + + Determines whether the provided exception is in fact related + to database access. This can be provider dependent in .NET 1.1 since + there isn't a common base class for ADO.NET exceptions. + + The exception thrown when performing data access + operations. + + true if is a valid data access exception for the specified + exception; otherwise, false. + + + + + Determines whether is data access exception in .NET 1.1 for the specified exception. + + The candidate exception. + + true if is data access exception in .NET 1.1 for the specified exception; otherwise, false. + + + + + Return metadata information about the database provider + + + + + + Connection string used to create connections. + + + + + + + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Modify the application context's internal object factory after its + standard initialization. + + The object factory used by the application context. + +

+ All object definitions will have been loaded, but no objects will have + been instantiated yet. This allows for overriding or adding properties + even to eager-initializing objects. +

+ + + In case of errors. + + + + + Gets or sets the provider resource which contains additional IDbProvider definitions. + + The provider resource. + + + + Create DbProviders based on configuration information in assembly resource + dbproviders.xml + + + + + TODO: Provide over-ride resource location. + TODO: Add error codes to provider. + + Mark Pollack (.NET) + + + + The shared log instance for this class (and derived classes). + + + + + Initializes a new instance of the class. + + + + + Gets the DbProvider given an identifying name. + + + Familiar names for the .NET 2.0 provider model are supported, i.e. + System.Data.SqlClient. Refer to the documentation for a complete + listing of supported DbProviders and their names. You may + also use the method GetDbProviderClasses or obtain the + underlying IApplicationContext to progammatically obtain information + about supported providers. + + Name of the provider invariant. + + + + + Gets the application context that contains the definitions of the + various providers. + + This method should rarely, if ever, be used in + application code. It is used by the framework itself + to map other data access products abstractions for a 'DbProvider/DataSource' + onto Spring's model. + The application context. + + + + A implementation that + creates instances of the class. + + Typically used as a convenience for retrieving shared + in a Spring XML configuration file as compared to + using explict factory method support. + + + + + Creates a new instance of the class. + + + + + Return an instance of and IDbProvider as configured by this factory + managed by this factory. + + + The same (singleton) instance of the IDbProvider managed by + this factory. + + + + If this method is being called in the context of an enclosing IoC container and + returns , the IoC container will consider this factory + object as not being fully initialized and throw a corresponding (and most + probably fatal) exception. + + + + + + Create the actual provider instance as specified by this factory's configuration properties. + + the fully configured provider + + + + Validates that the provider name is specified. + + + Invoked by an + after it has injected all of an object's dependencies. + + + In the event of not setting the ProviderName. + + + + + Validates the properties. + + + + + Gets or sets the name of the database provider. + + The name of the database provider. + + + + Gets or sets the connection string. + + The connection string. + + + + Return the type of + + + + + Returns true, as the the object managed by this factory is a singleton. + + + + + + IDbProvider implementation that delegates all calls to a given target + IDbProvider + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The target db provider. + + + + Returns a new command object for executing SQL statments/Stored Procedures + against the database. + + An new + + + + Returns a new instance of the providers CommandBuilder class. + + In .NET 1.1 there was no common base class or interface + for command builders, hence the return signature is object to + be portable (but more loosely typed) across .NET 1.1/2.0 + A new Command Builder + + + + Returns a new connection object to communicate with the database. + + A new + + + + Returns a new adapter objects for use with offline DataSets. + + A new + + + + Returns a new parameter object for binding values to parameter + placeholders in SQL statements or Stored Procedure variables. + + A new + + + + Creates the name of the parameter in the format appropriate to use inside IDbCommand.CommandText. + + In most cases this adds the parameter prefix to the name passed into this method. + The unformatted name of the parameter. + The parameter name formatted foran IDbCommand.CommandText. + + + + Creates the name ofthe parameter in the format appropriate for an IDataParameter, i.e. to be + part of a IDataParameterCollection. + + The unformatted name of the parameter. + The parameter name formatted for an IDataParameter + + + + Extracts the provider specific error code as a string. + + The data access exception. + The provider specific error code + + + + Determines whether the provided exception is in fact related + to database access. This can be provider dependent in .NET 1.1 since + there isn't a common base class for ADO.NET exceptions. + + The exception thrown when performing data access + operations. + + true if is a valid data access exception for the specified + exception; otherwise, false. + + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Gets or sets the target IDbProvider that this IDbProvider should delegate to + + The target db provider. + + + + Return metadata information about the database provider + + + + + Connection string used to create connections. + + + + + Holds ADO.NET error codes for a particular provider. + + + Used by ErrorCodeExceptionTranslator. The embedded resource + "dbProviders.xml" in Spring.Data.Common contains default + ErrorCodes instances for various providers. + + Mark Pollack (.NET) + + + + The shared log instance for this class (and derived classes). + + + + + Initializes a new instance of the class. + + + + + A wrapper implementation for IDbProvider such that multiple DbProvider instances can be + selected at runtime, say based on web request criteria. + + + The name of which DbProvider to use, as provided to the IDictionary property TargetDbProviders + is "dbProviderName". Once the target dbprovider name is known, set the name via a call to + LogicalThreadContext.SetData(MultiDelegatingDbProvider.CURRENT_DBPROVIDER_SLOTNAME, "database1ProviderName"). The value + "database1ProviderName" must match a key in the provided TargetDbProviders dictionary. + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The target db providers. + + + + Ensures that the there are values in the TargetDbProviders dictionary and that the + key is of the type string and value is of the type IDbProvider. + + If the above conditions are not met. + + + + Returns a new command object for executing SQL statments/Stored Procedures + against the database. + + An new + + + + Returns a new connection object to communicate with the database. + + A new + + + + Returns a new parameter object for binding values to parameter + placeholders in SQL statements or Stored Procedure variables. + + A new + + + + Returns a new adapter objects for use with offline DataSets. + + A new + + + + Returns a new instance of the providers CommandBuilder class. + + A new Command Builder + In .NET 1.1 there was no common base class or interface + for command builders, hence the return signature is object to + be portable (but more loosely typed) across .NET 1.1/2.0 + + + + Creates the name of the parameter in the format appropriate to use inside IDbCommand.CommandText. + + The unformatted name of the parameter. + + The parameter name formatted foran IDbCommand.CommandText. + + In most cases this adds the parameter prefix to the name passed into this method. + + + + Creates the name ofthe parameter in the format appropriate for an IDataParameter, i.e. to be + part of a IDataParameterCollection. + + The unformatted name of the parameter. + + The parameter name formatted for an IDataParameter + + + + + Extracts the provider specific error code as a string. + + The data access exception. + The provider specific error code + + + + Determines whether the provided exception is in fact related + to database access. This can be provider dependent in .NET 1.1 since + there isn't a common base class for ADO.NET exceptions. + + The exception thrown when performing data access + operations. + + true if is a valid data access exception for the specified + exception; otherwise, false. + + + + + Determines whether is data access exception in .NET 1.1 for the specified exception. + + The candidate exception. + + true if is data access exception in .NET 1.1 for the specified exception; otherwise, false. + + + + + Gets the target provider based on the thread local name "dbProviderName" + + The corresonding IDbProvider. + + + + Sets the default IDbProvider. This will be returned if no DbProvider is found in thread local storage. + + The default db provider. + + + + Sets the target db providers. + + The target db providers. + + + + Return metadata information about the database provider + + + + + + Connection string used to create connections. + + + + + + Convenience method to sets the name of the DbProvider that will be used for the + the current thread's procesing. + + The name of the DbProvider to use for the current threads processing. + + + + An adapter for a target IDbProvider, applying the specified user credentials + to the connection string for every GetConnection call. + + + + + Sets the user credentials for current thread. The given username and password + strings will be added to the connection string for all subsequent GetConnection + requests. This will override any statically specified user credentials, that is, + set by the properties Username nad Password. + + The username part of the connection string. + The password part of the connection string. + + + + Removes the user credentials from current thread. Use statically specified + credentials afterwards. + + + + + Returns a new connection object to communicate with the database. + Determine if there are currently thread-bound credentials, using them if + available, falling back to the statically specified username and password + (i.e. values of the properties 'Username' and 'Password') otherwise. + The username and password will be concatenated on the connection string + using string in the Separator property + + A new + + + + Sets the username string that will be appended to the connection string. + + The username. + + + + Sets the password string that will be appended to the connection string. + + The password. + + + + Sets the separator used to separate elements of the connection string. Default is ';'. + + + The separator used to separate elements in the connection string. + + + + Implementation of the custom configuration parser for database definitions. + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Parse the specified element and register any resulting + IObjectDefinitions with the IObjectDefinitionRegistry that is + embedded in the supplied ParserContext. + + The element to be parsed into one or more IObjectDefinitions + The object encapsulating the current state of the parsing + process. + + The primary IObjectDefinition (can be null as explained above) + + + Implementations should return the primary IObjectDefinition + that results from the parse phase if they wish to used nested + inside (for example) a <property> tag. + Implementations may return null if they will not + be used in a nested scenario. + + + + + + Parses database provider definitions. + + Validator XML element. + The name of the object definition. + The parser context. + A database provider object definition. + + + + Gets the name of the object type for the specified element. + + The element. + The name of the object type. + + + + Base class for AdoTemplate and other ADO.NET DAO helper classes defining + common properties like DbProvider. + + Mark Pollack (.NET) + Juergen Hoeller + + + + Prepare the command setting the transaction timeout. + + + + + + Dispose the command, if any + + + + + Dispose the command, if any + + + + + Extract the command text from the given , if any. + + + + + Obtain a connection/transaction pair + + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Creates the data reader wrapper for use in AdoTemplate callback methods. + + The reader to wrap. + The data reader used in AdoTemplate callbacks + + + + Creates the a db parameters collection, adding to the collection a parameter created from + the method parameters. + + The name of the parameter + The type of the parameter. + The size of the parameter, for use in defining lengths of string values. Use + 0 if not applicable. + The parameter value. + A collection of db parameters with a single parameter in the collection based + on the method parameters + + + + Creates a new instance of + + a new instance of + + + + Derives the parameters of a stored procedure, not including the return parameter. + + Name of the procedure. + The stored procedure parameters. + + + + Derives the parameters of a stored procedure including the return parameter + + Name of the procedure. + if set to true to include return parameter. + The stored procedure parameters + + + + An instance of a DbProvider implementation. + + + + + Gets or sets a value indicating whether to lazily initialize the + IAdoExceptionTranslator for this accessor, on first encounter of a + exception from the data provider. Default is "true"; can be switched to + "false" for initialization on startup. + + true if to lazy initialize the IAdoExceptionTranslator; + otherwise, false. + + + + Gets or sets the exception translator. If no custom translator is provided, a default + is used. + + The exception translator. + + + + Gets or set the System.Type to use to create an instance of IDataReaderWrapper + for the purpose of having defaults values to use in case of DBNull values read + from IDataReader. + + The type of the data reader wrapper. + + + + Gets or sets the command timeout for IDbCommands that this AdoTemplate executes. + + Default is 0, indicating to use the database provider's default. + Any timeout specified here will be overridden by the remaining + transaction timeout when executing within a transaction that has a + timeout specified at the transaction level. + + The command timeout. + + + + Convenient super class for ADO.NET data access objects. + + + Requires a IDBProvider to be set, providing a + AdoTemplate based on it to subclasses. + This base class is mainly intended for AdoTemplate usage. + + + + + Create a AdoTemplate for a given DbProvider + Only invoked if populating the DAO with a DbProvider reference. + + + Can be overriden in subclasses to provide AdoTemplate instances + with a different configuration, or a cusotm AdoTemplate subclass. + + The DbProvider to create a AdoTemplate for + + + + Convenience method to create a parameters builder. + + Virtual for sublcasses to override with custom + implementation. + A new DbParameterBuilder + + + + The DbProvider instance used by this DAO + + + + + Set the AdoTemplate for this DAO explicity, as + an alternative to specifying a IDbProvider + + + + + ADO.NET based implementation of the + interface. + + Mark Pollack (.NET) + + + + Abstract base class that allows for easy implementation of concrete platform transaction managers. + + +

Provides the following workflow handling: +

    +
  • Determines if there is an existing transaction
    • +
  • Applies the appropriate propagation behavior
    • +
  • Suspends and resumes transactions if necessary
    • +
  • Checks the rollback-only flag on commit
    • +
  • Applies the appropriate modification on rollback (actual rollback or setting rollback-only)
    • +
  • Triggers registered synchronization callbacks (if transaction synchronization is active)
    • +
+

+

+ Transaction synchronization is a generic mechanism for registering + callbacks that get invoked at transaction completion time. The same mechanism + can also be used for custom synchronization efforts. +

+

+ The state of this class is serializable. It's up to subclasses if + they wish to make their state to be serializable. + They should implement if they need + to restore any transient state. +

+ + Juergen Hoeller + Mark Pollack (.NET) + Griffin Caprio (.NET) + + + + This is the central interface in Spring.NET's transaction support. + + +

+ Applications can use this directly, but it is not primarily meant as an API. + Typically, applications will work with either + or the AOP transaction + interceptor. +

+

+ For implementers, + is a good starting point. +

+ + Rod Johnson + Juergen Hoeller + Griffin Caprio (.NET) + + + + Return a currently active transaction or create a new one. + + +

+ Note that parameters like isolation level or timeout will only be applied + to new transactions, and thus be ignored when participating in active ones. + Furthermore, they aren't supported by every transaction manager: + a proper implementation should throw an exception when custom values + that it doesn't support are specified. +

+ + + instance (can be null for + defaults), describing propagation behavior, isolation level, timeout etc. + + + In case of lookup, creation, or system errors. + + + A representing the new or current transaction. + + + + + Commit the given transaction, with regard to its status. + + +

+ If the transaction has been marked rollback-only programmatically, + perform a rollback. +

+

+ If the transaction wasn't a new one, omit the commit to take part + in the surrounding transaction properly. +

+ + + The instance returned by the + () method. + + + In case of commit or system errors + + + + + Roll back the given transaction, with regard to its status. + + +

+ If the transaction wasn't a new one, just set it rollback-only + to take part in the surrounding transaction properly. +

+ + + The instance returned by the + () method. + + + In case of system errors. + + + + + Return the current transaction object. + + The current transaction object. + + If transaction support is not available. + + + In the case of lookup or system errors. + + + + + Check if the given transaction object indicates an existing transaction + (that is, a transaction which has already started). + + + The result will be evaluated according to the specified propagation + behavior for the new transaction. An existing transaction might get + suspended (in case of PROPAGATION_REQUIRES_NEW), or the new transaction + might participate in the existing one (in case of PROPAGATION_REQUIRED). + Default implementation returns false, assuming that detection of or + participating in existing transactions is generally not supported. + Subclasses are of course encouraged to provide such support. + + Transaction object returned by + . + + True if there is an existing transaction. + + In the case of system errors. + + + + + Begin a new transaction with the given transaction definition. + + + Does not have to care about applying the propagation behavior, + as this has already been handled by this abstract manager. + + + Transaction object returned by + . + + + instance, describing + propagation behavior, isolation level, timeout etc. + + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + + Transaction synchronization will already have been suspended. + + Default implementation throws a TransactionSuspensionNotSupportedException, + assuming that transaction suspension is generally not supported. + + + + Transaction object returned by + . + + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + If suspending is not supported by the transaction manager implementation. + + + in case of system errors. + + + + + Resume the resources of the current transaction. + + Transaction synchronization will be resumed afterwards. + + Default implementation throws a TransactionSuspensionNotSupportedException, + assuming that transaction suspension is generally not supported. + + + + Transaction object returned by + . + + + The object that holds suspended resources as returned by + . + + + If suspending is not supported by the transaction manager implementation. + + + In the case of system errors. + + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + +

+ An implementation does not need to check the rollback-only flag. +

+ + + In the case of system errors. + + + + + Perform an actual rollback on the given transaction. + + The status representation of the transaction. + + An implementation does not need to check the new transaction flag. + + + In the case of system errors. + + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + Default implementation throws an IllegalTransactionStateException, + assuming that participating in existing transactions is generally not + supported. Subclasses are of course encouraged to provide such support. + + The status representation of the transaction. + + In the case of system errors. + + + + + Return whether to use a savepoint for a nested transaction. Default is true, + which causes delegation to + for holding a savepoint. + + + +

+ Subclasses can override this to return false, causing a further + invocation of + + despite an already existing transaction. +

+ + + + + Register the given list of transaction synchronizations with the existing transaction. + + + Invoked when the control of the Spring transaction manager and thus all Spring + transaction synchronizations end, without the transaction being completed yet. This + is for example the case when participating in an existing System.Transactions or + EnterpriseServices transaction invoked via their APIs. + + The default implementation simply invokes the AfterCompletion methods + immediately, passing in TransactionSynchronizationStatus.Unknown. + This is the best we can do if there's no chance to determine the actual + outcome of the outer transaction. + + + The transaction transaction object returned by DoGetTransaction. + The lList of TransactionSynchronization objects. + In case of errors + + + + + + + Cleanup resources after transaction completion. + + + Transaction object returned by + . + + + + Called after + and + + execution on any outcome. + + + Should not throw any exceptions but just issue warnings on errors. + + + Default implementation does nothing. + + + + + + Return a currently active transaction or create a new one. + + +

+ This implementation handles propagation behavior. +

+

+ Delegates to + , + , + and + . +

+

+ Note that parameters like isolation level or timeout will only be applied + to new transactions, and thus be ignored when participating in active ones. + Furthermore, they aren't supported by every transaction manager: + a proper implementation should throw an exception when custom values + that it doesn't support are specified. +

+ + + instance (can be null for + defaults), describing propagation behavior, isolation level, timeout etc. + + + In case of lookup, creation, or system errors. + + + representing the new or current transaction. + + + + + This implementation of commit handles participating in existing transactions + and programmatic rollback requests. + + + + + ITransactionStatus object returned by the + () method. + + + In case of commit or system errors. + + + + + Roll back the given transaction, with regard to its status. + + +

+ This implementation handles participating in existing transactions. +

+

+ Delegates to + , + and + . +

+

+ If the transaction wasn't a new one, just set it rollback-only + to take part in the surrounding transaction properly. +

+ + + ITransactionStatusObject returned by the + () method. + + + In case of system errors. + + + + + Determines the timeout to use for the given definition. Will fall back to this manager's default + timeout if the transaction definition doesn't specify a non-default value. + + The transaction definition. + the actual timeout to use. + + + + Suspend the given transaction. Suspends transaction synchronization first, + then delegates to the doSuspend template method. + + the current transaction object + an object that holds suspended resources + + + + Resume the given transaction. Delegates to the doResume template method + first, then resuming transaction synchronization. + + the current transaction object + the object that holds suspended resources, as returned by suspend + + + + Invoke doRollback, handling rollback exceptions properly. + + object representing the transaction + the thrown application exception or error + + in case of a rollback error + + + + + Trigger beforeCommit callback. + + object representing the transaction + + + + Trigger beforeCompletion callback. + + object representing the transaction + + + + Trigger afterCompletion callback, handling exceptions properly. + + object representing the transaction + + Completion status according to + + + + + Clean up after completion, clearing synchronization if necessary, + and invoking doCleanupAfterCompletion. + + object representing the transaction + + + + Sets and gets when this transaction manager should activate the thread-bound + transaction synchronization support. Default is "always". + + +

+ Note that transaction synchronization isn't supported for + multiple concurrent transactions by different transaction managers. + Only one transaction manager is allowed to activate it at any time. +

+ + + + + + Sets and gets whether nested transactions are allowed. Default is false. + + +

+ Typically initialized with an appropriate default by the + concrete transaction manager subclass. +

+ + + + + Sets and gets a flag that determines whether or not the + + method must be invoked if a call to the + + method fails. Default is false. + + + Typically not necessary and thus to be avoided as it can override the + commit exception with a subsequent rollback exception. + + + + + Gets or sets a value indicating whether to fail early in case of the transaction being + globally marked as rollback-only. + + + Default is "false", only causing an UnexpectedRollbackException at the + outermost transaction boundary. Switch this flag on to cause an + UnexpectedRollbackException as early as the global rollback-only marker + has been first detected, even from within an inner transaction boundary. + + + true if fail early on global rollback; otherwise, false. + + + + + Gets or sets the default timeout that this transaction manager should apply if there + is no timeout specified at the transaction level, in seconds. + + Returns DefaultTransactionDefinition.TIMEOUT_DEFAULT to indicate the + underlying transaction infrastructure's default timeout. + The default timeout. + + + + Extension of the + interface, indicating a native resource transaction manager, operating on a single + target resource. Such transaction managers differ from DTC based transaction managers in + that they do not use transaction enlistment for an open number of resources but + rather focus on leveraging the native power and simplicity of a single target resource. + + + This interface is mainly used for abstract introspection of a transaction manager, + giving clients a hint on what kind of transaction manager they have been given + and on what concrete resource the transaction manager is operating on. + + Juergen Hoeller + Mark Pollack + + + + Gets the resource factory that this transaction manager operates on, + e.g. a IDbProvider or a Hibernate ISessionFactory. + + The resource factory. + + + + Return the current transaction object. + + The current transaction object. + + If transaction support is not available. + + + In the case of lookup or system errors. + + + + + Check if the given transaction object indicates an existing, + i.e. already begun, transaction. + + + Transaction object returned by + . + + True if there is an existing transaction. + + In the case of system errors. + + + + + Begin a new transaction with the given transaction definition. + + + Transaction object returned by + . + + + instance, describing + propagation behavior, isolation level, timeout etc. + + + Does not have to care about applying the propagation behavior, + as this has already been handled by this abstract manager. + + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + Transaction object returned by + . + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + Transaction synchronization will already have been suspended. + + + If suspending is not supported by the transaction manager implementation. + + + in case of system errors. + + + + + Resume the resources of the current transaction. + + Transaction object returned by + . + The object that holds suspended resources as returned by + . + + Transaction synchronization will be resumed afterwards. + + + If suspending is not supported by the transaction manager implementation. + + + In the case of system errors. + + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + +

+ An implementation does not need to check the rollback-only flag. +

+ + + In the case of system errors. + + + + + Perform an actual rollback on the given transaction. + + The status representation of the transaction. + + An implementation does not need to check the new transaction flag. + + + In the case of system errors. + + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + The status representation of the transaction. + + In the case of system errors. + + + + + Invoked by an + after it has injected all of an object's dependencies. + + + If DbProvider is null. + + + + + Gets the resource factory that this transaction manager operates on, + For the AdoPlatformTransactionManager this is the DbProvider + + The DbProvider. + + + + DbProvider transaction (state) object, representing a ConnectionHolder. + Used as a transaction object by AdoPlatformTransactionManager + + Derives from AdoTransactionObjectSupport to inherit the capability + to manage Savepoints. + + + + + + Convenient base class for ADO.NET transaction aware objects. + + + Can contain a ConnectionHolder object. + + Mark Pollack (.NET) + + + + Interface that specifies means to programmatically manage + transaction savepoints in a generic fashion. + + +

+ Note that savepoints can only work within an active transaction. + Just use this programmatic savepoint handling for advanced needs; + else, a subtransaction with a value + of is preferable. +

+ + Juergen Hoeller + Griffin Caprio (.NET) + + + + Create a new savepoint. + + + The name of the savepoint to create. + + + You can roll back to a specific savepoint + via , + and explicitly release a savepoint that you don't need anymore via + . +

+ Note that most transaction managers will automatically release + savepoints at transaction completion. +

+ + + If the savepoint could not be created, + either because the backend does not support it or because the + transaction is not in an appropriate state. + + + A savepoint object, to be passed into + + or . + + + + + Roll back to the given savepoint. + + + The savepoint will be automatically released afterwards. + + The savepoint to roll back to. + + If the rollback failed. + + + + + Explicitly release the given savepoint. + + +

+ Note that most transaction managers will automatically release + savepoints at transaction completion. +

+

+ Implementations should fail as silently as possible if + proper resource cleanup will still happen at transaction completion. +

+ + The savepoint to release. + + If the release failed. + + + + + Interface to be implemented by transaction objects that are able to + return an internal rollback-only marker, typically from a another + transaction that has participated and marked it as rollback-only. + + +

+ Autodetected by , + to always return a current rollbackOnly flag even if not resulting from the current + . +

+ + Juergen Hoeller + Griffin Caprio (.NET) + + + + Return whether the transaction is internally marked as rollback-only. + + True of the transaction is marked as rollback-only. + + + + The shared log instance for this class (and derived classes). + + + + + Create a new savepoint. + + + The name of the savepoint to create. + + + You can roll back to a specific savepoint + via , + and explicitly release a savepoint that you don't need anymore via + . +

+ Note that most transaction managers will automatically release + savepoints at transaction completion. +

+ + + If the savepoint could not be created, + either because the backend does not support it or because the + transaction is not in an appropriate state. + + + A savepoint object, to be passed into + + or . + + + + + Roll back to the given savepoint. + + + The savepoint will be automatically released afterwards. + + The savepoint to roll back to. + + If the rollback failed. + + + + + Explicitly release the given savepoint. + + +

+ Note that most transaction managers will automatically release + savepoints at transaction completion. +

+

+ Implementations should fail as silently as possible if + proper resource cleanup will still happen at transaction completion. +

+ + The savepoint to release. + + If the release failed. + + + + + Return whether the transaction is internally marked as rollback-only. + + + True of the transaction is marked as rollback-only. + + + + Sets the rollback only. + + + + + Return whether the transaction is internally marked as rollback-only. + + + True of the transaction is marked as rollback-only. + + + + This is the central class in the Spring.Data namespace. + It simplifies the use of ADO.NET and helps to avoid commons errors. + + Mark Pollack (.NET) + + + + Interface that defines ADO.NET related database operations. + + Mark Pollack (.NET) + + + + Execute the query with the specified command text returning a scalar result + + No parameters are used. As with + IDbCommand.ExecuteScalar, it returns the first column of the first row in the resultset + returned by the query. Extra columns or row are ignored. + The command type + The command text to execute. + The first column of the first row in the result set. + + + + Execute the query with the specified command text and parameter returning a scalar result + + The command type + The command text to execute. + The name of the parameter to map. + One of the database parameter type enumerations. + The length of the parameter. 0 if not applicable to parameter type. + The parameter value. + The first column of the first row in the result set + + + + Execute the query with the specified command text and parameters returning a scalar result + + The command type + The command text to execute. + The parameter collection to map. + The first column of the first row in the result set + + + + Execute the query with the specified command text and parameters set via the + command setter, returning a scalar result + + The command type + The command text to execute. + The command setter. + The first column of the first row in the result set + + + + Execute the query with a command created via IDbCommandCreator and + parameters + + Output parameters can be retrieved via the returned + dictionary. + + More commonly used as a lower level support method within the framework, + for example StoredProcedure/AdoScalar. + + + The callback to create a IDbCommand. + A dictionary containing output parameters, if any + + + + Executes a non query returning the number of rows affected. + + The command type. + The command text to execute. + The number of rows affected. + + + + Executes a non query returning the number of rows affected. + + The command type. + The command text to execute. + The name of the parameter to map. + One of the database parameter type enumerations. + The length of the parameter. 0 if not applicable to parameter type. + The parameter value. + The number of rows affected. + + + + Executes a non query returning the number of rows affected. + + The command type. + The command text to execute. + The parameter collection to map. + The number of rows affected. + + + + Executes a non query with parameters set via the + command setter, returning the number of rows affected. + + The command type. + The command text to execute. + The command setter. + The number of rows affected. + + + + Executes a non query with a command created via IDbCommandCreator and + parameters. + + Output parameters can be retrieved via the returned + dictionary. + + More commonly used as a lower level support method within the framework, + for example StoredProcedure/AdoScalar. + + + The callback to create a IDbCommand. + The number of rows affected. + + + + Execute a query given IDbCommand's type and text, reading a + single result set on a per-row basis with a . + + The type of command. + The text of the query. + callback that will extract results + one row at a time. + + + + + Execute a query given IDbCommand's type and text and provided parameter + information, reading a + single result set on a per-row basis with a . + + The type of command + The text of the query. + callback that will extract results + one row at a time. + + The name of the parameter to map. + One of the database parameter type enumerations. + The length of the parameter. 0 if not applicable to parameter type. + The parameter value. + + + + Execute a query given IDbCommand's type and text and provided IDbParameters, + reading a single result set on a per-row basis with a . + + Type of the command. + The text of the query. + callback that will extract results + one row at a time. + The parameter collection to map. + + + + Execute a query given IDbCommand's type and text by + passing the created IDbCommand to a ICommandSetter implementation + that knows how to bind values to the IDbCommand, reading a + single result set on a per-row basis with a . + + The type of command + The text of the query. + callback that will extract results + one row at a time. + + The command setter. + + + + Execute a ADO.NET operation on a command object using a delegate callback. + + This allows for implementing arbitrary data access operations + on a single command within Spring's managed ADO.NET environment. + The delegate called with a command object. + A result object returned by the action or null + + + + Execute a ADO.NET operation on a command object using an interface based callback. + + the callback to execute + object returned from callback + + + + Executes ADO.NET operations on a command object, created by the provided IDbCommandCreator, + using the interface based callback IDbCommandCallback. + + The command creator. + The callback to execute based on IDbCommand + A result object returned by the action or null + + + + Execute ADO.NET operations on a IDbDataAdapter object using an interface based callback. + + This allows for implementing abritrary data access operations + on a single DataAdapter within Spring's managed ADO.NET environment. + + The data adapter callback. + A result object returned by the callback or null + + + + Execute a query given IDbCommand's type and text, processing a + single result set with an instance of IResultSetExtractor + + The type of command + The text of the query. + Object that will extract all rows of a result set + An arbitrary result object, as returned by the IResultSetExtractor + + If there is any problem executing the query. + + + + + Execute a query given the CommandType and text with parameters set + via the command setter, processing a + single result set with an instance of IResultSetExtractor + + The command type. + The command text to execute. + The result set extractor. + The command setter. + An arbitrary result object, as returned by the IResultSetExtractor + + If there is any problem executing the query. + + + + + Execute a query given the CommandType and text specifying a single parameter and process a single result set with an + instance of IResultSetExtractor. + + Convention is to use 0 For the size if it does not make sense for the given data type + + The command type. + The command text to execute. + The result set extractor. + The name of the parameters + The enumeration of the parameter type + The size of the parmeter - e.g. string length. Use 0 if not relevant for specific data type + The value of the parameters + An arbitrary result object, as returned by the IResultSetExtractor + + If there is any problem executing the query. + + + + + Execute a query given the CommandType and text specifying a collection of parameters and process a single result set with an + instance of IResultSetExtractor. + + The command type. + The command text to execute. + The result set extractor. + The query parameters + An arbitrary result object, as returned by the IResultSetExtractor + + If there is any problem executing the query. + + + + + Execute a query given static SQL/Stored Procedure name + and process a single result set with an instance of ResultSetExtractorDelegate + + The type of command. + The command text. + Delegate that will process all rows of a result set + An arbitrary result object, as returned by the IResultSetExtractor + + If there is any problem executing the query. + + + + + Execute a query given the CommandType and text with parameters set + via the command setter, processing a + single result set with an instance of IResultSetExtractor + + The command type. + The command text to execute. + Delegate that will process all rows of a result set + The command setter. + An arbitrary result object, as returned by the IResultSetExtractor + + If there is any problem executing the query. + + + + + Execute a query given the CommandType and text specifying a single parameter and process a single result set with an + instance of IResultSetExtractor. + + Convention is to use 0 For the size if it does not make sense for the given data type + + The command type. + The command text to execute. + Delegate that will process all rows of a result set + The name of the parameters + The enumeration of the parameter type + The size of the parmeter - e.g. string length. Use 0 if not relevant for specific data type + The value of the parameters + An arbitrary result object, as returned by the IResultSetExtractor + + If there is any problem executing the query. + + + + + Execute a query given the CommandType and text specifying a collection of parameters and process a single result set with an + instance of IResultSetExtractor. + + The command type. + The command text to execute. + Delegate that will process all rows of a result set + The query parameters + An arbitrary result object, as returned by the IResultSetExtractor + + If there is any problem executing the query. + + + + + Execute a query given static SQL, mapping each row to a .NET object + via a RowMapper + + The type of command + SQL query to execute + delegate/lambda that will map one object per row + The result list containing mapped objects + + + + Execute a query given static SQL, mapping each row to a .NET object + via a RowMapper + + The type of command + SQL query to execute + object that will map one object per row + the result list containing mapped objects + + + + Execute a query with the specified command text, mapping a single result + row to an object via a RowMapper. + + The command type. + The command text to execute. + object that will map one object per row + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text and parameters set via the + command setter, mapping a single result row to an object via a RowMapper. + + The command type. + The command text to execute. + object that will map one object per row + The command setter. + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text and parameters, mapping a single result row + to an object via a RowMapper. + + The command type. + The command text to execute. + object that will map one object per row + The parameter collection to use in the query. + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text and parameter, mapping a single result row + to an object via a RowMapper. + + The command type. + The command text to execute. + object that will map one object per row + The name of the parameter to map. + One of the database parameter type enumerations. + The length of the parameter. 0 if not applicable to parameter type. + The parameter value. + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text, mapping a single result + row to an object via a RowMapper. + + The command type. + The command text to execute. + delegate that will map one object per row + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text and parameters set via the + command setter, mapping a single result row to an object via a RowMapper. + + The command type. + The command text to execute. + delegate that will map one object per row + The command setter. + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text and parameters, mapping a single result row + to an object via a RowMapper. + + The command type. + The command text to execute. + delegate that will map one object per row + The parameter collection to use in the query. + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text and parameter, mapping a single result row + to an object via a RowMapper. + + The command type. + The command text to execute. + delegate that will map one object per row + The name of the parameter to map. + One of the database parameter type enumerations. + The length of the parameter. 0 if not applicable to parameter type. + The parameter value. + + + + + Fill a based on a select command that requires no parameters. + + The to populate + The type of command + SQL query to execute + The number of rows successfully added to or refreshed in the + + + + Fill a based on a select command that requires no parameters. + + The to populate + The type of command + SQL query to execute + The number of rows successfully added to or refreshed in the + + + + Fill a based on a select command that requires no parameters + that returns one or more result sets that are added as + s to the + + The to populate + The type of command + SQL query to execute + The mapping of table names for each + created + + + + + Note that output parameters are marked input/output after derivation.... + (TODO - double check....) + + + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The database provider. + + + + Initializes a new instance of the class. + + The database provider. + if set to false + lazily initialize the ErrorCodeExceptionTranslator. + + + + Execute a ADO.NET operation on a command object using a delegate callback. + + The delegate called with a command object. + + A result object returned by the action or null + + This allows for implementing arbitrary data access operations + on a single command within Spring's managed ADO.NET environment. + + + + Callback to execute a IDbCommand. + + the callback to execute + object returned from callback + + + + Executes ADO.NET operations on a command object, created by the provided IDbCommandCreator, + using the interface based callback IDbCommandCallback. + + The command creator. + The callback to execute based on IDbCommand + A result object returned by the action or null + + + + Execute ADO.NET operations on a IDbDataAdapter object using an interface based callback. + + This allows for implementing abritrary data access operations + on a single DataAdapter within Spring's managed ADO.NET environment. + + The data adapter callback. + A result object returned by the callback or null + + + + Executes a non query returning the number of rows affected. + + The command type. + The command text to execute. + The number of rows affected. + + + + Executes a non query returning the number of rows affected. + + The command type. + The command text to execute. + The name of the parameter to map. + One of the database parameter type enumerations. + The length of the parameter. 0 if not applicable to parameter type. + The parameter value. + The number of rows affected. + + + + Executes a non query returning the number of rows affected. + + The command type. + The command text to execute. + The parameter collection to map. + The number of rows affected. + + + + Executes a non query with parameters set via the + command setter, returning the number of rows affected. + + The command type. + The command text to execute. + The command setter. + The number of rows affected. + + + + Executes a non query with a command created via IDbCommandCreator and + parameters. + + Output parameters can be retrieved via the returned + dictionary. + + More commonly used as a lower level support method within the framework, + for example StoredProcedure/AdoScalar. + + + The callback to create a IDbCommand. + The number of rows affected. + + + + Execute the query with the specified command text. + + No parameters are used. As with + IDbCommand.ExecuteScalar, it returns the first column of the first row in the resultset + returned by the query. Extra columns or row are ignored. + The command type + The command text to execute. + The first column of the first row in the result set + + + + Execute the query with the specified command text and parameter returning a scalar result + + The command type + The command text to execute. + The name of the parameter to map. + One of the database parameter type enumerations. + The length of the parameter. 0 if not applicable to parameter type. + The parameter value. + The first column of the first row in the result set + + + + Execute the query with the specified command text and parameters returning a scalar result + + The command type + The command text to execute. + The parameter collection to map. + The first column of the first row in the result set + + + + Execute the query with the specified command text and parameters set via the + command setter, returning a scalar result + + The command type + The command text to execute. + The command setter. + The first column of the first row in the result set + + + + Execute the query with a command created via IDbCommandCreator and + parameters + + Output parameters can be retrieved via the returned + dictionary. + + More commonly used as a lower level support method within the framework, + for example for StoredProcedure/AdoScalar. + + The callback to create a IDbCommand. + A dictionary containing output parameters, if any + + + + Execute a query given IDbCommand's type and text, reading a + single result set on a per-row basis with a . + + The type of command + The text of the query. + callback that will extract results + one row at a time. + + + + + Execute a query given IDbCommand's type and text by + passing the created IDbCommand to a ICommandSetter implementation + that knows how to bind values to the IDbCommand, reading a + single result set on a per-row basis with a . + + The type of command + The text of the query. + callback that will extract results + one row at a time. + + The command setter. + + + + Execute a query given IDbCommand's type and text and provided parameter + information, reading a + single result set on a per-row basis with a . + + The type of command + The text of the query. + callback that will extract results + one row at a time. + + The name of the parameter to map. + One of the database parameter type enumerations. + The length of the parameter. 0 if not applicable to parameter type. + The parameter value. + + + + Execute a query given static SQL/Stored Procedure name + and process a single result set with an instance of IResultSetExtractor + + The type of command. + The SQL/Stored Procedure to execute + Object that will extract all rows of a result set + An arbitrary result object, as returned by the IResultSetExtractor + + + + Execute a query given static SQL/Stored Procedure name + and process a single result set with an instance of IResultSetExtractor + + The type of command. + The SQL/Stored Procedure to execute + Delegate that will extract all rows of a result set + An arbitrary result object, as returned by the IResultSetExtractor + + + + Execute a query with the specified command text, mapping a single result + row to an object via a RowMapper. + + The command type. + The command text to execute. + object that will map one object per row + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text and parameters set via the + command setter, mapping a single result row to an object via a RowMapper. + + The command type. + The command text to execute. + object that will map one object per row + The command setter. + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text and parameters, mapping a single result row + to an object via a RowMapper. + + The command type. + The command text to execute. + object that will map one object per row + The parameter collection to use in the query. + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text and parameter, mapping a single result row + to an object via a RowMapper. + + The command type. + The command text to execute. + object that will map one object per row + The name of the parameter to map. + One of the database parameter type enumerations. + The length of the parameter. 0 if not applicable to parameter type. + The parameter value. + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text, mapping a single result + row to an object via a RowMapper. + + The command type. + The command text to execute. + delegate that will map one object per row + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text and parameters set via the + command setter, mapping a single result row to an object via a RowMapper. + + The command type. + The command text to execute. + delegate that will map one object per row + The command setter. + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text and parameters, mapping a single result row + to an object via a RowMapper. + + The command type. + The command text to execute. + delegate that will map one object per row + The parameter collection to use in the query. + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Execute a query with the specified command text and parameter, mapping a single result row + to an object via a RowMapper. + + The command type. + The command text to execute. + delegate that will map one object per row + The name of the parameter to map. + One of the database parameter type enumerations. + The length of the parameter. 0 if not applicable to parameter type. + The parameter value. + The single mapped object. + + If the query does not return exactly one row. + + + If there is any problem executing the query. + + + + + Fill a based on a select command that requires no parameters. + + The to populate + The type of command + SQL query to execute + The number of rows successfully added to or refreshed in the + + + + Creates the data reader wrapper for use in AdoTemplate callback methods. + + The reader to wrap. + The data reader used in AdoTemplate callbacks + + + + An instance of a DbProvider implementation. + + + + + Gets or sets a value indicating whether to lazily initialize the + IAdoExceptionTranslator for this accessor, on first encounter of a + exception from the data provider. Default is "true"; can be switched to + "false" for initialization on startup. + + true if to lazy initialize the IAdoExceptionTranslator; + otherwise, false. + + + + Gets or sets the exception translator. If no custom translator is provided, a default + is used. + + The exception translator. + + + + Gets or set the System.Type to use to create an instance of IDataReaderWrapper + for the purpose of having defaults values to use in case of DBNull values read + from IDataReader. + + The type of the data reader wrapper. + + + + Generic callback interface for code that operates on a + IDbDataAdapter. + + +

Allows you to execute any number of operations + on a IDbDataAdapter, for example to Fill a DataSet + or other more advanced operations such as the transfering + data between two different DataSets. +

+

Note that the passed in IDbDataAdapter + has been created by the framework and its SelectCommand + will be populated with values for CommandType and Text properties + along with Connection/Transaction properties based on the + calling transaction context. +

+ Execute(IDataAdapterCallback dataAdapterCallback) + method. + + Mark Pollack (.NET) + + + + Called by AdoTemplate.Execute with an preconfigured + ADO.NET IDbDataAdapter instance with its SelectCommand + property populated with CommandType and Text values + along with Connection/Transaction properties based on the + calling transaction context. + + An active IDbDataAdapter instance + The result object + + + + Generic callback interface for code that operates on a + IDbCommand. + + +

Allows you to execute any number of operations + on a single IDbCommand, for example a single ExecuteScalar + call or repeated execute calls with varying parameters. +

+

Used internally by AdoTemplate, but also useful for + application code. Note that the passed in IDbCommand + has been created by the framework.

+ + Mark Pollack + + + + Called by AdoTemplate.Execute with an active ADO.NET IDbCommand. + The calling code does not need to care about closing the + command or the connection, or + about handling transactions: this will all be handled by + Spring's AdoTemplate + + An active IDbCommand instance + The result object + + + + Interface to be implemented by objects that can provide SQL strings + + Typically implemented by IDbCommandCreator and + ICommandCallbacks that want to expose the CommandText they + use to create their ADO.NET commands, to allow for better + contextual information in case of exceptions + Mark Pollack(.NET) + Juergen Hoeller + + + + Adapter implementation of the ResultSetExtractor interface that delegates + to a RowMapper which is supposed to create an object for each row. + Each object is added to the results List of this ResultSetExtractor. + + + Useful for the typical case of one object per row in the database table. + The number of entries in the results list will match the number of rows. +

+ Note that a RowMapper object is typically stateless and thus reusable; + just the RowMapperResultSetExtractor adapter is stateful. +

+

+ As an alternative consider subclassing MappingAdoQuery from the + Spring.Data.Objects namespace: Instead of working with separate + AdoTemplate and IRowMapper objects you can have executable + query objects (containing row-mapping logic) there. +

+ + Mark Pollack (.NET) + + + + Callback interface to process all result sets and rows in + an AdoTemplate query method. + + Implementations of this interface perform the work + of extracting results but don't need worry about managing + ADO.NET resources, such as closing the reader or transaction management. +

+ This interface is mainly used within the ADO.NET + framework. An IResultSetExtractor is usually a simpler choice + for result set (DataReader) processing, in particular a + RowMapperResultSetExtractor in combination with a IRowMapper. +

+ Note: in contracts to a IRowCallbackHandler, a ResultSetExtractor + is usually stateless and thus reusable, as long as it doesn't access + stateful resources or keep result state within the object. + + + + + + + Implementations must implement this method to process all + result set and rows in the IDataReader. + + The IDataReader to extract data from. + Implementations should not close this: it will be closed + by the AdoTemplate. + An arbitrary result object or null if none. The + extractor will typically be stateful in the latter case. + + + + Initializes a new instance of the class. + + + + + Transaction Manager that uses EnterpriseServices to access the + MS-DTC. It requires the support of 'Services without Components' + functionality which is available on Win 2003 and Win XP SP2. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + This is indented only for unit testing purposes and should not be + called by production application code. + The tx adapter. + + + + Gets or sets a value indicating whether tracking is enabled. + + true if tracking is enabled; otherwise, false. + + + + Gets or sets a text string that corresponds to the application ID under which tracker information is reported. + The default value is 'Spring.NET' + + The name of the tracking app. + + + + Gets or sets a text string that corresponds to the context name under which tracker information is reported. + + The name of the tracking component. + + + + TransactionManager that uses TransactionScope provided by System.Transactions. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + This is indented only for unit testing purposes and should not be + called by production application code. + The tx adapter. + + + + No-op initialization + + + + + The transaction resource object that encapsulates the state and functionality + contained in TransactionScope and Transaction.Current via the ITransactionScopeAdapter + property. + + + + + Initializes a new instance of the class. + Will create an instance of . + + + + + Gets or sets the transaction scope adapter. + + The transaction scope adapter. + + + + Return whether the transaction is internally marked as rollback-only. + + + True of the transaction is marked as rollback-only. + + + + Convenient super class for ADO.NET data access objects using generics. + + + Requires a IDBProvider to be set, providing a + AdoTemplate based on it to subclasses. + This base class is mainly intended for AdoTemplate usage. + + + + + Create a AdoTemplate for a given DbProvider + Only invoked if populating the DAO with a DbProvider reference. + + + Can be overriden in subclasses to provide AdoTemplate instances + with a different configuration, or a cusotm AdoTemplate subclass. + + The DbProvider to create a AdoTemplate for + + + + Convenience method to create a parameters builder. + + Virtual for sublcasses to override with custom + implementation. + A new DbParameterBuilder + + + + The DbProvider instance used by this DAO + + + + + Set the AdoTemplate for this DAO explicity, as + an alternative to specifying a IDbProvider + + + + + This is the central class in the Spring.Data.Generic namespace. + It simplifies the use of ADO.NET and helps to avoid commons errors. + + Mark Pollack (.NET) + + + + Interface that defines ADO.NET related database operations using generics + + Mark Pollack (.NET) + + + + Execute a ADO.NET operation on a command object using a generic interface based callback. + + The type of object returned from the callback. + the callback to execute based on DbCommand + An object returned from callback + + + + Execute a ADO.NET operation on a command object using a generic interface based callback. + + The type of object returned from the callback. + The callback to execute based on IDbCommand + An object returned from callback + + + + Execute a ADO.NET operation on a command object using a generic delegate callback. + + The type of object returned from the callback. + This allows for implementing arbitrary data access operations + on a single command within Spring's managed ADO.NET environment. + The delegate called with a DbCommand object. + A result object returned by the action or null + + + + Execute a ADO.NET operation on a command object using a generic delegate callback. + + The type of object returned from the callback. + This allows for implementing arbitrary data access operations + on a single command within Spring's managed ADO.NET environment. + The delegate called with a IDbCommand object. + A result object returned by the action or null + + + + Executes ADO.NET operations on a command object, created by the provided IDbCommandCreator, + using the interface based callback IDbCommandCallback. + + The type of object returned from the callback. + The command creator. + The callback to execute based on IDbCommand + A result object returned by the action or null + + + + Execute ADO.NET operations on a IDbDataAdapter object using an interface based callback. + + This allows for implementing abritrary data access operations + on a single DataAdapter within Spring's managed ADO.NET environment. + + The type of object returned from the callback. + The data adapter callback. + A result object returned by the callback or null + + + + Execute ADO.NET operations on a IDbDataAdapter object using an delgate based callback. + + This allows for implementing abritrary data access operations + on a single DataAdapter within Spring's managed ADO.NET environment. + + The type of object returned from the callback. + The delegate called with a IDbDataAdapter object. + A result object returned by the callback or null + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The provider. + + + + Initializes a new instance of the class. + + The database provider. + if set to false + lazily initialize the ErrorCodeExceptionTranslator. + + + + Initializes a new instance of the class. + + Useful if you have a subclass of Spring.Data.Core.AdoTemplate. + The classic ADO template. + + + + Execute a ADO.NET operation on a command object using a interface based callback. + + the callback to execute + object returned from callback + + + + Execute a ADO.NET operation on a command object using a delegate callback. + + This allows for implementing arbitrary data access operations + on a single command within Spring's managed ADO.NET environment. + The delegate called with a command object. + A result object returned by the action or null + + + + Execute a ADO.NET operation on a command object using a interface based callback. + + the callback to execute + object returned from callback + + + + Execute a ADO.NET operation on a command object using a delegate callback. + + This allows for implementing arbitrary data access operations + on a single command within Spring's managed ADO.NET environment. + The delegate called with a command object. + A result object returned by the action or null + + + + Executes ADO.NET operations on a command object, created by the provided IDbCommandCreator, + using the interface based callback IDbCommandCallback. + + The type of object returned from the callback. + The command creator. + The callback to execute based on IDbCommand + + A result object returned by the action or null + + + + + Execute ADO.NET operations on a IDbDataAdapter object using an interface based callback. + + The type of object returned from the callback. + The data adapter callback. + + A result object returned by the callback or null + + This allows for implementing abritrary data access operations + on a single DataAdapter within Spring's managed ADO.NET environment. + + + + + Execute ADO.NET operations on a IDbDataAdapter object using an delgate based callback. + + This allows for implementing abritrary data access operations + on a single DataAdapter within Spring's managed ADO.NET environment. + + The type of object returned from the callback. + The delegate called with a IDbDataAdapter object. + A result object returned by the callback or null + + + + Executes a non query returning the number of rows affected. + + The command type. + The command text to execute. + The number of rows affected. + + + + Executes a non query returning the number of rows affected. + + The command type. + The command text to execute. + The name of the parameter to map. + One of the database parameter type enumerations. + The length of the parameter. 0 if not applicable to parameter type. + The parameter value. + The number of rows affected. + + + + Executes a non query returning the number of rows affected. + + The command type. + The command text to execute. + The parameter collection to map. + The number of rows affected. + + + + Executes a non query with parameters set via the + command setter, returning the number of rows affected. + + The command type. + The command text to execute. + The command setter. + The number of rows affected. + + + + Executes a non query with a command created via IDbCommandCreator and + parameters. + + Output parameters can be retrieved via the returned + dictionary. + + More commonly used as a lower level support method within the framework, + for example StoredProcedure/AdoScalar. + + + The callback to create a IDbCommand. + The number of rows affected. + + + + Execute the query with the specified command text. + + No parameters are used. As with + IDbCommand.ExecuteScalar, it returns the first column of the first row in the result set + returned by the query. Extra columns or row are ignored. + The command type + The command text to execute. + The first column of the first row in the result set + + + + Execute the query with the specified command text and parameter returning a scalar result + + The command type + The command text to execute. + The name of the parameter to map. + One of the database parameter type enumerations. + The length of the parameter. 0 if not applicable to parameter type. + The parameter value. + The first column of the first row in the result set + + + + Execute the query with the specified command text and parameters returning a scalar result + + The command type + The command text to execute. + The parameter collection to map. + The first column of the first row in the result set + + + + Execute the query with the specified command text and parameters set via the + command setter, returning a scalar result + + The command type + The command text to execute. + The command setter. + The first column of the first row in the result set + + + + Execute the query with a command created via IDbCommandCreator and + parameters + + Output parameters can be retrieved via the returned + dictionary. + + More commonly used as a lower level support method within the framework, + for example for StoredProcedure/AdoScalar. + + The callback to create a IDbCommand. + A dictionary containing output parameters, if any + + + + Execute a query given IDbCommand's type and text by + passing the created IDbCommand to a ICommandSetter implementation + that knows how to bind values to the IDbCommand, reading a + single result set on a per-row basis with a . + + The type of command + The text of the query. + callback that will extract results + one row at a time. + + The command setter. + + + + Execute a query given IDbCommand's type and text, reading a + single result set on a per-row basis with a . + + The type of command + The text of the query. + callback that will extract results + one row at a time. + + + + + Execute a query given IDbCommand's type and text and provided parameter + information, reading a + single result set on a per-row basis with a . + + The type of command + The text of the query. + callback that will extract results + one row at a time. + + The name of the parameter to map. + One of the database parameter type enumerations. + The length of the parameter. 0 if not applicable to parameter type. + The parameter value. + + + + Execute a query given IDbCommand's type and text and provided IDbParameters, + reading a single result set on a per-row basis with a . + + Type of the command. + The text of the query. + callback that will extract results + one row at a time. + The parameter collection to map. + + + + Checks if DbProvider is not null and creates ExceptionTranslator if not LazyInit. + + + + + Creates the data reader wrapper for use in AdoTemplate callback methods. + + The reader to wrap. + The data reader used in AdoTemplate callbacks + + + + Derives the parameters of a stored procedure including the return parameter + + Name of the procedure. + if set to true to include return parameter. + The stored procedure parameters + + + + An instance of a DbProvider implementation. + + + + + Gets or sets a value indicating whether to lazily initialize the + IAdoExceptionTranslator for this accessor, on first encounter of a + exception from the data provider. Default is "true"; can be switched to + "false" for initialization on startup. + + true if to lazy initialize the IAdoExceptionTranslator; + otherwise, false. + + + + Gets or sets the exception translator. If no custom translator is provided, a default + is used. + + The exception translator. + + + + Gets or set the System.Type to use to create an instance of IDataReaderWrapper + for the purpose of having defaults values to use in case of DBNull values read + from IDataReader. + + The type of the data reader wrapper. + + + + Gets the 'Classic' AdoTemplate in Spring.Data + + + Useful to access methods that return non-generic collections. + + The 'Classic; AdoTemplate in Spring.Data. + + + + Gets or sets the command timeout for IDbCommands that this AdoTemplate executes. It also + sets the value of the contained 'ClassicAdoTemplate'. + + The command timeout. + Default is 0, indicating to use the database provider's default. + Any timeout specified here will be overridden by the remaining + transaction timeout when executing within a transaction that has a + timeout specified at the transaction level. + + + + + Generic callback interface for code that operates on a + IDbCommand. + + The return type from executing the + callback + +

Allows you to execute any number of operations + on a single IDbCommand, for example a single ExecuteScalar + call or repeated execute calls with varying parameters. +

+

Used internally by AdoTemplate, but also useful for + application code. Note that the passed in IDbCommand + has been created by the framework and will have its + Connection property set and the Transaction property + set based on the transaction context.

+

As an alternative to using this interface you can use + the delegate version which is particularly nice when using + anonymous delegates for writing more terse code and having + easy access to the variables in the calling class.

+

See for a version that has the + base class DbCommand as the callback argument.

+ + Mark Pollack + + + + Called by AdoTemplate.Execute with an active ADO.NET IDbCommand. + The calling code does not need to care about closing the + command or the connection, or + about handling transactions: this will all be handled by + Spring's AdoTemplate + + An active IDbCommand instance + The result object + + + + Generic callback delegate for code that operates on a DbCommand. + + +

Allows you to execute any number of operations + on a single DbCommand, for example a single ExecuteScalar + call or repeated execute calls with varying parameters. +

+

Used internally by AdoTemplate, but also useful for + application code. Note that the passed in DbCommand + has been created by the framework and will have its + Connection property set and the Transaction property + set based on the transaction context.

+ + The return type from executing the + callback + The ADO.NET DbCommand object + The object returned from processing with the + provided DbCommand + Mark Pollack + + + + Called by AdoTemplate.Execute with an preconfigured + ADO.NET IDbDataAdapter instance with its SelectCommand + property populated with CommandType and Text values + along with Connection/Transaction properties based on the + calling transaction context. + + An active IDbDataAdapter instance + The result object + + + + Generic callback interface for code that operates on a + DbCommand. + + The return type from executing the + callback + +

Allows you to execute any number of operations + on a single DbCommand, for example a single ExecuteScalar + call or repeated execute calls with varying parameters. +

+

Used internally by AdoTemplate, but also useful for + application code. Note that the passed in DbCommand + has been created by the framework and will have its + Connection property set and the Transaction property + set based on the transaction context.

+ + Mark Pollack + + + + Called by AdoTemplate.Execute with an active ADO.NET IDbCommand. + The calling code does not need to care about closing the + command or the connection, or + about handling transactions: this will all be handled by + Spring's AdoTemplate + + An active IDbCommand instance + The result object + + + + Generic callback interface for code that operates on a + IDbDataAdapter. + + +

Allows you to execute any number of operations + on a IDbDataAdapter, for example to Fill a DataSet + or other more advanced operations such as the transfering + data between two different DataSets. +

+

Note that the passed in IDbDataAdapter + has been created by the framework and its SelectCommand + will be populated with values for CommandType and Text properties + along with Connection/Transaction properties based on the + calling transaction context. +

+ Execute(IDataAdapterCallback dataAdapterCallback) + method. + + Mark Pollack (.NET) + + + + Called by AdoTemplate.Execute with an preconfigured + ADO.NET IDbDataAdapter instance with its SelectCommand + property populated with CommandType and Text values + along with Connection/Transaction properties based on the + calling transaction context. + + An active IDbDataAdapter instance + The result object + + + + Generic callback delegate for code that operates on a IDbCommand. + + +

Allows you to execute any number of operations + on a single IDbCommand, for example a single ExecuteScalar + call or repeated execute calls with varying parameters. +

+

Used internally by AdoTemplate, but also useful for + application code. Note that the passed in DbCommand + has been created by the framework and will have its + Connection property set and the Transaction property + set based on the transaction context.

+ + The return type from executing the + callback + The ADO.NET DbCommand object + The object returned from processing with the + provided DbCommand + Mark Pollack + + + + Callback interface to process all results sets and rows in + an AdoTemplate query method. + + Implementations of this interface perform the work + of extracting results but don't need worry about managing + ADO.NET resources, such as closing the reader. +

+ This interface is mainly used within the ADO.NET + framework. An IResultSetExtractor is usually a simpler choice + for result set (DataReader) processing, in particular a + RowMapperResultSetExtractor in combination with a IRowMapper. +

+ Note: in contracts to a IRowCallbackHandler, a ResultSetExtractor + is usually stateless and thus reusable, as long as it doesn't access + stateful resources or keep result state within the object. + + + + + + + Implementations must implement this method to process all + result set and rows in the IDataReader. + + The IDataReader to extract data from. + Implementations should not close this: it will be closed + by the AdoTemplate. + An arbitrary result object or null if none. The + extractor will typically be stateful in the latter case. + + + + Generic callback to process each row of data in a result set to an object. + + Implementations of this interface perform the actual work + of mapping rows, but don't need worry about managing + ADO.NET resources, such as closing the reader. +

+ Typically used for AdoTemplate's query methods (with RowMapperResultSetExtractor + adapters). RowMapper objects are typically stateless and thus + reusable; they are ideal choices for implementing row-mapping logic in a single + place. +

+

Alternatively, consider subclassing MappingSqlQuery from the Spring.Data.Object + namespace: Instead of working with separate AdoTemplate and RowMapper objects, + you can have executable query objects (containing row-mapping logic) there. +

+ + Mark Pollack (.NET) + + + + Implementations must implement this method to map each row of data in the + result set (DataReader). This method should not call Next() on the + DataReader; it should only extract the values of the current row. + + The IDataReader to map (pre-initialized to the current row) + The number of the current row.. + The specific typed result object for the current row. + + + + Provides a name to a ResultSetProcessor for use with AdoOperation subclasses + such as StoredProcedure. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class with a + IRowCallback instance + + The name of the associated row callback for use with output + result set mappers. + A row callback instance. + + + + Initializes a new instance of the class with a + IRowMapper instance + + The name of the associated row mapper. + A IRowMapper instance. + + + + Initializes a new instance of the class with a + IResultSetExtractor instance + + The name of the associated result set extractor. + A IResultSetExtractor instance. + + + + Callback delegate to process all result sets and row in an + AdoTemplate query method. + + The type returned from the result set mapping. + The IDataReader to extract data from. + Implementations should not close this: it will be closed + by the AdoTemplate. + An arbitrary result object or null if none. + + + + Callback delegate to process each row of data in a result set to an object. + + The type of the object returned from the mapping operation. + The IDataReader to map + the number of the current row. + An abrirary object, typically derived from data + in the result set. + + + + Adapter implementation of the ResultSetExtractor interface that delegates + to a RowMapper which is supposed to create an object for each row. + Each object is added to the results List of this ResultSetExtractor. + + + Useful for the typical case of one object per row in the database table. + The number of entries in the results list will match the number of rows. +

+ Note that a RowMapper object is typically stateless and thus reusable; + just the RowMapperResultSetExtractor adapter is stateful. +

+

+ As an alternative consider subclassing MappingAdoQuery from the + Spring.Data.Objects namespace: Instead of working with separate + AdoTemplate and IRowMapper objects you can have executable + query objects (containing row-mapping logic) there. +

+ + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The row mapper. + The rows expected. + + + + A "AdoOperation" is a thread-safe, reusable object representing + an ADO Query, "NonQuery" (Create, Update, Delete), stored procedure + or DataSet manipualtions. + + + Subclasses should set Command Text and add parameters before invoking + Compile(). The order in which parameters are added is generally + significant when using providers or functionality that do not use + named parameters. + + + Mark Pollack (.NET) + + + + Abstract base class providing common functionality for generic and non + generic implementations of "AdoOperation" subclasses. + + Mark Pollack (.NET) + + + + Has this operation been compiled? Compilation means at + least checking that a IDbProvider and sql have been provided, + but subclasses may also implement their own custom validation. + + + + + Object enabling us to create IDbCommands + efficiently, based on this class's declared parameters. + + + + + Ensures compilation if used in an IApplicationContext + + + + + Compiles this operation. Ignores subsequent attempts to compile. + + + + + Check whether this operation has been compiled already; + lazily compile it if not already compiled. + + Automatically called by ValidateParameters and ValidateNamedParameters + + + + Validates the named parameters passed to an AdoTemplate ExecuteXXX method based on + declared parameters. + + + Subclasses should invoke this method very every ExecuteXXX method. + + The parameter dictionary supplied. May by null. + + + + Subclasses must implement to perform their own compilation. + Invoked after this class's compilation is complete. + Subclasses can assume that SQL has been supplied and that + a IDbProvider has been supplied. + + + + + Hook method that subclasses may override to react to compilation. + This implementation does nothing. + + + + + Gets or sets the type of the command. + + The type of the command. + + + + Gets or sets the db provider. + + The db provider. + + + + Gets or sets the SQL to execute + + The SQL. + + + + Gets or sets the declared parameters. + + The declared parameters. + + + + Gets a value indicating whether this is compiled. + + Compilation means that the operation is fully configured, + and ready to use. The exact meaning of compilation will vary between subclasses. + true if compiled; otherwise, false. + + + + Sets the command timeout for IDbCommands that this AdoTemplate executes. + + Default is 0, indicating to use the database provider's default. + Any timeout specified here will be overridden by the remaining + transaction timeout when executing within a transaction that has a + timeout specified at the transaction level. + + The command timeout. + + + + Initializes a new instance of the class. + + A DbProvider, SQL and any parameters must be supplied + before invoking the compile method and using this object. + + + + + Initializes a new instance of the class. + + A DbProvider, SQL and any parameters must be supplied + before invoking the compile method and using this object. + + Database provider to use. + + + + Initializes a new instance of the class. + + A DbProvider, SQL and any parameters must be supplied + before invoking the compile method and using this object. + + Database provider to use. + SQL query or stored procedure name. + + + + Compiles this operation. Ignores subsequent attempts to compile. + + + + + Gets or sets the ADO template. + + The ADO template. + + + + Gets or sets the db provider. + + The db provider. + + + + Sets the command timeout for IDbCommands that this AdoTemplate executes. + + Default is 0, indicating to use the database provider's default. + Any timeout specified here will be overridden by the remaining + transaction timeout when executing within a transaction that has a + timeout specified at the transaction level. + + The command timeout. + + + + Place together the mapping logic to a plain .NET object + for one result set within the same class. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The database provider. + The SQL to execute + + + + Convenient method to execute query without parameters or calling context. + + The type parameter for the returned collection + List of mapped objects + + + + Convenient method to execute query with parameters but without calling context. + + The type parameter for the returned collection + The parameters for the query. + + + + + Convenient method to execute query with parameters and access to output parameter values. + + The type parameter for the returned collection + The parameters for the query. + The returned output parameters. + + + + + Central execution method. All named parameter execution goes through this method. + + the type parameter for the returned collection + The in params. + The out params. + The calling context. + + + + + Reusable query in which concrete subclasses must implement the + MapRow method to map each row of a single result set into an + object. + + + Simplifies MappingSqlQueryWithContext API by dropping parameters and + context. Most subclasses won't care about parameters. If you don't use + contextual information, subclass this instead of MappingSqlQueryWithContext. + + Mark Pollack (.NET) + + + + Reusable query in which concrete subclasses must implement the + abstract MapRow method to map each row of a single result set into an + object. + + The MapRow method is also passed the input parameters and + a dictionary to provide the method with calling context information + (if necessary). If you do not need these additional parameters, use + the subclass MappingAdoQuery. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + + + + A superclass for object based abstractions of RDBMS stored procedures. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Execute the stored procedure using 'ExecuteScalar' + + Value of input parameters. + Dictionary with any named output parameters and the value of the + scalar under the key "scalar". + + + + Encapsulate Command.ExecuteNonQuery operations within a reusable class. + + Mark Pollack (.NET) + The default CommandType is CommandType.Text + + + + A "AdoOperation" is a thread-safe, reusable object representing + an ADO Query, "NonQuery" (Create, Update, Delete), stored procedure + or DataSet manipualtions. + + + Subclasses should set Command Text and add parameters before invoking + Compile(). The order in which parameters are added is generally + significant when using providers or functionality that do not use + named parameters. + + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + A DbProvider, SQL and any parameters must be supplied + before invoking the compile method and using this object. + + + + + Initializes a new instance of the class. + + A DbProvider, SQL and any parameters must be supplied + before invoking the compile method and using this object. + + Database provider to use. + + + + Initializes a new instance of the class. + + A DbProvider, SQL and any parameters must be supplied + before invoking the compile method and using this object. + + Database provider to use. + SQL query or stored procedure name. + + + + Compiles this operation. Ignores subsequent attempts to compile. + + + + + Gets or sets the ADO template. + + The ADO template. + + + + Gets or sets the db provider. + + The db provider. + + + + Sets the command timeout for IDbCommands that this AdoTemplate executes. + + Default is 0, indicating to use the database provider's default. + Any timeout specified here will be overridden by the remaining + transaction timeout when executing within a transaction that has a + timeout specified at the transaction level. + + The command timeout. + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + + + + Place together the mapping logic to a plain .NET object + for one result set within the same class. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Encapsulate Command ExecuteScalar operations within a reusable class. + + The default CommandType is CommandType.Text + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + + + + Reusable query in which concrete subclasses must implement the + MapRow method to map each row of a single result set into an + object. + + + Simplifies MappingAdoQueryWithContext API by dropping parameters and + context. Most subclasses won't care about parameters. If you don't use + contextual information, subclass this instead of MappingSqlQueryWithContext. + + Mark Pollack (.NET) + + + + Reusable query in which concrete subclasses must implement the + MapRow method to map each row of a single result set into an + object. + + The MapRow method is also passed the input parameters and + a dictionary to provide the method with calling context information + (if necessary). If you do not need these additional parameters, use + the subclass MappingAdoQuery. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Callback to process each row of data in a result set to an object. + + Implementations of this interface perform the actual work + of mapping rows, but don't need worry about managing + ADO.NET resources, such as closing the reader. +

+ Typically used for AdoTemplate's query methods (with RowMapperResultSetExtractor + adapters). RowMapper objects are typically stateless and thus + reusable; they are ideal choices for implementing row-mapping logic in a single + place. +

+

Alternatively, consider subclassing MappingSqlQuery from the Spring.Data.Object + namespace: Instead of working with separate AdoTemplate and RowMapper objects, + you can have executable query objects (containing row-mapping logic) there. +

+ + Mark Pollack (.NET) + + + + Implementations must implement this method to map each row of data in the + result set (DataReader). This method should not call Next() on the + DataReader; it should only extract the values of the current row. + + The IDataReader to map (pre-initialized for the current row) + The number of the current row. + The result object for the current row. + + + + Initializes a new instance of the class. + + + + + A superclass for object based abstractions of RDBMS stored procedures. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The db provider. + Name of the stored procedure. + + + + Execute the stored procedure using 'ExecuteScalar' + + Value of input parameters. + Dictionary with any named output parameters and the value of the + scalar under the key "scalar". + + + + Summary description for AdoUtils. + + + + + Order value for TransactionSynchronization objects that clean up + ADO.NET Connections. + + + + + Property dispose of the command. Useful in finally or catch blocks. + + command to dispose + + + + Connection holder, wrapping a ADO.NET connection and transaction. + + AdoTransactionManager binds instances of this class to the + thread for a given DbProvider. + Jurgen Hoeller + Mark Pollack (.NET) + + + + Convenient base class for resource holders. + + +

+ Features rollback-only support transactions. Can expire after a certain number of + seconds or milliseconds, to determine transactional timeouts. +

+ + Juergen Hoeller + Griffin Caprio (.NET) + + + + Clear the transaction state of this resource holder. + + + + + Increase the reference count by one because the holder has been requested. + + + + + Decrease the reference count by one because the holder has been released. + + + + + Mark the resource as synchronized with a transaction. + + + + + Get or set whether the resource is synchronized with a transaction. + + true if synchronized; otherwise, false. + + + + Return the expiration deadline of this object. + + + + + Return whether this object has an associated timeout. + + + + + Return the time to live for this object in seconds. + + +

+ Rounds up eagerly, e.g. '9.00001' to '10'. +

+ + + If no deadline has been set. + + + + + Return the time to live for this object in milliseconds. + + + If no deadline has been set. + + + + + Sets the timeout for this object in milliseconds. + + Number of milliseconds until expiration. + + + + Sets the timeout for this object in seconds. + + Number of seconds until expiration. + + + + Return wheterh there are still open references to this holder + + + + + Create a new ConnectionHolder + + The connection to hold + The transaction to hold + + + + Callback for resource cleanup at end of transaction. + + + + + Adapter for the + interface. + + + Contains empty implementations of all interface methods, for easy overriding of + single methods. + + Juergen Hoeller + Griffin Caprio (.NET) + Mark Pollack (.NET) + + + + Interface for transaction synchronization callbacks. + + + Supported by . + + Juergen Hoeller + Griffin Caprio (.NET) + Mark Pollack (.NET) + + + + Suspend this synchronization. + + +

+ Supposed to unbind resources from + + if managing any. +

+ + + + + Resume this synchronization. + + +

+ Supposed to rebind resources from + + if managing any. +

+ + + + + Invoked before transaction commit (before + ) + Can e.g. flush transactional O/R Mapping sessions to the database + + + + This callback does not mean that the transaction will actually be + commited. A rollback decision can still occur after this method + has been called. This callback is rather meant to perform work + that's only relevant if a commit still has a chance + to happen, such as flushing SQL statements to the database. + + + Note that exceptions will get propagated to the commit caller and cause a + rollback of the transaction. + + (note: do not throw TransactionException subclasses here!) + + + + If the transaction is defined as a read-only transaction. + + + + + Invoked after transaction commit. + + Can e.g. commit further operations that are supposed to follow on + a successful commit of the main transaction. + Throws exception in case of errors; will be propagated to the caller. + Note: To not throw TransactionExeption sbuclasses here! + + + + + + Invoked before transaction commit/rollback (after + , + even if + + threw an exception). + + +

+ Can e.g. perform resource cleanup. +

+

+ Note that exceptions will get propagated to the commit caller + and cause a rollback of the transaction. +

+ + + + + Invoked after transaction commit/rollback. + + + Status according to + + + Can e.g. perform resource cleanup, in this case after transaction completion. +

+ Note that exceptions will get propagated to the commit or rollback + caller, although they will not influence the outcome of the transaction. +

+ + + + + Suspend this synchronization. + + +

+ Supposed to unbind resources from + + if managing any. +

+ + + + + Resume this synchronization. + + +

+ Supposed to unbind resources from + + if managing any. +

+ + + + + Invoked before transaction commit (before + ) + + + If the transaction is defined as a read-only transaction. + + +

+ Can flush transactional sessions to the database. +

+

+ Note that exceptions will get propagated to the commit caller and + cause a rollback of the transaction. +

+ + + + + Invoked after transaction commit. + + Can e.g. commit further operations that are supposed to follow on + a successful commit of the main transaction. + Throws exception in case of errors; will be propagated to the caller. + Note: To not throw TransactionExeption sbuclasses here! + + + + + Invoked before transaction commit/rollback (after + , + even if + + threw an exception). + + +

+ Can e.g. perform resource cleanup. +

+

+ Note that exceptions will get propagated to the commit caller + and cause a rollback of the transaction. +

+ + + + + Invoked after transaction commit/rollback. + + + Status according to + + + Can e.g. perform resource cleanup, in this case after transaction completion. +

+ Note that exceptions will get propagated to the commit or rollback + caller, although they will not influence the outcome of the transaction. +

+ + + + + Compares the current instance with another object of the same type. + + + + A 32-bit signed integer that indicates the relative order of the objects being compared. The return value has these meanings: Value Meaning Less than zero This instance is less than obj. Zero This instance is equal to obj. Greater than zero This instance is greater than obj. + + + An object to compare with this instance. + obj is not the same type as this instance. 2 + + + + Create a new instance. + + + + + + + Compares the current instance with another object of the same type. + + An object to compare with this instance. + + The value of the order property. + + + + + Suspend this synchronization. + + +

+ Supposed to unbind resources from + + if managing any. +

+ + + + + Resume this synchronization. + + +

+ Supposed to unbind resources from + + if managing any. +

+ + + + + Invoked before transaction commit/rollback (after + , + even if + + threw an exception). + + +

+ Can e.g. perform resource cleanup. +

+

+ Note that exceptions will get propagated to the commit caller + and cause a rollback of the transaction. +

+ + + + + Invoked after transaction commit/rollback. + + Status according to + + Can e.g. perform resource cleanup, in this case after transaction completion. +

+ Note that exceptions will get propagated to the commit or rollback + caller, although they will not influence the outcome of the transaction. +

+ + + + + A simple holder for the current Connection/Transaction objects + to use within a given AdoTemplate Execute operation. Used internally. + + + + + Initializes a new instance of the class. + + The connection. + The transaction. + + + + Gets the connection. + + The connection. + + + + Gets the transaction. + + The transaction. + + + + Summary description for DbProviderUtils. + + + + + Dispose of the given Connection, created via the given IDbProvider, + if it is not managed externally (that is, not bound to the thread). + + The connection to close if necessary. If + this is null the call will be ignored. + The IDbProvider the connection came from + + + + Get a ADO.NET Connection/Transaction Pair for the given IDbProvider. + Changes any exception into the Spring hierarchy of generic data access + exceptions, simplifying calling code and making any exception that is + thrown more meaningful. + + + Is aware of a corresponding Connection/Transaction bound to the current thread, for example + when using AdoPlatformTransactionManager. Will bind a IDbConnection to the thread + if transaction synchronization is active + + The provider. + A Connection/Transaction pair. + + + + Get a ADO.NET Connection/Transaction Pair for the given IDbProvider. + Same as but throwing original provider + exception. + + + Is aware of a corresponding Connection/Transaction bound to the current thread, for example + when using AdoPlatformTransactionManager. Will bind a IDbConnection to the thread + if transaction synchronization is active + + The provider. + + + + + Do the connection mgmt. + + + + + + + Applies the current transaction timeout, if any, to the given ADO.NET IDbCommand object. + + The command. + The db provider. + + + + Applies the specified timeout - overridden by the current transaction timeout, if any, to to the + given ADO.NET IDb command object. + + The command. + The db provider the command was obtained from. + The timeout to apply (or 0 for no timeout outside of a transaction. + + + + Implementation that delegates to ServiceDomain and ContextUtil for all functionality. + + Introduced for purposes of unit testing. + Mark Pollack (.NET) + + + + Provides the necessary transactional state and operations for ServiceDomainTransactionManager to + work with ServiceDomain and ContextUtil. + + Introduced for purposes of unit testing. + Mark Pollack (.NET) + + + + Creates the context specified by the ServiceConfig object and pushes it onto the context stack to + become the current context. + + A ServiceConfig that contains the configuration information for the services to be used within the enclosed code. + + + + Leaves this ServiceDomain. The current context is then popped from the context stack, and the + context that was running when Enter was called becomes the current context. + + One of the TransactionStatus values + + + + Sets the consistent bit and the done bit to true in the COM+ context + + + + + Sets the consistent bit to false and the done bit to true in the COM+ context. + + + + + Gets or sets the consistent bit in the COM+ context. + + My transaction vote. + + + + Gets a value indicating whether the current context is transactional. + + + true if this instance is existing transaction; otherwise, false. + + + + + Creates the context specified by the ServiceConfig object and pushes it onto the context stack to + become the current context. + + A ServiceConfig that contains the configuration information for the services to be used within the enclosed code. + + + + Leaves this ServiceDomain. The current context is then popped from the context stack, and the + context that was running when Enter was called becomes the current context. + + One of the TransactionStatus values + + + + Sets the consistent bit and the done bit to true in the COM+ context + + + + + Sets the consistent bit to false and the done bit to true in the COM+ context. + + + + + Gets or sets the consistent bit in the COM+ context. + + My transaction vote. + + + + Gets a value indicating whether the current context is transactional. + + + true if this instance is existing transaction; otherwise, false. + + + + + Uses and System.Transactions.Transaction.Current to provide + necessary state and operations to TxScopeTransactionManager. + + Mark Pollack (.NET) + + + + Provides the necessary transactional state and operations for TxScopeTransactionManager to + work with TransactionScope and Transaction.Current. + + Introduced for purposes of unit testing. + Mark Pollack (.NET) + + + + Creates the transaction scope. + + The tx scope option. + The tx options. + The interop option. + + + + Call Complete() on the TransactionScope object created by this instance. + + + + + Call Disponse() on the TransactionScope object created by this instance. + + + + + Gets a value indicating whether there is a new transaction or an existing transaction. + + + true if this instance is existing transaction; otherwise, false. + + + + + Gets a value indicating whether rollback only has been called (i.e. Rollback() on the + Transaction object) and therefore voting that the transaction will be aborted. + + true if rollback only; otherwise, false. + + + + Call Complete() on the TransactionScope object created by this instance. + + + + + Call Disponse() on the TransactionScope object created by this instance. + + + + + Creates the transaction scope. + + The tx scope option. + The tx options. + The interop option. + + + + Gets a value indicating whether there is a new transaction or an existing transaction. + + + true if this instance is existing transaction; otherwise, false. + + + + + Gets a value indicating whether rollback only has been called (i.e. Rollback() on the + Transaction object) and therefore voting that the transaction will be aborted. + + true if rollback only; otherwise, false. + + + + Implementation of IAdoExceptionTranslator that analyzes provider specific + error codes and translates into the DAO exception hierarchy. + + This class loads the obtains error codes from + the IDbProvider metadata property ErrorCodes + which defines error code mappings for various providers. + + Mark Pollack (.NET) + + + + Interface to be implemented by classes that can translate between properietary SQL exceptions + and Spring.NET's data access strategy-agnostic . + + +

+ Implementations can be generic (for example, ADO.NET Exceptions) or proprietary (for example, + using SQL Server or Oracle error codes) for greater precision. +

+ + Rod Johnson + Griffin Caprio (.NET) + Mark Pollack + + + + Translate the given into a generic data access exception. + + A readable string describing the task being attempted. + The SQL query or update that caused the problem. May be null. + + The encountered by the ADO.NET implementation. + + + A appropriate for the supplied + . + + + + + The shared log instance for this class (and derived classes). + + + + + Initializes a new instance of the class. + + The data provider. + + + + Initializes a new instance of the class. + + The data provider. + The error code collection. + + + + Translate the given into a generic data access exception. + + A readable string describing the task being attempted. + The SQL query or update that caused the problem. May be null. + + The encountered by the ADO.NET implementation. + + + A appropriate for the supplied + . + + + + + Template method for actually translating the given exception. + given into a generic data access exception. + + A readable string describing the task being attempted. + The SQL query or update that caused the problem. May be null. + The error code. + The encountered by the ADO.NET implementation. + + A appropriate for the supplied + . + + + The passed-in arguments will have been pre-checked. furthermore, this method is allowed to + return null to indicate that no exception match has been found and that + fallback translation should kick in. + + + + + Subclasses can override this method to attempt a custom mapping from a data access Exception + to DataAccessException. + + Readable text describing the task being attempted. + SQL query or update that caused the problem. May be null. + The error code extracted from the generic data access exception for + a particular provider. + The exception thrown from a data access operation. + + null if no custom translation was possible, otherwise a DataAccessException + resulting from custom translation. This exception should include the exception parameter + as a nested root cause. This implementation always returns null, meaning that + the translator always falls back to the default error codes. + + + + + Builds the message. + + The task. + The SQL. + The exception. + + + + + Determines whether the specified exception is valid data access exception. + + The exception. + + true if is valid data access exception; otherwise, false. + + + + + Logs the translation. + + The task. + The SQL. + The error code. + The exception. + if set to true [b]. + + + + Sets the db provider. + + The db provider. + + + + Gets the error codes for the provider + + The error codes. + + + + Gets or sets the fallback translator to use in case error code based translation + fails. + + The fallback translator. + + + + Translates all exceptions to an UncategorizedAdoException. + + + This exception translator used when an exception is thrown using the + "primary" implementation of IAdoExceptionTranslator, i.e. AdoExceptionTranslator. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Translate the given into a generic data access exception. + + A readable string describing the task being attempted. + The SQL query or update that caused the problem. May be null. + + The encountered by the ADO.NET implementation. + + + A appropriate for the supplied + . + + + + + Provides a name to a ResultSetProcessor for use with AdoOperation subclasses + such as StoredProcedure. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class with a + IRowCallback instance + + The name of the associated row callback for use with output + result set mappers. + A row callback instance. + + + + Initializes a new instance of the class with a + IRowMapper instance + + The name of the associated row mapper. + A IRowMapper instance. + + + + Initializes a new instance of the class with a + IResultSetExtractor instance + + The name of the associated result set extractor. + A IResultSetExtractor instance. + + + + A data reader implementation that mapps DBNull values to sensible defaults. + + IDataRecord methods are virtual. + Mark Pollack (.NET) + + + + Custom data reader implementations often delegate to an underlying + instance. This interface captures that relationship for reuse in + the framework. + + Implementations will typically add behavior to standard IDataReader methods, + for example, by providing default values for DbNull values. + See as an example. + + Mark Pollack (.NET) + + + + The underlying reader implementation to delegate to for accessing data + from a returned result sets. + + The wrapped reader. + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The data reader to delegate operations to. + + + + Gets the 32-bit signed integer value of the specified field. + + The index of the field to find. + + The 32-bit signed integer value of the specified field or 0 if null + + The index passed was outside the range of 0 through . + + + + Return the value of the specified field, null if value equals DBNull.Value + + The index of the field to find. + + The which will contain the field value upon return. + Returns null if value equals DBNull.Value + + + The index passed was outside the range of 0 through . + + + + + Return whether the specified field is set to null. + + The index of the field to find. + + if the specified field is set to null, otherwise + . + + The index passed was outside the range of 0 through . + + + + Gets the with the specified name. + Returns null if value equals DBNull.Value + + + + + + Gets the with the specified i. + Returns null if value equals DBNull.Value + + Return the object or null if the value equals DBNull.Value + + + + Miscellaneous utility methods for manipulating parameter objects. + + Mark Pollack (.NET) + + + + The shared log instance for this class (and derived classes). + + + + + Initializes a new instance of the class. + + + + + Copies the parameters from IDbParameters to the parameter collection in IDbCommand + + The command. + The spring param collection. + + + + Copies the parameters in IDbCommand to IDbParameters + + The spring param collection. + The command. + + + + Adapter to enable use of a IRowCallback inside a ResultSetExtractor. + + We don't use it for navigating since this could lead to unpredictable consequences. + Mark Pollack + + + + Initializes a new instance of the class. + + The row callback. + + + + Initializes a new instance of the class. + + The row callback delegate. + + + + All rows of the data reader are passed to the IRowCallback + associated with this class. + + The IDataReader to extract data from. + Implementations should not close this: it will be closed + by the AdoTemplate. + + Null is returned since IRowCallback manages its own state. + + + + + A class that contains the properties of ServiceConfig used by ServiceDomainPlatformTransactionManager. + + This is done to enhance testability of the transaction manager since ServiceConfig does not override Equals or Hashcode + Mark Pollack (.NET) + + + + Using reflection on VS.NET 2005 a generated typed dataset, apply the + connection/transaction pair associated with the current Spring based + transaction scope. + + This avoids the limitations of using System.Transaction + based transaction scope for multiple operation on typed datasets withone one + transaction. Reflection was used rather than partial classes to provide + a general solution that can be written and applied once. + Usage within a DAO method, FindAll() is shown below. Note: Convenience methods + to simplify calling syntax maybe provided in the future, it is a trade off on type + safety calling the typed adapter defined outside the anonymous method as + compared to casting inside a "DoInDbAdapter(object dbAdapter) method. + + public PrintGroupMappingDataSet FindAll() + { + + PrintGroupMappingTableAdapter adapter = new PrintGroupMappingTableAdapter(); + PrintGroupMappingDataSet printGroupMappingDataSet = new PrintGroupMappingDataSet(); + + + printGroupMappingDataSet = AdoTemplate.Execute(delegate(IDbCommand command) + { + TypedDataSetUtils.ApplyConnectionAndTx(adapter, command); + adapter.Fill(printGroupMappingDataSet.PrintGroupMapping); + return printGroupMappingDataSet; + }) + as PrintGroupMappingDataSet; + + return printGroupMappingDataSet; + } + + See http://www.code-magazine.com/articleprint.aspx?quickid=0605031 for a + more complete discussion. + + + + + + Applies the connection and tx to the provided typed dataset. The connection and transaction + used are taken from the Spring's current transactional context. See ConnectionUtils.GetConnectionTxPair + for more information + + The typed data set adapter. + The db provider. + + + + Applies the connection and tx to the provided typed dataset. + + Generated dataset to not inherit from a common base + class so that we must pass in the generic object type. + The typed data set adapter. + The IDbCommand managed by Spring and set with + the connection/transaction of the current Spring transaction scope. + + + + Exception thrown when SQL specified is invalid. + + Mark Pollack (.NET) + + + + SQL that led to the problem + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + A message about the exception. + + + + Initializes a new instance of the class. + + A message about the exception. + The inner exception. + + + + Initializes a new instance of the class. + + name of the current task. + The offending SQL statment + The root cause. + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + When overridden in a derived class, sets the + with information about the exception. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The parameter is a null reference ( in Visual Basic). + + + + Fatal exception thrown when we can't connect to an RDBMS using ADO.NET + + Rod Johnson + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + A message about the exception. + + + + Initializes a new instance of the class. + + A message about the exception. + The inner exception. + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Callback delegate for code that operates on a IDbCommand. + + the ADO.NET command object. + +

Allows you to execute any number of operations + on a single IDbCommand, for example a single ExecuteScalar + call or repeated execute calls with varying parameters. +

+

Used internally by AdoTemplate, but also useful for + application code. Note that the passed in IDbCommand + has been created by the framework and will have its + Connection property set and the Transaction property + set based on the transaction context.

+ + Mark Pollack + + + + Callback delegate to set any necessary parameters or other + properties on the command object. The CommandType and + CommandText properties will have already been supplied + + The database command object. + Mark Pollack + + + + Exception thrown when an attempt to insert or update data + results in violation of an primary key or unique constraint. + Note that this is not necessarily a purely relational concept; + unique primary keys are required by most database types. + + Thomas Risberg + Mark Pollack (.NET) + + + + SQL that led to the problem + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + A message about the exception. + + + + Initializes a new instance of the class. + + A message about the exception. + The inner exception. + + + + Initializes a new instance of the class. + + name of the current task. + The offending SQL statment + The root cause. + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + When overridden in a derived class, sets the + with information about the exception. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The parameter is a null reference ( in Visual Basic). + + + + Gets the SQL that caused the exception + + The SQL that caused the exception. + + + + Called by the AdoTemplate class to allow implementations + to set any necessary parameters on the command object. + The CommandType and CommandText will have already been supplied. + + Mark Pollack (.NET) + + + + Called by the AdoTemplate class to allow implementations + to set any necessary properties on the DbDataAdapter object. + + +

For example, this callback can be used to set the + AcceptChangesDuringFill property, register an event handler + for the FillErrors event, set update batch sizes if your provider + supports such functionality, set the ContinueUpdateOnError property, + or in .NET 2.0 to set the property AcceptChangesDuringUpdate. +

+

+ Downcast to the appropriate subtype to access vendor specific + functionality.

+

+ The DataAdapter SelectCommand will be already be + populated with values for CommandType and Text properties + along with Connection/Transaction properties based on the + calling transaction context. +

+ + Mark Pollack (.NET) + + + + Lifecycle callback methods that can be registered when + performing Fill operations with AdoTemplate. + + +

+ The methods let you set various properties and invoke + methods on the DataSet before and after it gets filled by a DataAdapter. + For example, EnforceConstraints, BeginLoadData, and EndLoadData + can be called to optimize the loading of large DataSets with + many related tables. +

+

Vendors may expose other propriety methods on their DataSet + implementation, downcast to access this specific functionality. +

+ + Mark Pollack (.NET) + + + + Called before a DataAdapter is used to fill a DataSet + the the provided tablename. + + The DataSet to be filled with a DataTable + The table collection to be filled + + + + Called after a DataAdapter is used to fill a DataSet + the the provided tablename. + + The DataSet to be filled with a DataTable + The table collection to be filled + + + + One of the central callback interfaces used by the AdoTemplate class + This interface creates a IDbCommand. Implementations are responsible + for configuring the created command with command type, command text and + any necessary parameters. + + Mark Pollack (.NET) + + + + Creates a IDbCommand. + + The IDbProvider reference that can be used to create the command in a + provider independent manner. The provider supplied is the same as used in configuration of AdoTemplate. + + + + + Helper class that can efficiently create multiple IDbCommand + objects with different parameters based on a SQL statement and a single + set of parameter declarations. + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + This interface creates a IDbDataAdapterCommand. + Implementations are responsible + for configuring the created command with appropriate + select and actions commands along with their parameters. + + + Generally used to to support the DataSet functionality in + the Spring.Data.Objects namespace. + + Mark Pollack (.NET) + + + + Creates the data adapter. + + A new IDbDataAdapter instance + + + + Exception thrown when a result set has been accessed in an invalid fashion. + + Mark Pollack (.NET) + + + + SQL that led to the problem + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + A message about the exception. + + + + Initializes a new instance of the class. + + A message about the exception. + The inner exception. + + + + Initializes a new instance of the class. + + name of the current task. + The offending SQL statment + The root cause. + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + When overridden in a derived class, sets the + with information about the exception. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The parameter is a null reference ( in Visual Basic). + + + + Gets the SQL that caused the exception + + The SQL that caused the exception. + + + + Callback to process each row of data in an AdoOperation's Query method. + + + Implementations of this interface perform the actual work of extracting + results. In contrast to a IResultSetExtractor, a IRowCallback object is typically + stateful. It keeps the result state within the object, to be available + for later inspection. + + + + + + Implementations must implement this method to process each row of data + in the data reader. + + + This method should not advance the cursor by calling Read() + on IDataReader but only extract the current values. The + caller does not need to care about closing the reader, command, connection, or + about handling transactions: this will all be handled by + Spring's AdoTemplate + + An active IDataReader instance + The result object + + + + Callback delegate to process all result sets and row in an + AdoTemplate query method. + + + Implementations of this delegate perform the work + of extracting results but don't need worry about managing + ADO.NET resources, such as closing the reader, or transaction management. + + The IDataReader to extract data from. + Implementations should not close this: it will be closed + by the AdoTemplate. + An arbitrary result object or null if none. + + + + Callback delegate to process each row of data in a result set to an object. + + The IDataReader to map + the number of the current row. + An abrirary object, typically derived from data + in the result set. + + + + Exception thrown when we can't classify a SQLException into + one of our generic data access exceptions. + + Mark Pollack (.NET) + + + + SQL that led to the problem + + + + + The error code, if available, that was unable to be categorized. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + A message about the exception. + + + + Initializes a new instance of the class. + + A message about the exception. + The inner exception. + + + + Initializes a new instance of the class. + + name of the current task. + the underlying error code that could not be translated + The offending SQL statment + The root cause. + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + When overridden in a derived class, sets the + with information about the exception. + + The that holds the serialized object data about the exception being thrown. + The that contains contextual information about the source or destination. + The parameter is a null reference ( in Visual Basic). + + + + Return the underlying error code if available from the underlying provider. + + + + + Return the SQL that resulted in this exception. + + + + + IObjectDefinitionParser implementation that allows users to easily configure all the + infrastructure objects required to enable attribute-driven transction demarcation. + + Rob Harrop + Juergen Hoeller + Mark Pollack (.NET) + + + + The 'proxy-target-type' attribute + + + + + The 'order' property/attribute + + + + + Central template method to actually parse the supplied XmlElement + into one or more IObjectDefinitions. + + The element that is to be parsed into one or more s + The the object encapsulating the current state of the parsing process; + provides access to a + + The primary IObjectDefinition resulting from the parsing of the supplied XmlElement + + + + + Configures the auto proxy creator. + + The parser context. + The element. + + + + Gets a value indicating whether an ID should be generated instead of read + from the passed in XmlElement. + + true if should generate id; otherwise, false. + Note that this flag is about always generating an ID; the parser + won't even check for an "id" attribute in this case. + + + + + The for the <tx:advice> tag. + + Rob Harrop + Juergen Hoeller + Adrian Colyer + Mark Pollack (.NET) + + + + NamespaceParser allowing for the configuration of + declarative transaction management using either XML or using attributes. + + This namespace handler is the central piece of functionality in the + Spring transaction management facilities and offers two appraoches + to declaratively manage transactions. + + One approach uses transaction semantics defined in XML using the + <tx:advice> elements, the other uses attributes + in combination with the <tx:annotation-driven> element. + Both approached are detailed in the Spring reference manual. + + + + + Register the for the 'advice' and + 'attribute-driven' tags. + + + + + This is a utility class to help in parsing the transaction namespace + + Mark Pollack + + + + The transaction manager attribute + + + + + The source of transaction metadata + + + + + The property asociated with the transaction manager xml element + + + + + Abstract implementation of + + that caches attributes for methods, and implements a default fallback policy. + + +

+ The default fallback policy applied by this class is: + + + most specific method + + + target class attribute + + + declaring method + + + declaring class + + +

+

+ Defaults to using class's transaction attribute if none is associated + with the target method. Any transaction attribute associated with the + target method completely overrides a class transaction attribute. +

+

+ This implementation caches attributes by method after they are first used. + If it's ever desirable to allow dynamic changing of transaction attributes + (unlikely) caching could be made configurable. Caching is desirable because + of the cost of evaluating rollback rules. +

+ + Rod Johnson + Griffin Caprio (.NET) + Mark Pollack (.NET) + + + + Interface used by + to source transaction attributes. + + +

+ Implementations know how to source transaction attributes, whether from configuration, + metadata attributes at source level, or anywhere else. +

+ + Rod Johnson + Griffin Caprio (.NET) + + + + Return the for this + method. + + The method to check. + + The target . May be null, in which case the declaring + class of the supplied must be used. + + + A or + null if the method is non-transactional. + + + + + Canonical value held in cache to indicate no transaction attibute was found + for this method, and we don't need to look again. + + + + + Cache of s, keyed by method and target class. + + + + + Creates a new instance of the + + class. + + +

+ This is an class, and as such exposes no public constructors. +

+ + + + + Subclasses should implement this to return all attributes for this method. + May return null. + + + We need all because of the need to analyze rollback rules. + + The method to retrieve attributes for. + The transactional attributes associated with the method. + + + + Subclasses should implement this to return all attributes for this class. + May return null. + + + The to retrieve attributes for. + + + All attributes associated with the supplied . + + + + + Return the transaction attribute for this method invocation. + + + Defaults to the class's transaction attribute if no method + attribute is found + + method for the current invocation. Can't be null + target class for this invocation. May be null. + for this method, or null if the method is non-transactional + + + + Return the transaction attribute, given this set of attributes + attached to a method or class. Return null if it's not transactional. + + + Protected rather than private as subclasses may want to customize + how this is done: for example, returning a + + affected by the values of other attributes. + This implementation takes into account + s, if + the TransactionAttribute is a RuleBasedTransactionAttribute. + + + Attributes attached to a method or class. May be null, in which case a null + will be returned. + + + The configured transaction attribute, or null + if none was found. + + + + + Does the supplied satisfy this matcher? + + +

+ Must be implemented by a derived class in order to specify matching + rules. +

+ + The candidate method. + + The target (may be , + in which case the candidate must be taken + to be the 's declaring class). + + + if this this method matches statically. + + + + + Implementation of that uses + s. + + Rod Johnson + Griffin Caprio (.NET) + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + + implementation. + + + We need all because of the need to analyze rollback rules. + + The method to retrieve attributes for. + The transactional attributes associated with the method. + + + + + implementation. + + + The to retrieve attributes for. + + + All attributes associated with the supplied . + + + + + Transaction attribute approach to rolling back on all exceptions, no other + exceptions by default. + + Rod Johnson + Griffin Caprio (.NET) + + + + Default implementation of the + interface, offering object-style configuration and sensible default values. + + +

+ Base class for both and + . +

+ + Juergen Hoeller + Griffin Caprio (.NET) + Mark Pollack (.NET) + + + + Interface for classes that define transaction properties. Base interface for + . + + +

+ Note that isolation level, timeout and read-only settings will only + get applied when starting a new transaction. As only + and + can actually cause that, it doesn't make sense + to specify any of those settings else. Furthermore, not all transaction + managers will support those features and thus throw respective exceptions + when given non-default values. +

+ + Griffin Caprio (.NET) + Mark Pollack (.NET) + + + + Return the propagation behavior of type + . + + + + + Return the isolation level of type . + + +

+ Only makes sense in combination with + and + . +

+

+ Note that a transaction manager that does not support custom isolation levels + will throw an exception when given any other level than + . +

+ + + + + Return the transaction timeout. + + +

+ Must return a number of seconds, or -1. + Only makes sense in combination with + and + . + Note that a transaction manager that does not support timeouts will + throw an exception when given any other timeout than -1. +

+ + + + + Get whether to optimize as read-only transaction. + + +

+ This just serves as hint for the actual transaction subsystem, + it will not necessarily cause failure of write accesses. +

+

+ Only makes sense in combination with + and + . +

+

+ A transaction manager that cannot interpret the read-only hint + will not throw an exception when given ReadOnly=true. +

+ + + + + Return the name of this transaction. Can be null. + + + This will be used as a transaction name to be shown in a + transaction monitor, if applicable. In the case of Spring + declarative transactions, the exposed name will be the fully + qualified type name + "." method name + assembly (by default). + + + + + Gets the enterprise services interop option. + + The enterprise services interop option. + + + + The default transaction timeout. + + + + + Prefix for Propagation settings. + + + + + Prefix for IsolationLevel settings. + + + + + Prefix for transaction timeout values in description strings. + + + + + Marker for read-only transactions in description strings. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class + with the supplied + behaviour. + + + The desired behavior. + + + + + An override of the default method. + + The to compare to. + True if the objects are equal. + + + + An override of the default method that returns the + hashcode of the + + property. + + + The hashcode of the + + property. + + + + + An override of the default method that returns a string + representation of the + + property. + + + A string representation of the + + property. + + + + + Gets / Sets the propagation + behavior. + + + + + Return the isolation level of type . + + +

+ Only makes sense in combination with + and + . +

+

+ Note that a transaction manager that does not support custom isolation levels + will throw an exception when given any other level than + . +

+ + + + + Return the transaction timeout. + + +

+ Must return a number of seconds, or -1. + Only makes sense in combination with + and + . + Note that a transaction manager that does not support timeouts will + throw an exception when given any other timeout than -1. +

+ + + + + Get whether to optimize as read-only transaction. + + +

+ This just serves as hint for the actual transaction subsystem, + it will not necessarily cause failure of write accesses. +

+

+ Only makes sense in combination with + and + . +

+

+ A transaction manager that cannot interpret the read-only hint + will not throw an exception when given ReadOnly=true. +

+ + + + + Return the name of this transaction. Can be null. + + + + This will be used as a transaction name to be shown in a + transaction monitor, if applicable. In the case of Spring + declarative transactions, the exposed name will be the fully + qualified type name + "." method name + assembly (by default). + + + + + Gets the enterprise services interop option. + + The enterprise services interop option. + + + + Returns a representation of the + + property. + + + + + This interface adds a + + specification to . + + Griffin Caprio (.NET) + + + + Decides if rollback is required for the supplied . + + The to evaluate. + True if the exception causes a rollback, false otherwise. + + + + Prefix for rollback-on-exception rules in description strings. + + + + + Prefix for commit-on-exception rules in description strings. + + + + + Creates a new instance of the + + class. + + + + + Creates a new instance of the + + class, setting the propagation behavior to the supplied value. + + + The desired transaction propagation behaviour. + + + + + Decides if rollback is required for the supplied . + + +

+ The default behavior is to rollback on any exception. + Consistent with 's behavior. +

+ + The to evaluate. + True if the exception causes a rollback, false otherwise. + + + + Return a description of this transaction attribute. + + +

+ The format matches the one used by the + , + to be able to feed any result into a + instance's properties. +

+ + + + + Advisor driven by a , + used to exclude a general advice from methods that + are non-transactional. + + + + To put it another way, use this advisor when you would like to associate other AOP + advice based on the pointcut specified by declarative transaction demarcation, + attibute based or otherwise. + +

+ Because the AOP framework caches advice calculations, this is normally + faster than just letting the + run and find out itself that it has no work to do. +

+ + Mark Pollack (.NET) + + + + Creates a new instance of the + class. + + + + + Tests the input method to see if it's covered by the advisor. + + The method to match. + The to match against. + + True if the supplied is covered by the advisor. + + + + + ITransactionAttribute that delegates all calls to a give target attribute except for the + name, which is specified in the constructor. + + + + + Initializes a new instance of the class. + + The target attribute. + The identification. + + + + Decides if rollback is required for the supplied . + + The to evaluate. + + True if the exception causes a rollback, false otherwise. + + + + + Return a description of this transaction attribute. + + +

+ The format matches the one used by the + , + to be able to feed any result into a + instance's properties. +

+ + + + + Return the propagation behavior of type + . + + + + + + Return the isolation level of type . + + + +

+ Only makes sense in combination with + and + . +

+

+ Note that a transaction manager that does not support custom isolation levels + will throw an exception when given any other level than + . +

+ + + + + Return the transaction timeout. + + + +

+ Must return a number of seconds, or -1. + Only makes sense in combination with + and + . + Note that a transaction manager that does not support timeouts will + throw an exception when given any other timeout than -1. +

+ + + + + Get whether to optimize as read-only transaction. + + + +

+ This just serves as hint for the actual transaction subsystem, + it will not necessarily cause failure of write accesses. +

+

+ Only makes sense in combination with + and + . +

+

+ A transaction manager that cannot interpret the read-only hint + will not throw an exception when given ReadOnly=true. +

+ + + + + Return the name of this transaction. + + + + The exposed name will be the fully + qualified type name + "." method name + assembly (by default). + + + + + Gets the enterprise services interop option. + + The enterprise services interop option. + + + + Very simple implementation of + which will always return the same + for all methods fed to it. + + +

+ The + may be specified, but will otherwise default to PROPAGATION_REQUIRED. This may be + used in the cases where you want to use the same transaction attribute with all + methods being handled by a transaction interceptor. +

+ + Colin Sampaleanu + Griffin Caprio (.NET) + + + + Creates a new instance of the + + class. + + + + + Return the for this + method. + + The method to check. + + The target . May be null, in which case the declaring + class of the supplied must be used. + + + A or + null if the method is non-transactional. + + + + + Determines whether the specified is equal to the current . + + The to compare with the current . + + true if the specified is equal to the current ; otherwise, false. + + + + + Serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Returns a that represents the current . + + + + A that represents the current . + + 2 + + + + Allows a transaction attribute to be specified, using the + form, for example, "PROPAGATION_REQUIRED". + + + + + Simple implementation of the + interface that allows attributes to be stored per method in a map. + + Rod Johnson + Juergen Hoeller + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Add an attribute for a transactional method. + + + Method names can end or start with "*" for matching multiple methods. + + The class and method name, separated by a dot. + The attribute to be associated with the method. + + + + Add an attribute for a transactional method. + + + Method names can end or start with "*" for matching multiple methods. + + The target interface or class. + The mapped method name. + + The attribute to be associated with the method. + + + + + Add an attribute for a transactional method. + + The transactional method. + + The attribute to be associated with the method. + + + + + Does the supplied match the supplied ? + + + The default implementation checks for "xxx*", "*xxx" and "*xxx*" matches, + as well as direct equality. This behaviour can (of course) be overridden in + derived classes. + + The method name of the class. + The name in the descriptor. + True if the names match. + + + + Return the for this + method. + + The method to check. + + The target . May be null, in which case the declaring + class of the supplied must be used. + + + A or + null if the method is non-transactional. + + + + + Set a name/attribute map, consisting of "FQCN.method, AssemblyName" method names + (e.g. "MyNameSpace.MyClass.MyMethod, MyAssembly") and ITransactionAttribute + instances (or Strings to be converted to instances). + + +

+ The key values of the supplied + must adhere to the following form:
+ FQCN.methodName, Assembly. +

+ + MyNameSpace.MyClass.MyMethod, MyAssembly + + + + + + Simple implementation of the + that allows attributes to be matched by registered name. + + Juergen Hoeller + Griffin Caprio (.NET) + + + + Logger available to subclasses, static for optimal serialization + + + + + Keys are method names; values are ITransactionAttributes + + + + + Creates a new instance of the + class. + + + + + Enumerate the string/ mapping entries. + + + + + Add a mapping. + + + + + Add a mapping. + + + + + Does the supplied match the supplied ? + + + The default implementation checks for "xxx*", "*xxx" and "*xxx*" matches, + as well as direct equality. Can be overridden in subclasses. + + The method name of the class. + The name in the descriptor. + True if the names match. + + + + Add an attribute for a transactional method. + + +

+ Method names can end with "*" for matching multiple methods. +

+ + The transactional method name. + + The attribute to be associated with the method. + + + + + Parses the given properties into a name/attribute map. + + + Expects method names as keys and string attributes definitions as values, + parsable into + instances via + . + + The properties of the transaction. + + + + Return the for this + method. + + The method to check. + + The target . May be null, in which case the declaring + class of the supplied must be used. + + + A or + null if the method is non-transactional. + + + + + Set a name/attribute map, consisting of method names (e.g. "MyMethod") and + instances + (or Strings to be converted to ITransactionAttribute instances). + + + + + Parses the given properties into a name/attribute map. + + + Expects method names as keys and string attributes definitions as values, + parsable into + instances via + . + + The properties of the transaction. + + + + Tag class. Its class means it has the opposite behaviour to the + superclass. + + Rod Johnson + Griffin Caprio (.NET) + + + + Rule determining whether or not a given exception (and any subclasses) should + cause a rollback. + + +

+ Multiple such rules can be applied to determine whether a transaction should commit + or rollback after an exception has been thrown. +

+ + Griffin Caprio (.NET) + + + + Could hold exception, resolving class name but would always require FQN. + This way does multiple string comparisons, but how often do we decide + whether to roll back a transaction following an exception? + + + + + Canonical instance representing default behavior for rolling back on + all s. + + + + + Creates a new instance of the + class + for the named . + + The exception name. + +

+ As always, the should be the full + assembly qualified version. +

+ + + + + Creates a new instance of the + class + for the suplied . + + +

+ The exception class must be or a subclass. +

+

+ This is the preferred way to construct a + , + matching the exception class and subclasses. +

+ + + The class that will trigger a rollback. + + + + + Return the depth to the matching superclass execption . + + + A return value of 0 means that the matches. + + + The of exception to find. + + + Return -1 if there's no match. Otherwise, return depth. Lowest depth wins. + + + + + Return the depth to the matching superclass execption . + + + A return value of 0 means that the s + matches. + + + The exception object to find. + + + Return -1 if there's no match. Otherwise, return depth. Lowest depth wins. + + + + + Returns a representation of this instance. + + + A containing the exception covered by this instance. + + + + + Override of . + + The hashcode of the exception name covered by this instance. + + + + Override of . + + The object to compare. + True if the input object is equal to this instance. + + + + Strongly typed Equals() implementation. + + + The to compare. + + + True if the input object is equal to the supplied . + + + + + Returns the name of the exception. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + The class that will trigger a rollback. + + + + + The that drives this advisor. + + + + + implementation + that works out whether a given exception should cause transaction rollback by applying + a number of rollback rules, both positive and negative. + + + If no rules are relevant to the exception, it behaves like the + class + (rolling back on runtime exceptions).. +

+ The + creates objects of this class. +

+ + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + + class. + + + The desired transaction propagation behaviour. + + + The rollback rules list for this transaction attribute. + + + + + Creates a new instance of the + + class. + + + + + Will a transaction be rolled back if the supplied + is thrown during the lifecycle of a transaction to which this attribute is applied? + + The offending . + True if the exception should cause a rollback, false otherwise. + + + + Returns a representation of this instance. + + + A representation of this instance. + + + + + Adds a to this + attributes list of rollback rules. + + + The to add. + + + + + Clears the rollback rules for this attribute. + + + + + Sets the rollback rules list for this transaction attribute. + + + + + Superclass for transaction aspects, such as the AOP Alliance-compatible + . + + +

+ This enables the underlying Spring transaction infrastructure to be used + to easily implement an aspect for any aspect system. +

+

+ Subclasses are responsible for calling methods in this class in the correct order. +

+

+ Uses the Strategy design pattern. A + implementation will perform the actual transaction management +

+

+ A transaction aspect is serializable if its + and + are serializable. +

+ + Rod Johnson + Juergen Hoeller + Griffin Caprio (.NET) + Mark Pollack (.NET) + + + + The name in thread local storage where the TransactionInfo object is located + + + + + The currently referenced by + this aspect + + + + + The currently + referenced by this aspect. + + + + + Creates a new instance of the + class. + + + + + Checks that the required properties are set. + + + + + Create a transaction if necessary + + Method about to execute + Type that the method is on + + A object, + whether or not a transaction was created. +

+ The + + property on the + + class can be used to tell if there was a transaction created. +

+ + + + + Creates the transaction if necessary. + + The source transaction attribute. + The joinpoint identification. + Transaction Info for declarative transaction management. + + + + Identifies the method by providing the qualfied method name. + + The method info. + qualified mehtod name. + + + + Execute after the successful completion of call, but not after an exception was handled. + + +

+ Do nothing if we didn't create a transaction. +

+ + + The + + about the current transaction. + + + + + Handle a exception, closing out the transaction. + + +

+ We may commit or roll back, depending on our configuration. +

+ + + The + + about the current transaction. + + The encountered. + + + + Resets the + + for this thread. + + + + Call this in all cases: exceptions or normal return. + + + + The + + about the current transaction. May be null. + + + + + Gets and sets the for + this aspect. + + + + + Gets and sets the + for + this aspect. + + + + + Returns the + of the current method invocation. + + + Mainly intended for code that wants to set the current transaction + rollback-only but not throw an application exception. + + + If the transaction info cannot be found, because the method was invoked + outside of an AOP invocation context. + + + + + Subclasses can use this to return the current + . + + + Only subclasses that cannot handle all operations in one method + need to use this mechanism to get at the current + . + An around advice such as an AOP Alliance + can hold a reference to the + + throughout the aspect method. + A + will be returned even if no transaction was created. The + + property can be used to query this. + + + If no transaction has been created by an aspect. + + + + + Set properties with method names as keys and transaction attribute + descriptors (parsed via ) as values: + e.g. key = "MyMethod", value = "PROPAGATION_REQUIRED,readOnly". + + + + Method names are always applied to the target class, no matter if defined in an + interface or the class itself. + +

+ Internally, a + + will be created from the given properties. +

+ + + + + Opaque object used to hold transaction information. + + +

+ Subclasses must pass it back to method on this class, but not see its internals. +

+ + + + + Creates a new instance of the + + class for the supplied . + + The transaction attributes to associate with any transaction. + The info for diagnostic display of joinpoint + + + + Binds this + + instance to the thread local storage variable for the current thread and + backs up the existing + + object for the current thread. + + + + + Restores the previous + + object to the current thread. + + + + + Does this instance currently have a transaction? + + True if this instance has a transaction. + + + + Gets and sets the for this object. + + + + + Gets the current + for this + + object. + + + + + Gets the joinpoint identification. + + The joinpoint identification. + + + + .NET Attribute for describing transactional behavior of methods in a class. + + This attribute type is generally directly comparable + to Spring's class and + in fact will + directly convert the data to a + so that Spring's transaction support code does not have to know about + attributes. If no rules are relevant to the exception it will be treaded + like DefaultTransactionAttribute, (rolling back on all exceptions). + + The default property values are TransactionPropagation.Required, IsolationLevel.ReadCommitted, + DefaultTransactionDefinition.TIMEOUT_DEFAULT (can be changed, by default is the default + value of the underlying transaction subsystem) + ReadOnly = false, and Type.EmtptyTypes specified for Rollbackfor and NoRollbackFor exception + types. + + + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The transaction propagation. + + + + Initializes a new instance of the class. + + The transaction propagation. + The isolation level. + + + + Initializes a new instance of the class. + + The isolation level. + + + + Gets the transaction propagation. + + Defaults to TransactionPropagation.Required + The transaction propagation. + + + + Gets the isolation level. + + Defaults to IsolationLevel.Unspecified + The isolation level. + + + + Gets or sets the timeout. + + Defaults to the default timeout of the underlying transaction system. + The timeout. + + + + Gets or sets a value indicating whether the transaction is readonly. + + Defaults to false + true if read-only; otherwise, false. + + + + Gets or sets the zero or more exception types which + indicating which exception types must cause a transaction + rollback. + + This is the preferred way to construct a rollback rule, + matching the exception class and subclasses. + The rollback types. + + + + Gets or sets zero or more exceptions types which + indicationg which exception type must not + cause a transaction rollback. + + This is the preferred way to construct a rollback rule, + matching the exception type. + The no rollback for. + + + + Gets or sets the enterprise services interop option. + + The enterprise services interop option. + + + + Type converter for + objects. + + + Takes s of the form +

PROPAGATION_NAME,ISOLATION_NAME,readOnly,timeout_NNNN,+Exception1,-Exception2

+

where only propagation code is required. For example:

+

PROPAGATION_MANDATORY,ISOLATION_DEFAULT

+

+ The tokens can be in any order. Propagation and isolation codes + must use the names of the values in the + enumeration. Timeout values are in seconds. If no timeout is specified, the transaction + manager will apply a default timeout specific to the particular transaction manager. +

+

+ A "+" before an exception name substring indicates that transactions should commit even + if this exception is thrown; a "-" that they should roll back. +

+ + Mark Pollack + + + + Returns whether this converter can convert an object of the given type to an ITransactionAttribute, using the specified context. + + An that provides a format context. + A that represents the type you want to convert from. + + true if this converter can perform the conversion; otherwise, false. + + + + + Converts from string to ITransactionAttribute + + The context. + The culture. + The string value to convert + An ITransactionAttribute instance + + + + Type converter for + objects. + + + Takes s of the form +

PROPAGATION_NAME,ISOLATION_NAME,readOnly,timeout_NNNN,+Exception1,-Exception2

+

where only propagation code is required. For example:

+

PROPAGATION_MANDATORY,ISOLATION_DEFAULT

+

+ The tokens can be in any order. Propagation and isolation codes + must use the names of the values in the + enumeration. Timeout values are in seconds. If no timeout is specified, the transaction + manager will apply a default timeout specific to the particular transaction manager. +

+

+ A "+" before an exception name substring indicates that transactions should commit even + if this exception is thrown; a "-" that they should roll back. +

+ + Rod Johnson + Juergen Hoeller + Griffin Caprio (.NET) + + + + Parses the input properties string into a valid + instance + + + The string defining the transactional properties. + + + + + Gets the + from this editor. + + + + + Advisor driven by a , used to include + a for methods that + are transactional. + + +

+ Because the AOP framework caches advice calculations, this is normally + faster than just letting the + run and find out itself that it has no work to do. +

+ + Rod Johnson + Griffin Caprio (.NET) + + + + Initializes a new instance of the class. + + +

+ This is an abstract class, and as such has no publicly + visible constructors. +

+ + + + + Creates a new instance of the + class. + + + The pre-configured transaction interceptor. + + + + + Tests the input method to see if it's covered by the advisor. + + The method to match. + The to match against. + + True if the supplied is covered by the advisor. + + + + + Sets the tx attribute source. + + The transaction interceptor. + + + + Sets the transaction interceptor. + + The transaction interceptor. + + + + Editor that can convert values into + instances. + + + The transaction attribute string must be parseable by the + in this package. +

+ Strings must be specified in the following syntax:
+ FQCN.methodName=<transaction attribute string> (sans <>). +

+ + ExampleNamespace.ExampleClass.MyMethod=PROPAGATION_MANDATORY,ISOLATION_DEFAULT + + + The specified class must be the one where the methods are defined; in the case of + implementing an interface, the interface class name must be specified. + +

+ This will register all overloaded methods for a given name. Does not support explicit + registration of certain overloaded methods. Supports wildcard style mappings (in + the form "xxx*"), e.g. "Notify*" for "Notify" and "NotifyAll". +

+ + Rod Johnson + Juergen Hoeller + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Parses the input properties into a valid + + instance + + The properties string to be parsed. + + + + Gets the + from this instance. + + + + + Internal class to parse property values. + + + + + Creates a new instance of the + class. + + The property values to be parsed. + + + + Indexer to return values based on index value. + + + + + Returns the collection of keys for properties. + + + + + An AOP Alliance providing + declarative transaction management using the common Spring.NET transaction infrastructure. + + +

+ That class contains the necessary calls into Spring.NET's underlying + transaction API: subclasses such as this are responsible for calling + superclass methods such as + + in the correct order, in the event of normal invocation return or an exception. +

+

+ s are thread-safe. +

+ + Rod Johnson + Juergen Hoeller + Griffin Caprio (.NET) + Mark Pollack (.NET) + + + + AOP Alliance invoke call that handles all transaction plumbing. + + + The method that is to execute in the context of a transaction. + + The return value from the method invocation. + + + + Proxy factory object for simplified declarative transaction handling. + + +

+ Alternative to the standard AOP + with a . +

+

+ This class is intended to cover the typical case of declarative + transaction demarcation: namely, wrapping a (singleton) target object with a + transactional proxy, proxying all the interfaces that the target implements. +

+

+ Internally, a + instance is used, but the user of this class does not have to care. Optionally, an + can be specified to cause conditional invocation of + the underlying . +

+

+ The + + and + + properties can be set to add additional interceptors to the mix. +

+ + Juergen Hoeller + Dmitriy Kopylenko + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Returns the object wrapped by this proxy factory. + + The target object proxy. + + + + Method run after all the properties have been set for this object. + Responsible for actual proxy creation. + + + + + Set the target or . + + + The target. If this is an implementation of the + interface, it is used as our ; otherwise it is + wrapped in a . + + An for this object. + + + + Set the transaction manager for this factory. + + + It is this instance that will perform actual transaction management: this class is + just a way of invoking it. + + + + + Set the target object, i.e. the object to be wrapped with a transactional proxy. + + +

+ The target may be any object, in which case a + will + be created. If it is a , no wrapper + is created: this enables the use of a pooling + or prototype . +

+ + + + + Specify the set of interfaces being proxied. + + +

+ If left null (the default), the AOP infrastructure works + out which interfaces need proxying by analyzing the target, + proxying all of the interfaces that the target object implements. +

+ + + + + Set properties with method names as keys and transaction attribute + descriptors as values. + + +

+ The various transaction attribute descriptors are parsed via + an instance of the + class. +

+ + Method names are always applied to the target class, no matter if defined in an + interface or the class itself. + +

+ Internally, a + + will be created from the given properties. +

+ + +

+ An example string (method name and transaction attributes) might be: +

+

+ key = "myMethod", value = "PROPAGATION_REQUIRED,readOnly". +

+ + + + + Set the transaction attribute source which is used to find transaction + attributes. + + +

+ If specifying a property value, an + appropriate + implementation will create a + + from the value. +

+ + + + + Set a pointcut, i.e an object that can cause conditional invocation + of the + depending on method and attributes passed. + + + + Additional interceptors are always invoked. + + + + + + Set additional interceptors (or advisors) to be applied before the + implicit transaction interceptor. + + + + + Set additional interceptors (or advisors) to be applied after the + implicit transaction interceptor. + + +

+ Note that this is just necessary if you rely on those interceptors in general. +

+ + + + + Specify the to use. + + The default instance is the global AdvisorAdapterRegistry. + + + + Returns the object for this proxy factory. + + + + + Is this object a singleton? Always returns true in this implementation. + + + + + Default implementation of the interface, + used by . + + +

+ Holds all status information that + + needs internally, including a generic transaction object determined by + the concrete transaction manager implementation. +

+

+ Supports delegating savepoint-related methods to a transaction object + that implements the interface. +

+ + Juergen Hoeller + Griffin Caprio (.NET) + Mark Pollack (.NET) + + + + Representation of the status of a transaction, + consisting of a transaction object and some status flags. + + +

+ Transactional code can use this to retrieve status information, + and to programmatically request a rollback (instead of throwing + an exception that causes an implicit rollback). +

+

+ Derives from the interface to provide access + to savepoint management facilities. Note that savepoint management + is just available if the actual transaction manager supports it. +

+ + Juergen Hoeller + Griffin Caprio (.NET) + Mark Pollack (.NET) + + + + Set the transaction rollback-only. This instructs the transaction manager that the only possible outcome of + the transaction may be a rollback, proceeding with the normal application + workflow though (i.e. no exception). + + +

+ For transactions managed by a or + . + An alternative way to trigger a rollback is throwing an transaction exception. +

+ + + + + Returns true if the transaction is new, else false if participating + in an existing transaction. + + + + + Return whether the transaction has been marked as rollback-only, + (either by the application or by the transaction infrastructure). + + + + + Gets the current transaction object. + + + Returns the current transaction object for a given connection. +

+ Used to associate with the property. +

+ + + + + Creates a new instance of the + class. + + The underlying transaction object that can hold state for the internal + transaction implementation. + True if the transaction is new, else false if participating in an existing transaction. + True if a new transaction synchronization has been opened for the given + . + True if the transaction is read only. + if set to true, enable debug log in tx managers. + The suspended resources for the given . + + + + Determines whether there is an actual transaction active. + + + true if there is an actual transaction active; otherwise, false. + + + + + Set the transaction rollback-only. This instructs the transaction manager that the only possible outcome of + the transaction may be a rollback, proceeding with the normal application + workflow though (i.e. no exception). + + +

+ For transactions managed by a or + . + An alternative way to trigger a rollback is throwing an transaction exception. +

+ + + + + This implementation delegates to the underlying transaction object + (if it implements the interface) + to create a savepoint. + + + If the underlying transaction does not support savepoints. + + + + + This implementation delegates to the underlying transaction object + (if it implements the interface) + to rollback to the supplied . + + The savepoint to rollback to. + + + + This implementation delegates to the underlying transaction object + (if it implements the interface) + to release the supplied . + + The savepoint to release. + + + + Create a savepoint and hold it for the transaction. + + + If the underlying transaction does not support savepoints. + + + + + Roll back to the savepoint that is held for the transaction. + + + If no save point has been created. + + + + + Release the savepoint that is held for the transaction. + + + If no save point has been created. + + + + + Gets a value indicating whether the progress of this transaction is debugged. + This is used by AbstractPlatformTransactionManager as an optimization, to prevent repeated + calls to log.IsDebug. Not really intended for client code. + true if debug; otherwise, false. + + + + Returns the underlying transaction object. + + + + + Gets or sets a value indicating whether the Transaction is completed, that is commited or rolled back. + + true if completed; otherwise, false. + + + + Returns true if the underlying transaction is read only. + + + + + Flag indicating if a new transaction synchronization has been opened + for this transaction. + + + + + Returns suspended resources for this transaction. + + + + + Gets and sets the savepoint for the current transaction, if any. + + + + + Returns a flag indicating if the transaction has a savepoint. + + + + + Return the underlying transaction as a + , if possible. + + + If the underlying transaction does not support savepoints. + + + + + Return true if the underlying transaction implements the + interface. + + + + + Returns true if the transaction is new, else false if participating + in an existing transaction. + + + + + Determine the rollbackOnly flag via checking both this + + and the transaction object, provided that the latter implements the + interface. + + The property can only be set to true. + + + + Determine the rollback-only flag via checking this TransactionStatus. Will only + return true if the application set the property RollbackOnly to true on this + TransactionStatus object. + + true if [local rollback only]; otherwise, false. + + + + Callback interface for transactional code. + + +

To be used with 's Execute + methods. +

+

+ Typically used to gather various calls to transaction-unaware low-level + services into a higher-level method implementation with transaction + demarcation. +

+ + Juergen Hoeller + Mark Pollack (.NET) + + + + Gets called by TransactionTemplate.Execute within a + transaction context. + + The associated transaction status. + A result object or null. + + + + Interface specifying basic transaction exectuion operations. + + + Implemented by . Not often used directly, + but a useful option to enhance testability, as it can easily be mocked or stubbed. + + Juergen Hoeller + Mark Pollac (.NET) + + + + Executes the the action specified by the given delegate callback within a transaction. + + Allows for returning a result object created within the transaction, that is, + a domain object or a collection of domain objects. An exception thrown by the callback + is treated as a fatal exception that enforces a rollback. Such an exception gets + propagated to the caller of the template. + + The delegate that specifies the transactional action. + A result object returned by the callback, or null if one + + In case of initialization or system errors. + + + + + Executes the action specified by the given callback object within a transaction. + + Allows for returning a result object created within the transaction, that is, + a domain object or a collection of domain objects. An exception thrown by the callback + is treated as a fatal exception that enforces a rollback. Such an exception gets + propagated to the caller of the template. + + The callback object that specifies the transactional action. + A result object returned by the callback, or null if one + + In case of initialization or system errors. + + + + + Simple convenience class for TransactionCallback implementation. + Allows for implementing a DoInTransaction version without result, + i.e. without the need for a return statement. + + Mark Pollack (.NET) + + + + Gets called by TransactionTemplate.execute within a transactional context + when no return value is required. + + The status. + + Does not need to care about transactions itself, although it can retrieve + and influence the status of the current transaction via the given status + object, e.g. setting rollback-only. + A RuntimeException thrown by the callback is treated as application + exception that enforces a rollback. An exception gets propagated to the + caller of the template. + + + + + Gets called by TransactionTemplate.Execute within a + transaction context. + + The associated transaction status. + a result object or null + + + + Callback delegate for performing actions within a transactional context. + + +

To be used with 's Execute + methods. +

+

+ Typically used to gather various calls to transaction-unaware low-level + services into a higher-level method implementation with transaction + demarcation. +

+ + The status of the transaction, can be used to + trigger a rollback the current transaction by settings its + RollbackOnly property to true. + A result object or null. + + + + Internal class that manages resources and transaction synchronizations per thread. + + + Supports one resource per key without overwriting, i.e. a resource needs to + be removed before a new one can be set for the same key. + Supports a list of transaction synchronizations if synchronization is active. +

+ Resource management code should check for thread-bound resources via GetResource(). + It is normally not supposed + to bind resources to threads, as this is the responsiblity of transaction managers. + A further option is to lazily bind on first use if transaction synchronization + is active, for performing transactions that span an arbitrary number of resources. +

+

+ Transaction synchronization must be activated and deactivated by a transaction + manager via + InitSynchronization + and + ClearSynchronization. + This is automatically supported by + . +

+

+ Resource management code should only register synchronizations when this + manager is active, and perform resource cleanup immediately else. + If transaction synchronization isn't active, there is either no current + transaction, or the transaction manager doesn't support synchronizations. +

+ Note that this class uses following naming convention for the + named 'data slots' for storage of thread local data, 'Spring.Transaction:Name' + where Name is either + + Juergen Hoeller + Griffin Caprio (.NET) + Mark Pollack (.NET) + + + + Check if there is a resource for the given key bound to the current thread. + + key to check + if there is a value bound to the current thread + + + + Retrieve a resource for the given key that is bound to the current thread. + + key to check + a value bound to the current thread, or null if none. + + + + Bind the given resource for teh given key to the current thread + + key to bind the value to + value to bind + + + + Unbind a resource for the given key from the current thread + + key to check + the previously bound value + if there is no value bound to the thread + + + + Activate transaction synchronization for the current thread. + + + Called by transaction manager at the beginning of a transaction. + + + If synchronization is already active. + + + + + Deactivate transaction synchronization for the current thread. + + + Called by transaction manager on transaction cleanup. + + + If synchronization is not active. + + + + + Clears the entire transaction synchronization state for the current thread, registered + synchronizations as well as the various transaction characteristics. + + + + + Register a new transaction synchronization for the current thread. + + + Typically called by resource management code. + + + If synchronization is not active. + + + + + Return all resources that are bound to the current thread. + + Main for debugging purposes. Resource manager should always + invoke HasResource for a specific resource key that they are interested in. + + IDictionary with resource keys and resource objects or empty + dictionary if none is bound. + + + + Return an unmodifiable list of all registered synchronizations + for the current thread. + + + A list of + instances. + + + If synchronization is not active. + + + + + Return if transaction synchronization is active for the current thread. + + + Can be called before + InitSynchronization + to avoid unnecessary instance creation. + + + + + Gets or sets a value indicating whether the + current transaction is read only. + + + Called by transaction manager on transaction begin and on cleanup. + Return whether the current transaction is marked as read-only. + To be called by resource management code when preparing a newly + created resource (for example, a Hibernate Session). +

Note that transaction synchronizations receive the read-only flag + as argument for the beforeCommit callback, to be able + to suppress change detection on commit. The present method is meant + to be used for earlier read-only checks, for example to set the + flush mode of a Hibernate Session to FlushMode.Never upfront. +

+ + + true if current transaction read only; otherwise, false. + + + + + Gets or sets the name of the current transaction, if any. + + Called by the transaction manager on transaction begin and on cleanup. + To be called by resource management code for optimizations per use case, for + example to optimize fetch strategies for specific named transactions. + The name of the current transactio or null if none set. + + + + Gets or sets a value indicating whether there currently is an actual transaction + active. + + This indicates wheter the current thread is associated with an actual + transaction rather than just with active transaction synchronization. + Called by the transaction manager on transaction begin and on cleanup. + To be called by resource management code that wants to discriminate between + active transaction synchronization (with or without backing resource transaction; + also on PROPAGATION_SUPPORTS) and an actual transaction being active; on + PROPAGATION_REQUIRES, PROPAGATION_REQUIRES_NEW, etC) + + true if [actual transaction active]; otherwise, false. + + + + + Gets or sets the current transaction isolation level, if any. + + Called by the transaction manager on transaction begin and on cleanup. + The current transaction isolation level. If no current transaction is + active, retrun IsolationLevel.Unspecified + + + + Enumeration containing the state of transaction synchronization. + + Griffin Caprio (.NET) + + + + Always activate transaction synchronization, even for "empty" transactions + that result from . + + with no existing backend transaction. + + + + Activate transaction synchronization only for actual transactions, + i.e. not for empty ones that result from . + + with no + existing backend transaction. + + + + Never active transaction synchronization. + + + + + Enumeration of status values when synchronizing transactions. + + Griffin Caprio + + + + Completion status in case of proper commit. + + + + + Completion status in case of proper rollback. + + + + + Completion status in case of heuristic mixed completion or system error. + + + + + Helper class that simplifies programmatic transaction demarcation and + transaction exception handling. + + +

+ The central methods are + + and + supporting transactional code wrapped in the delegate instance. It handles the + transaction lifecycle and possible exceptions such that neither the delegate + implementation nor the calling code needs to explicitly handle transactions. +

+

+ Can be used within a service implementation via direct instantiation with + a transaction manager reference, or get prepared in an application context + and given to services as object reference. +

+ + The transaction manager should always be configured as an object in the application + context, in the first case given to the service directly, in the second case to the + prepared template. + +

+ Supports setting the propagation behavior and the isolation level by name, + for convenient configuration in context definitions. +

+ + Juergen Hoeller + Mark Pollack (.NET) + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + +

+ Mainly targeted at configuration by an object factory. +

+ + The + + property must be set before any calls to the + + or + method. + + + + + + + Creates a new instance of the + class. + + +

+ Mainly targeted at configuration by an object factory. +

+ + + The transaction management strategy to be used. + + + + + Ensures that the + + has been set. + + + + + Executes the the action specified by the given delegate callback within a transaction. + + The delegate that specifies the transactional action. + + A result object returned by the callback, or null if one + + Allows for returning a result object created within the transaction, that is, + a domain object or a collection of domain objects. An exception thrown by the callback + is treated as a fatal exception that enforces a rollback. Such an exception gets + propagated to the caller of the template. + + + In case of initialization or system errors. + + + + + Executes the action specified by the given callback object within a transaction. + + The callback object that specifies the transactional action. + + A result object returned by the callback, or null if one + + Allows for returning a result object created within the transaction, that is, + a domain object or a collection of domain objects. An exception thrown by the callback + is treated as a fatal exception that enforces a rollback. Such an exception gets + propagated to the caller of the template. + + + In case of initialization or system errors. + + + + + Perform a rollback, handling rollback exceptions properly. + + The object representing the transaction. + The thrown application exception or error. + + + + Gets and sets the to + be used. + + + + + Exception thrown when a transaction can't be created using an + underlying transaction API such as COM+. + + Rod Johnson + Griffin Caprio (.NET) + + + + Base class for all transaction exceptions. + + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the TransactionException class. + + + + + Creates a new instance of the TransactionException class, with the specified message. + + + A message about the exception. + + + + + Creates a new instance of the TransactionException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the TransactionException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception that represents a transaction failure caused by heuristics. + + Rod Johnson + Juergen Hoeller + Griffin Caprio (.NET) + + + + The outcome state of the transaction: have some or all resources been committed? + + + + + Returns a representation of the supplied + . + + + The value that + is to be stringified. + + A representation. + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class + with the specified + and inner exception. + + + The + for the transaction. + + + The inner exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Override of + to allow for private serialization. + + + The + that holds the serialized object data about the exception. + + + The + that contains contextual information about the source or destination. + + + + + Returns the transaction's outcome state. + + + + + Exception thrown when the existence or non-existence of a transaction + amounts to an illegal state according to the transaction propagation + behavior that applies. + + Juergen Hoeller + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception that gets thrown when an invalid isolation level is specified, + i.e. an isolation level that the transaction manager implementation + doesn't support. + + Juergen Hoeller + Griffin Caprio (.NET) + + + + Superclass for exceptions caused by inappropriate usage of + a Spring.NET transaction API. + + Juergen Hoeller + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception that gets thrown when an invalid timeout is specified, + for example when the transaction manager implementation doesn't support timeouts. + + Juergen Hoeller + Griffin Caprio (.NET) + + + + Invalid timeout value. + + + + + Creates a new instance of the + class + with the specified message and timeout value. + + + A message about the exception. + + The (possibly invalid) timeout value. + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Override of + to allow for private serialization. + + + The + that holds the serialized object data about the exception. + + + The + that contains contextual information about the source or destination. + + + + + Returns the invalid timeout for this exception. + + + + + Exception thrown when attempting to work with a nested transaction + but nested transactions are not supported by the underlying backend. + + Juergen Hoeller + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception thrown when an operation is attempted that relies on an existing + transaction (such as setting rollback status) and there is no existing transaction. + This represents an illegal usage of the transaction API. + + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Represents a transaction's current state. + + Griffin Caprio (.NET) + + + + The transaction state is unknown. + + + + + The transaction has been committed. + + + + + The transaction has been rolled back. + + + + + The transaction is in an unknown, mixed state. + + + + + Enumeration describing Spring.NET's + transaction propagation settings. + + Griffin Caprio (.NET) + + + + Support a current transaction, create a new one if none exists. + + +

+ Analogous to System.EnterpriseServices.TransactionOption value of the same name. + This is typically the default setting of a transaction definition. +

+ + + + + Support a current transaction, execute non-transactionally if none exists. + + +

+ Analogous to System.EnterpriseServices.TransactionOption.Supported. +

+ + + + + Support a current transaction, throw an exception if none exists. + + +

+ No corresponding System.EnterpriseServices.TransactionOption value. +

+ + + + + Create a new transaction, suspending the current transaction if one exists. + + +

+ Analogous to System.EnterpriseServices.TransactionOption value of the same name. +

+ + + + + Execute non-transactionally, suspending the current transaction if one exists. + + +

+ Analogous to System.EnterpriseServices.TransactionOption value of the same name. +

+ + + + + Execute non-transactionally, throw an exception if a transaction exists. + + +

+ Analogous to System.EnterpriseServices.TransactionOption.Disabled. +

+ + + + + Execute within a nested transaction if a current transaction exists, else + behave like . + + +

+ There is no analogous feature in TransactionOption. +

+ + + + + Exception thrown when attempting to suspend an existing transaction + but transaction suspension is not supported by the underlying backend. + + Juergen Hoeller + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception thrown when a general transaction system error is encountered, + for instance on commit or rollback. + + Juergen Hoeller + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Exception to be thrown when a transaction has timed out. + + + + + Create a new instance + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Thrown when an attempt to commit a transaction resulted in an unexpected rollback. + + Rod Johnson + Griffin Caprio (.NET) + + + + Creates a new instance of the + class. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Creates a new instance of the + class. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the + class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Messaging.Ems.dll b/Resources/Libraries/Spring.NET/Spring.Messaging.Ems.dll new file mode 100644 index 00000000..a09e91cc Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Messaging.Ems.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Messaging.Ems.pdb b/Resources/Libraries/Spring.NET/Spring.Messaging.Ems.pdb new file mode 100644 index 00000000..5802b7aa Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Messaging.Ems.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Messaging.Ems.xml b/Resources/Libraries/Spring.NET/Spring.Messaging.Ems.xml new file mode 100644 index 00000000..3ea3a32d --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Messaging.Ems.xml @@ -0,0 +1,4922 @@ + + + + Spring.Messaging.Ems + + + + + A Connection object is a client's active connection to TIBCO EMS Server. + + + + + An interface containing all methods and properties on the TIBCO.EMS.Connection class. + Refer to the TIBCO EMS API documentation for more information. + + Mark Pollack + + + + Closes the connection and reclaims resources. + + + + + Creates the session. + + if set to true the session has transaction semantcis. + Indicates whether and how the consumer is to acknowledge received messages. + This version of CreateSession accepts an integer value associated with the acknowledge mode described by a Session member and should only be used for backward compatibility. + This parameter is ignored if the session is transacted. + A newly created session. + + + + Creates the session. + + if set to true [transacted]. + The acknowledge mode. + When true, the new session has transaction semantics. + Indicates whether and how the consumer is to acknowledge received messages. + Legal values are listed under SessionMode. + This parameter is ignored if the session is transacted. + + A newly created session. + + + + Starts (or restarts) a connection's delivery of incoming messages. + + + + + Temporarily stops a connection's delivery of incoming messages. + + + + + A String representation of the connection object + + + A that represents this instance. + + + + + Gets the native TIBCO EMS connection. + + The native connection. + + + + Occurs when the client library detects a problem with the connection. + + + + + Gets the URL of the server this connection is currently connected to + + The active URL. + + + + Gets or sets the client ID. + + The client ID. + + + + Gets the connection ID. + + The connection ID. + + + + Gets or sets the exception listener. + + The exception listener. + + + + Gets a value indicating whether the connection is closed. + + true if the connection is closed; otherwise, false. + + + + Gets a value indicating whether the connection communicates with a secure protocol + + true if the connection communicates with a secure protocol; otherwise, false. + + + + Gets the metadata for this connection + + The metadata for this connection. + + + + Initializes a new instance of the class. + + The underlying TIBCO EMS connection. + + + + Closes the connection and reclaims resources. + + + + + Creates the session. + + if set to true the session has transaction semantcis. + Indicates whether and how the consumer is to acknowledge received messages. + This version of CreateSession accepts an integer value associated with the acknowledge mode described by a Session member and should only be used for backward compatibility. + This parameter is ignored if the session is transacted. + A newly created session. + + + + Creates the session. + + if set to true [transacted]. + The acknowledge mode. + When true, the new session has transaction semantics. + Indicates whether and how the consumer is to acknowledge received messages. + Legal values are listed under SessionMode. + This parameter is ignored if the session is transacted. + A newly created session. + + + + Starts (or restarts) a connection's delivery of incoming messages. + + + + + Temporarily stops a connection's delivery of incoming messages. + + + + + Gets the native TIBCO EMS connection. + + The native connection. + + + + Occurs when the client library detects a problem with the connection. + + + + + Gets the URL of the server this connection is currently connected to + + The active URL. + + + + Gets or sets the client ID. + + The client ID. + + + + Gets the connection ID. + + The connection ID. + + + + Gets or sets the exception listener. + + The exception listener. + + + + Gets a value indicating whether the connection is closed. + + + true if the connection is closed; otherwise, false. + + + + + Gets a value indicating whether the connection communicates with a secure protocol + + + true if the connection communicates with a secure protocol; otherwise, false. + + + + + Gets the metadata for this connection + + The metadata for this connection. + + + + An interface containing all methods and properties on the TIBCO.EMS.ConnectionFactory class. + Refer to the TIBCO EMS API documentation for more information. + + + All the 'GetXXX()' methods in the TIBCO.EMS.ConnectionFactory were translated to .NET properties + + Mark Pollack + + + + Creates the connection. + + The newly created connection + + + + Creates the connection with the given username and password + + Name of the user. + The password. + + + + + Gets the native TIBCO EMS connection factory. + + The native connection factory. + + + + Gets the certificate store info object associated with this connection factory. + + The certificate store. + + + + Gets or sets the SSL proxy host. + + The SSL proxy host. + + + + Gets or sets the SSL proxy port. + + The SSL proxy port. + + + + Gets the SSL proxy password. + + The SSL proxy password. + + + + Gets the SSL proxy user. + + The SSL proxy user. + + + + Sets the type of the certificate store. + + The type of the certificate store. + + + + Sets the client ID. + + The client ID. + + + + Sets the client tracer to a given output stream + + The client tracer. + + + + Sets the number of connection attempts + + The number of connection attempts. + + + + Sets delay between connection attempts + + The delay between connection attempts. + + + + Sets the connection attempt timeout. + + The connection attempt timeout. + + + + Sets the custom host name verifier. Set to null to remove custom host name verifier. + + The host name verifier. + + + + Sets the load balance metric as an integer. + + The load balance metric as int. + + + + Sets the port on which the client will connect to the multicast daemon. + + The multicast daemon port. + + + + Sets whether MessageConsumers subscribed to a multicast-enabled topic will receive messages over multicast. + + true to enable multicast; false to disable. + + + + Gets or sets the the default length of time in milliseconds from its dispatch time + that a produced message should be retained by the message system. + + Time to live is set to zero by default. + The message time to live in milliseconds; zero is unlimited + + + + Market interface for EMS SSL store types + + + + + Namespace parser for the EMS namespace. + + Mark Fisher + Juergen Hoeller + Mark Pollack (.NET) + + + + Register a MessageListenerContainer for the 'listener-container' tag. + + + + + Parser for the EMS <listener-container> element. + + Mark Fisher + Juergen Hoeller + Mark Pollack (.NET) + + + + Parse the specified XmlElement and register the resulting + ObjectDefinitions with the IObjectDefinitionRegistry + embedded in the supplied + + The element to be parsed. + TThe object encapsulating the current state of the parsing process. + Provides access to a IObjectDefinitionRegistry + The primary object definition. + +

+ This method is never invoked if the parser is namespace aware + and was called to process the root node. +

+ + + + + EMS MessageConsumer decorator that adapts all calls + to a shared MessageConsumer instance underneath. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + The target. + + + + Receives the next message produced for this message consumer. + + the next message produced for this message consumer, , or null if this message consumer is concurrently closed + + + + Receives the next message that arrives within the specified timeout interval. + + The timeout value. + the next message produced for this message consumer, or null if the timeout expires or this message consumer is concurrently closed + + + + Receives the next message if one is immediately available. + + the next message produced for this message consumer, or null if one is not available + + + + No-op implementation since it is caching. + + + + + Description that shows this is a cached MessageConsumer + + Description that shows this is a cached MessageConsumer + + + + Gets the target MessageConsumer, the consumer we are 'wrapping' + + The target MessageConsumer. + + + + Occurs when a message is received. + + + + + MessageProducer decorator that adapts calls to a shared MessageProducer + instance underneath, managing QoS settings locally within the decorator. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + The target. + + + + Sends the specified message. + + The message. + + + + Sends the specified message. + + The message. + The delivery mode. + The priority. + The time to live. + + + + Sends a message to the specified destination. + + The destination. + The message. + + + + Reset properties. + + + + + Returns string indicated this is a wrapped MessageProducer + + + + + + Gets or sets a value indicating whether disable setting of the message ID property. + + true if disable message ID setting; otherwise, false. + + + + Gets or sets a value indicating whether disable setting the message timestamp property. + + + true if disable message timestamp; otherwise, false. + + + + + Gets or sets the producer's default delivery mode. + + The message delivery mode for this message producer + + + + Gets or sets the MSG delivery mode. + + The MSG delivery mode. + + + + Gets or sets the priority of messages sent with this producer. + + The priority. + + + + Gets or sets the the default length of time in milliseconds from its dispatch time + that a produced message should be retained by the message system. + + Time to live is set to zero by default. + The message time to live in milliseconds; zero is unlimited + + + + Gets the target MessageProducer, the producer we are 'wrapping' + + The target MessageProducer. + + + + Wrapper for Session that caches producers and registers itself as available + to the session cache when being closed. Generally used for testing purposes or + if need to get at the wrapped Session object via the TargetSession property (for + vendor specific methods). + + Juergen Hoeller + Mark Pollack + + + + Subinterface of Session to be implemented by + implementations that wrap an Session to provide added + functionality. Allows access to the the underlying target Session. + + Mark Pollack + + + + + + Gets the target session of the decorator. + This will typically be the native provider Session or a wrapper from a session pool. + + The underlying session, never null + + + + Initializes a new instance of the class. + + The target session. + The session list. + The CachingConnectionFactory. + + + + Creates the producer, potentially returning a cached instance. + + The destination. + A message producer. + + + + If have not yet reached session cache size, cache the session, otherwise + dispose of all cached message producers and close the session. + + + + + Creates the consumer, potentially returning a cached instance. + + The destination. + A message consumer + + + + Creates the consumer, potentially returning a cached instance. + + The destination. + The selector. + A message consumer + + + + Creates the consumer, potentially returning a cached instance. + + The destination. + The selector. + if set to true [no local]. + A message consumer. + + + + Creates the durable consumer, potentially returning a cached instance. + + The destination. + The name of the durable subscription. + The selector. + if set to true [no local]. + A message consumer + + + + Creates the durable consumer, potentially returning a cached instance. + + The destination. + The name of the durable subscription. + A message consumer + + + + Creates the consumer. + + The destination. + The selector. + if set to true [no local]. + The subscription. + + + + + Gets the queue. + + The name. + + + + + Gets the topic. + + The name. + + + + + Creates the temporary queue. + + + + + + Creates the temporary topic. + + + + + + Creates the message. + + + + + + Creates the text message. + + + + + + Creates the text message. + + The text. + + + + + Creates the map message. + + + + + + Creates the bytes message. + + + + + + Creates the object message. + + + + + + Creates the object message. + + The body. + + + + + Creates the stream message. + + + + + + Commits this instance. + + + + + Rollbacks this instance. + + + + + Returns a that represents the current . + + + A that represents the current . + + + + + Gets the target, for testing purposes. + + The target. + + + + Gets a value indicating whether this is transacted. + + true if transacted; otherwise, false. + + + + Gets the acknowledgement mode. + + The acknowledgement mode. + + + + subclass that adds + Session, MessageProducer, and MessageConsumer caching. This ConnectionFactory + also switches the ReconnectOnException property to true + by default, allowing for automatic recovery of the underlying + Connection. + + + By default, only one single Session will be cached, with further requested + Sessions being created and disposed on demand. Consider raising the + SessionCacheSize property in case of a high-concurrency environment. + + NOTE: This ConnectionFactory requires explicit closing of all Sessions + obtained from its shared Connection. This is the usual recommendation for + native EMS access code anyway. However, with this ConnectionFactory, its use + is mandatory in order to actually allow for Session reuse. + + + Note also that MessageConsumers obtained from a cached Session won't get + closed until the Session will eventually be removed from the pool. This may + lead to semantic side effects in some cases. For a durable subscriber, the + logical Session.Close() call will also close the subscription. + Re-registering a durable consumer for the same subscription on the same + Session handle is not supported; close and reobtain a cached Session first. + + + + Juergen Hoeller + Mark Pollack (.NET) + + + + A ConnectionFactory adapter that returns the same Connection + from all CreateConnection() calls, and ignores calls to + Connection.Close(). According to the JMS Connection + model, this is perfectly thread-safe. The + shared Connection can be automatically recovered in case of an Exception. + + + + You can either pass in a specific Connection directly or let this + factory lazily create a Connection via a given target ConnectionFactory. + + + Useful for testing and in applications when you want to keep using the + same Connection for multiple + calls, without having a pooling ConnectionFactory underneath. This may span + any number of transactions, even concurrently executing transactions. + + + Note that Spring's message listener containers support the use of + a shared Connection within each listener container instance. Using + SingleConnectionFactory with a MessageListenerContainer only really makes sense for + sharing a single Connection across multiple listener containers. + + + Juergen Hoeller + Mark Pollack + Mark Pollack (.NET) + + + + Wrapped Connection + + + + + Proxy Connection + + + + + Whether the shared Connection has been started + + + + + Synchronization monitor for the shared Connection + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class + that alwasy returns the given Connection. + + The single Connection. + + + + Initializes a new instance of the class + that alwasy returns a single Connection. + + The target connection factory. + + + + Creates the connection. + + A single shared connection + + + + Creates the connection. + + Name of the user. + The password. + + + + + Initialize the underlying shared Connection. Closes and reinitializes the Connection if an underlying + Connection is present already. + + + + + Exception listener callback that renews the underlying single Connection. + + The exception from the messaging infrastructure. + + + + Prepares the connection before it is exposed. + The default implementation applies ExceptionListener and client id. + Can be overridden in subclasses. + + The Connection to prepare. + if thrown by any EMS API methods. + + + + Template method for obtaining a (potentially cached) Session. + + The connection to operate on. + The session ack mode. + the Session to use, or null to indicate + creation of a raw standard Session + + + + reate a JMS Connection via this template's ConnectionFactory. + + + + + + Closes the given connection. + + The connection. + + + + Ensure that the connection or TargetConnectionFactory are specified. + + + + + Close the underlying shared connection. The provider of this ConnectionFactory needs to care for proper shutdown. + As this object implements an application context will automatically + invoke this on distruction o + + + + + Resets the underlying shared Connection, to be reinitialized on next access. + + + + + Wrap the given Connection with a proxy that delegates every method call to it + but suppresses close calls. This is useful for allowing application code to + handle a special framework Connection just like an ordinary Connection from a + ConnectionFactory. + + The original connection to wrap. + the wrapped connection + + + + Gets or sets the target connection factory which will be used to create a single + connection. + + The target connection factory. + + + + Sets the exception listener. + + The exception listener. + + + + Gets or sets a value indicating whether the single Connection + should be reset (to be subsequently renewed) when a EMSException + is reported by the underlying Connection. + + + Default is false. Switch this to true + to automatically trigger recover based on your messaging provider's + exception notifications. + + Internally, this will lead to a special ExceptionListener (this + SingleConnectionFactory itself) being registered with the underlying + Connection. This can also be combined with a user-specified + ExceptionListener, if desired. + + + + true attempt to reconnect on exception during next access; otherwise, false. + + + + + Gets the connection monitor. + + The connection monitor. + + + + Gets a value indicating whether this instance is started. + + + true if this instance is started; otherwise, false. + + + + + Gets the client id. + + The client id. + + + + Initializes a new instance of the class. + and sets the ReconnectOnException to true + + + + + Initializes a new instance of the class for the given + IConnectionFactory + + The target connection factory. + + + + Resets the Session cache as well as resetting the connection. + + + + + Obtaining a cached Session. + + The connection to operate on. + The session ack mode. + The Session to use + + + + + Wraps the given Session so that it delegates every method call to the target session but + adapts close calls. This is useful for allowing application code to + handle a special framework Session just like an ordinary Session. + + The original Session to wrap. + The List of cached Sessions that the given Session belongs to. + The wrapped Session + + + + Gets or sets the size of the session cache. + + + This cache size is the maximum limit for the number of cached Sessions + per session acknowledgement type (auto, client, dups_ok, transacted). + As a consequence, the actual number of cached Sessions may be up to + four times as high as the specified value - in the unlikely case + of mixing and matching different acknowledgement types. + + Default is 1: caching a single Session, (re-)creating further ones on + demand. Specify a number like 10 if you'd like to raise the number of cached + Sessions; that said, 1 may be sufficient for low-concurrency scenarios. + + + The size of the session cache. + + + + Gets or sets a value indicating whether to cache MessageProducers per + Session instance. (more specifically: one MessageProducer per Destination + and Session). + + + Default is "true". Switch this to "false" in order to always, + recreate MessageProducers on demand. + + + true if should cache message producers; otherwise, false. + + + + Gets or sets a value indicating whether o cache JMS MessageConsumers per + EMS Session instance. + + + Mmore specifically: one MessageConsumer per Destination, selector String + and Session. Note that durable subscribers will only be cached until + logical closing of the Session handle. + + Default is "true". Switch this to "false" in order to always + recreate MessageConsumers on demand. + + + true to cache consumers per session instance; otherwise, false. + + + + Gets or sets a value indicating whether this instance is active. + + true if this instance is active; otherwise, false. + + + + Implementation of Spring IExceptionListener interface that supports + chaining allowing the addition of multiple ExceptionListener instances in order. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Adds the exception listener to the chain + + The listener. + + + + Called when an exception occurs in message processing. + + The exception. + + + + Gets the exception listeners as an array. + + The exception listeners. + + + Helper class for obtaining transactional EMS resources + for a given ConnectionFactory. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Releases the given connection, stopping it (if necessary) and eventually closing it. + + Checks , if available. + This is essentially a more sophisticated version of + + + The connection to release. (if this is null, the call will be ignored) + The ConnectionFactory that the Connection was obtained from. (may be null) + whether the Connection might have been started by the application. + + + + Return the innermost target Session of the given Session. If the given + Session is a decorated session, it will be unwrapped until a non-decorated + Session is found. Otherwise, the passed-in Session will be returned as-is. + + The session to unwrap + The innermost target Session, or the passed-in one if no decorator + + + + Determines whether the given JMS Session is transactional, that is, + bound to the current thread by Spring's transaction facilities. + + The session to check. + The ConnectionFactory that the Session originated from + + true if is session transactional, bound to current thread; otherwise, false. + + + + Obtain a EMS Session that is synchronized with the current transaction, if any. + the ConnectionFactory to obtain a Session for + + the existing EMS Connection to obtain a Session for + (may be null) + + whether to allow for a local EMS transaction + that is synchronized with a Spring-managed transaction (where the main transaction + might be a ADO.NET-based one for a specific DataSource, for example), with the EMS + transaction committing right after the main transaction. If not allowed, the given + ConnectionFactory needs to handle transaction enlistment underneath the covers. + + the transactional Session, or null if none found + + EMSException in case of EMS failure + + + + Obtain a EMS Session that is synchronized with the current transaction, if any. + + the TransactionSynchronizationManager key to bind to + (usually the ConnectionFactory) + the ResourceFactory to use for extracting or creating + EMS resources + whether the underlying Connection approach should be + started in order to allow for receiving messages. Note that a reused Connection + may already have been started before, even if this flag is false. + + the transactional Session, or null if none found + + EMSException in case of EMS failure + + + Callback interface for resource creation. + Serving as argument for the DoGetTransactionalSession method. + + + + Fetch an appropriate Session from the given EmsResourceHolder. + the EmsResourceHolder + + an appropriate Session fetched from the holder, + or null if none found + + + + Fetch an appropriate Connection from the given EmsResourceHolder. + the EmsResourceHolder + + an appropriate Connection fetched from the holder, + or null if none found + + + + Create a new EMS Connection for registration with a EmsResourceHolder. + the new EMS Connection + + EMSException if thrown by EMS API methods + + + Create a new EMS Session for registration with a EmsResourceHolder. + the EMS Connection to create a Session for + + the new EMS Session + + EMSException if thrown by EMS API methods + + + + Return whether to allow for a local EMS transaction that is synchronized with + a Spring-managed transaction (where the main transaction might be a ADO.NET-based + one for a specific IDbProvider, for example), with the EMS transaction + committing right after the main transaction. + Returns whether to allow for synchronizing a local EMS transaction + + + + + Callback for resource cleanup at the end of a non-native EMS transaction + + + + Connection holder, wrapping a EMS Connection and a EMS Session. + EmsTransactionManager binds instances of this class to the thread, + for a given EMS ConnectionFactory. + +

Note: This is an SPI class, not intended to be used by applications.

+ + + Juergen Hoeller + Mark Pollack (.NET) + + + Create a new EmsResourceHolder that is open for resources to be added. + + + + Initializes a new instance of the class + at is open for resources to be added. + + The connection factory that this + resource holder is associated with (may be null) + + + + + Initializes a new instance of the class for the + given Session. + + The session. + + + Create a new EmsResourceHolder for the given EMS resources. + the EMS Connection + + the EMS Session + + + + + Initializes a new instance of the class. + + The connection factory. + The connection. + The session. + + + + Adds the connection to the list of resources managed by this holder. + + The connection. + + + + Adds the session to the list of resources managed by this holder. + + The session. + + + + Adds the session and connection to the list of resources managed by this holder. + + The session. + The connection. + + + + Gets the connection managed by this resource holder + + A Connection, or null if no managed connection. + + + + Gets the connection of a given type managed by this resource holder. This is used + when storing Queue or Topic Connections (from the older 1.0.2 API) as compared to the + 'unified domain' API , just Connection, in the newer 1.2 API. + + Type of the connection. + The connection, or null if not found. + + + + Gets the first session manged by this holder or null if not available. + + The session or null if not available. + + + + Gets the session managed by this holder by type. + + Type of the session. + The session or null if not available. + + + + Gets the session of a given type associated with the given connection + + Type of the session. + The connection. + The sessin or null if not available. + + + + Commits all sessions. + + + + + Closes all sessions then stops and closes all connections, in that order. + + + + + Determines whether the holder contains the specified session. + + The session. + + true if the holder contains the specified session; otherwise, false. + + + + + Gets a value indicating whether this is frozen, namely that + additional resources can be registered with the holder. If using any of the constructors with + a Session, the holder will be set to the frozen state. + + true if frozen; otherwise, false. + + + + A implementation + for a single EMS ConnectionFactory. Binds a + Connection/Session pair from the specified ConnecctionFactory to the thread, + potentially allowing for one thread-bound Session per ConnectionFactory. + + + + Application code is required to retrieve the transactional Session via + . Spring's + will autodetect a thread-bound Session and + automatically participate in it. + + + Transaction synchronization is turned off by default, as this manager might be used + alongside an IDbProvider based Spring transaction manager such as the + AdoPlatformTransactionManager, which has stronger needs for synchronization. + + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + The ConnectionFactory has to be set before using the instance. + This constructor can be used to prepare a EmsTemplate via a ApplicationContext, + typically setting the ConnectionFactory via ConnectionFactory property. + + Turns off transaction synchronization by default, as this manager might + be used alongside a dbprovider-based Spring transaction manager like + AdoPlatformTransactionManager, which has stronger needs for synchronization. + Only one manager is allowed to drive synchronization at any point of time. + + + + + + Initializes a new instance of the class + given a ConnectionFactory. + + The connection factory to obtain connections from. + + + + Make sure the ConnectionFactory has been set. + + + + + Get the EmsTransactionObject. + + he EmsTransactionObject. + + + + Begin a new transaction with the given transaction definition. + + Transaction object returned by + . + instance, describing + propagation behavior, isolation level, timeout etc. + + Does not have to care about applying the propagation behavior, + as this has already been handled by this abstract manager. + + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + Transaction object returned by + . + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + Transaction synchronization will already have been suspended. + + + in case of system errors. + + + + + Resume the resources of the current transaction. + + Transaction object returned by + . + The object that holds suspended resources as returned by + . + Transaction synchronization will be resumed afterwards. + + + In the case of system errors. + + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + + In the case of system errors. + + + + + Perform an actual rollback on the given transaction. + + The status representation of the transaction. + + In the case of system errors. + + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + The status representation of the transaction. + + In the case of system errors. + + + + + Cleanup resources after transaction completion. + + Transaction object returned by + . + + + Called after + and + + execution on any outcome. + + + + + + Check if the given transaction object indicates an existing transaction + (that is, a transaction which has already started). + + Transaction object returned by + . + + True if there is an existing transaction. + + + In the case of system errors. + + + + + Creates the connection via thie manager's ConnectionFactory. + + The new Connection + If thrown by underlying messaging APIs + + + + Creates the session for the given Connection + + The connection to create a Session for. + the new Session + If thrown by underlying messaging APIs + + + + Gets or sets the connection factory that this instance should manage transaction. + for. + + The connection factory. + + + + Gets the resource factory that this transaction manager operates on, + In tihs case the ConnectionFactory + + The ConnectionFactory. + + + + EMS Transaction object, representing a EmsResourceHolder. + Used as transaction object by EMSTransactionManager + + + + + Extension of the IConnectionFactory interface, + indicating how to release Connections obtained from it. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Shoulds we stop the connection, obtained from this ConnectionFactory? + + The connection to check. + wheter a stop call is necessary + + + + Internal chained ExceptionListener for handling the internal recovery listener + in combination with a user-specified listener. + + + + + Add information to show this is a shared EMS connection + + Description of connection wrapper + + + Exception thrown when a synchronized local transaction failed to complete + (after the main transaction has already completed). + + Jergen Hoeller + Mark Pollack (.NET) + + + + Creates a new instance of the SynchedLocalTransactionFailedException class. with the specified message. + + + A message about the exception. + + + + + Creates a new instance of the SynchedLocalTransactionFailedException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Delegate callback for browsing the messages in an EMS queue. + + + + + Convenient super class for application classes that need EMS access. + + + Requires a ConnectionFactory or a EmsTemplate instance to be set. + It will create its own EmsTemplate if a ConnectionFactory is passed in. + A custom EmsTemplate instance can be created for a given ConnectionFactory + through overriding the createEmsTemplate method. + + + + + + Creates a EmsTemplate for the given ConnectionFactory. + + Only invoked if populating the gateway with a ConnectionFactory reference. + Can be overridden in subclasses to provide a different EmsTemplate instance + + + The connection factory. + + + + + Ensures that the JmsTemplate is specified and calls . + + + + + Subclasses can override this for custom initialization behavior. + Gets called after population of this instance's properties. + + + + + Gets or sets the EMS template for the gateway. + + The EMS template. + + + + Gets or sets he EMS connection factory to be used by the gateway. + Will automatically create a EmsTemplate for the given ConnectionFactory. + + The connection factory. + + + Helper class that simplifies EMS access code. + + If you want to use dynamic destination creation, you must specify + the type of EMS destination to create, using the "pubSubDomain" property. + For other operations, this is not necessary. + Point-to-Point (Queues) is the default domain. + + Default settings for EMS Sessions is "auto-acknowledge". + + This template uses a DynamicDestinationResolver and a SimpleMessageConverter + as default strategies for resolving a destination name or converting a message, + respectively. + + + Mark Pollack + Juergen Hoeller + Mark Pollack (.NET) + + + Base class for EmsTemplate} and other + EMS-accessing gateway helpers, adding destination-related properties to + EmsAccessor's common properties. + + +

Not intended to be used directly. See EmsTemplate.

+ + + Juergen Hoeller + Mark Pollack (.NET) + + + Base class for EmsTemplate and other EMS-accessing gateway helpers + It defines common properties like the ConnectionFactory}. The subclass + EmsDestinationAccessor adds further, destination-related properties. + + Not intended to be used directly. See EmsTemplate. + + + Juergen Hoeller + Mark Pollack (.NET) + + + + Verify that ConnectionFactory property has been set. + + + + + Creates the connection via the ConnectionFactory. + + + + + + Creates the session for the given Connection + + The connection to create a session for. + The new session + + + + Returns whether the Session is in client acknowledgement mode. + + The session to check. + true if in client ack mode, false otherwise + + + + Gets or sets the connection factory to use for obtaining EMS Connections. + + The connection factory. + + + + Gets or sets the session acknowledge mode for EMS Sessions including whether or not the session is transacted + + + Set the EMS acknowledgement mode that is used when creating a EMS + Session to send a message. The default is AUTO_ACKNOWLEDGE. + + The session acknowledge mode. + + + + Set the transaction mode that is used when creating a EMS Session. + Default is "false". + + + Setting this flag to "true" will use a short local EMS transaction + when running outside of a managed transaction, and a synchronized local + EMS transaction in case of a managed transaction being present. + The latter has the effect of a local EMS + transaction being managed alongside the main transaction (which might + be a native ADO.NET transaction), with the EMS transaction committing + right after the main transaction. + + + + + + Resolves the given destination name to a EMS destination. + + The current session. + Name of the destination. + The located Destination + If resolution failed. + + + + Gets or sets the destination resolver that is to be used to resolve + Destination references for this accessor. + + The default resolver is a DynamicDestinationResolver. Specify a + JndDestinationResolver for resolving destination names as JNDI locations. + + The destination resolver. + + + + Gets or sets a value indicating whether Publish/Subscribe + domain (Topics) is used. Otherwise, the Point-to-Point domain + (Queues) is used. + + + this + setting tells what type of destination to create if dynamic destinations are enabled. + true if Publish/Subscribe domain; otherwise, false + for the Point-to-Point domain. + + + Specifies a basic set of EMS operations. + + +

Implemented by EmsTemplate. Not often used but a useful option + to enhance testability, as it can easily be mocked or stubbed.

+ +

Provides EmsTemplate's send(..) and + receive(..) methods that mirror various EMS API methods. + See the EMS specification and EMS API docs for details on those methods. +

+ + Mark Pollack + Juergen Hoeller + Mark Pollack (.NET) + + + Execute the action specified by the given action object within + a EMS Session. + + delegate that exposes the session + the result object from working with the session + + If there is any problem accessing the EMS API + + + Execute the action specified by the given action object within + a EMS Session. + + callback object that exposes the session + + the result object from working with the session + + If there is any problem accessing the EMS API + + + Send a message to a EMS destination. The callback gives access to + the EMS session and MessageProducer in order to do more complex + send operations. + + callback object that exposes the session/producer pair + + the result object from working with the session + + EMSException if there is any problem + + + Send a message to a EMS destination. The callback gives access to + the EMS session and MessageProducer in order to do more complex + send operations. + + delegate that exposes the session/producer pair + + the result object from working with the session + + If there is any problem accessing the EMS API + + + Send a message to the default destination. +

This will only work with a default destination specified!

+ + callback to create a message + + If there is any problem accessing the EMS API + + + Send a message to the specified destination. + The IMessageCreator callback creates the message given a Session. + + the destination to send this message to + + callback to create a message + + If there is any problem accessing the EMS API + + + Send a message to the specified destination. + The IMessageCreator callback creates the message given a Session. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + callback to create a message + + If there is any problem accessing the EMS API + + + Send a message to the default destination. +

This will only work with a default destination specified!

+ + delegate callback to create a message + + If there is any problem accessing the EMS API + + + Send a message to the specified destination. + The IMessageCreator callback creates the message given a Session. + + the destination to send this message to + + delegate callback to create a message + + If there is any problem accessing the EMS API + + + Send a message to the specified destination. + The IMessageCreator callback creates the message given a Session. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + delegate callback to create a message + + If there is any problem accessing the EMS API + + + Send the given object to the default destination, converting the object + to a EMS message with a configured IMessageConverter. +

This will only work with a default destination specified!

+ + the object to convert to a message + + If there is any problem accessing the EMS API + + + Send the given object to the specified destination, converting the object + to a EMS message with a configured IMessageConverter. + + the destination to send this message to + + the object to convert to a message + + If there is any problem accessing the EMS API + + + Send the given object to the specified destination, converting the object + to a EMS message with a configured IMessageConverter. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the object to convert to a message + + If there is any problem accessing the EMS API + + + Send the given object to the default destination, converting the object + to a EMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. +

This will only work with a default destination specified!

+ + the object to convert to a message + + the callback to modify the message + + If there is any problem accessing the EMS API + + + Send the given object to the specified destination, converting the object + to a EMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the destination to send this message to + + the object to convert to a message + + the callback to modify the message + + If there is any problem accessing the EMS API + + + Send the given object to the specified destination, converting the object + to a EMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the object to convert to a message. + + the callback to modify the message + + If there is any problem accessing the EMS API + + + + Send the given object to the default destination, converting the object + to a EMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. +

This will only work with a default destination specified!

+ + the object to convert to a message + the callback to modify the message + If there is any problem accessing the EMS API + + + + Send the given object to the specified destination, converting the object + to a EMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the destination to send this message to + the object to convert to a message + the callback to modify the message + If there is any problem accessing the EMS API + + + + Send the given object to the specified destination, converting the object + to a EMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + the object to convert to a message. + the callback to modify the message + If there is any problem accessing the EMS API + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the message received by the consumer, or null if the timeout expires + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the message received by the consumer, or null if the timeout expires + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the message received by the consumer, or null if the timeout expires + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the EMS message selector expression (or null if none). + See the EMS specification for a detailed definition of selector expressions. + + the message received by the consumer, or null if the timeout expires + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the EMS message selector expression (or null if none). + See the EMS specification for a detailed definition of selector expressions. + + the message received by the consumer, or null if the timeout expires + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the EMS message selector expression (or null if none). + See the EMS specification for a detailed definition of selector expressions. + + the message received by the consumer, or null if the timeout expires + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the message produced for the consumer or null if the timeout expires. + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the message produced for the consumer or null if the timeout expires. + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the message produced for the consumer or null if the timeout expires. + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the EMS message selector expression (or null if none). + See the EMS specification for a detailed definition of selector expressions. + + the message produced for the consumer or null if the timeout expires. + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the EMS message selector expression (or null if none). + See the EMS specification for a detailed definition of selector expressions. + + the message produced for the consumer or null if the timeout expires. + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the EMS message selector expression (or null if none). + See the EMS specification for a detailed definition of selector expressions. + + the message produced for the consumer or null if the timeout expires. + + If there is any problem accessing the EMS API + + + + Browses messages in the default EMS queue. The callback gives access to the EMS + Session and QueueBrowser in order to browse the queue and react to the contents. + + The action callback object that exposes the session/browser pair. + the result object from working with the session + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + The queue to browse. + The action callback object that exposes the session/browser pair. + the result object from working with the session + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + Name of the queue to browse, + (to be resolved to an actual destination by a DestinationResolver) + The action callback object that exposes the session/browser pair. + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + The EMS message selector expression (or null if none). + The action callback object that exposes the session/browser pair. + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + The queue to browse. + The EMS message selector expression (or null if none). + The action callback object that exposes the session/browser pair. + + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + Name of the queue to browse, + (to be resolved to an actual destination by a DestinationResolver) + The EMS message selector expression (or null if none). + The action callback object that exposes the session/browser pair. + + If there is any problem accessing the EMS API + + + + Browses messages in the default EMS queue. The callback gives access to the EMS + Session and QueueBrowser in order to browse the queue and react to the contents. + + The action callback delegate that exposes the session/browser pair. + the result object from working with the session + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + The queue to browse. + The action callback delegate that exposes the session/browser pair. + the result object from working with the session + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + Name of the queue to browse, + (to be resolved to an actual destination by a DestinationResolver) + The action callback delegate that exposes the session/browser pair. + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + The EMS message selector expression (or null if none). + The action callback delegate that exposes the session/browser pair. + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + The queue to browse. + The EMS message selector expression (or null if none). + The action callback delegate that exposes the session/browser pair. + + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + Name of the queue to browse, + (to be resolved to an actual destination by a DestinationResolver) + The EMS message selector expression (or null if none). + The action callback delegate that exposes the session/browser pair. + + If there is any problem accessing the EMS API + + + + Timeout value indicating that a receive operation should + check if a message is immediately available without blocking. + + + + Create a new EmsTemplate. + + Note: The ConnectionFactory has to be set before using the instance. + This constructor can be used to prepare a EmsTemplate via an ObjectFactory, + typically setting the ConnectionFactory. + + + + Create a new EmsTemplate, given a ConnectionFactory. + the ConnectionFactory to obtain Connections from + + + + Initialize the default implementations for the template's strategies: + DynamicDestinationResolver and SimpleMessageConverter. + + + + Execute the action specified by the given action object within a + EMS Session. + + Generalized version of execute(SessionCallback), + allowing the EMS Connection to be started on the fly. +

Use execute(SessionCallback) for the general case. + Starting the EMS Connection is just necessary for receiving messages, + which is preferably achieved through the receive methods.

+ + callback object that exposes the session + + Start the connection before performing callback action. + + the result object from working with the session + + If there is any problem accessing the EMS API + + + Execute the action specified by the given action object within a + EMS Session. + + Generalized version of execute(SessionCallback), + allowing the EMS Connection to be started on the fly. +

Use execute(SessionCallback) for the general case. + Starting the EMS Connection is just necessary for receiving messages, + which is preferably achieved through the receive methods.

+ + callback object that exposes the session + + Start the connection before performing callback action. + + the result object from working with the session + + If there is any problem accessing the EMS API + + + + Extract the content from the given JMS message. + + The Message to convert (can be null). + The content of the message, or null if none + + + Fetch an appropriate Connection from the given EmsResourceHolder. + + the EmsResourceHolder + + an appropriate Connection fetched from the holder, + or null if none found + + + + Fetch an appropriate Session from the given EmsResourceHolder. + + the EmsResourceHolder + + an appropriate Session fetched from the holder, + or null if none found + + + + Create a EMS MessageProducer for the given Session and Destination, + configuring it to disable message ids and/or timestamps (if necessary). +

Delegates to doCreateProducer for creation of the raw + EMS MessageProducer

+ + the EMS Session to create a MessageProducer for + + the EMS Destination to create a MessageProducer for + + the new EMS MessageProducer + + If there is any problem accessing the EMS API + + + + + + + + + + Determines whether the given Session is locally transacted, that is, whether + its transaction is managed by this template class's Session handling + and not by an external transaction coordinator. + + + The Session's own transacted flag will already have been checked + before. This method is about finding out whether the Session's transaction + is local or externally coordinated. + + The session to check. + + true if the session is locally transacted; otherwise, false. + + + + Create a raw EMS MessageProducer for the given Session and Destination. + + If CacheJmsResource is true, then the producer + will be created upon the first invocation and will retrun the same + producer (per destination) on all subsequent calls. + + the EMS Session to create a MessageProducer for + + the EMS Destination to create a MessageProducer for + + the new EMS MessageProducer + + If there is any problem accessing the EMS API + + + Create a EMS MessageConsumer for the given Session and Destination. + + the EMS Session to create a MessageConsumer for + + the EMS Destination to create a MessageConsumer for + + the message selector for this consumer (can be null) + + the new EMS MessageConsumer + + If there is any problem accessing the EMS API + + + + Send the given message. + + The session to operate on. + The destination to send to. + The message creator delegate callback to create a Message. + + + + Send the given message. + + The session to operate on. + The destination to send to. + The message creator callback to create a Message. + + + Send the given EMS message. + the EMS Session to operate on + + the EMS Destination to send to + + callback to create a EMS Message + + delegate callback to create a EMS Message + + If there is any problem accessing the EMS API + + + Actually send the given EMS message. + the EMS MessageProducer to send with + + the EMS Message to send + + If there is any problem accessing the EMS API + + + + Execute the action specified by the given action object within + a EMS Session. + + delegate that exposes the session + + the result object from working with the session + + + Note that the value of PubSubDomain affects the behavior of this method. + If PubSubDomain equals true, then a Session is passed to the callback. + If false, then a Session is passed to the callback.b + + If there is any problem accessing the EMS API + + + Execute the action specified by the given action object within + a EMS Session. +

Note: The value of PubSubDomain affects the behavior of this method. + If PubSubDomain equals true, then a Session is passed to the callback. + If false, then a Session is passed to the callback.

+ + callback object that exposes the session + + the result object from working with the session + + If there is any problem accessing the EMS API + + + Send a message to a EMS destination. The callback gives access to + the EMS session and MessageProducer in order to do more complex + send operations. + + callback object that exposes the session/producer pair + + the result object from working with the session + + If there is any problem accessing the EMS API + + + Send a message to a EMS destination. The callback gives access to + the EMS session and MessageProducer in order to do more complex + send operations. + + delegate that exposes the session/producer pair + + the result object from working with the session + + If there is any problem accessing the EMS API + + + Send a message to the default destination. +

This will only work with a default destination specified!

+ + delegate callback to create a message + + If there is any problem accessing the EMS API + + + Send a message to the specified destination. + The MessageCreator callback creates the message given a Session. + + the destination to send this message to + + delegate callback to create a message + + If there is any problem accessing the EMS API + + + Send a message to the specified destination. + The MessageCreator callback creates the message given a Session. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + delegate callback to create a message + + If there is any problem accessing the EMS API + + + Send a message to the default destination. +

This will only work with a default destination specified!

+ + callback to create a message + + If there is any problem accessing the EMS API + + + Send a message to the specified destination. + The MessageCreator callback creates the message given a Session. + + the destination to send this message to + + callback to create a message + + If there is any problem accessing the EMS API + + + Send a message to the specified destination. + The MessageCreator callback creates the message given a Session. + + the destination to send this message to + + callback to create a message + + If there is any problem accessing the EMS API + + + Send the given object to the default destination, converting the object + to a EMS message with a configured IMessageConverter. +

This will only work with a default destination specified!

+ + the object to convert to a message + + If there is any problem accessing the EMS API + + + Send the given object to the specified destination, converting the object + to a EMS message with a configured IMessageConverter. + + the destination to send this message to + + the object to convert to a message + + If there is any problem accessing the EMS API + + + Send the given object to the specified destination, converting the object + to a EMS message with a configured IMessageConverter. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the object to convert to a message + + If there is any problem accessing the EMS API + + + Send the given object to the default destination, converting the object + to a EMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. +

This will only work with a default destination specified!

+ + the object to convert to a message + + the callback to modify the message + + If there is any problem accessing the EMS API + + + Send the given object to the specified destination, converting the object + to a EMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the destination to send this message to + + the object to convert to a message + + the callback to modify the message + + If there is any problem accessing the EMS API + + + Send the given object to the specified destination, converting the object + to a EMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the object to convert to a message. + + the callback to modify the message + + If there is any problem accessing the EMS API + + + + Send the given object to the default destination, converting the object + to a EMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. +

This will only work with a default destination specified!

+ + the object to convert to a message + the callback to modify the message + If there is any problem accessing the EMS API + + + + Send the given object to the specified destination, converting the object + to a EMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the destination to send this message to + the object to convert to a message + the callback to modify the message + If there is any problem accessing the EMS API + + + + Send the given object to the specified destination, converting the object + to a EMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + the object to convert to a message. + the callback to modify the message + If there is any problem accessing the EMS API + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the message received by the consumer, or null if the timeout expires + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the message received by the consumer, or null if the timeout expires + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the message received by the consumer, or null if the timeout expires + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the EMS message selector expression (or null if none). + See the EMS specification for a detailed definition of selector expressions. + + the message received by the consumer, or null if the timeout expires + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the EMS message selector expression (or null if none). + See the EMS specification for a detailed definition of selector expressions. + + the message received by the consumer, or null if the timeout expires + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the EMS message selector expression (or null if none). + See the EMS specification for a detailed definition of selector expressions. + + the message received by the consumer, or null if the timeout expires + + If there is any problem accessing the EMS API + + + + Receive a message. + + The session to operate on. + The destination to receive from. + The message selector for this consumer (can be null + The Message received, or null if none. + + + + Receive a message. + + The session to operate on. + The consumer to receive with. + The Message received, or null if none + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the message produced for the consumer or null if the timeout expires. + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the message produced for the consumer or null if the timeout expires. + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the message produced for the consumer or null if the timeout expires. + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the EMS message selector expression (or null if none). + See the EMS specification for a detailed definition of selector expressions. + + the message produced for the consumer or null if the timeout expires. + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the EMS message selector expression (or null if none). + See the EMS specification for a detailed definition of selector expressions. + + the message produced for the consumer or null if the timeout expires. + + If there is any problem accessing the EMS API + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the EMS message selector expression (or null if none). + See the EMS specification for a detailed definition of selector expressions. + + the message produced for the consumer or null if the timeout expires. + + If there is any problem accessing the EMS API + + + + Browses messages in the default EMS queue. The callback gives access to the EMS + Session and QueueBrowser in order to browse the queue and react to the contents. + + The action callback object that exposes the session/browser pair. + the result object from working with the session + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + The queue to browse. + The action callback object that exposes the session/browser pair. + the result object from working with the session + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + Name of the queue to browse, + (to be resolved to an actual destination by a DestinationResolver) + The action callback object that exposes the session/browser pair. + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + The EMS message selector expression (or null if none). + The action callback object that exposes the session/browser pair. + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + The queue to browse. + The EMS message selector expression (or null if none). + The action callback object that exposes the session/browser pair. + + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + Name of the queue to browse, + (to be resolved to an actual destination by a DestinationResolver) + The EMS message selector expression (or null if none). + The action callback object that exposes the session/browser pair. + + If there is any problem accessing the EMS API + + + + Browses messages in the default EMS queue. The callback gives access to the EMS + Session and QueueBrowser in order to browse the queue and react to the contents. + + The action callback delegate that exposes the session/browser pair. + the result object from working with the session + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + The queue to browse. + The action callback delegate that exposes the session/browser pair. + the result object from working with the session + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + Name of the queue to browse, + (to be resolved to an actual destination by a DestinationResolver) + The action callback delegate that exposes the session/browser pair. + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + The EMS message selector expression (or null if none). + The action callback delegate that exposes the session/browser pair. + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + The queue to browse. + The EMS message selector expression (or null if none). + The action callback delegate that exposes the session/browser pair. + + If there is any problem accessing the EMS API + + + + Browses messages in a EMS queue. The callback gives access to the EMS Session + and QueueBrowser in order to browse the queue and react to the contents. + + Name of the queue to browse, + (to be resolved to an actual destination by a DestinationResolver) + The EMS message selector expression (or null if none). + The action callback delegate that exposes the session/browser pair. + + If there is any problem accessing the EMS API + + + + Creates the queue browser. + + The session. + The queue. + The selector. + A new queue browser + + + + Gets or sets the default destination to be used on send/receive operations that do not + have a destination parameter. + + Alternatively, specify a "defaultDestinationName", to be + dynamically resolved via the DestinationResolver. + The default destination. + + + + Gets or sets the name of the default destination name + to be used on send/receive operations that + do not have a destination parameter. + + + Alternatively, specify a EMS Destination object as "DefaultDestination" + + The name of the default destination. + + + + Gets or sets the message converter for this template. + + + Used to resolve + Object parameters to convertAndSend methods and Object results + from receiveAndConvert methods. +

The default converter is a SimpleMessageConverter, which is able + to handle BytesMessages, TextMessages and ObjectMessages.

+ + The message converter. + + + + Gets or sets a value indicating whether Message Ids are enabled. + + true if message id enabled; otherwise, false. + + + + Gets or sets a value indicating whether message timestamps are enabled. + + + true if [message timestamp enabled]; otherwise, false. + + + + + Gets or sets a value indicating whether to inhibit the delivery of messages published by its own connection. + + + true if inhibit the delivery of messages published by its own connection; otherwise, false. + + + + Gets or sets the receive timeout to use for recieve calls. + + The default is -1, which means no timeout. + The receive timeout. + + + + Gets or sets a value indicating whether to use explicit Quality of Service values. + + If "true", then the values of deliveryMode, priority, and timeToLive + will be used when sending a message. Otherwise, the default values, + that may be set administratively, will be used + true if use explicit QoS values; otherwise, false. + + + + Sets a value indicating the delivery mode QOS + + + This will set the delivery to persistent, non-persistent, or reliable delivery. + Default value is Message.DEFAULT_DELIVERY_MODE (aka TIBCO.EMS.DeliveryMode.PERSISTENT) + + Integer value representing the delivery mode [delivery persistent]; otherwise, false. + + + + Gets or sets the priority when sending. + + Since a default value may be defined administratively, + this is only used when "isExplicitQosEnabled" equals "true". + The priority. + + + + Gets or sets the time to live when sending + + Since a default value may be defined administratively, + this is only used when "isExplicitQosEnabled" equals "true". + The time to live. + + + + ResourceFactory implementation that delegates to this template's callback methods. + + + + Callback for executing any number of operations on a provided + Session + + +

To be used with the EmsTemplate.Execute(ISessionCallback)} + method, often implemented as an anonymous inner class.

+ + Mark Pollack + + + + + Execute any number of operations against the supplied EMS + Session, possibly returning a result. + + the EMS Session + + a result object from working with the Session, if any (so can be null) + + EMSException if there is any problem + + + Creates a EMS message given a Session + +

The Session typically is provided by an instance + of the EmsTemplate class.

+ + Mark Pollack + + + Create a Message to be sent. + the EMS Session to be used to create the + Message (never null) + + the Message to be sent + + EMSException if thrown by EMS API methods + + + + This is a TIBCO specific class so that we can reuse connections, session, and + message producers instead of creating/destroying them on each operation. + + + + + Callback for browsing the messages in an EMS queue. + + + To be used with EmsTemplate's callback methods that take a IBrowserCallback argument + + Juergen Hoeller + Mark Pollack (.NET) + + + + Perform operations on the given Session and QueueBrowser + + The session. + The browser. + The object from working with the Session and QueueBrowser, may be null + If there is any problem when accessing EMS API + + + To be used with EmsTemplate's send method that + convert an object to a message. + + + It allows for further modification of the message after it has been processed + by the converter. This is useful for setting of EMS Header and Properties. + + Mark Pollack + + + Apply a IMessagePostProcessor to the message. The returned message is + typically a modified version of the original. + + the EMS message from the IMessageConverter + + the modified version of the Message + + EMSException if thrown by EMS API methods + + + Callback for sending a message to a EMS destination. + +

To be used with the EmsTemplate.Execute(IProducerCallback) + method, often implemented as an anonymous inner class.

+ +

The typical implementation will perform multiple operations on the + supplied EMS Session and MessageProducer.

+ + Mark Pollack + + + Perform operations on the given Session and MessageProducer. + The message producer is not associated with any destination. + + the EMS Session object to use + + the EMS MessageProducer object to use + + a result object from working with the Session, if any (can be null) + + + + + Delegate that creates a EMS message given a Session + + the EMS Session to be used to create the + Message (never null) + + the Message to be sent + + EMSException if thrown by EMS API methods + + + + Delegate that is used with EmsTemplate's ConvertAndSend method that converts + an object. + + + It allows for further modification of the message after it has been processed + by the converter. This is useful for setting of EMS Header and Properties. + + Mark Pollack + + + Perform operations on the given Session and MessageProducer. + The message producer is not associated with any destination. + + the EMS Session object to use + + the EMS MessageProducer object to use + + a result object from working with the Session, if any (can be null) + + + + + Callback delegate for code that operates on a Session. + + The EMS Session object. + + Allows you to execute any number of operations + on a single ISession, possibly returning a result a result. + + + A result object from working with the Session, if any (so can be null) + + EMSException if there is any problem + Mark Pollack + + + + Convenient superclass to access JndiProperties, JndiContextType or alternatively set the ILookupContext directly. + + Juergen Hoeller + Mark Pollack + + + + Create the JndiLookupContext if it has not been explicitly set. + + + + + Gets or sets the lookup context. + + The lookup context. + + + + Gets or sets the JNDI environment properties. + + The jndi properties. + + + + Gets or sets the type of the jndi context. The default is JndiContextType.JMS + + The type of the jndi context. + + + + The various JNDI Context types. + + + + + Create a tibjmsnaming context to lookup administered object inside the tibjmsnaming server. + + + + + Create a ldap context to lookup administered object in an ldap server. + + + + + Convenient superclass for JNDI-based service locators, + providing configurable lookup of a specific JNDI resource. + + + + Exposes a JndiName property. + + Subclasses may invoke the Lookup method whenever it is appropriate. + Some classes might do this on initialization, while others might do it + on demand. The latter strategy is more flexible in that it allows for + initialization of the locator before the JNDI object is available. + + + Juergen Hoeller + Mark Pollack (.NET) + + + + Ensure that the JndiName property is set and create the TIBCO EMS ILookupContext instance. + + + + + Lookups this instance using the JndiName and ExpectedType properties + + The object retrieved from Jndi + + + + Gets or sets the Jndi name to lookup. + + The name of the jndi. + + + + Gets or sets the type that the located JNDI object is supposed + to be assignable to, if any. + + The expected type. + + + + Return the Jndi object + + The Jndi object + + + + Sets the default object to fall back to if the JNDI lookup fails. + Default is none. + + + This can be an arbitrary bean reference or literal value. + It is typically used for literal values in scenarios where the JNDI environment + might define specific config settings but those are not required to be present. + + + The default object to use when lookup fails. + + + + Return type of object retrieved from Jndi or the expected type if the Jndi retrieval + did not succeed. + + Return value of retrieved object + + + + Returns true + + + + + Gets the template object definition that should be used + to configure the instance of the object managed by this factory. + + + + + + A Spring FactoryObject that returns TIBCO.EMS.ILookupContext. Use the returned + ILookupContext to do you lookups at runtime. + + + + Important properties to set are JndiProperties and JndiContexType. JndiContextType is set to + LookupContextFactory.TIBJMS_NAMING_CONT by default. + + To lookup objects at startup time and cache their values, as well as provide a + default value if lookup fail, + + + Mark Pollack + + + + Returns the TIBCO.EMS.ILookupContext + + TIBCO.EMS.ILookupContext + + + + Return typeof(TIBCO.EMS.ILookupContext) + + + + + Returns true + + + + + Exception thrown if a type mismatch is encountered for an object + located in a JNDI environment. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Creates a new instance of the + class. + + + A message about the exception. + + + + + Initializes a new instance of the class + building an explanation text from the given arguments. + + The Jndi name. + Type required type of the lookup. + The actual type that the lookup returned. + + + + Gets the actual type that the lookup returned, if available. + + The actual type that the lookup. + + + + Gets the required type for the lookup, if available. + + The equired type for the lookup + + + + Exception to be thrown when the execution of a listener method failed. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class, with the specified message + + The message. + + + + Initializes a new instance of the class, with the specified message + and root cause exception + + The message. + The inner exception. + + + + Message listener adapter that delegates the handling of messages to target + listener methods via reflection, with flexible message type conversion. + Allows listener methods to operate on message content types, completely + independent from the EMS API. + + + By default, the content of incoming messages gets extracted before + being passed into the target listener method, to let the target method + operate on message content types such as String or byte array instead of + the raw Message. Message type conversion is delegated to a Spring + . By default, a + will be used. (If you do not want such automatic message conversion taking + place, then be sure to set the property + to null.) + + If a target listener method returns a non-null object (typically of a + message content type such as String or byte array), it will get + wrapped in a EMS Message and sent to the response destination + (either the EMS "reply-to" destination or the + specified. + + + The sending of response messages is only available when + using the entry point (typically through a + Spring message listener container). Usage as standard EMS MessageListener + does not support the generation of response messages. + + Consult the reference documentation for examples of method signatures compliant with this + adapter class. + + + Juergen Hoeller + Mark Pollack (.NET) + + + + Variant of the standard EMS MessageListener interface, + offering not only the received Message but also the underlying + Session object. The latter can be used to send reply messages, + without the need to access an external Connection/Session, + i.e. without the need to access the underlying ConnectionFactory. + + + Supported by Spring's + as direct alternative to the standard MessageListener interface. + + Juergen Hoeller + Mark Pollack (.NET) + + + Callback for processing a received EMS message. + Implementors are supposed to process the given Message, + typically sending reply messages through the given Session. + + the received EMS message + + the underlying EMS Session + + EMSException if thrown by EMS methods + + + + The default handler method name. + + + + + Initializes a new instance of the class with default settings. + + + + + Initializes a new instance of the class for the given handler object + + The delegate object. + + + + Standard JMS {@link MessageListener} entry point. + Delegates the message to the target listener method, with appropriate + conversion of the message arguments + + + + In case of an exception, the method will be invoked. + Note + Does not support sending response messages based on + result objects returned from listener methods. Use the + entry point (typically through a Spring + message listener container) for handling result objects as well. + + The incoming message. + + + + Spring entry point. + + Delegates the message to the target listener method, with appropriate + conversion of the message argument. If the target method returns a + non-null object, wrap in a EMS message and send it back. + + + The incoming message. + The session to operate on. + + + + Initialize the default implementations for the adapter's strategies. + + + + + Handle the given exception that arose during listener execution. + The default implementation logs the exception at error level. + This method only applies when used as standard EMS MessageListener. + In case of the Spring mechanism, + exceptions get handled by the caller instead. + + + The exception to handle. + + + + Extract the message body from the given message. + + The message. + the content of the message, to be passed into the + listener method as argument + if thrown by EMS API methods + + + + Gets the name of the listener method that is supposed to + handle the given message. + The default implementation simply returns the configured + default listener method, if any. + + The EMS request message. + The converted JMS request message, + to be passed into the listener method as argument. + the name of the listener method (never null) + if thrown by EMS API methods + + + + Handles the given result object returned from the listener method, sending a response message back. + + The result object to handle (never null). + The original request message. + The session to operate on (may be null). + + + + Builds a JMS message to be sent as response based on the given result object. + + The JMS Session to operate on. + The content of the message, as returned from the listener method. + the JMS Message (never null) + If there was an error in message conversion + if thrown by EMS API methods + + + + Post-process the given response message before it will be sent. The default implementation + sets the response's correlation id to the request message's correlation id. + + The original incoming message. + The outgoing JMS message about to be sent. + if thrown by EMS API methods + + + + Determine a response destination for the given message. + + + The default implementation first checks the JMS Reply-To + Destination of the supplied request; if that is not null + it is returned; if it is null, then the configured + default response destination} + is returned; if this too is null, then an + is thrown. + + + The original incoming message. + Tthe outgoing message about to be sent. + The session to operate on. + the response destination (never null) + if thrown by EMS API methods + if no destination can be determined. + + + + Resolves the default response destination into a Destination, using this + accessor's in case of a destination name. + + The session to operate on. + The located destination + + + + Sends the given response message to the given destination. + + The session to operate on. + The destination to send to. + The outgoing message about to be sent. + + + + Post-process the given message producer before using it to send the response. + The default implementation is empty. + + The producer that will be used to send the message. + The outgoing message about to be sent. + + + + Gets or sets the handler object to delegate message listening to. + + + Specified listener methods have to be present on this target object. + If no explicit handler object has been specified, listener + methods are expected to present on this adapter instance, that is, + on a custom subclass of this adapter, defining listener methods. + + The handler object. + + + + Gets or sets the default handler method to delegate to, + for the case where no specific listener method has been determined. + Out-of-the-box value is ("HandleMessage"}. + + The default handler method. + + + + Sets the default destination to send response messages to. This will be applied + in case of a request message that does not carry a "JMSReplyTo" field. + Response destinations are only relevant for listener methods that return + result objects, which will be wrapped in a response message and sent to a + response destination. + + Alternatively, specify a "DefaultResponseQueueName" or "DefaultResponseTopicName", + to be dynamically resolved via the DestinationResolver. + + + The default response destination. + + + + Sets the name of the default response queue to send response messages to. + This will be applied in case of a request message that does not carry a + "EMSReplyTo" field. + Alternatively, specify a JMS Destination object as "defaultResponseDestination". + + The name of the default response destination queue. + + + + Sets the name of the default response topic to send response messages to. + This will be applied in case of a request message that does not carry a + "ReplyTo" field. + Alternatively, specify a JMS Destination object as "defaultResponseDestination". + + The name of the default response destination topic. + + + + Gets or sets the destination resolver that should be used to resolve response + destination names for this adapter. + The default resolver is a . + Specify another implementation, for other strategies, perhaps from a directory service. + + The destination resolver. + + + + Gets or sets the message converter that will convert incoming JMS messages to + listener method arguments, and objects returned from listener + methods back to EMS messages. + + + The default converter is a {@link SimpleMessageConverter}, which is able + to handle BytesMessages}, TextMessages, MapMessages, and ObjectMessages. + + + The message converter. + + + + Internal class combining a destination name and its target destination type (queue or topic). + + + + + Common base class for all containers which need to implement listening + based on a Connection (either shared or freshly obtained for each attempt). + Inherits basic Connection and Session configuration handling from the + base class. + + + This class provides basic lifecycle management, in particular management + of a shared Connection. Subclasses are supposed to plug into this + lifecycle, implementing the as well as + + + + + + Mark Pollack + + + + The monitor object to lock on when performing operations on the connection. + + + + + The monitor object to lock on when performing operations that update the lifecycle of the container. + + + + + Call base class method, then and then + + + + + Validates the configuration of this container. The default implementation + is empty. To be overriden in subclasses. + + + + + Calls when the application context destroys the container instance. + + + + + Initializes this container. Creates a Connection, starts the Connection + (if the property hasn't been turned off), and calls + . + + If startup failed + + + + Stop the shared connection, call , and close this container. + + + + + Starts this container. + + if starting failed. + + + + Start the shared Connection, if any, and notify all invoker tasks. + + + + + Stops this container. + + if stopping failed. + + + + Notify all invoker tasks and stop the shared Connection, if any. + + if thrown by EMS API methods. + + + + + Register any invokers within this container. + Subclasses need to implement this method for their specific + invoker management process. A shared Connection, if any, will already have been + started at this point. + + + + + Close the registered invokers. Subclasses need to implement this method + for their specific invoker management process. A shared Connection, if any, + will automatically be closed afterwards. + + + + + Establishes a shared Connection for this container. + + + + The default implementation delegates to + which does one immediate attempt and throws an exception if it fails. + Can be overridden to have a recovery process in place, retrying + until a Connection can be successfully established. + + + If thrown by EMS API methods + + + + Refreshes the shared connection that this container holds. + + + Called on startup and also after an infrastructure exception + that occurred during invoker setup and/or execution. + + If thrown by EMS API methods + + + + Creates the shared connection for this container. + + + The default implementation creates a standard Connection + and prepares it through + + the prepared Connection + if the creation failed. + + + + Prepares the given connection, which is about to be registered + as shared Connection for this container. + + + The default implementation sets the specified client id, if any. + Subclasses can override this to apply further settings. + + The connection to prepare. + If the preparation efforts failed. + + + + Starts the shared connection. + + If thrown by EMS API methods + + + + + Stops the shared connection. + + if thrown by EMS API methods. + + + + Gets or sets the client id for a shared Connection created and used by this container. + + + Note that client ids need to be unique among all active Connections + of the underlying JMS provider. Furthermore, a client id can only be + assigned if the original ConnectionFactory hasn't already assigned one. + + The client id. + + + Set whether to automatically start the listener after initialization. +

Default is "true"; set this to "false" to allow for manual startup.

+ + + + + Set the name of the object in the object factory that created this object. + + The name of the object in the factory. + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + + + Gets a value indicating whether this container is currently running, + that is, whether it has been started and not stopped yet. + + + true if this container is running; otherwise, false. + + + + + Gets a value indicating whether this container's listeners are generally allowed to run. + + + + >This implementation always returns true; the default 'running' + state is purely determined by /. + + + Subclasses may override this method to check against temporary + conditions that prevent listeners from actually running. In other words, + they may apply further restrictions to the 'running' state, returning + false if such a restriction prevents listeners from running. + + + true if running allowed; otherwise, false. + + + + Gets a value indicating whether this container is currently active, + that is, whether it has been set up but not shut down yet. + + true if active; otherwise, false. + + + Return whether a shared EMS Connection should be maintained + by this listener container base class. + + + + + + Gets the shared connection maintained by this container. + Available after initialization. + + The shared connection (never null) + if this container does not maintain a + shared Connection, or if the Connection hasn't been initialized yet. + + + + + + Exception that indicates that the initial setup of this container's + shared Connection failed. This is indicating to invokers that they need + to establish the shared Connection themselves on first access. + + + + + Initializes a new instance of the class. + + The message. + + + + Abstract base class for message listener containers. Can either host + a standard EMS MessageListener or a Spring-specific + + + + + + Validate that the destination is not null and that if the subscription is durable, then we are not + using the Pub/Sub domain. + + + + + Executes the specified listener, + committing or rolling back the transaction afterwards (if necessary). + + The session to operate on. + The received message. + + + + + + + + Executes the specified listener, + committing or rolling back the transaction afterwards (if necessary). + + The session to operate on. + The received message. + If thrown by EMS API methods. + + + + + + + Invokes the specified listener: either as standard EMS MessageListener + or (preferably) as Spring ISessionAwareMessageListener. + + The session to operate on. + The received message. + If thrown by EMS API methods. + + + + + Invoke the specified listener as Spring ISessionAwareMessageListener, + exposing a new EMS Session (potentially with its own transaction) + to the listener if demanded. + + The Spring ISessionAwareMessageListener to invoke. + The session to operate on. + The received message. + If thrown by EMS API methods. + + + + + + Invoke the specified listener as standard JMS MessageListener. + + Default implementation performs a plain invocation of the + OnMessage methods + The listener to invoke. + The received message. + if thrown by the EMS API methods + + + + Perform a commit or message acknowledgement, as appropriate + + The session to commit. + The message to acknowledge. + In case of commit failure + + + + Determines whether the given Session is locally transacted, that is, whether + its transaction is managed by this listener container's Session handling + and not by an external transaction coordinator. + + + The Session's own transacted flag will already have been checked + before. This method is about finding out whether the Session's transaction + is local or externally coordinated. + + The session to check. + + true if the is session locally transacted; otherwise, false. + + + + + + Perform a rollback, if appropriate. + + The session to rollback. + In case of a rollback error + + + + Perform a rollback, handling rollback excepitons properly. + + The session to rollback. + The thrown application exception. + in case of a rollback error. + + + + Handle the given exception that arose during listener execution. + + + The default implementation logs the exception at error level, + not propagating it to the JMS provider - assuming that all handling of + acknowledgement and/or transactions is done by this listener container. + This can be overridden in subclasses. + + The exceptin to handle + + + + Invokes the registered exception listener, if any. + + The exception that arose during EMS processing. + + + + + Checks the message listener, throwing an exception + if it does not correspond to a supported listener type. + By default, only a standard JMS MessageListener object or a + Spring object will be accepted. + + The message listener. + + + + Gets or sets the destination to receive messages from. Will be null + if the configured destination is not an actual Destination type; + c.f. when the destination is a String. + + The destination. + + + + Gets or sets the name of the destination to receive messages from. + Will be null if the configured destination is not a + string type; c.f. when it is an actual Destination object. + + The name of the destination. + + + + Gets or sets the message selector. + + The message selector expression (or null if none).. + + + + Gets or sets the message listener to register. + + + + + This can be either a standard EMS MessageListener object or a + Spring object. + + + The message listener. + + + + Gets or sets a value indicating whether the subscription is durable. + + + Set whether to make the subscription durable. The durable subscription name + to be used can be specified through the "DurableSubscriptionName" property. + Default is "false". Set this to "true" to register a durable subscription, + typically in combination with a "DurableSubscriptionName" value (unless + your message listener class name is good enough as subscription name). + + Only makes sense when listening to a topic (pub-sub domain). + + true if the subscription is durable; otherwise, false. + + + + Gets or sets the name of the durable subscription to create. + + + To be applied in case of a topic (pub-sub domain) with subscription durability activated. + The durable subscription name needs to be unique within this client's + client id. Default is the class name of the specified message listener. + Note: Only 1 concurrent consumer (which is the default of this + message listener container) is allowed for each durable subscription. + + + The name of the durable subscription. + + + + Gets or sets the exception listener to notify in case of a EMSException thrown + by the registered message listener or the invocation infrastructure. + + The exception listener. + + + + Sets an ErrorHandler to be invoked in case of any uncaught exceptions thrown + while processing a Message. By default there will be no ErrorHandler + so that error-level logging is the only result. + + The error handler. + + + + Gets or sets a value indicating whether to expose listener session to a registered + as well as to calls. + + + Default is "true", reusing the listener's Session. + Turn this off to expose a fresh Session fetched from the same + underlying Connection instead, which might be necessary + on some messaging providers. + Note that Sessions managed by an external transaction manager will + always get exposed to + calls. So in terms of EmsTemplate exposure, this setting only affects + locally transacted Sessions. + + + + true if expose listener session; otherwise, false. + + + + + Gets or sets a value indicating whether to accept messages while + the listener container is in the process of stopping. + + + + Return whether to accept received messages while the listener container + receive attempt. Switch this flag on to fully process such messages + even in the stopping phase, with the drawback that even newly sent + messages might still get processed (if coming in before all receive + timeouts have expired). + + + Aborting receive attempts for such incoming messages + might lead to the provider's retry count decreasing for the affected + messages. If you have a high number of concurrent consumers, make sure + that the number of retries is higher than the number of consumers, + to be on the safe side for all potential stopping scenarios. + + + + true if accept messages while in the process of stopping; otherwise, false. + + + + + Internal exception class that indicates a rejected message on shutdown. + Used to trigger a rollback for an external transaction manager in that case. + + + + + EmsResourceHolder marker subclass that indicates local exposure, + i.e. that does not indicate an externally managed transaction. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + The session. + + + + Exception thrown when the maximum connection recovery time has been exceeded. + + Mark Pollack + + + + Initializes a new instance of the class, with the specified message + + The message. + + + + Initializes a new instance of the class, with the specified message + and root cause exception + + The message. + The inner exception. + + + + Message listener container that uses the plain EMS client API's + MessageConsumer.Listener method to create concurrent + MessageConsumers for the specified listeners. + + Juergen Hoeller + Mark Pollack (.NET) + + + + The default recovery time interval between connection reconnection attempts + + + + + The total time connection recovery will be attempted. + + + + + Call base class for valdation and then check that if the subscription is durable that the number of + concurrent consumers is equal to one. + + + + + Creates the specified number of concurrent consumers, + in the form of a JMS Session plus associated MessageConsumer + + + + + + Re-initializes this container's EMS message consumers, + if not initialized already. + + + + + Registers this listener container as EMS ExceptionListener on the shared connection. + + + + + + implementation, invoked by the EMS provider in + case of connection failures. Re-initializes this listener container's + shared connection and its sessions and consumers. + + The reported connection exception. + + + + Refresh the underlying Connection, not returning before an attempt has been + successful. Called in case of a shared Connection as well as without shared + Connection, so either needs to operate on the shared Connection or on a + temporary Connection that just gets established for validation purposes. + + + The default implementation retries until it successfully established a + Connection, for as long as this message listener container is active. + Applies the specified recovery interval between retries. + + + + + The amount of time to sleep in between recovery attempts. + + + + + Initialize the Sessions and MessageConsumers for this container. + + in case of setup failure. + + + + Creates a MessageConsumer for the given Session, + registering a MessageListener for the specified listener + + The session to work on. + the MessageConsumer"/> + if thrown by EMS methods + + + + Close the message consumers and sessions. + + EMSException if destruction failed + + + + Creates a MessageConsumer for the given Session and Destination. + + The session to create a MessageConsumer for. + The destination to create a MessageConsumer for. + The new MessageConsumer + + + + Gets or sets a value indicating whether to inhibit the delivery of messages published by its own connection. + Default is "false". + + true if should inhibit the delivery of messages published by its own connection; otherwise, false. + + + + Specify the number of concurrent consumers to create. Default is 1. + + + Raising the number of concurrent consumers is recommendable in order + to scale the consumption of messages coming in from a queue. However, + note that any ordering guarantees are lost once multiple consumers are + registered. In general, stick with 1 consumer for low-volume queues. + Do not raise the number of concurrent consumers for a topic. + This would lead to concurrent consumption of the same message, + which is hardly ever desirable. + + + The concurrent consumers. + + + + Sets the time interval between connection recovery attempts. The default is 5 seconds. + + The recovery interval. + + + + Sets the max recovery time to try reconnection attempts. The default is 10 minutes. + + The max recovery time. + + + + Always use a shared EMS connection + + + + Strategy interface that specifies a IMessageConverter + between .NET objects and EMS messages. + + + Mark Pollack + Juergen Hoeller + Mark Pollack (.NET) + + + Convert a .NET object to a EMS Message using the supplied session + to create the message object. + + the object to convert + + the Session to use for creating a EMS Message + + the EMS Message + + EMSException if thrown by EMS API methods + MessageConversionException in case of conversion failure + + + Convert from a EMS Message to a .NET object. + the message to convert + + the converted .NET object + + MessageConversionException in case of conversion failure + + + + Provides a layer of indirection when adding the 'type' of the object as a message property. + + Mark Pollack + + + + Convert from a type to a string. + + The type of object to convert. + + + + + Convert from a string to a type + + The type id. + + + + + Gets the name of the field in the message that has type information.. + + The name of the type id field. + + + Thrown by IMessageConverter implementations when the conversion + of an object to/from a Message fails. + + Mark Pollack + + + + Creates a new instance of the IMessageConverterException class. with the specified message. + + + A message about the exception. + + + + + Creates a new instance of the IMessageConverterException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + A simple message converter that can handle TextMessages, BytesMessages, + MapMessages, and ObjectMessages. Used as default by EmsTemplate, for + ConvertAndSend and ReceiveAndConvert operations. + +

Converts a String to a EMS TextMessage, a byte array to a EMS BytesMessage, + a Map to a EMS MapMessage, and a Serializable object to a EMS ObjectMessage + (or vice versa).

+ + + + Juergen Hoeller + Mark Pollack (.NET) + + + Convert a .NET object to a EMS Message using the supplied session + to create the message object. + + the object to convert + + the Session to use for creating a EMS Message + + the EMS Message + + EMSException if thrown by EMS API methods + MessageConversionException in case of conversion failure + + + Convert from a EMS Message to a .NET object. + the message to convert + + the converted .NET object + + MessageConversionException in case of conversion failure + + + Create a EMS TextMessage for the given String. + the String to convert + + current EMS session + + the resulting message + + EMSException if thrown by EMS methods + + + Create a EMS BytesMessage for the given byte array. + the byyte array to convert + + current EMS session + + the resulting message + + EMSException if thrown by EMS methods + + + Create a EMS MapMessage for the given Map. + the Map to convert + + current EMS session + + the resulting message + + EMSException if thrown by EMS methods + + + Create a EMS ObjectMessage for the given Serializable object. + the Serializable object to convert + + current EMS session + + the resulting message + + EMSException if thrown by EMS methods + + + Extract a String from the given TextMessage. + the message to convert + + the resulting String + + EMSException if thrown by EMS methods + + + Extract a byte array from the given BytesMessage. + the message to convert + + the resulting byte array + + EMSException if thrown by EMS methods + + + Extract a IDictionary from the given MapMessage. + the message to convert + + the resulting Map + + EMSException if thrown by EMS methods + + + + Extracts the serializable object from the given object message. + + The message to convert. + The resulting serializable object. + + + + Provides a layer of indirection when adding the 'type' of the object as a message property. + + + + + Initializes a new instance of the + + + + + Convert from a type to a string. + + The type of object to convert. + + + + + Convert from a string to a type + + The type id. + + + + + Afters the properties set. + + + + + Gets or sets the id type mapping. + + The id type mapping. + + + + Gets the name of the field in the message that has type information.. + + The name of the type id field. + + + + Sets the default hashtable class. + + The default hashtable class. + + + + Gets or sets the default namespace. + + The default namespace. + + + + Gets or sets the default name of the assembly. + + The default name of the assembly. + + + + Convert an object via XML serialization for sending via an ITextMessage + + Mark Pollack + + + + Convert a .NET object to a EMS Message using the supplied session + to create the message object. + + the object to convert + the Session to use for creating a EMS Message + the EMS Message + EMSException if thrown by EMS API methods + MessageConversionException in case of conversion failure + + + + Gets the XML string for an object + + The object to convert. + XML string + + + + Convert from a EMS Message to a .NET object. + + the message to convert + the converted .NET object + MessageConversionException in case of conversion failure + + + + Gets the type of the target given the message. + + The message. + Type of the target + + + + Converts a byte array to a UTF8 string. + + The characters. + UTF8 string + + + + Converts a UTF8 string to a byte array + + The p XML string. + + + + + Sets the type mapper. + + The type mapper. + + + + Gets or sets a value indicating whether encoder should emit UTF8 byte order mark. Default is false. + + + true to specify that a Unicode byte order mark is provided; otherwise, false. + + + + + Gets or sets a value indicating whether to throw an exception on invalid bytes. Default is true. + + true to specify that an exception be thrown when an invalid encoding is detected; otherwise, false. + + + + Simple DestinationResolver implementation resolving destination names + as dynamic destinations. + + Juergen Hoeller + Mark Pollack (.NET) + + + Strategy interface for resolving EMS destinations. + + + Used by EmsTemplate for resolving + destination names from simple Strings to actual + Destination implementation instances. + + + The default DestinationResolver implementation used by + EmsTemplate instances is the + DynamicDestinationResolver class. Consider using the + JndDestinationResolver for more advanced scenarios. + + + Juergen Hoeller + Mark Pollack (.NET) + + + Resolve the given destination name, either as located resource + or as dynamic destination. + + the current EMS Session + + the name of the destination + + true if the domain is pub-sub, false if P2P + + the EMS destination (either a topic or a queue) + + EMSException if resolution failed + + + Resolve the given destination name, either as located resource + or as dynamic destination. + + the current EMS Session + + the name of the destination + + true if the domain is pub-sub, false if P2P + + the EMS destination (either a topic or a queue) + + EMSException if resolution failed + + + Resolve the given destination name to a Topic. + the current EMS Session + + the name of the desired Topic. + + the EMS Topic name + + EMSException if resolution failed + + + Resolve the given destination name to a Queue. + the current EMS Session + + the name of the desired Queue. + + the EMS Queue name + + EMSException if resolution failed + + + + Generic utility methods for working with EMS. Mainly for internal use + within the framework, but also useful for custom EMS access code. + + + + Close the given EMS Connection and ignore any thrown exception. + This is useful for typical finally blocks in manual EMS code. + + the EMS Connection to close (may be null) + + + + Close the given EMS Connection and ignore any thrown exception. + This is useful for typical finally blocks in manual EMS code. + + the EMS Connection to close (may be null) + + whether to call stop() before closing + + + + Close the given EMS Session and ignore any thrown exception. + This is useful for typical finally blocks in manual EMS code. + + the EMS Session to close (may be null) + + + + Close the given EMS MessageProducer and ignore any thrown exception. + This is useful for typical finally blocks in manual EMS code. + + the EMS MessageProducer to close (may be null) + + + + Close the given EMS MessageConsumer and ignore any thrown exception. + This is useful for typical finally blocks in manual EMS code. + + the EMS MessageConsumer to close (may be null) + + + + Commit the Session if not within a distributed transaction. + Needs investigation - no distributed tx in .NET messaging providers + the EMS Session to commit + + EMSException if committing failed + + + Rollback the Session if not within a distributed transaction. + Needs investigation - no distributed tx in EMS + the EMS Session to rollback + + EMSException if committing failed + + + + Closes the given queue browser and ignore any thrown exception. + This is useful for typical finally blocks in manual EMS code. + + The queue browser to close (may be null. + + + + Converts the acknowledgement mode from an integer to an enumeration. If the integer + does not match a valid enumeration, the returned enumeration is SessionMode.AutoAcknowledge + + The ack mode. + The corresponding SessionMode enumeration + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Messaging.Nms.dll b/Resources/Libraries/Spring.NET/Spring.Messaging.Nms.dll new file mode 100644 index 00000000..012fbbe4 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Messaging.Nms.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Messaging.Nms.pdb b/Resources/Libraries/Spring.NET/Spring.Messaging.Nms.pdb new file mode 100644 index 00000000..30300af6 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Messaging.Nms.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Messaging.Nms.xml b/Resources/Libraries/Spring.NET/Spring.Messaging.Nms.xml new file mode 100644 index 00000000..03eb447a --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Messaging.Nms.xml @@ -0,0 +1,4469 @@ + + + + Spring.Messaging.Nms + + + + + Parser for the NMS <listener-container> element. + + Mark Fisher + Juergen Hoeller + Mark Pollack (.NET) + + + + Parse the specified XmlElement and register the resulting + ObjectDefinitions with the IObjectDefinitionRegistry + embedded in the supplied + + The element to be parsed. + TThe object encapsulating the current state of the parsing process. + Provides access to a IObjectDefinitionRegistry + The primary object definition. + +

+ This method is never invoked if the parser is namespace aware + and was called to process the root node. +

+ + + + + Namespace parser for the nms namespace. + + Mark Fisher + Juergen Hoeller + Mark Pollack (.NET) + + + + Register a MessageListenerContainer for the 'listener-container' tag. + + + + + NMS MessageConsumer decorator that adapts all calls + to a shared MessageConsumer instance underneath. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + The target. + + + + Receives the next message produced for this message consumer. + + the next message produced for this message consumer, , or null if this message consumer is concurrently closed + + + + Receives the next message that arrives within the specified timeout interval. + + The timeout value. + the next message produced for this message consumer, or null if the timeout expires or this message consumer is concurrently closed + + + + Receives the next message if one is immediately available. + + the next message produced for this message consumer, or null if one is not available + + + + No-op implementation since it is caching. + + + + + Dispose of wrapped MessageConsumer + + + + + Description that shows this is a cached MessageConsumer + + Description that shows this is a cached MessageConsumer + + + + Gets the target MessageConsumer, the consumer we are 'wrapping' + + The target MessageConsumer. + + + + Register for message events. + + + + + A Delegate that is called each time a Message is dispatched to allow the client to do + any necessary transformations on the received message before it is delivered. + + + + + + MessageProducer decorator that adapts calls to a shared MessageProducer + instance underneath, managing QoS settings locally within the decorator. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + The target. + + + + Sends the specified message. + + The message. + + + + Sends a message to the specified message. + + The message to send. + The QOS to use for sending . + The message priority. + The time to live. + + + + Sends a message to the specified destination. + + The destination. + The message. + + + + Sends a message the specified destination. + + The destination. + The message to send. + The QOS to use for sending . + The priority. + The time to live. + + + + Creates the message. + + A new message + + + + Creates the text message. + + A new text message. + + + + Creates the text message. + + The text. + A texst message with the given text. + + + + Creates the map message. + + a new map message. + + + + Creates the object message. + + The body. + A new object message with the given body. + + + + Creates the bytes message. + + A new bytes message. + + + + Creates the bytes message. + + The body. + A new bytes message with the given body. + + + + Creates the stream message. + + A new stream message. + + + + Reset properties. + + + + + Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. + + + + + Returns string indicated this is a wrapped MessageProducer + + + + + + Gets the target MessageProducer, the producer we are 'wrapping' + + The target MessageProducer. + + + + A delegate that is called each time a Message is sent from this Producer which allows + the application to perform any needed transformations on the Message before it is sent. + The Session instance sets the delegate on each Producer it creates. + + + + + + Gets or sets a value indicating what DeliveryMode this + should use, for example a persistent QOS + + + + + + Gets or sets the time to live value for messages sent with this producer. + + The time to live. + + + + Gets or sets the request timeout for the message producer. + + The request timeout. + + + + Gets or sets the priority of messages sent with this producer. + + The priority. + + + + Gets or sets a value indicating whether disable setting of the message ID property. + + true if disable message ID setting; otherwise, false. + + + + Gets or sets a value indicating whether disable setting the message timestamp property. + + + true if disable message timestamp; otherwise, false. + + + + + Wrapper for Session that caches producers and registers itself as available + to the session cache when being closed. Generally used for testing purposes or + if need to get at the wrapped Session object via the TargetSession property (for + vendor specific methods). + + Juergen Hoeller + Mark Pollack + + + + Subinterface of Session to be implemented by + implementations that wrap an Session to provide added + functionality. Allows access to the the underlying target Session. + + Mark Pollack + + + + + + Gets the target session of the decorator. + This will typically be the native provider Session or a wrapper from a session pool. + + The underlying session, never null + + + + Initializes a new instance of the class. + + The target session. + The session list. + The CachingConnectionFactory. + + + + Creates the producer, potentially returning a cached instance. + + A message producer, potentially cached. + + + + Creates the producer, potentially returning a cached instance. + + The destination. + A message producer. + + + + If have not yet reached session cache size, cache the session, otherwise + dispose of all cached message producers and close the session. + + + + + Creates the consumer, potentially returning a cached instance. + + The destination. + A message consumer + + + + Creates the consumer, potentially returning a cached instance. + + The destination. + The selector. + A message consumer + + + + Creates the consumer, potentially returning a cached instance. + + The destination. + The selector. + if set to true [no local]. + A message consumer. + + + + Creates the durable consumer, potentially returning a cached instance. + + The destination. + The name of the durable subscription. + The selector. + if set to true [no local]. + A message consumer + + + + Deletes the durable consumer. + + The name of the durable subscription. + + + + Creates the consumer. + + The destination. + The selector. + if set to true [no local]. + The durable subscription name. + + + + + Gets the queue. + + The name. + + + + + Gets the topic. + + The name. + + + + + Creates the temporary queue. + + + + + + Creates the temporary topic. + + + + + + Deletes the destination. + + The destination. + + + + Creates the message. + + + + + + Creates the text message. + + + + + + Creates the text message. + + The text. + + + + + Creates the map message. + + + + + + Creates the object message. + + The body. + + + + + Creates the bytes message. + + + + + + Creates the bytes message. + + The body. + + + + + Creates the stream message. + + + + + + Commits this instance. + + + + + Rollbacks this instance. + + + + + Call dispose on the target. + + + + + Creates the queue browser with a specified selector + + The queue. + The selector. + The Queue browser + + + + Creates the queue browser. + + The queue. + The Queue browser + + + + Returns a that represents the current . + + + A that represents the current . + + + + + Gets the target, for testing purposes. + + The target. + + + + A Delegate that is called each time a Message is dispatched to allow the client to do + any necessary transformations on the received message before it is delivered. + The Session instance sets the delegate on each Consumer it creates. + + + + + + A delegate that is called each time a Message is sent from this Producer which allows + the application to perform any needed transformations on the Message before it is sent. + The Session instance sets the delegate on each Producer it creates. + + + + + + Gets or sets the request timeout. + + The request timeout. + + + + Gets a value indicating whether this is transacted. + + true if transacted; otherwise, false. + + + + Gets the acknowledgement mode. + + The acknowledgement mode. + + + + subclass that adds + Session, MessageProducer, and MessageConsumer caching. This ConnectionFactory + also switches the ReconnectOnException property to true + by default, allowing for automatic recovery of the underlying + Connection. + + + By default, only one single Session will be cached, with further requested + Sessions being created and disposed on demand. Consider raising the + SessionCacheSize property in case of a high-concurrency environment. + + NOTE: This ConnectionFactory requires explicit closing of all Sessions + obtained from its shared Connection. This is the usual recommendation for + native NMS access code anyway. However, with this ConnectionFactory, its use + is mandatory in order to actually allow for Session reuse. + + + Note also that MessageConsumers obtained from a cached Session won't get + closed until the Session will eventually be removed from the pool. This may + lead to semantic side effects in some cases. For a durable subscriber, the + logical Session.Close() call will also close the subscription. + Re-registering a durable consumer for the same subscription on the same + Session handle is not supported; close and reobtain a cached Session first. + + + + Juergen Hoeller + Mark Pollack (.NET) + + + + A ConnectionFactory adapter that returns the same Connection + from all CreateConnection() calls, and ignores calls to + Connection.Close(). According to the JMS Connection + model, this is perfectly thread-safe. The + shared Connection can be automatically recovered in case of an Exception. + + + + You can either pass in a specific Connection directly or let this + factory lazily create a Connection via a given target ConnectionFactory. + + + Useful for testing and in applications when you want to keep using the + same Connection for multiple + calls, without having a pooling ConnectionFactory underneath. This may span + any number of transactions, even concurrently executing transactions. + + + Note that Spring's message listener containers support the use of + a shared Connection within each listener container instance. Using + SingleConnectionFactory with a MessageListenerContainer only really makes sense for + sharing a single Connection across multiple listener containers. + + + Juergen Hoeller + Mark Pollack + Mark Pollack (.NET) + + + + Exception handler for exceptions from the messaging infrastrcture. + + Mark Pollack + + + + Called when there is an exception in message processing. + + The exception. + + + + Wrapped Connection + + + + + Proxy Connection + + + + + Whether the shared Connection has been started + + + + + Synchronization monitor for the shared Connection + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class + that alwasy returns the given Connection. + + The single Connection. + + + + Initializes a new instance of the class + that alwasy returns a single Connection. + + The target connection factory. + + + + Creates the connection. + + A single shared connection + + + + Creates the connection. + + Name of the user. + The password. + + + + + Initialize the underlying shared Connection. Closes and reinitializes the Connection if an underlying + Connection is present already. + + + + + Exception listener callback that renews the underlying single Connection. + + The exception from the messaging infrastructure. + + + + Prepares the connection before it is exposed. + The default implementation applies ExceptionListener and client id. + Can be overridden in subclasses. + + The Connection to prepare. + if thrown by any NMS API methods. + + + + Template method for obtaining a (potentially cached) Session. + + The connection to operate on. + The session ack mode. + the Session to use, or null to indicate + creation of a raw standard Session + + + + reate a JMS Connection via this template's ConnectionFactory. + + + + + + Closes the given connection. + + The connection. + + + + Ensure that the connection or TargetConnectionFactory are specified. + + + + + Close the underlying shared connection. The provider of this ConnectionFactory needs to care for proper shutdown. + As this object implements an application context will automatically + invoke this on distruction o + + + + + Resets the underlying shared Connection, to be reinitialized on next access. + + + + + Wrap the given Connection with a proxy that delegates every method call to it + but suppresses close calls. This is useful for allowing application code to + handle a special framework Connection just like an ordinary Connection from a + ConnectionFactory. + + The original connection to wrap. + the wrapped connection + + + + Gets or sets the target connection factory which will be used to create a single + connection. + + The target connection factory. + + + + Gets or sets the client id for the single Connection created and exposed by + this ConnectionFactory. + + Note that the client IDs need to be unique among all active + Connections of teh underlying provider. Furthermore, a client ID can only + be assigned if the original ConnectionFactory hasn't already assigned one. + The client id. + + + + Gets or sets the exception listener implementation that should be registered + with with the single Connection created by this factory, if any. + + The exception listener. + + + + Gets or sets a value indicating whether the single Connection + should be reset (to be subsequently renewed) when a NMSException + is reported by the underlying Connection. + + + Default is false. Switch this to true + to automatically trigger recover based on your messaging provider's + exception notifications. + + Internally, this will lead to a special ExceptionListener (this + SingleConnectionFactory itself) being registered with the underlying + Connection. This can also be combined with a user-specified + ExceptionListener, if desired. + + + + true attempt to reconnect on exception during next access; otherwise, false. + + + + + Get/or set the broker Uri. + + + + + Get/or set the redelivery policy that new IConnection objects are + assigned upon creation. + + + + + A Delegate that is called each time a Message is dispatched to allow the client to do + any necessary transformations on the received message before it is delivered. The + ConnectionFactory sets the provided delegate instance on each Connection instance that + is created from this factory, each connection in turn passes the delegate along to each + Session it creates which then passes that along to the Consumers it creates. + + + + + + A delegate that is called each time a Message is sent from this Producer which allows + the application to perform any needed transformations on the Message before it is sent. + The ConnectionFactory sets the provided delegate instance on each Connection instance that + is created from this factory, each connection in turn passes the delegate along to each + Session it creates which then passes that along to the Producers it creates. + + + + + + Gets the connection monitor. + + The connection monitor. + + + + Gets a value indicating whether this instance is started. + + + true if this instance is started; otherwise, false. + + + + + Initializes a new instance of the class. + and sets the ReconnectOnException to true + + + + + Initializes a new instance of the class for the given + IConnectionFactory + + The target connection factory. + + + + Resets the Session cache as well as resetting the connection. + + + + + Obtaining a cached Session. + + The connection to operate on. + The session ack mode. + The Session to use + + + + + Wraps the given Session so that it delegates every method call to the target session but + adapts close calls. This is useful for allowing application code to + handle a special framework Session just like an ordinary Session. + + The original Session to wrap. + The List of cached Sessions that the given Session belongs to. + The wrapped Session + + + + Gets or sets the size of the session cache. + + + This cache size is the maximum limit for the number of cached Sessions + per session acknowledgement type (auto, client, dups_ok, transacted). + As a consequence, the actual number of cached Sessions may be up to + four times as high as the specified value - in the unlikely case + of mixing and matching different acknowledgement types. + + Default is 1: caching a single Session, (re-)creating further ones on + demand. Specify a number like 10 if you'd like to raise the number of cached + Sessions; that said, 1 may be sufficient for low-concurrency scenarios. + + + The size of the session cache. + + + + Gets or sets a value indicating whether to cache MessageProducers per + Session instance. (more specifically: one MessageProducer per Destination + and Session). + + + Default is "true". Switch this to "false" in order to always, + recreate MessageProducers on demand. + + + true if should cache message producers; otherwise, false. + + + + Gets or sets a value indicating whether o cache JMS MessageConsumers per + NMS Session instance. + + + Mmore specifically: one MessageConsumer per Destination, selector String + and Session. Note that durable subscribers will only be cached until + logical closing of the Session handle. + + Default is "true". Switch this to "false" in order to always + recreate MessageConsumers on demand. + + + true to cache consumers per session instance; otherwise, false. + + + + Gets or sets a value indicating whether this instance is active. + + true if this instance is active; otherwise, false. + + + + Implementation of Spring IExceptionListener interface that supports + chaining allowing the addition of multiple ExceptionListener instances in order. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Adds the exception listener to the chain + + The listener. + + + + Called when an exception occurs in message processing. + + The exception. + + + + Gets the exception listeners as an array. + + The exception listeners. + + + Helper class for obtaining transactional NMS resources + for a given ConnectionFactory. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Releases the given connection, stopping it (if necessary) and eventually closing it. + + Checks , if available. + This is essentially a more sophisticated version of + + + The connection to release. (if this is null, the call will be ignored) + The ConnectionFactory that the Connection was obtained from. (may be null) + whether the Connection might have been started by the application. + + + + Return the innermost target Session of the given Session. If the given + Session is a decorated session, it will be unwrapped until a non-decorated + Session is found. Otherwise, the passed-in Session will be returned as-is. + + The session to unwrap + The innermost target Session, or the passed-in one if no decorator + + + + Determines whether the given JMS Session is transactional, that is, + bound to the current thread by Spring's transaction facilities. + + The session to check. + The ConnectionFactory that the Session originated from + + true if is session transactional, bound to current thread; otherwise, false. + + + + Obtain a NMS Session that is synchronized with the current transaction, if any. + the ConnectionFactory to obtain a Session for + + the existing NMS Connection to obtain a Session for + (may be null) + + whether to allow for a local NMS transaction + that is synchronized with a Spring-managed transaction (where the main transaction + might be a ADO.NET-based one for a specific DataSource, for example), with the NMS + transaction committing right after the main transaction. If not allowed, the given + ConnectionFactory needs to handle transaction enlistment underneath the covers. + + the transactional Session, or null if none found + + NMSException in case of NMS failure + + + + Obtain a NMS Session that is synchronized with the current transaction, if any. + + the TransactionSynchronizationManager key to bind to + (usually the ConnectionFactory) + the ResourceFactory to use for extracting or creating + NMS resources + whether the underlying Connection approach should be + started in order to allow for receiving messages. Note that a reused Connection + may already have been started before, even if this flag is false. + + the transactional Session, or null if none found + + NMSException in case of NMS failure + + + Callback interface for resource creation. + Serving as argument for the DoGetTransactionalSession method. + + + + Fetch an appropriate Session from the given MessageResourceHolder. + the MessageResourceHolder + + an appropriate Session fetched from the holder, + or null if none found + + + + Fetch an appropriate Connection from the given MessageResourceHolder. + the MessageResourceHolder + + an appropriate Connection fetched from the holder, + or null if none found + + + + Create a new NMS Connection for registration with a MessageResourceHolder. + the new NMS Connection + + NMSException if thrown by NMS API methods + + + Create a new NMS ISession for registration with a MessageResourceHolder. + the NMS Connection to create a ISession for + + the new NMS Session + + NMSException if thrown by NMS API methods + + + + Return whether to allow for a local NMS transaction that is synchronized with + a Spring-managed transaction (where the main transaction might be a ADO.NET-based + one for a specific IDbProvider, for example), with the NMS transaction + committing right after the main transaction. + Returns whether to allow for synchronizing a local NMS transaction + + + + + Callback for resource cleanup at the end of a non-native NMS transaction + + + + + Extension of the ConnectionFactory interface, + indicating how to release Connections obtained from it. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Shoulds we stop the connection, obtained from this ConnectionFactory? + + The connection to check. + wheter a stop call is necessary + + + Connection holder, wrapping a NMS Connection and a NMS Session. + MessageTransactionManager binds instances of this class to the thread, + for a given NMS ConnectionFactory. + +

Note: This is an SPI class, not intended to be used by applications.

+ + + Juergen Hoeller + Mark Pollack (.NET) + + + Create a new MessageResourceHolder that is open for resources to be added. + + + + Initializes a new instance of the class + at is open for resources to be added. + + The connection factory that this + resource holder is associated with (may be null) + + + + + Initializes a new instance of the class for the + given Session. + + The session. + + + Create a new MessageResourceHolder for the given NMS resources. + the NMS Connection + + the NMS Session + + + + + Initializes a new instance of the class. + + The connection factory. + The connection. + The session. + + + + Adds the connection to the list of resources managed by this holder. + + The connection. + + + + Adds the session to the list of resources managed by this holder. + + The session. + + + + Adds the session and connection to the list of resources managed by this holder. + + The session. + The connection. + + + + Gets the connection managed by this resource holder + + A Connection, or null if no managed connection. + + + + Gets the connection of a given type managed by this resource holder. This is used + when storing Queue or Topic Connections (from the older 1.0.2 API) as compared to the + 'unified domain' API , just Connection, in the newer 1.2 API. + + Type of the connection. + The connection, or null if not found. + + + + Gets the first session manged by this holder or null if not available. + + The session or null if not available. + + + + Gets the session managed by this holder by type. + + Type of the session. + The session or null if not available. + + + + Gets the session of a given type associated with the given connection + + Type of the session. + The connection. + The sessin or null if not available. + + + + Commits all sessions. + + + + + Closes all sessions then stops and closes all connections, in that order. + + + + + Determines whether the holder contains the specified session. + + The session. + + true if the holder contains the specified session; otherwise, false. + + + + + Gets a value indicating whether this is frozen, namely that + additional resources can be registered with the holder. If using any of the constructors with + a Session, the holder will be set to the frozen state. + + true if frozen; otherwise, false. + + + + A implementation + for a single NMS ConnectionFactory. Binds a + Connection/Session pair from the specified ConnecctionFactory to the thread, + potentially allowing for one thread-bound Session per ConnectionFactory. + + + + Application code is required to retrieve the transactional Session via + . Spring's + will autodetect a thread-bound Session and + automatically participate in it. + + + The use of as a target for this + transaction manager is strongly recommended. CachingConnectionFactory + uses a single NMS Connection for all NMS access in order to avoid the overhead + of repeated Connection creation, as well as maintaining a cache of Sessions. + Each transaction will then share the same NMS Connection, while still using + its own individual NMS Session. + + The use of a raw target ConnectionFactory would not only be inefficient + because of the lack of resource reuse. It might also lead to strange effects + when your NMS provider doesn't accept MessageProducer.close() calls + and/or MessageConsumer.close() calls before Session.commit(), + with the latter supposed to commit all the messages that have been sent through the + producer handle and received through the consumer handle. As a safe general solution, + always pass in a into this transaction manager's + ConnectionFactory property. + + + Transaction synchronization is turned off by default, as this manager might be used + alongside an IDbProvider based Spring transaction manager such as the + AdoPlatformTransactionManager, which has stronger needs for synchronization. + + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + The ConnectionFactory has to be set before using the instance. + This constructor can be used to prepare a NmsTemplate via a ApplicationContext, + typically setting the ConnectionFactory via ConnectionFactory property. + + Turns off transaction synchronization by default, as this manager might + be used alongside a dbprovider-based Spring transaction manager like + AdoPlatformTransactionManager, which has stronger needs for synchronization. + Only one manager is allowed to drive synchronization at any point of time. + + + + + + Initializes a new instance of the class + given a ConnectionFactory. + + The connection factory to obtain connections from. + + + + Make sure the ConnectionFactory has been set. + + + + + Get the MessageTransactionObject. + + he MessageTransactionObject. + + + + Begin a new transaction with the given transaction definition. + + Transaction object returned by + . + instance, describing + propagation behavior, isolation level, timeout etc. + + Does not have to care about applying the propagation behavior, + as this has already been handled by this abstract manager. + + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + Transaction object returned by + . + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + Transaction synchronization will already have been suspended. + + + in case of system errors. + + + + + Resume the resources of the current transaction. + + Transaction object returned by + . + The object that holds suspended resources as returned by + . + Transaction synchronization will be resumed afterwards. + + + In the case of system errors. + + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + + In the case of system errors. + + + + + Perform an actual rollback on the given transaction. + + The status representation of the transaction. + + In the case of system errors. + + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + The status representation of the transaction. + + In the case of system errors. + + + + + Cleanup resources after transaction completion. + + Transaction object returned by + . + + + Called after + and + + execution on any outcome. + + + + + + Check if the given transaction object indicates an existing transaction + (that is, a transaction which has already started). + + Transaction object returned by + . + + True if there is an existing transaction. + + + In the case of system errors. + + + + + Creates the connection via thie manager's ConnectionFactory. + + The new Connection + If thrown by underlying messaging APIs + + + + Creates the session for the given Connection + + The connection to create a Session for. + the new Session + If thrown by underlying messaging APIs + + + + Gets or sets the connection factory that this instance should manage transaction. + for. + + The connection factory. + + + + Gets the resource factory that this transaction manager operates on, + In tihs case the ConnectionFactory + + The ConnectionFactory. + + + + NMS Transaction object, representing a MessageResourceHolder. + Used as transaction object by MessageTransactionManager + + + + + Add information to show this is a shared NMS connection + + Description of connection wrapper + + + Exception thrown when a synchronized local transaction failed to complete + (after the main transaction has already completed). + + Jergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the SynchedLocalTransactionFailedException class. with the specified message. + + + A message about the exception. + + + + + Creates a new instance of the SynchedLocalTransactionFailedException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Initializes a new instance of the class. + + The SerializationInfo that holds the serialized object data about the exception being thrown. + The StreamingContext that contains contextual information about the source or destination. + + + Creates a NMS message given a Session + +

The Session typically is provided by an instance + of the MessageTemplate class.

+ + Mark Pollack + + + Create a Message to be sent. + the NMS Session to be used to create the + IMessage (never null) + + the Message to be sent + + NMSException if thrown by NMS API methods + + + + Interfaced based approach to listen to messaging events. + + + + + Called when a message is delivered. + + The message. + + + To be used with NmsTemplate's send method that + convert an object to a message. + + + It allows for further modification of the message after it has been processed + by the converter. This is useful for setting of NMS Header and Properties. + + Mark Pollack + + + Apply a IMessagePostProcessor to the message. The returned message is + typically a modified version of the original. + + the NMS message from the IMessageConverter + + the modified version of the Message + + NMSException if thrown by NMS API methods + + + + Specifies a basic set of NMS operations. + + +

Implemented by NmsTemplate. Not often used but a useful option + to enhance testability, as it can easily be mocked or stubbed.

+

Provides NmsTemplate's + send(..) and + receive(..) methods that mirror various NMS API methods. + See the NMS specification and NMS API docs for details on those methods. +

+ + Mark Pollack + Juergen Hoeller + Mark Pollack (.NET) + + + + Execute the action specified by the given action object within + a NMS Session. + + callback object that exposes the session + + the result object from working with the session + + NMSException if there is any problem + + + + Execute the action specified by the given action object within + a NMS Session. + + delegate that exposes the session + + the result object from working with the session + + NMSException if there is any problem + + + Send a message to a NMS destination. The callback gives access to + the NMS session and MessageProducer in order to do more complex + send operations. + + delegate that exposes the session/producer pair + + the result object from working with the session + + NMSException if there is any problem + + + Send a message to a NMS destination. The callback gives access to + the NMS session and MessageProducer in order to do more complex + send operations. + + callback object that exposes the session/producer pair + + the result object from working with the session + + NMSException if there is any problem + + + Send a message to the default destination. +

This will only work with a default destination specified!

+ + callback to create a message + + NMSException if there is any problem + + + Send a message to the specified destination. + The IMessageCreator callback creates the message given a Session. + + the destination to send this message to + + callback to create a message + + NMSException if there is any problem + + + Send a message to the specified destination. + The IMessageCreator callback creates the message given a Session. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + callback to create a message + + NMSException if there is any problem + + + Send a message to the default destination. +

This will only work with a default destination specified!

+ + delegate callback to create a message + + NMSException if there is any problem + + + Send a message to the specified destination. + The IMessageCreator callback creates the message given a Session. + + the destination to send this message to + + delegate callback to create a message + + NMSException if there is any problem + + + Send a message to the specified destination. + The IMessageCreator callback creates the message given a Session. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + delegate callback to create a message + + NMSException if there is any problem + + + Send the given object to the default destination, converting the object + to a NMS message with a configured IMessageConverter. +

This will only work with a default destination specified!

+ + the object to convert to a message + + NMSException if there is any problem + + + Send the given object to the specified destination, converting the object + to a NMS message with a configured IMessageConverter. + + the destination to send this message to + + the object to convert to a message + + NMSException if there is any problem + + + Send the given object to the specified destination, converting the object + to a NMS message with a configured IMessageConverter. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the object to convert to a message + + NMSException if there is any problem + + + Send the given object to the default destination, converting the object + to a NMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. +

This will only work with a default destination specified!

+ + the object to convert to a message + + the callback to modify the message + + NMSException if there is any problem + + + Send the given object to the specified destination, converting the object + to a NMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the destination to send this message to + + the object to convert to a message + + the callback to modify the message + + NMSException if there is any problem + + + Send the given object to the specified destination, converting the object + to a NMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the object to convert to a message. + + the callback to modify the message + + NMSException if there is any problem + + + + Send the given object to the default destination, converting the object + to a NMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. +

This will only work with a default destination specified!

+ + the object to convert to a message + the callback to modify the message + NMSException if there is any problem + + + + Send the given object to the specified destination, converting the object + to a NMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the destination to send this message to + the object to convert to a message + the callback to modify the message + NMSException if there is any problem + + + + Send the given object to the specified destination, converting the object + to a NMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + the object to convert to a message. + the callback to modify the message + NMSException if there is any problem + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the message received by the consumer, or null if the timeout expires + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the message received by the consumer, or null if the timeout expires + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the message received by the consumer, or null if the timeout expires + + NMSException if there is any problem + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the NMS message selector expression (or null if none). + See the NMS specification for a detailed definition of selector expressions. + + the message received by the consumer, or null if the timeout expires + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the NMS message selector expression (or null if none). + See the NMS specification for a detailed definition of selector expressions. + + the message received by the consumer, or null if the timeout expires + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the NMS message selector expression (or null if none). + See the NMS specification for a detailed definition of selector expressions. + + the message received by the consumer, or null if the timeout expires + + NMSException if there is any problem + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the message produced for the consumer or null if the timeout expires. + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the message produced for the consumer or null if the timeout expires. + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the message produced for the consumer or null if the timeout expires. + + NMSException if there is any problem + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the NMS message selector expression (or null if none). + See the NMS specification for a detailed definition of selector expressions. + + the message produced for the consumer or null if the timeout expires. + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the NMS message selector expression (or null if none). + See the NMS specification for a detailed definition of selector expressions. + + the message produced for the consumer or null if the timeout expires. + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the NMS message selector expression (or null if none). + See the NMS specification for a detailed definition of selector expressions. + + the message produced for the consumer or null if the timeout expires. + + NMSException if there is any problem + + + Callback for sending a message to a NMS destination. + +

To be used with the MessageTemplate.Execute(IProducerCallback) + method, often implemented as an anonymous inner class.

+ +

The typical implementation will perform multiple operations on the + supplied NMS Session and MessageProducer.

+ + Mark Pollack + + + Perform operations on the given Session and MessageProducer. + The message producer is not associated with any destination. + + the NMS Session object to use + + the NMS MessageProducer object to use + + a result object from working with the Session, if any (can be null) + + + + Callback for executing any number of operations on a provided + Session + + + To be used with the NmsTemplate.Execute(ISessionCallback)} + method. See for the equivalent callback + that can be used as a (anonymous) delegate. + + Mark Pollack + + + + + Execute any number of operations against the supplied NMS + Session, possibly returning a result. + + the NMS Session + + a result object from working with the Session, if any (so can be null) + + NMSException if there is any problem + + + + Delegate that creates a NMS message given a ISession + + the NMS Session to be used to create the + Message (never null) + + the Message to be sent + + NMSException if thrown by NMS API methods + + + + Delegate that is used with NmsTemplate's ConvertAndSend method that converts + an object. + + + It allows for further modification of the message after it has been processed + by the converter. This is useful for setting of NMS Header and Properties. + + Mark Pollack + + + + Convenient super class for application classes that need NMS access. + + + Requires a ConnectionFactory or a NmsTemplate instance to be set. + It will create its own NmsTemplate if a ConnectionFactory is passed in. + A custom NmsTemplate instance can be created for a given ConnectionFactory + through overriding the createNmsTemplate method. + + + + + Creates a NmsTemplate for the given ConnectionFactory. + + Only invoked if populating the gateway with a ConnectionFactory reference. + Can be overridden in subclasses to provide a different NmsTemplate instance + + + The connection factory. + + + + + Ensures that the JmsTemplate is specified and calls . + + + + + Subclasses can override this for custom initialization behavior. + Gets called after population of this instance's properties. + + + + + Gets or sets the NMS template for the gateway. + + The NMS template. + + + + Gets or sets he NMS connection factory to be used by the gateway. + Will automatically create a NmsTemplate for the given ConnectionFactory. + + The connection factory. + + + Helper class that simplifies NMS access code. + + If you want to use dynamic destination creation, you must specify + the type of NMS destination to create, using the "pubSubDomain" property. + For other operations, this is not necessary. + Point-to-Point (Queues) is the default domain. + + Default settings for NMS Sessions is "auto-acknowledge". + + This template uses a DynamicDestinationResolver and a SimpleMessageConverter + as default strategies for resolving a destination name or converting a message, + respectively. + + + Mark Pollack + Juergen Hoeller + Mark Pollack (.NET) + + + Base class for NmsTemplate} and other + NMS-accessing gateway helpers, adding destination-related properties to + MessagingAccessor's common properties. + + +

Not intended to be used directly. See NmsTemplate.

+ + + Juergen Hoeller + Mark Pollack (.NET) + + + Base class for NmsTemplate and other NMS-accessing gateway helpers + It defines common properties like the ConnectionFactory}. The subclass + NmsIDestinationAccessor adds further, destination-related properties. + + Not intended to be used directly. See NmsTemplate. + + + Juergen Hoeller + Mark Pollack (.NET) + + + + Verify that ConnectionFactory property has been set. + + + + + Creates the connection via the ConnectionFactory. + + + + + + Creates the session for the given Connection + + The connection to create a session for. + The new session + + + + Returns whether the ISession is in client acknowledgement mode. + + The session to check. + true if in client ack mode, false otherwise + + + + Gets or sets the connection factory to use for obtaining NMS Connections. + + The connection factory. + + + + Gets or sets the session acknowledge mode for NMS Sessions including whether or not the session is transacted + + + Set the NMS acknowledgement mode that is used when creating a NMS + Session to send a message. The default is AUTO_ACKNOWLEDGE. + + The session acknowledge mode. + + + + Set the transaction mode that is used when creating a NMS Session. + Default is "false". + + + Setting this flag to "true" will use a short local NMS transaction + when running outside of a managed transaction, and a synchronized local + NMS transaction in case of a managed transaction being present. + The latter has the effect of a local NMS + transaction being managed alongside the main transaction (which might + be a native ADO.NET transaction), with the NMS transaction committing + right after the main transaction. + + + + + + Resolves the given destination name to a NMS destination. + + The current session. + Name of the destination. + The located IDestination + If resolution failed. + + + + Gets or sets the destination resolver that is to be used to resolve + IDestination references for this accessor. + + The default resolver is a DynamicDestinationResolver. Specify a + JndiDestinationResolver for resolving destination names as JNDI locations. + + The destination resolver. + + + + Gets or sets a value indicating whether Publish/Subscribe + domain (Topics) is used. Otherwise, the Point-to-Point domain + (Queues) is used. + + + this + setting tells what type of destination to create if dynamic destinations are enabled. + true if Publish/Subscribe domain; otherwise, false + for the Point-to-Point domain. + + + + Timeout value indicating that a receive operation should + check if a message is immediately available without blocking. + + + + + Timeout value indicating a blocking receive without timeout. + + + + Create a new NmsTemplate. + + Note: The ConnectionFactory has to be set before using the instance. + This constructor can be used to prepare a NmsTemplate via an ObjectFactory, + typically setting the ConnectionFactory. + + + + Create a new NmsTemplate, given a ConnectionFactory. + the ConnectionFactory to obtain IConnections from + + + + Initialize the default implementations for the template's strategies: + DynamicDestinationResolver and SimpleMessageConverter. + + + + Execute the action specified by the given action object within a + NMS Session. + + Generalized version of execute(ISessionCallback), + allowing the NMS Connection to be started on the fly. +

Use execute(ISessionCallback) for the general case. + Starting the NMS Connection is just necessary for receiving messages, + which is preferably achieved through the receive methods.

+ + callback object that exposes the session + + Start the connection before performing callback action. + + the result object from working with the session + + NMSException if there is any problem + + + + Extract the content from the given JMS message. + + The Message to convert (can be null). + The content of the message, or null if none + + + Fetch an appropriate Connection from the given MessageResourceHolder. + + the MessageResourceHolder + + an appropriate IConnection fetched from the holder, + or null if none found + + + + Fetch an appropriate Session from the given MessageResourceHolder. + + the MessageResourceHolder + + an appropriate ISession fetched from the holder, + or null if none found + + + + Create a NMS MessageProducer for the given Session and Destination, + configuring it to disable message ids and/or timestamps (if necessary). +

Delegates to doCreateProducer for creation of the raw + NMS MessageProducer

+ + the NMS Session to create a MessageProducer for + + the NMS Destination to create a MessageProducer for + + the new NMS MessageProducer + + NMSException if thrown by NMS API methods + + + + + + + + + + Determines whether the given Session is locally transacted, that is, whether + its transaction is managed by this template class's Session handling + and not by an external transaction coordinator. + + + The Session's own transacted flag will already have been checked + before. This method is about finding out whether the Session's transaction + is local or externally coordinated. + + The session to check. + + true if the session is locally transacted; otherwise, false. + + + + Create a raw NMS MessageProducer for the given Session and Destination. + + the NMS Session to create a MessageProducer for + + the NMS IDestination to create a MessageProducer for + + the new NMS MessageProducer + + NMSException if thrown by NMS API methods + + + Create a NMS MessageConsumer for the given Session and Destination. + + the NMS Session to create a MessageConsumer for + + the NMS Destination to create a MessageConsumer for + + the message selector for this consumer (can be null) + + the new NMS IMessageConsumer + + NMSException if thrown by NMS API methods + + + + Send the given message. + + The session to operate on. + The destination to send to. + The message creator delegate callback to create a Message. + + + + Send the given message. + + The session to operate on. + The destination to send to. + The message creator callback to create a Message. + + + Send the given NMS message. + the NMS Session to operate on + + the NMS Destination to send to + + callback to create a NMS Message + + delegate callback to create a NMS Message + + NMSException if thrown by NMS API methods + + + Actually send the given NMS message. + the NMS MessageProducer to send with + + the NMS Message to send + + NMSException if thrown by NMS API methods + + + + Execute the action specified by the given action object within + a NMS Session. + + delegate that exposes the session + + the result object from working with the session + + + Note that the value of PubSubDomain affects the behavior of this method. + If PubSubDomain equals true, then a Session is passed to the callback. + If false, then a ISession is passed to the callback.b + + NMSException if there is any problem + + + Execute the action specified by the given action object within + a NMS Session. +

Note: The value of PubSubDomain affects the behavior of this method. + If PubSubDomain equals true, then a Session is passed to the callback. + If false, then a Session is passed to the callback.

+ + callback object that exposes the session + + the result object from working with the session + + NMSException if there is any problem + + + Send a message to a NMS destination. The callback gives access to + the NMS session and MessageProducer in order to do more complex + send operations. + + callback object that exposes the session/producer pair + + the result object from working with the session + + NMSException if there is any problem + + + Send a message to a NMS destination. The callback gives access to + the NMS session and MessageProducer in order to do more complex + send operations. + + delegate that exposes the session/producer pair + + the result object from working with the session + + NMSException if there is any problem + + + Send a message to the default destination. +

This will only work with a default destination specified!

+ + delegate callback to create a message + + NMSException if there is any problem + + + Send a message to the specified destination. + The MessageCreator callback creates the message given a Session. + + the destination to send this message to + + delegate callback to create a message + + NMSException if there is any problem + + + Send a message to the specified destination. + The MessageCreator callback creates the message given a Session. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + delegate callback to create a message + + NMSException if there is any problem + + + Send a message to the default destination. +

This will only work with a default destination specified!

+ + callback to create a message + + NMSException if there is any problem + + + Send a message to the specified destination. + The MessageCreator callback creates the message given a Session. + + the destination to send this message to + + callback to create a message + + NMSException if there is any problem + + + Send a message to the specified destination. + The MessageCreator callback creates the message given a Session. + + the destination to send this message to + + callback to create a message + + NMSException if there is any problem + + + Send the given object to the default destination, converting the object + to a NMS message with a configured IMessageConverter. +

This will only work with a default destination specified!

+ + the object to convert to a message + + NMSException if there is any problem + + + Send the given object to the specified destination, converting the object + to a NMS message with a configured IMessageConverter. + + the destination to send this message to + + the object to convert to a message + + NMSException if there is any problem + + + Send the given object to the specified destination, converting the object + to a NMS message with a configured IMessageConverter. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the object to convert to a message + + NMSException if there is any problem + + + Send the given object to the default destination, converting the object + to a NMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. +

This will only work with a default destination specified!

+ + the object to convert to a message + + the callback to modify the message + + NMSException if there is any problem + + + Send the given object to the specified destination, converting the object + to a NMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the destination to send this message to + + the object to convert to a message + + the callback to modify the message + + NMSException if there is any problem + + + Send the given object to the specified destination, converting the object + to a NMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the object to convert to a message. + + the callback to modify the message + + NMSException if there is any problem + + + + Send the given object to the default destination, converting the object + to a NMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. +

This will only work with a default destination specified!

+ + the object to convert to a message + the callback to modify the message + NMSException if there is any problem + + + + Send the given object to the specified destination, converting the object + to a NMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the destination to send this message to + the object to convert to a message + the callback to modify the message + NMSException if there is any problem + + + + Send the given object to the specified destination, converting the object + to a NMS message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. + + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + the object to convert to a message. + the callback to modify the message + NMSException if there is any problem + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the message received by the consumer, or null if the timeout expires + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the message received by the consumer, or null if the timeout expires + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the message received by the consumer, or null if the timeout expires + + NMSException if there is any problem + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the NMS message selector expression (or null if none). + See the NMS specification for a detailed definition of selector expressions. + + the message received by the consumer, or null if the timeout expires + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the NMS message selector expression (or null if none). + See the NMS specification for a detailed definition of selector expressions. + + the message received by the consumer, or null if the timeout expires + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the NMS message selector expression (or null if none). + See the NMS specification for a detailed definition of selector expressions. + + the message received by the consumer, or null if the timeout expires + + NMSException if there is any problem + + + + Receive a message. + + The session to operate on. + The destination to receive from. + The message selector for this consumer (can be null + The Message received, or null if none. + + + + Receive a message. + + The session to operate on. + The consumer to receive with. + The Message received, or null if none + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the message produced for the consumer or null if the timeout expires. + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the message produced for the consumer or null if the timeout expires. + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the message produced for the consumer or null if the timeout expires. + + NMSException if there is any problem + + + Receive a message synchronously from the default destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+

This will only work with a default destination specified!

+ + the NMS message selector expression (or null if none). + See the NMS specification for a detailed definition of selector expressions. + + the message produced for the consumer or null if the timeout expires. + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the destination to receive a message from + + the NMS message selector expression (or null if none). + See the NMS specification for a detailed definition of selector expressions. + + the message produced for the consumer or null if the timeout expires. + + NMSException if there is any problem + + + Receive a message synchronously from the specified destination, but only + wait up to a specified time for delivery. Convert the message into an + object with a configured IMessageConverter. +

This method should be used carefully, since it will block the thread + until the message becomes available or until the timeout value is exceeded.

+ + the name of the destination to send this message to + (to be resolved to an actual destination by a DestinationResolver) + + the NMS message selector expression (or null if none). + See the NMS specification for a detailed definition of selector expressions. + + the message produced for the consumer or null if the timeout expires. + + NMSException if there is any problem + + + + Gets or sets the default destination to be used on send/receive operations that do not + have a destination parameter. + + Alternatively, specify a "defaultDestinationName", to be + dynamically resolved via the DestinationResolver. + The default destination. + + + + Gets or sets the name of the default destination name + to be used on send/receive operations that + do not have a destination parameter. + + + Alternatively, specify a NMS IDestination object as "DefaultDestination" + + The name of the default destination. + + + + Gets or sets the message converter for this template. + + + Used to resolve + Object parameters to convertAndSend methods and Object results + from receiveAndConvert methods. +

The default converter is a SimpleMessageConverter, which is able + to handle IBytesMessages, ITextMessages and IObjectMessages.

+ + The message converter. + + + + Gets or sets a value indicating whether Message Ids are enabled. + + true if message id enabled; otherwise, false. + + + + Gets or sets a value indicating whether message timestamps are enabled. + + + true if [message timestamp enabled]; otherwise, false. + + + + + Gets or sets a value indicating whether to inhibit the delivery of messages published by its own connection. + + + true if inhibit the delivery of messages published by its own connection; otherwise, false. + + + + Gets or sets the receive timeout to use for recieve calls (in milliseconds) + + The default is -1, which means no timeout. + The receive timeout. + + + + Gets or sets a value indicating whether to use explicit Quality of Service values. + + If "true", then the values of deliveryMode, priority, and timeToLive + will be used when sending a message. Otherwise, the default values, + that may be set administratively, will be used + true if use explicit QoS values; otherwise, false. + + + + Sets a value indicating whether message delivery should be persistent or non-persistent + + + This will set the delivery to persistent or non-persistent +

Default it "true" aka delivery mode "PERSISTENT".

+ + true if [delivery persistent]; otherwise, false. + + + + Gets or sets a value indicating what DeliveryMode this + should use, for example a persistent QOS + + + + + + Gets or sets the priority when sending. + + Since a default value may be defined administratively, + this is only used when "isExplicitQosEnabled" equals "true". + The priority. + + + + Gets or sets the time to live when sending + + Since a default value may be defined administratively, + this is only used when "isExplicitQosEnabled" equals "true". + The time to live. + + + + ResourceFactory implementation that delegates to this template's callback methods. + + + + + Implemention of NMS ITrace interface that will log NMS messages to Common.Logging. + + Registering of this class is done by default in NmsTemplate and SimpleMessageListenerContainer if the value + of Apache.NMS.Tracer.Trace is null, indicating it was not set. + + Mark Pollack + + + + Initializes a new instance of the class. The log name used is typeof(NmsTrace). + + + + + Initializes a new instance of the class. + + The log instance to use for logging. + + + + Logs message at Debug Level. + + The message. + + + + Logs message at Info Level. + + The message. + + + + Logs message at Warn Level. + + The message. + + + + Logs message at Error Level. + + The message. + + + + Logs message at Fatal Level. + + The message. + + + + Gets a value indicating whether the debug log level is enabled. + + + true if this instance is debug enabled; otherwise, false. + + + + + Gets a value indicating whether the info log level is enabled. + + + true if this instance is info enabled; otherwise, false. + + + + + Gets a value indicating whether the warn log level is enabled. + + + true if this instance is warn enabled; otherwise, false. + + + + + Gets a value indicating whether the error log level is enabled. + + + true if this instance is error enabled; otherwise, false. + + + + + Gets a value indicating whether the fatal log level is enabled. + + + true if this instance is fatal enabled; otherwise, false. + + + + Perform operations on the given Session and MessageProducer. + The message producer is not associated with any destination. + + the NMS Session object to use + + the NMS MessageProducer object to use + + a result object from working with the Session, if any (can be null) + + + + + Callback delegate for code that operates on a Session. + + The NMS ISession object. + + Allows you to execute any number of operations + on a single ISession, possibly returning a result a result. + + + A result object from working with the Session, if any (so can be null) + + NMSException if there is any problem + Mark Pollack + + + + Exception to be thrown when the execution of a listener method failed. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class, with the specified message + + The message. + + + + Initializes a new instance of the class, with the specified message + and root cause exception + + The message. + The inner exception. + + + + Initializes a new instance of the class. + + The SerializationInfo that holds the serialized object data about the exception being thrown. + The StreamingContext that contains contextual information about the source or destination. + + + + Message listener adapter that delegates the handling of messages to target + listener methods via reflection, with flexible message type conversion. + Allows listener methods to operate on message content types, completely + independent from the NMS API. + + + By default, the content of incoming messages gets extracted before + being passed into the target listener method, to let the target method + operate on message content types such as String or byte array instead of + the raw Message. Message type conversion is delegated to a Spring + . By default, a + will be used. (If you do not want such automatic message conversion taking + place, then be sure to set the property + to null.) + + If a target listener method returns a non-null object (typically of a + message content type such as String or byte array), it will get + wrapped in a NMS Message and sent to the response destination + (either the NMS "reply-to" destination or the + specified. + + + The sending of response messages is only available when + using the entry point (typically through a + Spring message listener container). Usage as standard NMS MessageListener + does not support the generation of response messages. + + Consult the reference documentation for examples of method signatures compliant with this + adapter class. + + + Juergen Hoeller + Mark Pollack (.NET) + + + + Variant of the standard NMS MessageListener interface, + offering not only the received Message but also the underlying + Session object. The latter can be used to send reply messages, + without the need to access an external Connection/Session, + i.e. without the need to access the underlying ConnectionFactory. + + + Supported by Spring's + as direct alternative to the standard MessageListener interface. + + Juergen Hoeller + Mark Pollack (.NET) + + + Callback for processing a received NMS message. + Implementors are supposed to process the given Message, + typically sending reply messages through the given Session. + + the received NMS message + + the underlying NMS Session + + NMSException if thrown by NMS methods + + + + The default handler method name. + + + + + Initializes a new instance of the class with default settings. + + + + + Initializes a new instance of the class for the given handler object + + The delegate object. + + + + Standard JMS {@link MessageListener} entry point. + Delegates the message to the target listener method, with appropriate + conversion of the message arguments + + + + In case of an exception, the method will be invoked. + Note + Does not support sending response messages based on + result objects returned from listener methods. Use the + entry point (typically through a Spring + message listener container) for handling result objects as well. + + The incoming message. + + + + Spring entry point. + + Delegates the message to the target listener method, with appropriate + conversion of the message argument. If the target method returns a + non-null object, wrap in a NMS message and send it back. + + + The incoming message. + The session to operate on. + + + + Initialize the default implementations for the adapter's strategies. + + + + + Handle the given exception that arose during listener execution. + The default implementation logs the exception at error level. + This method only applies when used as standard NMS MessageListener. + In case of the Spring mechanism, + exceptions get handled by the caller instead. + + + The exception to handle. + + + + Extract the message body from the given message. + + The message. + the content of the message, to be passed into the + listener method as argument + if thrown by NMS API methods + + + + Gets the name of the listener method that is supposed to + handle the given message. + The default implementation simply returns the configured + default listener method, if any. + + The NMS request message. + The converted JMS request message, + to be passed into the listener method as argument. + the name of the listener method (never null) + if thrown by NMS API methods + + + + Handles the given result object returned from the listener method, sending a response message back. + + The result object to handle (never null). + The original request message. + The session to operate on (may be null). + + + + Builds a JMS message to be sent as response based on the given result object. + + The JMS Session to operate on. + The content of the message, as returned from the listener method. + the JMS Message (never null) + If there was an error in message conversion + if thrown by NMS API methods + + + + Post-process the given response message before it will be sent. The default implementation + sets the response's correlation id to the request message's correlation id. + + The original incoming message. + The outgoing JMS message about to be sent. + if thrown by NMS API methods + + + + Determine a response destination for the given message. + + + The default implementation first checks the JMS Reply-To + Destination of the supplied request; if that is not null + it is returned; if it is null, then the configured + default response destination + is returned; if this too is null, then an + is thrown. + + + The original incoming message. + Tthe outgoing message about to be sent. + The session to operate on. + the response destination (never null) + if thrown by NMS API methods + if no destination can be determined. + + + + Resolves the default response destination into a Destination, using this + accessor's in case of a destination name. + + The session to operate on. + The located destination + + + + Sends the given response message to the given destination. + + The session to operate on. + The destination to send to. + The outgoing message about to be sent. + + + + Post-process the given message producer before using it to send the response. + The default implementation is empty. + + The producer that will be used to send the message. + The outgoing message about to be sent. + + + + Gets or sets the handler object to delegate message listening to. + + + Specified listener methods have to be present on this target object. + If no explicit handler object has been specified, listener + methods are expected to present on this adapter instance, that is, + on a custom subclass of this adapter, defining listener methods. + + The handler object. + + + + Gets or sets the default handler method to delegate to, + for the case where no specific listener method has been determined. + Out-of-the-box value is ("HandleMessage"}. + + The default handler method. + + + + Sets the default destination to send response messages to. This will be applied + in case of a request message that does not carry a "JMSReplyTo" field. + Response destinations are only relevant for listener methods that return + result objects, which will be wrapped in a response message and sent to a + response destination. + + Alternatively, specify a "DefaultResponseQueueName" or "DefaultResponseTopicName", + to be dynamically resolved via the DestinationResolver. + + + The default response destination. + + + + Sets the name of the default response queue to send response messages to. + This will be applied in case of a request message that does not carry a + "NMSReplyTo" field. + Alternatively, specify a JMS Destination object as "defaultResponseDestination". + + The name of the default response destination queue. + + + + Sets the name of the default response topic to send response messages to. + This will be applied in case of a request message that does not carry a + "NMSReplyTo" field. + Alternatively, specify a JMS Destination object as "defaultResponseDestination". + + The name of the default response destination topic. + + + + Gets or sets the destination resolver that should be used to resolve response + destination names for this adapter. + The default resolver is a . + Specify another implementation, for other strategies, perhaps from a directory service. + + The destination resolver. + + + + Gets or sets the message converter that will convert incoming JMS messages to + listener method arguments, and objects returned from listener + methods back to NMS messages. + + + The default converter is a {@link SimpleMessageConverter}, which is able + to handle BytesMessages}, TextMessages, MapMessages, and ObjectMessages. + + + The message converter. + + + + Internal class combining a destination name and its target destination type (queue or topic). + + + + + Common base class for all containers which need to implement listening + based on a Connection (either shared or freshly obtained for each attempt). + Inherits basic Connection and Session configuration handling from the + base class. + + + + This class provides basic lifecycle management, in particular management + of a shared Connection. Subclasses are supposed to plug into this + lifecycle, implementing the as well as + + + Juergen Hoeller + Mark Pollack(.NET) + + + + The monitor object to lock on when performing operations on the connection. + + + + + The monitor object to lock on when performing operations that update the lifecycle of the container. + + + + + Call base class method, then and then + + + + + Validates the configuration of this container. The default implementation + is empty. To be overriden in subclasses. + + + + + Calls when the application context destroys the container instance. + + + + + Initializes this container. Creates a Connection, starts the Connection + (if the property hasn't been turned off), and calls + . + + If startup failed + + + + Stop the shared connection, call , and close this container. + + + + + Starts this container. + + if starting failed. + + + + Start the shared Connection, if any, and notify all invoker tasks. + + + + + Stops this container. + + if stopping failed. + + + + Notify all invoker tasks and stop the shared Connection, if any. + + if thrown by NMS API methods. + + + + + Register any invokers within this container. + Subclasses need to implement this method for their specific + invoker management process. A shared Connection, if any, will already have been + started at this point. + + + + + Close the registered invokers. Subclasses need to implement this method + for their specific invoker management process. A shared Connection, if any, + will automatically be closed afterwards. + + + + + Establishes a shared Connection for this container. + + + + The default implementation delegates to + which does one immediate attempt and throws an exception if it fails. + Can be overridden to have a recovery process in place, retrying + until a Connection can be successfully established. + + + If thrown by NMS API methods + + + + Refreshes the shared connection that this container holds. + + + Called on startup and also after an infrastructure exception + that occurred during invoker setup and/or execution. + + If thrown by NMS API methods + + + + Creates the shared connection for this container. + + + The default implementation creates a standard Connection + and prepares it through + + the prepared Connection + if the creation failed. + + + + Prepares the given connection, which is about to be registered + as shared Connection for this container. + + + The default implementation sets the specified client id, if any. + Subclasses can override this to apply further settings. + + The connection to prepare. + If the preparation efforts failed. + + + + Starts the shared connection. + + If thrown by NMS API methods + + + + + Stops the shared connection. + + if thrown by NMS API methods. + + + + Gets or sets the client id for a shared Connection created and used by this container. + + + Note that client ids need to be unique among all active Connections + of the underlying JMS provider. Furthermore, a client id can only be + assigned if the original ConnectionFactory hasn't already assigned one. + + The client id. + + + Set whether to automatically start the listener after initialization. +

Default is "true"; set this to "false" to allow for manual startup.

+ + + + + Set the name of the object in the object factory that created this object. + + The name of the object in the factory. + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + + + Gets a value indicating whether this container is currently running, + that is, whether it has been started and not stopped yet. + + + true if this container is running; otherwise, false. + + + + + Gets a value indicating whether this container's listeners are generally allowed to run. + + + + >This implementation always returns true; the default 'running' + state is purely determined by /. + + + Subclasses may override this method to check against temporary + conditions that prevent listeners from actually running. In other words, + they may apply further restrictions to the 'running' state, returning + false if such a restriction prevents listeners from running. + + + true if running allowed; otherwise, false. + + + + Gets a value indicating whether this container is currently active, + that is, whether it has been set up but not shut down yet. + + true if active; otherwise, false. + + + Return whether a shared NMS Connection should be maintained + by this listener container base class. + + + + + + Gets the shared connection maintained by this container. + Available after initialization. + + The shared connection (never null) + if this container does not maintain a + shared Connection, or if the Connection hasn't been initialized yet. + + + + + + Exception that indicates that the initial setup of this container's + shared Connection failed. This is indicating to invokers that they need + to establish the shared Connection themselves on first access. + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message. + + + + Initializes a new instance of the class, with the specified message + and root cause exception + + The message. + The inner exception. + + + + Initializes a new instance of the class. + + The SerializationInfo that holds the serialized object data about the exception being thrown. + The StreamingContext that contains contextual information about the source or destination. + + + + Abstract base class for message listener containers. Can either host + a standard NMS MessageListener or a Spring-specific + + + + + + Validate that the destination is not null and that if the subscription is durable, then we are not + using the Pub/Sub domain. + + + + + Executes the specified listener, + committing or rolling back the transaction afterwards (if necessary). + + The session to operate on. + The received message. + + + + + + + + Executes the specified listener, + committing or rolling back the transaction afterwards (if necessary). + + The session to operate on. + The received message. + If thrown by NMS API methods. + + + + + + + Invokes the specified listener: either as standard NMS MessageListener + or (preferably) as Spring SessionAwareMessageListener. + + The session to operate on. + The received message. + If thrown by NMS API methods. + + + + + Invoke the specified listener as Spring SessionAwareMessageListener, + exposing a new NMS Session (potentially with its own transaction) + to the listener if demanded. + + The Spring ISessionAwareMessageListener to invoke. + The session to operate on. + The received message. + If thrown by NMS API methods. + + + + + + Invoke the specified listener as standard JMS MessageListener. + + Default implementation performs a plain invocation of the + OnMessage methods + The listener to invoke. + The received message. + if thrown by the NMS API methods + + + + Perform a commit or message acknowledgement, as appropriate + + The session to commit. + The message to acknowledge. + In case of commit failure + + + + Determines whether the given Session is locally transacted, that is, whether + its transaction is managed by this listener container's Session handling + and not by an external transaction coordinator. + + + The Session's own transacted flag will already have been checked + before. This method is about finding out whether the Session's transaction + is local or externally coordinated. + + The session to check. + + true if the is session locally transacted; otherwise, false. + + + + + + Perform a rollback, if appropriate. + + The session to rollback. + In case of a rollback error + + + + Perform a rollback, handling rollback excepitons properly. + + The session to rollback. + The thrown application exception. + in case of a rollback error. + + + + Handle the given exception that arose during listener execution. + + + The default implementation logs the exception at error level, + not propagating it to the JMS provider - assuming that all handling of + acknowledgement and/or transactions is done by this listener container. + This can be overridden in subclasses. + + The exceptin to handle + + + + Invokes the error handler. + + The exception. + + + + Invokes the registered exception listener, if any. + + The exception that arose during NMS processing. + + + + + Checks the message listener, throwing an exception + if it does not correspond to a supported listener type. + By default, only a standard JMS MessageListener object or a + Spring object will be accepted. + + The message listener. + + + + Gets or sets the destination to receive messages from. Will be null + if the configured destination is not an actual Destination type; + c.f. when the destination is a String. + + The destination. + + + + Gets or sets the name of the destination to receive messages from. + Will be null if the configured destination is not a + string type; c.f. when it is an actual Destination object. + + The name of the destination. + + + + Gets or sets the message selector. + + The message selector expression (or null if none).. + + + + Gets or sets the message listener to register. + + + + + This can be either a standard NMS MessageListener object or a + Spring object. + + + The message listener. + + + + Gets or sets a value indicating whether the subscription is durable. + + + Set whether to make the subscription durable. The durable subscription name + to be used can be specified through the "DurableSubscriptionName" property. + Default is "false". Set this to "true" to register a durable subscription, + typically in combination with a "DurableSubscriptionName" value (unless + your message listener class name is good enough as subscription name). + + Only makes sense when listening to a topic (pub-sub domain). + + true if the subscription is durable; otherwise, false. + + + + Gets or sets the name of the durable subscription to create. + + + To be applied in case of a topic (pub-sub domain) with subscription durability activated. + The durable subscription name needs to be unique within this client's + client id. Default is the class name of the specified message listener. + Note: Only 1 concurrent consumer (which is the default of this + message listener container) is allowed for each durable subscription. + + + The name of the durable subscription. + + + + Gets or sets the exception listener to notify in case of a NMSException thrown + by the registered message listener or the invocation infrastructure. + + The exception listener. + + + + Sets an ErrorHandler to be invoked in case of any uncaught exceptions thrown + while processing a Message. By default there will be no ErrorHandler + so that error-level logging is the only result. + + The error handler. + + + + Gets or sets a value indicating whether to expose listener session to a registered + as well as to calls. + + + Default is "true", reusing the listener's Session. + Turn this off to expose a fresh Session fetched from the same + underlying Connection instead, which might be necessary + on some messaging providers. + Note that Sessions managed by an external transaction manager will + always get exposed to + calls. So in terms of NmsTemplate exposure, this setting only affects + locally transacted Sessions. + + + + true if expose listener session; otherwise, false. + + + + + Gets or sets a value indicating whether to accept messages while + the listener container is in the process of stopping. + + + + Return whether to accept received messages while the listener container + receive attempt. Switch this flag on to fully process such messages + even in the stopping phase, with the drawback that even newly sent + messages might still get processed (if coming in before all receive + timeouts have expired). + + + Aborting receive attempts for such incoming messages + might lead to the provider's retry count decreasing for the affected + messages. If you have a high number of concurrent consumers, make sure + that the number of retries is higher than the number of consumers, + to be on the safe side for all potential stopping scenarios. + + + + true if accept messages while in the process of stopping; otherwise, false. + + + + + Internal exception class that indicates a rejected message on shutdown. + Used to trigger a rollback for an external transaction manager in that case. + + + + + MessageResourceHolder marker subclass that indicates local exposure, + i.e. that does not indicate an externally managed transaction. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Initializes a new instance of the class. + + The session. + + + + Exception thrown when the maximum connection recovery time has been exceeded. + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class, with the specified message + + The message. + + + + Initializes a new instance of the class, with the specified message + and root cause exception + + The message. + The inner exception. + + + + Initializes a new instance of the class. + + The SerializationInfo that holds the serialized object data about the exception being thrown. + The StreamingContext that contains contextual information about the source or destination. + + + + Message listener container that uses the plain NMS client API's + MessageConsumer.Listener method to create concurrent + MessageConsumers for the specified listeners. + + Mark Pollack + + + + The default recovery time interval between connection reconnection attempts + + + + + The total time connection recovery will be attempted. + + + + + Call base class for valdation and then check that if the subscription is durable that the number of + concurrent consumers is equal to one. + + + + + Creates the specified number of concurrent consumers, + in the form of a JMS Session plus associated MessageConsumer + + + + + + Re-initializes this container's NMS message consumers, + if not initialized already. + + + + + Registers this listener container as NMS ExceptionListener on the shared connection. + + + + + + implementation, invoked by the NMS provider in + case of connection failures. Re-initializes this listener container's + shared connection and its sessions and consumers. + + The reported connection exception. + + + + Refresh the underlying Connection, not returning before an attempt has been + successful. Called in case of a shared Connection as well as without shared + Connection, so either needs to operate on the shared Connection or on a + temporary Connection that just gets established for validation purposes. + + + The default implementation retries until it successfully established a + Connection, for as long as this message listener container is active. + Applies the specified recovery interval between retries. + + + + + The amount of time to sleep in between recovery attempts. + + + + + Initialize the Sessions and MessageConsumers for this container. + + in case of setup failure. + + + + Creates a MessageConsumer for the given Session, + registering a MessageListener for the specified listener + + The session to work on. + the MessageConsumer"/> + if thrown by NMS methods + + + + Close the message consumers and sessions. + + NMSException if destruction failed + + + + Creates a MessageConsumer for the given Session and Destination. + + The session to create a MessageConsumer for. + The destination to create a MessageConsumer for. + The new MessageConsumer + + + + Gets or sets a value indicating whether to inhibit the delivery of messages published by its own connection. + Default is "false". + + true if should inhibit the delivery of messages published by its own connection; otherwise, false. + + + + Specify the number of concurrent consumers to create. Default is 1. + + + Raising the number of concurrent consumers is recommendable in order + to scale the consumption of messages coming in from a queue. However, + note that any ordering guarantees are lost once multiple consumers are + registered. In general, stick with 1 consumer for low-volume queues. + Do not raise the number of concurrent consumers for a topic. + This would lead to concurrent consumption of the same message, + which is hardly ever desirable. + + + The concurrent consumers. + + + + Sets the time interval between connection recovery attempts. The default is 5 seconds. + + The recovery interval. + + + + Sets the max recovery time to try reconnection attempts. The default is 10 minutes. + + The max recovery time. + + + + Always use a shared NMS connection + + + + Strategy interface that specifies a IMessageConverter + between .NET objects and NMS messages. + + + Mark Pollack + Juergen Hoeller + Mark Pollack (.NET) + + + Convert a .NET object to a NMS Message using the supplied session + to create the message object. + + the object to convert + + the Session to use for creating a NMS Message + + the NMS Message + + NMSException if thrown by NMS API methods + MessageConversionException in case of conversion failure + + + Convert from a NMS Message to a .NET object. + the message to convert + + the converted .NET object + + MessageConversionException in case of conversion failure + + + + Provides a layer of indirection when adding the 'type' of the object as a message property. + + Mark Pollack + + + + Convert from a type to a string. + + The type of object to convert. + + + + + Convert from a string to a type + + The type id. + + + + + Gets the name of the field in the message that has type information.. + + The name of the type id field. + + + Thrown by IMessageConverter implementations when the conversion + of an object to/from a Message fails. + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Creates a new instance of the IMessageConverterException class. with the specified message. + + + A message about the exception. + + + + + Creates a new instance of the IMessageConverterException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Initializes a new instance of the class. + + The SerializationInfo that holds the serialized object data about the exception being thrown. + The StreamingContext that contains contextual information about the source or destination. + + + A simple message converter that can handle ITextMessages, IBytesMessages, + IMapMessages, and IObjectMessages. Used as default by NmsTemplate, for + ConvertAndSend and ReceiveAndConvert operations. + +

Converts a String to a NMS ITextMessage, a byte array to a NMS IBytesMessage, + a Map to a NMS IMapMessage, and a Serializable object to a NMS IObjectMessage + (or vice versa).

+ + + + Juergen Hoeller + Mark Pollack (.NET) + + + Convert a .NET object to a NMS Message using the supplied session + to create the message object. + + the object to convert + + the Session to use for creating a NMS Message + + the NMS Message + + NMSException if thrown by NMS API methods + MessageConversionException in case of conversion failure + + + Convert from a NMS Message to a .NET object. + the message to convert + + the converted .NET object + + MessageConversionException in case of conversion failure + + + Create a NMS ITextMessage for the given String. + the String to convert + + current NMS session + + the resulting message + + NMSException if thrown by NMS methods + + + Create a NMS IBytesMessage for the given byte array. + the byyte array to convert + + current NMS session + + the resulting message + + NMSException if thrown by NMS methods + + + Create a NMS IMapMessage for the given Map. + the Map to convert + + current NMS session + + the resulting message + + NMSException if thrown by NMS methods + + + Create a NMS IObjectMessage for the given Serializable object. + the Serializable object to convert + + current NMS session + + the resulting message + + NMSException if thrown by NMS methods + + + Extract a String from the given ITextMessage. + the message to convert + + the resulting String + + NMSException if thrown by NMS methods + + + Extract a byte array from the given IBytesMessage. + the message to convert + + the resulting byte array + + NMSException if thrown by NMS methods + + + Extract a IDictionary from the given IMapMessage. + the message to convert + + the resulting Map + + NMSException if thrown by NMS methods + + + + Extracts the serializable object from the given object message. + + The message to convert. + The resulting serializable object. + + + + Provides a layer of indirection when adding the 'type' of the object as a message property. + + + + + Initializes a new instance of the [ERROR: invalid expression DeclaringTypeKind]. + + + + + Convert from a type to a string. + + The type of object to convert. + + + + + Convert from a string to a type. Will look into the IdTypeMapping dictionary first to resolve the + type, then check if it is the well known typeId of 'Hashtable' followed by a strategy to resolve a fully qualfied + name from a simple type name. This strategy requires that + + The type id. + The type associated with the string. + If the type can not be resolved. + + + + Afters the properties set. + + + + + Gets or sets the id type mapping. + + The id type mapping. + + + + Gets the name of the field in the message that has type information.. + + The name of the type id field. + + + + Sets the default hashtable class. + + The default hashtable class. + + + + Gets or sets a value indicating whether use the assembly qualified name when creating a string from a type reference. + + + By setting this property to true you will be able to easily share types that are available on both the publisher and + consumer with minimal configuration. However, this means that the publishers and subscribers would be tightly coupled + despite the use of loosely coupled messaging middleware. + + + true if to the assembly qualified name; otherwise, false. + + + + + Gets or sets the default namespace. + + The default namespace. + + + + Gets or sets the default name of the assembly. + + The default name of the assembly. + + + + Convert an object via XML serialization for sending via an ITextMessage + + Mark Pollack + + + + Convert a .NET object to a NMS Message using the supplied session + to create the message object. + + the object to convert + the Session to use for creating a NMS Message + the NMS Message + NMSException if thrown by NMS API methods + MessageConversionException in case of conversion failure + + + + Gets the XML string for an object + + The object to convert. + XML string + + + + Convert from a NMS Message to a .NET object. + + the message to convert + the converted .NET object + MessageConversionException in case of conversion failure + + + + Gets the type of the target given the message. + + The message. + Type of the target + + + + Converts a byte array to a UTF8 string. + + The characters. + UTF8 string + + + + Converts a UTF8 string to a byte array + + The p XML string. + + + + + Sets the type mapper. + + The type mapper. + + + + Gets or sets a value indicating whether encoder should emit UTF8 byte order mark. Default is false. + + + true to specify that a Unicode byte order mark is provided; otherwise, false. + + + + + Gets or sets a value indicating whether to throw an exception on invalid bytes. Default is true. + + true to specify that an exception be thrown when an invalid encoding is detected; otherwise, false. + + + + Simple DestinationResolver implementation resolving destination names + as dynamic destinations. + + Juergen Hoeller + Mark Pollack (.NET) + + + Strategy interface for resolving NMS destinations. + + + Used by MessageTemplate for resolving + destination names from simple Strings to actual + IDestination implementation instances. + + + The default DestinationResolver implementation used by + MessageTemplate instances is the + DynamicDestinationResolver class. Consider using the + JndiDestinationResolver for more advanced scenarios. + + + Juergen Hoeller + Mark Pollack (.NET) + + + Resolve the given destination name, either as located resource + or as dynamic destination. + + the current NMS Session + + the name of the destination + + true if the domain is pub-sub, false if P2P + + the NMS destination (either a topic or a queue) + + NMSException if resolution failed + + + Resolve the given destination name, either as located resource + or as dynamic destination. + + the current NMS Session + + the name of the destination + + true if the domain is pub-sub, false if P2P + + the NMS destination (either a topic or a queue) + + NMSException if resolution failed + + + Resolve the given destination name to a Topic. + the current NMS Session + + the name of the desired Topic. + + the NMS Topic name + + NMSException if resolution failed + + + Resolve the given destination name to a Queue. + the current NMS Session + + the name of the desired Queue. + + the NMS Queue name + + NMSException if resolution failed + + + + Generic utility methods for working with NMS. Mainly for internal use + within the framework, but also useful for custom NMS access code. + + + + Close the given NMS Connection and ignore any thrown exception. + This is useful for typical finally blocks in manual NMS code. + + the NMS Connection to close (may be null) + + + + Close the given NMS Connection and ignore any thrown exception. + This is useful for typical finally blocks in manual NMS code. + + the NMS Connection to close (may be null) + + whether to call stop() before closing + + + + Close the given NMS Session and ignore any thrown exception. + This is useful for typical finally blocks in manual NMS code. + + the NMS Session to close (may be null) + + + + Close the given NMS MessageProducer and ignore any thrown exception. + This is useful for typical finally blocks in manual NMS code. + + the NMS MessageProducer to close (may be null) + + + + Close the given NMS MessageConsumer and ignore any thrown exception. + This is useful for typical finally blocks in manual NMS code. + + the NMS MessageConsumer to close (may be null) + + + + Commit the Session if not within a distributed transaction. + Needs investigation - no distributed tx in .NET messaging providers + the NMS Session to commit + + NMSException if committing failed + + + Rollback the Session if not within a distributed transaction. + Needs investigation - no distributed tx in EMS + the NMS Session to rollback + + NMSException if committing failed + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Messaging.dll b/Resources/Libraries/Spring.NET/Spring.Messaging.dll new file mode 100644 index 00000000..6f42daa4 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Messaging.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Messaging.pdb b/Resources/Libraries/Spring.NET/Spring.Messaging.pdb new file mode 100644 index 00000000..38ee9b4a Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Messaging.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Messaging.xml b/Resources/Libraries/Spring.NET/Spring.Messaging.xml new file mode 100644 index 00000000..69cc921d --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Messaging.xml @@ -0,0 +1,2685 @@ + + + + Spring.Messaging + + + + + A implementation that caches MessageQueue and IMessageConverter + instances. The MessageQueue objects are created by retrieving them by-name from the + ApplicationContext. + + Mark Pollack + + + + An interface for creating MessageQueue and IMessageConverter objects from object definitions + defined in the application context. + + + MessageQueue and IMessageConverter objects have methods that are generally not thread safe, + (IMessageConverter classes rely on IMessageFormatter objects that are not thread safe). + As such, a major reason to for this interface is to provide thread-local instances such that + appliation code need not be concerned with these resource management issues. + + Mark Pollack + + + + Registers the message queue, its creation specified via the factory method + MessageQueueCreatorDelegate, with the provided name in the application context + + Name of the message queue object. + The message queue creator delegate. + + + + Creates the message queue given its name in the application context. + + Name of the message queue object. + A MessageQueue instance configured via the application context + + + + Determines whether the application context contains the message queue object definition. + + Name of the message queue object. + + true if the application context contains the specified message queue object name; otherwise, false. + + + + + Registers the message converter, its creation specified via the factory method + MessageConverterCreatorDelegate, with the provided name in the application context. + + Name of the message converter. + The message converter creator delegate. + + + + Creates the message converter given its name in the application context. + + Name of the message converter object. + A IMessageConverter instance configured via the application context + + + + Determines whether the application context contains the message queue object definition. + + Name of the message converter object. + + true if the application context contains the specified message message converter object name; otherwise, false. + + + + + The instance for this class. + + + + + Registers the message queue, its creation specified via the factory method + MessageQueueCreatorDelegate, with the provided name in the application context + + Name of the message queue object. + The message queue creator delegate. + + + + Creates the message queue given its name in the application context. + + Name of the message queue object. + + A MessageQueue instance configured via the application context + + + + + Determines whether the application context contains the message queue object definition. + + Name of the message queue object. + + true if the application context contains the specified message queue object name; otherwise, false. + + + + + Registers the message converter. + + Name of the message converter. + The message converter creator delegate. + + + + Creates the message converter given its name in the application context. + + Name of the message converter object. + + A IMessageConverter instance configured via the application context + + + + + Determines whether the application context contains the message queue object definition. + + Name of the message converter object. + + true if the application context contains the specified message message converter object name; otherwise, false. + + + + + Gets or sets the that this + object runs in. + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Specifies a basic set of helper MSMQ opertions. + + + Implemented by . Not often used but a useful option + to enhance testability, as it can easily be mocked or stubbed. + + + Provides MessageQueueTemplate's + Send(..) and receive(..) methods that mirror various MSMQ MessageQueue + API methods. + + + Mark Pollack + + + + Send the given object to the default destination, converting the object + to a MSMQ message with a configured IMessageConverter. + + This will only work with a default destination queue specified! + The obj. + + + Send the given object to the default destination, converting the object + to a MSMQ message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. +

This will only work with a default destination specified!

+ + the object to convert to a message + + the callback to modify the message + + if thrown by MSMQ API methods + + + Send the given object to the specified destination, converting the object + to a MSMQ message with a configured and resolving the + destination name to a using a + + the name of the destination queue + to send this message to (to be resolved to an actual MessageQueue + by a IMessageQueueFactory) + + the object to convert to a message + + NMSException if there is any problem + + + Send the given object to the specified destination, converting the object + to a MSMQ message with a configured and resolving the + destination name to a with an + The callback allows for modification of the message after conversion. + + the name of the destination queue + to send this message to (to be resolved to an actual MessageQueue + by a IMessageQueueFactory) + + the object to convert to a message + + the callback to modify the message + + if thrown by MSMQ API methods + + + + Receive and convert a message synchronously from the default message queue. + + The converted object + if thrown by MSMQ API methods. Note an + exception will be thrown if the timeout of the syncrhonous recieve operation expires. + + + + + Receives and convert a message synchronously from the specified message queue. + + Name of the message queue object. + the converted object + if thrown by MSMQ API methods. Note an + exception will be thrown if the timeout of the syncrhonous recieve operation expires. + + + + + Receives a message on the default message queue using the transactional settings as dicted by MessageQueue's Transactional property and + the current Spring managed ambient transaction. + + A message. + + + + Receives a message on the specified queue using the transactional settings as dicted by MessageQueue's Transactional property and + the current Spring managed ambient transaction. + + Name of the message queue object. + + + + + Sends the specified message to the default message queue using the + transactional settings as dicted by MessageQueue's Transactional property and + the current Spring managed ambient transaction. + + The message to send + + + + Sends the specified message to the message queue using the + transactional settings as dicted by MessageQueue's Transactional property and + the current Spring managed ambient transaction. + + Name of the message queue object. + The message. + + + + Sends the specified message on the provided MessageQueue using the + transactional settings as dicted by MessageQueue's Transactional property and + the current Spring managed ambient transaction. + + + Note that it is the callers responsibility to ensure that the MessageQueue instance + passed into this not being access simultaneously by other threads. + + A transactional send (either local or DTC transaction) will be + attempted for a transacitonal queue, falling back to a single-transaction send + to a transactional queue if there is not ambient Spring managed transaction. + The DefaultMessageQueue to send a message to. + The message to send + + + + MessageQueueResourceHolder marker subclass that indicates local exposure, + i.e. that does not indicate an externally managed transaction. + + Mark Pollack + + + + MessageQueue resource holder, wrapping a MessageQueueTransaction. + MessageQueueTransactionManager binds instances of this class to the thread. + + + This is an SPI class, not intended to be used by applications. + + Mark Pollack + + + + Initializes a new instance of the class. + + The message queue transaction. + + + + Gets or sets the message queue transaction. + + The message queue transaction. + + + + Initializes a new instance of the class. + + The message queue transaction. + + + + To be used with MessageQueueTemplate's send method that + convert an object to a message. + + + It allows for further modification of the message after it has been processed + by the converter. This is useful for setting of Message properties (e.g. + CorrelationId, AppSpecific, TimeToReachQueue). + + Mark Pollack + + + + Convenient super class for application classes that need MSMQ access. + + + Override the InitGateway method to perform custom startup tasks. + + Mark Pollack + + + + Subclasses can override this for custom initialization behavior. + Gets called after population of this instance's properties. + + + + + Gets or sets the message queue template. . + + The message queue template. + + + + Gets the message queue factory, a convenience method. + + The message queue factory. + + + + Encapsulates additional metadata information about the MessageQueue that can not be easily obtained + from the MessageQueue itself. + + + + + Initializes a new instance of the class. + + if set to true [remote queue]. + if set to true [remote queue is transactional]. + + + + Gets or sets a value indicating whether the queue is a remote queue. + + + The operations that one can perform on the MessageQueue depend on if it is local or remote, for + example checking if it is transactional. This is very difficult to determine programmatically. + The property was made virtual so it can be overridden to take into account custom heuristics you + may want to use to determine this programmatically. + + true if remote queue; otherwise, false. + + + + Gets or sets a value indicating whether the remote queue is transactional. + + + true if the remote queue is transactional; otherwise, false. + + + + + Retrieves MessageQueueMetadata from the cache. + + The queue path. + + Item for the specified , or null. + + + + + Removes the specified queue path from the cache + + The queue path. + + + + Removes collection of MessageQueueMetaCache from the cache. + + + Array of MessageQueue paths to remove. + + + + + Removes all MessageQueueMetadata from the cache. + + + + + Gets the number of items in the cache. + + + + + Gets a collection of all cache queue paths. + + + + + Helper class that simplifies MSMQ access code. + + + + Using the System.Messaging.MessageQueue class directly in application code has a number of + shortcomings, namely that most operations are not thread safe (in particular Send) and + IMessageFormatter classes are not thread safe either. + + + The MessageQueueTemplate class overcomes these limitations letting you use a single instance + of MessageQueueTemplate across multiple threads to perform standard MessageQueue opertations. + Classes that are not thread safe are obtained and cached in thread local storage via an + implementation of the interface, specifically + . + + + You can access the thread local instance of the MessageQueue associated with this template + via the Property DefaultMessageQueue. + + + The template's Send methods will select an appropriate transaction delivery settings so + calling code does not need to explicitly manage this responsibility themselves and thus + allowing for greater portability of code across different, but common, transactional usage scenarios. + + A transactional send (either local or DTC transaction) will be + attempted for a transacitonal queue, falling back to a single-transaction send + to a transactional queue if there is not ambient Spring managed transaction. + + The overloaded ConvertAndSend and ReceiveAndConvert methods inherit the transactional + semantics of the previously described Send method but more importantly, they help to ensure + that thread safe access to instances are + used as well as providing additional central location to put programmic logic that translates + between the MSMQ Message object and the your business objects. This for example is useful if you + need to perform additional translation operations after calling a IMessageFormatter instance or + want to directly extract and process the Message body contents. + + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + Name of the message queue as registered in the Spring container. + + + + Invoked by an + after it has injected all of an object's dependencies. + + + Ensure that the DefaultMessageQueueObjectName property is set, creates + a default implementation of the interface + () that retrieves instances on a per-thread + basis, and registers in the Spring container a default implementation of + () with a + simple System.String as its TargetType. + + + + + Send the given object to the default destination, converting the object + to a MSMQ message with a configured IMessageConverter. + + The obj. + This will only work with a default destination queue specified! + + + + Send the given object to the default destination, converting the object + to a MSMQ message with a configured IMessageConverter. The IMessagePostProcessor + callback allows for modification of the message after conversion. +

This will only work with a default destination specified!

+ + the object to convert to a message + the callback to modify the message + if thrown by MSMQ API methods + + + + Send the given object to the specified destination, converting the object + to a MSMQ message with a configured and resolving the + destination name to a using a + + the name of the destination queue + to send this message to (to be resolved to an actual MessageQueue + by a IMessageQueueFactory) + the object to convert to a message + NMSException if there is any problem + + + + Send the given object to the specified destination, converting the object + to a MSMQ message with a configured and resolving the + destination name to a with an + The callback allows for modification of the message after conversion. + + the name of the destination queue + to send this message to (to be resolved to an actual MessageQueue + by a IMessageQueueFactory) + the object to convert to a message + the callback to modify the message + if thrown by MSMQ API methods + + + + Receive and convert a message synchronously from the default message queue. + + The converted object + if thrown by MSMQ API methods. Note an + exception will be thrown if the timeout of the syncrhonous recieve operation expires. + + + + + Receives and convert a message synchronously from the specified message queue. + + Name of the message queue object. + the converted object + if thrown by MSMQ API methods. Note an + exception will be thrown if the timeout of the syncrhonous recieve operation expires. + + + + + Receives a message on the default message queue using the transactional settings as dicted by MessageQueue's Transactional property and + the current Spring managed ambient transaction. + + A message. + + + + Receives a message on the specified queue using the transactional settings as dicted by MessageQueue's Transactional property and + the current Spring managed ambient transaction. + + Name of the message queue object. + + + + + Sends the specified message to the default message queue using the + transactional settings as dicted by MessageQueue's Transactional property and + the current Spring managed ambient transaction. + + The message to send + + + + Sends the specified message to the message queue using the + transactional settings as dicted by MessageQueue's Transactional property and + the current Spring managed ambient transaction. + + Name of the message queue object. + The message. + + + + Sends the specified message on the provided MessageQueue using the + transactional settings as dicted by MessageQueue's Transactional property and + the current Spring managed ambient transaction. + + The DefaultMessageQueue to send a message to. + The message to send + + Note that it is the callers responsibility to ensure that the MessageQueue instance + passed into this not being access simultaneously by other threads. + + A transactional send (either local or DTC transaction) will be + attempted for a transacitonal queue, falling back to a single-transaction send + to a transactional queue if there is not ambient Spring managed transaction. + + + + Sends the message to the given message queue. + + If System.Transactions.Transaction.Current is null, then send based on + the transaction semantics of the queue definition. See + The message queue. + The message. + + + + Send the message queue selecting the appropriate transactional delivery options. + + + + If the message queue is transactional and there is an ambient MessageQueueTransaction + in thread local storage (put there via the use of Spring's MessageQueueTransactionManager + or TransactionalMessageListenerContainer), the message will be sent transactionally using the + MessageQueueTransaction object in thread local storage. This lets you group together multiple + messaging operations within the same transaction without having to explicitly pass around the + MessageQueueTransaction object. + + + If the message queue is transactional but there is no ambient MessageQueueTransaction, + then a single message transaction is created on each messaging operation. + (MessageQueueTransactionType = Single). + + + If there is an ambient System.Transactions transaction then that transaction will + be used (MessageQueueTransactionType = Automatic). + + + If the queue is not transactional, then a non-transactional send + (MessageQueueTransactionType = None) is used. + + + The mq. + The MSG. + + + + Does the send message transaction. + + The mq. + The transaction to use. + The MSG. + + + + Does the send message queue non transactional. + + The mq. + The transaction to use. + The MSG. + + + + Sends using MessageQueueTransactionType.Automatic transaction type + + The message queue. + The message. + + + + Template method to convert the message if it is not null. + + The message. + The converted message ,or null if no message converter is set. + + + + Checks if the default message queue if defined. + + + + + Gets or sets the message queue factory to use for creating MessageQueue and IMessageConverters. + Default value is one that support thread local instances. + + The message queue factory. + + + + Gets or sets the name of the default message queue as identified in the Spring container. + + The name of the message queue as identified in the Spring container. + + + + Gets or sets the name of the message converter object. The name will be passed to + the class to resolve it to an actual MessageQueue + instance. + + The default name is internally generated and will register an XmlMessageConverter + that uses an and a simple System.String as its TargetType. + The name of the message converter object. + + + + Gets the default message queue to be used on send/receive operations that do not + have a destination parameter. The MessageQueue instance is resolved using + the template's , the default implementaion + will return an unique instance per thread. + + The default message queue. + + + + Gets the message converter to use for this template. Used to resolve + object parameters to ConvertAndSend methods and object results + from ReceiveAndConvert methods. + + + The default + + The message converter. + + + + Gets or sets the receive timeout to be used on recieve operations. Default value is + MessageQueue.InfiniteTimeout (which is actually ~3 months). + + The receive timeout. + + + + Gets or sets the metadata cache. + + The metadata cache. + + + + Gets or sets the that this + object runs in. + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + implementation for MSMQ. Binds a + MessageQueueTransaction to the thread. + + + + This local strategy is an alternative to executing MSMQ operations within + DTC transactions. Its advantage is that multiple MSMQ operations can + easily participate within the same local MessagingTransaction transparently when + using the class for send and recieve operations + and not pay the overhead of a DTC transaction. + + Transaction synchronization is turned off by default, as this manager might + be used alongside a IDbProvider-based Spring transaction manager such as the + ADO.NET . + which has stronger needs for synchronization. + + Mark Pollack + + + + Location where the message transaction is stored in thread local storage. + + + + + Initializes a new instance of the class. + + + Turns off transaction synchronization by default, as this manager might + be used alongside a DbProvider-based Spring transaction manager like + AdoPlatformTransactionManager, which has stronger needs for synchronization. + Only one manager is allowed to drive synchronization at any point of time. + + + + + Return the current transaction object. + + The current transaction object. + + If transaction support is not available. + + + In the case of lookup or system errors. + + + + + Check if the given transaction object indicates an existing transaction + (that is, a transaction which has already started). + + MessageQueueTransactionObject object returned by + . + + True if there is an existing transaction. + + + + + Begin a new transaction with the given transaction definition. + + Transaction object returned by + . + instance, describing + propagation behavior, isolation level, timeout etc. + + In the case of creation or system errors. + + + + + Suspend the resources of the current transaction. + + Transaction object returned by + . + + An object that holds suspended resources (will be kept unexamined for passing it into + .) + + + + + Resume the resources of the current transaction. + + Transaction object returned by + . + The object that holds suspended resources as returned by + . + + + + Perform an actual commit on the given transaction. + + The status representation of the transaction. + +

+ An implementation does not need to check the rollback-only flag. +

+ + + + + Perform an actual rollback on the given transaction, calls Transaction.Abort(). + + The status representation of the transaction. + + An implementation does not need to check the new transaction flag. + + + + + Set the given transaction rollback-only. Only called on rollback + if the current transaction takes part in an existing one. + + The status representation of the transaction. + Default implementation throws an IllegalTransactionStateException, + assuming that participating in existing transactions is generally not + supported. Subclasses are of course encouraged to provide such support. + + + In the case of system errors. + + + + + Cleanup resources after transaction completion. + + Transaction object returned by + . + + + Called after + and + + execution on any outcome. + + + + + + Utility methods to support Spring's MSMQ functionality + + + + + Registers the default message converter with the application context. + + The application context. + The name of the message converter to use for lookups with + . + + + + + Gets the message queue transaction from thread local storage + + The resource factory. + null if not found in thread local storage + + + Callback interface for resource creation. + Serving as argument for the GetMessageQueueTransaction method. + + + + + Return whether to allow for a local transaction that is synchronized with + a Spring-managed transaction (where the main transaction might be a ADO.NET-based + one for a specific IDbProvider, for example), with the MSMQ transaction + committing right after the main transaction. + Returns whether to allow for synchronizing a local MSMQ transaction + + + + + Provides basic lifecyle management methods for implementing a message listener container. + + + This base class does not assume any specific listener programming model + or listener invoker mechanism. It just provides the general runtime + lifecycle management needed for any kind of message-based listening mechanism. + + For a concrete listener programming model, check out the + subclass. For a concrete listener + invoker mechanism, check out the , + , or + classes. + + + Mark Pollack + + + + Delegates to and + + + + + Calls when the application context destroys the container instance. + + + + + Validates the configuration of this container + The default implementation is empty. To be overridden in subclasses. + + + + + Initializes this container. Calls the abstract method to + initialize the listening infrastructure (i.e. subclasses will typically + resolve a MessageQueue instance from a MessageQueueObjectName) and then calls + the abstract method DoStart if the property is set to true, + + + + + Sets the container state to inactive and not running, calls template method + + + + + + Starts this container. + + + + + Sets the state to running, can be overridden in subclasses. + + + + + Stops this instance. + + + + + Template method suitable for overriding that stops the container. + + + + + Check whether this container's listeners are generally allowed to run. + + + This implementation always returns true; the default 'running' + state is purely determined by and + + Subclasses may override this method to check against temporary + conditions that prevent listeners from actually running. In other words, + they may apply further restrictions to the 'running' state, returning + false if such a restriction prevents listeners from running. + + + false if such a restriction prevents listeners from running. + + + + Subclasses need to implement this method for their specific + listener management process. + + + + + Subclasses need to implement this method for their specific + listener management process. + + + + + Sets a value indicating whether to automatically start the container after initialization. + Default is "true"; set this to "false" to allow for manual startup though the + method. + + true if autostartup; otherwise, false. + + + + Gets a value indicating whether this Container is active, + that is, whether it has been set up but not shut down yet. + + true if active; otherwise, false. + + + + Gets a value indicating whether this Container is running, + that is whether it has been started and not stopped yet. + + true if running; otherwise, false. + + + + Return the object name that this listener container has been assigned + in its containing object factory, if any. + + + + + Defines a minimal programming model for message listener containers. They are expected to + invoke a upon asynchronous receives of a MSMQ message. Access to + obtain MessageQueue and instances is available through the + property, the default implementation + provides per-thread instances of these classes. + + Mark Pollack + + + + Most operations within the MessageListener container hierarchy use methods on the + MessageQueue instance which are thread safe (BeginPeek, BeginReceive, + EndPeek, EndReceive, GetAllMessages, Peek, and Receive). When using another + method on the shared MessageQueue instance, wrap calls with a lock on this object. + + + + + Validates that the is not null. If + is null, a is created. Can be be overridden in subclasses. + + + + + Template method that execute listener with the provided message if + is true. Subclasses will call + this method at the appropriate point in their processing lifecycle, for example + committing or rolling back a transaction if needed. + + Calls the template method + The message. + + + + Invokes the listener if it is not null. Invokes the method . + Can be overridden in subclasses. + + The message. + + + + Invokes the listener. Can be overriden in subclasses. + + The listener. + The message. + + + + Closes the queue handle. Cancel pending receive operation by closing the queue handle + To properly dispose of the queue handle, ensure that EnableConnectionCache=false on the + MessageQueue that this listener is configured to use. + + + + + Gets or sets the message queue factory. + + The message queue factory. + + + + Gets or sets the name of the message queue object, as refered to in the + Spring configuration, that will be used to create a DefaultMessageQueue instance + for consuming messages in the container. + + The name of the message queue object. + + + + Gets or sets the message listener. + + The message listener. + + + + Gets or sets the recovery time span, how long to sleep after an exception in processing occured + to avoid excessive redelivery attempts. Default value is 1 second. + + The recovery time span. + + + + Gets or sets the that this + object runs in. + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Base class for listener container implementations which are based on Peeking for messages on + a MessageQueue. Peeking is the only resource efficient approach that can be used in + order to have MessageQueue receipt in conjunction with transactions, either local MSMQ transactions, + local ADO.NET based transactions, or DTC transactions. See SimpleMessageListenerContainer for + an implementation based on a synchronous receives and you do not require transactional support. + + + The number of threads that will be created for processing messages after the Peek occurs + is set via the property MaxConcurrentListeners. Each processing thread will continue to listen + for messages up until the the timeout value specified by ListenerTimeLimit or until + there are no more messages on the queue (which ver comes first). + + The default value of + ListenerTimeLimit is TimeSpan.Zero, meaning that only one attempt to recieve a message from the + queue will be performed by each listener thread. + + + The current implementation uses the standard .NET thread pool. Future implementations will + use a custom (and pluggable) thread pool. + + + + + + Retrieves a MessageQueue instance given the MessageQueueObjectName + + + + + Wait for all listener threads to exit and closes the DefaultMessageQueue. + + + + + Starts peeking on the DefaultMessageQueue. + + + + + Stops peeking on the message queue. + + + + + Starts peeking on the DefaultMessageQueue. This is the method that must be called + again at the end of message procesing to continue the peeking process. + + + + + The callback when the peek has completed. Schedule up to the maximum number of + concurrent listeners to receive messages off the queue. Delegates to the abstract + method DoReceiveAndExecute so that subclasses may customize the receiving process, + for example to surround the receive operation with transactional semantics. + + The async result. + + + + Execute the listener for a message received from the given queue + wrapping the entire operation in an external transaction if demanded. + + The DefaultMessageQueue upon which the call to receive should be + called. + + + + Subclasses perform a receive opertion on the message queue and execute the + message listener + + The DefaultMessageQueue. + true if received a message, false otherwise + + + + Waits for listener threads to exit. + + + + + Configures the initial peek thread, setting it to be a background thread. + Can be overridden in subclasses. + + The peek thread. + + + + Template method that gets called right when a new message has been received, + before attempting to process it. Allows subclasses to react to the event + of an actual incoming message, for example adapting their consumer count. + + The message. + + + + Template method that gets called right before a new message is received, i.e. + messageQueue.Receive(). + + It allows subclasses to modify the state of the MessageQueue + before receiving which maybe required when using remote queues + + + + + Gets or sets the listener time limit to continuously receive messages. + The value is specified in milliseconds. The default value is TimeSpan.Zero, + indicating to only perform one Receive operation per Peek trigger. + + The listener time limit in millis. + + + + Gets or sets the max concurrent listeners to receive messages. + + The max concurrent listeners. + + + + Gets or sets the message queue used for Peeking. + + The message queue. + + + + Provides common functionality to exception handlers that will send the exceptional message to + another queue. + + Allows for setting of MaxRetry limit and contains an internal dictionary to keep track + of the Message Ids of messages. + + Mark Pollack + + + + Synchronization object for access to messageMap protected variable + + + + + In-memory storage to keep track of Message Ids that have been already processed. + + + + + Ensure that the MessageQueueObject name is set and creates a + if no + is specified. + + Will attempt to create an instance of the DefaultMessageQueue to detect early + any configuraiton errors. + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Gets or sets the maximum retry count to reattempt processing of a message that has thrown + an exception + + The max retry count. + + + + Gets or sets the message queue factory. + + The message queue factory. + + + + Gets or sets the name of the message queue object to send the message that cannot be + processed successfully after MaxRetry delivery attempts. + + The name of the message queue object. + + + + Gets or sets the that this + object runs in. + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + An implementation of a Peeking based MessageListener container that starts a transaction + before recieving a message. The implementation determines + the type of transaction that will be started. An exception while processing the message will + result in a rollback, otherwise a transaction commit will be performed. + + + The type of transaction that can be started can either be local transaction, + (e.g. , a local messaging transaction + (e.g. or a DTC based transaction, + (eg. . + + Transaction properties can be set using the property + and the transaction timeout via the property . + + + + + + Subclasses perform a receive opertion on the message queue and execute the + message listener + + The DefaultMessageQueue. + + true if received a message, false otherwise + + + + + Does the receive and execute using platform transaction manager. + + The message queue. + The transactional status. + true if should continue peeking, false otherwise. + + + + Rollback the transaction on exception. + + The transactional status. + The exception. + + + + Gets or sets the platform transaction manager. + + The platform transaction manager. + + + + Gets or sets the transaction definition. + + The transaction definition. + + + + Sets the transaction timeout to use for transactional wrapping, in seconds. + Default is none, using the transaction manager's default timeout. + + The transaction timeout. + + + + A MessageListenerContainer that uses distributed (DTC) based transactions. Exceptions are + handled by instances of . + + + + Starts a DTC based transaction before receiving the message. The transaction is + automaticaly promoted to 2PC to avoid the default behaivor of transactional promotion. + Database and messaging operations will commit or rollback together. + + + If you only want local message based transactions use the + . With some simple programming + you may also achieve 'exactly once' processing using the + . + + + Poison messages can be detected and sent to another queue using Spring's + . + + + + + + Set the transaction name to be the spring object name. + Call base class Initialize() functionality. + + + + + Does the receive and execute using TxPlatformTransactionManager. Starts a distributed + transaction before calling Receive. + + The message queue. + The transactional status. + + true if should continue peeking, false otherwise. + + + + + Handles the distributed transaction listener exception by calling the + if not null. + + The exception. + The message. + + + + Gets or sets the distributed transaction exception handler. + + The distributed transaction exception handler. + + + + Exception handler for use with DTC based message listener container. + such as . + See for + an implementation that detects poison messages and send them to another queue. + + + + + Determines whether the incoming message is a poison message. This method is + called before the is invoked. + + + The will call + if this method returns true and will + then commit the distibuted transaction (removing the message from the queue). + + The incoming message. + + true if it is a poison message; otherwise, false. + + + + + Handles the poison message. + + Typical implementations will move the message to another queue. + The will call this + method while still within a DTC-based transaction. + + The poison message. + + + + Called when an exception is thrown in listener processing. + + The exception. + The message. + + + + Exception handler called when an exception occurs during + non-transactional receive processing. + + + A non-transactional receive will remove the message from the queue. Non-transactional + receivers do not suffer from poison messages since there is no redelivery by MSMQ. + Typical actions to perform are to log the message or place it in another queue. + If placed in another queue, another message listener container can be used to + process the message later, assuming the root cause of the original exception is + transient in nature. + + + + + Called when an exception is thrown in listener processing. + + The exception. + The message. + + + + The callback invoked when a message is received. + + Mark Pollack + + + + Called when message is received. + + The message. + + + + The exception handler within a transactional context. + + + The return value indicates to the invoker (typically a + ) whether the + MessageTransaction that is associated with the delivery of this message + should be rolled back (placing the message back on the transactional queue + for redelivery) or commited (removing the message from the transactional queue) + + Mark Pollack + + + + Called when an exception is thrown during listener processing under the + scope of a . + + The exception. + The message. + The message queue transaction. + An action indicating if the caller should commit or rollback the + + + + + + Exception to be thrown when the execution of a listener method failed. + + Juergen Hoeller + Mark Pollack (.NET) + + + + Base exception class for exceptions thrown by Spring in Spring.Messaging + + Mark Pollack + + + Creates a new instance of the MessagingException class. + + + + Creates a new instance of the MessagingException class. with the specified message. + + + A message about the exception. + + + + + Creates a new instance of the MessagingException class with the specified message + and root cause. + + + A message about the exception. + + + The root exception that is being wrapped. + + + + + Creates a new instance of the MessagingException class. + + + The + that holds the serialized object data about the exception being thrown. + + + The + that contains contextual information about the source or destination. + + + + + Initializes a new instance of the class, with the specified message + + The message. + + + + Initializes a new instance of the class, with the specified message + and root cause exception + + The message. + The inner exception. + + + + Message listener adapter that delegates the handling of messages to target + listener methods via reflection , + with flexible message type conversion. + Allows listener methods to operate on message content types, completely + independent from the MSMQ API. + + + + By default, the content of incoming MSMQ messages gets extracted before + being passed into the target handler method, to let the target method + operate on message content types such as String or business object instead of + . Message type conversion is delegated to a Spring + By default, an + with TargetType set to System.String is used. If you do not want such automatic + message conversion taking place, then be sure to set the + MessageConverter property to null. + + + If a target handler method returns a non-null object (for example, with a + message content type such as String), it will get + wrapped in a MSMQ Message and sent to the response destination + (either using the MSMQ Message.ResponseQueue property or + ) specified default response queue + destination). + + + Find below some examples of method signatures compliant with this adapter class. + This first example uses the default that can + marhsall/unmarshall string values from the MSMQ Message. + + + public interface IMyHandler + { + void HandleMessage(string text); + } + + + The next example indicates a similar method signature but the name of the + handler method name has been changed to "DoWork", using the property + + + + public interface IMyHandler + { + void DoWork(string text); + } + + If your implementation will return multiple object + types, overloading the handler method is perfectly acceptible, the most specific matching + method will be used. A method with an object signature would be consider a + 'catch-all' method + + + public interface IMyHandler + { + void DoWork(string text); + void DoWork(OrderRequest orderRequest); + void DoWork(InvoiceRequest invoiceRequest); + void DoWork(object obj); + } + + + The last example shows how to send a message to the ResponseQueue for those + methods that do not return void. + + public interface MyHandler + { + string DoWork(string text); + OrderResponse DoWork(OrderRequest orderRequest); + InvoiceResponse DoWork(InvoiceRequest invoiceRequest); + void DoWork(object obj); + } + + + + Mark Pollack + + + + Out-of-the-box value for the default listener method: "HandleMessage" + + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The handler object. + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Called when message is received. + + The message. + + + + Gets the name of the handler method. + + The original message. + The extracted message. + The name of the handler method. + + + + Builds an array of arguments to be passed into the taret listener method. + + + Allows for multiple method arguments to be built from a single message object. +

The default implementation builds an array with the given message object + as sole element. This means that the extracted message will always be passed + into a single method argument, even if it is an array, with the target + method having a corresponding single argument of the array's type declared.

+

This can be overridden to treat special message content such as arrays + differently, for example passing in each element of the message array + as distinct method argument.

+ + The converted message. + the array of arguments to be passed into the + listener method (each element of the array corresponding + to a distinct method argument) + + + + Invokes the specified listener method. This default implementation can only handle invoking a + single argument method. + + Name of the listener method. + The arguments to be passed in. Only the first argument in the list is currently + supported in this implementation. + The result returned from the listener method + + + + Initialize the default implementations for the adapter's strategies. + + + + + Extracts the message body from the given message. + + The message. + the content of the message, to be passed into the + listener method as argument + + + + Sends the given response message to the given destination. + + The destination to send to. + The outgoing message about to be sent. + + + + Builds a MSMQ message to be sent as response based on the given result object. + + The result. + the MSMQ Message (never null) + If no messgae converter is specified. + + + + Post-process the given response message before it will be sent. The default implementation + sets the response's correlation id to the request message's correlation id. + + The original incoming message. + The outgoing MSMQ message about to be sent. + + + + Determine a response destination for the given message. + + + The default implementation first checks the MSMQ ResponseQueue + of the supplied request; if that is not null + it is returned; if it is null, then the configured + default response destination} + is returned; if this too is null, then an + is thrown. + + + The request. + The response. + + + + + Gets or sets the handler object to delegate message listening to. + + + Specified listener methods have to be present on this target object. + If no explicit handler object has been specified, listener + methods are expected to present on this adapter instance, that is, + on a custom subclass of this adapter, defining listener methods. + + The handler object. + + + + Gets or sets the default handler method to delegate to, + for the case where no specific listener method has been determined. + Out-of-the-box value is "HandleMessage". + + The default handler method. + + + + Gets or sets the processing expression for use in custom subclasses + + The processing expression. + + + + Gets or sets the that this + object runs in. + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Gets or sets the message queue factory. + + The message queue factory. + + + + Sets the name of the default response queue to send response messages to. + This will be applied in case of a request message that does not carry a + "ResponseQueue" value. + Alternatively, specify a response queue via the property + . + + The name of the default response destination queue. + + + + Sets the default destination to send response messages to. This will be applied + in case of a request message that does not carry a "ResponseQueue" property + Response destinations are only relevant for listener methods that return + result objects, which will be wrapped in a response message and sent to a + response destination. + + Alternatively, specify a "DefaultResponseQueueName" + to be dynamically resolved via the MessageQueueFactory. + + + The default response destination. + + + + Gets or sets the name of the message converter object used to resolved a + instance. + + The name of the message converter object. + + + + Gets message converter that will convert incoming MSMQ messages to + listener method arguments, and objects returned from listener + methods back to MSMQ messages. + + + The converter used is the one returned by CreateMessageConverter on MessageQueueFactory. + + + The message converter. + + + + Sets the message queue template. + + If not set, will create one for it own internal use whne MessageListenerAdapter is constructed. + It maybe useful to share an existing instance if you have an extensively configured MessageQueueTemplate. + + The message queue template. + + + + An implementation of a Peeking based MessageListener container that does not surround the + receive operation with a transaction. + + + Exceptions that occur during message processing are handled by an instance + of . + + Mark Pollack + + + + Handles the listener exception. + + The exception. + The message delivered that resultd in an processing exception. + + + + Perform a receive opertion on the message queue and execute the + message listener + + The MessageQueue. + + true if received a message, false otherwise + + + + + Gets or sets the exception handler. + + The exception handler. + + + + detects poison messages by tracking the Message Id property in memory with a count of how many + times an exception has occurred. If that count is greater than the handler's MaxRetry count it + will be sent to another queue. The queue to send the message to is specified via the property M + essageQueueObjectName. + + Exception handler when using DistributedTxMessageListenerContainer + + + + Determines whether the incoming message is a poison message. This method is + called before the is invoked. + + The incoming message. + + true if it is a poison message; otherwise, false. + + + The will call + if this method returns true and will + then commit the distibuted transaction (removing the message from the queue). + + + + + Handles the poison message. + + The message. + + + + Called when an exception is thrown in listener processing. + + The exception. + The message. + + + + Sends the message to queue. + + The message. + + + + Keeps track of the Message's Id property in memory with a count of how many times an + exception has occurred. If that count is greater than the handler's MaxRetry count it + will be sent to another queue using the provided MessageQueueTransaction. The queue to + send the message to is specified via the property MessageQueueObjectName. + + + + + Called when an exception is thrown during listener processing under the + scope of a . + + The exception. + The message. + The message queue transaction. + + An action indicating if the caller should commit or rollback the + + + + + + Determines whether this exception was already processed. + + The exception. + + true if the exception was already processed; otherwise, false. + + + + + Sends the message to queue. + + The message. + The message queue transaction. + TransactionAction.Commit + + + + Template method called before the message that caused the exception is + send to another queue. The default behavior is to set the CorrelationId + to the current message's Id value for tracking purposes. Subclasses + can use other means, perhaps using the AppSpecific field or modifying the + body of the message to a known shared format that keeps track of + the full 'lifecycle' of the message as it goes from queue-to-queue. + + The message. + + + + Gets or sets the exception anmes that indicate the message has already + been processed. If the exception thrown matches one of these names then + the returned TransactionAction is Commit to remove it from the queue. + + The name test is thrownException.GetType().Name.IndexOf(exceptionName) >= 0 + The message already processed exception types. + + + + Action to perform on the MessageQueueTransaction when handling message listener exceptions. + + + + + Rollback the MessageQueueTransaction, returning the recieved message back onto the queue. + + + + + Commit the MessageQueueTransaction, removing the message from the queue. + + + + + A MessageListenerContainer that uses local (non-DTC) based transactions. Exceptions are + handled by instances of . + + + + This container distinguishes between two types of + implementations. + + If you specify a then + a MSMQ will be started + before receiving the message and used as part of the container's recieve operation. The + binds the + to thread local storage and as such will implicitly be used by + send and receive operations to a transactional queue. + + + Service layer operations that are called inside the message listener will typically + be transactional based on using standard Spring declarative transaction management + functionality. In case of exceptions in the service layer, the database operation + will have been rolled back and the + that is later invoked should decide to either commit the surrounding local + MSMQ based transaction (removing the message from the queue) or to rollback + (placing the message back on the queue for redelivery). + + + The use of a transactional service layer in combination with + a container managed is a powerful combination + that can be used to achieve "exactly one" transaction message processing with + database operations that are commonly associated with using transactional messaging and + distributed transactions (i.e. both the messaging and database operation commit or rollback + together). + + + The additional programming logic needed to achieve this is to keep track of the Message.Id + that has been processed successfully within the transactional service layer. + This is needed as there may be a system failure (e.g. power goes off) + between the 'inner' database commit and the 'outer' messaging commit, resulting + in message redelivery. The transactional service layer needs logic to detect if incoming + message was processed successfully. It can do this by checking the database for an + indication of successfull processing, perhaps by recording the Message.Id itself in a + status table. If the transactional service layer determines that the message has + already been processed, it can throw a specific exception for thise case. The + container's exception handler will recognize this exception type and vote to commit + (remove from the queue) the 'outer' messaging transaction. + Spring provides an exception handler with this functionality, + see for more information. + + If you specify an implementation of + (e.g. or HibernateTransactionManager) then + an local database transaction will be started before receiving the message. By default, + the container will also start a local + after the local database transaction has started, but before the receiving the message. + The will be used to receive the message. + If you do not want his behavior set + to false. Also by default, the + will be bound to thread local storage such that any + send or recieve operations will participate transparently in the same + . If you do not want this behavior + set the property to false. + + In case of exceptions during processing + when using an implementation of + (e.g. and starting a container managed + ) the container's + will determine if the + should commit (removing it from the queue) + or rollback (placing it back on the queue for redelivery). The listener + exception will always + trigger a rollback in the 'outer' (e.g. + or HibernateTransactionManager) based transaction. + + + PoisonMessage handing, that is endless redelivery of a message due to exceptions + during processing, can be detected using implementatons of the + interface. A specific implementation + is provided that will move the poison message to another queue after a maximum number + of redelivery attempts. See for more information. + + + + + + Determine if the container should create its own + MessageQueueTransaction when a IResourceTransactionManager is specified. + Set the transaction name to the name of the spring object. + Call base class Initialize() funtionality + + + + + Does the receive and execute using platform transaction manager. + + The message queue. + The transactional status. + + true if should continue peeking, false otherwise. + + + + + Does the recieve and execute using message queue transaction manager. + + The message queue. + The transactional status. + true if should continue peeking, false otherise + + + + Does the recieve and execute using a local MessageQueueTransaction. + + The mqessage queue. + The transactional status. + true if should continue peeking, false otherwise. + + + + Handles the transactional listener exception. + + The exception thrown while processing the message. + The message. + The message queue transaction. + The TransactionAction retruned by the TransactionalExceptionListener + + + + Invokes the transactional exception listener. + + The exception thrown during message processing. + The message. + The message queue transaction. + TransactionAction.Rollback if no exception handler is defined, otherwise the + TransactionAction returned by the exception handler + + + + Gets or sets a value indicating whether the MessageListenerContainer should be + responsible for creating a MessageQueueTransaction + when receiving a message. + + + + Creating MessageQueueTransactions is usually the responsibility of the + IPlatformTransactionManager, e.g. TxScopePlatformTransactionManager (when using DTC) + or MessageQueueTransactionManager (when using local messaging transactions). + + + For all other IPlatformTransactionManager implementations, including when none is + specified, the MessageListenerContainer will itself create a MessageQueueTransaction + (assuming the container is consuming from a transactional queue). + + + Set the ExposeContainerManagedMessageQueueTransaction property to true if you want + the MessageQueueTransaction to be exposed to Spring's MessageQueueTemplate class + + + + true to use a container managed MessageQueueTransaction; otherwise, false. + + + + + Gets or sets a value indicating whether expose the + container managed to thread local storage + where it will be automatically used by send + and receive operations. + + + Using an will always exposes a + to thread local storage. This property + only has effect when using a non-DTC based + + + true if [expose container managed message queue transaction]; otherwise, false. + + + + + Gets or sets the message transaction exception handler. + + The message transaction exception handler. + + + + An implementation that delegates to an instance of + to convert messages. + + Mark Pollack + + + + An interface specifying the contract to convert to and from objects. + + + + + Convert the given object to a Message. + + The object to send. + Message to send + + + + Convert the given message to a object. + + The message. + the object + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message formatter. + + + + Convert the given object to a Message. + + The object to send. + Message to send + + + + Convert the given message to a object. + + The message. + the object + + + + Creates a new object that is a copy of the current instance. + + + A new object that is a copy of this instance. + + + + + An implementation that delegates to an instance of + to convert messages. + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The binary message formatter. + + + + Convert the given object to a Message using the + + The object to send. + Message to send + + + + Convert the given message to a object using the + + The message. + the object + + + + Creates a new object that is a copy of the current instance. + + + A new object that is a copy of this instance. + + + + + Gets or sets the type format used in the + + The type format. + + + + Gets or sets the top object format used in the + + The top object format. + + + + Delegate for creating IMessageConverter instance. Used by + to register a creation function with a given name. + + + + + Internal class to that users can specify a delegate function to register with the application context that + will create a IMessageConverter instance easily at runtime. + + Mark Pollack + + + + Gets the template object definition that should be used + to configure the instance of the object managed by this factory. + + The object definition to configure the factory's product + + + + Converts an to a Message and vice-versa by using the message's + body stream. + + Mark Pollack + + + + Convert the given object to a Message. + + The object to send. + Message to send + + + + Convert the given message to a object. + + The message. + the object + + + + Creates a new object that is a copy of the current instance. + + + A new object that is a copy of this instance. + + + + + An implementation that delegates to an instance of + to convert messages. + + Mark Pollack + + + + Initializes a new instance of the class. + + + + + Initializes a new instance of the class. + + The message formatter. + + + + Convert the given object to a Message. + + The object to send. + Message to send + + + + Convert the given message to a object. + + The message. + the object + + + + Creates a new object that is a copy of the current instance. + + + A new object that is a copy of this instance. + + + + + Gets or sets the target types used by the + + The target types. + + + + Gets or sets the target type names used by the + + The target type names. + + + + Delegate for creating MessageQueue instance. Used by + to register a creation function with a given name. + + + + + Factory for creating MessageQueues. This factory will create prototype instances, i.e. every call to GetObject + will return a new MessageQueue object. + + All MessageQueue constructor arguments are exposed as properties of the factory object. As this + is a use the PropertyTemplate property to specify additional + configuration of the MessageQueue. + + Mark Pollack + + + + Retrun a configured MessageQueue object. + + A newly configured MessageQueue object + + + + Gets or sets an instance of the MessageQueueCreator delegate that will be used to create the + MessageQueue object, instead of using the various public properties on this class such + as Path, AccessMode, etc. Not intended for end-users but rather as a means to help + register MessageQueueFactoryObject at runtime using convenience method on the IMessageQueueFactory. + + + Can also be specifed using an instance of MessageCreatorDelegate. If both are specifed, the + Interface implementation has priority. + + The function that is responsbile for creating a message queue. + + + + Gets or sets the path used to create a MessageQueue instance. + + The location of the queue. + + + + Gets or sets a value indicating whether to create the MessageQueue instance with + exclusive read access to the first application that accesses the queue + + + true to grant exclusive read access to the first application that accesses the queue; otherwise, false. + + + + + Gets or sets the queue access mode. + + The queue access mode. + + + + + Gets or sets a value indicating whether [enable cache]. + + true to create and use a connection cache; otherwise false. + + + + Sets a value indicating whether to enable connection cache. The default is false, which + is different than the default value when creating a System.Messaging.MessageQueue object. + + + true if enable connection cache; otherwise, false. + + + + + Sets a value indicating whether to retrieve all message properties when receiving a message. + + + true if should etrieve all message properties when receiving a message; otherwise, false. + + + + + Sets a value indicating whether to set the filter values of common Message Queuing properties + to true and the integer-valued properties to their default values.. + + + true if should set the filter values of common Message Queuing properties; otherwise, false. + + + + + Gets or sets a value indicating whether the queue is a remote queue. + + + The operations that one can perform on the MessageQueue depend on if it is local or remote, for + example checking if it is transactional. This is very difficult to determine programmatically. + The property was made virtual so it can be overridden to take into account custom heuristics you + may want to use to determine this programmatically. + + true if remote queue; otherwise, false. + + + + Gets or sets a value indicating whether the remote queue is transactional. + + + true if the remote queue is transactional; otherwise, false. + + + + + Return the of object that this + creates, or + if not known in advance. + + The type System.Messaging.MessageQueue + + + + Is the object managed by this factory a singleton or a prototype? + + return false, a new object will be created for each request of the object + + + + Gets the template object definition that should be used + to configure the instance of the object managed by this factory. + + The object definition to configure the factory's product + + + + Set the name of the object in the object factory that created this object. + + The name of the object in the factory. + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Scheduling.Quartz.dll b/Resources/Libraries/Spring.NET/Spring.Scheduling.Quartz.dll new file mode 100644 index 00000000..0bd3f2c3 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Scheduling.Quartz.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Scheduling.Quartz.pdb b/Resources/Libraries/Spring.NET/Spring.Scheduling.Quartz.pdb new file mode 100644 index 00000000..79d1557b Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Scheduling.Quartz.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Scheduling.Quartz.xml b/Resources/Libraries/Spring.NET/Spring.Scheduling.Quartz.xml new file mode 100644 index 00000000..be5b5be2 --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Scheduling.Quartz.xml @@ -0,0 +1,2040 @@ + + + + Spring.Scheduling.Quartz + + + + + JobFactory implementation that supports + objects as well as standard Quartz instances. + + Juergen Hoeller + Marko Lahma (.NET) + + + + + + Called by the scheduler at the time of the trigger firing, in order to + produce a instance on which to call Execute. + + + It should be extremely rare for this method to throw an exception - + basically only the the case where there is no way at all to instantiate + and prepare the Job for execution. When the exception is thrown, the + Scheduler will move all triggers associated with the Job into the + state, which will require human + intervention (e.g. an application restart after fixing whatever + configuration problem led to the issue wih instantiating the Job. + + The TriggerFiredBundle from which the + and other info relating to the trigger firing can be obtained. + the newly instantiated Job + SchedulerException if there is a problem instantiating the Job. + + + + Create an instance of the specified job class. +

+ Can be overridden to post-process the job instance. +

+ + + The TriggerFiredBundle from which the JobDetail + and other info relating to the trigger firing can be obtained. + + The job instance. + + + + Adapt the given job object to the Quartz Job interface. + + + The default implementation supports straight Quartz Jobs + as well as Runnables, which get wrapped in a DelegatingJob. + + + The original instance of the specified job class. + + The adapted Quartz Job instance. + + + + + Convenience subclass of Quartz's CronTrigger type, making property based + usage easier. + + +

+ CronTrigger itself is already property based but lacks sensible defaults. + This class uses the Spring object name as job name, the Quartz default group + ("DEFAULT") as job group, the current time as start time, and indefinite + repetition, if not specified. +

+

+ This class will also register the trigger with the job name and group of + a given . This allows + to automatically register a trigger for the corresponding JobDetail, + instead of registering the JobDetail separately. +

+ + Juergen Hoeller + + + + + + + + + + + + Interface to be implemented by Quartz Triggers that are aware + of the JobDetail object that they are associated with. + + +

+ SchedulerFactoryObject will auto-detect Triggers that implement this + interface and register them for the respective JobDetail accordingly. +

+ +

+ The alternative is to configure a Trigger for a Job name and group: + This involves the need to register the JobDetail object separately + with SchedulerFactoryObject. +

+ + Juergen Hoeller + + + + + + + + Return the JobDetail that this Trigger is associated with. + + The associated JobDetail, or null if none + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Register objects in the JobDataMap via a given Map. + + + These objects will be available to this Trigger only, + in contrast to objects in the JobDetail's data map. + + + + + + Set the misfire instruction via the name of the corresponding + constant in the CronTrigger class. + Default is . + + + + + + + + Set the name of the object in the object factory that created this object. + + The name of the object in the factory. + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + + + Set the JobDetail that this trigger should be associated with. + + + This is typically used with a object reference if the JobDetail + is a Spring-managed object. Alternatively, the trigger can also + be associated with a job by name and group. + + + + + + + Set the start delay as . + + + + The start delay is added to the current system UTC time + (when the object starts) to control the + of the trigger. + + + If the start delay is non-zero it will always + take precedence over start time. + + + the start delay, as object. + + + + Helper class to map constant names to their values. + + + + + Simple Quartz IJob adapter that delegates to a + given instance. + + + Typically used in combination with property injection on the + Runnable instance, receiving parameters from the Quartz JobDataMap + that way instead of via the JobExecutionContext. + + Juergen Hoeller + Marko Lahma (.NET) + + + + + + Create a new DelegatingJob. + + + The Runnable implementation to delegate to. + + + + + Delegates execution to the underlying ThreadStart. + + + + + Return the wrapped Runnable implementation. + + The delegate. + + + + Callback interface to be implemented by Spring-managed + Quartz artifacts that need access to the SchedulerContext + (without having natural access to it). + + + Currently only supported for custom JobFactory implementations + that are passed in via Spring's SchedulerFactoryObject. + + Juergen Hoeller + + + + + + Set the SchedulerContext of the current Quartz Scheduler. + + + + + + + + + + + + + + + + Executes this instance. + + + + + Gets a value indicating whether´this instance prefers short lived tasks. + + + true if prefers short lived tasks; otherwise, false. + + + + + Convenience subclass of Quartz' JobDetail class that eases properties based + usage. + + + itself is already a object but lacks + sensible defaults. This class uses the Spring object name as job name, + and the Quartz default group ("DEFAULT") as job group if not specified. + + Juergen Hoeller + + + + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Overridden to support any job class, to allow a custom JobFactory + to adapt the given job class to the Quartz Job interface. + + + + + + Register objects in the JobDataMap via a given Map. + + + These objects will be available to this Job only, + in contrast to objects in the SchedulerContext. +

+ Note: When using persistent Jobs whose JobDetail will be kept in the + database, do not put Spring-managed objects or an ApplicationContext + reference into the JobDataMap but rather into the SchedulerContext. +

+ + + + + + Set the name of the object in the object factory that created this object. + + The name of the object in the factory. + + Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. + + + + + Gets or sets the that this + object runs in. + + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Set the key of an IApplicationContext reference to expose in the JobDataMap, + for example "applicationContext". Default is none. + Only applicable when running in a Spring ApplicationContext. + + +

+ In case of a QuartzJobObject, the reference will be applied to the Job + instance as object property. An "applicationContext" attribute will correspond + to a "setApplicationContext" method in that scenario. +

+

+ Note that ObjectFactory callback interfaces like IApplicationContextAware + are not automatically applied to Quartz Job instances, because Quartz + itself is responsible for the lifecycle of its Jobs. +

+

+ Note: When using persistent job stores where JobDetail contents will + be kept in the database, do not put an IApplicationContext reference into + the JobDataMap but rather into the SchedulerContext. +

+ + + + + + + Subclass of Quartz's JobStoreCMT class that delegates to a Spring-managed + DataSource instead of using a Quartz-managed connection pool. This JobStore + will be used if SchedulerFactoryObject's "dbProvider" property is set. + + +

Operations performed by this JobStore will properly participate in any + kind of Spring-managed transaction, as it uses Spring's DataSourceUtils + connection handling methods that are aware of a current transaction.

+ +

Note that all Quartz Scheduler operations that affect the persistent + job store should usually be performed within active transactions, + as they assume to get proper locks etc.

+ + Juergen Hoeller + Marko Lahma (.NET) + + + + + + Name used for the transactional ConnectionProvider for Quartz. + This provider will delegate to the local Spring-managed DataSource. + + + + + + + Gets the non managed TX connection. + + + + + + Closes the connection. + + The connection and transaction holder. + + + + Gets or sets the name of the instance. + + The name of the instance. + + + + Quartz ThreadPool adapter that delegates to a Spring-managed + TaskExecutor instance, specified on SchedulerFactoryObject. + + Juergen Hoeller + + + + + Logger available to subclasses. + + + + + Initializes a new instance of the class. + + + + + Called by the QuartzScheduler before the is + used, in order to give the it a chance to Initialize. + + + + + Called by the QuartzScheduler to inform the + that it should free up all of it's resources because the scheduler is + shutting down. + + + + + + Execute the given in the next + available . + + + + + The implementation of this interface should not throw exceptions unless + there is a serious problem (i.e. a serious misconfiguration). If there + are no available threads, rather it should either queue the Runnable, or + block until a thread is available, depending on the desired strategy. + + + + + Determines the number of threads that are currently available in in + the pool. Useful for determining the number of times + can be called before returning + false. + + + the number of currently available threads + + + The implementation of this method should block until there is at + least one available thread. + + + + + Gets the size of the pool. + + The size of the pool. + + + + Quartz Job implementation that invokes a specified method. + Automatically applied by MethodInvokingJobDetailFactoryObject. + + + + + Simple implementation of the Quartz Job interface, applying the + passed-in JobDataMap and also the SchedulerContext as object property + values. This is appropriate because a new Job instance will be created + for each execution. JobDataMap entries will override SchedulerContext + entries with the same keys. + + +

+ For example, let's assume that the JobDataMap contains a key + "myParam" with value "5": The Job implementation can then expose + a object property "myParam" of type int to receive such a value, + i.e. a method "setMyParam(int)". This will also work for complex + types like business objects etc. +

+ +

+ Note: The QuartzJobObject class itself only implements the standard + Quartz IJob interface. Let your subclass explicitly implement the + Quartz IStatefulJob interface to mark your concrete job object as stateful. +

+ + Juergen Hoeller + + + + + + + + + + + This implementation applies the passed-in job data map as object property + values, and delegates to ExecuteInternal afterwards. + + + + + + Execute the actual job. The job data map will already have been + applied as object property values by execute. The contract is + exactly the same as for the standard Quartz execute method. + + + + + + Invoke the method via the MethodInvoker. + + + + + + Set the MethodInvoker to use. + + + + + IFactoryObject that exposes a JobDetail object that delegates job execution + to a specified (static or non-static) method. Avoids the need to implement + a one-line Quartz Job that just invokes an existing service method. + + +

+ Derived from ArgumentConverting MethodInvoker to share common properties and behavior + with MethodInvokingFactoryObject. +

+

+ Supports both concurrently running jobs and non-currently running + ones through the "concurrent" property. Jobs created by this + MethodInvokingJobDetailFactoryObject are by default volatile and durable + (according to Quartz terminology). +

+

NOTE: JobDetails created via this FactoryObject are not + serializable and thus not suitable for persistent job stores. + You need to implement your own Quartz Job as a thin wrapper for each case + where you want a persistent job to delegate to a specific service method. +

+ + Juergen Hoeller + Alef Arendsen + + + + + + Initializes a new instance of the class. + + + + + Return an instance (possibly shared or independent) of the object + managed by this factory. + + + An instance (possibly shared or independent) of the object managed by + this factory. + + + + If this method is being called in the context of an enclosing IoC container and + returns , the IoC container will consider this factory + object as not being fully initialized and throw a corresponding (and most + probably fatal) exception. + + + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Callback for post-processing the JobDetail to be exposed by this FactoryObject. +

+ The default implementation is empty. Can be overridden in subclasses. +

+ + the JobDetail prepared by this FactoryObject + + + + Set the name of the job. + Default is the object name of this FactoryObject. + + + + + + Set the group of the job. + Default is the default group of the Scheduler. + + + + + + + Specify whether or not multiple jobs should be run in a concurrent + fashion. The behavior when one does not want concurrent jobs to be + executed is realized through adding the interface. + More information on stateful versus stateless jobs can be found + here. +

+ The default setting is to run jobs concurrently. +

+ + + + + Gets the job detail. + + The job detail. + + + + Set a list of JobListener names for this job, referring to + non-global JobListeners registered with the Scheduler. + + + A JobListener name always refers to the name returned + by the JobListener implementation. + + + + + + + Set the name of the object in the object factory that created this object. + + The name of the object in the factory. + + Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. + + + + + Set the name of the target object in the Spring object factory. + + + This is an alternative to specifying TargetObject + allowing for non-singleton objects to be invoked. Note that specified + "TargetObject" and "TargetType" values will + override the corresponding effect of this "TargetObjectName" setting + (i.e. statically pre-define the object type or even the target object). + + + + + Sets the object factory. + + The object factory. + + + + Return the of object that this + creates, or + if not known in advance. + + + + + + Is the object managed by this factory a singleton or a prototype? + + + + + + Adapter that implements the Runnable interface as a configurable + method invocation based on Spring's MethodInvoker. + + +

+ Derives from ArgumentConvertingMethodInvoker, inheriting common + configuration properties from MethodInvoker. +

+ +

+ Useful to generically encapsulate a method invocation as timer task for + java.util.Timer, in combination with a DelegatingTimerTask adapter. + Can also be used with JDK 1.5's java.util.concurrent.Executor + abstraction, which works with plain Runnables. +

+

+ Extended by Spring's MethodInvokingTimerTaskFactoryObject adapter + for TimerTask. Note that you can populate a + ScheduledTimerTask object with a plain MethodInvokingRunnable instance + as well, which will automatically get wrapped with a DelegatingTimerTask. +

+ + Juergen Hoeller + + + + + + Logger instance shared by this instance and its sub-class instances. + + + + + Initializes a new instance of the class. + + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + This method has to be implemented in order that starting of the thread causes the object's + run method to be called in that separately executing thread. + + + + + Gets the invocation failure message. + + The invocation failure message. + + + + Subclass of Quartz' JobSchedulingDataProcessor that considers + given filenames as Spring resource locations. + + Juergen Hoeller + + + + + Initializes a new instance of the class. + + + + + Returns an from the fileName as a resource. + + Name of the file. + + an from the fileName as a resource. + + + + + Sets the + that this object runs in. + + + + Invoked after population of normal objects properties but + before an init callback such as + 's + + or a custom init-method. Invoked before setting + 's + + property. + + + + + Common base class for accessing a Quartz Scheduler, i.e. for registering jobs, + triggers and listeners on a instance. + + + For concrete usage, check out the and + classes. + + Juergen Hoeller + Marko Lahma (.NET) + + + + Logger instance. + + + + + Resource loader instance for sub-classes + + + + + Initializes a new instance of the class. + + + + + Register jobs and triggers (within a transaction, if possible). + + + + + Add the given job to the Scheduler, if it doesn't already exist. + Overwrites the job in any case if "overwriteExistingJobs" is set. + + the job to add + true if the job was actually added, false if it already existed before + + + + Add the given trigger to the Scheduler, if it doesn't already exist. + Overwrites the trigger in any case if "overwriteExistingJobs" is set. + + the trigger to add + true if the trigger was actually added, false if it already existed before + + + + Register all specified listeners with the Scheduler. + + + + + Template method that determines the Scheduler to operate on. + To be implemented by subclasses. + + + + + + Set whether any jobs defined on this SchedulerFactoryObject should overwrite + existing job definitions. Default is "false", to not overwrite already + registered jobs that have been read in from a persistent job store. + + + + + Set the locations of Quartz job definition XML files that follow the + "job_scheduling_data_1_5" XSD. Can be specified to automatically + register jobs that are defined in such files, possibly in addition + to jobs defined directly on this SchedulerFactoryObject. + + + + + + Set the location of a Quartz job definition XML file that follows the + "job_scheduling_data" XSD. Can be specified to automatically + register jobs that are defined in such a file, possibly in addition + to jobs defined directly on this SchedulerFactoryObject. + + + + + + + Register a list of JobDetail objects with the Scheduler that + this FactoryObject creates, to be referenced by Triggers. + This is not necessary when a Trigger determines the JobDetail + itself: In this case, the JobDetail will be implicitly registered + in combination with the Trigger. + + + + + + + + + + Register a list of Quartz ICalendar objects with the Scheduler + that this FactoryObject creates, to be referenced by Triggers. + + Map with calendar names as keys as Calendar objects as values + + + + + + Register a list of Trigger objects with the Scheduler that + this FactoryObject creates. + + + If the Trigger determines the corresponding JobDetail itself, + the job will be automatically registered with the Scheduler. + Else, the respective JobDetail needs to be registered via the + "jobDetails" property of this FactoryObject. + + + + + + + + + + Specify Quartz SchedulerListeners to be registered with the Scheduler. + + + + + Specify global Quartz JobListeners to be registered with the Scheduler. + Such JobListeners will apply to all Jobs in the Scheduler. + + + + + Specify named Quartz JobListeners to be registered with the Scheduler. + Such JobListeners will only apply to Jobs that explicitly activate + them via their name. + + + + + + + + Specify global Quartz TriggerListeners to be registered with the Scheduler. + Such TriggerListeners will apply to all Triggers in the Scheduler. + + + + + Specify named Quartz TriggerListeners to be registered with the Scheduler. + Such TriggerListeners will only apply to Triggers that explicitly activate + them via their name. + + + + + + + + Set the transaction manager to be used for registering jobs and triggers + that are defined by this SchedulerFactoryObject. Default is none; setting + this only makes sense when specifying a DataSource for the Scheduler. + + + + + Sets the + that this object runs in. + + + + Invoked after population of normal objects properties but + before an init callback such as + 's + + or a custom init-method. Invoked before setting + 's + + property. + + + + + Spring class for accessing a Quartz Scheduler, i.e. for registering jobs, + triggers and listeners on a given instance. + + Juergen Hoeller + Marko Lahma (.NET) + + + + + + Template method that determines the Scheduler to operate on. + + + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Finds the scheduler. + + Name of the scheduler. + + + + + Specify the Quartz Scheduler to operate on via its scheduler name in the Spring + application context or also in the Quartz {@link org.quartz.impl.SchedulerRepository}. + + + Schedulers can be registered in the repository through custom bootstrapping, + e.g. via the or + factory classes. + However, in general, it's preferable to use Spring's + which includes the job/trigger/listener capabilities of this accessor as well. + + + + + Return the Quartz Scheduler instance that this accessor operates on. + + + + + Return the Quartz Scheduler instance that this accessor operates on. + + + + + FactoryObject that sets up a Quartz Scheduler and exposes it for object references. + + +

+ Allows registration of JobDetails, Calendars and Triggers, automatically + starting the scheduler on initialization and shutting it down on destruction. + In scenarios that just require static registration of jobs at startup, there + is no need to access the Scheduler instance itself in application code. +

+ +

+ For dynamic registration of jobs at runtime, use a object reference to + this SchedulerFactoryObject to get direct access to the Quartz Scheduler + (). This allows you to create new jobs + and triggers, and also to control and monitor the entire Scheduler. +

+ +

+ Note that Quartz instantiates a new Job for each execution, in + contrast to Timer which uses a TimerTask instance that is shared + between repeated executions. Just JobDetail descriptors are shared. +

+ +

+ When using persistent jobs, it is strongly recommended to perform all + operations on the Scheduler within Spring-managed transactions. + Else, database locking will not properly work and might even break. +

+

+ The preferred way to achieve transactional execution is to demarcate + declarative transactions at the business facade level, which will + automatically apply to Scheduler operations performed within those scopes. + Alternatively, define a TransactionProxyFactoryObject for the Scheduler itself. +

+ + Juergen Hoeller + Marko Lahma (.NET) + + + + + + + Default thread count to be set to thread pool. + + + + + Property name for thread count in thread pool. + + + + + Initializes a new instance of the class. + + + + + Shut down the Quartz scheduler on object factory Shutdown, + stopping all scheduled jobs. + + + + + Template method that determines the Scheduler to operate on. + To be implemented by subclasses. + + + + + + Return an instance (possibly shared or independent) of the object + managed by this factory. + + + An instance (possibly shared or independent) of the object managed by + this factory. + + + + If this method is being called in the context of an enclosing IoC container and + returns , the IoC container will consider this factory + object as not being fully initialized and throw a corresponding (and most + probably fatal) exception. + + + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Load and/or apply Quartz properties to the given SchedulerFactory. + + the SchedulerFactory to Initialize + + + + Merges the properties into map. This effectively also + overwrites existing properties with same key in map. + + The properties to merge into given map. + The map to merge to. + + + + Create the Scheduler instance for the given factory and scheduler name. + Called by afterPropertiesSet. + + + Default implementation invokes SchedulerFactory's GetScheduler + method. Can be overridden for custom Scheduler creation. + + the factory to create the Scheduler with + the name of the scheduler to create + the Scheduler instance + + + + + + Expose the specified context attributes and/or the current + IApplicationContext in the Quartz SchedulerContext. + + + + + Start the Quartz Scheduler, respecting the "startDelay" setting. + + the Scheduler to start + the time span to wait before starting + the Scheduler asynchronously + + + + Starts this instance. + + + + + Stops this instance. + + + + + Handles the application context's refresh event and starts the scheduler. + + + + + Return the IDbProvider for the currently configured Quartz Scheduler, + to be used by LocalDataSourceJobStore. + + + This instance will be set before initialization of the corresponding + Scheduler, and reset immediately afterwards. It is thus only available + during configuration. + + + + + + + Return the TaskExecutor for the currently configured Quartz Scheduler, + to be used by LocalTaskExecutorThreadPool. + + + This instance will be set before initialization of the corresponding + Scheduler, and reset immediately afterwards. It is thus only available + during configuration. + + + + + Set the Quartz SchedulerFactory implementation to use. + + + Default is StdSchedulerFactory, reading in the standard + quartz.properties from Quartz' dll. To use custom Quartz + properties, specify "configLocation" or "quartzProperties". + + The scheduler factory class. + + + + + + + Set the name of the Scheduler to fetch from the SchedulerFactory. + If not specified, the default Scheduler will be used. + + The name of the scheduler. + + + + + + Set the location of the Quartz properties config file, for example + as assembly resource "assembly:quartz.properties". + + + Note: Can be omitted when all necessary properties are specified + locally via this object, or when relying on Quartz' default configuration. + + + + + + Set Quartz properties, like "quartz.threadPool.type". + + + Can be used to override values in a Quartz properties config file, + or to specify all necessary properties locally. + + + + + + Set the Spring TaskExecutor to use as Quartz backend. + Exposed as thread pool through the Quartz SPI. + + + By default, a Quartz SimpleThreadPool will be used, configured through + the corresponding Quartz properties. + + The task executor. + + + + + + Register objects in the Scheduler context via a given Map. + These objects will be available to any Job that runs in this Scheduler. + + + Note: When using persistent Jobs whose JobDetail will be kept in the + database, do not put Spring-managed object or an ApplicationContext + reference into the JobDataMap but rather into the SchedulerContext. + + + Map with string keys and any objects as + values (for example Spring-managed objects) + + + + + + Set the key of an IApplicationContext reference to expose in the + SchedulerContext, for example "applicationContext". Default is none. + Only applicable when running in a Spring ApplicationContext. + + +

+ Note: When using persistent Jobs whose JobDetail will be kept in the + database, do not put an IApplicationContext reference into the JobDataMap + but rather into the SchedulerContext. +

+ +

+ In case of a QuartzJobObject, the reference will be applied to the Job + instance as object property. An "applicationContext" attribute will + correspond to a "setApplicationContext" method in that scenario. +

+ +

+ Note that ObjectFactory callback interfaces like IApplicationContextAware + are not automatically applied to Quartz Job instances, because Quartz + itself is reponsible for the lifecycle of its Jobs. +

+ + The application context scheduler context key. + + + + + Set the Quartz JobFactory to use for this Scheduler. + + +

+ Default is Spring's , which supports + standard Quartz instances. Note that this default only applies + to a local Scheduler, not to a RemoteScheduler (where setting + a custom JobFactory is not supported by Quartz). +

+

+ Specify an instance of Spring's here + (typically as an inner object definition) to automatically populate a job's + object properties from the specified job data map and scheduler context. +

+ + + + + + + Set whether to expose the Spring-managed instance in the + Quartz . Default is "false", since the Spring-managed + Scheduler is usually exclusively intended for access within the Spring context. + + + Switch this flag to "true" in order to expose the Scheduler globally. + This is not recommended unless you have an existing Spring application that + relies on this behavior. + + + + + Set whether to automatically start the scheduler after initialization. + Default is "true"; set this to "false" to allow for manual startup. + + + + + Set the time span to wait after initialization before + starting the scheduler asynchronously. Default is 0, meaning + immediate synchronous startup on initialization of this object. + + + Setting this to 10 or 20 seconds makes sense if no jobs + should be run before the entire application has started up. + + + + + Set whether to wait for running jobs to complete on Shutdown. + Default is "false". + + + true if [wait for jobs to complete on Shutdown]; otherwise, false. + + + + + + Set the default DbProvider to be used by the Scheduler. If set, + this will override corresponding settings in Quartz properties. + + +

+ Note: If this is set, the Quartz settings should not define + a job store "dataSource" to avoid meaningless double configuration. +

+

+ A Spring-specific subclass of Quartz' JobStoreSupport will be used. + It is therefore strongly recommended to perform all operations on + the Scheduler within Spring-managed transactions. + Else, database locking will not properly work and might even break + (e.g. if trying to obtain a lock on Oracle without a transaction). +

+ + + + + + + Set the name of the object in the object factory that created this object. + + The name of the object in the factory. + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + + + Gets a value indicating whether this is running. + + true if running; otherwise, false. + + + + Sets the that this + object runs in. + + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Return the of object that this + creates, or + if not known in advance. + + + + + + Is the object managed by this factory a singleton or a prototype? + + + + + + Generic scheduling exception. + + + + + Initializes a new instance of the class. + + The message. + + + + Initializes a new instance of the class. + + The message. + The original exception. + + + + Subclass of Quartz's SimpleThreadPool that implements Spring's + TaskExecutor interface and listens to Spring lifecycle callbacks. + + Juergen Hoeller + + + + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Executes the specified task. + + The task. + + + + Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. + + + + + Set whether to wait for running jobs to complete on Shutdown. + Default is "false". + + + true if [wait for jobs to complete on shutdown]; otherwise, false. + + + + + This task executor prefers short-lived work units. + + + + Convenience subclass of Quartz's + class, making properties based usage easier. + + +

+ SimpleTrigger itself is already a PONO but lacks sensible defaults. + This class uses the Spring object name as job name, the Quartz default group + ("DEFAULT") as job group, the current time as start time, and indefinite + repetition, if not specified. +

+ +

+ This class will also register the trigger with the job name and group of + a given . This allows + to automatically register a trigger for the corresponding JobDetail, + instead of registering the JobDetail separately. +

+ + Juergen Hoeller + + + + + + + + + + + + + Initializes a new instance of the class. + + + + + Invoked by an + after it has injected all of an object's dependencies. + + +

+ This method allows the object instance to perform the kind of + initialization only possible when all of it's dependencies have + been injected (set), and to throw an appropriate exception in the + event of misconfiguration. +

+

+ Please do consult the class level documentation for the + interface for a + description of exactly when this method is invoked. In + particular, it is worth noting that the + + and + callbacks will have been invoked prior to this method being + called. +

+ + + In the event of misconfiguration (such as the failure to set a + required property) or if initialization fails. + + + + + Register objects in the JobDataMap via a given Map. +

+ These objects will be available to this Trigger only, + in contrast to objects in the JobDetail's data map. +

+ + + + + + Set the misfire instruction via the name of the corresponding + constant in the SimpleTrigger class. + Default is . + + + + + + + + + + + Set the delay before starting the job for the first time. + The given time span will be added to the current + time to calculate the start time. Default is . + + + This delay will just be applied if no custom start time was + specified. However, in typical usage within a Spring context, + the start time will be the container startup time anyway. + Specifying a relative delay is appropriate in that case. + + + + + + Set the name of the object in the object factory that created this object. + + The name of the object in the factory. + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + + + Set the JobDetail that this trigger should be associated with. +

+ This is typically used with a object reference if the JobDetail + is a Spring-managed object. Alternatively, the trigger can also + be associated with a job by name and group. +

+ + + + + Adapts Spring's to Quartz's + . + + + + + Initializes a new instance of the class. + + The Spring db provider. + + + + Creates the command. + + + + + + Creates the command builder. + + + + + + Creates the connection. + + + + + + Creates the parameter. + + + + + + Shutdowns this instance. + + + + + Gets or sets the connection string. + + The connection string. + + + + Gets the metadata. + + The metadata. + + + + Helper class to map between Quartz and Spring DB metadata. + + + + + Initializes a new instance of the class. + + The metadata to wrap and adapt. + + + + Gets or sets the name of the product. + + The name of the product. + + + + Gets or sets the type of the connection. + + The type of the connection. + + + + Gets or sets the type of the command. + + The type of the command. + + + + Gets or sets the type of the parameter. + + The type of the parameter. + + + + Gets or sets the type of the command builder. + + The type of the command builder. + + + + Gets or sets the command builder derive parameters method. + + The command builder derive parameters method. + + + + Gets or sets the parameter name prefix. + + The parameter name prefix. + + + + Gets or sets the type of the exception. + + The type of the exception. + + + + Gets or sets a value indicating whether [bind by name]. + + true if [bind by name]; otherwise, false. + + + + Gets or sets the type of the parameter db. + + The type of the parameter db. + + + + Gets or sets the parameter db type property. + + The parameter db type property. + + + + Gets or sets the parameter is nullable property. + + The parameter is nullable property. + + + + Gets the type of the db binary. + + The type of the db binary. + + + + Gets or sets a value indicating whether [use parameter name prefix in parameter collection]. + + + true if [use parameter name prefix in parameter collection]; otherwise, false. + + + + + Subclass of AdaptableJobFactory that also supports Spring-style + dependency injection on object properties. This is essentially the direct + equivalent of Spring's QuartzJobObject in the shape of a + Quartz JobFactory. + + + Applies scheduler context, job data map and trigger data map entries + as object property values. If no matching object property is found, the entry + is by default simply ignored. This is analogous to QuartzJobObject's behavior. + + Juergen Hoeller + + + + + + Create the job instance, populating it with property values taken + from the scheduler context, job data map and trigger data map. + + + + + Return whether the given job object is eligible for having + its object properties populated. +

+ The default implementation ignores QuartzJobObject instances, + which will inject object properties themselves. +

+ + + The job object to introspect. + + + + + + Specify the unknown properties (not found in the object) that should be ignored. + + + Default is null, indicating that all unknown properties + should be ignored. Specify an empty array to throw an exception in case + of any unknown properties, or a list of property names that should be + ignored if there is no corresponding property found on the particular + job class (all other unknown properties will still trigger an exception). + + + + + Set the SchedulerContext of the current Quartz Scheduler. + + + + + + + Extension of the MethodInvokingJob, implementing the StatefulJob interface. + Quartz checks whether or not jobs are stateful and if so, + won't let jobs interfere with each other. + + + + + Summary description for TaskRejectedException. + + + + + Exception that wraps an exception thrown from a target method. + Propagated to the Quartz scheduler from a Job that reflectively invokes + an arbitrary target method. + + Juergen Hoeller + + + + + Constructor for JobMethodInvocationFailedException. + + the MethodInvoker used for reflective invocation + the root cause (as thrown from the target method) + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Services.dll b/Resources/Libraries/Spring.NET/Spring.Services.dll new file mode 100644 index 00000000..1836814d Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Services.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Services.pdb b/Resources/Libraries/Spring.NET/Spring.Services.pdb new file mode 100644 index 00000000..c0aa150d Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Services.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Services.xml b/Resources/Libraries/Spring.NET/Spring.Services.xml new file mode 100644 index 00000000..369778a6 --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Services.xml @@ -0,0 +1,2127 @@ + + + + Spring.Services + + + + + Exports components as ServicedComponents using the specified s. + + + + This class will create ServicedComponent wrapper for each of the + specified components and register them with the Component Services. + + + First you need to generate and register your components. This is done by writing a simple e.g. console application using a configuration as shown below: + + <!-- actual objects 'calculatorService' and 'simpleCalculatorService' are defined elsewhere --> + + <!-- Define the component for exporting 'calculatorService' --> + <object id="calculatorComponent" type="Spring.EnterpriseServices.ServicedComponentExporter, + Spring.Services"> + <property name="TargetName" value="calculatorService" /> + <property name="TypeAttributes"> + <list> + <object type="System.EnterpriseServices.TransactionAttribute, System.EnterpriseServices" /> + </list> + </property> + <property name="MemberAttributes"> + <dictionary> + <entry key="*"> + <list> + <object type="System.EnterpriseServices.AutoCompleteAttribute, System.EnterpriseServices" /> + </list> + </entry> + </dictionary> + </property> + </object> + + <!-- Define the component for exporting 'simpleCalculatorService' --> + <object id="simpleCalculatorComponent" type="Spring.EnterpriseServices.ServicedComponentExporter, + Spring.Services"> + <property name="TargetName" value="simpleCalculatorService" /> + </object> + + <!-- Export components into assembly and autoregister with COM+ --> + <object type="Spring.EnterpriseServices.EnterpriseServicesExporter, Spring.Services"> + <!-- assembly name to generated - will generate 'Spring.Calculator.EnterpriseServices.dll' --> + <property name="Assembly" value="Spring.Calculator.EnterpriseServices" /> + + <!-- + use Spring's ContextRegistry for managing services. If true, requires a file + 'Spring.Calculator.EnterpriseServices.dll.spring-context.xml' containing a + <spring/context /> section placed next to the generated assembly. + --> + <property name="UseSpring" value="true" /> + + <property name="ApplicationName" value="Spring Calculator Application" /> + <property name="ActivationMode" value="Library" /> + <property name="Description" value="Spring Calculator application" /> + <property name="Components"> + <list> + <ref object="calculatorComponent" /> + <ref object="simpleCalculatorComponent" /> + </list> + </property> + </object> + + + + To load your objectdefinitions at runtime of the components, place a configuration file next to the assembly + generated by the exporter, using the filename of the exported assembly, postfixing it with '.spring-context.config'. + Taking the example above, the file must be named 'Spring.Calculator.EnterpriseServices.dll.spring-context.xml' and look like: + + <-- --> + <spring> + <context> + <resource uri="Config/services.xml" /> + </context> + </spring> + + This file should point to the service object definitions you exported using with a + configuration as shown above. + + + + Aleksandar Seovic + Erich Eichinger + + + + Creates new enterprise services exporter. + + + + + Called by Spring container after object is configured in order to initialize it. + + + + + Creates ServicedComponent wrappers for the specified components and registers + them with COM+ Component Services. + + + + + Generates all configured to the given assembly. + + + + + Generates service types from the list of instances + into the given assembly. + + the module to export types to + the object factory to resolve target types + the list of instances. + whether to generate context lookups, + + + + + + + + + + + + + + + + Reads key pair from embedded resource. + + Key pair as a byte array. + + + + Applies custom attributes to generated assembly. + + Dynamic assembly to apply attributes to. + + + + Replaces roles expressed using string with appropriate SecurityRoleAttribute instance. + + + + + Parses string representation of SecurityRoleAttribute. + + Role definition string. + Configured SecurityRoleAttribute instance. + + + + Creates the SpringServicedComponent base class to derive all s from. + + + + internal class SpringServicedComponent: BaseType + { + protected delegate object GetObjectHandler(ServicedComponent servicedComponent, string targetName); + + protected static readonly GetObjectHandler getObjectRef; + + static SpringServicedComponent() + { + // first look for a local copy + System.Reflection.Assembly servicesAssembly; + string servicesAssemblyPath = Path.Combine( + new FileInfo(System.Reflection.Assembly.GetExecutingAssembly().Location).DirectoryName + , "Spring.Services.dll" ); + servicesAssembly = System.Reflection.Assembly.LoadFrom(servicesAssemblyPath); + if (servicesAssembly == null) + { + // then let the normal loader handle the typeload + servicesAssembly = System.Reflection.Assembly.Load("Spring.Services, culture=neutral, version=x.x.x.x, publicKey=xxxxxxxx"); + } + + Type componentHelperType = servicesAssembly.GetType("Spring.EnterpriseServices.ServicedComponentHelper"); + getObjectRef = (GetObjectHandler) Delegate.CreateDelegate(typeof(GetObjectHandler) + , componentHelperType.GetMethod("GetObject")); + } + } + + + + + + Gets or sets list of components to export. + + + + + Gets or sets COM+ application name. + + + + + Gets or sets application identifier (GUID). Defaults to generated GUID if not specified. + + + + + Gets or sets application activation mode, which can be either Server or Library (default). + + + + + Gets or sets application description. + + + + + Gets or sets access control attribute. + + + + + Gets or sets application queuing attribute. + + + + + Gets or sets application roles. + + + + + Gets or sets name of the generated assembly that will contain serviced components. + + + + + Use Spring context to configure the serviced components within COM. + + + + + Sets object factory instance. + + + + + SUBJECT TO CHANGE -FOR INTERNAL USE ONLY!
+ Holds configuration information from a given configuration file, obtained by . + You may use to replace the active configuration system. + + + + + + + initializes this instance with a path to be passed into + + + + + + Purges cached configuration + + + + + Set the nested configuration system to delegate calls in case we can't resolve a config section ourselves + + + + + Get the specified section + + + + + + + Only true if the underlying config system supports this. + + + + + Handles loading of <spring/context> configuration sections for + in-process s generated by + . + + Erich Eichinger + + + + Prevent auto-registering the context with the global ContextRegistry + + + + + Encapsulates information necessary to create ServicedComponent + wrapper around target class. + + + + Instances of this class should be used as elements in the Components + list of the class, which will + register them with COM+ Services. For a full description on how to export + and use services with COM+, see the reference. + + + + Aleksandar Seovic + Erich Eichinger + + + + Creates a new instance of the + class. + + + + + Validate configuration. + + + + + Creates ServicedComponent wrapper around target class. + + Dynamic module builder to use + + Type of the exported object. + whether to generate lookups in ContextRegistry for each service method call or use a 'new'ed target instance + + if is true, each ServicedComponent method call will look similar to + + class MyServicedComponent { + void MethodX() { + ContextRegistry.GetContext().GetObject("TargetName").MethodX(); + } + } + +
+ if is false, the instance will be simply created at component activation using 'new': + + class MyServicedComponent { + TargetType target = new TargetType(); + + void MethodX() { + target.MethodX(); + } + } + +
+ The differences are of course that in the former case, the target lifecycle is entirely managed by Spring, thus avoiding + issues with ServiceComponent activation/deactivation as well as removing the need for default constructors. + + + + + Gets or sets name of the target object that should be exposed as a serviced component. + + + + + Gets or sets the list of interfaces whose methods should be exported. + + + The default value of this property is all the interfaces + implemented or inherited by the target type. + + The interfaces to export. + + + + Gets or sets a list of custom attributes + that should be applied to a proxy class. + + + + + Gets or sets a dictionary of custom attributes + that should be applied to proxy members. + + + Map key is an expression that members can be matched against. Value is a list + of attributes that should be applied to each member that matches expression. + + + + + Set the name of the object in the object factory + that created this object. + + + + + Suppress output to avoid Spring.Core dependency + + + + + Implements default constructor for the proxy class. + + + + + Generates the IL instructions that pushes + the target instance on which calls should be delegated to. + + The IL generator to use. + + + + Factory Object that instantiates and configures ServicedComponent. + + +

+ This factory object should be used to instantiate and configure + serviced components created by . +

+ + Aleksandar Seovic + + + + Creates new instance of serviced component factory. + + + + + Returns configured instance of the serviced component. + + Configured instance of the serviced component. + + + + Initializes factory object. + + + + + Creates new instance of serviced component. + + New instance of serviced component. + + + + Gets or sets component name, as registered with COM+ Services. + + + + + Gets or sets name of the remote server that COM+ component is registered with. + + + + + Returns type of serviced component. + + + + + Gets or sets whether serviced component should be treated as singleton. Default is false. + + + + + Gets or sets the template object definition + that should be used to configure proxy instance. + + + + + This class supports s exported using . + and must never be used directly. + + Erich Eichinger + + + + Reads in the 'xxx.spring-context.xml' configuration file associated with the specified . + See for an in-depth description on how to export and configure COM+ components. + + + + + Called by a exported by + to obtain a reference to the service it proxies. + + + + + Implementation of the custom configuration parser for remoting definitions. + + Bruno Baia + + + + Initializes a new instance of the class. + + + + + Parse the specified element and register any resulting + IObjectDefinitions with the IObjectDefinitionRegistry that is + embedded in the supplied ParserContext. + + The element to be parsed into one or more IObjectDefinitions + The object encapsulating the current state of the parsing + process. + + The primary IObjectDefinition (can be null as explained above) + + + Implementations should return the primary IObjectDefinition + that results from the parse phase if they wish to used nested + inside (for example) a <property> tag. + Implementations may return null if they will not + be used in a nested scenario. + + + + + + Parses remoting definitions. + + Validator XML element. + The name of the object definition. + The parser context. + A remoting object definition. + + + + Parses the RemotingConfigurer definition. + + The element to parse. + The name of the object definition. + The parser context. + RemotingConfigurer object definition. + + + + Parses the SaoFactoryObject definition. + + The element to parse. + The name of the object definition. + The parser context. + SaoFactoryObject object definition. + + + + Parses the CaoFactoryObject definition. + + The element to parse. + The name of the object definition. + The parser context. + CaoFactoryObject object definition. + + + + Parses the RemoteObjectFactory definition. + + The element to parse. + The name of the object definition. + The parser context. + RemoteObjectFactory object definition. + + + + Parses the SaoExporter definition. + + The element to parse. + The name of the object definition. + The parser context. + SaoExporter object definition. + + + + Parses the CaoExporter definition. + + The element to parse. + The name of the object definition. + The parser context. + CaoExporter object definition. + + + + Parses the LifeTime definition. + + + + + Gets the name of the object type for the specified element. + + The element. + The name of the object type. + + + + This class extends to allow users + to define object lifecycle details by simply setting its properties. + + +

+ Remoting exporters uses this class as a base proxy class + in order to support lifecycle configuration when exporting + a remote object. +

+ + Aleksandar Seovic + + + + Initializes a new instance of the class. + + + + + Obtains a lifetime service object to control the lifetime policy for this instance. + + +

+ This method uses property values to configure for this object. +

+

+ It is very much inspired by Ingo Rammer's example in Chapter 6 of "Advanced .NET Remoting", + but is modified slightly to make it more "Spring-friendly". Basically, the main difference is that + instead of pulling lease configuration from the .NET config file, this implementation relies + on Spring DI to get appropriate values injected, which makes it much more flexible. +

+ + + An object of type used to control the + lifetime policy for this instance. This is the current lifetime service object for + this instance if one exists; otherwise, a new lifetime service object initialized to the value + of the property. + + The immediate caller does not have infrastructure permission. + + + + Gets or sets a value indicating whether this instance has infinite lifetime. + + + if this instance has infinite lifetime; + otherwise, . + + + + + Gets or sets the initial lease time. + + The initial lease time. + + + + Gets or sets the amount of time lease should be + extended for on each call to this object. + + The amount of time lease should be + extended for on each call to this object. + + + + Gets or sets the amount of time lease manager will for this object's + sponsors to respond. + + The amount of time lease manager will for this object's + sponsors to respond. + + + + Configurable implementation of the interface. + + Bruno Baia + + + + Defines lifetime's properties of remote objects that is used by Spring. + + Bruno Baia + + + + Gets or sets a value indicating whether this instance has infinite lifetime. + + + true if this instance has infinite lifetime; otherwise, false. + + + + + Gets the initial lease time. + + The initial lease time. + + + + Gets the amount of time lease + should be extended for on each call to this object. + + The amount of time lease should be + extended for on each call to this object. + + + + Gets the amount of time lease manager + will for this object's sponsors to respond. + + The amount of time lease manager will for this object's + sponsors to respond. + + + + Gets or sets a value indicating whether this instance has infinite lifetime. + + + true if this instance has infinite lifetime; otherwise, false. + + + + + Gets or sets the initial lease time. + + The initial lease time. + + + + Gets or sets the amount of time lease + should be extended for on each call to this object. + + The amount of time lease should be + extended for on each call to this object. + + + + Gets or sets the amount of time lease manager + will for this object's sponsors to respond. + + The amount of time lease manager will for this object's + sponsors to respond. + + + + Interface for a CAO based object factory. + + +

+ Provides a well known location for clients to retrieve + references to CAO references. +

+ + Aleksandar Seovic + Mark Pollack + Bruno Baia + + + + Returns the CAO proxy. + + The remote object. + + + + Returns the CAO proxy using the + argument list to call the constructor. + + + The matching of arguments to call the constructor is done + by type. The alternative ways, by index and by constructor + name are not supported. + + Constructor + arguments used to create the object. + The remote object. + + + + Builds a proxy type based on to wrap a target object + that is intended to be remotable. + + Bruno Baia + + + + Creates a new instance of the + class. + + + The lifetime properties to be applied to the target object. + + + + + Creates a remotable proxy type based on . + + The generated proxy class. + + If the is not + an instance of . + + + + + Implements constructors for the proxy class. + + + The to use. + + + + + Generate initialization code for 's lifetime properties. + + ILGenerator + + + + Registers an object type on the server + as a Client Activated Object (CAO). + + Aleksandar Seovic + Mark Pollack + Bruno Baia + + + + Creates a new instance of the class. + + + + + Publish the object + + + + + Disconnect the remote object from the registered remoting channels. + + + + + Gets or sets the name of the target object definition. + + + + + Gets or sets the list of interfaces whose methods should be exported. + + + The default value of this property is all the interfaces + implemented or inherited by the target type. + + The interfaces to export. + + + + Sets the that this + object runs in. + + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Sets object factory to use. + + + + + This class extends to allow CAOs + to be disconnect from the client. + + + + + Create a new instance of the RemoteFactory. + + + + + Returns the CAO proxy. + + The remote object. + + + + Returns the CAO proxy using the + argument list to call the constructor. + + + The matching of arguments to call the constructor is done + by type. The alternative ways, by index and by constructor + name are not supported. + + Constructor + arguments used to create the object. + The remote object. + + + + Set infinite lifetime. + + + + + Factory for creating a reference to a + client activated object (CAO). + + Aleksandar Seovic + Mark Pollack + Bruno Baia + + + + Creates a new instance of the class. + + + + + Callback method called once all factory properties have been set. + + if an error occured + + + + Return the CAO proxy. + + the CAO proxy + + + + The remote target name to activate. + + + + + The Uri of the remote type. + + + + + Argument list used to call the CAO constructor. + + + + + Always return false. + + + + + The type of object to be created. + + + + + Factory for creating MarshalByRefObject wrapper around target class. + + Bruno Baia + + + + Creates a new instance of the MarshalByRefObjectFactory. + + + + + Initializes factory object. + + + + + Creates new instance of the remotable target proxy. + + New instance of the remotable target proxy. + + + + Gets or sets the target object. + + + + + Gets or sets the class or subclass + that the proxy must inherit from. + + + + + Gets or sets the list of interfaces to wrap. + + + The default value of this property is all the interfaces + implemented or inherited by the target type. + + The interfaces to export. + + + + Returns type of the remotable target proxy. + + + + + Always returns false. + + + + + Convenience class to configure remoting infrastructure from the IoC container. + + Bruno Baia + + + + Initializes a new instance of the class. + + + + + Modify the application context's internal object factory after its + standard initialization. + + + The object factory used by the application context. + + + + + + Gets or sets the name of the remoting configuration file. + + + If filename is or not set, + current AppDomain's configuration file will be used. + + + + + Indicates whether a configuration file is used. + Default value is . + + + If , default remoting configuration will be used. + + + + + Gets or sets if security is enabled. + + + This property is only available since .NET Framework 2.0. + + + + + Return the order value of this object, + where a higher value means greater in terms of sorting. + + + + + Publishes an instance of an object under + a given url as a Server Activated Object (SAO). + + + Remoting servers exported by always correspond to . + Objects can be exported either as SingleCall or Singleton by marking the exported object identified by + as either singleton or prototype. + + Aleksandar Seovic + Mark Pollack + Bruno Baia + Erich Eichinger + + + + Holds EXPORTER_ID to SaoExporter instance mappings. + + + + + Returns the target object instance exported by the SaoExporter identified by . + + + + + + + Creates a new instance of the class. + + + + + Cleanup before GC + + + + + Publish the object + + + + + Disconnect the remote object from the registered remoting channels. + + + + + Stops exporting the object identified by . + + true to release both managed and unmanaged resources; false to release only unmanaged resources. + + + + Gets or sets the name of the target object definition. + + + + + Gets or sets the name of the remote application. + + + + + Gets or sets the name of the exported remote service. + + The name that will be used in the URI to refer to this service. + This will be of the form, tcp://host:port/ServiceName or + tcp://host:port/ApplicationName/ServiceName + + + + + + Gets or sets the list of interfaces whose methods should be exported. + + + The default value of this property is all the interfaces + implemented or inherited by the target type. + + The interfaces to export. + + + + Sets object factory to use. + + + + + Builds a proxy type based on to wrap a target object + that is intended to be remotable. + + + The wrapped target object is retrieved by name from the IoC container. + + + + + Creates a new instance of the + class. + + + The exporter to be associated with the proxy. + + + + + Generates the IL instructions that pushes + the target instance on which calls should be delegated to. + + The IL generator to use. + + + + Implements constructors for the proxy class. + + + The to use. + + + + + Deaclares a field that holds the target object instance. + + + The builder to use for code generation. + + + + + Factory for creating a reference to a + remote server activated object (SAO). + + + This is useful alternative to adminstrative type registration on + the client when you would like the client to have only + a reference to the interface that an SAO implements and not the + actual SAO implentation. + + Aleksandar Seovic + Mark Pollack + Bruno Baia + + + + Creates a new instance of the SaoFactoryObject class. + + + + + Callback method called once all factory properties have been set. + + if an error occured + + + + Return the SAO proxy. + + the SAO proxy + + + + The remote service interface. + + + + + The URI of the well known object + + + + + Is the object managed by this factory a singleton or a prototype? + + + + + The type of object to be created. + + + + + Factory that provides instances of + to host objects created by Spring's IoC container. + + Bruno Baia + + + + Creates a for + a specified Spring-managed object with a specific base address. + + + A reference to a Spring-managed object or to a service type. + + + The of type that contains + the base addresses for the service hosted. + + + A for the Spring-managed object. + + + If the Service attribute in the ServiceHost directive was not provided. + + + + + Factory that provides instances of + to host objects created with Spring's IoC container. + + Bruno Baia + + + + The owning factory. + + + + + The instance managed by this factory. + + + + + Creates a new instance of the + class. + + + + + Return a instance + managed by this factory. + + + An instance of + managed by this factory. + + + + + Publish the object. + + + + + Close the SpringServiceHost + + + + + Validates the configuration. + + + + + Gets or sets the name of the target object that should be exposed as a service. + + + The name of the target object that should be exposed as a service. + + + + + Gets or sets the base addresses for the hosted service. + + + The base addresses for the hosted service. + + + + + Controls, whether the underlying should cache + the generated proxy types. Defaults to true. + + + + + Callback that supplies the owning factory to an object instance. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + In case of initialization errors. + + + + + Return the of object that this + creates. + + + + + Always returns + + + + + Factory that provides instances of + to host objects created by Spring's IoC container. + + Steve Bohlen + + + + Creates a for + a specified Spring-managed object with a specific base address. + + + A reference to a Spring-managed object or to a service type. + + + The of type that contains + the base addresses for the service hosted. + + + A for the Spring-managed object. + + + If the Service attribute in the ServiceHost directive was not provided. + + + + + The for the <wcf:channelFactory> tag. + + Bruno Baia + + + + Parse the specified XmlElement and register the resulting + ObjectDefinitions with the IObjectDefinitionRegistry + embedded in the supplied + + The element to be parsed. + The object encapsulating the current state of the parsing process. + Provides access to a IObjectDefinitionRegistry + The primary object definition. + +

+ This method is never invoked if the parser is namespace aware + and was called to process the root node. +

+ + + + + Namespace parser for the WCF namespace. + + Bruno Baia + + + + Register the for the WCF tags. + + + + + Builds a WCF service type. + + Bruno Baia + + + + Target instance calls should be delegated to. + + + + + Creates a new instance of the + class. + + The name of the service within Spring's IoC container. + The to use. + Whether to cache the generated service proxy type. + + + + Creates a new instance of the + class. + + The name of the service within Spring's IoC container. + The name of the generated WCF service . + The to use. + Whether to cache the generated service proxy type. + + + + Creates a proxy that delegates calls to an instance of the target object. + This overriden implementation caches the generated proxy type + and sets the '__objectFactory' field. + + + If the + does not implement any interfaces. + + + + + Implements constructors for the proxy class. + + + This implementation generates a constructor + that gets instance of the target object using + . + + + The builder to use. + + + + + Creates an appropriate type builder. Add a field to hold a reference to the application context. + + The name to use for the proxy type name. + The type to extends if provided. + The type builder to use. + + + + that creates a channel that is used by clients + to send messages to a specified endpoint address. + + The type of channel produced by the channel factory. + Bruno Baia + + + + Creates a new instance of the class. + + + The configuration name used for the endpoint. + + + + + Return an instance (possibly shared or independent) of the channel + managed by this factory. + + + An instance (possibly shared or independent) of the channel managed by + this factory. + + + + + Gets the configuration name used for the endpoint. + + + + + Return the of channel that this + creates. + + + + + Is the object managed by this factory a singleton or a prototype ? + + + Default value is . + + + + + Exports an object as a WCF service. + + Bruno Baia + + + + The name of the object in the factory. + + + + + The owning factory. + + + + + The generated WCF service wrapper type. + + + + + Creates a new instance of the class. + + + + + Publish the object + + + + + Return an instance (possibly shared or independent) of the object + managed by this factory. + + + + If this method is being called in the context of an enclosing IoC container and + returns , the IoC container will consider this factory + object as not being fully initialized and throw a corresponding (and most + probably fatal) exception. + + + + An instance (possibly shared or independent) of the object managed by + this factory. + + + + + Validates the configuration. + + + + + Generates the WCF service wrapper type. + + + + + Gets or sets the name of the target object definition. + + + + + Gets or sets the service contract interface type. + + + If not set, uses the unique interface implemented or inherited by the target type. + An error will be thrown if the target type implements more than one interface. + + The service contract interface type. + + + + Gets or sets a list of custom attributes + that should be applied to the WCF service class. + + + + + Gets or sets a dictionary of custom attributes + that should be applied to the WCF service members. + + + Dictionary key is an expression that members can be matched against. + Value is a list of attributes that should be applied + to each member that matches expression. + + + + + Controls, whether the underlying should cache + the generated proxy types. Defaults to true. + + + + + Gets or sets the name for the <portType> element in + Web Services Description Language (WSDL). + + + The default value is the name of the class or interface to which the + System.ServiceModel.ServiceContractAttribute is applied. + + + + + Gets or sets the namespace of the <portType> element in + Web Services Description Language (WSDL). + + + The WSDL namespace of the <portType> element. The default value is "http://tempuri.org". + + + + + Gets or sets the name used to locate the service in an application configuration file. + + + The name used to locate the service element in an application configuration file. + The default is the name of the service implementation class. + + + + + Gets or sets the type of callback contract when the contract is a duplex contract. + + + A that indicates the callback contract. The default is null. + + + + + Specifies whether the binding for the contract must support the value of + the ProtectionLevel property. + + + One of the values. + The default is . + + + + + Gets or sets whether sessions are allowed, not allowed or required. + + + A that indicates whether sessions are allowed, + not allowed, or required. + + + + + Callback that supplies the owning factory to an object instance. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + In case of initialization errors. + + + + + Return the of object that this + creates, or + if not known in advance. + + + + + Is the object managed by this factory a singleton or a prototype? + + + + + Set the name of the object in the object factory that created this object. + + + The name of the object in the factory. + + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + + + Builds a WCF service type. + + + + + Applies attributes to the proxy class. + + The type builder to use. + The proxied class. + + + + + + Provides a host for Spring-managed services. + + Bruno Baia + + + + Creates a new instance of the class. + + The name of the service within Spring's IoC container. + The base addresses for the hosted service. + + + + Creates a new instance of the class. + + The name of the service within Spring's IoC container. + The name of the Spring context to use. + The base addresses for the hosted service. + + + + Creates a new instance of the class. + + The name of the service within Spring's IoC container. + The to use. + The base addresses for the hosted service. + + + + Creates a new instance of the class. + + The name of the service within Spring's IoC container. + The to use. + Whether to cache the generated service proxy type. + The base addresses for the hosted service. + + + + Provides a host for Spring-managed services. + + Bruno Baia + + + + Creates a new instance of the class. + + The name of the service within Spring's IoC container. + The base addresses for the hosted service. + + + + Creates a new instance of the class. + + The name of the service within Spring's IoC container. + The name of the Spring context to use. + The base addresses for the hosted service. + + + + Creates a new instance of the class. + + The name of the service within Spring's IoC container. + The to use. + The base addresses for the hosted service. + + + + Creates a new instance of the class. + + The name of the service within Spring's IoC container. + The to use. + Whether to cache the generated service proxy type. + The base addresses for the hosted service. + + + + Factory Object that dynamically implements service interface for web service. + + +

+ This factory object should be used to obtain reference to a web service + that can be safely cast to a service interface, which allows client code to code + against interface, and not directly against the web service. +

+

+ The WSDL contract needs to conform to WS-I Basic Profiles. +

+ + Bruno Baia + Aleksandar Seovic + + + + The web service proxy default constructor. + + + + + Creates a new instance of the + class. + + + + + Creates new instance of the web service proxy. + + New instance of the web service proxy. + + + + Initializes factory object. + + + + + Validates the configuration. + + + + + Generates the web service proxy type. + + + + + Gets XML Web Services documents from a Spring resource. + + + + + Gets or sets the base type that web service proxy should inherit. + + + Default is + + + + + Gets or sets the URI for an + that contains the web service description (WSDL). + + + + + Gets or sets type of the proxy class to wrap. + + + + + Gets or sets service interface that proxy should implement. + + + + + Gets or sets the instance + to use when connecting to a server that requires authentication. + + + + + Gets or sets the url of the proxy server to use for retrieving the WSDL. + + +

+ This only applies when using an as uri. +

+

+ The default is to use the system proxy setting. +

+ + + + + Gets or sets the instance + to use when connecting to a proxy server that requires authentication. + + +

+ This only applies when using an as uri. +

+ + + + + Gets or sets the web service binding name to use for the proxy. + + + + + Gets or sets a list of custom attributes + that should be applied to a proxy class. + + + + + Gets or sets a dictionary of custom attributes + that should be applied to web service members. + + + Dictionary key is an expression that members can be matched against. + Value is a list of attributes that should be applied + to each member that matches expression. + + + + + Returns type of the web service proxy. + + + + + Always returns false. + + + + + Gets or sets the template object definition + that should be used to configure proxy instance. + + + + + Proxy type builder that can be used to create a proxy for + derived classes. + + + + + Creates a new instance of the + class. + + The URI that contains the Web Service meta info (WSDL). + The XML Web Service documents to use to create the proxy. + The name of the Web Service binding to use. + + + + Creates the proxy type. + + The generated proxy class. + + + + Generates the IL instructions that pushes + the target instance on which calls should be delegated to. + + The IL generator to use. + + + + Implements constructors for the proxy class. + + + The to use. + + + + + Search and returns the binding for the specified name. + + + + + Search and returns the url for the specified binding. + + + + + Search and returns the operation that matches the specified method. + + + + + Search and returns the OperationBinding that matches the specified Operation. + + + + + Search and returns the type mapping between method parameters/return value + and the element parts of a literal-use SOAP message. + + + + + Creates a that should be applied to proxy type. + + + + + Creates a or a + that should be applied to proxy method. + + + + + Proxy method builder that can be used to create a proxy method + for web services operation invocation. + + + + + Creates a new instance of the method builder. + + The type builder to use. + + The implementation to use. + + + + + Generates the proxy method. + + The IL generator to use. + The method to proxy. + + The interface definition of the method, if applicable. + + + + + Proxy type builder that can be used to create a proxy for + .Net-generated proxy class that can be safely cast to a service interface. + + + + + Creates a new instance of the + class. + + + + + Gets the mapping of the interface to proxy + into the actual methods on the target type + that does not need to implement that interface. + + +

+ As the proxy type does not implement the interface, + we try to find matching methods. +

+ + + The of the target object. + + The interface to implement. + + An interface mapping for the interface to proxy. + + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Template.Velocity.dll b/Resources/Libraries/Spring.NET/Spring.Template.Velocity.dll new file mode 100644 index 00000000..3d590db8 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Template.Velocity.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Template.Velocity.pdb b/Resources/Libraries/Spring.NET/Spring.Template.Velocity.pdb new file mode 100644 index 00000000..6eba2878 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Template.Velocity.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Template.Velocity.xml b/Resources/Libraries/Spring.NET/Spring.Template.Velocity.xml new file mode 100644 index 00000000..d79c57ec --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Template.Velocity.xml @@ -0,0 +1,698 @@ + + + + Spring.Template.Velocity + + + + + Implementation of the custom configuration parser for template configurations + based on + + + Erez Mazor + + + + + Initializes a new instance of the class. + + + + + + + + Parse a template definition from the templating namespace + + the root element defining the templating object + the parser context + + + + + Parses the object definition for the engine object, configures a single NVelocity template engine based + on the element definitions. + + the root element defining the velocity engine + the parser context + + + + Parses child element definitions for the NVelocity engine. Typically resource loaders and locally defined properties are parsed here + + the XmlNodeList representing the child configuration of the root NVelocity engine element + the parser context + the MutablePropertyValues used to configure this object + + + + Configures the NVelocity resource loader definitions from the xml definition + + the root resource loader element + the MutablePropertyValues used to configure this object + the properties used to initialize the velocity engine + + + + Set the caching and modification interval checking properties of a resource loader of a given type + + the properties used to initialize the velocity engine + type of the resource loader + caching flag + modification interval value + + + + Set global velocity resource loader properties (caching, modification interval etc.) + + the properties used to initialize the velocity engine + the type of resource loader + the suffix property + the value of the property + + + + Creates a nvelocity file based resource loader by setting the required properties + + a list of nv:file elements defining the paths to template files + the properties used to initialize the velocity engine + + + + Creates a nvelocity assembly based resource loader by setting the required properties + + a list of nv:assembly elements defining the assemblies + the properties used to initialize the velocity engine + + + + Creates a spring resource loader by setting the ResourceLoaderPaths of the + engine factory (the resource loader itself will be created internally either as + spring or as file resource loader based on the value of prefer-file-system-access + attribute). + + list of resource loader path elements + the MutablePropertyValues to set the property for the engine factory + + + + Create a custom resource loader from an nv:custom element + generates the 4 required nvelocity props for a resource loader (name, description, class and path). + + the nv:custom xml definition element + the properties used to initialize the velocity engine + + + + Parses the nvelocity properties map using ObjectNamespaceParserHelper + and appends it to the properties dictionary + + root element of the map element + the parser context + the properties used to initialize the velocity engine + + + + Gets the name of the object type for the specified element. + + The element. + The name of the object type. + + + + constructs an nvelocity style resource loader property in the format: + prefix.resource.loader.suffix + + the prefix + the suffix + a concatenated string like: prefix.resource.loader.suffix + + + + This method is overriden from ObjectsNamespaceParser since when invoked on + sub-elements from the objets namespace (e.g., objects:objectMap for nvelocity + property map) the element.SelectNodes fails because it is in + the nvelocity custom namespace and not the object's namespace (http://www.springframwork.net) + to amend this the object's namespace is added to the provided XmlNamespaceManager + + The element to be searched in. + The name of the child nodes to look for. + + The child s of the supplied + with the supplied . + + + + + + Template definition constants + + + + + Engine element definition + + + + + Spring resource loader element definition + + + + + Custom resource loader element definition + + + + + uri attribute of the spring element + + + + + prefer-file-system-access attribute of the engine factory + + + + + config-file attribute of the engine factory + + + + + override-logging attribute of the engine factory + + + + + template-caching attribute of the nvelocity engine + + + + + default-cache-size attribute of the nvelocity engine resource manager + + + + + modification-check-interval attribute of the nvelocity engine resource loader + + + + + resource loader element + + + + + nvelocity propeties element (map) + + + + + PreferFileSystemAccess property of the engine factory + + + + + OverrideLogging property of the engine factory + + + + + ConfigLocation property of the engine factory + + + + + ResourceLoaderPaths property of the engine factory + + + + + VelocityProperties property of the engine factory + + + + + resource.loader.cache property of the resource loader configuration + + + + + resource.loader.modificationCheckInterval property of the resource loader configuration + + + + + the type used for file resource loader + + + + + the type used for assembly resource loader + + + + + the type used for spring resource loader + + + + + NVelocity LogSystem implementation for Commons Logging. + + Erez Mazor + + + + Shared logger instance. + + + + + Initializes the specified runtime services. No-op in current implementatin + + the runtime services. + + + + Log a NVelocity message using the commons logging system + + LogLevel to match + message to log + + + + NVelocity's abstract ResourceLoader extension which serves + as an adapter that loads templates via a Spring IResourceLoader. + +
+ Used by VelocityEngineFactory for any resource loader path that + cannot be resolved to a File or an Assembly or for + implementations which rely on spring's IResourceLoader + mechanism. + +
+ Important: this loader does not allow for modification detection. +
+ Expects "spring.resource.loader" (IResourceLoader implementations) + and "spring.resource.loader.path" application attributes in the + NVelocity runtime. + + + + + + + Erez Mazor (.NET) + + + + Prefix used for the NVelocity Configuration + + + + + The IResourceLoader implementation type + + + + + A flag indicating weather a template cache is used + + + + + Fully qualified name of the IResourceLoader implementation class + + + + + A comma delimited list of paths used by the spring IResourceLoader implementation + + + + + Shared logger instance. + + + + + Initialize the template loader with a resources class. + + The ExtendedProperties representing the Velocity configuration. + + + + Get the System.IO.Stream that the Runtime will parse to create a template. + + the source template name + a System.IO.Stream representation of the resource + + + + Given a template, check to see if the source of InputStream has been modified. + + The resource. + + true if the source of the InputStream has been modified; otherwise, false. + + + + + Get the last modified time of the InputStream source + that was used to create the template. We need the template + here because we have to extract the name of the template + in order to locate the InputStream source. + + The resource. + + + + + Common Velocity constants. + + + + + File. + + + + + Type. + + + + + Assembly. + + + + + Class. + + + + + Name. + + + + + Description. + + + + + Path. + + + + + Separator. + + + + + Factory that configures a VelocityEngine. Can be used standalone, + but typically you will use VelocityEngineFactoryObject + for preparing a VelocityEngine as bean reference. + +
+ The optional "ConfigLocation" property sets the location of the Velocity + properties file, within the current application. Velocity properties can be + overridden via "VelocityProperties", or even completely specified locally, + avoiding the need for an external properties file. + +
+ The "ResourceLoaderPath" property can be used to specify the Velocity + resource loader path via Spring's IResource abstraction, possibly relative + to the Spring application context. + +
+ If "OverrideLogging" is true (the default), the VelocityEngine will be + configured to log via Commons Logging, that is, using the Spring-provided + CommonsLoggingLogSystem as log system. + +
+ The simplest way to use this class is to specify a ResourceLoaderPath + property. the VelocityEngine typically then does not need any further + configuration. + + + + + + Erez Mazor + + + + Shared logger instance. + + + + + Create and initialize the VelocityEngine instance and return it + + VelocityEngine + + + + + + + + + This is to overcome an issue with the current NVelocity library, it seems the + default runetime properties/directives (nvelocity.properties and directive.properties + files) are not being properly located in the library at load time. A jira should + be filed but for now we attempt to do this on our own. Particularly our + concern here is with several required properties which I don't want + to require users to re-defined. e.g.,: +
+ + Pre-requisites:
+ resource.manager.class=NVelocity.Runtime.Resource.ResourceManagerImpl
+ directive.manager=NVelocity.Runtime.Directive.DirectiveManager
+ runtime.introspector.uberspect=NVelocity.Util.Introspection.UberspectImpl
+ + + + + Return a new VelocityEngine. Subclasses can override this for + custom initialization, or for using a mock object for testing.
+ Called by CreateVelocityEngine() + + VelocityEngine instance (non-configured) + + + + + Initialize a Velocity resource loader for the given VelocityEngine: + either a standard Velocity FileResourceLoader or a SpringResourceLoader. +
Called by CreateVelocityEngine(). + + velocityEngine the VelocityEngine to configure + + paths the path list to load Velocity resources from + + + + + + + + Initialize a SpringResourceLoader for the given VelocityEngine. +
Called by InitVelocityResourceLoader. + + Important: the NVeloctity ResourceLoaderFactory.getLoader + method replaces ';' with ',' when attempting to construct our resource + loader. The name on the SPRING_RESOURCE_LOADER_CLASS property + has to be in the form of "ClassFullName; AssemblyName" in replacement + of the tranditional "ClassFullName, AssemblyName" to work. + + velocityEngine the VelocityEngine to configure + + resourceLoaderPath the path to load Velocity resources from + + + + + + To be implemented by subclasses that want to to perform custom + post-processing of the VelocityEngine after this FactoryObject + performed its default configuration (but before VelocityEngine.init) +
+ Called by CreateVelocityEngine + + velocityEngine the current VelocityEngine + + + + + + + Populates the velocity properties from the given resource + + ExtendedProperties instance to populate + The resource from which to load the properties + A flag indicated weather the properties loaded from the resource should be appended or replaced in the extendedProperties + + + + Set the location of the Velocity config file. Alternatively, you can specify all properties locally. + + + + + + + Set local NVelocity properties. + + + + + + Single ResourceLoaderPath + + + + + + Set the Velocity resource loader path via a Spring resource location. + Accepts multiple locations in Velocity's comma-separated path style. +
+ When populated via a String, standard URLs like "file:" and "assembly:" + pseudo URLs are supported, as understood by IResourceLoader. Allows for + relative paths when running in an ApplicationContext. +
+ Will define a path for the default Velocity resource loader with the name + "file". If the specified resource cannot be resolved to a File, + a generic SpringResourceLoader will be used under the name "spring", without + modification detection. +
+ Take notice that resource caching will be enabled in any case. With the file + resource loader, the last-modified timestamp will be checked on access to + detect changes. With SpringResourceLoader, the resource will be throughout + the life time of the application context (for example for class path resources). +
+ To specify a modification check interval for files, use Velocity's + standard "file.resource.loader.modificationCheckInterval" property. By default, + the file timestamp is checked on every access (which is surprisingly fast). + Of course, this just applies when loading resources from the file system. +
+ To enforce the use of SpringResourceLoader, i.e. to not resolve a path + as file system resource in any case, turn off the "preferFileSystemAccess" + flag. See the latter's documentation for details. + + + + + + + + + + Set the Spring ResourceLoader to use for loading Velocity template files. + The default is DefaultResourceLoader. Will get overridden by the + ApplicationContext if running in a context. + + + + + + + + + Set whether to prefer file system access for template loading. + File system access enables hot detection of template changes. +
+ If this is enabled, VelocityEngineFactory will try to resolve the + specified "resourceLoaderPath" as file system resource. +
+ Default is "true". Turn this off to always load via SpringResourceLoader + (i.e. as stream, without hot detection of template changes), which might + be necessary if some of your templates reside in a directory while + others reside in assembly files. + + + + + + Set whether Velocity should log via Commons Logging, i.e. whether Velocity's + log system should be set to CommonsLoggingLogSystem. Default value is true + + + + + + FactoryObject implementation that configures a VelocityEngine and provides it + as an object reference. This object is intended for any kind of usage of Velocity in + application code, e.g. for generating email content. + + See the base class VelocityEngineFactory for configuration details. + + + Erez Mazor + + + + Get the velocity engine underlying object + + An instance of a configured VelocityEngine + + + + + Facilitate the creation of the velocity engine object + + + + + Get the type of the velocity engine + + + + + Singleton + + + + + Generalized Utility class for merging velocity templates into a text writer or return the result as a string + + Erez Mazor + + + + Shared logger instance. + + + + + Merge the specified Velocity template with the given model and write + the result to the given Writer. + + VelocityEngine to work with + the location of template, relative to Velocity's resource loader path + encoding the encoding of the template file + the Hashtable that contains model names as keys and model objects + writer the TextWriter to write the result to + thrown if any exception is thrown by the velocity engine + + + + Merge the specified Velocity template with the given model into a string. + + VelocityEngine to work with + the location of template, relative to Velocity's resource loader path + the encoding string to use for the merge + the Hashtable that contains model names as keys and model objects + the result as string + thrown if any exception is thrown by the velocity engine + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Testing.Microsoft.dll b/Resources/Libraries/Spring.NET/Spring.Testing.Microsoft.dll new file mode 100644 index 00000000..a807b27f Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Testing.Microsoft.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Testing.Microsoft.pdb b/Resources/Libraries/Spring.NET/Spring.Testing.Microsoft.pdb new file mode 100644 index 00000000..6e0988ed Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Testing.Microsoft.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Testing.Microsoft.xml b/Resources/Libraries/Spring.NET/Spring.Testing.Microsoft.xml new file mode 100644 index 00000000..42acb336 --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Testing.Microsoft.xml @@ -0,0 +1,521 @@ + + + + Spring.Testing.Microsoft + + + + + Convenient superclass for tests depending on a Spring context. + The test instance itself is populated by Dependency Injection. + + + +

Really for integration testing, not unit testing. + You should not normally use the Spring container + for unit tests: simply populate your objects in plain NUnit tests!

+ +

This supports two modes of populating the test: +

    +
  • Via Property Dependency Injection. Simply express dependencies on objects + in the test fixture, and they will be satisfied by autowiring by type.
    • +
  • Via Field Injection. Declare protected variables of the required type + which match named beans in the context. This is autowire by name, + rather than type. This approach is based on an approach originated by + Ara Abrahmian. Property Dependency Injection is the default: set the + "populateProtectedVariables" property to true in the constructor to switch + on Field Injection.
    • +

+ +

This class will normally cache contexts based on a context key: + normally the config locations String array describing the Spring resource + descriptors making up the context. Unless the SetDirty() method + is called by a test, the context will not be reloaded, even across different + subclasses of this test. This is particularly beneficial if your context is + slow to construct, for example if you are using Hibernate and the time taken + to load the mappings is an issue.

+ +

If you don't want this behavior, you can override the ContextKey + property, most likely to return the test class. In conjunction with this you would + probably override the GetContext method, which by default loads + the locations specified by the ConfigLocations property.

+ +

WARNING: When doing integration tests from within VS.NET, only use + assembly resource URLs. Else, you may see misleading failures when changing + context locations.

+ + + Rod Johnson + Rob Harrop + Rick Evans + Aleksandar Seovic (.NET) + + + + Superclass for NUnit test cases using a Spring context. + + +

Maintains a cache of contexts by key. This has significant performance + benefit if initializing the context would take time. While initializing a + Spring context itself is very quick, some objects in a context, such as + a LocalSessionFactoryObject for working with NHibernate, may take time to + initialize. Hence it often makes sense to do that initializing once.

+

Normally you won't extend this class directly but rather extend one + of its subclasses.

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Map of context keys returned by subclasses of this class, to + Spring contexts. + + + + + Static ctor to avoid "beforeFieldInit" problem. + + + + + Disposes any cached context instance and removes it from cache. + + + + + Indicates, whether context instances should be automatically registered with the global . + + + + + Logger available to subclasses. + + + + + Default constructor for AbstractSpringContextTests. + + + + + Set custom locations dirty. This will cause them to be reloaded + from the cache before the next test case is executed. + + + Call this method only if you change the state of a singleton + object, potentially affecting future tests. + + Locations + + + + Returns true if context for the specified + is cached. + + Context key to check. + + true if context for the specified + is cached, + false otherwise. + + + + + Converts context key to string. + + + Subclasses can override this to return a string representation of + their contextKey for use in logging. + + Context key to convert. + + String representation of the specified . Null if + contextKey is null. + + + + + Caches application context. + + Key to use. + Context to cache. + + + + Returns cached context if present, or loads it if not. + + Context key. + Spring application context associated with the specified key. + + + + Loads application context from the specified resource locations. + + Resources to load object definitions from. + + + + Loads application context based on user-defined key. + + + Unless overriden by the user, this method will alway throw + a . + + User-defined key. + + + + Controls, whether application context instances will + be registered/unregistered with the global . + Defaults to true. + + + + + Application context this test will run against. + + + + + Holds names of the fields that should be used for field injection. + + + + + Default constructor for AbstractDependencyInjectionSpringContextTests. + + + + + Called to say that the "applicationContext" instance variable is dirty and + should be reloaded. We need to do this if a test has modified the context + (for example, by replacing an object definition). + + + + + Test setup method. + + + + + Inject dependencies into 'this' instance (that is, this test instance). + + +

The default implementation populates protected variables if the + property is set, else + uses autowiring if autowiring is switched on (which it is by default).

+

You can certainly override this method if you want to totally control + how dependencies are injected into 'this' instance.

+ + + + + Loads application context from the specified resource locations. + + Resources to load object definitions from. + + + + Retrieves the names of the fields that should be used for field injection. + + + + + Injects protected fields using Field Injection. + + + + + Called right before a field is being injected + + + + + Subclasses can override this method in order to + add custom test setup logic. + + + + + Test teardown method. + + + + + Subclasses can override this method in order to + add custom test teardown logic. + + + + + Gets or sets a flag specifying whether to populate protected + variables of this test case. + + + A flag specifying whether to populate protected variables of this test case. + Default is false. + + + + + Gets or sets the autowire mode for test properties set by Dependency Injection. + + + The autowire mode for test properties set by Dependency Injection. + The default is . + + + + + Gets or sets a flag specifying whether or not dependency checking + should be performed for test properties set by Dependency Injection. + + +

A flag specifying whether or not dependency checking + should be performed for test properties set by Dependency Injection.

+

The default is true, meaning that tests cannot be run + unless all properties are populated.

+ + + + + Gets the current number of context load attempts. + + + + + Gets a key for this context. Usually based on config locations, but + a subclass overriding buildContext() might want to return its class. + + + + + Subclasses must implement this property to return the locations of their + config files. A plain path will be treated as a file system location. + + An array of config locations + + + + Subclass of AbstractTransactionalSpringContextTests that adds some convenience + functionality for ADO.NET access. Expects a IDbProvider object + to be defined in the Spring application context. + + + This class exposes a AdoTemplate and provides an easy way to delete from the + database in a new transaction. + + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + + + + Convenient superclass for tests that should occur in a transaction, but normally + will roll the transaction back on the completion of each test. + + +

This is useful in a range of circumstances, allowing the following benefits:

+
    +
  • Ability to delete or insert any data in the database, without affecting other tests
    • +
  • Providing a transactional context for any code requiring a transaction
    • +
  • Ability to write anything to the database without any need to clean up.
    • +
+ +

This class is typically very fast, compared to traditional setup/teardown scripts.

+ +

If data should be left in the database, call the SetComplete() + method in each test. The "DefaultRollback" property, which defaults to "true", + determines whether transactions will complete by default.

+ +

It is even possible to end the transaction early; for example, to verify lazy + loading behavior of an O/R mapping tool. (This is a valuable away to avoid + unexpected errors when testing a web UI, for example.) Simply call the + endTransaction() method. Execution will then occur without a + transactional context.

+ +

The StartNewTransaction() method may be called after a call to + EndTransaction() if you wish to create a new transaction, quite + independent of the old transaction. The new transaction's default fate will be to + roll back, unless setComplete() is called again during the scope of the + new transaction. Any number of transactions may be created and ended in this way. + The final transaction will automatically be rolled back when the test case is + torn down.

+ +

Transactional behavior requires a single object in the context implementing the + IPlatformTransactionManager interface. This will be set by the superclass's + Dependency Injection mechanism. If using the superclass's Field Injection mechanism, + the implementation should be named "transactionManager". This mechanism allows the + use of this superclass even when there's more than one transaction manager in the context.

+ +

This superclass can also be used without transaction management, if no + IPlatformTransactionManager object is found in the context provided. Be careful about + using this mode, as it allows the potential to permanently modify data. + This mode is available only if dependency checking is turned off in + the AbstractDependencyInjectionSpringContextTests superclass. The non-transactional + capability is provided to enable use of the same subclass in different environments.

+ + + + Rod Johnson + Juergen Hoeller + Rick Evans + Mark Pollack (.NET) + + + + The transaction manager to use + + + + + Should we roll back by default? + + + + + Should we commit the current transaction? + + + + + Number of transactions started + + + + + Default transaction definition is used. + Subclasses can change this to cause different behaviour. + + + + + TransactionStatus for this test. Typical subclasses won't need to use it. + + + + + Initializes a new instance of the class. + + + + + Prevents the transaction. + + + + + Creates a transaction + + + + + Callback method called before transaction is setup. + + + + + Callback method called after transaction is setup. + + + + + rollback the transaction. + + + + + Callback before rolling back the transaction. + + + + + Callback after rolling back the transaction. + + + + + Set the complete flag.. + + + + + Ends the transaction. + + + + + Starts the new transaction. + + + + + Sets the transaction manager to use. + + + + + Sets the default rollback flag. + + + + + Set the to be used + + + Defaults to + + + + + Holds the that this base class manages + + + + + Did this test delete any tables? If so, we forbid transaction completion, + and only allow rollback. + + + + + Initializes a new instance of the class. + + + + + Convenient method to delete all rows from these tables. + Calling this method will make avoidance of rollback by calling + SetComplete() impossible. + + + + + + Overridden to prevent the transaction committing if a number of tables have been + cleared, as a defensive measure against accidental permanent wiping of a database. + + + + + Counts the rows in given table. + + Name of the table to count rows in. + The number of rows in the table + + + + Sets the DbProvider, via Dependency Injection. + + The IDbProvider. + + + + Gets or sets the AdoTemplate that this base class manages. + + The ADO template. + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Testing.NUnit.dll b/Resources/Libraries/Spring.NET/Spring.Testing.NUnit.dll new file mode 100644 index 00000000..7406240a Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Testing.NUnit.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Testing.NUnit.pdb b/Resources/Libraries/Spring.NET/Spring.Testing.NUnit.pdb new file mode 100644 index 00000000..5a434e3f Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Testing.NUnit.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Testing.NUnit.xml b/Resources/Libraries/Spring.NET/Spring.Testing.NUnit.xml new file mode 100644 index 00000000..216d1beb --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Testing.NUnit.xml @@ -0,0 +1,655 @@ + + + + Spring.Testing.NUnit + + + + + Holds status for an active transaction. You *must* dispose this object! + + + + Usage Pattern: + + TBD + + + + + + + Mark transaction for commit on disposal + + + + + Throw exception and rollback any uncommitted commands + + + + + TBD + + Erich Eichinger + + + + TBD + + + + + TBD + + + + + TBD + + + + + TBD + + + + + TBD + + + + + TBD + + + + + TBD + + + + + TBD + + + + + TBD + + + + + Execute the given script + + + + + Execute the given script + + + + + Execute the given script + + + + + Execute the given script + + + + + Execute the given script + + + + + Execute the given script + + + + + Execute the given script + + + + + TBD + + + + + Convenient superclass for tests depending on a Spring context. + The test instance itself is populated by Dependency Injection. + + + +

Really for integration testing, not unit testing. + You should not normally use the Spring container + for unit tests: simply populate your objects in plain NUnit tests!

+ +

This supports two modes of populating the test: +

    +
  • Via Property Dependency Injection. Simply express dependencies on objects + in the test fixture, and they will be satisfied by autowiring by type.
    • +
  • Via Field Injection. Declare protected variables of the required type + which match named beans in the context. This is autowire by name, + rather than type. This approach is based on an approach originated by + Ara Abrahmian. Property Dependency Injection is the default: set the + "populateProtectedVariables" property to true in the constructor to switch + on Field Injection.
    • +

+ +

This class will normally cache contexts based on a context key: + normally the config locations String array describing the Spring resource + descriptors making up the context. Unless the SetDirty() method + is called by a test, the context will not be reloaded, even across different + subclasses of this test. This is particularly beneficial if your context is + slow to construct, for example if you are using Hibernate and the time taken + to load the mappings is an issue.

+ +

If you don't want this behavior, you can override the ContextKey + property, most likely to return the test class. In conjunction with this you would + probably override the GetContext method, which by default loads + the locations specified by the ConfigLocations property.

+ +

WARNING: When doing integration tests from within VS.NET, only use + assembly resource URLs. Else, you may see misleading failures when changing + context locations.

+ + + Rod Johnson + Rob Harrop + Rick Evans + Aleksandar Seovic (.NET) + + + + Superclass for NUnit test cases using a Spring context. + + +

Maintains a cache of contexts by key. This has significant performance + benefit if initializing the context would take time. While initializing a + Spring context itself is very quick, some objects in a context, such as + a LocalSessionFactoryObject for working with NHibernate, may take time to + initialize. Hence it often makes sense to do that initializing once.

+

Normally you won't extend this class directly but rather extend one + of its subclasses.

+ + Rod Johnson + Aleksandar Seovic (.NET) + + + + Map of context keys returned by subclasses of this class, to + Spring contexts. + + + + + Static ctor to avoid "beforeFieldInit" problem. + + + + + Disposes any cached context instance and removes it from cache. + + + + + Indicates, whether context instances should be automatically registered with the global . + + + + + Logger available to subclasses. + + + + + Default constructor for AbstractSpringContextTests. + + + + + Set custom locations dirty. This will cause them to be reloaded + from the cache before the next test case is executed. + + + Call this method only if you change the state of a singleton + object, potentially affecting future tests. + + Locations + + + + Set context with dirty. This will cause + it to be reloaded from the cache before the next test case is executed. + + + Call this method only if you change the state of a singleton + object, potentially affecting future tests. + + Locations + + + + Returns true if context for the specified + is cached. + + Context key to check. + + true if context for the specified + is cached, + false otherwise. + + + + + Converts context key to string. + + + Subclasses can override this to return a string representation of + their contextKey for use in logging. + + Context key to convert. + + String representation of the specified . Null if + contextKey is null. + + + + + Caches application context. + + Key to use. + Context to cache. + + + + Returns cached context if present, or loads it if not. + + Context key. + Spring application context associated with the specified key. + + + + Loads application context from the specified resource locations. + + Resources to load object definitions from. + + + + Loads application context based on user-defined key. + + + Unless overriden by the user, this method will alway throw + a . + + User-defined key. + + + + Controls, whether application context instances will + be registered/unregistered with the global . + Defaults to true. + + + + + Application context this test will run against. + + + + + Holds names of the fields that should be used for field injection. + + + + + Default constructor for AbstractDependencyInjectionSpringContextTests. + + + + + Called to say that the "applicationContext" instance variable is dirty and + should be reloaded. We need to do this if a test has modified the context + (for example, by replacing an object definition). + + + + + Test setup method. + + + + + Inject dependencies into 'this' instance (that is, this test instance). + + +

The default implementation populates protected variables if the + property is set, else + uses autowiring if autowiring is switched on (which it is by default).

+

You can certainly override this method if you want to totally control + how dependencies are injected into 'this' instance.

+ + + + + Loads application context from the specified resource locations. + + Resources to load object definitions from. + + + + Retrieves the names of the fields that should be used for field injection. + + + + + Injects protected fields using Field Injection. + + + + + Called right before a field is being injected + + + + + Subclasses can override this method in order to + add custom test setup logic after the context has been created and dependencies injected. + Called from this class's [SetUp] method. + + + + + Test teardown method. + + + + + Subclasses can override this method in order to + add custom test teardown logic. Called from this class's [TearDown] method. + + + + + Gets or sets a flag specifying whether to populate protected + variables of this test case. + + + A flag specifying whether to populate protected variables of this test case. + Default is false. + + + + + Gets or sets the autowire mode for test properties set by Dependency Injection. + + + The autowire mode for test properties set by Dependency Injection. + The default is . + + + + + Gets or sets a flag specifying whether or not dependency checking + should be performed for test properties set by Dependency Injection. + + +

A flag specifying whether or not dependency checking + should be performed for test properties set by Dependency Injection.

+

The default is true, meaning that tests cannot be run + unless all properties are populated.

+ + + + + Gets the current number of context load attempts. + + + + + Gets a key for this context. Usually based on config locations, but + a subclass overriding buildContext() might want to return its class. + + + + + Subclasses must implement this property to return the locations of their + config files. A plain path will be treated as a file system location. + + An array of config locations + + + + Subclass of AbstractTransactionalSpringContextTests that adds some convenience + functionality for ADO.NET access. Expects a IDbProvider object + to be defined in the Spring application context. + + + This class exposes a AdoTemplate and provides an easy way to delete from the + database in a new transaction. + + Rod Johnson + Juergen Hoeller + Mark Pollack (.NET) + + + + Convenient superclass for tests that should occur in a transaction, but normally + will roll the transaction back on the completion of each test. + + +

This is useful in a range of circumstances, allowing the following benefits:

+
    +
  • Ability to delete or insert any data in the database, without affecting other tests
    • +
  • Providing a transactional context for any code requiring a transaction
    • +
  • Ability to write anything to the database without any need to clean up.
    • +
+ +

This class is typically very fast, compared to traditional setup/teardown scripts.

+ +

If data should be left in the database, call the SetComplete() + method in each test. The "DefaultRollback" property, which defaults to "true", + determines whether transactions will complete by default.

+ +

It is even possible to end the transaction early; for example, to verify lazy + loading behavior of an O/R mapping tool. (This is a valuable away to avoid + unexpected errors when testing a web UI, for example.) Simply call the + endTransaction() method. Execution will then occur without a + transactional context.

+ +

The StartNewTransaction() method may be called after a call to + EndTransaction() if you wish to create a new transaction, quite + independent of the old transaction. The new transaction's default fate will be to + roll back, unless setComplete() is called again during the scope of the + new transaction. Any number of transactions may be created and ended in this way. + The final transaction will automatically be rolled back when the test case is + torn down.

+ +

Transactional behavior requires a single object in the context implementing the + IPlatformTransactionManager interface. This will be set by the superclass's + Dependency Injection mechanism. If using the superclass's Field Injection mechanism, + the implementation should be named "transactionManager". This mechanism allows the + use of this superclass even when there's more than one transaction manager in the context.

+ +

This superclass can also be used without transaction management, if no + IPlatformTransactionManager object is found in the context provided. Be careful about + using this mode, as it allows the potential to permanently modify data. + This mode is available only if dependency checking is turned off in + the AbstractDependencyInjectionSpringContextTests superclass. The non-transactional + capability is provided to enable use of the same subclass in different environments.

+ + + + Rod Johnson + Juergen Hoeller + Rick Evans + Mark Pollack (.NET) + + + + The transaction manager to use + + + + + Should we roll back by default? + + + + + Should we commit the current transaction? + + + + + Number of transactions started + + + + + Default transaction definition is used. + Subclasses can change this to cause different behaviour. + + + + + TransactionStatus for this test. Typical subclasses won't need to use it. + + + + + Initializes a new instance of the class. + + + + + Prevents the transaction. + + + + + Creates a transaction + + + + + Callback method called before transaction is setup. + + + + + Callback method called after transaction is setup. + + + + + rollback the transaction. + + + + + Callback before rolling back the transaction. + + + + + Callback after rolling back the transaction. + + + + + Set the complete flag.. + + + + + Ends the transaction. + + + + + Starts the new transaction. + + + + + Sets the transaction manager to use. + + + + + Sets the default rollback flag. + + + + + Set the to be used + + + Defaults to + + + + + Holds the that this base class manages + + + + + Did this test delete any tables? If so, we forbid transaction completion, + and only allow rollback. + + + + + Initializes a new instance of the class. + + + + + Convenient method to delete all rows from these tables. + Calling this method will make avoidance of rollback by calling + SetComplete() impossible. + + + + + + Overridden to prevent the transaction committing if a number of tables have been + cleared, as a defensive measure against accidental permanent wiping of a database. + + + + + Counts the rows in given table. + + Name of the table to count rows in. + The number of rows in the table + + + + Execute the given SQL script using + + + + + + + + Sets the DbProvider, via Dependency Injection. + + The IDbProvider. + + + + Gets or sets the AdoTemplate that this base class manages. + + The ADO template. + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Web.Extensions.dll b/Resources/Libraries/Spring.NET/Spring.Web.Extensions.dll new file mode 100644 index 00000000..dc8b5e7c Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Web.Extensions.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Web.Extensions.pdb b/Resources/Libraries/Spring.NET/Spring.Web.Extensions.pdb new file mode 100644 index 00000000..58d59a5e Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Web.Extensions.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Web.Extensions.xml b/Resources/Libraries/Spring.NET/Spring.Web.Extensions.xml new file mode 100644 index 00000000..c2970ec2 --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Web.Extensions.xml @@ -0,0 +1,50 @@ + + + + Spring.Web.Extensions + + + + + An implementation that + creates a handler object for either ASP.NET AJAX 1.0 or Spring web services. + + Bruno Baia + Thomas Broyer + + + + Creates a new instance of the class. + + + + + Retrieves an instance of the + implementation for handling web service requests + for both Spring and ASP.NET AJAX 1.0 web services. + + The current HTTP context. + The type of HTTP request (GET or POST). + The url of the web service. + The physical application path for the web service. + The web service handler object. + + + + Enables a factory to reuse an existing handler instance. + + The object to reuse. + + + + Create a handler instance for the given URL. + + the application context corresponding to the current request + The instance for this request. + The HTTP data transfer method (GET, POST, ...) + The requested . + The physical path of the requested resource. + A handler instance for the current request. + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Web.Mvc.dll b/Resources/Libraries/Spring.NET/Spring.Web.Mvc.dll new file mode 100644 index 00000000..7da13f5d Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Web.Mvc.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Web.Mvc.pdb b/Resources/Libraries/Spring.NET/Spring.Web.Mvc.pdb new file mode 100644 index 00000000..b7793de1 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Web.Mvc.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Web.Mvc.xml b/Resources/Libraries/Spring.NET/Spring.Web.Mvc.xml new file mode 100644 index 00000000..ab89632b --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Web.Mvc.xml @@ -0,0 +1,260 @@ + + + + Spring.Web.Mvc + + + + + Application Context for ASP.NET MVC Applications + + + + + Create a new MvcApplicationContext, loading the definitions + from the given XML resource. + + The application context name. + Flag specifying whether to make this context case sensitive or not. + Names of configuration resources. + + + + Create a new MvcApplicationContext with the given parent, + loading the definitions from the given XML resources. + + The application context name. + Flag specifying whether to make this context case sensitive or not. + The parent context. + Names of configuration resources. + + + + Initializes a new instance of the class. + + The args. + + + + Create a new MvcApplicationContext, loading the definitions + from the given XML resource. + + The application context name. + Flag specifying whether to make this context case sensitive or not. + Names of configuration resources. + Configuration resources. + + + + Create a new MvcApplicationContext, loading the definitions + from the given XML resource. + + Names of configuration resources. + + + + An array of resource locations, referring to the XML object + definition files that this context is to be built with. + + + +

+ Examples of the format of the various strings that would be + returned by accessing this property can be found in the overview + documentation of with the + class. +

+ + + An array of resource locations, or if none. + + + + + An array of resources that this context is to be built with. + + + +

+ Examples of the format of the various strings that would be + returned by accessing this property can be found in the overview + documentation of with the + class. +

+ + + An array of s, or if none. + + + + + Encapsulates arguments to the class. + + + + + Initializes a new instance of the MvcApplicationContextArgs class. + + + + + Initializes a new instance of the MvcApplicationContextArgs class. + + The name. + The parent context. + The configuration locations. + The configuration resources. + + + + Initializes a new instance of the MvcApplicationContextArgs class. + + The name. + The parent context. + The configuration locations. + The configuration resources. + if set to true [case sensitive]. + + + + Context Handler for ASP.NET MVC Applications + + + + + The of + created if no type attribute is specified on a context element. + + + + + + Get the context's case-sensitivity to use if none is specified + + + +

+ Derived handlers may override this property to change their default case-sensitivity. +

+

+ Defaults to 'true'. +

+ + + + + ActionInvoker implementation that enables the to satisfy dependencies on ActionFilter attributes. + + + + + Initializes a new instance of the class. + + The IApplicationContext. + + + + Retrieves information about the action filters. + + The controller context. + The action descriptor. + Information about the action filters. + + + + Controller Factory for ASP.NET MVC + + + + + Creates the specified controller by using the specified request context. + + The context of the HTTP request, which includes the HTTP context and route data. + The name of the controller. + A reference to the controller. + The parameter is null. + The parameter is null or empty. + + + + Retrieves the controller instance for the specified request context and controller type. + + The context of the HTTP request, which includes the HTTP context and route data. + The type of the controller. + The controller instance. + + is null. + + cannot be assigned. + An instance of cannot be created. + + + + Adds the action invoker to the controller instance. + + The controller. + + + + Gets the application context. + + The application context. + + + + Gets or sets the name of the application context. + + + Defaults to using the root (default) Application Context. + + The name of the application context. + + + + Spring.NET-specific HttpApplication for ASP.NET MVC integration. + + + + + Handles the Start event of the Application control. + + The source of the event. + The instance containing the event data. + + + + Configures the instance. + + + You must override this method in a derived class to control the manner in which the + is configured. + + + + + Executes custom initialization code after all event handler modules have been added. + + + + + Registers the areas. + + + Override this method in a derived class to modify the registered areas as neeeded. + + + + + Registers the routes. + + + Override this method in a derived class to modify the registered routes as neeeded. + + + + + Registers the controller factory with the Mvc Framework. + + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Web.Mvc3.dll b/Resources/Libraries/Spring.NET/Spring.Web.Mvc3.dll new file mode 100644 index 00000000..bcfcaf1b Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Web.Mvc3.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Web.Mvc3.pdb b/Resources/Libraries/Spring.NET/Spring.Web.Mvc3.pdb new file mode 100644 index 00000000..db6a077d Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Web.Mvc3.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Web.Mvc3.xml b/Resources/Libraries/Spring.NET/Spring.Web.Mvc3.xml new file mode 100644 index 00000000..62def68b --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Web.Mvc3.xml @@ -0,0 +1,218 @@ + + + + Spring.Web.Mvc3 + + + + + Application Context for ASP.NET MVC Applications + + + + + Create a new MvcApplicationContext, loading the definitions + from the given XML resource. + + The application context name. + Flag specifying whether to make this context case sensitive or not. + Names of configuration resources. + + + + Create a new MvcApplicationContext with the given parent, + loading the definitions from the given XML resources. + + The application context name. + Flag specifying whether to make this context case sensitive or not. + The parent context. + Names of configuration resources. + + + + Initializes a new instance of the class. + + The args. + + + + Create a new MvcApplicationContext, loading the definitions + from the given XML resource. + + The application context name. + Flag specifying whether to make this context case sensitive or not. + Names of configuration resources. + Configuration resources. + + + + Create a new MvcApplicationContext, loading the definitions + from the given XML resource. + + Names of configuration resources. + + + + An array of resource locations, referring to the XML object + definition files that this context is to be built with. + + + +

+ Examples of the format of the various strings that would be + returned by accessing this property can be found in the overview + documentation of with the + class. +

+ + + An array of resource locations, or if none. + + + + + An array of resources that this context is to be built with. + + + +

+ Examples of the format of the various strings that would be + returned by accessing this property can be found in the overview + documentation of with the + class. +

+ + + An array of s, or if none. + + + + + Encapsulates arguments to the class. + + + + + Initializes a new instance of the MvcApplicationContextArgs class. + + + + + Initializes a new instance of the MvcApplicationContextArgs class. + + The name. + The parent context. + The configuration locations. + The configuration resources. + + + + Initializes a new instance of the MvcApplicationContextArgs class. + + The name. + The parent context. + The configuration locations. + The configuration resources. + if set to true [case sensitive]. + + + + Context Handler for ASP.NET MVC Applications + + + + + Spring.NET-specific HttpApplication for ASP.NET MVC integration. + + + + + Executes custom initialization code after all event handler modules have been added. + + + + + Handles the BeginRequest event of the Application control. + + The source of the event. + The instance containing the event data. + + + + Builds the dependency resolver. + + The instance. + You must override this method in a derived class to control the manner in which the + is created. + + + + Configures the instance. + + + You must override this method in a derived class to control the manner in which the + is configured. + + + + + Registers the DependencyResolver implementation with the MVC runtime. + + You must override this method in a derived class to control the manner in which the + is registered. + + + + + + Thread-safe class that ensures that the is registered only once. + + + + + Registers the specified resolver. + + The resolver. + + + + Spring-based implementation of the interface. + + + + + Initializes a new instance of the class. + + The context. + + + + Resolves singly registered services that support arbitrary object creation. + + The type of the requested service or object. + The requested service or object. + + + + Resolves multiply registered services. + + The type of the requested services. + The requested services. + + + + Gets the application context. + + The application context. + + + + Gets or sets the name of the application context. + + + Defaults to using the root (default) Application Context. + + The name of the application context. + + + diff --git a/Resources/Libraries/Spring.NET/Spring.Web.dll b/Resources/Libraries/Spring.NET/Spring.Web.dll new file mode 100644 index 00000000..c9b1c7e9 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Web.dll differ diff --git a/Resources/Libraries/Spring.NET/Spring.Web.pdb b/Resources/Libraries/Spring.NET/Spring.Web.pdb new file mode 100644 index 00000000..0cbd7e57 Binary files /dev/null and b/Resources/Libraries/Spring.NET/Spring.Web.pdb differ diff --git a/Resources/Libraries/Spring.NET/Spring.Web.xml b/Resources/Libraries/Spring.NET/Spring.Web.xml new file mode 100644 index 00000000..91d4d3bd --- /dev/null +++ b/Resources/Libraries/Spring.NET/Spring.Web.xml @@ -0,0 +1,9254 @@ + + + + Spring.Web + + + + + An implementation backed by ASP.NET Cache (see ). + + + + Because ASP.NET Cache uses strings as cache keys, you need to ensure + that the key object type has properly implemented ToString method. + + + Despite the shared underlying , it is possible to use more than + one instance of without interfering each other. + + + Aleksandar Seovic + Erich Eichinger + + + + Initializes a new instance of + + + + + Initializes a new instance of + with the specified implementation. + + + + + + Retrieves an item from the cache. + + + Item key. + + + Item for the specified , or null. + + + + + Removes an item from the cache. + + + Item key. + + + + + Inserts an item into the cache. + + + Items inserted using this method have default and default + + + Item key. + + + Item value. + + + Item's time-to-live (TTL). + + + + + Inserts an item into the cache. + + + Item key. + + + Item value. + + + Item's time-to-live. + + + Flag specifying whether the item's time-to-live should be reset + when the item is accessed. + + + + + Inserts an item into the cache. + + + Item key. + + + Item value. + + + Item's time-to-live. + + + Flag specifying whether the item's time-to-live should be reset + when the item is accessed. + + + Item priority. + + + + + Generate a key to be used for the underlying implementation. + + + + + + + Gets/Sets a flag, whether to use sliding expiration policy. + + + + + Gets/Sets a default priority to be applied to all items inserted into this cache. + + + + + Gets a collection of all cache item keys. + + + + + Abstracts the underlying runtime cache + + + + + Insert an item into the cache. + + + + + Removes an item from the cache. + + The key of the item to remove + The object that has been removed from the cache + + + + Retrieve an item with the specified key from the cache. + + The key of the item to be retrieved + The item, if found. null otherwise + + + + Actually delegates all calls to the underlying + + + + + + + Erich Eichinger + + + + Holds shared application Template + + + + + Holds shared modules Templates + + + + + Configures the instance and its modules. + + + When called, configures using the instance + provided in and the templates available in + and . + + the application context instance to be used for resolving object references. + the instance to be configured. + + + + Gets or Sets the shared application template + + + + + Gets the dictionary of shared module templates + + + to synchronize access to the dictionary, use property. + + + + + Web application context, taking the context definition files + from the file system or from URLs. + + Treats resource paths as web resources, when using + IApplicationContext.GetResource. Resource paths are considered relative + to the virtual directory. + + Note: In case of multiple config locations, later object definitions will + override ones defined in earlier loaded files. This can be leveraged to + deliberately override certain object definitions via an extra XML file. + + Aleksandar Seovic + + + + Create a new WebApplicationContext, loading the definitions + from the given XML resource. + + Names of configuration resources. + + + + Create a new WebApplicationContext, loading the definitions + from the given XML resource. + + The application context name. + Flag specifying whether to make this context case sensitive or not. + Names of configuration resources. + + + + Create a new WebApplicationContext, loading the definitions + from the given XML resource. + + The application context name. + Flag specifying whether to make this context case sensitive or not. + Names of configuration resources. + Configuration resources. + + + + Create a new WebApplicationContext with the given parent, + loading the definitions from the given XML resources. + + The application context name. + Flag specifying whether to make this context case sensitive or not. + The parent context. + Names of configuration resources. + + + + Initializes a new instance of the class. + + The args. + + + + returns detailed instance information for debugging + + + + + + Since the HttpRuntime discards it's configurationsection cache, we maintain our own context cache. + Despite it really speeds up context-lookup, since we don't have to go through the whole HttpConfigurationSystem + + + + + EventHandler for ContextRegistry.Cleared event. Discards webContextCache. + + + + + Returns the root context of this web application + + + + + Returns the web application context for the given (absolute!) virtual path + + + + + Initializes object definition reader. + + Reader to initialize. + + + + Creates web object factory for this context using parent context's factory as a parent. + + Web object factory to use. + + + + Returns the application-relative virtual path of this context (without leading '~'!). + + + + + + Create a reader instance capable of handling web objects (Pages,Controls) for importing o + bject definitions into the specified . + + + + + Returns the web application context for the current request's filepath + + + + + An array of resource locations, referring to the XML object + definition files with which this context is to be built. + + + An array of resource locations, or if none. + + + + + + An array of resources instances with which this context is to be built. + + + An array of s, or if none. + + + + + + Encapsulates arguments to the class. + + + + + Initializes a new instance of the WebApplicationContextArgs class. + + + + + Initializes a new instance of the WebApplicationContextArgs class. + + The name. + The parent context. + The configuration locations. + The configuration resources. + + + + Initializes a new instance of the WebApplicationContextArgs class. + + The name. + The parent context. + The configuration locations. + The configuration resources. + if set to true [case sensitive]. + + + + Creates an instance + using context definitions supplied in a custom configuration and + configures the with that instance. + + + This class extends ContextHandler with + web specific behaviour. It uses WebApplicationContext + as default Context-Type. + + Erich Eichinger + + + + Gets the context name from the given + + + + + Throws a configuration exception, if child contexts are specified. + + + Nesting contexts in webapplications is done by explicitly declaring + spring context sections for each directory. + + + + + Handles web specific details of context instantiation. + + + + + Sets default context type to + + + + + Sets default case-sensitivity to 'false' for web-applications + + + + + Provides various support for proper handling requests. + + Erich Eichinger + + + + Identifies the Objectdefinition used for the current IHttpHandler instance in TLS + + + + + For webapplications always +
    +
  • convert IResources using the current context.
    • +
  • use "web" as default resource protocol
    • +
  • use as default threading storage
    • +
+ + + + + Registers this module for all events required by the Spring.Web framework + + + + + Configures the current IHttpHandler as specified by . + + + + + Configures the specified handler instance using the object definition . + + + TODO + + + + + + + + + + + TODO + + + + + + + + TODO + + + + + + + + + Disposes this instance + + + + + Holds the handler configuration information. + + + + + implementation specifically + for resources served up from a web server. + + +

+ Uses the System.Web.HttpContext.Current.Server.MapPath + method to resolve the file name for a given resource. +

+ + Aleksandar Seovic + + + + Creates a new instance of the class. + + + The name of the file system resource (on the server). + + + + + Resolves the handle + for the supplied . + + + The name of the file system resource. + + + The handle for this resource. + + + + + Resolves the root location for the supplied . + + + The name of the file system resource. + + + The root location of the resource. + + + + + Resolves the path for the supplied . + + + The name of the file system resource. + + + The current path of the resource. + + + + + Resolves the presence of the + value + in the supplied into a path. + + + The name of the resource. + + + The string that is a placeholder for a base path. + + + The name of the resource with any + value having been resolved into an actual path. + + + + + Does the supplied relative ? + + + The name of the resource to test. + + + if resource name is relative; + otherwise . + + + + + Factory Method. Create a new instance of the current resource type using the given resourceName + + + + + The ResourceLoader to be used for resolving relative resources + + + + + Gets those characters that are valid path separators for the + resource type. + + + Those characters that are valid path separators for the resource + type. + + + + + + This formatter acts as an adapter to a datasource. It parses a given datasource into + a table to allow converting back and forth between objects and their keys during formatting. + + + + The DataSourceItemFormatter expects the "source" to have 2 properties named "DataSourceField" and "DataValueField". + + + + + + + + + + + Sets the binding context of this formatter. + + + + + + + + + Clears the binding context of this formatter. + + + + + Initialize this instance. + + The name of the "source"s property containing the dataSource + The name of the "source"s property containing the name of the key property + + + + Sets the bindingContext for the current thread. + + The source object + The target object + Variables to be used during binding + The current binding's direction + + + + Reset the current thread's binding context. + + + + + Initialize a new instance. + + The datasource containing list items + The name of the listitem's property that evaluates to the item's key + The direction of the current binding + + + + Returns the key of the specified value object. + + The value to extract the key from. + Key extracted from . + + + + Return the object with the specified key from the datasource. + + The key of the object. + Parsed . + + + + Binds agroup of HTTP request multi-valued items to the data model. + + + Due to the fact, that browsers don't send the values of unchecked checkboxes, you + can't use for binding to checkboxes. + + Aleksandar Seovic + + + + Creates a new instance of . + + + Comma separated list of multi-valued request parameters that + should be used to create a target item. + + + Expression that identifies a target list items should be added to. + + + The type of the target item. + + + + + Adds the binding. + + + This is a convinience method for adding SimpleExpressionBinding, + one of the most often used binding types, to the bindings list. + + + The source expression. + + + The target expression. + + + Binding direction. + + + to use for value formatting and parsing. + + + Added instance. + + + + + Binds source object to target object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + Variables that should be used during expression evaluation. + + + + + Binds target object to source object. + + + The source object. + + + The target object. + + + Validation errors collection that type conversion errors should be added to. + + + Variables that should be used during expression evaluation. + + + + + A page or control must implement this interface to support spring's databinding infrastructure. + + + + + + + + + + Return the UniqueID of this page or control. + + + + + Return the where + instances should be optained from. + + + + + This event is raised to initialize bindings for . + + + + + Handles binding of a multiple selection ListControl to a target's IList property. + + + + + Creates a new instance of this binding. + + The expression that will evaluate to the acting as the source + The expression that will evaluate to an property acting as the target + Binding's direction + An optional formatter converting target items into and back + + If no formatter is specified, a will be used. + + + + + Actually performs unbinding the ListControl's selected values into the target's + + + + + Actually performs binding the targetlist to the ListControl. + + + + + Setting source value is not allowed in this bindingType. + + + + + Setting target value is not allowed in this bindingType. + + + + + Culture resolver that uses cookie to store culture information. + + Aleksandar Seovic + + + + Default culture resolver for web applications. Contains some common utility methods for web culture resolvers. + + Aleksandar Seovic + + + + Returns default culture. If property is not set, + it tries to get culture from the request headers + and falls back to a current thread's culture if no headers are available. + + Default culture to use. + + + + Extracts the users favorite language from "accept-language" header of the current request. + + a language string if any or null, if no languages have been sent with the request + + + + Resolves a culture by name. + + the name of the culture to get + a (possible neutral!) or null, if culture could not be resolved + + + + Resolves the culture from the context. + + Culture that should be used to render view. + + + + Not supported for this implementation. + + The new culture or null to clear the culture. + + + + Resolves the culture from the request. + + + If the culture cookie doesn't exist, this method will return + the value of the 'Accept-Language' request header, or if no + headers are specified, the culture of the current server thread. + + Culture that should be used to render view. + + + + Sets the culture. + + The new culture or null to clear the culture. + + + + Creates cookie for the specified culture. + + Culture to store in a cookie. + Created cookie. + + + + Culture resolver that uses request headers to determine culture. If no languages + are specified in the request headers, it returns default culture specifed, and + if no default culture was specifed it returns current culture for the executing + server thread. + + + Note: This culture resolver cannot be used to change the culture + because request headers cannot be modified. In order to change the culture + when using this culture resolver user has to change language settings in + the web browser. + + Aleksandar Seovic + + + + Tries to determine culture from the request headers. If no languages + are specified in the request headers, it returns default culture specifed, and + if no default culture was specifed it returns current culture for the executing + server thread. + + Culture that should be used to render view. + + + + Not supported for this resolver implementation + + The new culture or null to clear the culture. + + + + Culture resolver that uses HTTP session to store culture information. + + Aleksandar Seovic + + + + Resolves the culture from the request. + + + If culture information doesn't exist in the session, it will be created and its value will + be set to the value of the 'Accept-Language' request header, or if no + headers are specified to the culture of the current server thread. + + Culture that should be used to render view. + + + + Sets the culture. + + The new culture or null to clear the culture. + + + + Gets/Sets the current session's culture. + + + + + Resource cache implementation that uses ASP.NET to cache resources. + + Aleksandar Seovic + + + + Gets the list of resources from cache. + + Cache key to use for lookup. + A list of cached resources for the specified target object and culture. + + + + Puts the list of resources in the cache. + + Cache key to use for the specified resources. + A list of resources to cache. + + + + Web object definitions extend + by adding scope property. + + +

+ This is the most common type of object definition in ASP.Net web applications +

+ + Aleksandar Seovic + + + + Defines additional members web object definitions need to implement. + + Aleksandar Seovic + + + + Gets or sets scope for the web object (application, session or request) + + + + + Returns true if web object is .aspx page. + + + + + Gets the rooted url of the .aspx page, if object definition represents page. + + + + + Creates a new instance of the + class + for a singleton, providing property values and constructor arguments. + + Name of the parent object definition. + The class of the object to instantiate. + + The + to be applied to a new instance of the object. + + + The to be applied to + a new instance of the object. + + + + + Creates a new instance of the + class + for a singleton, providing property values and constructor arguments. + + Name of the parent object definition. + The class name of the object to instantiate. + + The + to be applied to a new instance of the object. + + + The to be applied to + a new instance of the object. + + + + + Creates a new instance of the + class + for an .aspx page, providing property values. + + Name of the parent object definition. + Name of the .aspx page to instantiate. + + The to be applied to + a new instance of the object. + + + + + Overrides this object's values using values from other argument. + + The object to copy values from. + + + + A that represents the current + . + + + A that represents the current + . + + + + + Object scope. + + + + + Returns true if web object is .aspx page. + + + + + Gets the rooted url of the .aspx page, if object definition represents page. + + + + + Forces ASP pages to be treated as prototypes all the time inorder to comply with ASP.Net requirements. + + + + + + Erich Eichinger + + + + Web object definitions extend + by adding scope property. + + +

+ This is the most common type of object definition in ASP.Net web applications +

+ + Aleksandar Seovic + + + + Creates a new instance of the + class + for a singleton, providing property values and constructor arguments. + + + The type of the object to instantiate. + + + The to be applied to + a new instance of the object. + + + The + to be applied to a new instance of the object. + + + + + Creates a new instance of the + class + for a singleton, providing property values and constructor arguments. + + + The assembly qualified of the object to instantiate. + + + The to be applied to + a new instance of the object. + + + The + to be applied to a new instance of the object. + + +

+ Takes an object class name to avoid eager loading of the object class. +

+ + + + + Creates a new instance of the + class + for an .aspx page, providing property values. + + + Name of the .aspx page to instantiate. + + + The to be applied to + a new instance of the object. + + + + + Creates a new instance of the + class + + + The definition that is to be copied. + + +

+ Deep copy constructor. +

+ + + + + Overrides this object's values using values from other argument. + + The object to copy values from. + + + + A that represents the current + . + + + A that represents the current + . + + + + + Object scope. + + + + + Returns true if web object is .aspx page. + + + + + Gets the rooted url of the .aspx page, if object definition represents page. + + + + + Forces ASP pages to be treated as prototypes all the time inorder to comply with ASP.Net requirements. + + + + + Object instantiation strategy for use in + . + + +

+ This strategy checks if objects id ASP.Net page and if it is uses + PageParser to compile and instantiate page instance. Otherwise it + delagates call to its parent. +

+ + Aleksandar Seovic + + + + Creates a new instance of the + class. + + + + + Instantiate an instance of the object described by the supplied + from the supplied . + + + The definition of the object that is to be instantiated. + + + The name associated with the object definition. The name can be the null + or zero length string if we're autowiring an object that doesn't belong + to the supplied . + + + The owning + + + An instance of the object described by the supplied + from the supplied . + + + + + Custom implementation of + for web applications. + + +

+ This implementation adds support for .aspx pages and scoped objects. +

+ + Aleksandar Seovic + + + + Factory style method for getting concrete + + instances. + + If no parent is specified, a RootWebObjectDefinition is created, otherwise a + ChildWebObjectDefinition. + The of the defined object. + The name of the parent object definition (if any). + The against which any class names + will be resolved into instances. + + An + + instance. + + + + + Concrete implementation of + that knows + how to handle s. + + +

+ This class should only be used within the context of an ASP.NET web application. +

+ + Aleksandar Seovic + + + + Holds the virtual path this factory has been created from. + + + + + Holds the handler reference for creating an object dictionary + matching this factory's case-sensitivity + + + + + Registers events handlers with to ensure + proper disposal of 'request'- and 'session'-scoped objects + + + + + Creates a new instance of the + class. + + The virtual path resources will be relative resolved to. + Flag specifying whether to make this object factory case sensitive or not. + + + + Creates a new instance of the + class. + + The virtual path resources will be relative resolved to. + Flag specifying whether to make this object factory case sensitive or not. + + The parent object factory. + + + + + Creates a dictionary matching this factory's case sensitivity behaviour. + + + + + Creates the root object definition. + + The template definition. + Root object definition. + + + + Tries to find cached object for the specified name. + + + This implementation tries to find object first in the Request scope, + then in the Session scope and finally in the Application scope. + + Object name to look for. + Cached object if found, null otherwise. + + + + Looks up an in the specified cache dictionary. + + the name to lookup. + the cache dictionary to search + the found instance. null otherwise + + + + Creates a singleton instance for the specified object name and definition. + + + The object name (will be used as the key in the singleton cache key). + + The object definition. + + The arguments to use if creating a prototype using explicit arguments to + a static factory method. It is invalid to use a non-null arguments value + in any other case. + + The created object instance. + + + + Creates a singleton instance for the specified object name and definition + and caches the instance in the specified dictionary + + + The object name (will be used as the key in the singleton cache key). + + The object definition. + + The arguments to use if creating a prototype using explicit arguments to + a static factory method. It is invalid to use a non-null arguments value + in any other case. + + the dictionary to be used for caching singleton instances + The created object instance. + + If the object is successfully created, + contains the cached instance with the key . + + + + + Add the created, but yet unpopulated singleton to the singleton cache + to be able to resolve circular references + + the name of the object to add to the cache. + the definition used to create and populated the object. + the raw object instance. + + Derived classes may override this method to select the right cache based on the object definition. + + + + + Remove the specified singleton from the singleton cache that has + been added before by a call to + + the name of the object to remove from the cache. + the definition used to create and populated the object. + + Derived classes may override this method to select the right cache based on the object definition. + + + + + Configures object instance by injecting dependencies, satisfying Spring lifecycle + interfaces and applying object post-processors. + + + The name of the object definition expressing the dependencies that are to + be injected into the supplied instance. + + + An object definition that should be used to configure object. + + + A wrapped object instance that is to be so configured. + + + + + + Disposes all 'request'-scoped objects at the end of each Request + + + + + Disposes all 'session'-scoped objects at the end of a session + + + + + Creates a case insensitive hashtable instance + + + + + Creates a case sensitive hashtable instance + + + + + Returns the virtual path this object factory is associated with. + + + + + Convinience accessor for HttpContext + + + + + Get the table of 'request'-scoped objects. + + + + + Get the table of 'session'-scoped objects. Returns null, if Session is disabled. + + + + + Miscellaneous utility methods to support web functionality within Spring.Objects + + Aleksandar Seovic + + + + Creates a new instance of the class. + + +

+ This is a utility class, and as such exposes no public constructors. +

+ + + + + Creates an instance of the ASPX page + referred to by the supplied . + + + The URL of the ASPX page. + + Page instance. + + If this method is not called in the scope of an active web session + (i.e. the implementation this method depends on this code executing + in the environs of a running web server such as IIS); or if the + page could not be instantiated (for whatever reason, such as the + ASPX not actually existing). + + + + + Creates the raw handler instance without any exception handling + + + + + + + Returns the of the ASPX page + referred to by the supplied . + + +

+ As indicated by the exception that can be thrown by this method, + the ASPX page referred to by the supplied + does have to be instantiated in order to determine its + see cref="System.Type"/> +

+ + + The filename of the ASPX page. + + + The of the ASPX page + referred to by the supplied . + + + If the supplied is or + contains only whitespace character(s). + + + If this method is not called in the scope of an active web session + (i.e. the implementation this method depends on this code executing + in the environs of a running web server such as IIS); or if the + page could not be instantiated (for whatever reason, such as the + ASPX not actually existing). + + + + + Calls the underlying ASP.NET infrastructure to obtain the compiled page type + relative to the current . + + + The filename of the ASPX page relative to the current + + + The of the ASPX page + referred to by the supplied . + + + + + Gets the controls type from a given filename + + + + + An capable of handling web objects (Pages,Controls). + + Erich Eichinger + + + + Creates an instance for the given + and element. + + + + + An capable of handling web objects (Pages,Controls) + + Erich Eichinger + + + + Initializes a new instance of the class. + + used for generating object definition names from web object types (page, control) + The reader context. + The root element of the xml document to parse + + + + Gets the scope out of the supplied . + + +

+ If the supplied is invalid + (i.e. it does not resolve to one of the + values), + then the return value of this method call will be + ; + no exception will be raised (although the value of the invalid + scope will be logged). +

+ + The string containing the scope name. + The scope. + + + + + An capable of handling web object definitions (Pages, Controls) + + Erich Eichinger + + + + Creates a new instance of the + class. + + the (rooted) virtual path to resolve relative virtual paths. + + The + instance that this reader works on. + + the to use for resolving entities. + + + + Creates the to use for actually + reading object definitions from an XML document. + + + + + Create an object definition name for the given control path + + + + + Create an object definition name for the given page path + + + + + A custom implementation of the + + interface that properly handles web application specific attributes, + such as object scope. + + +

+ Parses object definitions according to the standard Spring.NET schema. +

+ + Aleksandar Seovic + + + + + Creates a new instance of the + class. + + + + + Implements by using . + + Erich Eichinger + + + + Retrieves an object with the specified name. + + The name of the item. + The object in the context associated with the specified name or null if no object has been stored previously + + + + Stores a given object and associates it with the specified name. + + The name with which to associate the new item. + The object to store in the call context. + + + + Empties a data slot with the specified name. + + The name of the data slot to empty. + + + + Implements by using both and and choosing dynamically between them. + + + In web applications a single Request may be executed on different threads. In this case HttpContext.Current is the only invariant.
+ This implementation dynamically chooses between System.Runtime.Remoting.Messaging.CallContext + and System.Web.HttpContext to store data. + + Erich Eichinger + + + + Retrieves an object with the specified name. + + The name of the item. + The object in the context associated with the specified name or null if no object has been stored previously + + + + Stores a given object and associates it with the specified name. + + The name with which to associate the new item. + The object to store in the call context. + + + + Empties a data slot with the specified name. + + The name of the data slot to empty. + + + + Performs a . Original path will be restored on + + + Rewrites the current HttpContext's filepath to <directory>/currentcontext.dummy.
+ This affects resolving resources by calls to and
+ Original path is restored during . + + + + using( new HttpContextSwitch( "/path" ) ) + { + Response.Write( Request.FilePath ); // writes "/path/currentcontext.dummy" to response. + } + // Request.FilePath has been reset to original url here + + + Erich Eichinger + + + + Performs an immediate call to + + a directory path (without trailing filename!) + + + + Restores original path if necessary + + + + + Abstracts HttpSession + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Abstracts the underlying infrastructure of a HttpRequest + + + + + Maps a virtual path to it's physical location + + + + + Rewrites the , thus also affecting + + + + + Get the compiled type for the given virtual path + + the absolute (=rooted) virtual path + + + + + Creates an instance from the given virtual path + + the absolute (=rooted) virtual path + the required base type + + + + The virtual (rooted) path of the current Application with trailing slash + + + For the site rooted applications, "/" will be returned, for all others "/..someappdir../" + + + + + The virtual (rooted) path of the current Request including + + + + + The virtual (rooted) path of the current Request without trailing + + + + + The virtual (rooted) path of the currently executing script + + + Normally this property is the same as . + In case of , this property returns the current script + whereas CurrentVirtualPath returns the original script path. + + + + + The query parameters + + + + + Returns the current Session's variable dictionary + + + + + Returns the current Request's variable dictionary + + + + + Returns the current Request's parameter dictionary + + + + + Utility class to be used from within this assembly for executing security critical code + NEVER EVER MAKE THIS PUBLIC! + + Erich Eichinger + + + + Provides platform independent access to HttpRuntime methods + + + For e.g. testing purposes, the default environment implementation may be replaced using . + + Erich Eichinger + + + + Replaces the current enviroment implementation. + + the new environment implementation to be used + the previously set environment instance + + + + Maps a virtual path to it's physical location + + + + + Rewrites the , thus also affecting + + + + + Returns an instance of the specified file. + + + + + Returns an the compiled type of the specified file. + + + + + Receives EndRequest-event from an instance + and dispatches it to all handlers registered with this module. + + the HttpApplication instance sending this event + always + + + + Receives the EndSession-event and dispatches it to all handlers + registered with this module. + + + + + Signals, that VirtualEnvironment is ready to accept + handler registrations for EndRequest and EndSession events + + + + + Ensures, that WebSupportModule has been initialized. Otherwise an exception is thrown. + + + + + The virtual (rooted) path of the current Application containing a leading '/' as well as a trailing '/' + + + + + The virtual (rooted) path of the current Request including + + + + + The virtual (rooted) path of the current Request including + + + + + The virtual (rooted) path of the current Request without trailing + + + + + The virtual (rooted) path of the currently executing script + + + + + The query parameters + + + + + Returns the current Request's variable dictionary () + + + + + Returns the current Request's parameter dictionary () + + + + + Register with this event to receive any EndRequest event occuring in the current AppDomain. + + + + + Register with this event to receive any EndSession event occuring in the current AppDomain + + + This event may be raised asynchronously on it's own thread. + Don't rely on e.g. being available. + + + + + Is this VirtualEnviroment ready to accept handler registrations + for EndRequest and EndSession events ? + + + + + Represents a method that handles Request related events + + + + + Represents a method that handles Session related events + + + + + Implementation for running within HttpRuntime + + + + + Miscellaneous web utility methods. + + Aleksandar Seovic + + + + Creates a new instance of the class. + + +

+ This is a utility class, and as such exposes no public constructors. +

+ + + + + Default protocol used for resolving resources in web applications + + + + + Extracts the bare ASPX page name without any extension from the + supplied . + + +

+ Examples of what would be returned from this method given a url would be: +

+

+ + 'Login.aspx' => 'Login' + '~/Login.aspx' => 'Login' + '~/B2B/SignUp.aspx' => 'SignUp' + 'B2B/Foo/FooServices.aspx' => 'FooServices' + +

+ + The full URL to the ASPX page. + + The bare ASPX page name without any extension. + + + If the supplied is or + contains only whitespace character(s). + + + + + Returns only the directory portion of a virtual path + + + The returned path is guaranteed to always have a leading and a trailing slash.
+ If a path does not end with a file-extension it is assumed to be a directory + + + + + Returns absolute path that can be referenced within plain HTML. + + +

+ If relative path starts with '/' (forward slash), no concatenation will occur + and it will be assumed that the relative path specified is indeed the absolute path + and will be returned verbatim.

+

+ Otherwise, relative path will be appended to the application path, while making sure that + path separators are not duplicated between the paths.

+ + Application path. + Relative path to combine with the application path. + Absolute path. + + + + Combines a rooted base path with a relative path. + + Must be a path starting with '/' + the path to be combined. May start with basepath Placeholder '~' + the combined path + + If relativePath starts with '~', rootPath is ignored and '~' resolves to the current AppDomain's application virtual path
+ If relativePath start with '/', rootPath is ignored and relativePath is returned as-is. + + + + + Gets the application-relative virtual path portion of the given absolute URL. + + the absolute url + the url relative to the current application's virtual path + + + + Gets the virtual path portion of the given absolute URL + relative to the given base path. + + + Base path comparison is done case insensitive. + + the absolute base path + the absolute url + the url relative to the given basePath + + + + Returns the 'logical' parent of the specified control. Technically when dealing with masterpages and control hierarchy, + the order goes controls->masterpage->page. But one often wants the more logical order controls->page->masterpage. + + the control, who's parent is to be determined. + the logical parent or null if the top of the hierarchy is reached. + if is null + + + + Encode for use in URLs. + + the text to be encoded. + the url-encoded + + This method may be used outside of a current request. If executed within a + request, is used. + will be used otherwise. + + + + + A spring configurable version of + + Erich Eichinger + + + + An Interface for class. + + Damjan Tomic + + + + Initializes the provider. + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + The providerId attribute is mandatory. + + The friendly name of the provider. + The or is null. + An attempt is made to call on a provider after the provider has already been initialized. + The has a length of zero or providerId attribute is not set. + + + + Adds a new membership user to the data source. + + + + A object populated with the information for the newly created user. + + + Whether or not the new user is approved to be validated. + The password answer for the new user + The user name for the new user. + The unique identifier from the membership data source for the user. + The password for the new user. + The password question for the new user. + The e-mail address for the new user. + A enumeration value indicating whether the user was created successfully. + + + + Processes a request to update the password question and answer for a membership user. + + + + true if the password question and answer are updated successfully; otherwise, false. + + + The new password question for the specified user. + The new password answer for the specified user. + The user to change the password question and answer for. + The password for the specified user. + + + + Gets the password for the specified user name from the data source. + + + + The password for the specified user name. + + + The user to retrieve the password for. + The password answer for the user. + + + + Processes a request to update the password for a membership user. + + + + true if the password was updated successfully; otherwise, false. + + + The new password for the specified user. + The current password for the specified user. + The user to update the password for. + + + + Resets a user's password to a new, automatically generated password. + + + + The new password for the specified user. + + + The user to reset the password for. + The password answer for the specified user. + + + + Updates information about a user in the data source. + + + A object that represents the user to update and the updated information for the user. + + + + Verifies that the specified user name and password exist in the data source. + + + + true if the specified username and password are valid; otherwise, false. + + + The name of the user to validate. + The password for the specified user. + + + + Clears a lock so that the membership user can be validated. + + + + true if the membership user was successfully unlocked; otherwise, false. + + + The membership user to clear the lock status for. + + + + Gets information from the data source for a user based on the unique identifier for the membership user. Provides an option to update the last-activity date/time stamp for the user. + + + + A object populated with the specified user's information from the data source. + + + The unique identifier for the membership user to get information for. + true to update the last-activity date/time stamp for the user; false to return user information without updating the last-activity date/time stamp for the user. + + + + Gets information from the data source for a user. Provides an option to update the last-activity date/time stamp for the user. + + + + A object populated with the specified user's information from the data source. + + + The name of the user to get information for. + true to update the last-activity date/time stamp for the user; false to return user information without updating the last-activity date/time stamp for the user. + + + + Gets the user name associated with the specified e-mail address. + + + + The user name associated with the specified e-mail address. If no match is found, return null. + + + The e-mail address to search for. + + + + Removes a user from the membership data source. + + + + true if the user was successfully deleted; otherwise, false. + + + The name of the user to delete. + true to delete data related to the user from the database; false to leave data related to the user in the database. + + + + Gets a collection of all the users in the data source in pages of data. + + + + A collection that contains a page of pageSize objects beginning at the page specified by pageIndex. + + + The total number of matched users. + The index of the page of results to return. pageIndex is zero-based. + The size of the page of results to return. + + + + Gets the number of users currently accessing the application. + + + + The number of users currently accessing the application. + + + + + + Gets a collection of membership users where the user name contains the specified user name to match. + + + + A collection that contains a page of pageSize objects beginning at the page specified by pageIndex. + + + The total number of matched users. + The index of the page of results to return. pageIndex is zero-based. + The user name to search for. + The size of the page of results to return. + + + + Gets a collection of membership users where the e-mail address contains the specified e-mail address to match. + + + + A collection that contains a page of pageSize objects beginning at the page specified by pageIndex. + + + The total number of matched users. + The index of the page of results to return. pageIndex is zero-based. + The e-mail address to search for. + The size of the page of results to return. + + + + Gets the friendly name used to refer to the provider during configuration. + + + + The friendly name used to refer to the provider during configuration. + + + + + + Gets a brief, friendly description suitable for display in administrative tools or other user interfaces (UIs). + + + + A brief, friendly description suitable for display in administrative tools or other UIs. + + + + + + Indicates whether the membership provider is configured to allow users to retrieve their passwords. + + + + true if the membership provider is configured to support password retrieval; otherwise, false. The default is false. + + + + + + Indicates whether the membership provider is configured to allow users to reset their passwords. + + + + true if the membership provider supports password reset; otherwise, false. The default is true. + + + + + + Gets a value indicating whether the membership provider is configured to require the user to answer a password question for password reset and retrieval. + + + + true if a password answer is required for password reset and retrieval; otherwise, false. The default is true. + + + + + + The name of the application using the custom membership provider. + + + + The name of the application using the custom membership provider. + + + + + + Gets the number of invalid password or password-answer attempts allowed before the membership user is locked out. + + + + The number of invalid password or password-answer attempts allowed before the membership user is locked out. + + + + + + Gets the number of minutes in which a maximum number of invalid password or password-answer attempts are allowed before the membership user is locked out. + + + + The number of minutes in which a maximum number of invalid password or password-answer attempts are allowed before the membership user is locked out. + + + + + + Gets a value indicating whether the membership provider is configured to require a unique e-mail address for each user name. + + + + true if the membership provider requires a unique e-mail address; otherwise, false. The default is true. + + + + + + Gets a value indicating the format for storing passwords in the membership data store. + + + + One of the values indicating the format for storing passwords in the data store. + + + + + + Gets the minimum length required for a password. + + + + The minimum length required for a password. + + + + + + Gets the minimum number of special characters that must be present in a valid password. + + + + The minimum number of special characters that must be present in a valid password. + + + + + + Gets the regular expression used to evaluate a password. + + + + A regular expression used to evaluate a password. + + + + + + Initializes the provider. + + + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + + Values may be overridden by specifying them in list. + + The friendly name of the provider. + The or is null. + An attempt is made to call on a provider after the provider has already been initialized. + The has a length of zero or providerId attribute is not set. + + + + The ConnectionString to be used + + + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + + + + + + + Erich Eichinger + + + + An Interface for class. + + +

+ Configuration for this provider requires providerId element set in web.config file, + as the Id of wrapped provider (defined in the Spring context). +

+ + Damjan Tomic + + + + Initializes the provider. + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + The providerId attribute is mandatory. + + The friendly name of the provider. + The or is null. + An attempt is made to call on a provider after the provider has already been initialized. + The has a length of zero or providerId attribute is not set. + + + + Returns the collection of settings property values for the specified application instance and settings property group. + + + + A containing the values for the specified settings property group. + + + A describing the current application use. + A containing the settings property group whose values are to be retrieved.2 + + + + Sets the values of the specified group of property settings. + + + A describing the current application usage. + A representing the group of property settings to set.2 + + + + When overridden in a derived class, deletes profile properties and information for the supplied list of profiles. + + + + The number of profiles deleted from the data source. + + + A of information about profiles that are to be deleted. + + + + When overridden in a derived class, deletes profile properties and information for profiles that match the supplied list of user names. + + + + The number of profiles deleted from the data source. + + + A string array of user names for profiles to be deleted. + + + + When overridden in a derived class, deletes all user-profile data for profiles in which the last activity date occurred before the specified date. + + + + The number of profiles deleted from the data source. + + + One of the values, specifying whether anonymous, authenticated, or both types of profiles are deleted. + A that identifies which user profiles are considered inactive. If the value of a user profile occurs on or before this date and time, the profile is considered inactive. + + + + When overridden in a derived class, returns the number of profiles in which the last activity date occurred on or before the specified date. + + + + The number of profiles in which the last activity date occurred on or before the specified date. + + + One of the values, specifying whether anonymous, authenticated, or both types of profiles are returned. + A that identifies which user profiles are considered inactive. If the of a user profile occurs on or before this date and time, the profile is considered inactive. + + + + When overridden in a derived class, retrieves user profile data for all profiles in the data source. + + + + A containing user-profile information for all profiles in the data source. + + + One of the values, specifying whether anonymous, authenticated, or both types of profiles are returned. + When this method returns, contains the total number of profiles. + The index of the page of results to return. + The size of the page of results to return. + + + + When overridden in a derived class, retrieves user-profile data from the data source for profiles in which the last activity date occurred on or before the specified date. + + + + A containing user-profile information about the inactive profiles. + + + One of the values, specifying whether anonymous, authenticated, or both types of profiles are returned. + A that identifies which user profiles are considered inactive. If the of a user profile occurs on or before this date and time, the profile is considered inactive. + When this method returns, contains the total number of profiles. + The index of the page of results to return. + The size of the page of results to return. + + + + When overridden in a derived class, retrieves profile information for profiles in which the user name matches the specified user names. + + + + A containing user-profile information for profiles where the user name matches the supplied usernameToMatch parameter. + + + One of the values, specifying whether anonymous, authenticated, or both types of profiles are returned. + When this method returns, contains the total number of profiles. + The index of the page of results to return. + The user name to search for. + The size of the page of results to return. + + + + When overridden in a derived class, retrieves profile information for profiles in which the last activity date occurred on or before the specified date and the user name matches the specified user name. + + + + A containing user profile information for inactive profiles where the user name matches the supplied usernameToMatch parameter. + + + One of the values, specifying whether anonymous, authenticated, or both types of profiles are returned. + A that identifies which user profiles are considered inactive. If the value of a user profile occurs on or before this date and time, the profile is considered inactive. + When this method returns, contains the total number of profiles. + The index of the page of results to return. + The user name to search for. + The size of the page of results to return. + + + + Gets the friendly name used to refer to the provider during configuration. + + + + The friendly name used to refer to the provider during configuration. + + + + + Gets a brief, friendly description suitable for display in administrative tools or other user interfaces (UIs). + + + + A brief, friendly description suitable for display in administrative tools or other UIs. + + + + + Gets or sets the name of the currently running application. + + + + A that contains the application's shortened name, which does not contain a full path or extension, for example, SimpleAppSettings. + + 2 + + + + Initializes the provider. + + + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + + Values may be overridden by specifying them in list. + + The friendly name of the provider. + The or is null. + An attempt is made to call on a provider after the provider has already been initialized. + The has a length of zero or providerId attribute is not set. + + + + The ConnectionString to be used + + + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + + + + + A spring-configurable version of + + Erich Eichinger + + + + An Interface for class. + + +

+ Configuration for this provider requires providerId element set in web.config file, + as the Id of wrapped provider (defined in the Spring context). +

+ + Damjan Tomic + + + + Initializes the provider. + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + The providerId attribute is mandatory. + + The friendly name of the provider. + The or is null. + An attempt is made to call on a provider after the provider has already been initialized. + The has a length of zero or providerId attribute is not set. + + + + Gets a value indicating whether the specified user is in the specified role for the configured applicationName. + + + + true if the specified user is in the specified role for the configured applicationName; otherwise, false. + + + The user name to search for. + The role to search in. + + + + Gets a list of the roles that a specified user is in for the configured applicationName. + + + + A string array containing the names of all the roles that the specified user is in for the configured applicationName. + + + The user to return a list of roles for. + + + + Adds a new role to the data source for the configured applicationName. + + + The name of the role to create. + + + + Removes a role from the data source for the configured applicationName. + + + + true if the role was successfully deleted; otherwise, false. + + + If true, throw an exception if roleName has one or more members and do not delete roleName. + The name of the role to delete. + + + + Gets a value indicating whether the specified role name already exists in the role data source for the configured applicationName. + + + + true if the role name already exists in the data source for the configured applicationName; otherwise, false. + + + The name of the role to search for in the data source. + + + + Adds the specified user names to the specified roles for the configured applicationName. + + + A string array of the role names to add the specified user names to. + A string array of user names to be added to the specified roles. + + + + Removes the specified user names from the specified roles for the configured applicationName. + + + A string array of role names to remove the specified user names from. + A string array of user names to be removed from the specified roles. + + + + Gets a list of users in the specified role for the configured applicationName. + + + + A string array containing the names of all the users who are members of the specified role for the configured applicationName. + + + The name of the role to get the list of users for. + + + + Gets a list of all the roles for the configured applicationName. + + + + A string array containing the names of all the roles stored in the data source for the configured applicationName. + + + + + + Gets an array of user names in a role where the user name contains the specified user name to match. + + + + A string array containing the names of all the users where the user name matches usernameToMatch and the user is a member of the specified role. + + + The user name to search for. + The role to search in. + + + + Gets the friendly name used to refer to the provider during configuration. + + + + The friendly name used to refer to the provider during configuration. + + + + + Gets a brief, friendly description suitable for display in administrative tools or other user interfaces (UIs). + + + + A brief, friendly description suitable for display in administrative tools or other UIs. + + + + + Gets or sets the name of the application to store and retrieve role information for. + + + + The name of the application to store and retrieve role information for. + + + + + + Initializes the provider. + + + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + + Values may be overridden by specifying them in list. + + The friendly name of the provider. + The or is null. + An attempt is made to call on a provider after the provider has already been initialized. + The has a length of zero or providerId attribute is not set. + + + + The ConnectionString to be used + + + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + + + + + A spring-configurable version of + + Erich Eichinger + + + + An Interface for class. + + +

+ Configuration for this provider requires providerId element set in web.config file, + as the Id of wrapped provider (defined in the Spring context). +

+ + Damjan Tomic + + + + Initializes the provider. + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + The providerId attribute is mandatory. + + The friendly name of the provider. + The or is null. + An attempt is made to call on a provider after the provider has already been initialized. + The has a length of zero or providerId attribute is not set. + + + + Retrieves a object that represents the currently requested page using the specified object. + + + + A that represents the currently requested page; otherwise, null, if no corresponding can be found in the or if the page context is null. + + + The used to match node information with the URL of the requested page. + + + + Retrieves a object based on a specified key. + + + + A that represents the page identified by key; otherwise, null, if no corresponding is found or if security trimming is enabled and the cannot be returned for the current user. The default is null. + + + A lookup key with which a is created. + + + + When overridden in a derived class, retrieves a object that represents the page at the specified URL. + + + + A that represents the page identified by rawURL; otherwise, null, if no corresponding is found or if security trimming is enabled and the cannot be returned for the current user. + + + A URL that identifies the page for which to retrieve a . + + + + When overridden in a derived class, retrieves the child nodes of a specific . + + + + A read-only that contains the immediate child nodes of the specified ; otherwise, null or an empty collection, if no child nodes exist. + + + The for which to retrieve all child nodes. + + + + Provides an optimized lookup method for site map providers when retrieving the node for the currently requested page and fetching the parent and ancestor site map nodes for the current page. + + + + A that represents the currently requested page; otherwise, null, if the is not found or cannot be returned for the current user. + + + The number of ancestor site map node generations to get. A value of -1 indicates that all ancestors might be retrieved and cached by the provider. + upLevel is less than -1. + + + + Provides an optimized lookup method for site map providers when retrieving the node for the currently requested page and fetching the site map nodes in the proximity of the current node. + + + + A that represents the currently requested page; otherwise, null, if the is not found or cannot be returned for the current user. + + + The number of ancestor generations to fetch. 0 indicates no ancestor nodes are retrieved and -1 indicates that all ancestors might be retrieved and cached by the provider. + The number of child generations to fetch. 0 indicates no descendant nodes are retrieved and a -1 indicates that all descendant nodes might be retrieved and cached by the provider. + upLevel or downLevel is less than -1. + + + + When overridden in a derived class, retrieves the parent node of a specific object. + + + + A that represents the parent of node; otherwise, null, if the has no parent or security trimming is enabled and the parent node is not accessible to the current user. + + + The for which to retrieve the parent node. + + + + Provides an optimized lookup method for site map providers when retrieving an ancestor node for the currently requested page and fetching the descendant nodes for the ancestor. + + + + A that represents an ancestor of the currently requested page; otherwise, null, if the current or ancestor is not found or cannot be returned for the current user. + + + The number of descendant node levels to retrieve from the target ancestor node. + The number of ancestor node levels to traverse when retrieving the requested ancestor node. + walkupLevels or relativeDepthFromWalkup is less than 0. + + + + Provides an optimized lookup method for site map providers when retrieving an ancestor node for the specified object and fetching its child nodes. + + + + A that represents an ancestor of node; otherwise, null, if the current or ancestor is not found or cannot be returned for the current user. + + + The number of descendant node levels to retrieve from the target ancestor node. + The that acts as a reference point for walkupLevels and relativeDepthFromWalkup. + The number of ancestor node levels to traverse when retrieving the requested ancestor node. + The value specified for walkupLevels or relativeDepthFromWalkup is less than 0. + node is null. + + + + Provides a method that site map providers can override to perform an optimized retrieval of one or more levels of parent and ancestor nodes, relative to the specified object. + + + The number of ancestor generations to fetch. 0 indicates no ancestor nodes are retrieved and -1 indicates that all ancestors might be retrieved and cached. + The that acts as a reference point for upLevel. + upLevel is less than -1. + node is null. + + + + Provides a method that site map providers can override to perform an optimized retrieval of nodes found in the proximity of the specified node. + + + The number of ancestor generations to fetch. 0 indicates no ancestor nodes are retrieved and -1 indicates that all ancestors (and their descendant nodes to the level of node) might be retrieved and cached. + The number of descendant generations to fetch. 0 indicates no descendant nodes are retrieved and -1 indicates that all descendant nodes might be retrieved and cached. + The that acts as a reference point for upLevel. + upLevel or downLevel is less than -1. + node is null. + + + + Retrieves a Boolean value indicating whether the specified object can be viewed by the user in the specified context. + + + + true if security trimming is enabled and node can be viewed by the user or security trimming is not enabled; otherwise, false. + + + The that contains user information. + The that is requested by the user. + context is null.- or -node is null. + + + + Gets the friendly name used to refer to the provider during configuration. + + + + The friendly name used to refer to the provider during configuration. + + + + + + Gets a brief, friendly description suitable for display in administrative tools or other user interfaces (UIs). + + + + A brief, friendly description suitable for display in administrative tools or other UIs. + + + + + + Gets the object that represents the currently requested page. + + + + A that represents the currently requested page; otherwise, null, if the is not found or cannot be returned for the current user. + + + + + + Gets or sets the parent object of the current provider. + + + + The parent provider of the current . + + + + + + Gets the root object in the current provider hierarchy. + + + + An that is the top-level site map provider in the provider hierarchy that the current provider belongs to. + + + There is a circular reference to the current site map provider. + + + + Gets the root object of the site map data that the current provider represents. + + + + The root of the current site map data provider. The default implementation performs security trimming on the returned node. + + + + + + Initializes the provider. + + + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + + Values may be overridden by specifying them in list. + + The friendly name of the provider. + The or is null. + An attempt is made to call on a provider after the provider has already been initialized. + The has a length of zero or providerId attribute is not set. + + + + The XML file to be used for reading in the sitemap + + + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + + + + + Wrapper for class. + + +

+ Configuration for this provider requires providerId element set in web.config file, + as the Id of wrapped provider (defined in the Spring context). +

+ + Damjan Tomic + + + + Reference to wrapped provider (defined in Spring context). + + + + + Initializes the provider. + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + The providerId attribute may be used to override the name being used for looking up an object definition. + + The friendly name of the provider. + The or is null. + An attempt is made to call on a provider after the provider has already been initialized. + The has a length of zero or providerId attribute is not set. + + + + Adds a new membership user to the data source. + + + + A object populated with the information for the newly created user. + + + Whether or not the new user is approved to be validated. + The password answer for the new user + The user name for the new user. + The unique identifier from the membership data source for the user. + The password for the new user. + The password question for the new user. + The e-mail address for the new user. + A enumeration value indicating whether the user was created successfully. + + + + Processes a request to update the password question and answer for a membership user. + + + + true if the password question and answer are updated successfully; otherwise, false. + + + The new password question for the specified user. + The new password answer for the specified user. + The user to change the password question and answer for. + The password for the specified user. + + + + Gets the password for the specified user name from the data source. + + + + The password for the specified user name. + + + The user to retrieve the password for. + The password answer for the user. + + + + Processes a request to update the password for a membership user. + + + + true if the password was updated successfully; otherwise, false. + + + The new password for the specified user. + The current password for the specified user. + The user to update the password for. + + + + Resets a user's password to a new, automatically generated password. + + + + The new password for the specified user. + + + The user to reset the password for. + The password answer for the specified user. + + + + Updates information about a user in the data source. + + + A object that represents the user to update and the updated information for the user. + + + + Verifies that the specified user name and password exist in the data source. + + + + true if the specified username and password are valid; otherwise, false. + + + The name of the user to validate. + The password for the specified user. + + + + Clears a lock so that the membership user can be validated. + + + + true if the membership user was successfully unlocked; otherwise, false. + + + The membership user to clear the lock status for. + + + + Gets information from the data source for a user based on the unique identifier for the membership user. Provides an option to update the last-activity date/time stamp for the user. + + + + A object populated with the specified user's information from the data source. + + + The unique identifier for the membership user to get information for. + true to update the last-activity date/time stamp for the user; false to return user information without updating the last-activity date/time stamp for the user. + + + + Gets information from the data source for a user. Provides an option to update the last-activity date/time stamp for the user. + + + + A object populated with the specified user's information from the data source. + + + The name of the user to get information for. + true to update the last-activity date/time stamp for the user; false to return user information without updating the last-activity date/time stamp for the user. + + + + Gets the user name associated with the specified e-mail address. + + + + The user name associated with the specified e-mail address. If no match is found, return null. + + + The e-mail address to search for. + + + + Removes a user from the membership data source. + + + + true if the user was successfully deleted; otherwise, false. + + + The name of the user to delete. + true to delete data related to the user from the database; false to leave data related to the user in the database. + + + + Gets a collection of all the users in the data source in pages of data. + + + + A collection that contains a page of pageSize objects beginning at the page specified by pageIndex. + + + The total number of matched users. + The index of the page of results to return. pageIndex is zero-based. + The size of the page of results to return. + + + + Gets the number of users currently accessing the application. + + + + The number of users currently accessing the application. + + + + + + Gets a collection of membership users where the user name contains the specified user name to match. + + + + A collection that contains a page of pageSize objects beginning at the page specified by pageIndex. + + + The total number of matched users. + The index of the page of results to return. pageIndex is zero-based. + The user name to search for. + The size of the page of results to return. + + + + Gets a collection of membership users where the e-mail address contains the specified e-mail address to match. + + + + A collection that contains a page of pageSize objects beginning at the page specified by pageIndex. + + + The total number of matched users. + The index of the page of results to return. pageIndex is zero-based. + The e-mail address to search for. + The size of the page of results to return. + + + + Gets the friendly name used to refer to the provider during configuration. + + + + The friendly name used to refer to the provider during configuration. + + + + + + Gets a brief, friendly description suitable for display in administrative tools or other user interfaces (UIs). + + + + A brief, friendly description suitable for display in administrative tools or other UIs. + + + + + + Indicates whether the membership provider is configured to allow users to retrieve their passwords. + + + + true if the membership provider is configured to support password retrieval; otherwise, false. The default is false. + + + + + + Indicates whether the membership provider is configured to allow users to reset their passwords. + + + + true if the membership provider supports password reset; otherwise, false. The default is true. + + + + + + Gets a value indicating whether the membership provider is configured to require the user to answer a password question for password reset and retrieval. + + + + true if a password answer is required for password reset and retrieval; otherwise, false. The default is true. + + + + + + The name of the application using the custom membership provider. + + + + The name of the application using the custom membership provider. + + + + + + Gets the number of invalid password or password-answer attempts allowed before the membership user is locked out. + + + + The number of invalid password or password-answer attempts allowed before the membership user is locked out. + + + + + + Gets the number of minutes in which a maximum number of invalid password or password-answer attempts are allowed before the membership user is locked out. + + + + The number of minutes in which a maximum number of invalid password or password-answer attempts are allowed before the membership user is locked out. + + + + + + Gets a value indicating whether the membership provider is configured to require a unique e-mail address for each user name. + + + + true if the membership provider requires a unique e-mail address; otherwise, false. The default is true. + + + + + + Gets a value indicating the format for storing passwords in the membership data store. + + + + One of the values indicating the format for storing passwords in the data store. + + + + + + Gets the minimum length required for a password. + + + + The minimum length required for a password. + + + + + + Gets the minimum number of special characters that must be present in a valid password. + + + + The minimum number of special characters that must be present in a valid password. + + + + + + Gets the regular expression used to evaluate a password. + + + + A regular expression used to evaluate a password. + + + + + + Wrapper for class. + + +

+ Configuration for this provider requires providerId element set in web.config file, + as the Id of wrapped provider (defined in the Spring context). +

+ + Damjan Tomic + + + + Reference to wrapped provider (defined in Spring context). + + + + + Initializes the provider. + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + The providerId attribute may be used to override the name being used for looking up an object definition. + + The friendly name of the provider. + The or is null. + An attempt is made to call on a provider after the provider has already been initialized. + The has a length of zero or providerId attribute is not set. + + + + Returns the collection of settings property values for the specified application instance and settings property group. + + + + A containing the values for the specified settings property group. + + + A describing the current application use. + A containing the settings property group whose values are to be retrieved.2 + + + + Sets the values of the specified group of property settings. + + + A describing the current application usage. + A representing the group of property settings to set.2 + + + + When overridden in a derived class, deletes profile properties and information for the supplied list of profiles. + + + + The number of profiles deleted from the data source. + + + A of information about profiles that are to be deleted. + + + + When overridden in a derived class, deletes profile properties and information for profiles that match the supplied list of user names. + + + + The number of profiles deleted from the data source. + + + A string array of user names for profiles to be deleted. + + + + When overridden in a derived class, deletes all user-profile data for profiles in which the last activity date occurred before the specified date. + + + + The number of profiles deleted from the data source. + + + One of the values, specifying whether anonymous, authenticated, or both types of profiles are deleted. + A that identifies which user profiles are considered inactive. If the value of a user profile occurs on or before this date and time, the profile is considered inactive. + + + + When overridden in a derived class, returns the number of profiles in which the last activity date occurred on or before the specified date. + + + + The number of profiles in which the last activity date occurred on or before the specified date. + + + One of the values, specifying whether anonymous, authenticated, or both types of profiles are returned. + A that identifies which user profiles are considered inactive. If the of a user profile occurs on or before this date and time, the profile is considered inactive. + + + + When overridden in a derived class, retrieves user profile data for all profiles in the data source. + + + + A containing user-profile information for all profiles in the data source. + + + One of the values, specifying whether anonymous, authenticated, or both types of profiles are returned. + When this method returns, contains the total number of profiles. + The index of the page of results to return. + The size of the page of results to return. + + + + When overridden in a derived class, retrieves user-profile data from the data source for profiles in which the last activity date occurred on or before the specified date. + + + + A containing user-profile information about the inactive profiles. + + + One of the values, specifying whether anonymous, authenticated, or both types of profiles are returned. + A that identifies which user profiles are considered inactive. If the of a user profile occurs on or before this date and time, the profile is considered inactive. + When this method returns, contains the total number of profiles. + The index of the page of results to return. + The size of the page of results to return. + + + + When overridden in a derived class, retrieves profile information for profiles in which the user name matches the specified user names. + + + + A containing user-profile information for profiles where the user name matches the supplied usernameToMatch parameter. + + + One of the values, specifying whether anonymous, authenticated, or both types of profiles are returned. + When this method returns, contains the total number of profiles. + The index of the page of results to return. + The user name to search for. + The size of the page of results to return. + + + + When overridden in a derived class, retrieves profile information for profiles in which the last activity date occurred on or before the specified date and the user name matches the specified user name. + + + + A containing user profile information for inactive profiles where the user name matches the supplied usernameToMatch parameter. + + + One of the values, specifying whether anonymous, authenticated, or both types of profiles are returned. + A that identifies which user profiles are considered inactive. If the value of a user profile occurs on or before this date and time, the profile is considered inactive. + When this method returns, contains the total number of profiles. + The index of the page of results to return. + The user name to search for. + The size of the page of results to return. + + + + Gets the friendly name used to refer to the provider during configuration. + + + + The friendly name used to refer to the provider during configuration. + + + + + Gets a brief, friendly description suitable for display in administrative tools or other user interfaces (UIs). + + + + A brief, friendly description suitable for display in administrative tools or other UIs. + + + + + Gets or sets the name of the currently running application. + + + + A that contains the application's shortened name, which does not contain a full path or extension, for example, SimpleAppSettings. + + 2 + + + + Wrapper for class. + + +

+ Configuration for this provider requires providerId element set in web.config file, + as the Id of wrapped provider (defined in the Spring context). +

+ + Damjan Tomic + + + + Reference to wrapped provider (defined in Spring context). + + + + + Initializes the provider. + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + The providerId attribute may be used to override the name being used for looking up an object definition. + + The friendly name of the provider. + The or is null. + An attempt is made to call on a provider after the provider has already been initialized. + The has a length of zero or providerId attribute is not set. + + + + Gets a value indicating whether the specified user is in the specified role for the configured applicationName. + + + + true if the specified user is in the specified role for the configured applicationName; otherwise, false. + + + The user name to search for. + The role to search in. + + + + Gets a list of the roles that a specified user is in for the configured applicationName. + + + + A string array containing the names of all the roles that the specified user is in for the configured applicationName. + + + The user to return a list of roles for. + + + + Adds a new role to the data source for the configured applicationName. + + + The name of the role to create. + + + + Removes a role from the data source for the configured applicationName. + + + + true if the role was successfully deleted; otherwise, false. + + + If true, throw an exception if roleName has one or more members and do not delete roleName. + The name of the role to delete. + + + + Gets a value indicating whether the specified role name already exists in the role data source for the configured applicationName. + + + + true if the role name already exists in the data source for the configured applicationName; otherwise, false. + + + The name of the role to search for in the data source. + + + + Adds the specified user names to the specified roles for the configured applicationName. + + + A string array of the role names to add the specified user names to. + A string array of user names to be added to the specified roles. + + + + Removes the specified user names from the specified roles for the configured applicationName. + + + A string array of role names to remove the specified user names from. + A string array of user names to be removed from the specified roles. + + + + Gets a list of users in the specified role for the configured applicationName. + + + + A string array containing the names of all the users who are members of the specified role for the configured applicationName. + + + The name of the role to get the list of users for. + + + + Gets a list of all the roles for the configured applicationName. + + + + A string array containing the names of all the roles stored in the data source for the configured applicationName. + + + + + + Gets an array of user names in a role where the user name contains the specified user name to match. + + + + A string array containing the names of all the users where the user name matches usernameToMatch and the user is a member of the specified role. + + + The user name to search for. + The role to search in. + + + + Gets the friendly name used to refer to the provider during configuration. + + + + The friendly name used to refer to the provider during configuration. + + + + + Gets a brief, friendly description suitable for display in administrative tools or other user interfaces (UIs). + + + + A brief, friendly description suitable for display in administrative tools or other UIs. + + + + + Gets or sets the name of the application to store and retrieve role information for. + + + + The name of the application to store and retrieve role information for. + + + + + + Wrapper for class. + + +

+ Configuration for this provider requires providerId element set in web.config file, + as the Id of wrapped provider (defined in the Spring context). +

+ + Damjan Tomic + + + + Reference to wrapped provider (defined in Spring context). + + + + + Initializes the provider. + + + A collection of the name/value pairs representing the provider-specific + attributes specified in the configuration for this provider. + The providerId attribute may be used to override the name being used for looking up an object definition. + + The friendly name of the provider. + The or is null. + An attempt is made to call on a provider after the provider has already been initialized. + The has a length of zero or providerId attribute is not set. + + + + Retrieves a object that represents the currently requested page using the specified object. + + + + A that represents the currently requested page; otherwise, null, if no corresponding can be found in the or if the page context is null. + + + The used to match node information with the URL of the requested page. + + + + Retrieves a object based on a specified key. + + + + A that represents the page identified by key; otherwise, null, if no corresponding is found or if security trimming is enabled and the cannot be returned for the current user. The default is null. + + + A lookup key with which a is created. + + + + When overridden in a derived class, retrieves a object that represents the page at the specified URL. + + + + A that represents the page identified by rawURL; otherwise, null, if no corresponding is found or if security trimming is enabled and the cannot be returned for the current user. + + + A URL that identifies the page for which to retrieve a . + + + + When overridden in a derived class, retrieves the child nodes of a specific . + + + + A read-only that contains the immediate child nodes of the specified ; otherwise, null or an empty collection, if no child nodes exist. + + + The for which to retrieve all child nodes. + + + + Provides an optimized lookup method for site map providers when retrieving the node for the currently requested page and fetching the parent and ancestor site map nodes for the current page. + + + + A that represents the currently requested page; otherwise, null, if the is not found or cannot be returned for the current user. + + + The number of ancestor site map node generations to get. A value of -1 indicates that all ancestors might be retrieved and cached by the provider. + upLevel is less than -1. + + + + Provides an optimized lookup method for site map providers when retrieving the node for the currently requested page and fetching the site map nodes in the proximity of the current node. + + + + A that represents the currently requested page; otherwise, null, if the is not found or cannot be returned for the current user. + + + The number of ancestor generations to fetch. 0 indicates no ancestor nodes are retrieved and -1 indicates that all ancestors might be retrieved and cached by the provider. + The number of child generations to fetch. 0 indicates no descendant nodes are retrieved and a -1 indicates that all descendant nodes might be retrieved and cached by the provider. + upLevel or downLevel is less than -1. + + + + When overridden in a derived class, retrieves the parent node of a specific object. + + + + A that represents the parent of node; otherwise, null, if the has no parent or security trimming is enabled and the parent node is not accessible to the current user. + + + The for which to retrieve the parent node. + + + + Provides an optimized lookup method for site map providers when retrieving an ancestor node for the currently requested page and fetching the descendant nodes for the ancestor. + + + + A that represents an ancestor of the currently requested page; otherwise, null, if the current or ancestor is not found or cannot be returned for the current user. + + + The number of descendant node levels to retrieve from the target ancestor node. + The number of ancestor node levels to traverse when retrieving the requested ancestor node. + walkupLevels or relativeDepthFromWalkup is less than 0. + + + + Provides an optimized lookup method for site map providers when retrieving an ancestor node for the specified object and fetching its child nodes. + + + + A that represents an ancestor of node; otherwise, null, if the current or ancestor is not found or cannot be returned for the current user. + + + The number of descendant node levels to retrieve from the target ancestor node. + The that acts as a reference point for walkupLevels and relativeDepthFromWalkup. + The number of ancestor node levels to traverse when retrieving the requested ancestor node. + The value specified for walkupLevels or relativeDepthFromWalkup is less than 0. + node is null. + + + + This method is marked as protected and should never be called. + + + + A that represents the root node of the set of nodes that the current provider manages. + + + + + + Provides a method that site map providers can override to perform an optimized retrieval of one or more levels of parent and ancestor nodes, relative to the specified object. + + + The number of ancestor generations to fetch. 0 indicates no ancestor nodes are retrieved and -1 indicates that all ancestors might be retrieved and cached. + The that acts as a reference point for upLevel. + upLevel is less than -1. + node is null. + + + + Provides a method that site map providers can override to perform an optimized retrieval of nodes found in the proximity of the specified node. + + + The number of ancestor generations to fetch. 0 indicates no ancestor nodes are retrieved and -1 indicates that all ancestors (and their descendant nodes to the level of node) might be retrieved and cached. + The number of descendant generations to fetch. 0 indicates no descendant nodes are retrieved and -1 indicates that all descendant nodes might be retrieved and cached. + The that acts as a reference point for upLevel. + upLevel or downLevel is less than -1. + node is null. + + + + Retrieves a Boolean value indicating whether the specified object can be viewed by the user in the specified context. + + + + true if security trimming is enabled and node can be viewed by the user or security trimming is not enabled; otherwise, false. + + + The that contains user information. + The that is requested by the user. + context is null.- or -node is null. + + + + Gets the friendly name used to refer to the provider during configuration. + + + + The friendly name used to refer to the provider during configuration. + + + + + + Gets a brief, friendly description suitable for display in administrative tools or other user interfaces (UIs). + + + + A brief, friendly description suitable for display in administrative tools or other UIs. + + + + + + Gets the object that represents the currently requested page. + + + + A that represents the currently requested page; otherwise, null, if the is not found or cannot be returned for the current user. + + + + + + Gets or sets the parent object of the current provider. + + + + The parent provider of the current . + + + + + + Gets the root object in the current provider hierarchy. + + + + An that is the top-level site map provider in the provider hierarchy that the current provider belongs to. + + + There is a circular reference to the current site map provider. + + + + Gets the root object of the site map data that the current provider represents. + + + + The root of the current site map data provider. The default implementation performs security trimming on the returned node. + + + + + + Exports an object as a web service. + + +

+ The exporter will create a web service wrapper for the object that is + to be exposed and additionally enable its configuration as a web + service. +

+

+ The exported object can be either a standard .NET web service + implementation, with methods marked using the standard + , or it can be a + plain .NET object. +

+ + Aleksandar Seovic + + + + Holds EXPORTER_ID to WebServiceExporter instance mappings. + + + + + Returns the target object instance exported by the WebServiceExporter identified by . + + + + + + + The name of the object in the factory. + + + + + The owning factory. + + + + + The generated web service wrapper type. + + + + + Creates a new instance of the class. + + + + + Cleanup before GC + + + + + Disconnect the remote object from the registered remoting channels. + + + + + Stops exporting the object identified by . + + true to release both managed and unmanaged resources; false to release only unmanaged resources. + + + + Exports specified object as a web service. + + + In the event of misconfiguration (such as failure to set an essential + property) or if initialization fails. + + + + + Returns the Web Service wrapper type for the object that is to be exposed. + + + + + + Validates the configuration. + + + + + Generates the web service wrapper type. + + + + + Gets or Sets the Web Services Interoperability (WSI) specification + to which the Web Service claims to conform. + + + Default is + + + + + Gets or sets the base type that web service should inherit. + + + Default is + + + + + Gets or sets the name of the target object that should be exposed as a web service. + + + The name of the target object that should be exposed as a web service. + + + + + Gets or sets the description of the web service (optional). + + + The web service description. + + + + + Gets or sets the name of the web service (optional). + + +

+ Defaults to the value of the exporter's object ID. +

+ + + The web service name. + + + + + Gets or sets the web service namespace. + + + The web service namespace. + + + + + Gets or sets the list of interfaces whose methods should be exposed as web services. + + + If not set, all the interfaces implemented or inherited + by the target type will be used. + + The interfaces. + + + + Gets or sets a list of custom attributes + that should be applied to a proxy class. + + + + + Gets or sets a dictionary of custom attributes + that should be applied to web service members. + + + Dictionary key is an expression that members can be matched against. + Value is a list of attributes that should be applied + to each member that matches expression. + + + + + Callback that supplies the owning factory to an object instance. + + + Owning + (may not be ). The object can immediately + call methods on the factory. + + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + In case of initialization errors. + + + + + Set the name of the object in the object factory that created this object. + + + The name of the object in the factory. + + +

+ Invoked after population of normal object properties but before an init + callback like 's + + method or a custom init-method. +

+ + + + + Implements constructors for the proxy class. + + + This implementation generates an empty noop default constructor + + + The builder to use. + + + + + An implementation that + retrieves configured WebService objects from the Spring.NET web + application context. + + + This handler factory uses web service name from the URL, without the extension, + to find web service object in the Spring context. + + Aleksandar Seovic + + + + Retrieves instance of the page from Spring web application context. + + current HttpContext + type of HTTP request (GET, POST, etc.) + requested page URL + translated server path for the page + instance of the configured page object + + + + Provides base functionality for Spring.NET context-aware + implementations. + + +

+ Provides derived classes with a default implementation of + method. +

+ + Aleksandar Seovic + + + + Holds all handlers having == true. + + + + + Holds an instance of the instrinsic System.Web.UI.SimpleHandlerFactory + + + + + Holds the shared logger for all factories. + + + + + Creates a new instance of the + class. + + + + + Returns an appropriate implementation. + + + An instance of the class that + provides references to intrinsic server objects. + + + The HTTP method of the request. + + The request URL. + + The physical path of the requested resource. + + + A new object that processes + the request. + + + + + Enables a factory to release an existing + instance. + + + The object to release. + + + + + Create a handler instance for the given URL. + + the application context corresponding to the current request + The instance for this request. + The HTTP data transfer method (GET, POST, ...) + The requested . + The physical path of the requested resource. + A handler instance for processing the current request. + + + + Get the application context instance corresponding to the given absolute url and checks + it for contract and being not null. + + the absolute url + + if no context is found + + + if context is not an + + teh application context instance corresponding to the given absolute url. + + Calls to obtain a context instance. + + + + + Returns the unchecked, raw application context for the given virtual path. + + the virtual path to get the context for. + the context or null. + + Subclasses may override this method to change the context source. + By default, is used for obtaining context instances. + + + + + DO NOT USE - this is subject to change! + + + + + This method requires registrars to follow the convention of registering web object definitions using their + application relative urls (~/mypath/mypage.aspx). + + + Resolve an object definition by url. + + + + + Apply dependency injection stuff on the handler. + + the handler to be intercepted + the context responsible for configuring this handler + + + + Get the global instance of System.Web.UI.SimpleHandlerFactory + + + This factory is a plaform version agnostic way to instantiate + arbitrary handlers without the need for additional reflection. + + + + + Holds a named + + Erich Eichinger + + + + Creates a new name/objectdefinition pair. + + + + + Get the name of the attached object definition + + + + + Get the . + + + + + implementation that allows users to monitor state + of the Spring.NET web application context. + + +

+ +

+ + Aleksandar Seovic + + + + Initializes a new instance of the class. + + + + + Processes HTTP request. + + An object that provides references to the intrinsic server objects (for example, , , , and ) used to service HTTP requests. + + + + Gets a value indicating whether another request can use + this instance. + + True if this handler is reusable, False otherwise. + + + + Helper class for easier access to reflected Control members. + + Erich Eichinger + + + + Instantiates a new Accessor. + + + + + + Returns the underlying ControlCollection instance. + + + + + Gets or sets the ControlCollection of the target without accessing the target's property. + + + If the underlying collection is null, it is automatically created. + + + + + Helper class for easier access to reflected ControlCollection members. + + Erich Eichinger + + + + Returns the underlying ControlCollection instance. + + + + + Returns the type of the underlying ControlCollection instance. + + + + + Creates a new Accessor for a given . + + The to be accessed + + + + Gets or sets the owner of the underlying ControlCollection. + + + + + Support Class providing a method to ensure a control has been intercepted + + Erich Eichinger + + + + Holds all available interception strategies + + + + + The last resort interception strategy... + + + + + Holds a control.GetType()->IInterceptionStrategy table. + + + + + Holds well-known Type/Strategy mappings. + + + + + Ensures, a control has been intercepted to support Web-DI. If not, the control will be intercepted. + + + + + Any concrete interception strategy must implement this interface + + Erich Eichinger + + + + Any implementation must never throw an exception from this method. + Instead false must be returned to indicate interception failure. + + + true, if interception succeeded. false otherwise. + + + + + SimpleHandlerFactory is used to wrap any arbitrary to make it "Spring-aware". + + + By default, an instance of is used as underlying factory. + + Erich Eichinger + + + + Creates a new instance, using a as underlying factory. + + + + + Create a new instance, using an instance of as underlying factory. + + a type that implements + + + + Create a new instance, using as underlying factory. + + the factory to be wrapped. + + + + Create a handler instance for the given URL. + + the application context corresponding to the current request + The instance for this request. + The HTTP data transfer method (GET, POST, ...) + The requested . + The physical path of the requested resource. + A handler instance for processing the current request. + + + + Enables a factory to release an existing + instance. + + + The object to release. + + + + + This result factory implementation creates instances from a given string representation. + + + For a larger example illustrating the customization of result processing, . + + + + + + Erich Eichinger + + + + A result factory is responsible for create an instance from a given string representation. + + + For a larger example illustrating the customization of result processing, . + + + + + + Erich Eichinger + + + + Create an instance from the given string representation. + + the resultMode that caused triggering this factory. + the remainder string to be interpreted and converted into an . + An instance. Must never be null! + + Note to implementors: This method must never return null. Instead exceptions should be thrown. + + + + + Create a new from the specified . + + the result mode. + the string representation of the result. + the instance created from . + + + + The default implementation of the interface. + + + + + Defines the interface, all hierarchical navigators capable of + dealing with instances must implement. + + + + + An extension of that must be implemented by + navigators that can be part of a hierarchy. + + Erich Eichinger + + + + Any component capable of navigating and participating in the navigation logic must implement this interface. + + + + + + Erich Eichinger + + + + Determines, whether this navigator or one of its parents can + navigate to the destination specified in . + + the name of the navigation destination + true, if this navigator can navigate to the destination. + + + + Instruct the navigator to navigate to the specified navigation destination. + + the destination to navigate to. + the sender that issued the navigation request. + the context to evaluate this navigation request in. + if this navigator cannot navigate to the specified (). + + + + Creates an uri poiniting to the specified navigation destination. + + the destination to navigate to. + the sender that issued the navigation request. + the context to evaluate this navigation request in. + if this navigator cannot navigate to the specified (). + + + + If any, get the parent navigator of the current navigator instance. May be null. + + + + + Contains the mappings of navigation destination names to + instances or their corresponding textual representations.
+ See for more information on how textual representations are resolved. + + + + + + + + + + Creates and initializes a new instance. + + + + + Creates and initializes a new instance. + + the parent of this instance. May be null. + a dictionary of result name to result mappings. May be null. + sets, how this navigator treats case sensitivity of result names + + + + Create the dictionary instance to be used by this navigator component. + + a dictionary of intitial result mappings + the dictionary, that will be used by this navigator. + + Implementors may override this for creating custom dictionaries. + + + + + Determines, whether this navigator or one of its parents can + navigate to the destination specified in . + + the name of the navigation destination + true, if this navigator can navigate to the destination. + + + + Redirects user to a URL mapped to specified result name. + + Name of the result. + the instance that issued this request + The context to use for evaluating the SpEL expression in the Result. + + + + Returns a redirect url string that points to the + defined by this + result evaluated using this Page for expression + + Name of the result. + the instance that issued this request + The context to use for evaluating the SpEL expression in the Result + A redirect url string. + + + + Obtain the named result instance from the dictionary. If necessary, the actual representation of the result + will be converted to an instance by this method. + + + + + + + Handle an unknown result object. + + the name of the result + the result instance obtained from the dictionary + + By default, this method throws a . + + + + + Handle an unknown destination. + + the destination that could not be resolved. + the sender that issued the request + the context to be used for evaluating any dynamic parts of the destination + the uri as being returned from + + By default, this method throws a . + + + + + Indicates, whether result names are treated case sensitive by this navigator. + + + + + Get/Set the parent of this navigator. + + if this navigator already has a parent. + + + + Gets or sets map of result names to instances or their textual representations. + See for information on parsing textual representations. + + + + + + + + + Holds a list of url expressions and their corresponding names of responsible + or objects managed by the container. + + Erich Eichinger + + + + Maps the specified url pattern expression to an object name denoting a or object. + + the string pattern (see conform to syntax) + an object name denoting the spring-managed handler definition + + + + Maps the specified url pattern expression to an object name denoting a or object. + + the url pattern + an object name denoting the spring-managed handler definition + + + + Maps the to a handler object name by matching against all registered patterns. + + the virtual path + the object name + + + + Add a new mapping + + an url pattern string + a handler object name string + + + + Clear the mapping table. + + + + + Copies all entries to the specified array. + + + + + Get an enumerator for iterating over the list of registered mappings. + + + + + Not supported by this implementation. + + + + + Not supported by this implementation. + + + + + Not supported by this implementation. + + + + + Add or replace a mapping + + + Getter will throw a ! + + an url pattern string + + + + Always returns false. + + + + + Gets a value indicating whether the object has a fixed size. + + + + true if the object has a fixed size; otherwise, false. + + 2 + + + + Get the number of registered mappings. + + + + + Gets an object that can be used to synchronize access. + + + + + Always returns false. + + + + + Not supported by this implementation. + + + + + Not supported by this implementation. + + + + + Holds pairs of (url pattern, handler object name). + + + + + Erich Eichinger + + + + Create a new instance. + + + + + + + Create a new instance + + + + + + + Return a string representation of this entry. + + + + + Get the url pattern + + + + + Get the handler object name + + + + + This strategy replaces the original collection's owner with an intercepting proxy + + Erich Eichinger + + + + This strategy enhances a ControlCollection's type by + dynamically implementing ISupportsWebDependencyInjection on this type + + Erich Eichinger + + + + The list of methods to be intercepted for a ControlCollection + + + + + Holds a table of already known intercepted ControlCollection types + + + + + Intercepts the given by dynamically deriving + the original type and let it implement . + + the ApplicationContext to be set on the collection instance. + a wrapper around the owner control instance. + a wrapper around the collection instance. + true, if interception was successful. false otherwise + + + + Holds a reference to the static(!) callback-method to be used during generation of intercepted ControlCollection-Types + + + + + An encapsulates concrete navigation logic. Usually executing a + result will invoke or . + + + For a larger example illustrating the customization of result processing . + + + + + + + + Erich Eichinger + + + + Execute the result logic within the given . + + the context to evaluate this request in. + + + + Returns an url representation of the result logic within the given . + + the context to evaluate this request in. + the url corresponding to the result instance. + + The returned url is not necessarily fully qualified nor absolute. Returned urls may be relative to the + given context.
+ To produce a client-usable url, consider applying e.g. or + before writing the result url to the response. + + + + + "Contract"-interface of the Web-DI infrastructure. + + + This interface supports Spring's DI infrastructure and normally doesn't need to be implemented
+
+ Any Page, Control or ControlCollection implementing this interface guarantees to + call on any control being added + before it is actually added to the child-collection. + + +

The following example shows, how to make a Control support the DI-infrastructure:

+ + class MyControl : Control, ISupportsWebDependencyInjection + { + private IApplicationContext _defaultApplicationContext; + + public IApplicationContext DefaultApplicationContext + { + get { return _defaultApplicationContext; } + set { _defaultApplicationContext = value; } + } + + override protected AddedControl( Control control, int index ) + { + WebUtils.InjectDependenciesRecursive( _defaultApplicationContext, control ); + base.AddedControl( control, index ); + } + } + + + +

The following example shows, how to make a ControlCollection support the DI-infrastructure:

+

Note, that you MUST implement the single-argument constructor ControlCollection( Control owner )!

+ + class MyControlCollection : ControlCollection, ISupportsWebDependencyInjection + { + private IApplicationContext _defaultApplicationContext; + + public MyControlCollection( Control owner ) : base( owner ) + {} + + public IApplicationContext DefaultApplicationContext + { + get { return _defaultApplicationContext; } + set { _defaultApplicationContext = value; } + } + + override public Add( Control child ) + { + WebUtils.InjectDependenciesRecursive( _defaultApplicationContext, child ); + base.Add( child ); + } + + override public AddAt( int index, Control child ) + { + WebUtils.InjectDependenciesRecursive( _defaultApplicationContext, child ); + base.AddAt( index, child ); + } + } + + + Erich Eichinger + + + + Holds the default instance to be used during injecting a control-tree. + + + + + Any component participating in the navigation infrastructure must implement this interface. + + Erich Eichinger + + + + Return the associated with this component. + + + + + This ResourceManager implementation swallows s and + simply returns null from if no resource is found. + + Erich Eichinger + + + + Avoid beforeFieldInit + + + + + Returns the value of the specified resource. + + + The value of the resource localized for the caller's current culture settings. If a match is not possible, null is returned. The resource value can be null. + + The name of the resource to get. + The name parameter is null. + + + + Gets the value of the resource localized for the specified culture. + + + The value of the resource, localized for the specified culture. If a "best match" is not possible, null is returned. + + The object that represents the culture for which the resource is localized. Note that if the resource is not localized for this culture, the lookup will fall back using the culture's property, stopping after checking in the neutral culture.If this value is null, the is obtained using the culture's property. + The name of the resource to get. + The name parameter is null. + + + + Returns the value of the specified resource. + + + The value of the resource localized for the caller's current culture settings. If a match is not possible, null is returned. The resource value can be null. + + The name of the resource to get. + The name parameter is null. + + + + Gets the value of the resource localized for the specified culture. + + + The value of the resource, localized for the specified culture. If a "best match" is not possible, null is returned. + + The object that represents the culture for which the resource is localized. Note that if the resource is not localized for this culture, the lookup will fall back using the culture's property, stopping after checking in the neutral culture.If this value is null, the is obtained using the culture's property. + The name of the resource to get. + The name parameter is null. + + + + MappingHandleryFactory allows for full Spring-managed <httpHandlers> configuration. + It uses regular expressions for url matching. + + + + The example below shows, how to map all url requests to spring and let + resolve urls to container-managed or objects. + + // web.config + + <httpHandlers> + <!-- map all requests to spring (just for demo - don't do this at home!) --> + <add verb="*" path="*.*" type="Spring.Web.Support.MappingHandlerFactory, Spring.Web" /> + </httpHandlers> + + // spring-objects.config + + <object type="Spring.Web.Support.MappingHandlerFactoryConfigurer, Spring.Web"> + <property name="HandlerMap"> + <dictionary> + <entry key="\.ashx$" value="standardHandlerFactory" /> + <!-- map any request ending with *.whatever to standardHandlerFactory --> + <entry key="\.whatever$" value="specialHandlerFactory" /> + </dictionary> + </property> + </object> + + <object name="standardHandlerFactory" type="Spring.Web.Support.DefaultHandlerFactory, Spring.Web" /> + + <object name="specialHandlerFactory" type="MySpecialHandlerFactoryImpl" /> + + + + + + + + Erich Eichinger + + + + Holds the cache of handler/factory pairs handed out by this factory. This is required + for proper handling of . + + + + + Create a handler instance for the given URL. Will try to find a match of onto patterns in . + If a match is found, delegates the call to the matching method. + + the application context corresponding to the current request + The instance for this request. + The HTTP data transfer method (GET, POST, ...) + The requested . + The physical path of the requested resource. + A handler instance for processing the current request. + + + + Obtains a handler by mapping to the list of patterns in . + + the application context corresponding to the current request + The instance for this request. + The HTTP data transfer method (GET, POST, ...) + The requested . + The physical path of the requested resource. + + + A handler instance for processing the current request. + + + + Enables a factory to release an existing + instance. + + + The object to release. + + + + + Removes the handler from the handler/factory dictionary and releases the handler. + + the handler to be released + a dictionary containing (, ) entries. + + + + Holds the global list of mappings from url patterns to handler names. + + + + + Configures . + + Erich Eichinger + + + + Contains mappings of url patterns to handler objects. + + + + + Represents a MIME media type as defined by http://www.iana.org/assignments/media-types/ + + Erich Eichinger + + + + Parses a string into a instance. + + a valid string representation of a mediaType + a new instance + + + + Creates a new media type instance representing a generic "application/octet-stream" + + + + + Creates a new media type instance representing a generic content type + with an unspecified subtype (e.g. "text/*") + + + + + Creates a new media type instance representing a particular media type + + + + + Returns a string representation of this instance. + + + + + Compares this instance to another + + another instance + + + + Determines whether the specified is equal to the current . + + + true if the specified is equal to the current ; otherwise, false. + + The to compare with the current . + + + + Serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. + + + A hash code for the current . + + + + + Gets the content type of this media type instance + + + + + Gets the subtype of this media type instance + + + + + Predefines common application media types + + + + + Represents "application/octet-stream" + + + + + Represents "application/pdf" + + + + + Represents "application/rtf" + + + + + Represents "application/soap+xml" + + + + + Represents "application/zip" + + + + + Predefines common image media types + + + + + Represents "image/gif" + + + + + Represents "image/jpeg" + + + + + Represents "image/tiff" + + + + + Predefines common text media types + + + + + Represents "text/html" + + + + + Represents "text/plain" + + + + + Represents "text/richtext" + + + + + Represents "text/xml" + + + + + Represents "text/javascript" + + + + + Represents "text/css" + + + + + Implementation of that retrieves + configured instances from Spring web application context. + + + + This handler factory uses the page name from the URL, without the extension, + to find the handler object in the Spring context. This means that the target object + definition doesn't need to resolve to an .aspx page -- it can be any valid + object that implements interface. + + + If the specified page is not found in the Spring application context, this + handler factory falls back to the standard ASP.NET behavior and tries + to find physical page with a given name. + + + In either case, handlers that implement + and will be provided with the references + to appropriate Spring.NET application context (based on the request URL) + and a that should be used to store the information + that needs to be shared by all instances of the handler. + + + Aleksandar Seovic + + + + Retrieves instance of the configured page from Spring web application context, + or if page is not defined in Spring config file tries to find it using standard + ASP.Net mechanism. + + Current HttpContext + Type of HTTP request (GET, POST, etc.) + Requested page URL + Translated server path for the page + Instance of the IHttpHandler object that should be used to process request. + + + + Create a handler instance for the given URL. + + the application context corresponding to the current request + The instance for this request. + The HTTP data transfer method (GET, POST, ...) + The requested . + The physical path of the requested resource. + A handler instance for the current request. + + + + Represents the ASPX result page that an operation maps to. + + +

+ Parameters can reference variables accessible from the page using the + standard NAnt style property notation, namely ${varName}. +

+

+ The result that is passed as the sole + parameter to the parameterized constructor + () must adhere to the + following format: +

+ + [<mode>:]<targetPage>[?param1,param2,...,paramN] + +

+ Only the targetPage is mandatory. +

+ + +

+ Examples of valid values that can be passed + to the the parameterized constructor + () include: +

+

+ + Login.aspx + ~/Login.aspx + redirect:~/Login.aspx + transfer:~/Login.aspx + transfer:Services/Register.aspx + Login.aspx?username=springboy,password=7623AAjoe + redirect:Login.aspx?username=springboy,password=7623AAjoe + +

+ + Aleksandar Seovic + Matan Shapira + + + + The default . + + +

+ Currently defaults to . +

+ + + + + + Creates a new instance of the class. + + + + + Creates a new instance of the class. + + +

+ See both the class documentation () + and the reference documentation for the Spring.Web library for a + discussion and examples of what values the supplied + can have. +

+ + The result descriptor. + + If the supplied is or + contains only whitespace character(s). + + if the result mode is unknown. + + + + Creates a new instance of the class. + + +

+ See both the class documentation () + and the reference documentation for the Spring.Web library for a + discussion and examples of what values the supplied + can have. +

+ + The desired result mode. May be null to use default mode. + The result descriptor (without resultMode prefix!). + + If the supplied is or + contains only whitespace character(s). + + if the result mode is unknown. + + + + Navigates to the + defined by this result. + + + The context object for parameter resolution. This is typically + a . + + + + + Performs a server-side transfer to the + defined by this result. + + + The context object for parameter resolution. This is typically + a . + + + + + + Resolves transfer parameters and stores them into instance. + + + + + + + Performs a redirect to the + defined by this + result. + + + The context object for parameter resolution. This is typically + a . + + + + + + Returns a redirect url string that points to the + defined by this + result. + + + A redirect url string. + + + + + Construct the actual url to be executed or returned. + + the already evaluated + the already evaluated parameters. + the url to be returned by + + + + Append the url parameter to the url being constructed. + + the containing the url constructed so far. + the parameter key + the parameter value + the to use for further url construction. + + + + Evaluates within and returns the evaluation result. + + the context to be used for evaluation. + the string that might need evaluation + the evaluation result. Unodified if no evalution occured. + + + + Checks, if value is a SpEL expression ${expression} or %{expression}. + + + + + If is a SpEL expression (${expression} or %{expression}), evaluates + the value against . + + + + + Extracts and sets this instance's + property from the supplied descriptor. + + +

+ The supplied descriptor is typically + something like /Foo.aspx or + redirect:http://www.springframework.net/. +

+ + + The result descriptor. + + + The supplied without the result mode + prefix (if any). + + + If the supplied starts with an illegal + result mode (see ). + + + + + Set the actual from the parsed string. + + the parsed result mode + + + + Resolves dynamic expression contained in if any by calling . + + the context to be used for evaluating the expression + the evaluated expression + + + + Parses query parameters from the supplied . + + + The query string (may be ). + + + + + The . Defines which + method will be used to navigate to the + . + + + + + The target page. + + +

+ This is the (relative) path to the target page. +

+ + +

+ Examples of valid values would be: +

+

+ + Login.aspx + ~/Login.aspx + ~/B2B/SignUp.aspx + B2B/Foo/FooServices.aspx + +

+ + + + + The parameters thar are to be passed to the + upon + navigation. + + + + + Indicates, if should be called with preserveForm='true' | 'false'. Only relevant for ResultMode.TransferXXXX modes. + + + + + Indicates, if should be called with endResponse='true' | 'false'. Only relevant for ResultMode.RedirectXXXX modes. + + + + + A result factory is responsible for create an instance from a given string representation. + + + + Factories get registered with the for a certain resultMode string. + uses for converting strings into instances + implementing the corresponding navigation logic. + + + Result string representations are always of the form:
+ "<resultmode>:<textual result representation>"
+ Calling on the registry will cause the registry to first extract the leading resultmode to obtain + the corresponding instance and handle the actual instantiation by delegating to + . + + + The following example illustrates the usual flow: + + class MySpecialResultLogic : IResult + { + ... + } + + class MySpecialResultLogicFactory : IResultFactory + { + IResult Create( string mode, string expression ) { /* ... convert 'expression' into + MySpecialResultLogic */ } + } + + // register with global factory + ResultFactoryRegistry.RegisterResultFactory( "mySpecialMode", new MySpecialResultLogicFactory ); + + // configure your Results + <object type="mypage.aspx"> + <property name="Results"> + <dictionary> + <entry key="continue" value="mySpecialMode:<some MySpecialResultLogic string representation>" /> + </dictionary> + </property> + + // on your page call + myPage.SetResult("continue"); + + + + + + + + + + Erich Eichinger + + + + Resets the factory registry to its defaults. Mainly used for unit testing. + + + + + Set a new default factory + + the new default factory instance. Must not be null. + the previous default factory. + + + + Registers a for the specified . + + the resultMode. Must not be null. + the factory respponsible for handling results. Must not be null. + the factory previously registered for the specified , if any. + + See overview for more information. + + + + + Creates a result from the specified by extracting the result mode from + the text and delegating to a corresponding , if any. + + the 'resultmode'-prefixed textual representation of the result instance to create. + + the instance corresponding to the textual represenation, + created by the + + + if either is null or returned null. + + This method guarantees that the return value will always be non-null.
+ must always be of the form "<resultmode>:<textual result representation>". + The resultmode will be extracted and the corresponding (previously registered + using ) is called to actually create the instance. If no factory matches + resultmode, the call is handled to the . + + + + + Returns the current set by . Will never be null. + + + The default factory is responsible for handling any unknown result modes. + + + + + The various result modes. + + Aleksandar Seovic + + + + + A server-side transfer. + + +

+ Issues a server-side transfer using the + method. +

+ + + + + + A redirect. + + +

+ Issues a redirect (to the user-agent - typically a browser) using + the method. +

+ + + + + + A server-side transfer. + + +

+ Issues a server-side transfer using the + method with parameter 'preserveForm=false'. +

+ + + + + + A redirect. + + +

+ Issues a redirect (to the user-agent - typically a browser) using + the method. +

+ + + + + + Base class that describes client side script block or file. + + +

+ Classes that extend this class are used by Spring.Web client-side + scripting support. +

+ + Aleksandar Seovic + + + + Initialize a new Script object of the specified language + + Script language. + + + + Initialize a new script object of the specified type + + a + + + + Gets or sets script language. + + + + + Gets or sets script mime type + + + + + Class that describes client side script block. + + +

+ Script blocks are used to insert script code directly into the page, + without references to an external file. +

+ + Aleksandar Seovic + + + + Default constructor. + + Script language. + The script text. + + + + Initialize a new script block instance. + + the script language's + the script body + + + + Gets or sets the script text. + + The script text. + + + + Class that describes client side script file. + + +

+ Script file references script code in the external file. +

+ + Aleksandar Seovic + + + + Initialize a new instance. + + Script language. + The name of the script file. + + + + Initialize a new instance. + + the script language's + the (virtual) path to the script + + + + Gets or sets the name of the script file. + + The name of the script file. + + + + Class that describes client side script file. + + +

+ Script file references script code in the external file. +

+ + Aleksandar Seovic + + + + Initialize a new instance. + + Script language. + Element ID of the event source. + Name of the event to handle. + Script text. + + + + Initialize a new instance. + + the script language's + Element ID of the event source. + Name of the event to handle. + Script text. + + + + Gets or sets the element ID. + + The element ID. + + + + Gets or sets the name of the event. + + The name of the event. + + + + Resource cache implementation that uses Spring.NET page/handler state to cache resources. + + Aleksandar Seovic + + + + Creates a new cache instance and attaches it to the given + + the holder of the shared state dictionary to be used for caching. + + + + Gets the list of resources from cache. + + Cache key to use for lookup. + A list of cached resources for the specified target object and culture. + + + + Puts the list of resources in the cache. + + Cache key to use for the specified resources. + A list of resources to cache. + + + + This MethodBuilder emits a Callback-call before calling the base method + + Erich Eichinger + + + + Initializes a new instance of a SupportsWebDependencyInjectionMethodBuilder + + + + + Inserts a call to a callback-method before actually calling the base-method. + + The IL generator to use + The method to proxy + The interface definition of this method, if applicable + + + + Emits the callback invocation. + + + + + Wraps a ControlCollection.Owner control to make it DI aware + + Erich Eichinger + + + + Wraps a control to make it DI aware + + + + + + + Performs DI before adding the control to it's parent + + + + + + + Delegates call to decorated control + + + + + + Wraps a ControlCollection.Owner control implementing INamingContainer to make it DI aware + + Erich Eichinger + + + + This TypeBuilder dynamically implements the contract on a given type. + + Erich Eichinger + + + + Creates a new TypeBuilder instance. + + The base type the proxy shall be derived from + The methods to be injected with a call to staticCallbackMethod + The static callback method to be injected into methodsToIntercept + + + + Creates a proxy that inherits the proxied object's class. + + + The generated proxy type. + + + + Actually implements the interface. + + + + + Declares field that holds the . + + + + + Determines if the specified + is one of those generated by this builder. + + The type to check. + + if the type is a SpringAwareControl-based proxy; + otherwise . + + + + + Utilities for dependency injection in the web tier. + + + + + Injects dependencies into all controls in the hierarchy + based on template definitions in the Spring config file. + + ApplicationContext to be used + Control to inject dependencies into. + + + + Aquires an ApplicationContext according to a Control's TemplateSourceDirectory + + if availabe, the control's IApplicationContext instance - defaultContext otherwise + + + + An implementation of specific for s. + The navigator hierarchy equals the control hierarchy when using a . + + + + This implementation supports 2 different navigator hierarchies: +
    +
  • The default hierarchy defined by
    • +
  • The hierarchy defined by a web form's hierarchy.
    • +
+ + + This implementation always checks the standard hierarchy first and - if a destination cannot be resolved, falls back + to the control hierarchy for resolving a specified navigation destination. + + + + + + Finds the next up the control hierarchy, + starting at the specified . + + + This method checks both, for controls implementing or . In addition + when MasterPages are used, it interprets the control hierarchy as control->page->masterpage. (). + + the control to start the search with. + include checking the control itself or start search with its parent. + requires s to hold a valid instance. + If found, the next or . + null otherwise + + + + Creates a new instance of a for the specified control. + + the control to be associated with this navigator. + the direct parent of this navigator + a dictionary containing results + specifies how to handle case for destination names. + + + + Determines, whether this navigator or one of its parents can + navigate to the destination specified in . + + the name of the navigation destination + true, if this navigator can navigate to the destination. + + + + Check, whether this navigator can navigate to the specified . + + the destination name to check. + + whether the check shall include the control hierarchy or + the standard hierarchy only. + + + + + Returns a redirect url string that points to the + defined by this + result evaluated using this Page for expression + + Name of the result. + the instance that issued this request + The context to use for evaluating the SpEL expression in the Result + A redirect url string. + + + + Redirects user to a URL mapped to specified result name. + + Name of the result. + the instance that issued this request + The context to use for evaluating the SpEL expression in the Result. + + + + The that this is associated with. + + + + + Return the next available within + this control's parent hierarchy. + + + + + Holds the result match from . + + + + + The matching control + + + + + The instance associated with the control. May be null. + + + + + Initializes the new match instance. + + the matching control. Must not be null! + + + + Adapts a concrete instance as a . + + Erich Eichinger + + + + Create a new adapter instance, wrapping the specified + into a interface. + + the instance to be adapted. May be null. + + + + Returns the wrapped that was passed into . + + + + + Provides functions required for implementing validators + but are unfortunately not accessible from + + Erich Eichinger + + + + Registers a javascript-block to be rendered. + + + + + Checks, if a certain javascript-block is already registered. + + + + + Adds an attribute to be rendered for clientside validation. + + + + + Is "XHTML 1.0 Transitional" rendering allowed? + + + + + Provides common functionality to all validation renderer controls. + + Erich Eichinger + + + + Create the default + for this ValidationControl if none is configured. + + + + + Gets the MessageSource to be used for resolve error messages + + + By default, returns 's MessageSource. + + the to resolve message texts. May be null + + + + Gets the list of validation errors to render + + the to render. May be null + + + + Gets the , who's + shall be rendered by this control. + + + First, it tries to resolve the specified , if any. If no explicit name + is set, will probe the control hierarchy for controls implementing . + + + + + Resolves the list of validation errors either explicitely specified using + or obtained from the containing + resolved by to a list + of elements containing the error messages to be rendered. + + + + The list of validation errors may either be explicitely specified using + or will automatically be obtained from the containing resolved by + . + + + Error Messages are resolved using either an explicitely specified or the + obtained from the validation container. + + + a list containing elements. May return null + + + + Renders error messages using the specified . + + + + + + Set a particular message source to be used for + resolving error messages to display texts. + + + If not set, the control will probe the control hierarchy + for containing controls implementing + and use the container's . + + + + + Allows to set a particular instance of the validation errors + collection to render. + + + If not set, the control will probe the control hierarchy for + containing controls implementing + and use the container's + + + + + If set, will resolve to the named control specified + by this property. The behavior of name resolution is identical to + , except that if the name + starts with "::", the resolution will start at the page level instead of relative to this + control + + + + + Gets or sets the provider. + + The provider. + + + + Gets or sets the validation errors renderer to use. + + + If not explicitly specified, defaults to . + + The validation errors renderer to use. + + + + Displays a pop-up DHTML calendar. + + +

+ Credit: this control uses a slightly modified version of the + Dynarch.com DHTML Calendar, + written by Mihai Bazon. +

+ + Aleksandar Seovic + + + + Registers necessary scripts and stylesheet. + + + An object that contains the event data. + + + + + Renders a hidden input field that stores the value for the radio button group. + + + to use for rendering. + + + + + Raises the SelectionChanged event. + + + + + Loads postback data into the control. + + + The key that should be used to retrieve data. + + The postback data collection. + if data has changed. + + + + The method that is called on postback if the date has changed. + + + The event argument (empty and unused). + + + + + Gets a reference to the instance that contains the + server control. + + + A reference to the instance that contains the + server control. + + + + + The selected date. + + The selected date. + + + + The date format that is to be used. + + A valid date format string. + + + + Is direct editing of the date allowed? + + + if direct editing of the date is allowed? + + + + The (CSS) style. + + The style for the calendar. + + + + Occurs when the value of the radio button group changes between postbacks to the server. + + + + + Adds the property to the framework's control. + + + When using Spring.Web's DataBinding, you should use this control for easier binding declaration. + + Erich Eichinger + + + + Gets or Sets the list of selected values and checks the es accordingly + + + + + This validator allows for validating a CheckBox's "Checked" state. + + Erich Eichinger + + + + Validates this validator's properties are set correctly. + + + + + + Returns the state of the checkbox's Checked property + + + + + + Adds attributes required for clientside validation + + + + + + Ensures the evaluation javascript functionblock is registered + + + + + + Represents Content control that can be used to populate or override placeholders + within the master page. + + + Any content defined within this control will override default content + in the matching control + within the master page + + Aleksandar Seovic + + + + Represents ContentPlaceHolder control that can be used to define placeholders + within the master page. + + + Any content defined within this control will be treated as a default content + for the placeholder and will be rendered unless the child page overrides it + by defining matching control. + + Aleksandar Seovic + + + + Represents Content control that can be used to populate or override placeholders + anywhere within the page. + + + + Any content defined within this control will override default content + in the matching control specified by anywhere + within the page. + + + In contrast to control, ContentReplacer can replace the content of + any control within the current page - it is not limited to replacing ContentPlaceholders on master pages. + + + This technique is useful if you want to group e.g. rendering navigation elements on 1 ascx control, but your + design requires navigation elements to be distributed across different places within the HTML code. + + + Erich Eichinger + + + + Overriden to correctly redirect rendermethod calls. + + + + + Renders child controls + + + + + Render nothing. + + + + + Specifies the unique id of the control, who's content is to be replaced. + + + + + May be used to wrap controls for databinding that don't accept unknown attributes. + + + + + Overridden to ensure only 1 control is wrapped by this adapter + + + + + + Overridden to render wrapped control only. + + + + + Returns the control wrapped by this adapter or null. + + + + + Any WebControl placed on a DataBindingPanel may be bound + to a model by adding an attribute "BindingTarget" + + Erich Eichinger + + + + This panel provides the same features as , but provides additional means with regards to Spring. + + + In some cases, automatic dependency injection can cause performance problems. In this case,you can use a Panel for finer-grained control + over which controls are to be injected or not. + + Erich Eichinger + + + + Overridden to set according to if necessary. + + + + + Renders the HTML opening tag of the control to the specified writer. + + An that represents the output stream to render HTML content on the client. + + + + Renders the HTML closing tag of the control to the specified writer. + + An that represents the output stream to render HTML content on the client. + + + + This method is invoked right before InitRecursive() is called for this Panel and + ensures, that dependencies get injected on child controls before their Init event is raised. + + + + + Injects dependencies into control before adding it. + + + + + Overridden to automatically aquire a reference to + root application context to use for DI. + + + + + An optional SpEL expression to control this Panel's state. + + + This panel instance is the context for evaluating the given expression. If no expression is specified, visibility behavior + reverts to standard behavior. + + + + + This flag controls, whether DI on child controls will be done or not + + By default, DI will be done + + + + This flag controls, whether this Panel's tag will be rendered. + + + + + Expose the context of this panel for medium trust safe access in e.g. . + + + + + Sets / Gets the ApplicationContext instance used to configure this control + + + + + Registers this control for the event of it's container. + + + + + Overridden to remove custom binding attributes before rendering. + + + + + + Overriden to suppress rendering this control's tag + + + + + + Called by the containing if bindings must be initialized. + + + + + Adds all controls on this panel to the containing 's binding collection. + + the usercontrol containing this panel + the of controls to be bound + action to be performed on matching controls + + + + Retrieves custom binding attributes from a webcontrol and adds a new binding + instance to the container's if necessary. + + + + + Removes custom binding attributes from a webcontrol to avoid them being rendered. + + + + + Probe for bindingType of know controls + + the control, who's bindingType is to be determined + null, if standard binding is to be used or the fully qualified typename of the binding implementation + + + + Probes for a few know controls and their properties. + + + The 'BindingSource' expression to be used for binding this control. + + + + + This control allows for suppressing output of the 'action' attribute. + + + the 'action' attribute rendered by the default control causes troubles + in case of URL-rewriting. See e.g. 'thescripts.com' forum + and also JIRA SPRNET-560 for more info. + + Erich Eichinger + + + + Renders attributes but performs 'action' suppressing logic. + + + + + + Sets or Gets a value indicating if the 'action' attribute shall be rendered. Defaults to 'false' + + + The following possibilites are available: + + If is 'true', rendering of the 'action' attribute is suppressed. + If is 'false' and is not set, + 'action' attribute will.be rendered to + + If is 'false' and is set, + 'action' attribute will.be rendered to + + + + + + + Sets or Gets an explicit url to be rendered + + + The url specified here is only rendered, if is true. + + + + + This wrapper suppresses output of 'action' attributes. + + + + + This control should be used instead of standard HTML head tag + in order to render dynamicaly registered head scripts and stylesheets. + + + If you need to use ASP.NETs built-in <head> tag, you should nest Spring's within ASP.NET's: + + <html> + <head> + <title>Some Title</title> + <spring:head> + <-- will render styleblocks etc. here --> + </spring:head> + </head> + </html> + + + Aleksandar Seovic + + + + Sends server control content to a provided object, which writes the content to + be rendered on + the client. + + The object that receives the server control content. + + + + Gets or sets the default mimetype for the <style> element's 'type' attribute + + + Defaults to "text/css" + + + + + Gets a reference to the instance that contains the + server control. + + + + + + This control should be used instead of standard HTML head tag + in order to render dynamicaly registered head scripts and stylesheets. + + Aleksandar Seovic + + + + Tries to determine full URL for the localized image before it's rendered. + + + + + + Name of the image file. + + + + + Gets a reference to the instance that contains the + server control. + + + + + + Groups radio button controls and returns the value of the selected control + + + This control alows radio buttons to be data-bound to a data model of the page. + + Aleksandar Seovic + + + + Overloaded to track addition of contained controls. + + + + + Overloaded to track removal of a RadioButton + + + + + + Registers the RadioButtonGroup for PostBack. + + + + + Renders only children of this control. + + HtmlTextWriter to use for rendering. + + + + Loads postback data into the control. + + Key that should be used to retrieve data. + Postback data collection. + True if data has changed, false otherwise. + + + + Raises SelectionChanged event. + + + + + Method that is called on postback if selected radio button has changed. + + Empty event argument. + + + + Gets or sets the ID of the selected radio button. + + ID of the selected radio button. + + + + Gets or sets whether form should be posted back on every selection change + within the radio group. + + + + + Occurs when the value of the radio button group changes between postbacks to the server. + + + + + Provides information about a command raised from a + + Erich Eichinger + + + + Initializes a new instance. + + The name of the command raised by a . + The index of the tab that raised this event. + + + + Returns the index of the tab that raised this command. + + + + + Represents the method that will handle the TabCommand event. + + The source of the event. + A that contains the event data. + Erich Eichinger + + + + This control is responsible for rendering tabs. + + + By default, this TabContainer implementation uses controls to + render tabs. Override to change this behaviour. + + Erich Eichinger + + + + Represents the command name of the tab to be selected. + + + + + Key into the eventhandler table. + + + + + Catches with name '' and + raises the event. + + The source of the event. + contains event information. + + + + + Raises the event. + + + + + Creates a new tab for the specified view within the given container. + + The containing the view + The for which a new tab is to be created. + The index of the tab to be created. + + By default, controls are used for rendering tabs. Override this method to + change this behaviour. + + + + + Occurs, when a tab control is clicked. + + + + + The control allows you to build ASP.NET Web pages that present + the user with content arranged in tabular form. + + Erich Eichinger + + + + Initializes a new instance. + + + + + Initializes a new instance with the given container tag to be used for rendering. + + + + + Create the container for tab items. + + + + + Creates TabContainer and MultiView + + + + + keeps parsed views until multiView is created + + + + + Initialize this control. + + + + + Creates child controls. + + + + + Adds the element to the collection of child controls. + + + + + Called if ActiveViewIndex is changed + + + + + Set the style class of the panel containing the Tabs. + + + + + Set the style class of each Tab item. + + + + + Set the style class of the currently selected Tab item. + + + + + Set the style class of the panel containing all controls. + + + + + Gets or sets the index of the active View control within a control. + + + + + Occurs, if the active tab has changed. + + + + + Represents a control that acts as a container for a group of controls within a control. + + Erich Eichinger + + + + Indicates if this view is currently active. + + + + + Get or Set the name of the tab item associated with this view. + + + + + Get or Set the tooltip text of the tab item associated with this view. + + + + + Holds the collection of controls in a . + + Erich Eichinger + + + + Initialize a new instance. + + + + + + Add the specified control to the collection. + + + + + Add the specified control to the collection. + + + + + Obtain the specified control from the collection. + + + + + This control should be used to display field-level validation errors. + + Aleksandar Seovic + Jonathan Allenby + + + + Create the default + for this ValidationControl if none is configured. + + + + + This control should be used instead of standard ValidationSummary control + to display validation errors identified by the Spring.NET validation framework. + + Aleksandar Seovic + Jonathan Allenby + + + + Create the default + for this ValidationControl if none is configured. + + + + + This class provides common members for all validation errors renderers. + + Aleksandar Seovic + + + + This interface should be implemented by all validation errors renderers. + + + + Validation errors renderers are used to decouple rendering behavior from the + validation errors controls such as and + . + + + This allows users to change how validation errors are rendered by simply pluggin in + appropriate renderer implementation into the validation errors controls using + Spring.NET dependency injection. + + + Aleksandar Seovic + + + + Renders validation errors using specified . + + Web form instance. + An HTML writer to use. + The list of validation errors. + + + + Renders validation errors using specified . + + Web form instance. + An HTML writer to use. + The list of validation errors. + + + + Gets or sets the name of the CSS class that should be used. + + + The name of the CSS class that should be used + + + + + Implementation of that renders + validation errors within a div element, using breaks between the + errors. + + + This renderer's behavior is consistent with standard ASP.NET behavior of + the validation summary, and is used as default renderer for Spring.NET + control. + + Aleksandar Seovic + + + + Renders validation errors using specified . + + Web form instance. + An HTML writer to use. + The list of validation errors. + + + + Implementation of that + displays an error image to let user know there is an error, and + tooltip to display actual error messages. + + + + This renderer's behavior is similar to Windows Forms error provider. + + + Aleksandar Seovic + + + + Renders validation errors using specified . + + Web form instance. + An HTML writer to use. + The list of validation errors. + + + + Gets or sets the name of the image file to use as an error icon. + + + + Image name should be relative to the value of the + property, and should not use leading path separator. + + + The name of the image file to use as an error icon. + + + + Implementation of that renders + validation errors within a span element, using breaks between the + errors. + + + This renderer's behavior is consistent with standard ASP.NET behavior of + the control validators, and is used as the default renderer for Spring.NET + control. + + Aleksandar Seovic + + + + Renders validation errors using specified . + + Web form instance. + An HTML writer to use. + The list of validation errors. + + + + Convinience implementation of the wizard-like page controller. + + +

+ Wizard steps are encapsulated within custom user controls. Wizard + controller takes care of navigation through steps and loading of the + appropriate user control. +

+

+ Developer implementing wizard needs to inherit from this class and implement + abstract, read-only StepPanel property that will be used as a container + for the wizard steps. Navigation event handlers should call Previous and Next methods + from this class to change current step. +

+ + Aleksandar Seovic + + + + Represents an .aspx file, also known as a Web Forms page, requested from a + server that hosts an ASP.NET Web application. + + +

+ The Page class is associated with files that have an .aspx extension. + These files are compiled at run time as Page objects and cached in server memory. +

+

+ This class extends and adds support for master + pages similar to upcoming ASP.Net 2.0 master pages feature. +

+

+ It also adds support for automatic localization using local page resource file, and + simplifies access to global resources (resources from the message source for the + application context). +

+ + Aleksandar Seovic + + + + Abstracts access to properties required for + handling validation and error rendering + + Erich Eichinger + + + + Gets the MessageSource to be used for + resolving error ids into messages + + + + + Gets the list of validation errors kept by this container. + + + + + Creates and initializes the new page instance. + + + Calls . + + + + + Initializes Spring.NET page internals and raises the PreInit event. + + The instance containing the event data. + + + + Initializes the culture. + + + + + Initializes data model and controls. + + + + + Raises the event after page initialization. + + + + + Raises the PreLoadViewState event for + this page and all contained controls. + + + + + Recursively raises PreLoadViewState event. + + + + + Overridden to add support for + + + If necessary override instead of this method. + + + + + If ViewState is disabled, calls recursively for all controls. + + + If ViewState is disabled, DropDownLists etc. might not fire "Changed" events. + + + + + Calls recursively for all controls. + + + + + Recursively calls for all controls. + + + + + If necessary override this method instead of + + + + + Initializes dialog result and unbinds data from the controls + into a data model. + + Event arguments. + + + + Binds data from the data model into controls and raises + PreRender event afterwards. + + Event arguments. + + + + Raises InitializeControls event. + + Event arguments. + + + + Obtains a object from a user control file + and injects dependencies according to Spring config file. + + The virtual path to a user control file. + + Returns the specified object, with dependencies injected. + + + + + Obtains a object by type + and injects dependencies according to Spring config file. + + The type of a user control. + parameters to pass to the control + + Returns the specified object, with dependencies injected. + + + + + Retrieves data model from a persistence store. + + + The default implementation uses to store and retrieve + the model for the current + + + + + Saves data model to a persistence store. + + + The default implementation uses to store and retrieve + the model for the current + + + + + Initializes data model when the page is first loaded. + + + This method should be overriden by the developer + in order to initialize data model for the page. + + + + + Loads the saved data model on postback. + + + This method should be overriden by the developer + in order to load data model for the page. + + + + + Returns a model object that should be saved. + + + This method should be overriden by the developer + in order to save data model for the page. + + + A model object that should be saved. + + + + + Stores the controller to be returned by property. + + + The default implementation uses a field to store the reference. Derived classes may override this behaviour + but must ensure to also change the behaviour of accordingly. + + Controller for the page. + + + + Returns the controller stored by . + + + The default implementation uses a field to retrieve the reference. Derived classes may override this behaviour + but must ensure to also change the behaviour of accordingly. + + + The controller for this page. + + If no controller is set, a reference to the page itself is returned. + + + + + + Registers single CSS style with the page. + + Style name. + Style definition. + + + + Returns True if specified style is registered, False otherwise. + + Style name. + True if specified style is registered, False otherwise. + + + + Registers CSS file with the page. + + Style file key. + Style file name. + + + + Returns True if specified style file is registered, False otherwise. + + Style file key. + True if specified style file is registered, False otherwise. + + + + Registers script block that should be rendered within the head HTML element. + + Script key. + Script text. + + + + Registers script block that should be rendered within the head HTML element. + + Script key. + Script language. + Script text. + + + + Registers script block that should be rendered within the head HTML element. + + Script key. + Script language MIME type. + Script text. + + + + Registers script file that should be referenced within the head HTML element. + + Script key. + Script file name. + + + + Registers script file that should be referenced within the head HTML element. + + Script key. + Script language. + Script file name. + + + + Registers script file that should be referenced within the head HTML element. + + Script key. + Script language MIME type. + Script file name. + + + + Registers script block that should be rendered within the head HTML element. + + Script key. + Element ID of the event source. + Name of the event to handle. + Script text. + + + + Registers script block that should be rendered within the head HTML element. + + Script key. + Script language. + Element ID of the event source. + Name of the event to handle. + Script text. + + + + Registers script block that should be rendered within the head HTML element. + + Script key. + The scripting language's MIME type. + Element ID of the event source. + Name of the event to handle. + Script text. + + + + Returns True if specified head script is registered, False otherwise. + + Script key. + True if specified head script is registered, False otherwise. + + + + Ensure, that is set to a valid instance. + + + If is not already set, creates and sets a new instance.
+ Override this method if you don't want to inject a navigator, but need a different default. + + + + + Redirects user to a URL mapped to specified result name. + + Result name. + + + + Redirects user to a URL mapped to specified result name. + + Name of the result. + The context to use for evaluating the SpEL expression in the Result. + + + + Returns a redirect url string that points to the + defined by this + result evaluated using this Page for expression + + Name of the result. + A redirect url string. + + + + Returns a redirect url string that points to the + defined by this + result evaluated using this Page for expression + + Name of the result. + The context to use for evaluating the SpEL expression in the Result + A redirect url string. + + + + Instructs any validation controls included on the page to validate their assigned information. + + + + + + Instructs the validation controls in the specified validation group to validate their assigned information. + + + The validation group name of the controls to validate. + + + + Evaluates specified validators and returns True if all of them are valid. + + +

+ Each validator can itself represent a collection of other validators if it is + an instance of or one of its derived types. +

+

+ Please see the Validation Framework section in the documentation for more info. +

+ + Object to validate. + Validators to evaluate. + + True if all of the specified validators are valid, False otherwise. + + + + + Creates the validator parameters. + + + + This method can be overriden if you want to pass additional parameters + to the validation framework, but you should make sure that you call + this base implementation in order to add page, session, application, + request, response and context to the variables collection. + + + + Dictionary containing parameters that should be passed to + the data validation framework. + + + + + Initializes the data bindings. + + + + + Returns the key to be used for looking up a cached + BindingManager instance in . + + a unique key identifying the instance in the dictionary. + + + + Creates a new instance. + + + This factory method is called if no could be found in + using the key returned by .
+
+ + + a instance to be used for DataBinding + + + + Initializes binding manager and data bindings if necessary. + + + + + Raises the event. + + + + + Bind data from model to form. + + + + + Unbind data from form to model. + + + + + Raises DataBound event. + + Event arguments. + + + + Raises DataBound event. + + Event arguments. + + + + Initializes local message source + + + + + Creates and returns local ResourceManager for this page. + + + + In ASP.NET 1.1, this method loads local resources from the web application assembly. + + + However, in ASP.NET 2.0, local resources are compiled into a dynamic assembly, + so we need to find that assembly and load the resources from it. + + + Local ResourceManager instance. + + + + Returns message for the specified resource name. + + Resource name. + Message text. + + + + Returns message for the specified resource name. + + Resource name. + Message arguments that will be used to format return value. + Formatted message text. + + + + Returns resource object for the specified resource name. + + Resource name. + Resource object. + + + + Raises UserLocaleChanged event. + + Event arguments. + + + + Creates a key for shared state, taking into account whether + this page belongs to a process or not. + + Key suffix + Generated unique shared state key. + + + + Injects dependencies into control before adding it. + + + + + PreLoadViewState event. + + + + This event is raised if is true + immediately before state is restored from ViewState. + + + NOTE: Different from , this event + will also be raised if the control has no ViewState or ViewState is disabled. + + + + + + This event is raised before Init event and should be used to initialize + controls as necessary. + + + + + Set the strategy for storing model + instances between requests. + + + By default the strategy is used. + + + + + Gets or sets controller for the page. + + + + Application pages should shadow this property and change its type + in order to make calls to controller within the page as simple as possible. + + + If external controller is not specified, page will serve as its own controller, + which will allow data binding to work properly. + + + Controller for the page. Defaults to the page itself. + + + + Returns a thread-safe dictionary that contains state that is shared by + all instances of this page. + + + + + Overrides the default PreviousPage property to return an instance of , + and to work properly during server-side transfers and executes. + + + + + Publish associated with this page for convenient usage in Binding Expressions + + + + + Gets the master page that determines the overall look of the page. + + + + + Returns true if page uses master page, false otherwise. + + + + + Gets a dictionary of registered styles. + + Registered styles. + + + + Gets a dictionary of registered style files. + + Registered style files. + + + + Gets a dictionary of registered head scripts. + + Registered head scripts. + + + + Gets or sets the CSS root. + + The CSS root. + + + + Gets or sets the scripts root. + + The scripts root. + + + + Gets or sets the images root. + + The images root. + + + + Gets/Sets the navigator to be used for handling calls. + + + + + Gets or sets map of result names to target URLs + + + Using requires to implement . + + + + + A convenience, case-insensitive table that may be used to e.g. pass data into SpEL expressions"/>. + + + By default, e.g. passes the control instance into an expression. Using + is an easy way to pass additional parameters into the expression + + This example shows how to pass an arbitrary value 'age' into a result expression. + + // config: + + <property Name="Results"> + <dictionary> + <entry key="ok_clicked" value="redirect:~/ShowResult.aspx?age=%{Args['age']}" /> + </dictionary> + </property> + + // code: + + void OnOkClicked(object sender, EventArgs e) + { + Args["result"] = txtAge.Text; + SetResult("ok_clicked"); + } + + + + + + + Gets or sets the validation errors container. + + The validation errors container. + + + + Expose BindingManager via IDataBound interface + + + + + Gets the binding manager. + + The binding manager. + + + + This event is raised after as been initialized. + + + + + This event is raised after all controls have been populated with values + from the data model. + + + + + This event is raised after data model has been populated with values from + web controls. + + + + + Gets or sets the that this + object runs in. + + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Gets or sets the localizer. + + The localizer. + + + + Gets or sets the culture resolver. + + The culture resolver. + + + + Gets or sets the local message source. + + The local message source. + + + + Gets or sets user's culture + + + + + This event is raised when the value of UserLocale property changes. + + + + + Holds default ApplicationContext instance to be used during DI. + + + + + Moves to the previous step in the list, if one exists. + + + + + Moves to the next step in the list, if one exists. + + + + + Initializes wizard steps. + + Event arguments. + + + + + + + + + + Loads new step into a step panel if step has changed. + + Event arguments. + + + + Initializes all the steps. + + List of step control names. + List of step control instances. + + + + Loads step control. + + + + + Gets or sets a list of user controls representing wizard steps. + + + + + Gets or sets current step using step index. + + + + + Returns true if there are no steps before the current step. + + + + + Returns true if there are no steps after the current step. + + + + + Panel that should serve as a container for wizard steps. + + + + + Specifies that page should be treated as a dialog, meaning that after processing + is over user should return to the referring page. + + +

+ Pages marked with this attribute will have "close" result predefined. +

+

+ Developers should call SetResult("close") from the event handler + in order to return control back to the calling page. +

+ + Aleksandar Seovic + + + + Abstracts storage strategy for storing model instances between requests. + All storage providers participating in UI model management must implement this interface. + + + Erich Eichinger + + + + Load the model for the specified control context. + + the control context. + the model for the specified control context. + + + + Save the specified model object. + + the control context. + the model to save. + + + + Spring.NET Master Page implementation for ASP.NET 2.0 + + Aleksandar Seovic + + + + Initialize a new MasterPage instance. + + + + + Initializes user control. + + + + + Binds data from the data model into controls and raises + PreRender event afterwards. + + Event arguments. + + + + Raises InitializeControls event. + + Event arguments. + + + + Obtains a object from a user control file + and injects dependencies according to Spring config file. + + The virtual path to a user control file. + + Returns the specified object, with dependencies injected. + + + + + Obtains a object by type + and injects dependencies according to Spring config file. + + The type of a user control. + parameters to pass to the control + + Returns the specified object, with dependencies injected. + + + + + Raises DataBound event. + + Event arguments. + + + + Raises DataBound event. + + Event arguments. + + + + Initializes local message source + + + + + Creates and returns local ResourceManager for this page. + + + + In ASP.NET 1.1, this method loads local resources from the web application assembly. + + + However, in ASP.NET 2.0, local resources are compiled into the dynamic assembly, + so we need to find that assembly instead and load the resources from it. + + + Local ResourceManager instance. + + + + Returns message for the specified resource name. + + Resource name. + Message text. + + + + Returns message for the specified resource name. + + Resource name. + Message arguments that will be used to format return value. + Formatted message text. + + + + Returns resource object for the specified resource name. + + Resource name. + Resource object. + + + + Ensure, that is set to a valid instance. + + + If is not already set, creates and sets a new instance.
+ Override this method if you don't want to inject a navigator, but need a different default. + + + + + Redirects user to a URL mapped to specified result name. + + Result name. + + + + Redirects user to a URL mapped to specified result name. + + Name of the result. + The context to use for evaluating the SpEL expression in the Result. + + + + Returns a redirect url string that points to the + defined by this + result evaluated using this Page for expression + + Name of the result. + A redirect url string. + + + + Returns a redirect url string that points to the + defined by this + result evaluated using this Page for expression + + Name of the result. + The context to use for evaluating the SpEL expression in the Result + A redirect url string. + + + + Evaluates specified validators and returns True if all of them are valid. + + +

+ Each validator can itself represent a collection of other validators if it is + an instance of or one of its derived types. +

+

+ Please see the Validation Framework section in the documentation for more info. +

+ + Object to validate. + Validators to evaluate. + + True if all of the specified validators are valid, False otherwise. + + + + + Creates the validator parameters. + + + + This method can be overriden if you want to pass additional parameters + to the validation framework, but you should make sure that you call + this base implementation in order to add page, session, application, + request, response and context to the variables collection. + + + + Dictionary containing parameters that should be passed to + the data validation framework. + + + + + Injects dependencies before adding the control. + + + + + This event is raised before Load event and should be used to initialize + controls as necessary. + + + + + This event is raised after all controls have been populated with values + from the data model. + + + + + This event is raised after data model has been populated with values from + web controls. + + + + + Gets or sets the that this + object runs in. + + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Gets or sets the localizer. + + The localizer. + + + + Gets or sets the local message source. + + The local message source. + + + + Gets or sets user's culture + + + + + Gets/Sets the navigator to be used for handling calls. + + + + + Gets or sets map of result names to target URLs + + + Using requires to implement . + + + + + A convenience, case-insensitive table that may be used to e.g. pass data into SpEL expressions"/>. + + + By default, e.g. passes the control instance into an expression. Using + is an easy way to pass additional parameters into the expression + + // config: + + <property Name="Results"> + <dictionary> + <entry key="ok_clicked" value="redirect:~/ShowResult.aspx?result=%{Args['result']}" /> + </dictionary> + </property> + + // code: + + void OnOkClicked(object sender, EventArgs e) + { + Args["result"] = txtUserInput.Text; + SetResult("ok_clicked"); + } + + + + + + Gets the validation errors container. + + The validation errors container. + + + + Overrides Page property to return + instead of . + + + + + Holds the default ApplicationContext to be used during DI. + + + + + implements -based storage for + UI model management. + + Erich Eichinger + + + + Load the model for the specified control context. + + + The key used for loading the model from the session dictionary is obtained by calling + + the control context. + the model for the specified control context. + + + + + Save the specified model object to session. + + + The key used for storing the model into the session dictionary is obtained by calling + + the control context. + the model to save. + + + + + Create the key to be used for accessing the dictionary. + + + + + + + Abstracts session access for unit testing. + + + + + Abstracts session access for unit testing. + + + + + Extends standard .Net user control by adding data binding and localization functionality. + + Aleksandar Seovic + + + + Initialize a new UserControl instance. + + + + + Initializes user control. + + + + + Raises the event after page initialization. + + + + + This method is called during a postback if this control has been visible when being rendered to the client. + + + If the controls has been visible when being rendering to the client, + has been called during + + true if the server control's state changes as a result of the post back; otherwise false. + + + + This method is called during a postback if this control has been visible when being rendered to the client. + + true if the server control's state changes as a result of the post back; otherwise false. + + + + When implemented by a class, signals the server control object to notify the + ASP.NET application that the state of the control has changed. + + + + + When implemented by a class, signals the server control object to notify the + ASP.NET application that the state of the control has changed. + + + + + First unbinds data from the controls into a data model and + then raises Load event in order to execute all associated handlers. + + Event arguments. + + + + Binds data from the data model into controls and raises + PreRender event afterwards. + + Event arguments. + + + + Raises InitializeControls event. + + Event arguments. + + + + Obtains a object from a user control file + and injects dependencies according to Spring config file. + + The virtual path to a user control file. + + Returns the specified object, with dependencies injected. + + + + + Obtains a object by type + and injects dependencies according to Spring config file. + + The type of a user control. + parameters to pass to the control + + Returns the specified object, with dependencies injected. + + + + + Retrieves data model from a persistence store. + + + The default implementation uses to store and retrieve + the model for the current + + + + + Saves data model to a persistence store. + + + The default implementation uses to store and retrieve + the model for the current + + + + + Initializes data model when the page is first loaded. + + + This method should be overriden by the developer + in order to initialize data model for the page. + + + + + Loads the saved data model on postback. + + + This method should be overriden by the developer + in order to load data model for the page. + + + + + Returns a model object that should be saved. + + + This method should be overriden by the developer + in order to save data model for the page. + + + A model object that should be saved. + + + + + Stores the controller to be returned by property. + + + The default implementation uses a field to store the reference. Derived classes may override this behaviour + but must ensure to also change the behaviour of accordingly. + + Controller for the control. + + + + Returns the controller stored by . + + + + The default implementation uses a field to retrieve the reference. + + + If external controller is not specified, control will serve as its own controller, + which will allow data binding to work properly. + + + You may override this method e.g. to return in order to + have your control bind to the same controller as your page. When overriding this behaviour, derived classes + must ensure to also change the behaviour of accordingly. + + + + The controller for this control. + If no controller is set, a reference to the control itself is returned. + + + + + Ensure, that is set to a valid instance. + + + If is not already set, creates and sets a new instance.
+ Override this method if you don't want to inject a navigator, but need a different default. + + + + + Redirects user to a URL mapped to specified result name. + + Result name. + + + + Redirects user to a URL mapped to specified result name. + + Name of the result. + The context to use for evaluating the SpEL expression in the Result. + + + + Returns a redirect url string that points to the + defined by this + result evaluated using this Page for expression + + Name of the result. + A redirect url string. + + + + Returns a redirect url string that points to the + defined by this + result evaluated using this Page for expression + + Name of the result. + The context to use for evaluating the SpEL expression in the Result + A redirect url string. + + + + Evaluates specified validators and returns True if all of them are valid. + + +

+ Each validator can itself represent a collection of other validators if it is + an instance of or one of its derived types. +

+

+ Please see the Validation Framework section in the documentation for more info. +

+ + Object to validate. + Validators to evaluate. + + True if all of the specified validators are valid, False otherwise. + + + + + Creates the validator parameters. + + + + This method can be overriden if you want to pass additional parameters + to the validation framework, but you should make sure that you call + this base implementation in order to add page, session, application, + request, response and context to the variables collection. + + + + Dictionary containing parameters that should be passed to + the data validation framework. + + + + + Initializes the data bindings. + + + + + Returns the key to be used for looking up a cached + BindingManager instance in . + + a unique key identifying the instance in the dictionary. + + + + Creates a new instance. + + + This factory method is called if no could be found in + using the key returned by .
+
+ + + a instance to be used for DataBinding + + + + Initializes binding manager and data bindings if necessary. + + + + + Raises the event. + + + + + Bind data from model to form. + + + + + Unbind data from form to model. + + + + + Raises DataBound event. + + Event arguments. + + + + Raises DataBound event. + + Event arguments. + + + + Initializes local message source + + + + + Creates and returns local ResourceManager for this page. + + + + In ASP.NET 1.1, this method loads local resources from the web application assembly. + + + However, in ASP.NET 2.0, local resources are compiled into the dynamic assembly, + so we need to find that assembly instead and load the resources from it. + + + Local ResourceManager instance. + + + + Returns message for the specified resource name. + + Resource name. + Message text. + + + + Returns message for the specified resource name. + + Resource name. + Message arguments that will be used to format return value. + Formatted message text. + + + + Returns resource object for the specified resource name. + + Resource name. + Resource object. + + + + Creates a key for shared state, taking into account whether + this page belongs to a process or not. + + Key suffix + Generated unique shared state key. + + + + Injects dependencies into control before adding it. + + + + + PreLoadViewState event. + + + + This event is raised if is true + immediately before state is restored from ViewState. + + + NOTE: Different from , this event will always be raised! + + + + + + This event is raised before Load event and should be used to initialize + controls as necessary. + + + + + Set the strategy for storing model + instances between requests. + + + By default the strategy is used. + + + + + Gets or sets controller for the control. + + + + Internally calls are delegated to and . + + + Controller for the control. + + + + Returns a thread-safe dictionary that contains state that is shared by + all instances of this control. + + + + + Gets/Sets the navigator to be used for handling calls. + + + + + Gets or sets map of result names to target URLs + + + Using requires to implement . + + + + + A convenience, case-insensitive table that may be used to e.g. pass data into SpEL expressions"/>. + + + By default, e.g. passes the control instance into an expression. Using + is an easy way to pass additional parameters into the expression + + // config: + + <property Name="Results"> + <dictionary> + <entry key="ok_clicked" value="redirect:~/ShowResult.aspx?result=%{Args['result']}" /> + </dictionary> + </property> + + // code: + + void OnOkClicked(object sender, EventArgs e) + { + Args["result"] = txtUserInput.Text; + SetResult("ok_clicked"); + } + + + + + + Gets or sets the validation errors container. + + The validation errors container. + + + + Gets the binding manager for this control. + + The binding manager. + + + + This event is raised after as been initialized. + + + + + This event is raised after all controls have been populated with values + from the data model. + + + + + This event is raised after data model has been populated with values from + web controls. + + + + + Gets or sets the that this + object runs in. + + + +

+ Normally this call will be used to initialize the object. +

+

+ Invoked after population of normal object properties but before an + init callback such as + 's + + or a custom init-method. Invoked after the setting of any + 's + + property. +

+ + + In the case of application context initialization errors. + + + If thrown by any application context methods. + + + + + + Gets or sets the localizer. + + The localizer. + + + + Gets or sets the local message source. + + The local message source. + + + + Gets or sets user's culture + + + + + Overrides Page property to return + instead of . + + + + + Publish associated with this page for convenient usage in Binding Expressions + + + + + Holds the default ApplicationContext to be used during DI. + + + + diff --git a/Resources/Libraries/ZXing/zxing.dll b/Resources/Libraries/ZXing/zxing.dll new file mode 100644 index 00000000..709a55ab Binary files /dev/null and b/Resources/Libraries/ZXing/zxing.dll differ diff --git a/Resources/Libraries/ZXing/zxing.pdb b/Resources/Libraries/ZXing/zxing.pdb new file mode 100644 index 00000000..73a01156 Binary files /dev/null and b/Resources/Libraries/ZXing/zxing.pdb differ diff --git a/Resources/Libraries/fastJSON/fastJSON-SL.dll b/Resources/Libraries/fastJSON/fastJSON-SL.dll new file mode 100644 index 00000000..50b6c6af Binary files /dev/null and b/Resources/Libraries/fastJSON/fastJSON-SL.dll differ diff --git a/Resources/Libraries/fastJSON/fastJSON-SL.pdb b/Resources/Libraries/fastJSON/fastJSON-SL.pdb new file mode 100644 index 00000000..bd845c61 Binary files /dev/null and b/Resources/Libraries/fastJSON/fastJSON-SL.pdb differ diff --git a/Resources/Libraries/fastJSON/fastJSON.dll b/Resources/Libraries/fastJSON/fastJSON.dll new file mode 100644 index 00000000..b7ee2f3d Binary files /dev/null and b/Resources/Libraries/fastJSON/fastJSON.dll differ diff --git a/Resources/Libraries/fastJSON/fastJSON.pdb b/Resources/Libraries/fastJSON/fastJSON.pdb new file mode 100644 index 00000000..1405a0be Binary files /dev/null and b/Resources/Libraries/fastJSON/fastJSON.pdb differ diff --git a/Resources/Libraries/iTextSharp/itextsharp.dll b/Resources/Libraries/iTextSharp/itextsharp.dll new file mode 100644 index 00000000..d094db4b Binary files /dev/null and b/Resources/Libraries/iTextSharp/itextsharp.dll differ