use oxinat::Xnat;

use crate::MyVersion;

let client = Xnat::configure("your.target.host")
    .use_secure(true)
    .with_username("your-username")
    .with_password("your-password")
    .with_version(MyVersion)
    .build()
    .expect("must build an XNAT client"); // Should produce a client.

现在，我们设置了所需的版本，以及我们想要的 URI 构建器，我们可以期望有一个合适的 Xnat 客户端。

协议

正在进行一项工作，以预定义一些您可能希望执行的一些常见操作。我们将它们定义为 协议，其中协议与XNAT为授权用户提供资源XNAT的相关 CRUD 操作相关。

对于实现 ClientCore 和 ClientREST 特性的客户端，随着我们继续开发，这些附加特性将可用。

/// Type is able to implement CREATE requests for
/// a particular model. Upon creation, these
/// methods are expected to then return the
/// individual results, and then a
/// `Ok(Self::Model)` response if the request is
/// successful.
trait Create<M> {
    /// Attempt to send a CREATE request to the
    /// XNAT server for **multiple** models.
    fn create_many(&self, models: M) -> Vec<PinnedFuture<'_, M>>;
    /// Attempt to send a CREATE request to the
    /// XNAT server for **one** model.
    fn create_once(&self, model: M) -> anyhow::Result<M>;
}

/// Type is able to implement RETRIEVE requests
/// for a particular model.
trait Retrieve<M> {
    /// Get all instances of a particular model
    /// available to the user via the XNAT host.
    async fn get_all(&self) -> anyhow::Result<Vec<M>>;
    /// Get all instances of a particular model
    /// using another model as the query
    /// parameters for the request.
    async fn get_any_from(&self, model: &M) -> anyhow::Result<Vec<M>>;
    /// Get one instance of a particular model
    /// using another model as the query
    /// parameters for the request.
    async fn get_one_from(&self, model: &M) -> anyhow::Result<M>;
}

/// Type is able to implement UPDATE or UPSERT
/// requests for a particular model.
trait Update<M> {
    /// Attempt to send **multiple** UPDATE
    /// requests to the XNAT host.
    fn update_many(&self, models: M) -> Vec<PinnedFuture<'_, M>>;
    /// Attempt to send **one** UPDATE request to
    /// the XNAT host.
    async fn update_once(&self, model: M) -> anyhow::Result<M>;
}

/// Type is able to implement DELETE requests for
/// a particular model.
trait Delete<M> {
    /// Attempt to send **multiple** DELETE
    /// requests to the XNAT host.
    fn delete_many(&self, models: M) -> Vec<PinnedFuture<'_, M>>;
    /// Attempt to send **one** DELETE request to
    /// the XNAT host.
    async fn delete_once(&self, model: M) -> anyhow::Result<M>;
}

创建

Create 特性已在某些模型的通用 Xnat 客户端上实现。然后，这些模型可用于通过此特性定义的方法来创建以下实例，或针对您的目标XNAT主机。

• 项目
• 受试者
• 实验
• 扫描
• 资源

根据每个模型所需的深度，您可能需要提供所有或部分标识符，以便您的目标XNAT主机了解模型应在哪里/如何创建。

例如，在 Scan 模型的案例中，您需要提供项目ID作为 project，受试者标签或ID作为 subject，实验标签或ID作为 experiment，以及指定扫描的ID作为 id。

use oxinat::{ClientCore, ClientToken, Xnat};
use oxinat::models::Scan;
use oxinat::protocols::Create;

use crate::{MyVersion, client};

let mut scan = Scan::default();
scan.id = Some(14u64);
scan.experiment = Some("EXPERIMENT_LABEL".into());
scan.subject    = Some("SUBJECT_LABEL".into());
scan.project    = Some("PROJECT_ID".into());

scan = client.create_once(scan).await.expect("scan must be created");

检索

Retrieve 特性已在某些模型的通用 Xnat 客户端上实现。

• 项目
• 受试者
• 实验
• 扫描
• 评估者
• 资源
• 插件

Retrieve 特性旨在允许您从您的目标XNAT实例中 GET 资源。

use oxinat::{ClientCore, ClientToken, Xnat}
use oxinat::models::Project;
use oxinat::protocols::Retrieve;

use crate::{MyVersion, client};

// Should retrieve all project records from your
// XNAT instance.
let found: Vec<Project> = client.get_all().await.unwrap();

// Should retrieve one project which matches the
// project ID.
let mut project = Project::default();
project.id.clone_from(&Some("SOME_PROJECT_ID".into()));
let found = client.get_one_from(&project).await.unwrap();

当执行查询时，预定义的getter会尝试首先提取相关标识符，然后消耗剩余填充的字段作为查询参数来构造请求路径。

删除

Delete 特性已针对多个模型实现。这允许这些模型用于在您的目标XNAT主机中请求对现有数据的 DELETE 调用。

• 项目
• 受试者
• 实验
• 扫描
• 资源

与 Create 特性类似，为了使 delete 调用成功，您必须提供所有必要标识符，以便进行有效的 DELETE 调用。没有它们，您的XNAT实例将不知道要删除哪些资源，并且作为安全网，oxinat 默认不允许此操作。