Bugzilla/Product.cs

Go to the documentation of this file.
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 }

Generated on Thu Jan 17 07:31:46 2008 for BugzillaProxy by  doxygen 1.5.4