1 /*
2 * Copyright (C) 2012 Alberto Irurueta Carro (alberto@irurueta.com)
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.irurueta.algebra;
17
18 public abstract class Decomposer {
19
20 /**
21 * Reference to input matrix to be decomposed.
22 */
23 protected Matrix inputMatrix;
24
25 /**
26 * Member indicating whether this decomposer instance is locked or not.
27 * When locked, attempting to change parameters of this instance might
28 * raise a com.algebra.LockedException.
29 */
30 protected boolean locked;
31
32 /**
33 * Constructor of this class.
34 */
35 protected Decomposer() {
36 this.inputMatrix = null;
37 locked = false;
38 }
39
40 /**
41 * Constructor of this class.
42 *
43 * @param inputMatrix Reference to input matrix to be decomposed.
44 */
45 protected Decomposer(final Matrix inputMatrix) {
46 this.inputMatrix = inputMatrix;
47 locked = false;
48 }
49
50 /**
51 * Returns decomposer type of this instance. Decomposer type determines the
52 * algorithm being used for matrix decomposition. Depending on this type,
53 * after calling decompose() method, different object or matrices will be
54 * available for retrieval.
55 *
56 * @return Decomposer type of this instance.
57 */
58 public abstract DecomposerType getDecomposerType();
59
60 /**
61 * Returns a reference to input matrix to be decomposed.
62 *
63 * @return Reference to input matrix to be decomposed.
64 */
65 public Matrix getInputMatrix() {
66 return inputMatrix;
67 }
68
69 /**
70 * Sets reference to input matrix to be decomposed.
71 *
72 * @param inputMatrix Reference to input matrix to be decomposed.
73 * @throws LockedException Exception thrown if attempting to call this
74 * method while this instance remains locked.
75 */
76 public void setInputMatrix(final Matrix inputMatrix) throws LockedException {
77 if (isLocked()) {
78 throw new LockedException();
79 }
80 this.inputMatrix = inputMatrix;
81 }
82
83 /**
84 * Returns boolean indicating whether this instance is ready for
85 * decomposition computation.
86 * Attempting to call decompose() method when this instance is not ready
87 * will result on a NotReadyException being thrown.
88 *
89 * @return Boolean indicating whether this instance is ready for
90 * decomposition computation.
91 */
92 public boolean isReady() {
93 return inputMatrix != null;
94 }
95
96 /**
97 * Returns boolean indicating whether this instance is locked or not. When
98 * locked, attempting to change some parameters of this instance might raise
99 * a LockedException.
100 *
101 * @return Boolean indicating whether this instance is locked or not.
102 */
103 public boolean isLocked() {
104 return locked;
105 }
106
107 /**
108 * Returns boolean indicating whether decomposition has been computed and
109 * results can be retrieved.
110 * Attempting to retrieve decomposition results when not available, will
111 * probably raise a NotAvailableException.
112 *
113 * @return Boolean indicating whether decomposition has been computed and
114 * results can be retrieved.
115 */
116 public abstract boolean isDecompositionAvailable();
117
118 /**
119 * This method computes matrix decomposition for each decomposer type.
120 * After execution of this method, different objects might be generated
121 * depending on decomposition type and decomposition results availability.
122 * Note: during execution of this method, this instance might become locked
123 * depending on subclass implementation.
124 *
125 * @throws NotReadyException Exception thrown if attempting to call this
126 * method when this instance is not yet ready for decomposition, usually
127 * because some data or parameter is missing.
128 * @throws LockedException Exception thrown if this decomposer is already
129 * locked before calling this method. Notice that this method will actually
130 * lock this instance while it is being executed.
131 * @throws DecomposerException Exception thrown if for any other reason
132 * decomposition fails while being executed, like when convergence or
133 * results cannot be obtained, etc.
134 */
135 public abstract void decompose() throws NotReadyException, LockedException,
136 DecomposerException;
137 }