00001 /* Bugzilla C# Proxy Library 00002 Copyright (C) 2006, Dansk BiblioteksCenter A/S 00003 Mads Bondo Dydensborg, <mbd@dbc.dk> 00004 00005 This library is free software; you can redistribute it and/or 00006 modify it under the terms of the GNU Lesser General Public 00007 License as published by the Free Software Foundation; either 00008 version 2.1 of the License, or (at your option) any later version. 00009 00010 This library is distributed in the hope that it will be useful, 00011 but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00013 Lesser General Public License for more details. 00014 00015 You should have received a copy of the GNU Lesser General Public 00016 License along with this library; if not, write to the Free Software 00017 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 00018 */ 00019 00020 /*! \file 00021 \brief Encapsulation of a product in Bugzilla 00022 00023 Bugs are associated with products and components. This is a class 00024 that describes the methods and properties of a product. 00025 00026 You cannot directly create a \b Product object. You should get a \b Product 00027 object from Server.GetProduct or Server.GetProducts. 00028 00029 In order to actually instantiate a Product, a Server instance must 00030 be created first. 00031 */ 00032 00033 using System; 00034 using CookComputing.XmlRpc; 00035 using Bugzproxy.ProxyStructs; 00036 00037 namespace Bugzproxy { 00038 00039 /// <summary>Encapsulation of a product in Bugzilla</summary> 00040 /// <remarks> 00041 /// <para>Currently there are no public constructors. You should get a <b>Product</b> 00042 /// object from <see cref="Server.GetProduct"/> or <see cref="Server.GetProducts"/>. 00043 /// </para> 00044 /// </remarks> 00045 public class Product { 00046 private Server server; 00047 00048 private ProductInfo pi; 00049 00050 /*! \name Constructors 00051 00052 Currently there is no way to create an entirely new product. Only 00053 product instances that reflect an already existing product on the 00054 server can be created. 00055 00056 You can obtain a Product object from Server.GetProduct or Server.GetProducts. 00057 */ 00058 //@{ 00059 00060 /// <summary>Initialize a new instance of the <see cref="Product"/> class with 00061 /// the specified Bugzilla server and <see cref="ProxyStructs.ProductInfo"/> 00062 /// struct.</summary> 00063 /// <param name="server">A Server instance that is associated with this product.</param> 00064 /// <param name="pi">Information about the product, as retrieved from the 00065 /// server</param> 00066 internal Product( Server server, ProductInfo pi ) { 00067 this.server = server; 00068 this.pi = pi; 00069 } 00070 //@} 00071 00072 /// <summary>Get the ID of the product.</summary> 00073 /// <value>The numeric ID of the product</value> 00074 public int Id { 00075 get { 00076 return pi.id; 00077 } 00078 } 00079 00080 /// <summary>Get the name of the product.</summary> 00081 /// <value>The name of the product</value> 00082 public string Name { 00083 get { 00084 return pi.name; 00085 } 00086 } 00087 00088 /// <summary>Get the description of the product</summary> 00089 /// <value>The description of the product</value> 00090 public string Description { 00091 get { 00092 return pi.description; 00093 } 00094 } 00095 00096 /// <summary>Get list of legal values for a bug field</summary> 00097 /// <param name="fieldName">The name of a field.</param> 00098 /// <remarks>This can be used to retrieve a list of legal values 00099 /// for both product specific fields, as well as non-product 00100 /// specific fields of a bug, such as status, severity, component, 00101 /// and so on. When applicable, you should prefer using one of 00102 /// <see cref="Server.OperatingSystem"/>, <see cref="Server.AssignedTo"/>, 00103 /// <see cref="Server.QaContact"/> or <see cref="Server.TargetMilestone"/>. 00104 /// For other fields, including your own custom fields, you may use the Bugzilla 00105 /// original naming (such as <c>op_sys</c>).</remarks> 00106 /// <returns>A list of legal values for the field</returns> 00107 public string[] GetLegalFieldValues(string fieldName) { 00108 return server.GetLegalFieldValues(fieldName, Id); 00109 } 00110 00111 /// <summary>Get a list of the components of this product.</summary> 00112 /// <remarks>This just calls <see cref="GetLegalFieldValues(string)"/> with 00113 /// <c>"component"</c> as parameter value.</remarks> 00114 /// <returns>A list of the components of the product.</returns> 00115 public string[] GetComponents() { 00116 return GetLegalFieldValues("component"); 00117 } 00118 00119 /*! \example CreateBug.cs 00120 * This is an example on how to use the Bugzproxy.Product.CreateBug call */ 00121 00122 /// <summary>Create a new bug on this product</summary> 00123 /// <remarks> 00124 /// <para>The parameters for this call can be marked "optional" 00125 /// or "defaulted". Optional parameters can be left out in all 00126 /// Bugzilla installations (i.e. receive <b>null</b>), and a default value 00127 /// from the server 00128 /// will be substituted. Defaulted parameters can be left out of 00129 /// some installations, while other installations may require 00130 /// these parameters to be present. This is decided in the 00131 /// Bugzilla preferences. If you wish to make sure that the call 00132 /// works with all Bugzilla installations, you should supply 00133 /// values for all "defaulted" parameters. Use <see cref="GetLegalFieldValues"/> 00134 /// to get a list of the legal values for a given 00135 /// field. Parameters not marked optional or defaulted are 00136 /// required.</para> 00137 /// <para>It is recommended that you use <see cref="GetLegalFieldValues"/> to 00138 /// retrieve legal values for parameters such as <paramref name="component"/>, 00139 /// <paramref name="version"/>, <see cref="operatingSystem"/>, and other parameters 00140 /// that have pre-configured values on the server.</para> 00141 /// </remarks> 00142 /// <param name="alias">(Optional) If aliases are enabled for the Bugzilla 00143 /// server, you can supply an unique identifier (no spaces or 00144 /// weird characters) to identify the bug with, in 00145 /// addition to the id.</param> 00146 /// <param name="component">The name of the component that the bug 00147 /// will be created under.</param> 00148 /// <param name="version">The version of the product, that the bug 00149 /// was found in.</param> 00150 /// <param name="operatingSystem">(Defaulted) The operating system 00151 /// the bug was discovered on.</param> 00152 /// <param name="platform">(Defaulted) What type of hardware the 00153 /// bug was experienced on.</param> 00154 /// <param name="summary">Summary of the bug.</param> 00155 /// <param name="description">(Defaulted) Description of the 00156 /// bug.</param> 00157 /// <param name="priority">(Defaulted) What order the bug will be 00158 /// fixed in by the developer, compared to the developer's other 00159 /// bugs.</param> 00160 /// <param name="severity">(Defaulted) How severe the bug 00161 /// is.</param> 00162 /// <param name="status">(Optional) The status that this bug 00163 /// should start out as. Note that only certain statuses can be 00164 /// set on bug creation.</param> 00165 /// <param name="targetMilestone">(Optional) A valid target 00166 /// milestone for this product.</param> 00167 /// <param name="assignedTo">(Optional) A user to assign this bug 00168 /// to, if you don't want it to be assigned to the component 00169 /// owner.</param> 00170 /// <param name="cc">(Optional) An array of usernames to CC on 00171 /// this bug.</param> 00172 /// <param name="qaContact">(Optional) If this installation has QA 00173 /// Contacts enabled, you can set the QA Contact here if you don't 00174 /// want to use the components default QA Contact. </param> 00175 /// <returns>The newly created bug.</returns> 00176 public Bug CreateBug(string alias, string component, 00177 string version, string operatingSystem, string platform, 00178 string summary, string description, 00179 string priority, string severity, string status, 00180 string targetMilestone, string assignedTo, string[] cc, 00181 string qaContact) { 00182 CreateBugParam param; 00183 param.product = pi.name; 00184 param.alias = alias; 00185 param.component = component; 00186 param.version = version; 00187 param.operatingSystem = operatingSystem; 00188 param.platform = platform; 00189 param.summary = summary; 00190 param.description = description; 00191 param.priority = priority; 00192 param.severity = severity; 00193 param.status = status; 00194 param.targetMilestone = targetMilestone; 00195 param.assignedTo = assignedTo; 00196 param.cc = cc; 00197 param.qaContact = qaContact; 00198 return server.GetBug(server.Proxy.CreateBug(param).id); 00199 } 00200 00201 00202 /// <summary> 00203 /// Create a new bug on this product 00204 /// </summary> 00205 /// <param name="component">The name of the component that the bug 00206 /// will be created under.</param> 00207 /// <param name="version">The version of the product, that the bug 00208 /// was found in.</param> 00209 /// <param name="operatingSystem">(Defaulted) The operating system 00210 /// the bug was discovered on.</param> 00211 /// <param name="platform">(Defaulted) What type of hardware the 00212 /// bug was experienced on.</param> 00213 /// <param name="summary">Summary of the bug.</param> 00214 /// <param name="description">(Defaulted) Description of the 00215 /// bug.</param> 00216 /// <param name="priority">(Defaulted) What order the bug will be 00217 /// fixed in by the developer, compared to the developer's other 00218 /// bugs.</param> 00219 /// <param name="severity">(Defaulted) How severe the bug 00220 /// is.</param> 00221 /// <returns>The newly created bug.</returns> 00222 /// <remarks> 00223 /// <para>Parameters marked as Defaulted can be left out in 00224 /// some installations, while other installations may require 00225 /// these parameters to be present. This is decided in the 00226 /// Bugzilla preferences. If you wish to make sure that the call 00227 /// works with all Bugzilla installations, you should supply 00228 /// values for all "defaulted" parameters.</para> 00229 /// <para>It is recommended that you use <see cref="GetLegalFieldValues"/> to 00230 /// retrieve legal values for parameters such as <paramref name="component"/>, 00231 /// <paramref name="version"/>, <see cref="operatingSystem"/>, and other parameters 00232 /// that have pre-configured values on the server.</para> 00233 /// </remarks> 00234 public Bug CreateBug( 00235 string component, string version, 00236 string operatingSystem, string platform, 00237 string summary, string description, 00238 string priority, string severity) { 00239 00240 return CreateBug(null, component, version, operatingSystem, platform, summary, 00241 description, priority, severity, null, null, null, null, null); 00242 } 00243 00244 /// <summary> 00245 /// Create a new bug on this product 00246 /// </summary> 00247 /// <param name="alias">If aliases are enabled for the Bugzilla server, you 00248 /// can supply an unique identifier (no spaces or weird characters) to identify 00249 /// the bug with, in addition to the id.</param> 00250 /// <param name="component">The name of the component that the bug 00251 /// will be created under.</param> 00252 /// <param name="version">The version of the product, that the bug 00253 /// was found in.</param> 00254 /// <param name="operatingSystem">(Defaulted) The operating system 00255 /// the bug was discovered on.</param> 00256 /// <param name="platform">(Defaulted) What type of hardware the 00257 /// bug was experienced on.</param> 00258 /// <param name="summary">Summary of the bug.</param> 00259 /// <param name="description">(Defaulted) Description of the 00260 /// bug.</param> 00261 /// <param name="priority">(Defaulted) What order the bug will be 00262 /// fixed in by the developer, compared to the developer's other 00263 /// bugs.</param> 00264 /// <param name="severity">(Defaulted) How severe the bug 00265 /// is.</param> 00266 /// <returns>The newly created bug.</returns> 00267 /// <remarks> 00268 /// <para>Parameters marked as Defaulted can be left out in 00269 /// some installations, while other installations may require 00270 /// these parameters to be present. This is decided in the 00271 /// Bugzilla preferences. If you wish to make sure that the call 00272 /// works with all Bugzilla installations, you should supply 00273 /// values for all "defaulted" parameters.</para> 00274 /// <para>It is recommended that you use <see cref="GetLegalFieldValues"/> to 00275 /// retrieve legal values for parameters such as <paramref name="component"/>, 00276 /// <paramref name="version"/>, <see cref="operatingSystem"/>, and other parameters 00277 /// that have pre-configured values on the server.</para> 00278 /// </remarks> 00279 public Bug CreateBug( 00280 string alias, string component, 00281 string version, string operatingSystem, 00282 string platform, string summary, 00283 string description, string priority, 00284 string severity) { 00285 00286 return CreateBug(alias, component, version, operatingSystem, platform, summary, 00287 description, priority, severity, null, null, null, null, null); 00288 } 00289 00290 /// <summary> 00291 /// Create a new bug on this product 00292 /// </summary> 00293 /// <param name="alias">(Optional) If aliases are enabled for the Bugzilla 00294 /// server, you can supply an unique identifier (no spaces or weird characters) 00295 /// to identify the bug with, in addition to the id.</param> 00296 /// <param name="component">The name of the component that the bug 00297 /// will be created under.</param> 00298 /// <param name="version">The version of the product, that the bug 00299 /// was found in.</param> 00300 /// <param name="operatingSystem">(Defaulted) The operating system 00301 /// the bug was discovered on.</param> 00302 /// <param name="platform">(Defaulted) What type of hardware the 00303 /// bug was experienced on.</param> 00304 /// <param name="summary">Summary of the bug.</param> 00305 /// <param name="description">(Defaulted) Description of the 00306 /// bug.</param> 00307 /// <param name="priority">(Defaulted) What order the bug will be 00308 /// fixed in by the developer, compared to the developer's other 00309 /// bugs.</param> 00310 /// <param name="severity">(Defaulted) How severe the bug 00311 /// is.</param> 00312 /// <param name="status">(Optional) The status that this bug 00313 /// should start out as. Note that only certain statuses can be 00314 /// set on bug creation.</param> 00315 /// <returns>The newly created bug.</returns> 00316 /// <remarks> 00317 /// <para>The parameters for this call can be marked "optional" 00318 /// or "defaulted". Optional parameters can be left out in all 00319 /// Bugzilla installations (i.e. receive <b>null</b>), and a default value 00320 /// from the server will be substituted. 00321 /// Parameters marked as Defaulted can be left out in 00322 /// some installations, while other installations may require 00323 /// these parameters to be present. This is decided in the 00324 /// Bugzilla preferences. If you wish to make sure that the call 00325 /// works with all Bugzilla installations, you should supply 00326 /// values for all "defaulted" parameters.</para> 00327 /// <para>It is recommended that you use <see cref="GetLegalFieldValues"/> to 00328 /// retrieve legal values for parameters such as <paramref name="component"/>, 00329 /// <paramref name="version"/>, <see cref="operatingSystem"/>, and other parameters 00330 /// that have pre-configured values on the server.</para> 00331 /// </remarks> 00332 public Bug CreateBug( 00333 string alias, string component, 00334 string version, string operatingSystem, 00335 string platform, string summary, 00336 string description, string priority, 00337 string severity, string status) { 00338 00339 return CreateBug(alias, component, version, operatingSystem, platform, summary, 00340 description, priority, severity, status, null, null, null, null); 00341 } 00342 00343 /// <summary> 00344 /// Create a new bug on this product 00345 /// </summary> 00346 /// <param name="alias">(Optional) If aliases are enabled for the Bugzilla 00347 /// server, you can supply an unique identifier (no spaces or weird characters) 00348 /// to identify the bug with, in addition to the id.</param> 00349 /// <param name="component">The name of the component that the bug 00350 /// will be created under.</param> 00351 /// <param name="version">The version of the product, that the bug 00352 /// was found in.</param> 00353 /// <param name="operatingSystem">(Defaulted) The operating system 00354 /// the bug was discovered on.</param> 00355 /// <param name="platform">(Defaulted) What type of hardware the 00356 /// bug was experienced on.</param> 00357 /// <param name="summary">Summary of the bug.</param> 00358 /// <param name="description">(Defaulted) Description of the 00359 /// bug.</param> 00360 /// <param name="priority">(Defaulted) What order the bug will be 00361 /// fixed in by the developer, compared to the developer's other 00362 /// bugs.</param> 00363 /// <param name="severity">(Defaulted) How severe the bug 00364 /// is.</param> 00365 /// <param name="status">(Optional) The status that this bug 00366 /// should start out as. Note that only certain statuses can be 00367 /// set on bug creation.</param> 00368 /// <param name="targetMilestone">(Optional) A valid target 00369 /// milestone for this product.</param> 00370 /// <returns>The newly created bug.</returns> 00371 /// <remarks> 00372 /// <para>The parameters for this call can be marked "optional" 00373 /// or "defaulted". Optional parameters can be left out in all 00374 /// Bugzilla installations (i.e. receive <b>null</b>), and a default value 00375 /// from the server will be substituted. 00376 /// Parameters marked as Defaulted can be left out in 00377 /// some installations, while other installations may require 00378 /// these parameters to be present. This is decided in the 00379 /// Bugzilla preferences. If you wish to make sure that the call 00380 /// works with all Bugzilla installations, you should supply 00381 /// values for all "defaulted" parameters.</para> 00382 /// <para>It is recommended that you use <see cref="GetLegalFieldValues"/> to 00383 /// retrieve legal values for parameters such as <paramref name="component"/>, 00384 /// <paramref name="version"/>, <see cref="operatingSystem"/>, and other parameters 00385 /// that have pre-configured values on the server.</para> 00386 /// </remarks> 00387 public Bug CreateBug( 00388 string alias, string component, 00389 string version, string operatingSystem, 00390 string platform, string summary, 00391 string description, string priority, 00392 string severity, string status, 00393 string targetMilestone) { 00394 00395 return CreateBug(alias, component, version, operatingSystem, platform, summary, 00396 description, priority, severity, status, targetMilestone, null, null, null); 00397 } 00398 00399 /// <summary> 00400 /// Create a new bug on this product 00401 /// </summary> 00402 /// <param name="alias">(Optional) If aliases are enabled for the Bugzilla 00403 /// server, you can supply an unique identifier (no spaces or weird characters) 00404 /// to identify the bug with, in addition to the id.</param> 00405 /// <param name="component">The name of the component that the bug 00406 /// will be created under.</param> 00407 /// <param name="version">The version of the product, that the bug 00408 /// was found in.</param> 00409 /// <param name="operatingSystem">(Defaulted) The operating system 00410 /// the bug was discovered on.</param> 00411 /// <param name="platform">(Defaulted) What type of hardware the 00412 /// bug was experienced on.</param> 00413 /// <param name="summary">Summary of the bug.</param> 00414 /// <param name="description">(Defaulted) Description of the 00415 /// bug.</param> 00416 /// <param name="priority">(Defaulted) What order the bug will be 00417 /// fixed in by the developer, compared to the developer's other 00418 /// bugs.</param> 00419 /// <param name="severity">(Defaulted) How severe the bug 00420 /// is.</param> 00421 /// <param name="status">(Optional) The status that this bug 00422 /// should start out as. Note that only certain statuses can be 00423 /// set on bug creation.</param> 00424 /// <param name="targetMilestone">(Optional) A valid target 00425 /// milestone for this product.</param> 00426 /// <param name="assignedTo">(Optional) A user to assign this bug 00427 /// to, if you don't want it to be assigned to the component 00428 /// owner.</param> 00429 /// <returns>The newly created bug.</returns> 00430 /// <remarks> 00431 /// <para>The parameters for this call can be marked "optional" 00432 /// or "defaulted". Optional parameters can be left out in all 00433 /// Bugzilla installations (i.e. receive <b>null</b>), and a default value 00434 /// from the server will be substituted. 00435 /// Parameters marked as Defaulted can be left out in 00436 /// some installations, while other installations may require 00437 /// these parameters to be present. This is decided in the 00438 /// Bugzilla preferences. If you wish to make sure that the call 00439 /// works with all Bugzilla installations, you should supply 00440 /// values for all "defaulted" parameters.</para> 00441 /// <para>It is recommended that you use <see cref="GetLegalFieldValues"/> to 00442 /// retrieve legal values for parameters such as <paramref name="component"/>, 00443 /// <paramref name="version"/>, <see cref="operatingSystem"/>, and other parameters 00444 /// that have pre-configured values on the server.</para> 00445 /// </remarks> 00446 public Bug CreateBug( 00447 string alias, string component, 00448 string version, string operatingSystem, 00449 string platform, string summary, 00450 string description, string priority, 00451 string severity, string status, 00452 string targetMilestone, string assignedTo) { 00453 00454 return CreateBug(alias, component, version, operatingSystem, platform, summary, 00455 description, priority, severity, status, targetMilestone, assignedTo, null, 00456 null); 00457 } 00458 00459 /// <summary> 00460 /// Create a new bug on this product 00461 /// </summary> 00462 /// <param name="alias">(Optional) If aliases are enabled for the Bugzilla 00463 /// server, you can supply an unique identifier (no spaces or weird characters) 00464 /// to identify the bug with, in addition to the id.</param> 00465 /// <param name="component">The name of the component that the bug 00466 /// will be created under.</param> 00467 /// <param name="version">The version of the product, that the bug 00468 /// was found in.</param> 00469 /// <param name="operatingSystem">(Defaulted) The operating system 00470 /// the bug was discovered on.</param> 00471 /// <param name="platform">(Defaulted) What type of hardware the 00472 /// bug was experienced on.</param> 00473 /// <param name="summary">Summary of the bug.</param> 00474 /// <param name="description">(Defaulted) Description of the 00475 /// bug.</param> 00476 /// <param name="priority">(Defaulted) What order the bug will be 00477 /// fixed in by the developer, compared to the developer's other 00478 /// bugs.</param> 00479 /// <param name="severity">(Defaulted) How severe the bug 00480 /// is.</param> 00481 /// <param name="status">(Optional) The status that this bug 00482 /// should start out as. Note that only certain statuses can be 00483 /// set on bug creation.</param> 00484 /// <param name="targetMilestone">(Optional) A valid target 00485 /// milestone for this product.</param> 00486 /// <param name="assignedTo">(Optional) A user to assign this bug 00487 /// to, if you don't want it to be assigned to the component 00488 /// owner.</param> 00489 /// <param name="cc">(Optional) An array of usernames to CC on 00490 /// this bug.</param> 00491 /// <returns>The newly created bug.</returns> 00492 /// <remarks> 00493 /// <para>The parameters for this call can be marked "optional" 00494 /// or "defaulted". Optional parameters can be left out in all 00495 /// Bugzilla installations (i.e. receive <b>null</b>), and a default value 00496 /// from the server will be substituted. 00497 /// Parameters marked as Defaulted can be left out in 00498 /// some installations, while other installations may require 00499 /// these parameters to be present. This is decided in the 00500 /// Bugzilla preferences. If you wish to make sure that the call 00501 /// works with all Bugzilla installations, you should supply 00502 /// values for all "defaulted" parameters.</para> 00503 /// <para>It is recommended that you use <see cref="GetLegalFieldValues"/> to 00504 /// retrieve legal values for parameters such as <paramref name="component"/>, 00505 /// <paramref name="version"/>, <see cref="operatingSystem"/>, and other parameters 00506 /// that have pre-configured values on the server.</para> 00507 /// </remarks> 00508 public Bug CreateBug( 00509 string alias, string component, 00510 string version, string operatingSystem, 00511 string platform, string summary, 00512 string description, string priority, 00513 string severity, string status, 00514 string targetMilestone, string assignedTo, 00515 string[] cc) { 00516 00517 return CreateBug(alias, component, version, operatingSystem, platform, summary, 00518 description, priority, severity, status, targetMilestone, assignedTo, cc, 00519 null); 00520 } 00521 00522 } 00523 }